Advanced System

Programmer's Guide
for the Amiga
Bleek
Jennrich
Schulz

A Data Becker Book

Published by

AbaCUS.

F~tPrinting,Novemberl989

Printed in U.S.A.
Copyright 1988, 1989

Abacus
5370 52nd Street SE
Grand Rapids, MI 49512

Copyright 1988

Data Becker, GmbH

Merowingerstrasse 30
4000 Duesseldorf, West Germany

This book is copyrighted. No part of this book may be reproduced, stored in a retrieval
system, or transmitted in any form or by any means, electronic, mechanical, photocopying,
recording or otherwise without the prior written permission of Abacus or Data Becker,
GmbH.
Every effort has been made to ensure complete and accurate information concerning the
material presented in this book. However, Abacus Software can neither guarantee nor be
held legally responsible for any mistakes in printing or faulty instructions contained in this
book. The authors always appreciate receiving notice of any errors or misprints.
AmigaBASIC and MS-DOS are trademarks or registered trademarks of Microsoft
Corporation. Amiga 500, Amiga 1000, Amiga 2000, Graphicraft, Musicraft, Sidecar and
Textcraft are trademarks or registered trademarks of Commodore-Amiga Inc. K-Seka
assembler is a registered trademark of Kuma Corporation.

ISBN'

ii

1-55755-047-6

Foreword
This book is written by programmers for programmers. Although
technical books are usually difficult to understand and very practical,
this book is different. Amiga Advanced System Programmers
Guide is similiar to working with the Abacus book Amiga C for
Advanced Programmers. We have tried to write a book that helps
the programmer with programming but doesn't contain too much
theory. Our goal was to provide information about large subjects with
many example programs.
We wrote this book with more information than any other book on this
subject. This book contains complete information about the parameter
statements in programs through the CLI and the WOrkbench, about all
of the devices of the Amiga, complete with example programs, about
the IFF format from Electronic Arts, and about the basic structures of
the Amiga operating system.
Bruno lennrich spent three months working with all of the devices and
thoroughly documented them so that anyone can begin to use them.
Wolf-Gideon Bleek concentrated on the parameter transfer and collected
information on programming style. So, you as a programmer can not
only program, but also develop a good programming style. He also
worked with Intuition and placed all of the information from
Preferepces together.
Peter Schulz explained the complicated keymaps and math libraries in
simple terms. This has made calculations, even with complicated
functions, much simpler.
All of the authors contributed to the documentation of all of the
libraries and the IFF format, with each writing about the library and the
format that he knows best
You should have a complete collection of information when this book
is used in conjunction with a reference book. So this book should
always be next to your computer.
(

W. Bleek, B. lennriCh, P. Schulz

iii

Table of Contents
Forewad ...............................................................iii

1.

Introduction ........................................... .. .. . .. . . .. .. .. .. .. . .. 1

2.
2.1
2.2
2.3
2.4
2.5

Good Programming Style ............................................... 3

Comments and fonnatting .............................................. 3
Development and multitasking ........................................ 8
Assembly language programming ................................... 12
Accessing system directories .......................................... 14
Intuition ..................................................................... 17

3.
3.1
3.2

Data Transfer............................................................... 19
CLI arguments ............................................................20
The .info file ...............................................................25

4.
4.1
4.2
4.3
4.3.1
4.3.2
4.3.3
4.3.4
4.3.5
4.3.6
4.3.7
4.4
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.4.6
4.4.7
4.5
4.5.1
4.5.2
4.5.3
4.5.4
4.5.5
4.5.6
4.6

Devices ..................................................................... .37

What are devices? .........................................................37
Communicating through devices .....................................46
The parallel device ........................................................50
()pening the parallel device ........................................... .50
Writing parallel device data ............. .51
Reading parallel device dati ............................................ 52
Reading parallel device status ........................................ .53
A parallel device application .......................................... .54
Parallel device enur messages ........................................ .55
Centronics port pin arrangement ..................................... 56
The serial device ......................................................... .57
()pening the serial device .............................................. .58
Reading and writing serial device data.............................. .58
Serial device parameters .................................................60
Reading serial interface status .........................................63
Serial device enur messages ...........................................64
Serial port pins............................................................65
A serial device application .............................................66
The printer device.........................................................68
Printing escape sequences ..............................................69
Amiga printer escape sequences .......................................69
Printer commands ........................................................72
:Hardcopy ....................................................73
Printer device enur messages ..........................................79
The printer device under Kickstart 1.3 ..............................79
The keyboard device......................................................81

4.6.1
4.6.2
4.6.3
4.6.4
4.7
4.7.1
4.7.2
4.7.3
4.8
4.8.1
4.8.2
4.8.3
4.9
4.9.1
4.9.2
4.9.2.1
4.9.2.2
4.10
4.11
4.11.1
4.11.2
4.11.3
4.11.4
4.11.5
4.12
4.13
4.14
4.14.1
4.14.2
4.14.3
4.14.4
4.14.5
4.14.6
4.14.7

()pening the keyboard device .......................................... 81

Reading the keyboard device ...........................................82
Resets through the keyboard device..................................83
A keyboard device application........................................84
1be gameport device ...................................85
Opening the gameport device........................................85
Reading gameport device status ....................................87
A gameport device application ........................................91
1be input device ....................................................93
Opening and closing the input device ............................... 93
Accessing the input device ...........................................94
The input device, mouse and keyboard............................ 107
1be console device ..................................................... 111
Key mapping ......................................... ,. ............... 124
Console internals ....................................................... 138
Console functions .................................................... 139
More key codes.................................................... 140
1be clipboard device ................................................. 141
1be audio device .................................................. 145
Allocating audio channels ........................................ 146
Audio period and volume ............................................ 151
Play it ..................................................................... 153
Additional audio device features ..................................... 155
Sound in the interrupt code ......................................... 167
1be nanator device .................................................... 168
1be timer device ....................................................... 179
The trackdisk device................................................... 189
Reading-' and writing sectors .......................................... 190
Reading and writing raw tracks ..................................... 194
Formatting a disk ...................................................... 196
Status commands ..................................................... 197
Disk interrupts ....................................................... 199
Error handling .......................................................... 20 1
The disk editor........................................................... 204

5.

Standard File Formats ............................................ 215

IFF ......................................................................... 215
The IFF ILBM graphic format ..................................... 216
The IFF FfXT text format ......................................... 229
The IFF SMUS music format ...................................... 230
The IFF 8SVX sample format ...................................... 233

5.1
5.1.1
5.1.2
5.1.3
5.1.4

6.
6.1
6.1.1
6.1.2

vi

The Amiga Libraries ................................................... 235

1be exec library ......................................................... 236
Special functions ...................................................... 240
Interrupt functions ...................................................... 242

6.1.3
6.1.4
6.1.5
6.1.6
6.1.7
6.1.8
6.1.9
6.1.10
6.1.11
6.1.12
6.2
6.2.1
6.2.2
6.2.3
6.2.4
6.2.5
6.2.6
6.2.7
6.3
6.3.1.
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3 8
6.3.9
6.4
6.4.1
6.4.2
6.4.3
6.5
6.5.1.
6.5.2
6.5.3
6.5.4
6.5.5
6.6
6.6.1
6.6.2
6.6.3
6.6.4
6.6.5.
6.6.6
6.6.7

Memory functions ...................................................... 246

List management functions .......................................... 250
Task functions ........................................................... 253
Message functions ...................................................... 258
Library functions ....................................................... 261
I>evice functions ........................................................ 265
Resource functions ..................................................... 269
Semaphore supported functions ..................................... 270
Kickstart and memory functions .................................... 274
Additional Functions .................................................. 276
The OOS library ........................................................ 277
Input and output ........................................................ 278
File management ....................................................... 282
File management utility functions ................................. 287
Process management................................................... 291
Loading programs ...................................................... 295
Internal OOS functions ............................................... 296
DosBase ................................................................... 298
The Intuition library ................................................... 299
Window functions ...................................................... 302
Gadget functions ........................................................ 309
Menu functions ......................................................... 318
Requester and alert functions ........................................ 321
Screen functions ........................................................ 326
Graphic functions ....................................................... 332
Memory functions ...................................................... 335
Refresh functions ....................................................... 336
Other functions .......................................................... 337
The layers library ....................................................... 347
Layer creation ............................................................ 348
Layer processing ........................................................ 353
Releasing layers ......................................................... 361
The icon library ......................................................... 364
Workbench object functions ......................................... 365
Icon functions ........................................................... 367
Disk object functions .................................................. 368
FreeList functions ...................................................... 370
Utility functions ........................................................ 372
The graphics library .................................................... 374
Raster initialization and processing ................................ 378
RastPort drawing functions .......................................... 385
RastPort fill functions ................................................ 389
Colormap functions .................................................... 397
Blitter functions ......................................................... 401
Copper functions ....................................................... 411
Layer functions .......................................................... 420

vii

6.6.8
6.6.9
6.7

6.8
6.8.1

6.8.2
6.8.3
6.8.4
6.9
6.10

6.11
6.12
6.13
6.14

7.
7.1
7.1.1
7.1.2
7.2
7.2.1
7.2.1.1
7.2.1.2
7.2.1.3
7.2.2
7.3
7.3.1
7.3.2

7.4

Character display ........................................................ 427

GELs and sprites ........................................................ 432
The DiskFont library .................................................. 446
The math libraries ...................................................... 450
The math library ........................................................ 450
The MathTrans library ................................................ 455
The MathIeeeDoubBas library....................................... 462
The MathIeeeDoubTrans library ................................... .467
The Potgo library ....................................................... 472
The Translator library ................................................. 474
The Expansion library ................................................. 475
The RomBoot library .................................................. 488
The Console library .................................................... 489
The Timer library ....................................................... 493
Basic System Structures ............................................. .495
Preferences as a data structure ...................................... .495
The data managed by Preferences ................................... 496
Preferences access through Intuition ............................... 500
Printer drivers ............................................................ 505
The PrinterExtendedData structure ................................. 506
Additional variables .................................................... 509
DoSpecial and command array ...................................... 510
The rest of the variables .............................................. 513
Tips for programming a printer driver ............................ 513
Fonts and text output .................................................. 515
The font header .......................................................... 515
The actual character data ................ " ............................ 519
Keymaps .................................................................. 525

Appendix A
AppendixB

Function List ................................................... 539

Bibliography .................................................... 544

Index ................................................................................... 545

viii

1.

ABACUS

1.

INTRoDUCTION

Introduction
Advanced System Programmer's Guide-an impressive title. The name
Amiga Advanced System Programmer's Guide tells you exactly what
you get: Information about the Amiga operating system, how the
system routines function, which of these functions are executable by
you, and how the hardware works. This book looks at the Amiga
system from an expanded viewpoint.
Chapter 2 of the Amiga Advanced System Programmer's Guide
discusses programming style. This chapter builds a base for good style
in program development. It thoroughly explains the division, organization and composition of a program. It describes the anatomy of the
version number, how to call libraries and how to document your
program clearly so that it can be understood by others.
Chapter 3 contains a description of the arguments which appear at the
beginning of a program. This explains how to read values that are
entered in the CLI, as well as arguments entered through the
Workbench. Most commercial Amiga applications use Workbench
access instead of the CLI. This chapter also shows which functions are
read by the . in f 0 structures, and shows you how to set the
corresponding routine at the beginning of a program. This chapter also
shows the two ways to start a program: From the CLI and from the
Worlcbench.
Chapter 4 describes all the Amiga devices available. Devices execute all
data exchanges between external or simulated internal devices, this book
describes device usage in detail. You'll find explanations for each
device's mode and command, as well as demonstration programs. With
the help of this book, you can address the Amiga's output and input
devices correctly with a minimum of hassle.
Chapter 5 discusses Interchange File Format (IFF), in simple ILBM
format as well as the more complex music and text formats. You'll find
lists and tables for the music and text formats. Chapter 5 concludes
with an explanation of the Anim format from Aegis. This represents a
complex mixture of ILBM data and the Anim format's own chunks.
Chapter 6 comprises the bulk of this Guide. Here you fmd descriptions
of the Amiga library functions, along with documentation for each
library. This documentation can be used by both assembly language and
C programmers. In addition to general syntax and arguments, each

1. INTRODUCTION

ADVANCED SYSTEM PROGRAMMER'S GUIDE

description includes defmitions for C variables, which make it easier for

the beginner to spot source code errors. Cross referencing makes it
possible to quickly fInd functions dealing with the same subject
Example:

You need information about the function which closes a window, but
you can't remember the function's name. You know that it's part of the
Intuition library, since Intuition controls all windows. You'd take the
following steps:
1.

Check the table of contents for the fIrst page of the Intuition
library chapter. This chapter contains a listing of Intuition
functions.

2.

Now look in the group of window functions. Here you'll fInd

Closewindow () and the number of the page describing the
function.

3.

Turn to the page to fInd that information.

Rule of thumb: Look in the beginning of the library chapter to find

what you need about each function.
Chapter 7 describes the basic structures of the Amiga operating system.
These structures are often short but are still needed by every program.
Do you use keymaps when you check the keyboard? Do you always
have to set Preferences for your program? How is your output formatted
when no Amiga fonts are present? The operating system structures take
care of all of this and more. This information is presented in
demonstration programs.

ABACUS

2.

2.

GOOD PROGRAMMING STYLE

Good Programming
Style
We live together on this planet under many rules and conventions.
There are conventions of dress, language, and more. Many of these
standards are basic, common sense rules. For example, most states
consider driving through a red light illegal.
Communicating with a computer must be done under certain rules as
well. There are more obvious rules you should follow in programming
(e.g., don't hit the Amiga when the system crashes). However, some
smaller conventions are very valuable to the user and developer alike.
Think about the Amiga's graphic user interface, Intuition. Certain icons
represent certain tools (applications) and projects (files run from
specific tools). Some icon designs have become standards, and it's best
to keep the standard icon design (e.g., AmigaBASIC projects).
This chapter looks at some helpful rules that you can follow in writing
elegant, stylish source code, as well as some hints for better program
development.

2.1

Comments and formatting

Comments in source code plays a special role in the field of
professional programming. Imagine a company that develops and
markets several application programs for the Amiga. After several
months Commodore announces a new improved Amiga operating
system-which is incompatible with all this company's Amiga
applications. Unfortunately, the company's original developer forgot to
place comments in the source code, and he now works for another firm.
This means that revisions to the program will take much longer than
they would have taken with commented code. No one except the
original developer knows where anything is in the program, or how
crucial routines work.
The same thing can happen to you. Say you develop a large program
and put no comments into the source code. You set the program aside

2.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

GOOD PROGRAMMING STYLE

for a few weeks and come back to it later. Without comments you have
no idea of what works when in the program. The only solution is to
analyze the program from the beginning and figure out what it does.
Comment programs carefully, for your own information as well as for
others who might study the program later.
Program header
You'll usually find information about the program's name, purpose,
author, last date of revision and other information in the program
header. Look at the following example, which was taken from the
Abacus book Amiga C for Advanced Programmers:
/***************************************

* Program: Window local definition

*
* =================================== *

* Author:
*
* Wgb
*

Date:

Comments:

---------- ---------10/16/1987

first test
window

*
*
*
*

***************************************/

The header starts with a brief description of the program. This C

program dermes a window locally, which means that the data belongs
to one function instead of more than one function. The header also lists
the author's initials and the date when he/she wrote the program. This
program header can be expanded by the author, or by someone who
revised this program for his or her own needs.
The program header is the easiest way to ensure that programmers
know of any changes, improvements or deletions that have been made
to this program. Program headers can contain much more vital
information. Here's another program header, taken from the Abacus
book Amiga Tricks & Tips:
1*********************************

,*

*
'* Open window through Intuition *
'* ----------------------------- *
,*
*
, * Author : Wolf-Gideon Bleek
*
, * Date
: May 22, 1988
*
'* Greetings: Denis "Angle"
*
, * Version : 1.1
*
, * Operating system: VI. 2 & VI. 3 *
.*
*
'*********************************

2.1 COMMENTARY AND FORMATTING

ABACUS

Here we also find information about the program's version and the
operating system versions. Both values have different meanings. The
operating system version may dictate how the program must be
compiled. The values are important for BASIC programs because the
libraries must be loaded during program execution.
The greeting entry is optional; it can add a personal touch to the code.
If you wish to thank someone for their efforts in helping write a
program, the program header is the pJace to insert the note of thanks.
The version number of the program should be in the program text so
you can differentiate easily between two similar versions of a program
by looking at the version number. This number should also appear in
the program itself for the same reason. In other words, the version
number should appear twice: Once in the program header, and once in
the program itself so that the user can easily find it.
You should specify the operating system version. This is the only way
error free use can be guaranteed for the user. You can also use this to
recognize if the program uses features that are implemented with the
new version. For example, a program which is compatible with
Kickstart 1.1 cannot support an auto boot from the hard disk since
KickStart 1.1 does not support this feature. On the other hand, a
program will only be compatible with every Amiga if it correctly
accesses the operating system functions.

More about version numbers

Version numbers follow certain conventions in Amiga development. A
version number helps the user and developer quickly recognize the
current version of the program. Most version numbers appear as two
digits, separated from one another by a decimal point
Version X.Y

The number to the left of the decimal point represents the major
version. This number is a zero if the program is still in the
development phase (e.g., Version 0.1 for an early design). The first
fully functional program version appears as version 1.0.
The Y parameter represents the minor version number. The Y usually
begins at zero (e.g., version 1.0) and goes up to nine (e.g., version
1.9). The .Y parameter can also be notated in tenths or hundredths.
These smaller notations indicate lesser changes to a program such as
minor error corrections.
It is up to the programer to change the version number when updating
the program. The programmer must decide the extent of the version

2. GOOD PROGRAMMING STYLE

ADVANCED SYSTEM PROGRAMMER'S GUIDE

number change. For example, imagine that you're developing a

program. You would assign the fIrst testing version a number of 0.1
(no preceding version numbers exist). H you correct existing errors
without adding any new real data, the version numbers can increase
from 0.11 to 0.19 (note the added decimal place). If you add a new
function to a program, the version number could then be changed to
version 0.2.
Let's assume that version 0.7 of your program is completely executable
and needs no more expansion. Then you can change the version number
to 1.0. The Amiga operating system is a good example of version
number changes. Version 1.0 was the first executable version of that
system, but required major revisions because of errors found after its
release. The next version (1.1) contained these changes. Revisions by
the European divisions of Commodore-Amiga resulted in version 1.2.
Version 1.3 contained many more improvements. The version in
development (1.4) includes special graphic chip support.
Version numbers don't usually go beyond the second or third decimal
place. It would he inhuman and impractical to assign the main version
of a program a version number of 1.279. This could result in a program
package stating the following: "This program runs with all operating
system versions of 1.2623 and up, but not with intennediate versions
1.2758 and 1.296." That's why a fInal version exists-to help users to
differentiate between versions easily.
You can fmd the current Kickstart and Workbench versions by selecting
the Version item from the Workbench menu. Version 1.2 of Kickstart
displays the number 33.180. This number indicates the library version
in use: 33 is the library version number. Later in this chapter you will
read about how this can affect the libraries. The Workbench uses
version number 33.57, but Kickstart 1.3 increases this version number
to 34.7.

The function header

Function headers list information about the 11lnction which follows it
The information here is different from that contained in the program
heade~. The function header describes syntax, parameters that are
transferred or returned and variables that are changed by a subroutine.
Here is an example:

2.1

ABACUS

COMMENTARY AND 'ORMATTING

1***************************************

*
* Function to erase an already
* existing Lexicon structure:
* FreeLexicon()

*
*
*

*
*

* Additions:
*
* - support of entries
*
* - select, i f saved
*
*
*
* Input parameters:
*
* Lexicon - pointer to best structure *
*
*
* Return parameters:
*
* none
*
*
*
* Date: April 3, 1988
*
* Author: Wolf-Gideon Bleek
*
* Greetings: Christian
*
*
*
***************************************/

The fIrSt lines of text in the function header clearly defme the function's
purpose. The third line of text states the C function's name. These
items are most important to the majority of programmers.
The Additions lines prove to be very useful in the development phases
of a function. Changes may be started during a programming session
and not completed at the end of that particular session. These additions
tell the programmer where development left off for the next session.
The input parameters specify any values needed by the function. C.
AmigaBASIC and other languages allow long parameter names. We
recommend that you use names that clearly describe the variable
whenever possible.
The return parameters describe the results of this routine. Functions
often have only one return parameter. if any. If a parameter name is
required. use names that clearly describe the variable.
The example above includes the date of completion. the author's name
and a personal greeting. This can be expanded as needed.

2. GOOD PROGRAMMING STYLE

2.2

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Development and multitasking

There are several rules that should be kept in mind when designing your
program to work with a multitasking operating system. These rules
ensure that your program does not conflict with other programs.
Opening and closing communication channels causes the most
problems. This refers to communication with the user, the devices and
the system routines. Management systems regulate these devices-no
direct access takes place.
A communication channel must be opened before communication takes
place. This is similar to a door leading to a room: You can't exchange
information with people in the next room if the door is closed. Once
you open the door, you can communicate with anyone in the adjacent
room. When you close the door. communication ends.
One rule suggests that you close a door when you don't need to enter a
room. The same goes for the computer: Close all of the data channels
when you no longer need them.
The telephone offers another illustration of communication channels.
When you want to call someone. you pick up the receiver and dial a
number. One of two things happens: Either you make the connection
and the telephone on the other end starts ringing. or you hear a busy
signal. The only option when a busy signal occurs is to hang up the
telephone and dial again. The Amiga also returns a busy signal if it
cannot currently open a library or something similar. One of two
things occurred: Either there was no memory available. or the channel
was non-existent.
Let's look at the processes used for opening and closing libraries.
devices or data channels. We need a routine which opens a library. All
it requires is the library's name and version number. When we try to
open a library. the routine either returns the base address of the library
or a zero (=error). The routine must constantly check for errors. since
the possibility of errors always exists. The following routine performs
this error check:
Library = OpenLibraryCttLibName tt , Version);
IF CLibrary == Null)
CancelC);

Version specifies the version number that your program needs. You can
fmd the version number by entering the AmigaDOS Version command
from the CLI. Stating a Version value of zero allows program access to

2.2 DEVELOPMENT AND MULTITASKING

ABACUS

all the libraries, even those not normally accessible through command
words. The following line combines the opening and the error check
into one short routine:
IF (! (Library = OpenLibrary("LibName", Version))
exit (FALSE) ;

Closing a library is very simple. You must never try to close an

unopened library, otherwise a system crash occurs. The following
checks a pointer which ensures that the library can be closed:
IF (Library) CloseLibrary(Library);

The closing procedure becomes much more complicated if a program

must execute multiple file accesses. All of the open libraries must be
closed. We need a routine which can fmd all open libraries and close the
open libraries only.
Let's look at an example. Your program needs two system libraries. a
window and multiple blocks of memory. The program displays an error
message when you try to open the window. A poor programmer would
simply stop the program at this point, but this creates problems for the
multitasking system. Remember that the two libraries reserved for the
program take up memory. Tasks running at the same time slow down
because of low available memory and active library access.
We can limit memory loss and open access using the Open_All ()
and C los e _A 11 () functions listed in the program below. These
functions open and close the necessary channels as needed. When an
error occurs while opening any area of memory. the program jumps to
the Close_All routine and ends the program. The Close_All
routine knows what is open and what is not. The following
demonstrates how this works:
/*****************************************

* Function: Open Libraries and Window

* ===================================== *

* Author:

* -----* Wgb

Date:
06/15/1988

Comments:
also memory

*
*

*
*
*

*****************************************/

Open_All ()
{

void
*OpenLibrary();
struct Window *OpenWindow();
if (!(IntuitionBase = (struct IntuitionBase *)
OpenLibrary ("intuition . library" , OL)))
{

2.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

GOOD PROGRAMMING STYLE

printf("No Intuition library found!\n");

Close_All ();
exit(FALSE);
}

if (! (GfxBase = (struct GfxBase *)

OpenLibrary(lgraphics.library", OL)
(

printf("No Graphics library found!\n");

Close_All();
exit(FALSE);
)

if (! (FirstWindow = (struct Window *)

OpenWindow(&FirstNewWindow)
{

printf ("Window will not open! \n");

Close_All ();
exit (FALSE);
)

UndoBuffer = Al1ocMem(512L, MemoryType);

.!..f (! UndoBuffer)
(

printf("Problems with Undo buffer!\n");

Close_All();
exit (FALSE) ;
)

FileBuffer = AllocMem(30L, MemoryType);

i f (!FileBuffer)
(

printf("Problems with File buffer!\n");

Close_All () ;
exit(FALSE);
)

1*****************************************

* Function:C1ose everything that is open*

* ===================================
*

* Author:

*
* Wgb

Date:
15.06.1988

Comments:

*
*
*

Intuition, Window *
Graphics 'Mem
*

*****************************************/

Close_All ()
{

if (FirstWindow)
if (IntuitionBase)
i f (GfxBase)
i f (UndoBuffer)
i f (FileBuffer)
)

10

C1oseWindow(FirstWindow);
CloseLibrary(IntuitionBase);
CloseLibrary(GfxBase);
FreeMem(UndoBuffer, 512L);
FreeMem(FileBuffer, 30L);

ABACUS

2.2 DEVELOPMENT AND MULTITASKING

The Close_All () function fulfills all of the requirements that we

set for ourselves. It can be accessed from any place in the program. and
it closes anything that it knows is open. Anything unopened is
ignored. decreasing the odds of fatal errors.
The use of the functions as listed here is tightly structured. You may
want to move all Open_All () calls to the beginning of the program
to save some program memory.
You could place the Close_All () routine at the end of the Main ()
function. but that would require a goto whenever an error occurs. This
is not highly structured C programming. but it is a legitimate and
practical solution. In addition. placing Close_All () 'after Main ()
saves a few bytes of program memory.

11

2. GOOD PROGRAMMING STYLE

2.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Assembly language
programming
Assembly language offers much more freedom in programming than
the C language. Assembly language code can be executed directly,
without the compiler and linker needed by C source codes. Higher level
languages and assembly language must be able to handle certain
services called registers. The Amiga's microprocessor has eight data
registers and seven address registers in addition to the address counter,
the two stack pointers and the status register.
All of these registers can be accessed from a program. However, there
are some rules that you must heed if you want to correctly use the
Amiga's operating system. Each library function assumes that you
know which register is used and which registers remain unused.

Register Tabula rasa ("forbidden registers"):

The first forbidden register is in address register A7. It usually acts as
the stack pointer (SP), and cannot be loaded with its own data. Like
SP, you cannot load the user stack pointer (USP) and the supervisor
stack pointer (SSP) with their own data. Changing these three registers
requires a high level of system knowledge, and even then any changes
to these registers should be avoided. Changing these registers disables
multitasking, which defeats one of the Amiga's biggest features.
Using registers in conjunction with libraries
Several factors must be considered when using the library routines in a
program. First and foremost is specifying the base address register.
Calling the library routine places the base address of the library in
register A6. This address could then be passed to another register. The
library routines also use internal variables that are addressed through
this register. Each function assumes that it finds its base address in
register A6. You can also execute a call that always stands at the base
value.
Next, look at the first two address and data registers (AO, Al & DO,
01). Almost every function uses these registers at some time or
another. The contents of these four registers are neither saved nor
restored. As you program, remember that these registers do not contain
important data throughout the entire program, or even during a longer

12

ABACUS

2.3 AsSEMBLY LANGUAGE PROGRAMMING

function. These registers work best for small data transfers and
calculations.
The dos.library uses the D2 and D3 registers constandy because of a
constant need for buffer memory. Keep these registers in mind when
accessing the dos.library from a program. In addition, notice that all of
the other registers called by the function are saved.
We wish to comment here about saving of registers. When you write
your own functions in your programs, state in the function header
which registers are saved and which are not saved. This makes it much
easier in later development. Hold to the library conventions of register
listing to avoid confusion.

Note:

Save registers while within a function-not before the function call.

Clearly format these register saves, and never try to cross registers.

13

2. GOOD PROGRAMMING STYLE

2.4

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Accessing system directories

Many programs on the Amiga won't run without system support. This
support comes from data already in the system (fonts. printer drivers.
libraries. etc.). Where do you find. the data when you want to use it?
The system directories contain most of the additional fIles and programs
needed for system support. These directories always exist under one
general name to minimize the time spent by the program searching for
system files.
Let's look at the existing directories. If you enter the Ass i g n
command from the CLI the following list appears (your list may look
slightly different from this one, since our Workbench disk is named
Wgb):
Directorys:
ENV
T
FONTS
S
L
C

DEVS
LIBS
SYS

RAM DISK:Env
RAM DISK:T
Workbench 1.3
Workbench 1.3
Workbench 1.3
Workbench 1.3
Workbench 1. 3
Workbench 1. 3
Workbench 1.3

Wgb:fonts
Wgb:S
Wgb:L
Wgb:c
Wgb: devs
Wgb: libs
Wgb:

The directories in this list can be addressed under a generally known

name. This general name carries through each directory to the actual
device and its directory.
Here's an example. You've developed a program that sends any text to a
printer. The user can select an alternate Amiga font The program takes
this font from the Workbench diskette in drive DFO:. The syntax would
look something like this:
DFO:fonts/name

This command sequence raises some questions:

14

The DFO: tells the system to look in the internal disk drive.
What about users who have two disk drives. and place the
Workbench disk in an external drive?

How can the user tell the program to look on the hard disk for
fonts?

2.4 ACCESSING SYSTEM DIRECTORIES

ABACUS

The program will look specifically for the fonts directory.

What if the user wants to change the name of the fonts
directory to something else and still have the program access
it?

All fonts must be on the Workbench disk. What about the

user who wants a font not in the fonts directory?

You can see that this solution is not ideal. The Amiga's operating
system accesses the directory with the desired contents through the
abovementioned name. The Assign command allows you to assign
the fonts directory, but the program will still access the fonts directory,
whatever drive this directory is on.
The developer should know what exists in which directory. The
following list describes the contents of each system directory.

FONTS

Workbench 1.3 Wgb:ronts:

The fonts directory contains all the available fonts. This directory is
primarily addressed by the diskfont.library. You can add new fonts or
delete existing fonts.

Workbench 1.3 Wgb:s:

The S directory contains script mes. Versions of the operating system
up to and including 1.2 contain only the script me named startupsequence. Version 1.3 includes a second startup-sequence for the CLI
and the Shell, as well as a demo version of the HardDisk startup
sequence. This directory is useful because the AmigaDOS Execute
command searches this directory for script mes if they cannot be found
in the current path. This saves the user some typing, and keeps all of
the script mes in one directory. The system searches the S directory
during booting and executes the me named startup-sequence.

Workbench 1.3 Wgb:l:

The L directory contains the handlers for all of the non-resident
libraries. A new library can be included using the

OverlayCodeSegments.

Workbench 1.3 Wgb:c:

The C directory contains all of the CLI commands. As soon as a
command is entered from a Shell or CLI window, the CLI searches this
directory for the command. The command list can be expanded using a
path.

15

2. GOOD PROGRAMMING STYLE

DEVS

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Workbench 1.3 Wgb:devs:

The devs directory contains many devices. Not all of the Amiga's
devices are implemented in the operating system, since some are only
used infrequendy. The operating system searches the devs directory after
an OpenDevice () call if the device is not already present in
memory. You can write your own devices and store them here if

desired.

LIBS

Workbench 1.3 Wgb:libs:

The libs directory contains many libraries. You can write your own
libraries and store them here if desired.

SYS

Workbench 1.3 Wgb:

SYS represents the label on the system disk used for booting. The user
can access this disk by entering SYS: instead of the drive specifier.
This is especially useful when you must change your Workbench disk
from drive DFO to another drive. When you enter SYS: from the CLI
or Shell, the Amiga automa;ically changes Workbench disk access.

16

Many applications access the T directory, which is used for storing

backup and temporary fIles. Version 1.3 of the operating system
renames the device in T: so that all of the advantages that we have
learned about can be used. When developing a program never place this
directory in the RAM disk. Even though access is faster in a RAM
disk, all of the infonnation is lost after a reset.

2.S INTUITION

ABACUS

2.5

Intuition
A big factor in program development lies in writing for the end user.
Intuition offers us an alternative to using the Shell and UI for access.

Menus

Menus allow the user to select different items. We're going to look at
the menu display for now, instead of programming menus. No matter
how helpful the menus may be, poor presentation can ruin the menus.
Here are some rules to help you when developing menu routines.
Write out a list of all the menu titles and items you want to include in
the program. The menu line can contain up to ten menu titles, which
appear on the menu line when you press the right mouse key. Choose
menu titles carefully-make sure that these titles clearly explain the
items below the titles.
The menu titles should be placed starting with the most important (or
most used) title farthest to the left. The titles should decrease in
importance from left to right. Most often the left menu title is the File
menu title.

Shortcuts

Include keyboard shortcuts for frequently used menu items (e.g.,

<Amiga><s> for Save from the File menu). Remember that the Amiga
is case sensitive (i.e., <Amiga><s> and <Amiga><S> can represent
two separate shortcuts). Special characters are also allowed.
Menu items should be placed in the most logical order possible. For
example, a File menu should display its New, Load and Save items
nrst, followed by items for me deletion and other file maintenance.
If more than one option is available for an item (e.g., Save and Save
As), a submenu or requester can be added. For example, if the program
offers a choice of formats in which the data can be saved (ASCII, IFF,
protected format), you can add a submenu listing the ASCII, IFF and
PROTECTED items to the Save item. This eliminates the need for a
requester and saves you some programming time.
Display a requester as a last warning to the user that something
important is about to happen (e.g., deleting a me).

Requesters

Requesters are smaller windows which request information of

confrrmation from the user. Requesters can contain gadgets displaying
words such as YES, OK and CANCEL, or string gadgets into which
the user can type text.

17

2.

GOOD PROGRAMMING STYLE

ADVANCED SYSTEM PROGRAMMER'S GmDE

Sketch out the way you want the requester to appear. The requester
must appear organized and clear. For example. a requester appearing to
confllDl execution of an important function (e.g. deleting a file) should
contain at least two gadgets to allow positive or negative feedback from
the user. A simple YES and NO gadget will serve this purpose. or even
OK and CANCEL.
Include a gadget for alternate selection in a requester. For the
abovementioned requester used to ConfllDl file deletion. you could have
a YES gadget. a NO gadget and even a BACKUP ONLY gadget to
allow the user to delete only the backup copy of the file.
Key response

Some gadgets let the user select a gadget from the keyboard instead of
the mouse. The keyboard is not supported from Intuition like the
menus. Intuition handles the keyboard as a gadget specifically assigned
to one of the gadgets in the requester.For example. BeckerText from
Abacus surrounds this gadget with a bold red border. When the user
presses the <Return> key while in an active requester. the reading
routine reads the <Return> key as the specified gadget.
Choose this keyboard actuated gadget carefully (e.g. do not make the
YES gadget of a Delete file requester accessible from the keyboard).

18

3.

ABACUS

3.

DATA TRANSFER

Data Transfer
Sometimes user interaction with a program begins before the program
even runs. This early interaction involves the entry of arguments
(parameters), which may not take effect immediately. For example, if
you enter the following from the CLI, the text editor ED loads into
memory, then a file loads into ED and appears on the screen:
ed filename

This same process can be used from the Workbench. You can move the
mouse pointer onto the icon of a text file created by a word processor
(e.g., BeckerText) and double-click on the text file icon. The word
processor loads first (assuming it is readily available), then the
operating system loads the selected file into the word processor.
Getting user
data

The programmer can use these two methods to get data from the user.
Some programs cannot operate without additional arguments. Many
Shell and CLI commands require arguments to operate correctly.
We've just seen how some programs require certain data to execute
correctly. This chapter views the transfer of data from two sources.
First we'll examine how the CLI accepts arguments from the user when
invoking a command. C programming for arguments is very simple,
thanks to the way the C compiler processes data. Then we'll see how
data is transferred by the Workbench.

19

3.

DATA TRANSFER

3.1

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ell arguments
Many CLI commands require additional arguments. The syntax can
look something like this:
cli_command argument

The invoked CLI command reads and confirms the arguments, then
executes the command based on these arguments if possible.
Arguments

The main () function of the C language has two arguments that are
seldom used but are very helpful. The first argument specifies the
number of arguments needed. The second argument represents a pointer
to a string array into which all of the arguments are placed. The
following routine reads the input line, from which we can read the
individual entries.
1****************************************

* Subroutine: Read the input line

====================================

* Inputsub.c
* Author: Date:

July 1988

Wgb

Comments:
Aztec Routine

*
*

*
*
*

*
*
*
*
*
*

****************************************/

*include <libraries/dosextens.h>
extern int argc, arg len;
extern char-** argv, *-arg lin;
_cli~rse(pp,-alen, aptr)struct Process *pp;
long alen;
register char *aptr;
{

register char *cp;

/* Character Pointer */
register struct CommandLinelnterface *cli;
register int c;
/* Characters at Pointer Position */
void * AllocMem();
cli= (struct CommandLinelnterface *) long)pp->pr CLI 2);
cp = (char *) long) cli->cli CommandName 2); arg len = cp[O]+alen+2; /* L;ngth + PrgName + Null-Bytes */
If _arg_lin = _AllocMemlong)_arg_len, OL == 0)
return;
strncpy( arg lin, cp+l, cp[O]);
/* Program name */
strcpy( arg lin+cp[O], " ");
/* spaces */
strncat( arg lin, aptr, (int)alen); /* Parameter
*/
for ( argc=O~aptr=cp= arg lin;; argc++)

while c=*cp) == , , II c == '\t' II c

c == '\r' II c == '\n')
{ -

20

==

'\f' II

3.1 eLI ARGUMENTS

ABACUS

cp++;
i f (*cp < ' ')

break;
if (*cp = ,n,)
I
cp++;
while (e = *cp++)
I
*aptr++ = e;
if (e = '''')
I
if (*ep == ,n,)
ep++;
else
I
aptr[-1) = 0;
break;
}

else
I
while(le=*cp++) "
e != '\x'
*aptx++ = e;
*aptr++ = 0;

e != , , " e != '\t' "

e != '\n')

&,

e!= '\f' "

i f Ie =

0)

--ep;
*aptr = 0;
if argv= AllocMemlong) ( arge+1)*sizeof(* argv),OL)== 0)
1_arge = 0;
return;
}

for (c=O,cp= arg lin;c< arge;c++)

I
argv[e) = cp;
cp += stxlen(cp) + 1;
}

_argv[e) = 0;
}

Program
description

The program takes the length of the input line from the CLI, then
allocates memory for the argument tables. When these are not present,
it means that no arguments were given in the command line. The
program name, spaces and arguments are then copied into the argument
table memory. This serves as the base for the following loop.
The loop checks the entire list for any separator characters (i.e., spaces,
tabs, form feeds, carriage returns and ends of lines). When the loop
fmds one of these characters, it determines how the characters are
handled, and whether a command character is found. If one of the
command characters is encountered, it is determined in many
comparisons which characters are handled or if a quotation mark is

21

3. DATA TRANSFER

ADVANCED SYSTEM PROGRAMMER'S GUIDE

encountered. This quotation mark tells the loop to look after the
quotation marlc for additional separators.

Quotation
marks

After this test, the loop treats the character suing between the quotes as
if no separating characters are found. Then the program loop places a
null byte after the text to end it This operation repeats until the entire
text has been checked. Then another memory function allocates new
memory for the pointer tables (more on this later). All of the pointers
to the individual texts are entered in this block of memory.
The last entry in the pointer table is set to zero to make the end
recognizable without number variables. To see how this routine wom,
here is a program that displays the number of parameters given as CLI
arguments, then lists all of the values in table form.
1***************************************

* Program: Display CLI arguments

=====================

* DisplayClLc
* Author: Date:

Comrrents:

* ------ ---------- ----------

*
*

*
*
*
*

June.l988
only listing
Wgb
*
***************************************/
main (ArgC, ArgV)
int ArgC;
char *ArgV[]:
{

int i;
printf ("Number of arguments: !fsd\n", ArgC);
for (i=O; i<ArgC; i++)
printf("CLIArg !fsd: >!fss<\n", i, ArgV[i]);
}

Program
description

The main () function handles the ArgC and ArgV arguments. ArgC
(Argument Counter) represents a counter variable which contains the
total number of assigned arguments. The program name is considered
one of these arguments within the entire input line. This input line is
assigned to a text table. The program name can include a disk path, if
such a path is needed. Program names are included as arguments, even
when a program is started from the Workbench (more on this later).
ArgV (Argument Vector) is the pointer to the text table mentioned
previously. It is handled as a one-dimensional array of char elements

(characters). The routine created from the enuies of this table recognizes
spaces between two words as a break between two arguments. There
may be times when a space is required in a text (e.g., file name
instead of f i 1 e n a me). If you wish to read two words as one
argument, then the desired text must be placed within quotation marks.
For example:

22

3.1 eLI ARGUMENTS

ABACUS

Wrong:
Right:

execute file name

execute "file name"

This program is intended to show you a simple application of the

routine. Enter the program and save it under the name
DisplayCLI. C. Compile and link normally according to your
compiler's instruction manual (e.g., Aztec C uses the 32 bit optio).
Let's execute the program a few times to test it out. Enter the CLI and
enter the following (add your own path names as needed):
OisplayCLI

The program displays the following on the screen:

Number of arguments: 1
CLIArg 0: <DisplayCli>

Let's execute the program with some arguments. Enter the following:
DisplayCLI 1. DFO: Hello Wally

The program displays the following on the screen:

Number
CLIArg
CLIArg
CLIArg
CLIArg
CLIArg

More about
quotation
marks

of
0:
1:
2:
3:
4:

arguments: 5
<DisplayCLI>
<1>.
<DFO:>
<Hello>
<Wally>

Earlier we discussed adding quotation marks to make multiple words

into one argument. Let's see if the program accepts this type of input
Enter the following:
DisplayCLI "DF1:1. Test Run"

The program displays the following on the screen:

Number of arguments: 2
CLIArg 0: <OisplayCLI>
CLIArg 1: <OF1:1. Test Run>

Argument
templates

Let's take a closer look at arguments. Programs should always have an

argument template available. An argument template tells the user

which arguments are acceptable to a command. You can display an
argument template from the CLI by entering the command name, a
space, a question mark and the <Return> key.
AmigaOOS has argument templates available for almost all of its
commands. For example, if you wanted to see the argument template

23

3.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DATA TRANSFER

for the di r command, you would enter the following in the

command line:

eLi

dir ?<Return>

Testing ror
argument
templates

Our own program should have the ability to test for a question mark. It
should also test for the proper number of arguments. If it detects an
incorrect number of arguments, the program should display an
appropriate error message.
The following program executes this task. We made this the main ()
function of the program. You may wish to follow this style in your
own programming.
1***************************************
* Program: Read CLI arguments

* ReadCLI.c
* Author: Date:

*
*
*

* =================================== *
* ------ ----------

* Wgb

06/20/1988

Comments:

also "?" Option *

***************************************1
iinclude <exec/types.h>
main (ArgC, Argv)
int ArgC;
UBYTE *Argv[ J;
{

int i;
i f (ArgC == 1)
printf("No parameters from the CLI!\n");
else
printf ("'lsd Parameter, that can be evaluated\n", ArgC-l);
if ArgC == 2) && (*Argv[l] == '?'
printf ("Format: 'Iss [ J [ J \n", ArgV [0]);

Program
description

The program displays the number of arguments given. If no arguments

were entered, the program displays this fact. The program also checks
for <Space><?>. If the user entered the request for the argument
template, the program displays the argument template on the screen.
The argument template may take up more than one screen line. Our
program reads the ftrst entry in the text table, rather than the program
name itself. This allows the user to rename programs and assign
different paths as needed, thus keeping the program open to change.
Remember that the above program listing shows only a few aspects of
argument template output. You've probably seen programs that react to
too few arguments, too many arguments, or even incorrect arguments.
The single disadvantage of the " ?" function is that the entire program
must be loaded before the argument template can be displayed.
Sometimes the argument template may not appear because of
insufftcient memory.

24

ABACUS

3.2

3.2 THE.INJ'O FILE

The .info file

The DisplayCLI program listed above demonstrated a method of
making the CLI easier to use. However, programmers and developers
are the most frequent users of the CLI. The average user accesses
programs through the Workbench. This user interface ensures simple
access for the user who just wants to use the computer with a
minimum of computer literacy.

Arguments
and the
Workbench

How can the user enter arguments in an application started from the
Workbench? Let's look at what happens when we start a program from
Workbench. The program receives information from a startup routine
determined by the main () function. This startup routine replaces the
argument table given by text entered in the CLI, while assigning values
from the Workbench. We'll now look more closely at these values.
The frrst data received is a list of files apd locks available to this
program. The files refer to a list of files invoked when you double-click
a program icon. The locks are pointers to the direcUXies, supplying the
program with pure filenames. Look at the following program:
1***************************************

* Program: List out WBMessage

======================

*
*
*

* WBMessage.c
* Author: Date:

Cormnents:

*
*

* Wgb
*

only Locks and

File names

*
*

* ------

06/20/1988

*
*

***************************************1

'include <exec/types.h>
'include <workbench/startup.h>
'include <stdio.h>
extern struct WBStartup ~nchMsg;
main 0
{

int i;
struct WBArg *Arg;
for (i=O, Arg=WBenchMsg->sm_ArgList; i<WBenchMsg->sm_NumArgs;
i++, Arg++)
printf(WWBArg %d: Lock=Ox%lx Name = %s\nn,
i, Arg->wa_Lock, Arg->wa_Name);
printf(ttPRESS <Return> TO EXIT\nW);
Delay (5*60L);
}

25

3.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DATA TRANSFER

Program
description

This program assumes that it was started from the Workbench. Later
you will see an example of a program that can be started either from the
CLIor the Workbench. It displays the message WBenchMsg, which
contains all of the applicable filenames and corresponding locks. These
are listed in table format in the for () loop.
Compile and link the program, then assign it a tool icon. Once you've
done that, we can begin experimenting. Open the Workbench screen and
select the icon of this program. Select the Workbench function Info
item from the Workbench menu. The Tool Types string gadget
should contain the following:
WINDOW=CON:0/0/600/80/TestWindow

Immediately after starting the program, the startup routine mentioned

automatically opens the window as defined in the Tool Types string
gadget. The short routine listed below performs this task:
/********************************************

* Program: Read ToolTypes in window

======================================-=

* ReadToolTypes.c
* Author: Date:

Conments:

* ------

* Wgb
*
*

July 1988

Aztecs Routine

*
*

*
*

*******************************************/

iinclude <libraries/dosextens.h>
iinclude <workbench/workhench.h>
iinclude <workbench/startup.h>
iinclude <workhench/icon.h>
void *IconBase = 0;
_wb-parse(pp, wbrn)
register struct Process *pp;
struct WBStartup *wbrn;
(

register char *cp;

register struct DiskObject *dop;
register struct FileHandle *fhp;
register long wind;
void * OpenLibrary();
long Open () ;
i f IconBase = _OpenLibrary ("icon.library", OL == 0)
return;
if dop = GetDiskObject(wbm->srn ArgList->wa Name == 0)
goto closeit;
- i f (cp = Fi ndTool Type (dop->do ToolTypes, "WIND~"
(
if (wind = Open(cp, MODE OLDFlLE
{ -

fhp = (struct FileHandle *)

pp->pr_ConsoleTask = (APTR)
pp->pr_CIS
(BPTR)
= (BPTR)
pp->pr_COS
)

26

(wind 2);
fhp->fh_Type;
wind;
_Open("*", MODE_OLDFlLE);

3.2 THE.lNFO m.E

ABACUS

FreeDiskObject(dop);
closeit:
CloseLibrary(IconBase);
IconBase ,;. 0;
}

Program.
description

This routine tries to open the Icon. library to detennine whether a

TooIType WINDOW appears in the program file. Then the .info
structure is accessed by means of Get 0 i 8 k 0 b j e c t ( ) , and
F indTool Type examines the structure. If an entry named WINDOW
is present, the routine attempts to open an output window using the
definition following WINDOW. If this is,successful, the window opens
and the routine informs the structure that execution was successful.
After opening the window, DiskObject releases the library. We
click on the program icon and OlD' program starts. The window appears
in the predefined location and displays an entry from the table. We also
see the dire<:tory lock, which contains the program and the program
name.
You can access more than one .info file from the Workbench, just as
you can call multiple programs in the CLI. Click on another icon,
press the <Shift> key and double-click the program's icon: Another
entry appears in the list.
Let's examine another way to do this. Create a Notepad text and copy it
to the disk which also contains WBMessage. Select the Info item
from the Workbench menu. When the Info screen appears,look at the
string gadget labeled Default tool. It should contain the text:
SYS:Utilities/Notepad
CJ

Click on this gadget and delete this text. Enter the following in its

place:
DFO: WSMessage

Click on the Save gadget to exit. Now. double-click on the Notepad

text. The window reappears. This time, the Notepad text tried to access
a non-existent Default Tool (Le., WBMessage). The lock entry displays
no value, and the program lists the name of this tool as it appears in
the Defaul t
Tool string gadget. We find the lock and the
corresponding name under the text entry.

More-about
Tools and
Projects

We can also determine whether a Tool (an application) was started

directly or through a Project icon. Add the following data to the above
program code:
printf("WBArg %d: Lock=OxUx Name

\5\n",

27

3. DATA TRANSFER

ADVANCED SYSTEM PROGRAMMER'S GUIDE

if

i, Arg->wa Lock, Arg->wa Name)

0) " (Arg->wa_Lock =-0

s=

printf("Started without program. This was loaded

afterwards!\nlt);
}

Compile and link the source, then assign it an icon. Click on the
Notepad text you created in the last example and select the
Duplicate item from the Workbench menu. Press the <Shift>
key and click on both Notepad text icons. Now double-click the
program icon. We get a longer list with more locks and filenames.
What sense does it make to use all of the filenames? Each filename
looks to the data in the .info file. We can read this data, examine it and
even process it
The Get Dis k 0 b j e c t () function. which lies within the
icon . library reads the data from the jnfo file. We can set a new
current directory using the lock, then read the .info file:. Look at the
following program code:
1***************************************

* Program: List out ToolTypes

=====================

* ListToolTypes.C
* Author: Date:

*
*
*

Comments:

*
*
*

*
*

06/20/1988

Access to .info *
file only
*
* Compile options
*
*
* cc +L listtooltypes.c
*
* In listtooltypes.o -lc32
Wgb

***************************************/

finclude <exec/types.h>
finclude <workbench/workbench.h>
finclude <workbench/startup.h>
'include <workbench/icon.h>
'include <stdio.h>
extern struct WBStartup *WBenchMsg;
extern struct IconBase *IconBase;
void
*OpenLibrary ();
main 0
{

int i, j;
char **ToolArray, *Value;
LONG OldDir;
struct DiskObject *Lock;
struct WBArg *Arg;
if (! (IconBase = (struct IconBase *)
OpenLibrary("icon.library", OL)
printf(-Library not received!\n");
exit (FALSE);
}

for (i=O, ArgsWBenchMsg->sm ArgList; i<WBenchMsg->sm_NumArgs;

i++, Arg++)

28

3.2 THE .INFO FILE

ABACUS

printf("WBArg 'd: Lock-OxUx Name = 's\n",

i, Arg->wa Lock, Arg->wa Name);
i f i = 0) " (A~->wa Lock ==0-')
(
printf("Started without program. This was loaded
afterwards!\n");
}

else
(

OldDir = CurrentDir(Arg->wa Lock);

Lock = GetDiskObject(Arg->wa Name);
i f (Lock ! = NULL)
(

FreeDiskObject(Lock);
)

CurrentDir(OldDir);
)
)

printf("\nWAIT A MOMENT!\nR);
CloseLibrary(IconBase);
Delay(5*60L);
}

Program
description

All this routine does is release the DiskObject and then return to the
current directory. When we first access the text array contained in
Tool Types, we can see which values were assigned. Now let's
replace the display routine:
ToolArray = Lock->do ToolTypes;
j = 0;
cb

printf("'d. Entry: 's\n", j, ToolArray[j]);

j++;
}

while (ToolArray[j] !- Null);

Create multiple ToolTypes in an .info flle for the next test Mter
saving, compiling and linking, return to the Workbench. Click on one
of the Notepad texts and select the Info item from the Workbench
menu. Click on the Tool Types suing gadget. Tool Type s are
entered in the following manner:
TYPE = FIAGS

The word TYPE represents a keyword, which certain functions can

access later on. You saw another example ah9ve in the form of a
keyword named WINDOW:
WINDOW = CON:0/0/640/80/TestWindow

Keywords can consist of any alphanumeric characters.

29

3. DATA TRANSFER

Flags

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Flags supply specific infonnation about execution and other processes.

The Notepad uses some flags that indicate whether the text uses one or
more fonts (more on this later). When you wish to set more flags,
separate each flag using the <I> character. This character is alternately
known as the Or character.
So far we can read data using the above code. How can we display and
edit this data? First we must see what the current values are in a
program's .info file. Next, we must check for an additional icon that
represents a Tool (application) or Project (data file). Project data takes
precedence over Tool data.
The procedure is as follows. First we read the Tool Type. For
example, if we have FILETYPE present, it searches for the known
types that our program also processes. We also compare to see if it is
handled as an ASCII file that can be loaded from the corresponding
routine. If it is not an ASCII file, the program must determine whether
it can process the other fonnat.
The following program examines the FILETYPE and displays a
corresponding message. That is why you must prepare an .info fIle for
this program, Use the"Dotepad icon you created in the previous
examples, remember to chage the default tool in the info window. This
.info file has a WINDOW entry. Instead of the text output you can
insert your own program name in the appropriate subroutines, or
supply just the flags with values. This is especially advisable if more
arguments are expected than just the file types.
1***************************************

* Program: Evaluate ToolTypes

* ;================================== *
*
Comments:
*
* -----*

* EvalToolTypes.c
* Author: Date:
* Wgb

06/20/1988

tests FlLETYFE

*
*
*
*
***************************************/
'include <exec/types.h>
'include <workbench/workbench.h>
'include <workbench/startup.h>
Unclude <workbench/icon.h>
'include <stdio.h>
extern struct WBStartup *WBenchMsg;
extern struct IconBase *IconBase;
void
*OpenLibrary () ;
main()
{

int i, j, Test;
char **ToolArray, *Value;
LONG OldDir;
struct DiskObject *Lock;

30

3.2

ABACUS

THE JNFO FILE

struct WBArg *Arg;

if (! (IconBase = (struct IconBase *)
OpenLibrary ("icon. library", OL)
printf ("Library not received! \n");
exit(FALSE);
}

for (i=O, Arg=WBenchMsg->sm ArgList; i<WBenchMsg->sm NumArgs;

i++, Arg++)
printf("WBArg %d: Lock=OxUx Name = %s\n",
i, Arg->wa Lock, Arg->wa Name);
i f i = 0) "
(Arg->wa Lock =='0
{
printf("Started without program. This was loaded
afterwards!\n");
}

else
{

OldDir = CurrentDir(Arg->wa Lock);

Lock = GetDiskObject(Arg->wa_Name);
if (Lock != NULL)
{

ToolArray = Lock->do ToolTypes;

Value = FindToolType(ToolArray, (char *)"FlLETYFE");
if (Value)
{

printf ("Tool Type FlLETYFE with %s present! \n",

Value);
Test = MatchToolValue(Value, (char *)"TOOLTEST");
printf("Test result %d\n", Test);
}

else
printf ("ToolType FlLETYFE is not present! \n");
}

FreeDiskObject(Lock);
}

CurrentDir(OldDir);
}

printf("\nWAIT A MOMENT!\n");
CloseLibrary(IconBase);
Delay(5*60L);
}

The above program doesn't fulfill the set provisions, since it is only a
short demo. Adding these features to your own programs would make
using the Amiga much simpler for the user. The last example program
makes the connection between CLI checks and .info fIle evaluations. It
allows the user the possibility to set three flags: a(dd), p(rint) and
i(nsert). This can occur through the CLI with a preceding hyphen (-a,
-p. -io), or through the .info fIle (entering ADD, PRINT and INSERT
next to the FLAGS keyword). Here's the listing:

31

3.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DATA TRANSFER

/****************************************

* Program: Setting flags from CLI , WB *

* --------------------- *

FlAGS.C

* Author:

06/20/1988

*Wgb

*
*

Comment sa

Date:

*
*

-a -p -i
*
FLAGS*
ADD IPRINT I INSERT *

***************************************/
'include <exec/types.h>
linclude <workbench/workbench.h>
'include <workbench/startup.h>
'include <workbench/icon.h>
linclude <stdio.h>
extern struct WBStartup *WBenchMsg;
extern struct lconBase *IconBase;
void
*OpenLibrary ();
main (ArgC, Arq'J)
int ArgC;
UBYTE *Arq'J[];
{

int i, j;
int TestA = 0, TestP = 0, TestI
char **ToolArray, *Value;
LONG OldDir;
struct DiskObject *Lock;
struct WBArg *Arg;

0;

1**********************************

* Routine: CLI Reader

~e=====

* Author: Date:

*
* Wgb

__ ===_z=_ **
*
COlI'I!Ients:

---------- *
06/20/1988 -a -p -i
*

**********************************1
i f (ArgC > 0)
{

for (i-O; i<ArgC; i++)

{

if (*ArgV[i] == (UBYTE)'-')
{

i f (* (Arq'J[ij +1)

if (* (ArgV[ij +1)
i f (* (ArgV[ij +1)

'a') TestA = TRUE;

'p') TestP = TRUE;
'i') TestI = TRUE;

else
1****************************************

* Program section: WB Reader

*
* =--======-:_-========-=======-=- *
*
*

* Author:

Date:

COlI'I!Ients:

*
---------------- *

* Wgb
06/20/1988 ADD I PRINT I INSERT *
****************************************1

32

ABACUS

i f (! (IconBase -

(struct IconBase *)
OpenLibrary(Wicon.library-, OL)))

printf(-Library not received!\nW);

exit (FALSE) ;
}

for (i-O, ArgzWBenchMsq->sm_ArgList; i<WBenchMsq>sm_ NumArqs;

i++, Arq++)
(

printf(nNBArq id: Lock-Ox'lx Name - 's\nW,

i, Arq->Wa Lock, Arg->wa Name);
i f i - 0) "
(~q->wa Lock -0))
(
printf("Started without proqram. This was loaded
later!\nn);
else
{

OldDir = CurrentDir (Arq->Wa Lock);

Lock - GetDiskObject(Arg->wa Name);
i f (Lock ! - NULL)
(

ToolArray = Lock->do ToolTypes;

Value = FindToolType(ToolArray, "FLAGS");
i f (Value)
(

TestA = MatchToolValue(Value, "ADD");

TestP - MatchToolValue (Value, npRINT");
TestI = MatchToolValue(Value, "INSERT");
}

else
(

printf("ToolType FLAGS is not present!\nn);

)

FreeDiskObject(Lock);
}

CurrentOir(OldDir);
}
}

printf(n\nKAIT A MOMENT!\n"):
CloseLibrary(IconBase):
1* Delay(5*60L): *1
}

if (TestA) printf("ADD flaq set!\nn);

if (TestP) printf(RPRINT flaq set!\nW}:
if (TestI) printf("INSERT flaq set!\n"):
Delay (5*60L);
}

Program
description

The program is composed of two main sections. 1be first section

checks to see if arguments were entered from the CLI. If this is the
case, these arguments are tested for the three relevant types. The flags
are set correspondingly. These flags control output once the program

ends.

33

3. DATA TRANSFER

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Two factors to remember: First, the program doesn't test for

unsupported flags. It simply displays an error message. In addition, we
chose not to include an argument template as described earlier in this
section. You can probably add these features later.
You can also assign values to a flag as well as assigning a flag itself.
The format for this looks like the following:
Flags -w=20

This check also represents no problem if you use the at 0 i ( )

function, which transforms the ASCII value "20" into the integer value
20. The second large section of the program executes when the program
was started from the Workbench instead of the CLI. This routine
examines Tool Types and sets the corresponding flags. This check is
incomplete, so it searches through only those Tool Types affecting
our flags. Other arrangements can be added here.
Here are some tables and rules for the .info files to conclude this
chapter.

Sequence of Workbench messages:

1.

Program info

2.

First data fIle clicked on

3.

Second data me clicked on

There is no info for a program if this is not clicked! That can be found
out if the lock = O.

Sequence of ToolTypes:

34

1.

The Tool Types are supplied in the abovementioned

succession as blocks.

2.

Individual blocks are transmitted in the same order as the

entries in INFO.

3.

Def aul t Tool of the frrst file clicked on is always loaded

after the fIle; all others are ignored.

J.l THE .INFO FILE

ABACUS

ToolTypes entries with the Notepad:

Name
FILETYPE
FONT
WINDOW
FLAGS

Example
notepad
topaz. 8
0,0,50,50
NOGLOBAL

Name
NOGLOBAL
GLOBAL
NOWRAP
WRAP
NOFONTS
FORMFEED
DRAFT

Meaning

Meaning
(_.

Notepad text
Global font

Window coordinates
Set flags

Notepad nags:
Disables global font function
Enables global font fWlction
Disables word wrap
Enables word wrap
No font table loaded \.
Enables form feed
Enables normal printing

35

4.1 WHAT ARE DEVICES?

ABACUS

4.

Devices
You've probably heard the word device used by other Amiga
programmers. Some of the source codes in this book access devices.
This chapter will help you understand the purpose and practical
application of devices.

4.1

What are devices?

Devices are actually nothing more than libraries containing additional
information that pertains to device drivers. These drivers can control
internal devices (e.g., disk drives, keyboard and game ports) and external
devices (e.g., printers and modems). Devices can be opened like
libraries. Here are the Exec functions used to call libraries and devices:
Libraries:
Devices:

OpenLibrary ()
OpenDevice ()

Libraries vs. devices

There is another major difference between devices and libraries. When
opening a library, Op e n Lib r a ry () returns the address of a
completely initialized and ready-to-enter library. OpenDevice () also
reports eventual errors to the programmer. That is why
OpenDevice () needs pre-initialized structures from the user. The
structures can be joined together and completely initialized.
Let's look at a typical OpenDev i ce () call:
Error = OpenDevice("trackdisk.device", OL, DiskRequest, OL);
if (Error! = 0) CloseIt
(IIOpenDevice () - Error");

The structure controlling the device (in this case, the internal disk drive)
is an IORequest structure:

37

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Offsets
0 OxOO
20 Oxl4
24 OxlS
28 Oxlc
30 Oxle
31 Oxlf
32 Ox20

struct IORequest
{ /* defined in "exec/io.h" */
struct Message io_Message;
struct Dev~ce *io Device;
struct unit
*io-Unit;
UWORD
io-Command;
UBYTE
io Flags;
BYTE
io-Error;
/* 32 == NumBytes of-this structure */
(

:IORequest

You don't need to define the IORequest Structure in your program

every time you want to use it. This structure is defmed in the include
file "exec/io.h". Once called, this structure lies ready for your
declarations. For example:
struct IORequest *DiskRequest;

Device initialization
We already mentioned that the device structures must be initialized
before use, unlike the libraries. This is done using the Exec support
function CreatExtIO (). "Exec support function" means that this
function is not based in a system library. Instead, it can be found in the
linker library for your compiler (c .lib for Aztec C or amiga .lib
for Lattice C). Here's a simple example of how CreatExtIO ()
works:
/**********************************************************/

/*
CreateExtIO ()
(Exec support) * /
/*
*/
/* Function:
Create device block
*/
/*--------------------------------------------------------*/
/* IOReplyPort: MsgPort for WaitIO() etc.
*/
/* Size:
Size of the device block
*/
/**********************************************************/

struct IORequest *CreatextIO(IOReplyPort, Size)

struct MsgPort
*IOReplyPort;
LONG
Size;
(

struct IORequest *Request;

/* no IOReplyPort? then leave CreateExtIO() */
if (IOReplyPort == NULL) return(NULL);
/* reserves memory for request */
Request = AllocMem(Size, MEMF PUBLIC I MEMF CLEAR);
/* no memory? Then leave CreateExtIO() */ if (Request == NULL) return(NULL);
/* report of type MESSAGE * /
Request->io Message.ron Node.ln Type = NT MESSAGE;
/* reports ~re SIZE bytes long-*/
/* See also DeleteExtIO().
*/
Request->io Message.ron Length
= Size;
/* give port messages */
Request->io Message.mn ReplyPort
IOReplyPort;
return (Request);
-

38

ABACUS

4.1 WHAT ARE DEVICES?

CreateExtIO () allocates memory for a device request sttucture.

Standard device blocks such as IOStdReq, IORequest, IOAudio
and others fall under the category of device request structures. You can
store and initialize these different device blocks, which help the
communication between computer and deVice, using Crea tExt IO ( ) .

Common ground
All of the device request structures or device blocks have one thing in
common: The first element is an IORequest sttucture. This means
that all of the different device blocks can be handled the same from
Crea teExt IO ( ) . The difference fll"St appears aft.er the first few bytes
of the IORequest structure. Let's look at the IOAudio sttucture
(the audio device block):
struct IOAudio
{

struct IORequest ioa_Request;/* IORequest at the beginning*/

WORD
ioa_ AllocKey;
UBYTE
*ioa Data;
ioa-Length;
ULONG
{]WORD
ioa:=Period;
{]WORD
ioa Volume;
ioa-Cycles;
{]WORD
struct Message
ioa=WriteMessage;

The first element of the IOAudio structure is an IORequest

structure. When you assign CR=CreateExtIO () the starting address
of some lOA udi 0 structure, this address is identical to that of an
IORequest structure. Because all structure element accesses occur
through offsets, they are automatically initialized at the beginning of
the IORequest structure of the IOAudio block. We can initialize it
using the following I/O block to open the device:
struct IOAudio *OWnlOAudio;
OWnIOAudio

= (struct lOAudio *)

i f (OWnlOAudio

CreateExtIO{AudioPort, sizeof{struct lOAudio))

== 0) CloseIt ("CreateExtIO () - Error");

The block is then executed with the help from OpenDevice () :

OpenDevice ("audio, device", OL, OWnIOAudio, OL));

This sample call shows the purpose of the sizeof parameter for
CreateExtIO (). It gives the size of the I/O blocks to be allocated.
IOReplyPort

The first parameter for CreateExtIO () (IOReplyPort) requires

closer examination. IOReplyPort is nothing more than a message

39

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

pm. Message ports are needed for message reportS. They act as anchor
points for the devices. They hold reports to the system just as an
anchor holds a ship to the bottom of the sea. These ports must be
initialized before they can be used:
struct MsgPort *AnyOldPort;
AnyOldPort = Cstruct MsqPort *)
CreatePortC"anyold.port", 0);
if (anyoldport == 0) Closelt("CreatePort() - Error n ) ;

The routine used for this is called ere ate Po r t ( ) . It is also an

Exec support function:
1********************************************************1
1*
CreatePortO
(Exec support)*1
1*
*1
1* Function: Create MessagePort
*1
1*------------------------------------------------------*1
1* Name:
Name of the MsgPort
*1
1* Priority: Priority of the port
*1
1********************************************************1
struct MsqPort *CreatePort(Name, Priority)
char
*Name;
BYTE
Priority;
struct MsgPort *Port;
BYTE
SignalBit;
if ((SignaIBit = AllocSignal(-l == -1) return(NULL);
1* no signal bit can be reserved *1
Port = (struct MsgPort *)
AllocMem(sizeof(struct MsgPort), MEMF_PUBLICIMEMF_CLEAR);
1* memory allocation *1
i f (Port == NULL)
{

Freesignal(SignaIBit);
return (NULL) ;

1* no memory *1
Port->mp Node.ln Name
Port->mp-Node.ln-pri
Port->mp-Node.ln-Type
Port->mp-Flags Port->mp=SigBit
Port->mp SigTask
1* Initial~zation *1

= Name;

= Priority;

=
=
=
=

NT MSGPORT;
PA-SIGNAL;
Si9naIBit;
FindTask(OI);

if (Name != OL) AddPort(Port);

else
NewList (& (Port->mp MsgList;
1* Port in new list *1
return (Port);

When using the devices the message ports generally have no name, so
the initialization of a message port can be done by using the following

sequence:
struct MsgPort *Port;
Port = (struct MsgPort *)CreatePort(OL, OL);

40

ABACUS

4.1

WHAT ARK DEVICES?

CreatePort () throws out the "anchor" on which the device secures

itself through CreateExtIO () and OpenDevice (}:
struct MsgPort
*Port;
struct IORequest *Request;
Port
(struet MsgPort *)
CreatePort (OL, OL);
Request s (struet IORequest *) CreateExtIO(Port, sizeof(struct
IORequest)) ;
OpenDevice; (DEVICENAME, OL, Request, 0

The three routines listed above give you the power to access any device.
Because the steps for opening a device are always the same. we'll now
list some universal routines for allocating and de-allocating device
blocks. for opening and closing devices:
1***************************************************** *****/
Device-Support Functions
*1
(c) Bruno Jennrich
*1

1*
1*
1*
1*

*1

June 8 1988
*/
/***************************************************** *****1
1***************************************************** *****/
1* Compile Info:
*1
/*--------------------------------------------------------*/
*/
1* cc Devs Support
*/
1***************************************************** *****/
'include "exec/types.h"
'include "exec/io.h"
'include "exec/devices.h"
VOID Closelt();
/* Closelt() exists
*/
/* in your own program */
VOID *CreatePort () ;
/* Exec-Support
*/
VOID *CreateExtIO () ;
VOID DeletePort () ;
VOID DeleteExtIO ();
1***************************************************** ******/
/*
GetDeviceBlock ()
*/
/*
*/
/* Function:
Device-Block open and initialization
*/

/*

/*---------------------------------------------------------*/
/* Input - Parameter:
*/

1*
1* Size:

*/
Size of the Device-Blocks in bytes
*/
/*---------------------------------------------------------*/
/* Return value:
*/
/*
*/
1*
Initialize Device-Block
*/
/***********************************************************/
1IPTR GetDeviceBlock (Size)
ULONG
Size;
(

struct MsgPort *Device_Port;

1IPTR
Device Request;
1* Becasue this routine should be insertable universally*/
1* no IORequest-Strueture is placed, but instead
*1
1* any structure that through (CASTS) can be
*1
1* passed to the IORequest-Structure.
*/
1* Tries to allocate the Device-Port. If this is not
*/

41

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GmDE

1* possible, leave program. (CloseIt(.

*1

Device Port
(struct MsgPort *) CreatePort (0,0);
if (Device Port =- 0) CloseIt ("Couldn4t get DEVICE-PORT !");
1* Tries to allocate Device-Block. If that is not
*1
1* possible, give Device-Port back and leave
*1
1* program.
*1
Device Request a (APTR) CreateExtIO (Device_Port, Size);
i f (Device Request = 0)
{
DeletePort (Device Port) ;
CloseIt ("Couldn4t-get DEVICE-BLOCK !");

1* Give back previously installed Device-Block

return (Device_Request);

*1

1***********************************************************1
1*
FreeDeviceBlock ()
*I
1*
*1
1* Function:
Release Device-Block
*1
1*---------------------------------------------------------*1
1* Input - Parameter:
*1
1*
*1
1* IORequest: Release Device-Block
*1
1***********************************************************1

VOID FreeDeviceBlock (IORequest)

struct IORequest
*IORequest;
{

1* If IORequest can be opened, free up

1* Device-Port. The free up IORequest

*1
*1

if (IORequest != 0)
{

if (IORequest->io Message.mn ReplyPort != 0)

DeletePort (IORequest->io Message.mn ReplyPort);
DeleteExtIO (IORequest);
-

1***********************************************************1
I*

Open

Device ()

*I

1*
- *1
1* Function:
Open any Device
*1
1*---------------------------------------------------------*1
1* Input - Parameter:
*1
1* Name:
Name the Devices (i.e. "audio.device") *1
I * Un! t :

Device-Uni t

1* DeVice_Request: Pointer to block to be initialized

1*
(initialized) Device-Block
1* Flags:
Device-Flags
1* Size:
Size of the Device-Blocks

*I

*1
*1
*1
*I

1***************************************************** ******/

VOID Open A Device (Name, Unit, Device Request, Flags, Size)

char
- *Name;
ULONG
Unit;
APTR
*Device Request;
Flags, Size;
ULONG
{

UWORD Error;
1* Error from OpenDevice () *1
1* If Size> 0, allocate Device-Block.
*1
1* If Size == 0, use initialized device block*1

42

4.1 WHAT ARE DEVICES?

ABACUS

1* from user
if (Size != 0) *Device_Request

*1
GetDeviceBlock(Size);

1* Open Device *1
Error = OpenDevice (Name, Unit, *Device_Request, Flags);
if (Error ! = 0)
{

printf ("Open-Device Error *'4lx\n",Error);

CloseIt ("Couldn4t get DEVICE ! ") ;

1* NOTE! !!
1*

4Device Request4 is a pointer

to a pointer ! (**DevReq)

*1
*1

1***************************************************** *******/
1*

*1

Close A Device

1*
*1
1* Function:
Device-Block free and close Device
*1
1*----------------------------------------------------------*1
1* Input - Parameter:
*1
1*
*1
1* IORequest:
Released Device-Block
*1
/************************************************************1
VOID Close A Device (IORequest)
struct IORequest
*IORequest;
{

1* If IORequest can be opened, release

1* Device-Port. Close Device. The release
1* IORequest.

*1
*1
*1

if (IORequest != 0)
{

if (IORequest->io_Message.mn_ReplyPort != 0)
DeletePort (IORequest->io Mess'age.mn ReplyPort) ;
if (IORequest->io Device != of
CloseDevice (IORequest);
DeleteExtIO (IORequest);

/***********************************************************/
1*
Do Command ()
*1

1*
1* Function:

Execute command

*1
*1

I*----------------------------------~----------------------*1

1* Input - Parameter:
1*
1* DeviceBlock: Device-Block

*1
*1
*1

1 * Command:

*1

corrnnand

1***************************************************** ******/
VOID Do Command (DeviceBlock,Command)
struct IORequest *DeviceBlock;
UWORD
Command;
(

DeviceBlock->io Command
DoIO(DeviceBlock);

Command;

Closing a device
'" them again with the help of these
You can open devices and then close
functions. You must close an open device when finished with it, just as

43

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

you must close a library. While programs and libraries may be used at
the same time, this is not possible with devices. The user can only
access one device at a time. For other users to obtain access, the devices
must be closed after they have been used. This happens through the
Exec support routines DeleteExt IO () and DeletePort () , as
well as the CloseDevice () command:
1***************************************************** ******/
/*
DeletePort ()
(Exec support) * /
/* Function:
Release port
*/
/*---------------------------------------------------------*/
/* Input parameters:
*/
/* IOReplyPort: Released port
*/

1***********************************************************1
VOID DeletePort(IOReplyPort)
struct MsgPort *IOReplyPort;
{

/* if port is nameless, then remove port */

if IOReplyPort->mp Node.ln Name) != OL)
RemPort(IOReplyport);
/* erase type of port */
IOReplyPort->mp Node.ln Type = Oxff;
/* remove port from list */
IOReplyPort->mp MsgList.lh Head = (struct Node *)-1;
/* Release-memory of 'Port * /
FreeMem(IOReplyPort, sizeof(struct MsgPort;

DeleteExt IO () looks like the following:

1***************************************************** ****/
/*
DeleteExtIO()
(Exec support) */
/* Function: Release device block
*/
/*-------------------------------------------------------*/
/* Input parameters:
*/
/* IORequest: Device block to be released
*/
1***************************************************** ****/
DeleteExtIO (IORequest)
struct IORequest *IORequest;
{

/* In case IORequest is not present, leave routine */

/* otherwise freed twice alert arises
*/
if (IORequest == 0) return(OI);
/* IORequest mutilated so that further */
/* use is impossible
*/
IORequest->io Message.mn Node.ln Type = Oxff;
IORequest->io-Device = (;truct D;vice *)-1;
IORequest->io-Unit
= (struct Unit *)-1;
/* memory fre;d up. (memory from FreeMem() */
/* not erased, that is why the above mutilation.)
*/
FreeMem(IORequest, IORequest->io_Message.mn_Length);

In addition to these two Exec support functions, which make it

impossible to re-use IOReplyPorts and IORequest structures, we
have used the command CloseDevice () in our device support

44

4.1

ABACUS

WHAT ARE DEVICES?

functions. This ensures that the device can be used from other programs
again.
The device to be closed is informed through ClaseDevice () over
the IORequest block, which contains a pointer to the opened device
(IORequest->ia_Device). This pointer extracts
ClaseDevice () itself and uses it for the closing. When you want to
use the routines from Devs_Suppart. you make a routine with the
name ClaseIt () available for use. This is always called when an
error is encountered while opening a device. You will encounter such
C 1 a s e I t () routines in this book. and we want you to have
confidence in the demands that this routine makes:
1*****************************************************/
/*
Close It ()
(User) */
/* Function: display encountered error.
*/
/*
Close everything.
*/
/*---------------------------------------------------*/
/* Input Parameters:
*/
/* String:
Error String
*/
1*****************************************************I
VOID Closelt(String)
char
*String;
{

UWORD Error
= 0;
UWORD i;
UWORD *dff180 = (UWORD *)Oxdff180;
if (strlen(String) > 0)
{

for(i=O;i<Oxffff;i++) *dff180 = i;
puts (String);
puts("\n");
Error = 100;
/* free-up routine */
exit(Error); /* leave program *1

This ClaseIt () routine ensures that the screen blinks colorfully

once by specifying the background color registers. Then the error
message appears on the screen. telling you the location at which you
should look for an error. Then all of the opened device libraries, etc.,
are released. You should make sure that everything is released before the
error message is displayed. Most errors occur when closing. so you
don't know the error that most recently occurred.

Warning:
You should only use ClaseTt () as an "emergency exit" You should
never use ClaseIt () for convenience as the exit of the program,
which frees all of the structures for you. Rule of thumb: The routine
that allocates memory also releases memory.

4S

4.

DEVICES

4.2

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Communicating through devices

You now know how to open a device and how to close it again. Now
let's look at how you can exchange data between a program and a

device.
A device has many similarities to a library. When the device is opened,
IORequest->io_Device provides some routines for establishing
communication between program and device. This device library
contains the following commands and other data:
Command:

Offset:

Open
Close
Expunge
Extfunc
BeginIO

-Ox06
-OxOc
-Ox12
-OxIS
-Oxle
-Ox24

AbortIO

Open

Open is a routine called from OpenDevice () to control the device

specific installations. The Exec function OpenDevice () offers you
access to this device file. The device's own Open command provides
the necessary steps for the initialization of the addressed device.

Cl.ose

Close is called from CloseDevice () to make sure that the device

file closes properly.

Expunge

If a device must be loaded from disk, the memory allocated for the
device structures is released by Expunge. Open and Close increment
and decrement the allocated amount. The occupied memory is not
completely released by Close. Expunge releases all memory once it
is called from the Exec function RemDevice ().

Extfunc

The Ext func routine is reserved for special tasks (e.g., printer device
DO_SPECIAL). The routines BeginIO and Abort IO are the
routines we are interested in:

Begin:rO

BeginIO initiates the data transfer between the program and the
device. After the device block is completely initialized (data pointer
adjusted, command given, etc.), this command is called from
SendIO () as well as from DolO () . The call looks like this:

46

4.1

ABACUS

COMMUNICATING THROUGH DEVICES

BeqinIO:
move. 1
jmp

* Al contains *IORequest *
20(al), a6 * Device Library after A6 *
-$le(a6) * jump to BeqinIO
*

The actual BeqinIO routine. which is jumped to here through your

offset. looks for every other device. This is also logical. because
different steps. other than the execution when using the
trackdisk.device. are taken for the use of timer devices. BeqinIO is
also called from SendIO () and DolO () (the command BeqinIO ()
is also in the linker library for your compiler [c .lib for Aztec C or
amiqa.lib for Lattice C]). What difference is there between DolO ()
and SendIO () '1
SandIO

SendIO () is an asynchronous command. That means that the called

program can continue its processing after a device command is sent.
The device command is executed alongside the called program. When
using DolO ( ) the program that was called must wait until the
command from the device is completely processed. That is why you
name the command DolO ( ). Program execution and the device
command are synchronized.
DolO () and SendIO () after identical in their handling of a device
command The ending of the device command is expected by means of
wai tIO () when using DolO () in conjunction with the MsqPorts.
After construction you can use DolO () by means of SendIO () and
WaitIO ():
Second_DolO
(IORequest)
struct IORequest *IORequest;
{

SendIO (IORequest) ;
WaitIO(IORequest);

WaitIO () can be constructed by means of CheckIO ():

Second WaitIO
(IORequest)
struct IORequest *IORequest;
{

while (CheckIO (IORequest)==O);

1* Device command is not ended *1

When the device command is fully operational. CheckIO () returns

the value 0 in register DO. When the command is processed. the address
of the device block (IORequest) after CheckIO () passes to register
DO. You now know the functions needed for communication between a
device and the program.
Now for a question: If you would like to send a command to the device
as things currently stand. which variable of the IORequest (or

47

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

IOStdRequest) structure comes into play? We'll discuss details as

we examine each device. For now, here are a few items common to
each device:

IORequest->io_Command is the variable into which the

device command is stored.

The device command consists of only one number. This

nwober branches in SendIO () or 0010 () fer some device
specific routines.

Just stating the command does nothing. When you want to include
data, a data pointer and a variable supply the length or number of data
bytes to be transferred. The transfer of data is no longer possible with
the help of the simple IORequest structure. The IOStdReq
structure or a device specific structure (see IOAudio) must be used

instead:
Offsets

o
2D
24
28
30
31
32
36

40
44
48

struct

IOStdReq

{/* defined in "exec/io.h" *1

1* - IORequest - *1
struct Message io Message;
struct Device *io Device;
struct Unit
*io-Unit;
UWORD io Command; UBYTE io-Flags;
BYTE
io-Error;
1* - IOSt"dReq - *1
ULONG io Actual;
ULONG io-Length;
APTR
io-Data;
ULONG io=Offset;

OxOD
Oxl4
Oxl8
Oxlc
Oxle
Oxlf
Ox20
Ox24
Ox28
Ox2c
Ox30

The data pointer which works in conjunction with a structure has a

similar name. For example, the data pointer of the IOStdReq
structure is called IOStdReq. io_Data, while the data pointer of the
IOAudio structure is called IOAudio. ioa Data. The number of
data bytes for IOStdReq can be found in IOStdReq. io_Length.
IOStdReq. lo_Actual often specifies the number of data bytes
written or read. These variables occur only with more complex device
blocks such as the IORequest block.
Flag variables

48

Flag and error variables also appear in device blocks. You can control
the execution of a device command with the help of flag variables.
Because almost every device has its own flags, these flags can specify
when it is necessary to use the device. All devices have the
IOF _QUICK flag in common. This IOF _QUICK flag is set if a
command can be processed immediately. The read and write commands
of the ttackdisk.device, for example, go in a ttackdisk task. The
program that was called must wait for this command to be processed
with assistance from a message port. When reading disk status (e.g.,

4.2 COMMUNICATING THROUGH DEVICES

ABACUS

write protect on), a set IOF_QUICK flag may not occur, since this
command is executed without the trackdisk task.
Error variables The error variable is of particular importance. If the error variable equals
zero after a device command. everything is running all right. When the
error variable contains a value other than zero, an error occurred. You
should react according to the severity of the error (e.g., a warning to the
user). Each device has its own errors.
The following errors are common to all devices:
Variable

Value Meaning
(-1) Device cannot be opened
IOE~ABORTED
(-2) Command interrupted by AbortIO ()
IOERR NOCMD
(-3) invalid command
IOERR BAD LENGTH (4)
io_Length has an invalid value
IOERR OPENFAIL

Almost every device uses the read (CMD_READ) and write

(CMD_WRITE) commands. The reset command (CMD_RESET), which
places the device in the original condition, is also used by almost every

oovice.
Extended
commands

In addition to these standardized commands, each device has its own

extended commands. These commands capitalize on the individual
device's special abilities. The remaining sections of this chapter
describe these commands and how they affect their devices. In the
following sections we listed the easiest device access routines we know.
You'll find device specific support routines as well as generic device
support routines. These routines need a device block and parameters for
you to access them. This saves you the trouble of assigning values to
structure elements.

49

4. DEVICES

4.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The parallel device

The parallel device allows easy access to the Amiga's parallel interface.
You can read and write data through the parallel interface.
The parallel device supports the following commands:
CMD RESET

(1)

CMD READ

(2)
(3)
(6)
(7)
(8)

CMD
CMD
CMD
CMD

WRITE
STOP
START
FLUSH

resets device to post-OpenDevice ( )

status (including TermArray)
readsdala
writes data
stops reruVwrite (expects handshake)
restarts read/write
ignores existing read/write commands

The parallel device includes two device specific commands:

PDCMD SETPARAMS (9)

PDCMD_QUERY
(10)

4.3.1

sets parameters
fmds out port status

Opening the parallel device

The following code easily opens the parallel device:
struct IOExtPar *ParReq = OL;
'define PAR_LEN (ULONG) sizeof(struct IOExtPar)
Open_A_Device ("parallel.device", OL, ParReq, OL, PAR_LEN);

If another user opens the parallel device, you no longer have access.
Setting the PARB_SHARED flag (32) before you open the device
ensures that multiple users can access the parallel device at one time:
struct IOExtPar *ParReq = OL;
'define PAR_LEN (ULONG) sizeof(struct IOExtPar)
VOID *GetDeviceBlock();
ParReq = (struct IOExtPar*)GetDeviceBlock(PAR LEN);
ParReq->io ParFlags = (UBYTE) PARS SHARED;
Open_A_Device("parallel.device", OL, ParReq, OL, OL);

50

4.3 THE PARALLEL DEVICE

ABACUS

Problems with Transferring data from multiple programs to the parallel device can
sharing
cause problems. For example, texts sent from two different word
processors may run together through the device.
Now back to the Open_A_Device () command. You must assign
this address to a pointer to the device block (&ParReq-ParReq is
its pointer). The parallel device's device block looks like the following:
Offset

Structure
struct IoExtPar
{

0
48
52
53
54
62

4.3.2

Oxoo
0x30
0x32
Ox33
0x34
Ox3c

struct IOStdReq IOPar:

ULONG
io_PExtF lags: /* unused */
UBYTE
io Status:
/* Port Status */
UBYTE
io=:'ParFlags: /* SHARED+EOFIDDE */
struct IOPArray io_PTermArray;/* Terminates *1
1* defined in "devices/parallel.h" *1

Writing parallel device data

All you need to write data to the parallel device is the data to be sent
and the number of data bytes to be sent. Once those items are
established, you can invoke CMD_WRITE:
1***************************************************** **********
Parallel_Write 0

(Par_Support) *

* Function: Send data over the parallel interface

*
*

*--------------------------------------------------------------*
* Input - Parameter:

* ParReq:
* Data:
* Len:

Device-Block
Date to be sent
number of bytes to be sent

*
*
*

****************************************************** *********1
VOID Parallel_Write (ParReq,Data,Len)
struct IOExtPar
*ParReq;
APTR
Data:
Len:
ULONG
{

ParReq->IOPar.io Data
= Data;
ParReq->IOPar.io-Length = Len;
Do_Cormland (ParR;q, (UWORD) CMD_WRITE):

If you give the value -1 for Len (the number of bytes to be written), the
parallel device writes data until it encounters a null byte. The parallel
device writes this null byte and stops writing data.

51

4.

DEVICES

4.3.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Reading parallel device data

The following routine shows how to read data from the parallel device:
1***************************************************** **********
Parallel_Read 0
(Par_Support) *

* Function: Read data from the parallel interface

*
*

*--------------------------------------------------------------*
* Input - Parameter:

* ParReq:
* Data:
* Len:

Device-Block
Data buffer
Number of bytes to be read

*
*
*
*
*

****************************************************** *********1

VOID Parallel Read (ParReq,Data,Len)

struct IOExtPar
*ParReq;
APTR
Data;
ULONG
Len;
{

ParReq->IOPar.io Data
= Data;
ParReq->IOPar.io-Length = Len;
Do Command (ParReq, (UWORD) CMD_READ);

You can stop the character reading process using a defined character.
The IOPArray can contain the eight terminators:
Offset

Structure
struct IOPArray

o
4
8

OxOO
ULONG PTermArrayO;
Ox04
ULONG PTermArrayl;
Ox08}; /* defined in "devices/parallel.h" */

The eight terminators are specified as two long words:

Parallel SetParams (ParReq, PARB_EOFMJDE, Ox0001010l,
Ox0101010l) ;
/* PARB_EOFMJDE = 2 *1

Terminators

When the terminators of the Parallel SetParams () function are

determined by the method listed above, the reading stops after the
routine encounters OxOO or OxOl in ASCII code form. When you, as
above, establish less than eight terminators, you should pad the
remaining terminators with the value of the last terminator listed.
The Parallel_SetParams () function looks like the following:

52

4.3 THE PARALLEL DEVICE

ABACUS

1***************************************************** **********
*
Parallel_Setparams ()
(Par_Support) *
*
*
* Function: Change interface parameters
*

*--------------------------------------------------------------*

*
*
*
*

Input - Parameter:
ParReq:
Device-Block
Flags:
new Flags
TermArrayO/l: new terminators

*
*
*

***************************************************************/
VOID Paralell SetParams (ParReq,Flags,TermArrayO,TermArray1)
struct IOExtPar
*ParReq;
BYTE
Flags;
ULONG
TermArrayO;
ULONG
TermArray1;
{

ParReq->io ParFlags = Flags;

ParReq->io-PTermArray.PTermArrayO = TermArrayO;
parReq->io:PTermArray.PTermArray1 = TermArray1;
Do Command (ParReq, (UWORD)PDCMD_SETPARAMS);

After Open_A_Device () the PTermArray is ignored and only

OxOO is recognized as a terminator. Logically you can only change the
parameter for the parallel device if there is no write or read access. To
change the parameters of such an operation destroys the communication
base between the sender and the receiver, making further
communication impossible. For now, you can only change the
terminators with Parallel_SetParams () (PARB_EOFMODE
must be set accordingly),

4.3.4

Reading parallel device status

You can read the status of the interface in io_ Stat us, with the help
of the PDCMP_QUERY command. The bits in io_Status represent
the following:
Bit 0

IOPTF PSEL

1 (Printer Selected)

= 1: OFFLINE
= 0: ONLINE
Bit 1

IOPTF PAPEROUT
= 1:
= 0:

Bit 2
Bit 3
Bit 4-7

OK

PAPER OUT
IOPTF PBUSY = 4 (Printer busy)
= 1: Printer has nothing to do
= 0: Printer printed
IOPTF RKDIR = B (Direction (Read, Write
= 1: It was written
= 0: It was read
reserved

53

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Bits 0, 1, and 2 are active low. There is a 0 in the flag labeled Status.
PaperOut indicates that the flag IOTPF_PAPEROUT is not set
(these flags are defined in devices/parallel.h). You have
already seen that the parallel device is often assigned to an interfaced and
active printer. Basically, the above bits can be used for other devices
such as an EPROM burner. This status byte informs the computer that
the parallel device is not ready to begin processing the data it received
The following command sequence displays the status of the parallel

device:
Do Corrmand(ParReq, (UWORD)PDCMD_QUERY);
Status = ParReq->io_Status;

4.3.5

A parallel device application

The following program sends a short string through the parallel device.
There is usually a printer connected to the parallel port. The program
can tell whether a printer is actually connected to this port, or whether
the printer is switched off. If the printer is off or not connected, the
program displays the message "Printer OFFLINE or not ready" on the
screen. Combine the three routines in the previous section to form the
Par_ Support.c module, don't forget to include the exec/types.h,
exec/memory.h, exec/io.h, and deviceslprinter.h fIles in Par_ Support.c.
1***************************************************************

*
*
*

Par.c
(c) Bruno Jennrich
August 1988

(User)

*
*
*

***************************************************************/
1***************************************************** **********

* Compile-Info:
* cc Par.c
* In Par.o Par Support.o Devs Support.o -lc

*
*

***************************************************************/

iinclude "exec/types.h"
'include "exec!memory.h"
'include "exec/io.h"
'include "devices/parallel.h"
struct IOExtPar *ParReq = 01;
idefine PAR LEN (ULONG) sizeof (struct IOExtPar)
VOID *GetDeviceBlock();
1***************************************************** **********

*
*
* Function: If error, close all
*
*--------------------------------------------------------------*

Closelt()

(User)

* Input - Parameter:
* String: Error-Message

*
*

***************************************************************/

VOID Closelt (String)

S4

ABACUS

4.3 THE PARALLEL DEVICE

char

*String;

m:lRD i;
UWORD *dff1BO = (m:lRD *)Oxdff1BO;
m:lRD Error = 0;
if (strlen (String) > 01)
{

for (i=O;i<Oxffff;i++)
puts (String);
Error = 10;

*dff1BO = i;

if (ParReq != 01) Close_A_Device (ParReq);

exit (Error);
/***************************************************************

main ()

(User) *

***************************************************************/

main ()
{

BYTE *String = HI write this to the Parallel-Port\OlS";

ParReq = (struct IOExtPar *)GetDeviceBlock (PAR LEN);
ParReq->io ParFlags = (UBYTE) PARF SHARED;
Open_A_DevIce ("parallel-device", 01, &ParReq, 01,01);
Do Command (ParReq, (UWORD) PDCMD QUERY);
if-(UBYTE)ParReq->io Status & (UBYTE) IOPTF PSEL)
(UBYTE) IOPTF PSEL)
printf ("Printer OFFLINE or not ready !\n");
else
Parallel Write (ParReq, String, (ULONG)strlen (String;
Close_A_DevIce (ParReq);

The Selected pin (pin 13) of the Centronics port usually indicates
whether or not a printer is connected. If this pin still equals zero after
thirty seconds, the program aborts.

4.3.6

Parallel device error messages

1be following errors can be encountered when using the parallel device:

ParErr_DevBusy

(1) Parallel device busy. Non-functional

ParErr_BufToBig
ParErr InvParam

(2) Read/write buffer too large.

(3) This parameter change not implemented
in this version. Only PARB_ EOFMODE
currently allowed for terminator changes.
(4) Transfer error.
(5) Error occurred when opening the device
(e.g., parallel.device not in the devs
drawer of the SYS disk). Error occurred
during OpenDevice ( ) .

PDCMD_ SETP ARAMS.

ParErr LineErr
ParErr_NotOpen

55

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ParErr_PortReset (6) parall. interface reset.

ParErr_InitErr
(7) Error occwred during paraI1el device
initialization (OpenDevice () ).

4.3.7

Centronics port pin arrangement

Pin
1
2
3
4
5
6
7
8
9
10
11

12
13
14
15
16
17
18
19
20

21
22

23
24
25

ASoo
STROBE
DataO
Datal
Data2
Data3
Data4
DataS
Data6
Data7
ACK
BUSY
POUT
SEL
+5v
NC
RESET

GND
GND
GND
GND
GND
GND
GND
GND
GND

A1000
DRDY
DataO
Datal
Data2
Data3
Data4
DataS
Data6
Data7
ACK
BUSY
POUT
SEL

GND
GND
GND
GND
GND
GND
GND
GND
GND
+5v
NC
RESET

A2000
STROBE

DataO
Datal
Data2
Data3
Data4
DataS
Data6
Data7
ACK
BUSY
POUT
SEL
+5v
NC
RESET

(Paper Out)
(Selected == OnLine)

GND
GND
GND

GND
GND
GND
GND
GND
GND

The Amiga 500 and 2000 require a DB25 male plug for connection to
their parallel ports.

Note:

56

Never use a standard mM printer cable alone on an Amiga 1000. The

Amiga 1000 uses a reverse standard, and inserting such a cable may
destroy your computer. Purchase a gender changer to reverse the
Centronics pinout to normal (the Amiga 1000 parallel port accepts a
DB25 Wnalc connector. Connect the gender changer to the Arniga 1000
parallel port, then connect a standard IBM printer cable to the exposed
end of the gender changer.

4.4 THE SERIAL DEVICE

ABACUS

4.4

The serial device

The serial device allows access to the serial interface of the Amiga. A
few device blocks also exist here:
Offset

Structure
struct lOExtSer
{

o
48
52
56
60
64
68
76
77
78
79
80
82

OxOO
Ox30
Ox34
Ox38
Ox3c
Ox40
Ox44
Ox4c
Ox4d
Ox4e
Ox4f
Ox50
Ox52

struct lOStdReq lOSer;

ULONG
io CtlChar; /* transfer protocol */
ULONG
io-RBufLen; /* Read buffer size */
ULONG
io-ExtFlags;/* unused */
ULONG
io-Baud;
/* Baud rate */
ULONG
io-BrkTime; /* Break time */
struct lOTArray io-TermArray;/* Terminators */
UBYTE
io-ReadLen; /* 7 or 8 Bits */
UBYTE
iO-WriteLen;/* 7 or 8 Bits */
BYTE
io-StopBits;/* 0, 1, 2 */
BYTE
io-SerFlaqs;/* see SetParams */
UWORD
io-Status; /* see Query * /
/* defined in "devices/serial.h" */

Notice the tenninator array (see Section 4.1). This array also consists
of eight bytes or two long words:
Offset

Structure
struct lOTArray
(

o Oxoo
4
8

Ox04
Ox08

ULONG TermArrayO;
ULONG TermArrayl;
/* defined in "devices/serial-h" */

Now we come to the commands which the serial device understands:

MD RESET

(I)

CMD
CMD
CMD
CMD
CMD

(2)
(3)
(6)
(1)
(8)

READ
WRITE
STOP
START
FLUSH

resets device to post-OpenDevice ()

status (including TermArray)
reads data
writes data
stops reading/writing
continue read/write operation
ignores existing read/write commands

57

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

In addition there are three device specific commands:

SDCMD_QUERY
SDCMD BREAK
SDCMD SETPARAMS

4.4.1

(9)

finds out port status

(10)
(11)

sets parameters

stops ttansfer

Opening the serial device

The following code easily opens the serial device:
struct IOExtSer *SerReq = OL;
'define SER_LEN (ULONG) sizeof(struct IOExtSer)

If another program already has access to the serial device, you won't be
able to access it at that time. The serial device offers the option of
sharing the device between users:
struct IOExtSer *SerReq = OL;
'define SER LEN (ULONG) sizeof(struct IOExtSer)
VOID *GetDeviceBlock();
SerReq = (struct IOExtSer *) GetDeviceBlock(SER LEN);
SerReq->io SerFlags = (UBYTE) SERB SHARED;
oPen A Device
(nserial.device n , OL, &SerReq, OL, OLl;
- -

SERB_SHARED has the value 32 (like PARB_SHARED for the parallel

device). Be sure that you declare the GetDeviceBlock () as a
function with a pointer as the return value. Otherwise the result
executes an extension of a long word (ext.l dO). This interrupts the
serial device.

4.4.2

Reading and writing serial device data

The standard commands CMD_READ and CMD_WRITE allow you to
read and write through the serial device:
1***************************************************** **********
*
*
*
* Compile-Info:
* cc Ser_Support.c

58

Ser Support. c
August 1988
(c) Bruno Jennrich

*
*
*

*
*

4.4 THE SERIAL DEVICE

ABACUS

****************************************************** *********1

iinclude "exec/types.h"
'include "exec/io.h"
iinclude "devices/serial.h"
1***************************************************************

*
* Function: Read data

Serial_Read 0

(Ser_Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
*
* SerReq: Device-Block
*
* Data: Data buffer
*
* Len:
Amount of data to be read
*

***************************************************************/

VOID Serial Read (SerReq, Data, Len)

struct IOExtSer *SerReq;
APTR
Data;
ULONG
Len;
{

SerReq->IOSer.io_Data = Data;
SerReq->IOSer.io Length = Len;
Do_Corrmand (SerReq, (UWORD) CMD_READ);
}

1****************************************************** *********
*
Serial Write()
(Ser Support)*
* Function: Write data
*

*--------------------------------------------------------------*
* Input - Parameter:
*
* SerReq: Device-Block
*
* Data: Data to be written
*
* Len:
Amount of data to be written
*
***************************************************************/

VOID Serial Write (SerReq, Data, Len)

struct lOExtSer
*SerReq;
APTR
Data;
ULONG
Len;
{

SerReq->IOSer.io_Data = Data;
SerReq->IOSer.io Length = Len;
Do_Command (SerReq, (UWORD) CMD_WRlTE);

These two commands require the address of the data to be sent, or the
address of the buffer to which the data should be written, as well as the
number of bytes to be transferred. If you enter a value of -1 for Len,
the serial device writes data until it encounters a null byte. The serial
device writes this null byte and stops writing data.
When reading you must determine whether io_TermArray is used.
The serial device reads data until a character from the TermArray is
received. When the serial device encounters a null byte during reading,
the reading process stops.

Note:

The above functions use the DolO () command for command

execution. It could be as important to work with SendIO ( ) ,
CheckIO () and Wait IO () to implement longer transfer time, when
much data is sent

S9

4.

DEVICES

4.4.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Serial device parameters

When reading about serial interfaces, you'll see many buzz phrases like
transfer protocol, word length, baud rate and stop bits. The serial device
allows you to set your own serial interface parameters. Let's take a
closer look at these parameters.

Transfer
protocols

Serial uansfer reads and writes data one bit at a time. An error occmring
during this transfer is quite possible. In parallel uansfer (one byte at a
time instead of one bit at a time), the odds of errors increase eight
times. Serial ttansfer offers the programmer many different transfer
protocols. These protocols allow a "re-take" of anincorrecdy transferred
byte.
The serial device currently supports the XOn/XOff transfer protocol.
XOn/XOff is the default protocol (after OpenDevice ( unless the
SERB_XDISABLED bit (bit 7) is set (bit 7 = 128). It is turned off
when SerReq->io_SerFlags = SERB_XDISABLED. Control
characters, which allow control over XOn/XOff uansfer, are determined
by SerReq-> _io_CtlChar. Like TermArray, this element
consists of a ULONG which can read the ASCII codes from characters:
Bits 31-24 test the xOn character, and bits 23-16 detennine the XOff
character. Bits 15-8 should take the INQ character, while bits 7-0
should be used for the ACK character. The INQ and ACK (handshaking)
are not cwrendy supported by the serial device.

Bits

The number of bits per byte that you want to send or receive also
direcdy affect the transfer protocol. You have the option of sending 7 or
8 bits (SerReq->io_WriteLen) or receiving 7 or 8 bits
(SerReq->io_ReadLen). A stop bit follows the seventh or eight
bit This stop bit marks the end of the transferred value. Seven bits are
most often used to send and receive ASCII codes. The ASCII codes here
have the values 0 to Oxf. You can increase the number of stop bits to 2
to further ensure data security when you are sending seven bits.
(SerReq->io_StopBit = (BYTE) 2).

Baud rate

In addition to the transfer protocol we must detennine the speed at

which the data should be transferred. The baud rale specifies the nwnber
of bits uansferred per second. The Amiga can handle serial transfer from
112 baud (bits per second) to 292,000 baud (bits per second). Insert
your baud rate in SerReq->io_Baud. The normal minimwn setting
is 110 baud; the Amiga can only process a minimum of 112 baud
because of its hardware design.

60

4.4 THE SERIAL DEVICE

ABACUS

Break

When you want to interrupt the data transfer you rnust send a break
signal. The break signal ensures that all of the connections are set to
zero for a specific amount of tirne. The time that the connections
should be in the low condition can be specified in microseconds in
SerReq->io_BrkTime. The SDCMD_BREAK command sends the
break signal. You rnust be sure that the same parameters exist on both
the receiver's side and the sender's side, otherwise the transfer will not
interact.

Buffers

The Amiga also rnanages sorne software based parameters. The serial
device also controls one of the Arniga's own read buffers. Normally this
buffer is 512 bytes. If you need a larger buffer, you can specify the new
buffer length in SerReq->io_RBufLen. You rnust then execute
SDCMD SETPARAMS. First the new buffer is allocated and the data
that was previously stored in the old buffer is lost. All of the
parameters that were changed are first given to the serial device after
SDCMD SETPARAMS.

Terminators

It is the same with a change of the terminators. You sirnply specify the
eight (or less) new terminators that end a read command (Len = -1) and
set the EOFMODE flag in SerReq->io_SerFlag. The terminators
are used after SDCMD SETPARAMS. You should make sure that the
only parameter change during a read or write operation is the change to
the SERB_XDISABLED parameter. Any other changes abort transfer
with an error.

Flags

The serial device includes a set of flags that can control data transfer.
Here are the flags and what they do:

SERB PARTY_ON

(1):

Checks parity of bits received.

SERB_PARTY_ODD

(2):

Checks for odd parity (total of the digits

parity is used.

SERB 7WiRE

1). If this bit is clear, even

(4):
When set before OpenDevice (), seven-wire cornrnunication
becomes active. Normal data transfer uses three lines:
TXD (fRANSMIT DATA)
RXD (RECEIVE DATA)
GND (GROUND)

Seven-wire handshaking adds four wires for a total of seven lines:

61

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

TXD (TRANSMIT DATA)

RXD (RECEIVE DATA)
GND (GROUND)
RTS (REQUEST TO SEND)
CTS (CLEAR TO SEND)
DSR (DATA SET READY)
OCD (DATA CARRIER DETECT).

SERB_QUEUEDBRK

(8):

Controls enqueued break commands. The queue is an area of memory

into which serial output is stored and ttansmitted. The queue operates
on a fIrst in, fIrst out (or FIFO) basis. If the SERB_QUEUEDBRK bit
is set, the system executes the current serial output commands
sequentially, ending with the break command (SDCMD_BREAK). If this
bit is cleared (default state), the break has fIrst priority over any other
serial output waiting in the queue. Once the break command executes,
the interrupted request continues execution, unless the user aborts the
request This flag may be set with SDCMD_ SETPARAMS.

SERB_RAD_BOOGIE

(16):

Controls high-speed mode. If this bit is set, parity check is disabled,

XOn/XOff protocol is disabled, SERB_XDISABLED is set and the
system consistently sends eight-bit data. Some external devices such as
MIDI equipment require high-speed data transfer.

SERB SHARED

(32):
Controls sharing the serial interface with other users. This flag can
only be set before OpenDevice (), or Open_A_Device ().

SERB EOFMODE

(64):
Controls io_TerrnArray and IORequest usage. Setting this flag
instructs the serial device to verify characters against io TerrnArray,
and instructs the serial device to end IORequest as soon as the device
detects and end of file character. This flag may be set without
SDCMD_SETPARAMS to activate and deactivate the established
terminators.

SERB XDISABLED

(128):

Disables XOn/XOff protocol. It is enabled after OpenDevice () .

SDCMD_SETPARAMS is consistently used to indicate a parameter
change for the serial device.

62

4.4 THE SERIAL DEVICE

ABACUS

4.4.4

Reading serial interface status

The following command sequence displays the status of the serial

device:
Do_ Conrnand (SerReq,

Status

(UWORD) SDCMD_QUERY) ;
SerReq->io_Status;

Calling Do_Command (SerReq, (UWORD) SDCMD_QUERY)

returns the stablS of the serial interface in SerReq->io_Status:

= 0:

Bit 0

BUSY
no transfer
Paper out
Paper is present
ONLINE
OFFLINE
Data Set Ready
= 1: No data
= 0: Clear To Send
= 1: Not clear
= 0: Carrier Detect (carrier signal present)
= 1: No carrier
= 0: Ready To Send
= 1: Not ready
= 0: Data Terminal Ready
= 1: Not ready
= 1: Read Buffer Overrun (Read buffer full)
= 0: No overrun
= 1: Break Sent
= 0: No break
= 1: Break received
= 0: No break
= 1: Transmit XOFFed (xOff sent)
= 0: No XOFF
= 1: Received XOFFed (xOff received)
= 0: No XOFF
Unused

= 1:
= 0:
= 1:
= 0:
= 1:
= 0:

Bit 1
Bit 2
Bit 3
Bit 4
Bit 5
Bit 6
Bit 7
Bit 8
Bit 9
Bit 10
Bit 11
Bit 12
Bits 13-15

In addition to checking the status word. you have the option of

checking the variable SerReq->IOSer. iO_Flags. The most
important conditions are saved here:
IOSERF
IOSERF
IOSERF
IOSERF
IOSERF
IOSERF
IOSERF

OVERRUN
WRITEBREAK
RFADBRFAK
XOFEWRITE
XOFFREAD
ACl'IVE
AOORT

(1)
(2)
(4)
(8)

(16)
(32)
(32)

Read buffer ovemm

Break sent
Break received
XOff written
XOff received
Read or write access executing
AhortIO () executed

63

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GmDE

(64)
IOSERF BUFRFAD

Read/write announced but not executed

(anodler read/write already active)
(128) Data read from the internal buffer

As you see, bit four (32) appeAlI's twice. This mayor may not be an
error, which makes it hard to determine which bit stands for which
condition. Avoid checking the iO_Flags variable, and go direcdy
over the SDCMD_QUERY and io_Status instead.

4.4.5

Serial device error messages

Serial device errors occur easily during the initial phases of developing
serial access programs. The following list describes the standard serial
device errors you may encounter:
SerErr_ DevBusy
SerErr Bauctti.smatch
SerErr InvBaucl
SerErr BuffErr

Reading or writing in process.

SETPARAMS cannot be executed
(2) Baud rates of sender and receiver do
not match
(3) Baud rate less than 112 and more
than 292,000 baud
(4) Internal buffer size is less than 512
bytes or too large (insufficient
(1)

(5)
(6)

SerErr_ NotOpen
SerErr PortReset
SerErr_ParityErr
SerErr lnitErr
SerErr TineErr
SerErr_ BufOlTerflow
SerErr Nd)sr
SerErr NoCTS
SerErr DetectedBzeak

64

(7)
(8)
(9)

(10)
(11)

(12)
(13)
(14)
(15)

memory)
Parameter change not allowed

Tmnsfer error (possibly defective

connection)
Cannot find serial. device
Intezface reset
Parity error in transfer
Device initialization error
Error in io_BrkTime
Read butTer overflow
No Data Set Ready signal
No Clear To Send signal
Break detected

4.4 THB SUIAL DEVICB

ABACUS

4.4.6

Serial port pins

Pin
1
2
3
4
5
6
7
S

ASOO

Al000

A2000

GND

GND

GND

(Ground)

TXD

TXD

TXD

RXD

RXD

RXD

RTS
CTS
DSR

RTS
CTS
DSR

RTS
CTS
DSR

(Transmit Data)
(Receive DaIa)
(Request To Send)
(Clear To Send)
(Data Set Ready)

GND

GND

GND

DCD

DCD

DCD

+12v
-12v
AUDO

NC

+12v
-12v
AUDO

(GroInI)
(Data Ouriet Defect

[receive carrier signal])

9
10
11
12
13
14
IS
16
17
IS
19
20
21
22
23
24
2S

--

---AUDI

-DTR
-RI
---

----

---

-Sv
AUOO
AUDI
EB
INI'2*

---

--

--

DTR
+Sv

+12v
C2*
RESB*

(Audio 0u1pUl)

(Audio 0u1pUl)
(Audio Input)
- - (716 KHz Takt)
AUDI (External interrupt [IRQ])
DTR

-RI

(Data Tenninal Ready)

(Ring Indicator)

--

- - (3.SSMHz)
- - (But'fmoJd reset)

To conclude here is a layout for a null modem cable to connect two

computers over the serial interface. and a short application fOJ' using the
null modem cable.
Null modem
cable

The connector used with Amiga serial pon is a DB2S (2S-pin)

connector. The Amiga lOOO uses a DB2S male connector. while the
Amiga 500 and 2000 accept a DB2S female conneetOJ'. This is
important when you go into an electronics store to get partS fOJ' the
null modem cable. The RS-232 connection is crossed in the null
modem cable. as shown in the following table:

65

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Null modem cable connections

Pin

ComDuter A

ColllDuter B

Pin

GND
TXD
RXD

GND
RXD
TXD

1
3
2

DCD
DCD

8
8

DTR

20

20

RTS
CTS
DSR
DTR

DCD

DSR
RTS

GND

GND

6
4
7

DCD

CTS

3
4

S
6

Connect pin 2 of one connector with pin 3 of the other connector, and
soon.

4.4.7

A serial device application

The following program transfers data between two computers using the
null modern cable described in Section 4.4.6.
1***************************************************** **********

*
*

Ser.c
August 1988
(c) Bruno Jennrich

*
*

* Function: Access serial interface

*
***************************************************************/

/***************************************************************
* Compile-Info:
*

* cc Ser
*
* In Ser.o Ser Support.o -Devs Support.o -lc
*
***************************************************************/
tinclude "exec/types.h"
iinclude "exec/io.h"
'include "devices/serial.h"
struct IOExtSer *SerReq;
tdefine SER_LEN (ULONG) sizeof (struct IOExtSer)
/***************************************************************
CloseIt()
(User) *
*

* Function: In case of error, close everything

*--------------------------------------------------------------*
66

ABACUS

4.4 THE SERIAL DEVICE

* Input - Parameter:

*
*

* String: Error-Message

***************************************************************/

VOID closeIt (String)

char
*String;
{

UWORD i;
UWORD *dff180 = (UWORD *)Oxdff180;
UWORD Error = 0;
if (strlen (String) > 01)
{

for (i=O;i<Oxffff;i++)
puts (String);
Error = 10;

*dff180

i;

if (SerReq != 01) Close A Device (SerReq);

exit (Error);

1***************************************************** **********

main ()

*
*--------------------------------------------------------------*

*
*

Input - Parameter:

* When arge > 1 => read data

* When arge == 0 0> write data

*
*

****************************************************** *********1

main (argc,argv)
UWORD arge;
BYTE
*argv[];
(

BYTE Buffer(256);
Open_A_Deviee ("serial.device",Ol,&SerReq,Ol,SER_LEN);
i f (arge > 1)
{

Serial Read (SerReq,Buffer,-l);

printf- ("'s \n", Buffer);
else
Serial Write (SerReq,"HELLO",-l);
Close A Device (SerReq);

Call the program with any command parameter (e.g., Ser x) on the
receiving Amiga. This Amiga waits until data is received. Remove the
disk from the drive and place it in the sending Amiga. Start the
program without command parameters (enter Ser) and watch the result:
The text sent appears on the receiving computer's screen.

67

4. DEVICES

4.5

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The printer device

The printer device allows access to a printer. The printer device has
three different types of access:
Text

CMD_WRITE (3) & PRD_RAWWRITE (9)

Command

PRD_PRTCOMMAND (10)

Hardcopy

PRD_DUMPRPORT (11)

These three task regions of the printer device use three different device
blocks. The printer commands and hardcopy access have their own
special device blocks:
Offset

Structure

--------

struct IOPrtCmdReq /* Command Request */

{

0
20
24
28
30
31
32
34
35
36
37
38

OxOO
Ox14
Ox18
Oxlc
Oxle
Oxlf
Ox20
Ox22
Ox23
Ox24
Ox25
Ox26

Offset

struct Message io_Message;

struct Device *io_Device;
struct Unit
*io_Unit;
UWORD
io Command;
/*
UBYTE
io=Flags;
BYTE
io Error;
io-PrtCommand; 1*
UWORD
io-ParmO;
UBYTE
/*
UBYTE
io=Parml;
UBYTE
io Parm2;
io-Parm3;
UBYTE
1* defined in "devices/printer.h"

PRO_PRTCOMMAND */
printer command *1
Parameter *1

*1

Structure

-------struct IODRPReq 1* DumpRastPort Request */

{

0
20
24
28
30
31
32
36
40
44
46
48
50
52
56
60
62

68

OxOO
Ox14
Ox18
Oxlc
Oxle
Oxlf
Ox20
Ox24
Ox28
Ox2c
Ox2e
Ox30
Ox32
Ox34
Ox38
Ox3c
Ox3e

struct Message
io_Message;
struct Device
*io Device;
struct Unit
*io=Unit;
UWORD
io Command;
1* PRO]RTCOMMANO *1
io -Flags;
UBYTE
BYTE
io=Error;
struct RastPort *io RastPort; 1* Graphic RastPort*1
struct ColorMap *io=colorMap; 1* color table */
ULONG
io_Modes;
1* ViewPort Modes *1
UWORD
io SrcX;
1* Start point *1
io-SrcY;
UWORD
UWORD
io-SrcWidth; 1* width *1
UWORD
io-SrcHeight;l* Height *1
LONG
io-DestCols; 1* print width *1
LONG
iO-DestRows; 1* print height *1
UWORD
iO-Special; 1* Special Flags */
1* defined in "devices/printer. h" */

4.5 THE PRINTER DEVICE

ABACUS

The following routine allows open access to all three device blocks
through the Normal. DumpRastPort and Command pointers:
struct IODRPReq
*PrtPtr = OL; /* Dummy pointer */
struct IOStdReq
*Normal;
struct IODRPReq
*DumpRastPort;
struct IOPrtCmciReq *Command;
'define PRT LEN (ULONG) sizeof (struct IODRPReq)/*larger block*/
Open A Device ("printer. device", OL, &PrtPtr, OL, PRT_LEN);
Normil(struct IOStdReq *)PrtPtr;
DumpRastPort
(struct IODRPReq *)PrtPtr;
Command
= (struct IOPrtCmciReq *)PrtPtr;

4.5.1

Printing escape sequences

You can send your texts to the printer with the PRD_RAWWRITE
command. The escape sequences are not replaced (see CMD_ WRI TE)
What you specified. as the output string. is also output:
/***************************************************************

Printer_RawWrite()

(Printer_Support) *

*
*

* Function: Display data

*
*--------------------------------------------------------------*
* Input - Parameter:
*
* PrtReq: Device-Block (Normal)
String to be displayed
* Data:
* Len:
Number of characters to be displayed

***************************************************************/

Printer RawWrite (PrtReq, Data, Len)

struct IOStdReq *PrtReq;
APTR
Data;
ULONG
Len;
(

PrtReq->io Data
= Data;
PrtReq->io-Length = Len;
Do_command-(PrtReq, (UWORD) PRD_RAWWRITE);

4.5.2

Amiga printer escape sequences

The Amiga can take a standard set of printer escape sequences and
translate them for most printers. using the available printer drivers. The
following table lists the escape sequences that the Amiga understands;
their command numbers; the standard printer escape sequences; and their
meanings.

69

4. DEVICES

Printer Escape
Sequences

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Command
name
aRIS
aRIN
aIND
aNEL
aRI

Command
number
OL
IL
2L
3L
4L

aSGRO
aSGR3
aSGR23
aSGR4
aSGR24
aSGRl
aSGR22
aSFC

5L
6L
7L
8L
9L
lOL
llL
12L

aSBC

13L

aSHORPO
aSHORP2
aSHORPl
aSHORP3
aSHORP6
aSHORPS
aDEN6
aDENS
aDEN4
aDEN3
aDEN2
aDENt
aSUS2
aSUSt
aPLU
aPLD

14L
lSL
16L
t8L
19L
20L
21L
22L
23L
24L
2SL
26L
27L
28L
32L
33L
34L
3SL
36L
37L
38L
39L
40L
41L

aFNTO
aFNTl
aFNT2

aFNT3
aFNT4
aFNTS
aFNT6
aFNT7

70

Escape

Meaning

~uence

ESCc
ESC#l
ESCD
ESCE
ESCM
ESCIOm
ESC[3m
ESC[23m
ESC[4m
ESC[24m
ESC[lm
ESC[22m
ESC[30mESC139m
ESC[40mESC49m
ESCrOw
ESC[2w
ESC[1w
ESC13w
ESC[6w
ESqSw
ESCr6"z
ESC[S"z
ESC[4"z
ESCj3"z
ESC[2"z
ESCjl"z
ESC[2v
ESC[lv
ESCL
ESCK
ESCiB
ESCiR
ESC(K
ESC(A
ESC(E
ESCiH
ESC(Y
ESC(Z

Reset
Initializing
Linefeed
LF=CR+LF
Reverse linefeed
Normal character set
Italics on
Italics off
Underline on
Underline off
Boldon
Bold off
Set
foreground color
Set
background color
Normal type
Elite on
Elite off
Condensed off
Expandedprint on
Expanded print off
Shaded print on
ShadedJ:!int off
Double-strike on
Double-strike off
NLQon
NLQoff
Superscript on
Supersc~t off
Superscript (half step)
Subscript {half stejJl
US character set
French character set
German character set
English character set
Danish character set 1
Swedish character set
Italian character set
Spanish character set

4.5

ABACUS

Printer Escape
Sequences

Command
aFNT8
aFNT9
aFNTlO
aPROn
aPROPO
aTSS
aJFY5
aJFY7
aJFY6
aJFY3
aJFYI
aVERPO
aVERPI
aSLPP
aPERF
aPERFO
aLMS
aRMS
aTMS
aBMS
aS1BM

Command
number
42L
43L
44L
45L
47L
48L
49L
SOL
51L
53L
54L
55L
56L
57L
58L
59L
60L
61L
62L
63L
64L

aSLRM

65L

aCAM
aHTS
aVTS
a1BCO
a1BC3
a1BCI
a1BC4
a1BCALL
aTBSALL
aEXTEND

66L
67L
68L
69L
70L
71L
72L
73L
74L
75L

name

THE PRINTER DEVICE

Escape

Meaning

ESC(J
ESC(6
ESC(C

J
characteJ"set
Norweftian characteJ" sa
Danish character set 2
~rtional text on
Proportional text off

ESC~

ESC(Op
ESC~nE

Pro~onal~aces=n

ESC[5 F
ESC[7 F
ESC[6 F
ESC[3 F
ESC[1 F
ESCIOz
ESC[lz
ESCjnt
ESC[nQ
ESC(Oq
ESC#9
ESC#O
ESC#8
ESC#2
ESC[Pnlr
ESC[Pn2r
ESC[Pnls
ESC[Pn2s
ESC#3
ESCH
ESC]
ESC[Og
ESC13jt
ESC[1g
ESCl4R
ESC#4
ESC#5
ESCIPn"x

Left justification
Ri&.htiustification
Block characters on
Adjust characteJ" width
Centering
Line~cil!K 1/S"
Line spacing 1/6"
Setj:)age lel!Kthl!!l
Pa/ite break (n>O)
Page break
Set left margin
Set right mar...&!n
Set page header
Set page footer
Set top (nl) and
bonom{n21 mar~s
Set left (nl) and
right (n2) margins
Clear all mar~ns
Horizontal tabs
Vertical tabs
Clear horizontal tab
Clear all horiz. tabs
Clear vertical tab
Clear all venical tabs
Clear all tabs
Set default tabs
Extended font

You can see the advantage of using this table. If someone wants to
write a text that contains underlined superscripts, the word processor
only needs to send the command "ESC[4m" for underline and "ESC[2v"
for superscripts. It's the same, no matteJ" what printer you're using. The
corresponding printer driver contains a similar table that has the printer
specific escape sequences.

71

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The eighth entry of the sequence in this table is "ESC-I" (Star NL-lO).
The printer device replaces "ESC[4m" with "ESC-I" and the following
text is underlined. This functions only when you use the CMD_ WRI TE
command instead of the PRD_RAWWRITE command:
/***************************************************************

Printer Write ()

(Printer Support) *

* Function: output data (Convert Escape-Sequences)

*
*--------------------------------------------------------------*
* Input - Parameter:
*

*
*
*

* PrtReq: Device-Block (Normal)

* Data:
* Len:

String to be output
Number of characters to be output

******************************************************.********/

Printer Write
(PrtReq, Data, Len)
struct IOStdReq *PrtReq;
APTR
Data;
ULONG
Len;
(

PrtReq->io Data
Data;
PrtReq->iO-Length = Len;
Do_Comrnand-(PrtReq, (UWORD) CMD_WRITE);

There is no substitution with the RAWWRITE command.

4.5.3

Printer commands
You can use these escape sequences as printer commands. When escape
sequences contain only parameters (e.g., setting the left and right
margins), no simple substitution can be made. A routine in the printer
driver processes the irreplaceable escape sequences. This routine can be
accessed directly with the command PRD_PRT COMMAND:
1***************************************************** **********

Printer_Command()

(Printer_Support) *

* Function: Execute printer command

*
*

*--------------------------------------------------------------*

* Input - Parameter:
*
* PrtReq: Device-Block
* Command: command
* PI-P4:
Parameter

*
*
*

****************************************************** *********1

Printer Command
(PrtReq,Command,PO,Pl,P2,P3)
struct IOPrtCmdReq *PrtReq;
UWORD
Corrrnand;
UBYTE
PO, Pl,P2, P3;

72

4.5 THE PRINTER DEVICE

ABACUS

PrtReq->io PrtCommand = Command;

PrtReq->io-ParmO = PO;
PrtReq->io-Parml = Pl;
PrtReq->io=Parm2 = P2;
PrtReq->io Parm3 = P3;
DO_Command-(PrtReq, (UWORD) PRD_PRTCOMMAND);

Here is a short example. To establish the left and right margins, you
can call:
Printer Command (PrtReq, 651, (BYTE) 2, (BYTE) 78, (BYTE) 0,
(BYTE) 0);

You can also replace the number 651 with the command name aSLRM.
The ParmO-Parm4 variables specify the printer driver routines.

4.5.4

Hardcopy
The PRD_ DUMPRPORT command provides the developer with an easy
method of printing a screen to the printer.
There are a few parameters you must provide when accessing
PRD DUMPPORT:
1.)
2.)
3.)

4.)

5.)

6.)

7.)

DestRows and
DestCols

The RastPort which contains the graphic to be printed.

The ColorMap which contains the graphic's colors (this is
especially important when using color printers).
The ViewPort mode variables so that the printer knows the
graphic's current display mode (HI-RES, LACE, HAM, etc.).
The upper left comer of the area to be printed (SrcX, SrcY).
The height and width of the area to be printed (SrcHeight,
SrcWidth). This allows you to print any rectangular section
of the screen (Src = Source = <=> RastPort).
The size of the hardcopy as it should appear on the printer
(DestRows,DestCols)(Dest = Destination <=>
Printer).
The io_Special flag should be set to zero.

The DestRows and DestCols parameters can be set in a number of

ways. Here are some examples.
DestCols>O
DestRows>O

73

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The above configuration prints a graphic DestRows rows high and

DestCols columns wide.
DestCols=O
DestRows>O

The above configuration prints a graphic as wide as the paper and

DestRows rows high.
DestCols=O
DestRows=O

The above configuration prints a graphic as wide as the paper and as

high as the paper.
DestCols>O
DestRows=O

The above configuration prints a graphic DestCols columns wide,

with the height proportional to the width.
DestCols<O
DestRows>O

The above configuration enlarges or reduces the size of the printed

graphic. The equation for computing this is as follows:
IDestColsl
- - - - - = enlargement factor
DestRows

For example, if DestCols has a value of -1 and DestRows has a

value of 4, the enlargement/reduction factor is equal to 1/4. This value
only applies to DestCols and DestRows if io_Special is zero.
The following lines describe the individual Special_Flags and
their tasks in the printing process:
SPECIAL_MILCOLS Ox001L
SPECIAL MILROWS Ox002L
SPECIAL FULLCOLS Ox004L
SPECIAL FULLROWS Ox008L
SPECIAL FRACCOLS Ox010L
SPECIAL FRACROWS Ox020L
SPECIAL_ASPECT Ox080L
SPECIAL
SPECIAL
SPECIAL
SPECIAL
SPECIAL

74

DENSITYl OxlOOL
DENSITY2 Ox200L
DENSITY3 Ox300L
DENSITY4 Ox400L
CENTER Ox040L

DestCols given in l/1000

DestRows given in 1/1000
DestCols set at maximum
DestRows set at maximum
Width = maximum/DestRows
Height = maximum/DestRows
If set, either height or width
changes to preserve page set up
Print density (1=low; 4=high)

Center graphic

4.5 THE PRINTER DEVICE

ABACUS

Maximum
printable area

The printer driver contains the width and height of the maximum
printable area. You get page setups from these two maxima
(MaximaX/MaximaY), reserved through Special_Aspect.
/***************************************************************
(Printer_Support) *
*
*
*
* Function: Hardcopy
*

*--------------------------------------------------------------*
* Input - Parameter:
*

* PrtPtr:
* RastPort:
* ColorMap:
* Modes:
* SrcX,SrcY:
* SrcWidth,
* SrcHeight:
* DestCols:
* DestRows:
* Special:

Device-Block
RastPort of the graphic to be printed
ColorMap contains the actual colors
Display modes
Top left corner of graphic to be printed

Width and height of the graphic to be printed

Number of columns (Printer)
Number of lines
(Printer)
Special-Flags

*
*

*
*
*

*
*

*
*

*
*
***************************************************************/
VOID Printer Dump (PrtPtr,RastPort,ColorMap,Modes,SrcX,SrcY,
SrcWidth,SrcHeight,DestCols,DestRows,Special)
struct IODRPReq
*PrtPt r;
struct RastPort
*RastPort;
struct ColorMap
*ColorMap;
ULONG
Modes;
UWORD
SrcX,SrcY;
UWORD
SrcWidth,SrcHeight;
LONG
DestCols,DestRows;
UWORD
Special;
{

PrtPtr->io RastPort
PrtPtr->io=ColorMap
PrtPtr->io Modes
PrtPtr->io SrcX
PrtPtr->io SrcY
PrtPtr->io SrcWidth
PrtPtr->io=SrcHeight
PrtPtr->io DestCols
PrtPtr->io-DestRows
PrtPtr->io_Special

=
=

RastPort;
ColorMap;
Modes;
SrcX;
SrcY;
SrcWidth;
SrcHeight;
DestCols;
DestRows;
Special;

1* Viewmodes *1
1* Start point *1
1* Width *1
1* Height *1
1* Print width */
/* Print height */
/* Special-Flags */

Do Command (PrtPtr, (UWORD) PRD_DUMPRPORT);

The following program uses the Dump routine to print a section of the
current window. You must select the section using the mouse.
Combine the previous printer support routines to make the
Printer_SupporLc file. Don't forget the include files in the
Printecsuppport.c file.

7S

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

1***************************************************** **********

*
*
*

Prt.c
August 1988
(c) Bruno Jennrieh

*
*
*

* Function: Hardcopy of the current Window

***************************************************************/
1***************************************************** **********

* Compile-Info:

* cc Prt
* In Prt.o Printer Support.o Devs Support.o -lc

*
*

***************************************************************/

tinclude "exec/types.h"
ftinclude "exec/io.h"
/tinel ude "devices/printer. hOI
iinclude "intuition/intuitionbase.h"
/tinclude "intuition/intuition.h"
tinclude "graphics/gfxbase.h"
tinclude "graphics/view.h"
union PrinterIO
(
/* Printer Blocke */
struct IOStdReq
Normal;
stroct IODRPReq
DumpRastPort;
stroct IOPrtCmdReq Conmand;
);

union PrinterIO
PrtReq;
stroct IODRPReq
*PrtPtr = 01;
stroct IOStdReq
*Normal;
struct IODRPReq
*DumpRastPort;
struct IOPrtCmdReq *Corrunand;
idefine PRT_LEN (ULONG) sizeof (struct IODRPReq)
stroct IntuitionBase *IntuitionBase = OL;
stroct Window
*Window = OL;
struct GfxBase
*GfxBase = OL:
VOID *OpenLibrary();
/***************************************************************

closelt ()

*
*

(User) *

* Function: In case of error close everything

*
*

*--------------------------------------------------------------*
* Input-Parameter:

*
*

* String: Error-Message

***************************************************************/

VOID CloseIt (String)

char
*String;
{

UWORD i;
UWORD *dff18D
(UWORD *)Oxdff180;
UWORD Error = 0;
if (strlen (String) > 01)
{

for (i=O;i<Oxffff;i++)
puts (String);
Error = 10;
if (PrtPtr != 01)

76

*dff180

i;

Close A Device (PrtPtr);

4.5

ABACUS

THE PRINTER DEVICE

if (IntuitionBase =- 01) CloseLibrary (IntuitionBase);

if (GfxBase == 01)
CloseLibrary (GfxBase);
exit (Error);
1***************************************************** **********

Mark_PrintArea ()

(User) *

*
*
* Function: Choose section for hardcopy
*
*--------------------------------------------------------------*
* Input-Parameter:

* Window: Address of the window to be printed

* xl,yl,x2,y2: later contains the upper left and lower
*
corner of the area to be printed

*
*

***************************************************************/

Mark_PrintArea (Window, xl, yl, x2, y2)

struct Window *Window;
ULONG
*xl, *yl, *x2, *y2;
{

UBYTE *LeftMouse = (UBYTE *)OxbfeOOl;

ULONG xold,yold;
*xl
*yl
*x2
*y2

(ULONG)
(ULONG)
(ULONG)
(ULONG)

0;
0;
0;
0;

SetDrMd (Window->RPort,COMPLEMENT);
while *LeftMouse
*xl
*yl

&

(UBYTE)Ox40)

(UBYTE) Ox40);

(ULONG)Window->MouseX;
(ULONG)Window->MouseY;

xold
yold
Move
Draw
Draw
Draw
Draw

*xl;
*yl;
(Window->RPort,*xl,*yl);
(Window->RPort,xold,*yl);
(Window->RPort,xold,yold);
(Window->RPort,*xl,yold);
(Window->RPort,*xl,*yl);

while *LeftMouse & (UBYTE)Ox40)

/* first rectangle */

(UBYTE) OxO)

*x2 = (ULONG)Window->MouseX;
*y2
(ULONG)Window->MouseY;
i f *x2 != xold) II

(*y2 ! = yold))

Move
Rectangle */
Draw
Draw
Draw
Draw

(Window->RPort,*xl,*yl);

Move
Draw
Draw
Draw
Draw

(Window->RPort,*xl,*yl);
(Window->RPort,*x2,*yl);
(Wlndow->RPort,*x2,*y2);
(Window->RPort,*xl,*y2);
(Window->RPort,*xl,*yl);

/* Rubberband-

(Window->RPort,xold,*yl);
(Window->RPort,xold,yold);
(Window->RPort,*xl,yold);
(Window->RPort,*xl,*yl);

77

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

xold
yold
Move
Draw
Draw
Draw
Draw

*x2;
*y2;

(Window->RPort,*xl,*yl);
(Window->RPort,xold,*yl);
(Window->RPort,xold,yold);
(Window->RPort,*xl,yold);
(Window->RPort,*xl,*yl);

1* erase rectangle */

SetDrMd (Window->RPort,JAM2);
i f (*xl > *x2)
{

xold
*xl;
*xl = *x2;
*x2 = xold;
i f (*yl > *y2)
(

yold
*yl;
*yl = *y2;
*y2 = yold;
1***************************************************** *******
*
main ()
(User) *
*
*
* May have to change SPECIAL_DENSITYl depending on quality *

* supported by your printer

****************************************************** ******1

main 0
{

ULONG xl,yl,x2,y2;
if IntuitionBase = (struct IntuitionBase *)
OpenLibrary (n intuition. library" ,OL) )
(struct
IntuitionBase *) 01)
CloseIt ("No Intuition !! !"):
if GfxBase = (struct GfxBase *)
OpenLibrary ("graphics library" , OL) )
(struct GfxBase
*) 01)
CloseIt ("No Graphics!!! ");
Window = IntuitionBase->ActiveWindow;
Mark_PrintArea (Window,&xl,&yl,&x2,&y2);
Open A Device (nprinter.device",OL,&PrtPtr,OL,PRT LEN);
Normal(struct IOStdReq *) PrtPtr;
DumpRastPort = (struct IODRPReq *)PrtPtr;
Command
= (struct IOPrtCmdReq *)PrtPtr:
Printer_Dump (DumpRastPort,
Window->RPort,
GfxBase->ActiView->ViewPort->ColorMap,
(ULONG) GfxBase->ActiView->ViewPort->Modes,
(UWORD) xl,
(UWORD) yl,
(UWORD) (x2-xl),
(tJWORD) (y2-yl),
(ULONG) (x2-xl),
(ULONG) (y2-yl),
(UWORD)SPECIAL DENSITYl);
CloseLibrary (GfxBase);
CloseLibrary (IntuitionBase);
Close_A_Device (PrtPtr);

78

4.5 THE PRINTER DEVICE

ABACUS

4.5.5

Printer device error messages

The printer device contains the following messages:

fdefine PDERR NOERR 0

No error~verything OK

fdefine PDERR CANCEL 1

Printer operation interrupted (AbortIO ()

fdefine PDERR NOTGRAPHICS 2

Printer does not support graphics

fdefine PDERR INVERTHAM 3

You cannot print inverted HAM pictures (Kick1.l and Kick1.2 only)

fdefine PDERR BADDlMENSION 4

Invalid print size

fdefine PDERR DlMENSIONOVFLOW 5

Too large a print size chosen (Kickl.l and Kick1.2 only)

fdefine PDERR INTERNALMEMORY 6

Insufficient memory present for internal variables

fdefine PDERR BUFFERMEMORY 7

Insufficient memory for printer driver to allocate printer buffer
These errors are returned in the i
blocks.

4.5.6

E r ro r variable of the device

The printer device under Kickstart 1.3

Printer drivers are much faster under Kickstart 1.3. Kickstart 1.3 also
provides a new command for the printer device: the P RD _QUERY
command (fdefine PRO QUERY 12), which returns the current
printer port status. You mayremember other forms of this command
from the parallel and serial devices. This way the port to which the
printer is connected (Le., Preferences) is the port that is chosen. To get
the status, you must enter two UBYTES or one UWORO and give the
address of these words to the io_Data pointer:

79

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

UWORD Status;
PrtReq->io_Data

(APTR) 'Status

The status stands in this UWORD after the call of the PRD _QUERY
f;Ommand (Do_Command (PrtReq, (UWORD) PRD_QUERY). The
entire UWORD is needed for the serial printer, while the parallel printer
needs only the lower byte (bits 0-7) of the UWORD to reserve the StablS.
With that you know how you must interpret the status returned in
Act u a l . You can tell if it is being handled as a serial
i
(io-Actual == 2) (X' a parallel pinter (io Actual =- 1). The
sectiOns on the serial and parallel devices indicare the meanings of these
bits.

In addition to the new command, there are some new flags:

'define SPECIAL DENSITY5 Ox0500
'define SPECIAL DENSITY6 Ox0600
'define SPECIAL=DENSITY5 Ox0700

You can now select seven print densities instead of four, if the printer
supports these.
'define SPECIAL NOFORMFEED OxOBOO

A page oriented printer (e.g., laser printers or friction feed printers)

usually executes a formfeed after printing a page. This ensures that you
only print one graphic to a sheet of paper. When you set this flag, no
formfeed is executed.
Idefine SPECIAL_TRUSTME OxlOOO

The printer is usually reset after a hardcopy. To print multiple graphics

on the same page, you must instruct the computer not to reset after a
hardcopy by setting the SPECIAL_TRUSTME flag.
'define SPECIAL NOPRINT Ox2000

This flag stops the printer from printing. This may seem silly-why
open the printer device and then print nothing? Remember that the
printer driver calculates the size of the hardcopy based on the data you
placed in io_DestCols, io_YDotslnch, etc. The size of the
hardcopy on the printer then passes to the variables io_DestCols
and iO_DestRows. io_DestCols and io_DestRows contain the
number of columns and lines needed to create the hardcopy. Using the
SPECIAL_NOPRINT flag can then test, for example, if the hardcopy
can be printed in the desired size, or if some parameters need changing.

80

4.6

ABACUS

4.6

THE KEYBOARD DEVICE

The keyboard device

The keyboard device allows direct reading of the keyboard. The keyboard
device uses the following commands:
KBD READEVENT

(10)

KBD READMATRIX

(11)

CMD CLEAR

(5)

prepares keyboard input as an input

event SU'UCture
reads staluS of all keys (pressed or not
JXeSSed)
clears keyboard buffez

The keyboard device also features reset handler routines:

(12)
(13)
(14)

inserts reset handler

removes reset handler
informs user that a reset
routine has been executed

Of these commands. the only command that currently works is the

KBD READEVENT command. All of the other commands return error
messages that say that the command is not implemented (-Oxfc). This
means that the input task checks this device and does not allow any
other users. Regardless. we1l discuss all of the commands.

4.6.1

Opening the keyboard device

The keyboard device uses a standard request block. The following code
opens access to the device:
struct IOStdReq *KeyRequest = OL;
'define KEY_LEN (ULONG) sizeof (struct IOStdReq)
Open A Device("keyboard.device", OL, &KeyRequest, OL,

KEY_LEN);-

81

4.

DEVICES

4.6.2

ADVANCED SYSTEM PROGRAMMERS GUIDE

Reading the keyboard device

As mentioned above, you have two options for viewing the keyboard
status. The first consists of allowing the input device to fill an input
structure, which you can examine:
1***************************************************** **********
KeyBoard_ReadEvent ()
(Key_Support) *

*
*

* Function: Read KeyBoard-Event

* Input - Parameter:
*
* GamePortRequest:
GamePort-Device-Block
* Type:
Controller-Type

*--------------------------------------------------------------*

*
*

***************************************************************/
VOID KeyBoard ReadEvent (KeyRequest,InputEvent)
struct IOStdReq
*KeyRequest;
struct InputEvent
* InputEvent;
{

KeyRequest->io Data
= (APTR) InputEvent;
KeyRequest->io-Length = (ULONG) sizeof (struct InputEvent);
Do Command (KeyRequest, (UWORD) KBD_READEVENT);

The second option consists of reading the status of all of the keys (this
second option is currently not implemented, but may be added soon).
The address of a byte array is frrst given to the iO_Data pointer of the
device block. This array will later contain the status of every key on the
keyboard. Each bit of this array represents one key (bit = 0 => key not
pressed).

The first byte contains the status for the keys coded 0-7. the second
contains the status for the keys coded 8-15, and so on. You must
specify the number of bytes ofthe array in i 0_Lengt h to execute the
KDB_READMATRIX command. Then the array fills with the status of
each key.
1***************************************************** **********
KeyBoard_ReadMatrix ()
(Key_Support) *

*
*

* Function: Read key statsu

*--------------------------------------------------------------*
* Input - Parameter:

* KeyRequest: Device-Block
* Array:
Byte-Array for Status
* Len:
Size of arrays

*
*
*
*

***************************************************************/
VOID KeyBoard ReadMatrix (KeyRequest,Array, Len)
struct IOStdReq
*KeyRequest;
APTR
Array;

82

4.6 THE KEYBOARD DEVICE

ABACUS

ULONG

Len;

KeyRequest->io Data

(APTR) Array;

KeYRequest->io~Length = Len;

Do_Command (KeyRequest, (UWORD)KBD_READMATRIX);

4.6.3

Resets through the keyboard device

The keyboard device has provisions for executing system reset routines.
These routines execute when the user presses the <Ctrl><left
Amiga><right Amiga> keys. These routines may close open files
when a reset occurs.

The resets
routine

This routine is installed through an interrupt structure whose

is_Code (program code) and is_Data (data) elements are initialized.
This interrupt structure is given in the iO_Data pointer of the device
block, where the i 0 _ Len g t h variable of the value s i z e 0 f
(struct interrupt) is. Then the KBD_ADDRESETHANDLER
command is called:
struct Interrupt OwnReset
OwnReset.is Code = YourOwnRoutine;
OwnReset.is=Data = YourOwnData;
KeyReq->io Data
= (APTR) OwnReset;
KeyReq->iO_Length = (ULONG) sizeof(struct Interrupt);
Do_Command (KeyReq, (UWORD) KBD_ADDRESETHANDLER);

Unfortunately, this command is not implemented. You may be able to

crash the system by accessing this command, which requires powering
down on most of the Amiga models.
KBD_REMRESETHANDLER works to some extent With the help of
this command the reset handler should be removed shortly before the
end of a program. The variables that must be initialized are the same as
those used by KBD_ADDRESETHANDLER.

The last command, which the keyboard device completely supports at

this time, is the KBD _RESETHANDLERDONE command. This
command must be called after the execution of a reset routine.
KBD_RESETHANDLERDONE infonns the system that the reset handler
has been completely processed and the reset can be continued. We don't
know if this command functions-we were never able to install a reset

handler.

83

4.

ADVANCED SYSTEM PROGRAMMERS GUIDE

DEVICES

4.6.4

A keyboard device application

The following program reads the input events from the keyboard and
displays the key code of the pressed key (ie_Code). Combine the two
keyboard support routines and the include files listed in the folowing
program to make the Key_Support.c file.
1***************************************************** **********

Key.c
(c) Bruno Jennrich

*
*

***************************************************************/
/***************************************************************

* Compile-Info:
* cc Key.c
* ln Key.o Key Support.o Devs Support.o -lc

*
*
*

****************************************************** *********1

flinclude "exec/types.h"
'include "exec/io.h"
'include "exec/devices.h"
'include "devices/inputevent.h"
'include "devices/keyboard.h"
struct InputEvent Event;
struct IOStdReq *KeyRequest=Ol;
'define KEY LEN (ULONG) sizeof (struct IOStdReq)
/***************************************************************

*
CloseIt ()
* Function: In case of error, close everything

(User) *
*

*--------------------------------------------------------------*

* Input - Parameter:
.. String: Error-Message

*
*

***************************************************************/

VOID Closelt (String)

char
*String;
{

UWORD i;
UWORD *dff180 = (UWORD *)Oxdff180;
UWORD Error = 0;
if (strlen (String) > 01)
{

for (i=O;i<Oxffff;l++)
puts (String);
Error = 10;

*dff180

i;

if (KeyRequest != 01) Close_A_Device (KeyRequest);

exit (Error);
IMinO
{

Open A Device ("keyboard.device",Ol,&KeyRequest,Ol,KEY_LEN);

do - (

KeyBoard ReadEvent (KeyRequest,&Event);

printf (Hie Code: %d\n",Event.ie Code);
while (Event.ie Code != (UWORD) Ox45); 1* Escape */
Close_A_Device (KeyRequest);

84

4.7 THE GAMEPORT DEVICE

ABACUS

4.7

The gameport device

The gameport device accesses any connections to the gameports (e.g.,
mice or joysticks). The gameport device supports the following
commands:
GPO
GPO
GPO
GPO
GPO
CMD

4.7.1

READEVENT
ASKCTYPE
SETCTYPE
ASKTRIGGER
SETTRIGGER
CLEAR

(9)
(10)
(11)
(12)
(13)
(5)

read conttoller status

read conttoller type
set controller type
read announcement status
set announcement conditions
erase gameport buffer

Opening the gameport device

When opening a device you must determine which gameport you want
to check. The uni t parameter of OpenOevice () contains either 0
for gameport 1 or 1 for gameport 2:
'define GP LEN (ULONG) (sizeof(struct IOStdReq
struct IOStdReq
*GamePortRequest = OL;
Open_A_Device("gameport.device", lL, &GamePortRequest, OL,
GP_LENl;
/* lL: GamePort 2 */
C!ose_A_Device(GamePortRequest);

This sequence opens gameport 2 for access. If you want to use both
gameports for a game, you must open the gameport device twice, once
with GamePortRequest = OL and with GamePortRequest =
lL.

Controller
specification

Once OpenOevice executes, you must specify the type of controller

in the gameport. You can select from the following conttoller types:
G?CT KXJSE
G?CT REIJOYSTICK
G?CT AESJOYSTICK

(1)
(2)
(3)

mouse
relative joystick
absolute joystick

If you select GPCT_MOUSE, the system accesses the Amiga mouse in

gameport 2. Do not tty accessing the mouse in gameport 1 through the
input device, because the input device treats the mouse in gameport 1
85

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

as a different device device. You can, however, instruct the input device
to check a joystick instead of a mouse (see Section 4.8-The input
device).

Gameport 1
access

The input device controls gameport 1 until you take over the entire
system through software, or disable the input task. Avoid disabling the
input task, since this can cause problems throughout the system. When
you want to use gameport 1 without disturbing the input task, you can
access it direct over hardware register joyOdat ($dftooa).
The GP _ SETCTYPE command helps you determine which controller
should be checked with OpenDevice (). You only need to give the
following routine the flags GPCT_MOUSE, GPCT_RELJOYSTICK,
and GPCT ABSJOYSTICK:
1***************************************************** **********
GamePort_SetCType()

* Function: Determine controller type

*
*

*--------------------------------------------------------------*
* Input - Parameter:

GamePortRequest:

* Type:

GamePort-Device-Block
Controller-Type

*
*
*
*

***************************************************************/
VOID GamePort SetCType (GamePortRequest,Type)
struct IOStdReq
*GamePortRequest;
UBYTE
Type;
{

GP_Type
= Type;
GamePortRequest->io_Data
= (APTR) &GP_Type;
GamePortRequest->io Length = 11;
Do_Command (GameportRequest, (UWORD)GPD_SETCTYPE);

The address of the variable is given to the gameport device block,

which contains the type to be set. Because this type must be
established as a UBYlE variable, it contains the value lL.

Operating
systems and
controllers

The Amiga's operating system is an ongoing system. Like many

softwarelhardware bases, it has undergone many upgrades and will
probably continue to develop. Later versions of Kickstart may support
other gameport controllers (e.g., a lightpen). Since this new controller
is not supported from the previous Kickstart versions, the program will
probably crash if started from an earlier Kickstart version.
To prevent this, the value -1 is returned for GPDERR_ SETCTYPE for a
controller not supported in the io Error of the gameport device
block. This can be altered to abort ilie program without a crash. The
controllers mouse, Relj oystick, and Abs joystick are all

86

4.7 THE GAMEPORT DEVICE

ABACUS

supported by all versions of Kickstart, so the controller check is

unnecessary for these controllers. The following routine helps you
determine which controllers are connected to the gameport:
1***************************************************** **********
GamePort_AskCType()
(Game Support) *

* Function: Which controller is supported?

*--------------------------------------------------------------*
* Input - Parameter:

* GamePortRequest: GamePort-Device-Block
Address of the bytes, assigned to the
* Type:
controller type
*

*
*

*
*
*

***************************************************************/

VOID GamePort AskCType (GamePortRequest,Type)

struct IOStdReq
*GamePortRequest;
UBYTE
*Type;
{

GamePortRequest->io Data
= (APTR) Type;
GamePortRequest->io-Length = 11;
Do_Command (GamePortRequest, (UWORD)GPD_ASKCTYPE);

Other than the gameport device block, you need the address of the bytes
into which the controller type should be placed. If the value zero
(GPCT_NOCONTROLLER) is returned in Type, you can then use the
gameport for your own controller. The gameport is occupied by another
program when Type == -1 (GPCT_ALLOCATED). When the
value 1,2 or 3 is returned in Type, that means that your program is
being used by the gameport, and the controller that was returned is
supported by the gameport device.

4.7.2

Reading gameport device status

The READEVENT command allows the user to read the gameport device
status.
/***************************************************************

GamePort_ReadEvent()

* Function: Read controller status

(Game_Support) *

*
*

*--------------------------------------------------------------*

* Input - Parameter:

*
*

* GamePortRequest: GamePort-Device-Block
*
* ReadEvent:
Addesse of an InputEvent strukture, in which*
*
the controller status is written
*
***************************************************************/

87

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

VOID GamePort ReadEvent (GamePortRequest,ReadEvent)

struct IOStdReq
*GamePortRequest;
struct InputEvent
*ReadEvent;
{

GamePortRequest->10 Data
- (APTR) ReadEvent;
GameportRequest->1o-Length - (ULONG) (sizeof (struct
InputEvent;
GamePortRequest->10 Command = (UWORD)GPD_READEVENT;
DolO
(GamePortReqUest);

The conb'oller status (e.g., left or right on a joystick) is placed in an

input event structure assigned by you (see Section 4.8).

PeadEvent.ieJX>Sitioo.ie_x and ReadEvent.ieJX>Sitioo.iey
return the conb'oller settings. That differentiates between the three
different controllez types.

When you read the mouse (or a trackball), the two variables listed
above receive the number of steps that the mouse has moved. The faster
you move the mouse, the larger the value. When you move the mouse
up, the Y COOftIinate is negative. When you move the mouse down, the
y coordinate is positive. When you move the mouse left, the X
coordinate is negative, and when you mouse the mouse right. the X

coordinate is positive.

+
Remember that the value given here represents the movement, rather
than the actual position of the mouse pointer. If you want to conb'ol

88

4.7

ABACUS

THE GAME PORT DEVICE

one of your own mouse pointers, you only need to add the values in
ReadEvent. ie_X and ReadEvent. ie_Y (see Section 4.8) to the
position of the mouse pointer.

GPCT_RELJOYSTICK:
When you plug a relative joystick in the gameport, the system returns
the stick status in the form of the numbers -1, 0 and 1. The pattern
given in the figure above represents the negative and positive values.
The center position of the joystick returns a zero to the variables.

GPCT _ABSJOYSTICK:
Movement patterns for the absolute and relative joysticks are the same.
The difference between them is that GPCT_RELJOYSTICK constantly
supplies the position, while GPCT_ABSJOYSTICK only states when
the joystick is brought to a new position.

Mouse and
fire buttons

The ReadEvent structure also comes into play for reading the mouse
buttons on a mouse or the fire button on a joystick. The ie_Code
field describes the status of these buttons. When this element has the
value IECODE LBUTTON (Ox68), either the fire button or the left
mouse key was pressed. The right mouse key is tested through
IECODE_RBUTTON (Ox69). You also have the option of reading the
release of the button by instructing the gameport device through
SETTRIGGER:

/***************************************************************
GamePort_SetTrigger ()
(Game_Support) *

* Function: Set movement trigger

*
*

*--------------------------------------------------------------*
* Input - Parameter:

* GamePortRequest:
* GPT:

*
*

GamePort-Device-Block
*
GamePortTrigger-Structure, which determines*
when
the
movement
message
mshould
be
sent
*
*
and if the keypress or release of the key *
*
should be announced
*
*
***************************************************************/
VOID GamePort_SetTrigger (GamePortRequest,GPT)
struct IOStdReq
*GamePortRequest;
struct GamePortTrigger
*GPT;
{

GamePortRequest->io_Data
(APTR) GPT;
GamePortRequest->io_Length = (ULONG) (sizeof (struct
GamePortTrigger;
Do_Command (GamePortRequest, (UWORD)GPD_SETTRIGGER);

Don't let the comments in this routine confuse you: the factors in this
function primarily control mouse movement (more on this later).

89

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

Keypresses

The given GamePort Trigger structure helps you determine whether

one key was pressed (GPTF _DOWNKEYS = OxOl), one key was
released (GPTF_UPKEYS
Ox02) or both keys were released
(GPTF_UPKEYS+GPTF_DOWNKEYS = Ox03). This determination
occurs through the Keys element
This Key s element is not the only element of the
GameportTrigger structure:
Offset

o
2
4
6
8

DxDD
DxD2
DxD4
DxD6
DxD8

Structure
-------struct GamePortTrigger
{/* defined in "devices/gameport. h" * /
UWORD gpt_Keys;
UWORD gpt TimeOut;
UWORD gpt=XDelta;
UWORD gpt_YDelta;

Timeout states the number of vertical blanks that should be sent from
the gameport device between ReadEvents (60 per second). XDelta
and YDel t a state after how many pulses of the controller a
ReadEvent should be created. This only works when using a mouse
as an input device. The mouse contains two shafts fitted with wheels,
and the wheels have holes drilled in them. When the mouse changes
position, the holes interrupt a light source. The gameport checks for
this light change.
These pulses are added together. When the sum of the values exceeds
the values given in XDel ta and YDel ta, the mouse pointer moves
to point XDelta and YDelta. When you give the value 1 for
XDel ta and YDel ta, the mouse pointer moves the fastest. This
means that you need less room on your desk to move the pointer from
the upper left corner of the screen to the lower right corner of the

screen.
Preferences

Preferences program also allows the user to set the mouse speed. The
mouse speed assigned after every boot operation is an input device
routine which accesses the gameport device.
How does Prefer~nces know which values to set for the mouse speed?
GamePort_AskTrigger reads the GamePort Trigger of the
corresponding gameport:
/***************************************************************

GamePort_AskTrigger()

(Game_Support) *

Function: Which condition makes sence for the controller

*
*

Input - Parameter:

*
*

GPT:

*--------------------------------------------------------------*
* GamePortRequest: GamePort-Device-Block

90

Address of the GamePortTrigger structure

ABACUS

4.7 THE GAME PORT DEVICE

to be filled

(see SetTrigger)

***************************************************************/

VOID GamePort AskTrigger (GamePortRequest,GPT)

struet IOStdReq
*GamePortRequest;
struet GamePortTrigger
*GPT;
(

GamePortRequest->io_Data
(APTR) GPT;
GamePortRequest->io Length
(ULONG) (sizeof (struet
GamePortTrigger;
Do_Command (GamePortRequest, (UWORD)GPD_ASKTRIGGER);

This routine fills the GamePortTrigger function that was given by

you with the trigger values of the corresponding gameport, which you
can then read.

4.7.3

A gameport device application

The following program checks a mouse in gameport 2. Left mouse
button key presses are displayed; pressing the right mouse button ends
the program. When you move the mouse, the position change is
displayed on the screen. The faster you move the mouse, the larger the
displayed value. Combine the game support routines to make the
Game_Support.c file. Include the devs/gameport.h and
devslinputevent.h files in the Game_Suppport.c file.
/***************************************************************

GamePort.e
(e) Bruno Jennrieh
August 1988

*
*

*
*

****************************************************** *********1
1***************************************************** **********

* Compile-Info:
*
* ee GamePort
* In GamePort.o Game Support.o Devs Support.o -lc

*
*
*
*

***************************************************************/

lIinclude
lIinclude
#include
lIinclude
#include
#include

"exeelrYpes.h"
"exec1memory.h"
"exec/io.h"
"exec/devices.h"
"devices/inputevent.h"
"devices/gameport.h"

#define GP_LEN (ULONG)

(sizeof (struct IOStdReq

struct IOStdReq
*GamePortRequest=O;
struct GamePortTrigger GPT;
struct InputEvent
ReadEvent;

91

4.

ADVANCED SYSTEM PROGRAMMER'S GmDE

DEVICES

/***************************************************************

CloseIt()
(User) *
* Function: In case of an error, release structure and memory *

*--------------------------------------------------------------*
* Input - Parameter:
* String: Error-Message

*
*

****************************************************** *********1

VOID Closelt(String)
UBYTE
*String;
{

UWORD *dff180 = (UWORD *)Oxdff180;

UWORD i;
UWORD Error;
Error = 0;
if (strlen (String) > 0)
{

for (i=O;i<Oxffff;i++) *dff180

Error = 10;

i;

puts (String);
if (GamePortRequest != 0) Close A Device (GamePortRequest);
exit (Error);
/***************************************************************

The_GamePort_DeviceO

(User)*

* Function: Use GamePort device

*
*

***************************************************************/

The GamePort Device()

(-

Open A Device
("gamep-;;rt. device" , 11, &GamePortRequest, 01, GP LEN);
printf (" Please put mouse in second GamePort!\n");
printf (" right mouse key == end of program\n");
GamePort_SetCType (GamePortRequest, (UBYTE)GPCT_MOUSE);
GPT.gpt Keys
= (UWORD) (GPTF UPKEYS+GPTF DOWNKEYS);
/* Annoui;"ce both * /
GPT.gpt_Timeout
(UWORD) 0;
GPT.gpt XDelta
(UWORD) 1;
GPT.gpt=YDelta
(UWORD) 1;
GamePort_SetTrigger (GamePortRequest,&GPT);
ReadEvent.ie Code = 0;
while (ReadEvent. ie_Code != IECODE_RBUTTON)
{

if (ReadEvent.ie Code
IECODE_LBUTTON) printf ("Left
Button\n");
if (ReadEvent.ie_Code
printf ("Left Button released\n");
GamePort~eadEvent (GamePortRequest,&ReadEvent);
printf ("x: %d\n y: %d\n",ReadEvent.ie X,ReadEvent.ie Y);
Do_Command (GamePortRequest, (UWORD)CMD=CLEAR);
GamePort SetCType (GamePortRequest, (UBYTE) GPCT NOCONTROLLER);
Close A Device (GamePortRequest);
lII3.inO
{

92

4.8 THE INPUT DEVICE

ABACUS

4.8

The input device

The input device is based to some degree on the keyboard device and the
garneport device (see Sections 4.6 and 4.7). The input device supports
the following commands:

IND ADDHANDLER
IND REMHANDLER
IND WRITEEVENT

(9)

IND
IND
IND
IND
IND

(12)
(13)
(14)
(15)
(16)

SETTHRESH
SETPERIOD
SETMPORT
SETMTYPE
SETMTRIG

(10)
(11)

insert own input handler

remove own handler
send input event to all other input
device usetS
set time trigger for repeat function
determine repeat speed
determine mouse port
determine mouse port controller
determine mouse port controller trigger

These commands are defined in "devices/input. h". In addition to

the device commands, the input device supports the following common
commands:

4.8.1

CMD RESET

(1)

CMD CLEAR

(5)

CMD STOP
CMD START

(6)
(7)

reset input device without disabling

handler
clear input buffer: suppress all
previously sent input events and those
not yet processed by the handler
stop input device
start input device

Opening and closing the Input device

The input device must be opened before access, using the
Open_A_Device () function:
'define INPUT LEN (ULONG) (sizeof(struct IOStdReq))
struct IOStdR~q *InputRequest;
Open_A_Device("input.device", OL, &InputRequest, OL,
INPUT_LEN) ;

93

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

After access the device must be closed again, using the

Close_A_Device () function, as usual:
Close A Device (InputRequest);

4.8.2

Accessing the Input device

No READ command exists for the input device. But how can we receive
key presses from the input device and process them? The key phrase
here is input handler. The input task calls an input handler which
controls all of the keypresses and mouse movements. This handler
receives an input event structure that was created from the input task.
The input event structure looks like this:
Offset:

o
4
5
6
8

Oxoo
Ox04
Ox05
Ox06
Ox08

Structure:
struct InputEvent
{/* defined in "devices/inputevent.h" * /
struct InputEvent *ie NextEvent;
UBYTE
ie -Class;
UBYTE
ie=SubClass;
UWORD
ie Code;
UWORD
ie=Qualifier;
union
{

struct
{

10 OxOA

12 OxOC
10 OxOA
14 OxOE
22 Ox16

WORD
WORD
ie_xy;
APTR
ieJ>osition;
struct timeval

Let's take a closer look at this structure. The variable i e Cl ass

contains the result type, which the input event structure contains. The
following input event classes exist:
IECIASS NULL
IECIASS RAWKEY
IECIASS RAWIDJSE
IECIASS EVENT
IECIASS POINTERPOS
!! !IFCIASS
IECIASS TIMER
IECIASS GADGE'IDCWN
IECIASS Gl\DGE'lUP
IECIASS_ RECPEST

94

(OxOO)
(OxOl)
(Ox02)
(Ox03)
(Ox04)
(Ox05)
(Ox06)
(Ox07)
(Ox08)
(Ox09)

NOP input event

keyboard code
mouse movement
internal event
mouse position
does not existl
timer event
gadget clicked on
gadget released
requester now displayed

4.8 THE INPUT DEVICE

ABACUS

IEX::lASS MENULIST
IEX::lASS_ CIDSEWINDCJf
IEX::lASS_SIZEMNXlf
IEX::lASS_ REF'RESHIr.[N[)
IEX::lASS NEJiPREFS
IEX::lASS DISI<REMJIlED
IEX::lASS DISKINSERTED
IEx:::IASS ACTIV9lINIXIi
IEOASS_INACI':IVEMNIXJi

(OxOA)
(OxOB)
(OxOC)
(OxOD)
(OxOE)
(OxOF)
(OXI0)
(Ox11)
(OxI2)

menu clicked on
window close gadget clicked
window resized
window refreshed
new PrefeteneeS

disk removed
disk inserted
window activated
winOOw deactivated

Let's examine each input event and how ie_Class interprets them:

IBCLASS Nu11
A NOP input event. Data from the event has no meaning.
IBCLASS RAWItBY
Places the keyboard code of the pressed key in ie_Code (not the
ASCU code). i e _ Qu ali fie r contains the status of the <Ctrl>,
<Shift> and <Alt> keys:
(Oxoool)
(OxOOO2)
~I~RSHIE"l'
IEQlALlFIER_ CAPSIro<
(OxOOO4)
IEQlALlFIER_ <XNmOL
(OxOOO8)
IEQlALlFIER_ IALT
(Oxool0)
(OxOO2O)
~ER_RALT
(Ox0040)
~ER_I.CX:MWID
(Ox0080)
~_RXMWID
IEQlALlFIER_ NtH:RICPAD
(OxOloo)
IEQlALlFIER_ REPFAT
(Ox02OO)
(Ox04OO)
~IER_INl'ERRllPT
~ER_M.JLTIBRONX'AST (OxOSOO)
(Ox 1000)
~IER_IaJTI'CN
(0x2000)
~IER_RElJTlXN
(Ox4000)
~ER_MEUI'TCN
~IER_

LSHIE"l'

(Ox8000)

left <Shift> key

right <Shift> key
enable <Caps lock>
<Ctr!> key
left <Alt> key
right <Alt> key
left <Amiga> key
right <Amiga> key
numeric keypad key
key repeated

m
m

left mouse button

right mouse button
middle button (does
not exist)
relative mouse
position message

When the bit is set, the <Shift>, <Alt> or <Ctr!> key was also pressed
as well as the key in ie_Code. The illustration shows the layout of
the key codes. The numbers on the keys are equal to the value retwned
in ie_Code. The two input events are sent from the input device
when one key is pressed. The keypress and the release of the key are
two separate events. You can differentiate the two input events because
the high value bit (bit 7 = Ox80) is set in actual keyboard code
(ie_Code) when the key is released (lOCMP flag: RAWKEY).

95

4. DEVICES

96

ADVANCED SYSTEM PROGRAMMER'S GUIDE

4.8

ABACUS

THE INPUT DEVICE

IECLASS_RAWMOOSE
Returns a mouse movement to ie_x and iey. These two variables
are part of a union. Here are two macros to allow you to move the
mouse in the X or Y direction without entering input event
ieyosi tion. ie_x time after time:
4define ie_X ie-position.ie_x;
4define ie_Y ie-position.ie_y;

Now it is possible to access the movement change over input event

ie_X to the X coordinate. The IDCMP flag DELTAMOVE must be set
in the current win<iow so that the input task of this event can be sent.

IECLASS EVENT
An internal event of the input device. It is a necessary part of keeping
the system informed of changes to the current input window.
ie_Code has the value IECODE_ NEWACTIVE (OxOl).
IECLASS POINTERPOS
The absolute mouse position as placed in ie_X and ie_Yo This event
functions only when the IDCMP flag MOUSEMOVE is set for the
current window.
IECLASS TIMER
Places the current system time in timeval. This event comes from
the input task every 60th of a second (IDCMP flag: INTUITICKS).
IECLASS GADGETDOWN
Places the address of a clicked gadget in ie_Posi tion. ie_addr.
This event functions only when the IDCMP flag GADGETDOWN is set
for the current window. System gadgets like the front gadget
(WINDOW-TO-FRONT) or the back gadget (WINDOW-TO-BACK)
cannot be checked.
IECLASS GADGETUP
Places the address of a released gadget in ieyosition. ie_addr.
This event functions only when the IDCMP flag GADGETUP is set for
the current window.
IECLASS_REQOESTER
Sent when a requester is represented in the current window.
IECODE_REQSET (OxOl) is in ie_Code with the requester
encountered first. When another one is encountered without the ftrst
requester disappearing, this event is no longer sent.
When all of the requesters have disappeared, another input event is sent.
This time the value I ECODE_REQCLEAR (OxOO) is given in

97

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ie_Code. To receive this input event. the IDCMP flag REQCLEAR

andlor REQSET must be set.

IECLASS MENULIST
Places the code of the menu selected from the current window in
i e _ Code. This event functions only when the IDCMP flag
MENUP I CK is set for the current window.
IECLASS CLOSEWINDOW
Sent when the user clicks on the close gadget of the current window.
This event functions only when the IDCMP flag CLOSEWINDOW is
set for the current window.
IECLASS SIZEWINDOW
Sent when the size of the current window changes. This event functions
only when the IDCMP flag NEWSIZE is set for the current window.
IECLASS REFRESHWINDOW
Sent when the current window should be refreshed. This event functions
only when the IDCMP flag REFRESHWINDOW is set for the current
window.
IECLASS NEWPREFS
Sent when new preferences are present due to changes from the
Preferences program (IDCMP flag: NEWPREFS).
IECLASS_DISKREMOVED
Sent when the user removes a disk from a disk drive (IDCMP flag:
DISKREMOVED).
IECLASS DISKINSERTED
Sent when the user inserts a disk in a disk drive (IDCMP flag:
DISKINSERTED).
IECLASS ACTIVEWINDOW
Makes the window most recently clicked the active window.
IECLASS INACTIVEWINDOW
Deactivates the currently active window.

Intuition and
the input
device

Many of the input/output functions used in Intuition are controlled

through the input device, and must be passed on to your Intuition
window. Now let's write a routine that will let you view the events
sent by the input task. We'll start by creating an input handler using
the IND ADDHANDLER device command:
ULONG User_Routine;
VOID
Input_Code();
struct Interrupt Input_Handler;

98

4.8 THE INPUT DEVICE

ABACUS

/***************************************************************

(Input_Support) *

Input_AddHandler()

*
*

* Function: Add own C handler in input handler

*
*--------------------------------------------------------------*
* Input - Parameter:
*
*
*
* InputRequest: Input-Device-Block
*
* Handler:
Address of your own handler routine (C)
*
* Data:
Address of data area for handler routine
*
****************************************************** *********1

VOID Input AddHandler (InputRequest, Handler, Data)

struct IOStdReq
*InputRequest;
VOID
*Handler;
APTR
Data;
{

User Routine
Input Handler.is Data
Input-Handler.ls-Code
Input=Handler.is=Node.ln_Pri

(ULONG) Handler;

= Data;
=
=

(VOID
51;

(*)

(Input_Code;

InputRequest->io Data
= (APTR)&Input Handler;
Do_Command(InputRequest, (UWORD) IND_ADDHANDLER);

This routine specifies the device block with which the device was
opened (or a copy of the original device block). Then the routine gives
the address of the handler routine that was written in C. You also have
the option of specifying a range of memory for use by your handler
routine (e.g., for variables).
Unfortunately the input task is not in the position to call C routines,
because the parameters are passed in the stack in C. The input task
gives the parameters (input event and data region) in the hardware
registers. For this reason, we must switch to an interface that moves
the parameters from the hardware register onto the stack, and then call
the C program. We have developed a short machine language routine
for this purpose:
/***************************************************************

_Input_Code.asm

(Input_Support) *

*
*
*--------------------------------------------------------------*
* Input - Parameter:
*
*
*
*
* Function: Call Input-Handler Routine (C-Routine)

* AO: Pointer to Input-Event

AI: pointer to your own data

*--------------------------------------------------------------*

* Return values:

* DO: Contains the Input-Event to process further

*
*

****************************************************** *********1

lIasm
public geta4
public =Input_Code

99

4. DEVICES

Anv ANCED SYSTEM PROGRAMMER'S GUIDE

_Input_Code:
move.l
a4,-(sp)
jsr
geta4
movem.l ~O/al,-(sp) ; parameter auf Stack
move.l
jsr
movem.l
move.l
rts
ilendasm

User Routine,aO
(aO) (sp)+,aO/al
(sp)+,a4

Because the Aztec compiler accesses program variables through

hardware register A4, this register must be re-initialized before each call
of the C handler routine. This :is done here using the routine geta4,
which transfers the variables' basis address according to A4. The
initialization of register A4 must occur because register A4 contains
another value during the input handler processing. This register should
return to its old value when leaving the handler. The parameter can be
brought to the stack after initialization of register A4, and the C routine
can be recalled.
This machine language routine is given as the actual input handler in
Input_AddHandler () . For this an interrupt structure is stored
whose is Code field is loaded with the address of the machine
language routine, and whose is _ Da ta field is loaded with the address
of the memory range. We set the priority of our handler higher than
that of the system input handler, so that we get all of the input events
that the input task creates first. The priority of the system input handler
is 50, and the priority of our handler is 51.
Then the initialized interrupt structure can be given in our input device
block (io_Data), and the IND_ADDHANDLER command is sent.
Remember not to use any variables named Input_Handler and
User_Routine, just in case you want to use the above program.
InputHandler is the intemJpt structure, over which the machine
language segment Input_Code is called. User_Routine contains
the address of the C routine that was called, and which the input handler
should process. When you want to exit a program that has installed an
input handler, you must remove the input handler again. This is done
with the following code.
/***************************************************************

Input_RemHandler()

* Function: Disable Input-Handler

(Input_Support) *

*
*

*---------------------------_._---------------------------------*
* Input - Parameter:
*
*
*

InputRequest: Input-Device-Block

*****************************w*********************************/

100

4.8

ABACUS

THE INPUT DEVICE

VOID Input_RemHandler (InputRequest)

struct IOStdReq
* InputRequest;
(

InputRequest->io Data
= (APTR) 'Input Handler;
Do_Command (InputRequest, (UWORD)IND_REMHANDLER);

These two routines give you the infonnation needed to write a macro
recorder that registers all of the encountered input events. Here's the
code for just such a recorder. Combine all the input support routines
presented in this section to make the InpucSupportc me. The header
for the InpucSupport.c file is presented at the end of this section.
1***************************************************** **********

*
*

Recorder.c
August 1988
(c) Bruno Jennrich

*
*

***************************************************************/

/***************************************************************

*
*

Compile-Info:
cc Recorder
In Recorder.o Input Support.o Devs iSupport.o -lc

************** *** ***

*,*

lIinclude "exec/types. h"

lIinclude "exec/memory.h"
llinclude "exec/interrupts.h"
Unclude "exec/nodes. h"
Unclude "devices/input.h"
lIinclude "devices/inputevent.h"
VOID *AllocMem();
VOID *Open () ;
ULONG User Routine;
1006L
'define MODE NEWFILE
IIdefine INPUT LEN
(ULONG) (sizeof (struct IOStdReq
#define RECORD SIZE
50001
IIdefine INEV LEN
ULONG) (sizeof (struct InputEvent)
IIdefine MEMTYPE
(MEMF_CHIP I MEMF_CLEAR)
ULONG HowMuchEvents;
ULONG ActualEvents;
800L End;
UWORD *FileHandle=Ol;
struct InputEvent *Recorder=Ol;
struct IOStdReq
*InputRequest = 01;
struct InputEvent *Pointer;
/***************************************************************

* Function:

CloseIt ()
(User) *
Release all occupied memory and structures
*

*--------------------------------------------------------------*

* Input - Parameter:
* String: Error-Message

*
*

***************************************************************/

Closelt (String)
BYTE
*String;
(

UWORD *dff180
(UWORD *)Oxdff180;
UWORD i;
UWORD Error;
Error = 0;
if (strlen (String) > 0)
(

101

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

for (1-0; i<Oxffff; i++) *dfflBO

Error = 10;

i;

puts (String);
i f (FileHandle != 0)
Clo:se (FlleHandle);
i f (InputRequest != 01) Clo:se_A_Device (InputRequest);
if (Recorder ! = 0)
Frel~Mem
(Recorder,HowMuchEvents*INEV U,N);
exit (Error);
1***************************************************** **********

C_Handler ()

(User) *

* Function: Handles InputEvent:s of the Input-Task

*----------------------------_._--------------------------------*
* Input - Parameter:
* Input: InputEvent
* Data: Pointer to data

* Return value:
* InputEvent, that should be processed further.

*
*

*
*---------------------------------------------------------------*
******************************,r********************************/

struct InputEvent *C_Handler(Input,Data)

struct InputEvent
*Input;
ULONG
*Data;
{

i f (!End)
{

if (Input->ie_Class == IECI.Jl,SS_RAWKEY)
{

i f (Input->ie Code == Ox45) End = TRUE;

else
if (*Data < HowMuchEvents)

/* Escape */

Pointer
= &Recorder[*Datal:
/* InputEvent */
Pointer->ie NextEvent
0;
Pointer->ie-Class
Input->ie Class;
Pointer->ie SubClass
Input->ie-SubClass;
Pointer->ie-Code
Input->ie -Code;
Pointer->ie-Qualifier
Input->ie=Qualifier;
Pointer->ie-TimeStamp.tv secs
Input>ie TimeStamp. tv secs;
Pointer-=>ie TimeStamp. tv micro
Input>ie TimeStamp. tv micro;
*Data+=l;
else End = TRUE;
return (Input);
1***************************************************** **********

Input _Device ()

* Function: Use InputDevice

(User) *

*
*

****************************************************** *********1

Input_Device ()
{

Open_A_Device ("input. device" , 01, &InputRequest, 01, INPUT_LEN);

End = FALSE;
ActualEvents

102

0;

-------------------------------------------------------4.8 THE INPUT DEVICE

ABACUS

Input_AddHandler (InputRequest,C_Handler,&ActualEvents);
while (!End);

1* wait until end of the line *1

Input RemHandler (InputRequest);

Close-A Device
(InputRequest);

/**********-****************************************************
*
main ()
(User) *

*
*
*
*

* Input - Parameter:
* argv[l]: Name of the Macro File
* argv[2]: Number of events

***************************************************************/
main (argc,argv)
UWORD argc;
BYTE
**argv;
(

i f ( argc !; 3)
{

printf ("USAGE: %s MacroFile How many events\n",argv[O);

CloseIt ( .... );
if HowMuchEvents ; atoi(argv[2] < 0)/* how many events *1
CloseIt ("HowMuchEvents < 0 !! !");
Recorder ; (struct InputEvent *) AllocMem
(HowMuchEvents*INEV_LEN,MEMTYPE);
1* Get memory for events
if (Recorder ;; 01)
CloseIt (nNo Memory for InputEvents !!!");

*1

Input_Device ();
FileHandle; Open (argv[l),MODE_NEWFILE);
if (FileHandle ;; 01)
CloseIt ("Cannot Open MacroFile ! !!");
Write (FileHandle,&ActualEvents,41);
1* save length *1
Write (FileHandle,Recorder,ActualEvents*INEV LEN);
1* save events *1
Close (FileHandle);
FreeMem (Recorder,HowMuchEvents*INEV_LEN);

Program
description

This program first opens the input device. Then the input handler is
installed. This handler calls our C_Handler routine. Only RAWKEY
events are recorded in this C Handl e r routine. Whether it was
recorded or not, the received input event is given in the other input
handler (all of the input handlers like interrupt server are organized in a
list). This happens by simply returning the received input event. The
return () routine writes the address of the received input event in DO
for this. If you place the value 0 in DO, you must remember that the
following handler can no longer be accessed.

103

4.

ADY ANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

Also, remember that input. events can be combined. The

ie_NextEvent array uses one of each input event structures (this
pointer points to the input event's successor). So it can happen that
your input handler only receivl~s the first input event of a long list.
You are free to change this list to insert your own input events. Just
bear in mind that anyone developing an input event handler is
responsible for any problems he/she creates.
Now back to the above program. We have recorded only RAWKEY
events there. With this you can record keypresses that occur while the
program is running (it doesn't matter in which window, as long as no
input handler with a higher priority exists). For this you must give the
maximum number of events that should be recorded. You must also
give the names of files in which these recorded input events should be
stored. A sample call of the program can look like this:
Recorder Macro 100

This program caIl allows you to save up to 50 keypresses to a file

named Macro. You can only record up to 50 key presses because a
keypress consists of depressing and releasing the key. An input event is
sent for each, so one keypress actually counts for two actions. But you
can test bit 7 in ie_Code and if this is clear, the corresponding event
is not recorded.
Pressing the <Esc> key aborts thl~ program-all data up to that point is
saved and the program ends. A macro recorder is worthwhile only if you
can play back the recorded key presses. We can also play back the input
task with the help of this function. We send only input events in the
input handler, from which mOire can be given in the system, for
example the system handler and our own input handler installed with
Input_AddHandler. This function is called WRITEVENT. Add it
to your Input_support.c file, remember to include devices/inputeventh
before compiling.
ftdefine INEV LEN

((ULONG)

(sizeof(struct InputEvent))

/*****************************"*********************************

Input_WriteEvent()
(Input_Support) *
*
*
*
* Function: Givw InputEvent in other Input-Handler again
*
*-----------------------------_._-------------------------------*

Input - Parameter:

*
* InputRequest: Input-Device-Block

Event:

InputEvent to redirect

*
*
*
*

******************************~*********************** *********/

VOID Input_WriteEvent (InputRequest, Event)

struct IOStdReq
* InputRequest;
struct InputEvent
*Event;
{

InputRequest->io_Data

104

(APTR) Event;

4.8

ABACUS

InputRequest->10 Length
InputRequest->io=Flags

THE INPUT DEVICE

INEV LEN;
(UBYTE) 0;

Do Command (InputRequest, (UWORD)IND_WRITEEVENT):

This routine lets you send an input event to all of the present handlers.
If you installed your own handler, this handler also receives your input
event, as long as a handler with a higher priority has not changed the
input events.
Based on the above routine we can actually write a program to play
back the entered keypresses. Our program must open the file created by
the recorder, read the saved number of recorded input events, allocate
memory as needed and load the input events into this allocated memory.
Then these input events only need to be executed by
Input_WriteEvent():
1***************************************************** **********

*
*
*

Play.c
August 1988
(c) Bruno Jennrich

*
*
*

***************************************************************/
/***************************************************************

* Compile-Info:
*
* cc Play
* ln Play.o Input Support.o Devs Support.o -lc

***************************************************************/

#include
iinclude
iinclude
#include
iinclude
iinclude

"exec/types.h"
"exec/memory.h"
"exec/interrupts.h"
"exec/nodes.h"
"devices/input.h"
"devices/inputevent.h"

VOID *Al1ocMem();
VOID *Open () :
#define MODE OLDFILE
1005L
#define INPUT LEN
(ULONG) (sizeof (struct IOStdReq
ide fine RECORD SIZE
50001
#define INEV LEN
ULONG) (sizeof (struct InputEvent))
#define MEMTYPE
(MEMF_CHIP I MEMF_CLEAR)
UWORD
*FileHand1e
01:
struct InputEvent *P1ayer
01:/* Memory for InputEvents */
ULONG
Length
01;/* Niumber of InputEvents */
struct IOStdReq
* InputRequest= 01:
1***************************************************** **********

CloseIt ()

(User) *

* Funktion: In case of erroe, release memory and structures

*
*

*--------------------------------------------------------------*
* Input - Parameter:

* String: Error-String

*
*
*

***************************************************************/

VOID Closelt (String)

lOS

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

BYTE

*String;

UWORD *dfflBO = (UWORD *)OxdfflBO;

UWORD i;
UWORD Error;
Error = 0:
if (strlen (String) > 0)
{

for (i=O:i<Oxffff;i++) *dfflBO

Error = 10;

i:

puts (String);
if (FileHandle != 01)
if (Player != 01)
if (InputRequest !~ 01)

Close (FileHandle);
FreeMem (Player,Length*INEV_LEN);
Close_A_Device (InputRequest);

exit (Error);
/***************************************************************

*
* Input - Parameter:
* argv[l]:
MacroFile

main

(User) *

*
*

*****************************~t*********************** **********/

main (arge,argv)
UWORD argc;
BYTE
**argv;
{

UWORD i;
i f (arge ! = 2)
{

printf ("USAGE: %s MacroFile\n",argv[O]);

CloseIt (n,,);
FileHandle = Open (argv[l],MODE OLDFILE);
if (FileHandle == 0) Closelt ("File does not exist! !! ");
if (Read (FileHandle,&Length,41) != 4)/* Number of events *1
CloseIt ("Read Error ill !!!");
1* Events cannot be *1
1* read
*1
Player = AllocMem (Length*INEV LEN,MEMTYPE);
if (Player == 0) CloseIt ("No Memory!!! ");
1* Memory for Length-Events occupied*/

if (Read (FileHandle,Player,Length*INEV LEN) !=

Length*INEV LEN)
Closelt ("Read-Error #2 ! !!");
Close (FileHandle);
Open_A_Device ("input .devic,e", 01, & InputRequest, 01, INPUT__LEN);
for (i=O;i<Length; i++)
/* rather small cost, isn't It? *1
Input_WriteEvent (InputRequest, &Player[ij):
Close_A_Device (InputRequest.);
FreeMem (Player, Length*INEV__LEN);

106

4.8 THE

ABACUS

INPUT DEVICE

This program shows you how to open and use a device with as little
effort as possible. The program section that sends out the input events
consist of only three functions and a control instruction (for (; ; ) i).
You find the compiled programs Recorder and Play on the optional disk
in the CH - 4 / 4 8 directory. We have also included a macro in this
directory. You can play it back by entering the directory and entering:
Play Macro

4.8.3

The input device, mouse and keyboard

Now let's look at the input device commands which access the mouse
and keyboard. You may want to re-read Section 4.7, since much of the
material concerning the gameport device also applies to the input
device.
This section also examines the similarities between the Preferences
program and the input device.

Setting repeat
speed

The Preferences program offers the option of changing the key repeat
speed. This parameter controls the speed at which a key repeats when
the user presses and holds the key. The key repeat speed is set from
Preferences using slider gadgets. When booting, the system reads the
repeat rate from the devs/ system configuration file and places the
value in IND_SETTHRESH. If you want to change the repeat speed
after booting, you must load the Preferences program, change the repeat
speed and exit to the Workbench. The following routine allows you to
change the repeat speed without returning to Preferences:
1***************************************************** **********
(Input_Support) *
Input_SetPeriod()
*

* Function: Set repeat period

*--------------------~-----------------------------------------*

* Input - Parameter:

* InputRequest: Input-Deviee-Bloek
* Sees, Micro: Time that should pass between two repetitions

*
*
*

***************************************************************/
VOID Input Set Period
struet timerequest
ULONG

(InputRequest,Sees,Miero)
*InputRequest;
Sees, Micro;

InputRequest->tr time.tv sees = Sees;

InputRequest->tr=time.tv=miero = Micro;
Do Command {InputRequest, (UWORD)IND_SETPERIOD);

107

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

You only need to give this routine the time that should pass between
two repetitions of a pressed key.

Changing the
repeat
threshold

When you press and hold a key, the key delays before beginning key
repeat. The time that passes between the pressing down and the
repetition of a key is called the repeat threshold. You can completely
change this threshold with the following routine.
/***************************************************************

Input_SetThresh ()

(Input_Support) *

*
*

* Function: Set repeat time thresholden

*--------------------------------------------------------------*
* Input - Parameter:
*
*
*
* InputRequest: Input-Device-Block
*
* Sees, Micro: After how many seconds and micro seconds the *

key should be repeated

***************************************************************/

VOID Input Set Thresh

struct timerequest
ULONG

(InputRequest, Sees, Micro)

*InputRequest;
Sees,Miero;

1* !!!! *1

InputRequest->tr time.tv sees

InputRequest->tr='time.tv='micro

Sees;
Micro;

Do Command (InputRequest, (UWORD)IND_SETTHRESH);

Try a threshold of zero seconds and zero microseconds. Run the

program, press a key and watch the result

Setting the
mouse speed

Now from the keyboard to the mouse. Here's one of the input device
functions usually reached through Preferences:
/****************************~,*********************** ***********

*
Input SetMTrig()
(Input_Support) *
* Function: Set threshold for mouse movement
*
*--------------------------------------------------------------*
* Input - Parameter:
*
* InputRequest: Input-Deviee-Bloek
*
* Keys:
Mouse button pressed or released?
*
* Timeout:
Send mouse report after how many VBlanks?
*
* XDelta,YDelta: Announce after n mouse movements?
*
**********~******************************************* *********/

VOID Input SetMTrig

struct IOStdReq
ULONG

(InputRequest,Keys,Timeout,XDelta,YDelta)

*InputReq~est;

Keys,Timeout,XDelta,YDelta;

struet GamePortTrigger GPT;

GPT.gpt Keys
= Keys;
GPT.gpt-Timeout = Timeout;
GPT.gpt-XDelta = XDelta;
GPT.gpt=YDelta = YDelta;
InputRequest->io Data
InputRequest->io=Length
GamePortTrigger));

108

(APTR) &GPT;
(ULONG) (sizeof (struet

4.8 THE INPUT DEVICE

ABACUS

Do Command (InputRequest, (UWORD)IND_SETMTRIG);

This routine informs the input device of how many pulses the mouse
should announce for one move in the X or Y direction. As mentioned
above, there are two shafts fitted with wheels perpendicular to each
other inside of the mouse. These wheels have holes drilled in them.
When moving the mouse, each wheel rotates, interrupting a light
source. This pulse is then sent to the input device, or the input device
reads this pulse from the hardware register.
When the number of this pulse of the given value has been reached, the
input device ensures that the mouse pointer moves to a point on the
screen. XDelta and YDelta give the number of the pulse in the X
and Y direction by which the mouse pointer was moved to a point on
the screen. The larger this value is, the slower the mouse is.
The Timeout parameter helps you determine the number of vertical
blanks after which a mouse report or mouse event should be sent, in
case the mouse is not moved extensively. The parameter has the value
1 (for Intuition). The mouse position is renewed after each vertical
blank in the Intuition window, or on the Intuition screen. The Keys
parameter allows the system to announce the release of a mouse button
(G P T F UP KEY S) instead of pressing down a mouse button
(GPTF_ DOWNKEYS).

Assigning the
mouse port

The following routine allows the user to connect the mouse to the
second gameport instead of the default first gameport
1***************************************************** **********
Input_SetMPort ()
(Input_Support) *
* Function: Set mouse port
*

*--------------------------------------------------------------*
* Input - Parameter:

* InputRequest: Input-Device-Block
* Port:
0: GamePort 1
*
1: GamePort 2

*
*

***************************************************************/
VOID Input_SetMPort (InputRequest,Port)
struct IOStdReq
* InputRequest;
UBYTE
Port;
{

UBYTE PointerToPort;
PointerToPort = Port;
InputRequest->io_Data
InputRequest->io_Length

(APTR) &PointerToPort;
(ULONG) 1;

Do Command (InputRequest, (UWORD)IND_SETMPORT);

You must give this routine the input device block and a one or zero.
Then, depending on which value you entered, the mouse is read from

109

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

gameport 1 or gameport 2. Remember that the address must be given

on the value 1 or 0 with this command.
Joystick as
mouse

You can change the mouse controller as well as the mouse port. For
example, this means that a joystick can take over almost all the
functions of the mouse, except for the right mouse button. The
following routine executes this.
/***************************************************************

Input SetMType ()
* Function: Set mouse controller type

(I nput _Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
*
* InputRequest: Input-Device-Block
* Type:
new controller type

*
*

***************************************************************/

VOID Input_SelMType
struct IOSldReq
UBYTE

(InpulRe~~esl,Type)

*InputRequest;
Type;

UBYTE MouseType;
MouseType = Type;
InputRequest->io_Data
= (APTR) &MouseType;
InputRequest->io_Length
= 11;
Do_Command (InputRequest, (miORD)IND_SETMTYPE);

The new controller type is given in Type:

GPCT
GPCT
GPCT
GPCT

MOUSE:
RELJOYSTICK:
ABSJOYSTICK:
NOCONTROLLER:

mouse in the port

relative joystick in the port
absolute joystick in the port
nothing more in the port

Remember that this command must include the address of the type.
That is why the given parameter lis written in an extra variable, whose
address is given in the device block.
The following is the start of the InpuCSupport.c file:
/***************************************************************

* Compile-Info:

Input_Support.c
cc Input Support

*
*

***************************************************************/

#include "exec/types.h"
#include "exec/memory.h"
#include "exec/interrupts.h"
lIinclude "exec/nodes.h"
#include "devices/input.h"
#include "devices/gameport.h"
#include "devices/timer.h"
lIinclude "devices/ inputevent. h"
ULONG User Routine;
'define INEV LEN
ULONG) (sizeof (struct InputEvent)))
VOID Input_Code();
struct Interrupt Input_Handler;

110

4.9 THE CONSOLE DEVICE

ABACUS

4.9

The console device

The console device is the simplest method used to display text on the
screen. A window must ftrst be opened. The console device can read
your input from this window, and the console device can activate the
output. The opened window is specified before the opening of the
console device in the corresponding device block.
struct IOstReq *ConsoleRead = OL;
'define CON_LEN ( ULONG) (sizeof(struct IOStdReq
Window = OpenWindow(&NewWindow);
ConsoleRead = (struct IOstdReq *)GetDeviceBlock(CON LEN);
ConsoleRead->io Data
= (APTR) Window;
ConsoleRead->io-Length = (ULONG) (sizeof(struct Window;
Open_A_Device (,'console.device", OL, &ConsoleRead, OL, OL);

You can now access the console device. The console device supports
the following commands:
CMD READ
CMD WRITE
CMD CLEAR
CD ASKKEYMAP
CD SETKEYMAP

(2)
(3)
(5)
(9)
(10)

CD ASKDEFAULTKEYMAP

(11)

CD SETDEFAULTKEYMAP

(12)

read keypress
display text
clear console buffer
send current keyboard layout
set new keyboard
arrangement
find out default keyboard
arrangement
set default keyboard
arrangement

As you see, the console device uses few commands, but they play an
important role in developing such complicated applications as editors
(see DiskEd), word processors, etc.
The console device is controlled through command strings. These are
sent to the console device with the help of the command CMD _ WRI TE.
You should prepare another device block for the C MD _ WR I T E
command so that the READ and WRITE commands do not interfere
with each other:
struct IOStdReq *ConsoleWrite = OL;
ConsoleWrite = (struct IOStdReq*) GetDeviceBlock(CON_LEN);
Console_Copy (ConsoleRead, ConsoleCopy);

111

4. DEVICES

AD"ANCED SYSTEM PROGRAMMER'S GUIDE

Combine the following routines labled (Con_Support) to form the

Con_Support.c file, don't forget to include the proper header files.
Some Structure elements must be borrowed for accessing the second
device block:
/***************************************************************

Console_Copy ( )

(Con_Support) *

*
*
*--------------------------------------------------------------*
* Input - Parameter:
*
*
*
* Function:

Device-Block copy

* OldStdReq: Original
* NewStdReq: Copy

***************************************************************/

VOID Console_Copy (OldStdReq, NewStdReq)

struct IOStdReq
*OldStdReq,*NewStdReq;
{

NewStdReq->io Device =
OldStdReq->io_Device;
NewStdReq->io Unit =
OldStdReq->io_Unit;

The following routine reads keypresses with Console_Read () and

Console_ Wri te () and displays them on the screen:
1***************************************************** **********

Console_W.ri te ()

* Function: Display string on Console-Device

(Con_Support) *

*----------------------------_._--------------------------------*
* Input - Parameter:

* ConWrite: Device-Block
* String: String to be displayed
* Len:
Length of string

*
*

***************************************************************/

VOID Console Write (ConWrite,St.ring, Len)

struct IOStclReq
*ConWrite;
BYTE
*String;
ULONG
Len;
{

ConWrite->io Data
= (APTR) String;
ConWrite->io Length = Len;
Do_Command (ConWrite, (UWORD)CMD_WRITE);
1***************************************************** **********

Console_Read ()

* Function: Read string from Console-Device

(Con_Support) *

*--------------------------------------------------------------*

*
*
*
*

Input - Parameter:
ConWrite: Device-Block
String:
Address of the buffers
How many characters to be read
Len:

*
*

****************************************************** *********1

112

4.9 THE CONSOLE DEVICE

ABACUS

VOID Console Read (ConRead,String, Len)

struct IOStdReq
*ConRead;
BYTE
*String;
ULONG
Len;
{

ConRead->io Data
(APTR) String;
ConRead->io-Length = Len;
ConRead->io-Colll1land = (UWORD) CMD_READ;
Doro (ConRead) ;

In addition to the device block, these routines give you the address of
the sUing to be displayed, or the address of the range of memory into
which the read keypress should be written. It also gives you the number
of characters to be displayed or read. If you enter -11 as the number of
characters to be displayed, all of the strings that end with a null byte are
displayed.
When you read keypresses from the keyboard by means of
Console_Read (), it returns the ASCII code that represents the
depressed key. Remember that this is not automatically displayed. You
must provide for the output yourself by means of
Console_Write () OrCMD_WRITE. As was already mentioned, a
certain number of control strings exist with which you can test for the
form of the input and output:

BELL

(Ox7)
Screen flashes and tone sounds.

BACKSPACE

(Ox08)
Moves the cursor one position to the left. The character to the left of
the cursor is not deleted. You can delete the character by combining a
backspace and a space.

LINE

(OxOa)
Moves the cursor one position down. When the cursor arrives at the
bottom line of the screen, the screen scrolls up one line (see SET

FEED

MODE).

VERTICAL

FORM
CR

FEED

TAB (OxOb)
Moves the cursor one line up. When the cursor arrives at the top line of
the screen, the screen scrolls down one line.

(OxOc)
Oears the console window.

(OxOd)
Places the cursor in the fIrst column but not in the next line.

113

4.

AD'VANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

SHIFT

IN

(OzOa)

Enables <Shift> key.

SHIFT

OUT

(OzOf)

Disables <Shift> key. Only capital letters are displayed in the output.
CAP S

LOC!C

!Cay

See keyboard layout.

ESC

(Ozlb)

<Escape> key.
CSI

(Oz9b)

Control Sequence Introducer. All command strings begin with this

ASCII code.
RESET

("<CSI>c")

Resets the console device.

INSERT

[N]

SPACES

("<CSI> [N]

8":1

Inserts N spaces starting at the: current cursor position. When N is

omitted, one space is inserted. N is a decimal string. For example,
"<CSI>I2@" inserts 12 spaces.@ represents the ASCII code 64.
CURSOR

UP

[N]

( "<CS I > [N] A" )

Moves the cursor N lines up. When N is omitted, the cursor moves up
one line. N is a decimal string. For example, "<CSI>2A" moves the
cursor up two lines.
CURSOR

DOWN

[N]

("<CSI>[N]B")

Moves the cursor N lines down. When N is omitted, the cursor moves
down one line. N is a decimal string. For example, "<CSI>2B" moves
the cursor down two lines.
CURSOR

FORWARD

("<CSI>[N]C n )

[N]

Moves the cursor N columns to the right. When N is omitted, the

cursor moves right one column. N is a decimal string. For example,
"<CSI>2OC" moves the cursor 20 characters to the right.
CURSOR

BACKWARD

[N]

("<CSI>[N]I)")

Moves the cursor N columns to the left. When N is omitted, the cursor
moves left one column. N is a decimal string. For example,
"<CSI>200" moves the cursor 20 characters to the left.
CURSOR

NEXT

LINE

[N]

("<CSI> [N] En)

Moves the cursor N lines down and to the flrst column (has the same
effect as pressing the <Return> key).

114

4.9 THE CONSOLE DEVICE

ABACUS

CURSOR

PRECEDING

LINE

[N]

(n<CSI> [N] Fn)

Moves the cursor N lines up and to the first column.

MOVE

(n<CSI>[N] [;M]H n )

CURSOR

Moves cursor to line N and, if given, column M. If the M parameter is

omitted, the semicolon must be omitted as well. For example,
"<CSl>l;lH" or "<CSl>lH" or "<CSI>H" each places the cursor in
the upper left comer of the screen (same as Cursor home).
ERASE

TO

END

OF

DISPLAY

("<CSI>J n )

Clears the screen from the current cursor position to the end of the
screen. To clear the entire screen, you can use the following sequence:
"<CSI>l;l;H" (Cursor home) and "<CSI>J" (Delete).
ERASE

TO

END

OF

( n<CSI>K n )

LINE

Deletes line from the current cursor position to the end of the current
line (same as <Ctrl><Y> function in ED).
INSERT

LINE

("<CSI>L")

Inserts a line at the current cursor position.

DELETE

LINE

("<CSI>M")

Deletes the line at the current cursor position. Lines below the deleted
line scroll up to fill in the deletion (same as <Ctrl><B> function in
ED).
DELETE

CHARACTER

(n<CSI>[N]p n )

Deletes N characters to the right of the current cursor position. If the N

parameter is omitted, only the character at the current cursor position is
deleted.
SCROLL

UP

[N]

LINES

(n<CSI> [N] S")

Scrolls the entire screen up N lines. The blank lines below fill with
blank spaces.
SCROLL

DOWN

[N]

LINES

("<CSI> [N] T")

Scrolls the entire screen down N lines. The blank lines above fill with
blank spaces.
SET

MODE

("<CSI>20h n )

Treats a line feed as <Return><Line feed> (OxOc,OxOa). The cursor

moves to the first column of the next line.
RESET

MODE

(n<CSI>20L n )

Treats a line feed as <Line feed> only when a line feed is sent (OxOa),
the cursor moves to the next line but remains in the same column.

l1S

4.

DEVICES

DEVICE

ADVANCED SYSTEM PROGRAMMER'S GUIDE

STATUS

REPORT

("<CSI>6n")

Instructs the console device to send a status report in the following

form: "<CSI>Line;ColumnR". There are decimal strings in Line
and Column which give the line and column of the cursor position.
This report can be read using CMD _READ. Remember that you must
convert the decimal strings to decimal values if you want to calculate
them to determine a new position.

SELECT GRAPHIC Style

("<CSI><Style>i<Foreground>i

<Background>m")

Selects character attribute (style), foreground color and background

color.

<Style>

The Style parameter allows the following values:

o
1
3
4
7

normal text
bold print
italics
underline
inverse

You give the foreground and background color of the characters to be

displayed with Foreground and Background:

<I'oreground>
30
31

Color 0
Color 1

37

Color 7

<Background>
40
41

Color 0
Color 1

47

Color 7

For example, if you want the text displayed underlined and bold and in
colors 0 and I, you must send the following sequence:
"<CSI>4;30;40m"
"<CSI>l;30;4lm"

(underline, without color)

(bold, with color)

All parameters must be entered.

SET

PAGE

LENGTH

("<CSI><LEN>t")

Specifies the number of lines that the console device should control in
the window. The entire window is usually allocated for text output, but
you can reduce the text area with this and the following commands.

116

4.9 THE CONSOLE DEVICE

ABACUS

When changing the size of the window the console device calculates the
new value from the current character set and alters the size of the text
range correspondingly. This happens only if you have not established
your own values. When you want the console device to manage the size
of the window or the text range by itself, you must call the commands
with statements of values, for example" <CSI>t".
SET

LINE

WIDTH

(n<CSIXwidth>u")

Specifies the number of characters per line. You can use the remaining
space for graphics.
SET

LEFT

OI'I'SBT

("<CSI><offset>:z:")

Specifies the starting vertical raster line (not column) at which the text
range should start. For example,"<CSI>8x" uses eight lines of space in
the left window margin for small graphics, scroll bars, etc.
SET

TOP

OFFSBT

("<CSI><offset>y")

Specifies the starting horizontal raster line (not text line) at which the
text range should start. The remaining space can be used for displaying
graphics, tab positions, etc.
CURSOR

ON

("<CSI>O

p")

Enables cursor.
CURSOR

01'1'

("<CSI>

p")

Disables cursor.
WINDOW

STATUS

("<CSI>o

q")

Sends window status request The system returns a status report in the
following form, readable using CMD_READ:
R<CSI>l:l;,<bottom border>; right border> r"

The window status report returns the positions of the upper left comer
(1,1) and the lower right comer.
RAW

EVENTS

Requests additional information about the system from the console

device. For this you must inform the console device which RAW
EVENTS you want to see:

o
1
2
3
4

5
6

no operation
keypress and the release of the key
mouse button pressed
window was activated
mouse pointer position
unused
timer events

117

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

8
9
10
11
12
13
14
15
16

gadget clicked
gadget released
requester displayed
menu selected
close gadget clicked
window resized
window redrawn
Preferences changed
disk: removed
disk inserted

The RAW EVENTS read through the console device are identical to
those events accessible from the input device. Here too the
corresponding flags for checking the event must be set. The following
syntax sends the required events:
<CSI>Event number{

The events return in the following format:

"<CSI><Class>;<SubClass>; <KeyCode>;<Qualifiers>; <X>; <Y>;<Seconds
>; <MicroSeconds> 1"

When you look at the input event structure, you determine large
coincidences between this structure and the control string, which are
sanded from the console device. Each decimal string means the
following:
<Cl.ass>

Returns the number of results received from the console device. You
can check multiple results of all of the results from the console device.
For example, if you want keypresses and mouse button clicks to be
returned, you can access them through "<C S I > 1 {" followed by
"<CSI>2 {n, or simply through n<CSI>l; 2 {".

<SubCl.aaa>

Most often contains the value O. SubClass contains the value 1 only
when the mouse is plugged into gameport 2.

<KeyCode>

Contains the decimal string that indicates the keyboard code of the

pressed or released key (see Section 4.8).

<Qual.ifiera>
Indicates which of the <Ctrl>, <Alt> and <Shift> keys was pressed.

1
2
4

8
16

32

118

left <Shift>
right <Shift>
<Caps lock>
<Ctrl>
left <Alt>
right <Alt>

4.9 THE CONSOLE DEVICE

ABACUS

64

128
256
512
1024
2048
4096

8192
16384
32768

left <Amiga>
right <Amiga>
numeric keypad key
key repeated (repeat function)
interrupt (unused)
multi broadcast (result for current window)
left mouse button
middle mouse button (unused)
right mouse button
relative mouse movement

When multiple Qualifiers are pressed, the corresponding values are

added and given in <Qualifier>.

<x> <y>

Returns the relative mouse movement or the address of the chosen

gadget (XI6+Y).

<Seconds>

Returns the system time in seconds.

<Microseconds>
Returns the system time in microseconds.
The user must decode the string supplied by the console device and
interpret the values found there. It takes little time to calculate how
much more he gets directly though the IDCMP flags of the events and
the keyboard code.
Now that we've described all of the control strings that can be sent and
received, we have here a short application that you can enter, compile,
link: and run. This console device editor allows you to enter control
strings from the keyboard and watch the result frrsthand. Because the
control sequence can be chosen by sources other than through the
keyboard, we check the escape key and interpret Escape as <CSI>. You
can get out of the editor by entering <q><Retum>.
Combine all of the Con_Support routines presented in this chapter to
form the Con_Support.c program. Compile the COD_Support.c
program and link it to the following program. Don't forget the proper
include files in the COD_SUpport.c file (exec/types.h, exec/memory.h,
eXec/devices.h, devices/console.h, devices/keymap.h)
1***************************************************** **********
*
Conni.e
*

*
*

(e) Bruno Jennrieh

August 1988

*************************.*************************************1
1***************************************************** **********

*
*

Compile-Info:
ee Conni.e
In ConnLo Con Support.o Devs Support.o -Ie

*
*

***************************************************************/

119

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

'include
'include
'include
'include
'include
'include
'include

nexec/types.h"
"exec/memory.hn
nexec/devices.h"
"devices/console.h"
ndevices/keymap.h"
nintuition/intuitioribase.h n
nintuition/intuition.h"

'define HEMTYPE
(MEMF CHIP I HEMP CLEAR)
'define CON_LEN (ULONG)-(sizeof (struct IOStdReq
VOID
VOID
VOID
VOID
VOID
VOID

*Open () ;
*AllocMem () ;
*GetDeviceBlock();
*OpenLibrary () ;
*OpenScreen();
*OpenWindow();

struct Screen
* Screen
struct Window
*Window
struct IntuitionBase *IntuitionBase
struct NewScreen

01;
01;
01;

New Screen = {
0,0,640,200,4,
0,1,
HIRES,
CUSTOMSCREEN,
01,
(UBYTE*) "No Name",
01,
01
};

struct NewWindow

NewWindow
0,0,
640,200,
0,1,
01,
(ULONG) ACTIVATE,
01,
01,
(UBYTE*) "Console-Device-

Editor (c) Bruno Jennrich",

01,
01,
0,0,
0,0,
CUSTOMSCREEN
};

struct IOStdReq

*ConsoleRead
*ConsoleWrite

01,
01;

1***************************************************** **********

CloseIt ()

* Function: In case of erro rclose everything

(User) *

*--------------------------------------------------------------*
* Input - Parameter:

* String: Error-Message

*
*

***************************************************************/

120

4.9 THE CONSOLE DEVICE

ABACUS

VOID closeIt (String)

char
*String;
UWORD i;
UWORD *dff180 = (UWORD *)Oxdff180;
UWORD Error = 0;
if (strlen (String) > 01)
{

for (i=O;i<Oxffff;i++)
puts {String);
Error = 10;

*dff180

i;

if (Window != 01)
CloseWindow (Window);
if (Screen != 01)
CloseScreen (Screen);
if (IntuitionBase != 01) CloseLibrary (IntuitionBase);
if (ConsoleRead != 0)
if (ConsoleWrite != 0)
exit (Error);

Close_A_Device (ConsoleRead);
FreeDeviceBlock (ConsoleWrite);

1***************************************************** **********
*
Open_Screen_and_WindowO
(User) *

* Function: Open editor screen and window

*
*

***************************************************************/

VOID Open_Screen_and_Window()
{

IntuitionBase = (struct IntuitionBase*)

OpenLibrary ("intuition. library", 01);
if (IntuitionBase == 01) CloseIt ("No IntuitionBase !");
Screen = (struct Screen *) OpenScreen (&NewScreen);
if (Screen == 01) CloseIt ("No Screen! ");
NewWindow.Screen = Screen;
Window = (struct Window *) OpenWindow (&NewWindow);
if (Window == 01) CloseIt ("No Window!");

1***************************************************** **********
*
Close_Screen_and_WindowO
(User)*

* Function: Close editor screen and window

***************************************************************/

VOID Close_Screen_and_Window()
{

CloseWindow (Window);
CloseScreen (Screen);
CloseLibrary (IntuitionBase);

121

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

/***************************************************************

main ()

(User) *

***************************************************************/
main ()
{

i;

UWORD

InputString[256];
*BufPointer;
/*
/*
/*
UWORD Pos;
Quit
FALSE; /*
BOOL
BOOL Return
FALSE; /*
BYTE

BYTE

ConsoleRead
ConsoleWrite

Actual input position inside */

of InputString
*/
Number chars in InputString */
Progranun ended? */
Return pressed? */

(struct IOStdReq *)GetDeviceBlock (CON_LEN);

(struct IOStdReq *)GetDeviceBlock (CON_LEN);

ConsoleRead->io Data
ConsoleRead->io=Length

(APTR) Window;
(ULONG) (sizeof (struct Window;

Open_A_Device ("console.device",Ol,&ConsoleRead,Ol,Ol);
Console_Copy (ConsoleRead,ConsoleWrite);
BufPointer = InputString;
Pos = 0;
while (!Quit)
(

while (!Return)
{

*BufPointer = (BYTE)O;
Console Read (ConsoleRead,BufPointer,ll);
if (*Bufpointer == (BYTE)OxOB) /* Backspace */
(

i f (Pos>O)
{

*BufPointer = (BYTE)O;
BufPointer--;
if (*BufPointer == (BYTE) Oxlb)
{
/* <
Console Write
(ConsoleWrite,"\OlO\OlO\OlO\OlO\OlO",-ll);
Console_Write (ConsoleWrite,"
Console Write
(ConsoleWrite,"\OlO\010\010\OlO\010",-ll);

",-11);

else
(

Console Write (ConsoleWrite,"\010",1l);

Console Write (ConsoleWrite," ",II);
Console-Write (ConsoleWrite,"\OlO",ll);
*BufPointer = (BYTE)O;
Pos--;
else
{

i f (Pos <256)
{

III

> */

4.9 THE CONSOLE DEVICE

ABACUS

if (*Bufpointer

==

(BYTE) Ox9b)

1* Replace revieved CSI with OxO? *1

*BufPointer = Ox?;

if (*BufPointer

==

OxOd) 1* Return *1

Return = TRUE;
Console Write (ConsoleWrite,"\012 n,1l);
if (*InputString == 'q') Quit = TRUE;
1* 'q' pressed? *1
else
if (*BufPointer == Oxlb) 1* Escape *1
{

Console_Write (ConsoleWrite,n<CSI>R,Sl);
else Console Write (ConsoleWrite,BufPointer,ll);
BufPointer++;
Pos++;

Return = FALSE;
*BufPointer = (BYTE)O;
if (*InputString == (BYTE)Oxlb)
{ 1* Display control string after Return *1
*InputString = (BYTE) Ox9b;
Console_Write (ConsoleWrite,InputString,-ll);
BufPointer
Pos = 0;

InputString;

Close A Device (ConsoleRead);

FreeDevlceBlock (ConsoleWrite);

Note:

Once you enter "<CSI>l {" there is no going back.

The <CSI> codes are replaced with BELLs (Ox07) when the control
strings are received. Many of the key presses (e.g., cursor keys) also
send a <CSI>. Therefore, cursor keys and function keys may not work.
One last item of interest: The control codes listed above also function
in a CON: window. To see if the ConIn program works press the
<Esc> <0> <p> to tum off the cursor, then <Esc> <p> to tum is back
on.

123

4. DEVICES

4.9.1

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Key mapping
The console device allows the option of overlaying new keys. This
makes it possible to print a string like "Hello people, how are you?" in
response to a single keypress. The console device gets the key code of
the character that was pressed from the input device by way of the
keyboard device. The console then exttacts the ASCII code from the
tables that correspond to the key that was pressed and gives this to the
user. You can change this table, provided you know the keymap
structure:
Offset

Structure

--------

struct KeyMap
{

0
4
8
12
16
20
24
28
32

Oxoo
Ox04
Ox08
OxOc
OxlO
Ox14
Ox18
OxIc
Ox20

UBYTE *km_ LoKeyMapTypes:

ULONG *km_ LoKeyMap;
UBYTE *km_LoCapsab1e;
UBYTE *km_LoRepeatab1e;
UBYTE *km_HiKeyMapTypes;
ULONG *km_HiKeyMap;
UBYTE *km_HiCapsab1e;
UBYTE *km_HiRepeatab1e:
/* defined in "devices/keymaps.h" */

This structure contains the pointer to memory ranges that compare

what was sent with a certain keypress in the console device. The
difference between Hi and Lo map is important. The La keymap
contains the data for key codes OxO through Ox3f. The Hi key map
contains the data for key codes Ox40-0x67.
Next we need the KeyMapTypes and the KeyMap. The pointers
km_LoKeyMapTypes and km_HiKeyMapTypes point to a byte
array which determines which qualifier Shift>, <Alt>, <Ctrl is
supported by the key, or if a string (KeF_STRING) should be sent
instead of a simple ASCII code. The following values are allowed:
'define KC NOQUAL
Oxoo
'define KeF SHIFT
OxOl
'define KCF-ALT
Ox02
'define KCF-CONTROL Ox04
'define KC VANILLA OxO? /* Shift+A1t+Ctr1 */
'define KeF STRING Ox40 /* String */
/* defined in "devices/keymaps.h" */

124

ABACUS

4.9 THE CONSOLE DEVICE

125

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The ASCII codes that should be sent if a single key or a key with a
qualifier is pressed are saved in km LoKeyMap and km Hi KeyMap.
This memory area is a long word array (4 bytes = 4 ASCn codes).
The result is that a key can support only two qualifiers (e.g.,
<Shift><Alt> or <Ctrl><Alt. ASCII codes are sent when a single
key is pressed, when a key is pressed in conjunction with one of the
qualifiers (e.g., <Shift> or <Alt, and when a key is pressed in
conjunction with two qualifiers (e.g., <Shift><Alt.
By using strings instead of simpler ASCII codes, up to eight different
strings can be sent out based on a single key and the corresponding
qualifier. Let's look at a German keymap that makes simple ASCII
codes available as strings:

';ownkeymap.asm
asm
KC NOQUAL
KC=VANILlA
KCF SHIFT
KCF=ALT
KCF CONTROL
KCF=STRING
CSI

(c) Bruno Jennrich

equ 0
equ 7
equ 1
equ 2
equ 4
equ 64
equ $9b

public _LoKeyMapTypes
even
_ LoKeyMapTypes:
dc.b KC VANILIA
dc.b KC-VANILIA
dc.b KC-VANILlA
dc.b KC-VANILlA
dc.b KC-VANILlA
dc.b KC-VANILlA
dc. b KC-VANILlA
dc.b KC-VANILIA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b 0 dc.b 0
dc.b KC_NOQUAL
dc.b KC VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA
dc.b KC-VANILLA

126

;$00
;$01
;$02
;$03
;$04
;$05
;$06
;$07
;$08
;$09
;$Oa
;$Ob
;$Oc
;$Od
;$Oe
;$Oe
;$Of
;$10
;$11
;$12
;$13
;$14
;$15
;$16
;$17
;$18
;$19
;$la
;$lb

Tilde
1

2
3
4
5
6
7
8
9
0

...
\
undefinied
!!!!!! !
undefinied
0 (Number field)
q

e
r
t

z , y on US keyboard
u
i
0

p
I
+

4.9 THE CONSOLE DEVICE

ABACUS

dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc. b
dc.b
dc.b

0
KC NOQUAL
KC-NOQUAL
KC-NOQUAL
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC VANILLA
KC-VANILLA
KC-VANILLA
0
0
KC NOQUAL
KC-NOQUAL
KC-NOQUAL
0 KC VANILLA
KC-VANILLA
KC-VANILLA
KC-VANILLA
KC VANILLA
KC-VANILLA
KC VANILLA
KC-VANILLA
KC VANILLA
KC-VANILLA
0
KC_NOQUAL
KC NOQUAL
KC:::NOQUAL
KC_NOQUAL

public _LoKeyMap
even
LoKeyMap:
- dc.h "_","fl1,"]II,"["
dc.b $21+$80,$31+$80,"!","1"
dc.b $22+$80,$32+$80,$22,"2"
dc.b $a7+$80,$33+$8C,"'","3"
dc.b $24+$80,$34+$80,"$","4"
dc.b $25+$80,$35+$80,"%","5"
dc.b $26+$80,$36+$80,"&","6"
dc.b $2f+$80,$37+$80,"/","7"
dc.b $28+$80,$38+$80,"(","8"
dc.b $29+$80,$39+$80,")","9"
dc.b $3d+$80,$30+$80,"=","0"
dc.b $3f+$80,$df+$80,"?"," "
dc.b $27+$80,$60+$80,"'","-;-"
dc.b $7c+$80,$5c+$80,"I","\"
dc.l $0
dc.l $0
dc.b $00,$00,$00,"0"
dc.b $51+$80,$71+$80, "Q", "q"
dc.b $57+$80,$77+$80, "W","w"
dc.b $45+$80, $65+$80, "E","e"
dc.b $52+$80,$72+$80,"R","r"
dc.b $54+$80,$74+$80,"T","t"

;$lc
;$ld
; $le
;$lf

;$20
;$21
;$22
;$23
;$24
;$25
;$26
; $27
; $28
;$29
;$2a
;$2b
;$2c
;$2d
;$2e
; $2f
;$30
;$31
;$32
;$33
;$34
;$35
;$36
;$37
;$38
;$39
;$3a
;$3b
;$3c
; $3d
;$3e
; $3f

undefinied
1 (Number field)
2 (Number field)
3 (Number field)
a
s
d
f
g

h
j

k
I
v

reserved
undefinied
4 (Number field)
5 (Number field)
6 (Number field)
reserved
y, z on US keyboard
x
c

v
b
n
m

undefinied
, (Number field)
7 (Number field)
8 (Number field)
9 (Number field)

;$00
; $01
;$02
;$03
;$04
;$05
;$06
;$07
;$08
;$09
;$Oa
;$Ob
;$Oc
;$Od
;$Oe
;$Oe
;$Of
;$10
;$11
;$12
;$13
;$14

1
2
3
4
5
6
7
8
9
0

-.\
undefinied
undefinied
0 (Number field)
q
w

e
r
t

127

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b

public _HiKeyMapTypes
even
_ HiKeyMapTypes:
dc.b KC NOQUAL
dc.b KC:::NOQUAL
dc.b KC NOQUAL
dc.b KC:::NOQUAL
dc.b KC NOQUAL
dc.b KC:::NOQUAL
dc.b KC_NOQUAL
dc.b a
dc.b a
dc.b a
dc.b KC_NOQUAL
dc.b 0
dc.b KCF STRING+KCF SHIFT
dc.b KCF-STRING+KCF-SHIFT
dc.b KCF-STRING+KCF-SHIFT

128

;$15
;$16
;$17
;$18
;$19
;$la
;$lb
;$lc
;$ld
;$le
;$lf
;$20
;$21
;$22
;$23
;$24
;$25
;$26
;$27
;$28
;$29
;$2a
;$2b
;$2c
;$2d
;$2e
;$2f
; $30
;$31
;$32
;$33
; $34
;$35
;$36
;$37
;$38
;$39
;$3a
;$3b
;$3c
;$3d
;$3e
;$3f

$5a+$80,$7a+$80,"Z","z"
$55+$80,$75+$80, "U", "U"
$49+$80,$69+$80,"I","i"
$4f+$80,$6f+$80, "0", "0"
$50+$80, $70+$80, "P", "p"
$dc+$80,$fc+$80,"\","I"
$2a+$80,$2b+$80,"*","+"
$00,$00,$00,$00
$00,$00,$00,"1"
$00,$00,$00,"2"
$00,$00,$00,"3"
$41+$80,$61+$80, "A", "a"
$53+$80,$73+$80, "S", "s"
$44+$80,$64+$80,"O","d"
$46+$80, $66+$80, "F", "f"
$47+$80,$67+$80, "G","g"
$48+$80,$68+$80, "H", "h"
$4a+$80,$6a+$80,"J","j"
$4b+$80, $6b+$80, "K", "k"
$4c+$80,$6c+$80, "L", "1"
$d6+$80, $f6+$80, "V", "v"
$c4+$80,$e4+$80,"O","d"
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,"4"
$00,$00,$00,"5"
$00,$00,$00,"6"
$00,$00,$00,$00
$59+$80,$79+$80,"Y","y"
$58+$80, $78+$80, "X", "x"
$43+$80,$63+$80,"C","c"
$56+$80, $76+$80, "V", "v"
$42+$80,$62+$80, "B", "b"
$4e+$80,$6e+$80, "N", "n"
$4f+$80,$6f+$80, "M", "m"
$3b+$80,$2c+$80,";",","
$3a+$80,$2e+$80,":","."
$5f+$80,$2d+$80,"_","-"
$00,$00,$00,$00
$00,$00,$00,","
$00,$00,$00,"1"
$00,$00,$00,"2"
$00,$00,$00,"3"

;$40
;$41
; $42
;$43
;$44
;$45
;$46
;$47
;$48
;$49
;$4a
;$4b
;$4c
;$4d
; $4e

z, y on us
U

i
0
p
I
+
undefinied
1 (Number field)
2 (Number field)
3 (Number field)
a
s
d
f
g
h
j

k
1
v
d
reservied
undefined
4 (Number field)
5 (Number field)
6 (Number field)
reserved
y, z on us
x
c
v
b
n
m

undefined
, (Number
7 (Number
8 (Number
9 (Number

Space
BackSpace
Tab
Enter
Return
Escape
Delete
undefined
undefined
undefined
Number feild
undefined
Up Arrow
Down Arrow
Forward Arrow

field)
field)
field)
field)

4.9

ABACUS

de.b
dc.b
dc.b
de.b
de.b
de.b
de.b
dc.b
de.b
de.b
de.b
de.b
dc.b
dc.b
de.b
dc.b
dc.b
dc.b
dc.b
de.b
dc.b
dc.b
dc.b
dc.b
dc.b

KCF STRING+KCF SHIFT

KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
KCF-STRING+KCF-SHIFT
0 0
0
0
0
KCF STRING
0 0
0
0
0
0
0
0

: $4f
:$50
: $51
:$52
:$53
: $54
: $55
:$56
: $57
:$58
: $59
: $5a
:$5b
:$5c
:$5d
;$5e
: $5f
: $60
:$61
:$62
: $63
:$64
:$65
;$66
:$67

THI CONSOLI DEVICE

Backward Arrow
Fl
F2
F3
F4
F5
F6
F7
F8
F9
FlO
undefined
undefined
undefined
undefined
undefined
Help
SHIFT left
SHIFT right
CAPS LOCI<
CTRL

ALT left
ALT right
AMIGA left
AMIGA right

public _HiKeyMap
even
_HiKeyMap:
dc.b
dc.b
dc.b
dc.b
dc.b
de.b
de.b
de.b
de.b
dc.b
dc.b
dc.b
dc.l
dc.l
de.l
dc.l
de.l
de.l
de.l
de.l
de.l
de.l
de.l
de.l
de.l
de.l
de.b
dc.b
dc.b
de.b
de.b
de.l

$00,$00,$00,$20
$00,$00,$00,$08
$00,$00,$00,$09
$OO,$OO,$OO,$Od
$OO,$OO,$OO,$Od
$00,$00,$9b,$lb
$00,$00,$00,$7f
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,"-"
$00,$00,$00,$00
Up_Arrow
Down Arrow
Forward Arrow
Backward Arrow
Fl
F2
F3
F4
F5
F6
F7
F8
F9
FlO
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
Help

;$40
;$41
: $42
:$43
: $44
: $45
: $46
:$47
;$48
: $49
;$4a
;$4b
;$4e
;$4d
; $4e
;$4f
; $50
; $51
;$52
: $53
: $54
: $55
: $56
; $57
; $58
: $59
; $5a
:$5b
: $5e
;$5d
;$5e
:$5f

Spaee
BackSpace
Tab
Enter
Return
Escape
Delete
undefined
undefined
undefined
Numerie Pad
undefined
Up Arrow
Down Arrow
Forward Arrow
Backward Arrow
Fl
F2
F3
F4
F5
F6
F7
F8
F9
FlO
undefined
undefined
undefined
undefined
undefined
Help

129

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b
dc.b

$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00
$00,$00,$00,$00

;$60
;$61
;$62
;$63
;$64
;$65
;$66
;$67

SHIFT left
SHIFT right
CAPS LOCK
CTRL

ALT left
ALT right
AMIGA left
AMIGA right

Up Arrow:
-dc.b 2
; Length of the strings (unshifted)
dc.b Up Arrow UnShift-Up Arrow
; Offset
dc.b 2
; Length of the strings (shifted)
dc.b Up Arrow Shift-Up Arrow
; Offset
Up Arrow UnShift:-dc.b CSI, "A"
Up Arrow Shift:
-dc.b CSI,nT"
Down Arrow:
dc.b 2
; Length of the strings (un shifted)
dc.b Down Arrow UnShift-Down Arrow
; Offset
dc.b 2 ; Length of the strings (shifted)
dc.b Down Arrow shift-Down Arrow
; Offset
Down Arrow UnShift:dc.b CSI, "Bn
Down Arrow Shift:
dc.b CSI,"S"
Forward Arrow:
dc.b- 2
; Length of the
dc.b Forward Arrow UnShift-Forward Arrow
dc.b 3
- ; Length of the
dc.b Forward Arrow Shift-Forward Arrow
Forward Arrow UnShift: dc.b-CSI, "C"
Forward Arrow Shift:
dc.b-CSI, "-A"

strings (unshifted)
; Offset
strings (shifted)
; Offset

Backward Arrow:
dc.b -2
; Length of the strings (unshifted)
dc.b Backward Arrow UnShift-Backward Arrow
; Offset
dc.b 3
- ; Length of the strings (shifted)
dc.b Backward Arrow Shift-Backward Arrow
; Offset
Backward Arrow UnShift:dc.b CSI,"D"
Backward Arrow Shift:
dc.b CSI," @n
Fl:
dc.b 3
dc.b Fl UnShift-Fl
dc.b 4
dc.b Fl_Shift-Fl
Fl UnShift:
dc.b CSI,"O-"
Fl Shift:
-dc.b CSI,"lo-n

Length of the strings (unshifted)

Offset
Length of the strings (shifted)
Offset

F2:
dc.b

130

Length of the strings (unshifted)

4.9 THE CONSOLE DEVICE

ABACUS

dc.b F2 UnShift-F2
dc.b 4
dc.b F2 Shift-F2
F2 UnShift:
-dc.b CSI,n1- n
F2 Shift:
-dc.b CSI,"ll-"

Offset
Lenght of the strings (shifted)
Offset

F3:
dc.b 3
dc.b F3 UnShift-F3
dc.b 4
dc.b F3 Shift-F3
F3 UnShift:
dc.b CSI,n2-"
F3 Shift:
-dc.b CSI,"12-"

Length of the strings (un shifted)

Offset
Length of the strings (shifted)
Offset

F4:
dc.b 3
dc.b F4_UnShift-F4
dc.b 4
dc.b F4_Shift-F4
F4 UnShift:
-dc.b CSI,n3-"
F4 Shift:
-dc.b CSI,"13- n

Length of the strings (un shifted)

Offset
Length of the strings (shifted)
offset

FS:
dc.b 3
dc.b FS UnShift-FS
dc.b 4
dc.b FS Shift-FS
FS UnShift:
dc.b CSI,n4-"
FS Shift:
dc.b CSI,"14- n

Length of the strings (un shifted)

Offset
Length of the strings (shifted)
Offset

F6:
dc.b 3
dc.b F6 UnShift-F6
dc.b 4
dc.b F6 shift-F6
F6 UnShift:
dc.b CSI,"S-"
F6 Shift:
-dc.b CSI,"1S-"

Length of the strings (un shifted)

Offset
Length of the strings (shifted)
Offset

F7:
dc.b 3
dc.b F7 UnShift-F7
dc.b 4
dc.b F7 Shift-F7
F7 UnShift:
dc.b CSI,"6-"
F7 Shift:
-dc.b CSI, "16-"

Length of the strings (unshifted)

Offset
Length of the strings (shifted)
Offset

F8:
dc.b
dc.b
dc.b

3
F8 UnShift-F8
4

Length of the strings (un shifted)

Offset
Length of the strings (shifted)

131

ADVANCED SYSTEM PROGRAMMER'S GUIDE

4. DEVICES

dc.b Fa shift-FS
Fa UnShift:
-dc.b CSI,n7-n
FS Shift:
-dc.b CSI,nI7-n

Offset

F9:
dc.b 3
dc.b F9 UnShift-F9
dc.b 4
dc.b F9 shift-F9
F9 UnShift:
-dc.b CSI,"a-"
F9 Shift:
dc.b CSI,nIS-"
FlO:
dc.b 3
dc.b FlO UnShift-FIO
dc.b 4
dc.b FlO Shift-FlO
FlO UnShift:dc.b CSI,"9-"
FlO Shift:
dc.b CSI,"19-"
Help:
dc.b 3
dc.b Help UnShift-Help
Help_UnShift:dc.b CSI,"?-"
even
'endasm

Note:

Length of the strings (unshifted)

Offset
Length of the strings (shifted)
Offset

Length of the strings (unshifted)

Offset
Length of the strings (shifted)
Offset

; Length of the strings (unshifted)

; Offset

For unknown reasons we must use $Oe twice for the keyboard code
instead of one byte in the KeyMapTypes table and eight bytes instead
of four in the Keymap table. If you don't do this, all of the keypresses
end with incorrect codes. For example, "v" instead of Cor "m" instead
ofM.
Remember that the KeyMap and KeyMapTypes arrays begin in word
addresses (even). After detennination of the arrays you should also make
sure that the rest of the program continues with an even address
otherwise a Guru Meditation occurs. This Guru informs you of an
address error (Guru number $000000(3).
Now let's examine the entries in LoKeyMap more closely: you have
determined that the fIrst byte contains the value "A" + $ 8 0 for the
keyboard code $20. The second byte contains "a" + $ 8 0 and the last
two bytes contain the value "A" and "a". Unfortunately the Aztec C
assembler does not understand expressions like "A" + $ 8 O. That is why
we have translated the character "A" into its ASCII code $41. Let's see
which of the four ASCII codes are sent when a key is pressed in
conjunction with a qualifier:

132

4.9 THE CONSOLE DEVICE

ABACUS

allowable qualifiers (keyMapTypes)

S

II)

.S

.4

C+A

S+C

S+A+C

$80

a+

$80

a+

a+

a+

a-

$80

$80

$30

$80

A+

A-

a+

$80

$80

30

A+

A+

A+

$80

$80

$80 $80
-$30

II)

A+

$80

!II

..it'

a+

II)

II)

S=Shlft
A=AIt
C=Control

A+

$80

A+

a+

a+

$80

$80

$80
-$30

A+

Example: allowable qualifier: S+A R ult'''.. $80

: printable qualifier: C+A es . a +
KeyMapEntry:
dc.b "A"+$80, "a"+$80. "A", "au

133

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

You see that one of the ASCII codes "a", "An, "A"+$80, or "a"+$80 is
sent only when the qualifiers <All> and <Shift> are pressed. When all
three qualifiers are allowed, bits 5 and 6 ($30) of the sent code are
cleared when the <Ctrf> key is pressed. You also have no option of
testing for the ASCII code sent in conjunction with <Ctrl> ,
independently from the codes established in the keymap.
This changes somewhat when we use strings instead of simple ASCII
codes. Here you must bear in mind that the four bytes in the keymap
act as an entry point to one or more string descriptors. Such a string
descriptor has the following format:
l.)
2.)

byte
byte

length of the string to be displayed

offset of the string at the beginning of the descriptor

Here is an example:
StringDescriptor:
dc.b 8
dc.b Stringtobedisplayed1-StringDescriptor
dc.b 14
dc.b Stringtobedisplayed2-StringDescriptor
Stringtobedisplayed1: dc.b "String 1"
Stringtobedisplayed2: dc.b "second String"

; length
;Offset
; length
;Offset

Because the strings to be displayed are addressed over offsets, the strings
must be placed in the range from +127 to -128 bytes from the
beginning of the string descriptor. Now you can represent all three
qualifiers and their combinations through other strings. The illustration
on the opposite page tells which combination of allowed and pressed
qualifiers display which string.
Remember that with one allowable qualifier, two strings must be
available; for two allowable qualifiers, four strings must be available;
and with three qualifiers, eight strings must be available. A string
descriptor must also be specified for each of the strings to be displayed
Now the pointers Lo/HiCapsable and Lo/HiRepeatable must
be explained.
Certain keys like the <Caps lock> key are not represented by their
shifted values. So <Caps lock> displays a "1" instead of a "!". The
CapsAble pointer points to a 8 byte array from which a bit is
responsible for seeing if a key should execute Caps lock (Bit == 1) or
ignore it (Bit = 0). The CapsAble bit 0 of the first byte is set to
zero for the key number zero (LoCapsable). The first bit of the
second byte pertains to key 8, and so on. The first bit from
HiCapsable pertains to key Ox40. Two pointers point to a 64 bit =
byte size array.

134

ABACUS

4.9 THE CONSOLE DEVICE

allowable qualifiers (keyMapTypes)

S

S.A

C.A

S.C

S.A.C

CD

()

CD

()

()

CD

()

CD

S=Shlft
A.AII
C=Control

KeyMapEntry
NewA:
de. b 1
de. b A-NewA
de. b 1
de. b B-NewA
de. b 1
de. b C-NewA
de.
de.
de.
de.

b1
b O-NewA

A: de . b "A"
B: de . b "8"
C: de. b-C"
0: de. b "0"
E: de. b "E"
F: de. bOP
G: de. b "G"

H: de . b "H"

b1
b E-NewA

de. b 1
de. b F-NewA
de. b 1
de. bG-NewA
de. b 1
de. b H-NewA

135

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

It is similar with Lo/HiRepeatable. Here one bit is reserved for

one key in HiKeyMap and LoKeyMap. The set bits indicate if the
corresponding key should be repeated after it has been released (see
input device). If, for example, this bit = 0 for the <Return> key, the
<Return> key does not repeal
How can you use a new keymap over the console device? The keymap
sttucture must be filled by Console_AskKeyMap () with the values
of the console window keymap structure.
struot KeyMap KeyMap;
Console_AskKeyMap(ConsoleRead, &KeyMap);

Then change the corresponding pointer of the keymap structure and the
command CD SETKEYMAP .
. KeyMap.km LoKeyMapTypes = (UBYTE*) &LoKeyMapTypes;
= (ULONG*) &LoKeyMap;
KeyMap.km-LoKeyMap
KeyMap.km-HiKeyMapTypes = (UBYTE*) &HiKeyMapTypes;
KeyMap.km-HiKeyMap
(ULONG*) &HiKeyMap;
Console_setKeyMap(ConsoleRead, &KeyMap);

Now the new keymap is installed. Here are the Con_Support

routines that we have used above, add them to your Con_SupporLc file:
1***************************************************** **********

Console_AskKeyMap ()

(Con_Support) *

* Function: Fill KeyMap-Structure

*--------------------------------------------------------------*
*
*
*
* ConReq:
Device-Block
*
* KeyMap: Pointer to KeyMap-Structure
*
* Input - Parameter:

*--------------------------------------------------------------*
* Return Value:
*

FALSE: Error !!!

***************************************************************/

BOOL Console AskKeyMap (ConReq,KeyMap)

struct IOStdReq
*ConReq;
struct KeyMap
*KeyMap;
{

ConReq->io_Length = (sizeof(struct KeyMap;

= (APTR)KeyMap;
ConReq->io Data
Do Command- (ConReq, (UWORD) CD ASKKEYMAP);
if-(ConReq->io Error != (BYTE) 0) return (FALSE);
return (TRUE);1***************************************************************

*
*

Console_SetKeyMap()

* Function: Install Console-KeyMap

136

(Con_Support) *

*
*

4.9 THE CONSOLE DEVICE

ABACUS

*--------------------------------------------------------------*
* Input - Parameter:
*

ConReq:
* KeyMap:

Device-Block
Pointer to KeyMap-Structure

*
*
*--------------------------------------------------------------*
* Rerun value:
*
*
*
* FALSE: Error !!!
*

***************************************************************/

BOOL Console SetKeyMap (ConReq,KeyMap)

struct IOStdReq
*ConReq;
struct KeyMap
*KeyMap;
{

ConReq->io Length = (sizeof(struct KeyMap;

= (APTR)KeyMap;
COnReq->io-Data
Do Command-(ConReq, (UWORD)CD SETKEYMAP);
if-(COnReq->io Error != (BYTE) 0) return (FALSE);
return (TRUE);-

You also have the option of bypassing the console device and assigning
a different keymap to the console window. This can be done through
CD ASKDEFAULTKEYMAP and CD SETDEFAULTKEYMAP. When
you use these two commands to install a new keymap, the next time
you invoke the Open_A_Device ("console .device", OL,
&ConsoleRead, OL. OL); command enables the keymap. These
commands are used by the SetMAP eLI command. The SetMAP
command changes the ConUnit structure of the current CLI window.
1***************************************************** **********

Console_AskDelfaultKeyMap()

(Con_Support) *

*
*
*--------------------------------------------------------------*
* Function: Fill KeyMap-Structure
* Input - Parameter:

* ConReq:
* KeyMap:

Device-Block
pointer to KeyMap-Structure

*
*

*--------------------------------------------------------------*

* Retrun value:

* FALSE: Error !!!

*
*

*
***************************************************************/

BOOL Console AskDefaultKeyMap (ConReq,KeyMap)

struct IOStdReq
*ConReq;
struct KeyMap
*KeyMap;
ConReq->io Length = (sizeof(struct KeyMap;
= (APTR)KeyMap;
ConReq->io-Data
Do Command- (ConReq, (UWORD) CD ASKDEFAULTKEYMAP);
if-(ConReq->io Error != (BYTE) 0) return (FALSE);
return (TRUE);-

137

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

/***************************************************************
*
Console SetDefaultKeyMap ()
(Con Support) *

* Function: Install Console-Default-KeyMap

*
*--------------------------------------------------------------*
* Input - Parameter:
*

*
*
*

ConReq:
KeyMap:

Device-Block
Pointer to KeyMap-Structure

*
*

*--------------------------------------------------------------*
* Retrun value:

*
* FALSE: Error

!!!

*
***************************************************************1

BOOL Console SetDefaultKeyMap (ConReq, KeyMap)

struct IOSt<ffieq
*ConReq;
struct KeyMap
*KeyMap;
{

ConReq->io_Length = (sizeof(struct KeyMap;

ConReq->io Data
= (APTR)KeyMap;
Do Command-(ConReq, (llWORD)CD SETDEFAULTKEYMAP);
if-(COnReq->io Error != (BYTE) 0) return (FALSE);
return (TRUE);-

4.9.2

Console internals
After Open_A_Device the ConsoleRead->io_Unit points to a
ConUn! t structure. This structure contains all of the important
variables needed for using the console:
Offset

138

Structure

--------

struct ConUnit

1* message port for sending *1

1* and receiving
*1
struct Window *cu_Window;
1* Console Window *1

Oxoo

34
38
40
42
44

Ox22
Ox26
Ox28
Ox2a
Ox2c

WORD
WORD
WORD
WORD

cu_XCP;
cu_YCP;
cu_XMax;
cu_YMax;

46
48
50
52

Ox2e
Ox30
Ox32
Ox34

WORD
WORD
WORD
WORD

cu_XRSize;
cu YRSize;
cu::::XROrigin;
cu_YROrigin;

54
56
58
60

Ox36
Ox38
Ox3a
Ox3c

WORD
WORD
WORD
WORD

62

Ox3e

*1
*1
cu_XRExtant; 1* maximum size
*1
cu_YRExtant; 1* of the text region *1
cu XMinShrink;
1* smaller
*1
cu::::YMinShrink;
1* unrelated *1
1* region by *1
1* Window Resize *1

WORD

cu_XCCP;

struct MsgPort

cu_MP;

1* character position *1
1* maximum character *1
1* position
*1
1* character size *1
1* start of the
1* text region

4.9 THE CONSOLE DEVICE

ABACUS

64 Ox40
WORD
cu_YCCP;
/* Cursor Position
66 Ox42
struct KeyMap
cu KeyMapStruct;
/* KeyMap
98 Ox62
UWORD
cu_TabStops[80];
/* Tab Positions
/* see RastPort Structure: */
178 Oxb2
BYTE
cu_Mask;
179 Oxb3
BYTE
cU_FgPen;
180 Oxb4
BYTE
cU_BgPen;
181 Oxb5
BYTE
cu AOLPen;
182 Oxb6
BYTE
cu=:DrawMode;
183 Oxb7
BYTE
cu_AreaPtSz;
184 Oxb8
APTR
cu AreaPtrn; /* Cursor Pattern
188 Oxbc
UBYTE
cu:)interms [8];
196 Oxc4
struct TextFont *cu_Font;
200 Oxc8
UBYTE
cu AlgoStyle;
201 Oxc9
UBYTE
cu::::TxFlags;
202 Oxca
WORD
cu TxHeight;
cu_Tx Width;
204 Oxcc
UWORD
206 Oxce
cu -TxBaseline;
UWORD
208 OxdO
cu-TxSpacing;
UWORD
210 Oxd2
UBYTE
cu Modes[3];
/* memory for modes
/* and RAW EVENTS
/* (respectively 1 Bit)
213 OxdS
UBYTE
cu RawEvents[3];
216 Oxd8
/* defined in "devices/conunit.h"

4.9.2.1

*/
*/
*/

*/

*/
*/
*/
*/

Console functions
The console device includes functions which can be accessed through
offsets. The ConsoleDevice = ConsoleRead->io Device
represents the basis address for these functions.
Offset
-Ox30
KeyMap)

Command
-------Ox2a

CDInputHandler(&InputEvent)
AO
Actual = RawKeyConvert(&InputEvent, Buffer, Length,
DO

AO

, Al

01

A2

CD Input Handle r () sends the event in the input device to the

current console window. For example, you can initialize an input event
structure and send it to the console device using CDInputHandler.
The input event's reaction can then be displayed by the console device.
CDInputHandler is similar to CMD_WRITE, except that
CDInputHandler displays event structures instead of strings.
CDInputHandler () calls RawKeyConvert () . This command
translates the input event into a string that begins at the B u f fer
parameter, and has a maximal length of Length. This specifies the
key map intended for conversion. Act ual contains the number of
characters which comprise the created string. If Act ual contains the
value -1, the buffer wasn't large enough to hold the string.

139

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

A console function can be called using the following syntax:

move.l _ConsoleDevice, a6
;initialize parameter
jsr
-$2a (a6)

4.9.2.2

More key codes

Take another look at the keymap illustration that appeared earlier in
this book. You'll notice that beside some undefined keyboard codes
there are also two reserved keyboard codes ($2b and $30). These
keyboard codes are intended for foreign characters.
In addition to the keyboard codes from OxOO through Ox67 there are
more codes that cannot be controlled through a keymap:
Ox68
Ox69
Ox6a

left mouse button

right mouse button
middle mouse button

These three key codes are never sent from the console device during
normal operation. First, if you turn on the RAW mode for the mouse
keypress with "<CSI>2{", you can add these key codes through the
control string that was received.

Ox80-0xe7

The key assigned a code ranging from OxOO to Ox67 was released (e.g.,
Ox80 for key OxOO). This code can only be received when the flag
KeF _DOWNUP (OxSO) is set for the key in KeyMapTypes.

Od9

The keyboard code last sent from the keyboard was incorrect

Oxfa

The internal keyboard buffer (10 characters) is full.

Odb

Keyboard catastrophe - fatal error.

Odd

Keyboard power-up (keys pressed during booting). This was sent from
Oxfd and Oxfe. (for example: Oxfd, Ox03, Ox04, Oxfe).

Ode

Keyboard power-up ended (keyboard initialized and all keys pressed in

the meantime are sent to the system).

Oxff

The mouse was moved (no button pressed).

140

4.10 THE CLIPBOARD DEVICE

ABACUS

4.10

The clipboard device

You have probably worked with the block movement operations
included in a word processor or text editor. Block operations require
some memory management. If you've ever thought about adding block
operations to your own programs. you may have changed your mind
when you thought about how complicated this memory management
can be.
The clipboard device offers a simple method of implementing block
commands. You allocate the block into which you want the clipboard
device to write. The clipboard device reserves this block until you
access it further or declare it as invalid.
The clipboard device can be opened as follows:
struct IOClipReq *ClipReq = OL;
'define CLIP_LEN (ULONG) sizeof(struct IOClipReq)
Open A Device(lIclipboard.device", Unit, &ClipReq, OL,
CLIP_LEN);

The clipboard device can only handle one unit at a time. Therefore. you
must open the clipboard device with different unit numbers, if you wish
to access more than one unit. The device block layout below will help
you understand how this works:
Offset

Structure

-------0
20
24
28
30
31
32

OxOO
Ox14
Ox18
Ox1c
Ox1e
Oxlf
Ox20

36

Ox24

40
44
48

Ox28
Ox2c
Ox30

52

Ox34

struct IOClipReq

struct Message io_Message;

struct Device * i o_Dev ice;
struct Unit
*io Unit;
io-Corrrnand;
UWORD
io-Flags;
UBYTE
UBYTE
io::::Error;
ULONG
io_Actual;

/* which unit? */

/* number of */
/*transferred bytes */
ULONG
io_Length; /* number of bytes to*/
/* transfer */
SPTR
io Data; /* data (Stringpointer)*/
ULONG
io::::Offset; /* Offset inside unit */
LONG
io_ClipID; /* identification number */
/* of the clip */
} /* defined in "devices/clipboard.h" */

The variables io_Message, io_Device, and so on may be

familiar to you from the previous section.

141

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The variables io_Offset and io_ClipID are of interest. The

clipboard device must reserve memory locations before it can save data
to memory. The io_Offset variable helps determine the position at
which the data was last read/written. io_Offset contains the byte
offset inside the clipboard device that gives the last read/write position.
This variable is similar to the fIle position used by DOS to detennine
the location of the flle. The i 0_Cl i p I D variable contains the number
of blocks that was a1ready written to the clipboard device, then deleted
from the clipboard device.
The following routine writes data to the clipboard using the
CMD WRITE command:
1***************************************************** *****

*
*
Function: Write data in the ClipBoard-Device n
*
*---------------------------------------------------------*
* Input - Parameter:
*
Clip_Write 0

(Clip_Support)

*
*

ClipReq: Device-Block
*
Data to be written
*
* Len:
Number of bytes to write
*
* FirstTime: TRUE => first write command
*
*
FALSE => write command of a sequence
*
*---------------------------------------------------------*
* Return value:
*

* Data:

* Number of data written

*
****************************************************** *****1
ULONG Clip Write (ClipReq, Data, Len, FirstTime)
struct IOClipReq *ClipReq;
APTR
Data;
LONG
Len;
BOOL
FirstTime;
{

if (First Time==TRUE)
ClipReq->io_Offset = 01;
ClipReq->io Data
= (STRPTR) Data;
ClipReq->iO-Length = Len;
Do_Command (ClipReq, (UWORD) CMD_WRITE);
return (ClipReq->io_Actual);

You must set the variables io_Offset and io_ClipID to zero on

the fIrSt write access. This prevents the clipboard device from acting
through another device. To infonn the clipboard device that all of the
data was written, a CMD_UPDATE command is sent after the
CMD_ WRI TE command. You can also write a larger block bit by bit to
the clipboard device.
The clipboard device now contains a block. This block can consist of
text, graphics or other data. If not enough memory was allocated to the

142

4.10 THE CLIPBOARD DEVICE

ABACUS

clipboard block, the clipboard device writes your block to disk, placing
it in the directory "SYS:devs/clipboards". The fIlename is the unit
number, notated as a decimal string (e.g., 0).
The following routine reads data from a clipboard device block using
the CMD_ READ command:
1***************************************************** *****

*
*
*

Clip_Read 0

(Clip_Support)

Funktion: Read data from ClipBoard-Device

*
*

*---------------------------------------------------------*

* Input - Parameter:
*
* ClipReq: Device-Block
* Data:
Data buffer
* Len:

*
*

Number of bytes to read

*
*
*

* FirstTime: TRUE => first read command

*
FALSE => read corrrnand of a sequence

*---------------------------------------------------------*
* Return value:
*
* Number of the data that was read (contains errors!)

***********************************************************1
ULONG Clip Read (ClipReq,Data, Len,FirstTime)
struct IOCIipReq *ClipReq;
APTR
Data;
LONG
Len;
BOOL
FirstTime;
{

if (FirstTime=TRUE)
ClipReq->io_Offset

= 01;

ClipReq->io Data
= (STRPTR) Data;
ClipReq->io-Length - Len;
Do Conunand (ClipReq, (UWORD) CMD READ);
return IClipReq->io_Actual);
-

The iO_Offset and io_ClipID variables must be set to zero on

the ftrst read access.
There is a bug in the clipboard device which we must mention here. A
zero is usually placed in iO_Actual to indicate that all of the data
bas been reael. Unfortunately, the clipboard device always takes the
value in io_Length and places it in iO_Actual. You must also
keep the number of bytes written in the footer yourself so that none of
the data is lost. In addition, you must read the data once with a value of
zero in io Length after all of the data bas been read. This serves to
end a read-sequence for the clipboard device when the value zero is
returned in iO_Actual. Because the value from io_Length is
always transferred into iO_Actual when reading, you must read zero
byteclata.

143

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

When you no longer need the block, you must execute the
CMD CLEAR command. This clears the data in the clipboard device and
increments the ClipID counter by one. For write and read accesses
you should only clear the i 0_0 f f set array. Do not write to
io_CUpID, for reasons which we'll explain in a moment.
Converting a large block to another format from the clipboard device
(e.g., conversion to IFF format) can take a lot of time. You can save
time by declaring a CUp (naming the transfer of data blocks in and out
of the clipboard device). First you specify the address of a message port
to the i 0 D a t a pointer. Through this message port you get a
Sati s fy message if the data available for use is needed by both parts.
This also sends a caD_ POS T command. The Sat i s fy message looks
like the following structure:
Offset

Structure
struct SatisfyMsg

o OxOO
20 0x14
22 Ox16
26 Oxla

struct Message sm Message;

UWORD
sm-Unit; 1* from which unit *1
LONG

sm::::ClipID;

You can then test for a received message using Message

GetMessage (ownPort). A received message is indicated by
(Message ! =0) If not, your program can continue with other
tasks. If a message has arrived, you must write the data into the
clipboaId device as described above. Remember that the clip announced
with POST is not needed in some cases. Meanwhile other blocks can be
written to and read from the clipboard device. This naturally changes the
io_CUpID variables.
When you want to get a POST command after receiving the Satisfy
message through a CMD_WRITE command, read the io_CUpID of
the current read command with caD CURRENTREADID. If this value
is larger than the io_CUpID variable of the device block, with which
the caD_POS T command is executed, your data is not needed.

If you want to test whether you should execute a previously sent POST
command before leaving the program, just read the i
C 1 i p I D.
Compare its contents with the io ClipID variable ofthe POST
device block. If the value returned from CURRENTWRITEID in
io_CUpID is larger than the CUpID variable of the POST device
block, the other CMD_ WRI TE commands are executed in the meantime
and the announced data transfer does not need to be executed

These two routines are combined to form the Clip_Support.c file,

remember to insert the following include files, exec/types.h,
exec/memory.h, exec/io.h, and devices/clipboard.h.

144

4.11 THE AUDIO DEVICE

ABACUS

4.11

The audio device

Y ou've probably heard about the fantastic sound capabilities of the
Amiga. Programming sound requires the use of the audio device. This
device allows you to send any wavefonn through the sound channels, at
any volume and of any duration.

The audio device can be opened using the following:

idefine AUDIO_LEN (ULONG) sizeof(struct IOAudio)
struct IOAudio *Audio_Request=OL;
Open A Device(ltaudio.device lt , OL, Audio_Request, OL,
AUDIOjJ::N) ;

The IOAudio device block through which the command is given and
developed looks like the following:
Offsets
0

OxOO

32
34
38
42
44
46
48
62

Ox20
Ox22
Ox26
Ox2a
Ox2c
Ox2e
Ox30
Ox3d

struct IOAudio
{/* defined in "devices/audio.h lt */
struct IORequest ioa_Request; /* IORequest to
begin */
WORD
ioa AllocKey;
UBYTE
*ioa-Data;
/* Data pointer */
ULONG
ioa-Length; /*size data field*/
UWORD
ioa-Period; 1* Frequency */
UWORD
ioa -Volume; /* volume * /
UWORD
ioa=eycles; /* cycles */
struct Message
ioa_WriteMessage;

The audio device supports the following commands:

ADCMD ALLOCATE
ADCMD FINISH
ADCMD FREE
ADCMD LOCK
ADCMD PERVOL
ADCMD SETPREC
ADCMD WAITCYCLE
CMD FLUSH
CMD READ
CMD RESET
CMD START
CMD STOP
CMD WRITE

(32)

allocate sound channel

(11)

end sound output

unlock sound channel
clean up before channel "stolen"
adjust period and volume
change channel precedence
wait for end of cycle
clear all write commands
find current writeIO block
reset audio hardware registers
start output
stop output
initialize sound output

(9)
(13)

(12)
(10)
(14)

(8)
(2)
(1)
(7)

(6)
(3)

145

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The audio device supports the following flags:

ADIOF PERVOL

(16)

set period and volume using

ADCMD ALLOCATE

ADIOF SYNCCYCLE
AD I OF_ NOWAI T

(32)
(64)

synchronize action with cycles

don't wait for ADCMD_ALLOCATE

The audio device supports the following errors:

ADIOERR NOALLOCATION
ADIOERR ALLOCFAILED
ADIOERR CHANNELS TOLEN

(-10)

AllocKey not understood

(-11)
(-12)

channel allocation failed

channel stolen by another

user

4.11.1

Allocating audio channels

The audio channels must be allocated for sound transmission. The audio
device has two methods of allocating the audio channels through which
the sound can be sent.

Audio channel
allocation:
Method one

OpenDevice () provides the first method. First the IOAudio

structure (the I/O block of the audio device) must be initialized.
Initialization through CreateExtIO () alone isn't enough here-the
lOA udi 0 structure must be opened as well. Next an attempt is made
to allocate the channels by calling OpenDevice () (Exec function).
This audio device block requires the address of your channel allocation
map. your audio channel reservation mask:
struct IOAudio *AudioReq;
char Channel_Map[ .. ] = ( );
AudioReq = (struct IOAudio *) GetDeviceBlock(AUDIO LEN);
AudioReq->ioa Data
= Channel Map;
AudioReq->ioa-Length = sizeof(Channel Map);
Open_A_Device(IIaudio.device ll , OL, AudioReq, OL, AUDIO_LEN);

A typical channel allocation map consists of up to 16 bytes, with

which you can determine channel allocation. The four lowest bits (the
low nibble) test for one of each of the bytes of the channels to be
allocated. If you want to send your wavefonn to a left and a right sound
channel, your allocation map would look like the following:

146

ABACUS

4.11 THE AUDIO DEVICE

'define Left Channel 0 1

1* Bit for first left channel
'define Right Channell 2
1* Bit for first right channel
'define Right-Channel-2 4
1* Bit for second right channel
'define Letf Channel 3 8
1* Bit for second left channel
UBYTE Channel Map[) - (Left Channel 0
Right Channell,
Left-Channel-O
Right-Channel-2,
Left -Channel-3
Right-Channel-1,
Left=Channel=3
Right=Channe1=2);

*1
*1
*1
*1

The channel_map array contains four entries (si zeof

(Channel_Map) == 4) that test a right and a left sound channel for
allocation. This array appeared in the previously initialized IOAudio
structure (see the ioa_data pointer). The number of entries in this
array is given through the ioa Length pointer. In this particular
case the length is four bytes. Thefollowing sequence is needed for the
allocation of the channels using OpenDevice () :
'define Left Channel 0 1
'define Right Channel 1 2
'define Right-Channel-2 4
'define Letf Channel 3 8
'define Precedence -40
'define AUDIO LEN sizeof(struct IOAudio)
UBYTE Channel-Map [)
{Left Channel 0 I Right Channell,
Left-Channel-O I Right-Channel-2,
Left-Channel-3 I Right-Channel-l,
Left-Channe1=3 I Right=Channel=2);
struct IOAudio *AudioReq;
AudioReq = (struct IOAudio *) GetDeviceBlock(AUDIO LEN);
AudioReq->ioa Data
= (UBYTE*)Channel Map;
AudioReq->ioa-Length = (ULONG)sizeof(Channel Map); 1* 4 *1
AudioReq->ioa=Request.io_Message.mn_Node.ln-p~i = Precedence;
Open_A_Device("audio.device", OL, &AudioReq, OL, OL);

Since we used GetDeviceBlock to take the audio block ourselves,

this does not have to be done through Open_A_Device (). This is
why we assign Open_A_ Dev ice () a value of zero as the size of the
audio device block.
Now the supplied audio channels are ready for use (in case
OurSounds->ioa_Request. io_Error == 0). You may have
been wondering what the following variable does in this device:

The above line controls the precedence of your sounds. The higher the
precedence number, the less chance of your channel being "stolen" by
another user. Stealing refers to another program allocating a sound
channel you already have allocated. If your channel has a high
precedence, a program trying to allocate your sound channel will be
rejected. If the other program has a precedence number higher than
yours, your channel must be released as soon as possible. Commodore-

147

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Amiga recommends the following precedence numbers for certain types

of sounds:
Precedeoce
number:

Sound
type

128

This precedence number is for the lazy programmer.

When your sounds run at a level of 127, no one can
access your allocated channels. You also don't have to
free the channels before leaving the program. Use this
number only when absolutely necessaryl

90 - 100

Emergency sounds. 'These sounds occur when a problem

occurs in an application (e.g., the application cannot
access a library).

80- 90

Announcements (e.g., the <Ctrl><G> bell).

75

Narrator device data (Le., speech).

50-70

Informational sounds or sonic cues.

-50 - +50

Music program data.

-70 - 0

Sound effects (e.g., explosions).

-100 --SO

Background music and ambient sounds.

-128

Total silence.

Audio channel The second method works through an audio device command We have
allocation:
placed this command (ADCMD_ALLOCATE) in an audio device support
Method two
function which looks like the following:
1***************************************************************
AUdio_Allocate ()
(Audio_Support) *

*
* Function: Allocate sound channels or audio device block
Prepare for allocation (OpenDevice)
*

*
*
*

*--------------------------------------------------------------*

* Input - Parameter:
* Audio Device Block:
* ChannEi"l Map:* Size: * Precedence:
* Wait:

Device-Block for allocation

Channel-allocations-mask
Size of the allocations-mask (BYTES)
Sound precedence (-127 - 128)
Wait for the desired channel to open?

*
*
*
*

*--------------------------------------------------------------*

* Return value:
*
* Error in command execution
*
***************************************************************/
BYTE Audio Allocate
(Audio Device Block,Channel Map,Size,Precedence,Wait)
struct-IOAudio
*Audio=Device_B1ock;

148

4.11

ABACUS

UBYTE

THE AUDIO DEVICE

*Channel_Map;
Size;

ULONG

BYTE
Precedence;
OOOL
Wait;
(

Audio Device Block->ioa Data

Channel Map;
Size; -

Audio~)evice=Block->ioa=Length

=
=

Audio Device Block->ioa Request.

io_Message.mn_Node.ln_Pri

= Precedence;

if (!Wait) 1* wait until channel is free? *1

Audio Device Block->ioa Request.io Flags
1= (UBYTE)
ADIOF Naru:T;
if-(Audio Device Block->ioa Request.io Device != OL)

Audio_Device_Block->ioa_Request.io_Command
ADCMD ALLOCATE;
-if (Wait) DolO (Audio Device Block);
else
--

(UWORD)

SendIO (Audio Device Block);

if (CheckIO(Audio De~ice Block) == 0) return
(ADIOERR ALLOCFAILED);
} return (Audio_Device_Block->ioa_Request.io_Error);
return (OxOO);

This routine sets the io_Data pointer (Channel_Map) and the

ioa_Length variable (size of the Channel_Map) as well as the
user assigned sound precedence. The NOWAIT flag (Wait =FALSE) is
also set to the user-assigned value. To allocate channels contained by a
higher precedence request while the NOWAI T flag is set, give
Ope n D e vic e () and AD C M D _ ALL 0 CAT E the error
ADIOERR_ALLOCFAILED as the return value or error flag
(AudioReq->ioa_Request. io_Error).

The unset NOWAIT flag waits until the request containing our channels
releases them. A small problem can occur when you use the NOWAIT
flag in conjunction with ADCMD_ALLOCATE, it cannot be used for
channel allocation with OpenDevice () You might think that by
returning the set NOWAIT flag ADCMD_ALLOCATE to the called
program, the channels can be allocated. This is done in case the
supplied channels are inaccessible, but unfortunately they wait for
ADCMD ALLOCATE.

We got around this error with the help of the SendIO () and
Check I 0 () commands. If channels should be released without delay,
we send a asynchronous request (SendIO () ) and check it immediately
to see if the sent command is executing, or if it was already processed.
If CheckIO () returns the value 0, that is one character for us that the

149

4.

ADVA.NCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

channels contain from others. Because we do not want to wait for the
channels to be released, the routine exits with the error
ADIOERR ALLOCFAILED.

If the channels could not be allocated, you get the bit combination of
the allocated channels in * Au d i 0_ D e vic e _ B 1 c k >ioa Request. io unit. It is important to know which channels
were actually allocated(more on this later). With multiple statements
of the channels to be allocated in the Channel_Map (up to 16),
ADCMD_ALLOCATE searches for the combination that requires the
least wait time.

If in the meantime some other program releases its sound channels,

ADCMD_ALLOCATE or OpenDevice () checks to see if some
successful allocation can be executed. This check results only when the
system is instructed to wait for released channels. Should the allocation
fail, the error variable of the Audio_Device_Block sets the
ALLOC_FAILED flag:
/***************************************************************

Audio_NoAllocO

(Audio_Support) *

* Function: Allocation succesful?

*
*--------------------------------------------------------------*
* Input - Parameter:
*

* Audio Device Block: Device-Bock to be tested

* Return value:

*
*

*------=------=------------------------------------------------*
*

* TRUE: No allocation
* FALSE: Allocation successful

*
*

***************************************************************/

BOOL Audio NoAlloc (Audio Device Block)

struct IOAudio
*Audio-Device-Block;
(
if Audio Device Block->ioa Request.io Error &
ADIOERR NOALr.Oc:ATION)
ADIOERR NOALLOCATION)
return (TRUE);
else
return (FALSE);

The AllocKey variable contains information about how many users

exist on the audio device when the computer is turned on (or reset).
When this AllocKey does not agree with the internally stored value
when an audio device command is executed, each audio device command
sends a NOALLOCATION error.
To avoid generating this error when you want to use a copy of the
original device block, this AllocKey is also copied when copying the
audio device block. Before we get to that, let's take a closer look at the
allocation. You can save work when allocating by using

ISO

4.11 THE AUDIO DEVICE

ABACUS

period
(frequency) and volume are also set. You can also do this for each
period with the help of an audio command.
OpenDevice () . When the ADIOF _PERVOL flag is set, the

4.11.2

Audio period and volume

The following routine demonstrates volume setting for the audio
device:
1***************************************************** **********
*
Audio Pervol ()
* Function: Set volume and frequency

(Audio Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
*

* Audio Device Block: Audio-Device-Block should be set for

*
volume and frequency
*
*
* Period:
Sample frequency
*
* Volume:
Volume
*
*--------------------------------------------------------------*
* Return value:
*

* Error encounter during commnad execution

***************************************************************/
BYTE Audio Pervol (Audio Device Block, Period, Volume)
struct IOAudio
*Audio_Device_Block;
UWORD
Period;
UWORD
Volume;
{

Audio_Device_Block->ioa_Request.io_Flags
ADIOF SYNCCYCLE;
Audio Device Block->ioa Period
Audio-Device-Block->ioa-Volume

(OOYTE)

=
=

Period;
Volume;

if (Audio Device Block->ioa Request.io Device != OL)

{ /* setting of-volume and-frequency */
Audio_Device_Block->ioa_Request.io_Command
(UWORD)
ADCMD PERVOL;
-DolO (Audio Device Block);
return (Audio_DeviCe_Block->ioa_Request.io_Error);
Audio Device Block->ioa Request.io Flags 1= ADIOF PERVOL;
1* ADIOF PERVOL must be-set for apenDevice() */
return (OxDD);

This routine can tell whether the volume should be set before or after
OpenDevice () The io_Device pointer as well as all unset
variables should equal zero before calling OpenDevice () , because
the allocation of the audio device block (GetDeviceBlock () ) has
been executed through AllocMem () with the MEMF PUBLIC and
MEMF_CLEAR parameters.

151

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Three options exist for setting the volume and period. The
ADIOF_PERVOL flag. used in conjunction with CMD_WRITE (sound
output) has the same function as when used in conjunction with
OpenDevice () . Before we get to the sound output itself. let's take a
closer look at the period and the volume.
We mentioned that the word period refers to the frequency of the sound
The period measurement requires a few simple calculations. For
example, a period value of 20000 means more than just an output of
20000 bytes per second. You can calculate the period from two items:
1.)

The number of bytes (samples) on which the waveform is

based.

2.)

The frequency at which the note(s) should be played

Look at the following equation:

1

Period

Sampling rate * 28 * 10- 8

The sampling rate is constructed from the number of bytes to be played

and the frequency at which these should be played
Here's an example:. You want to playa waveform created from 40
bytes. and you want this waveform played at 440 cycles per second.
This means that you want the waveform to sound at 440 Hz. or "A_
440" as it's called in the music dictionaries. To get the sampling rate
you do the following:
Sampling rate = 40 * 440 (40 bytes * 440 Hz)

The period is then calculated as follows:

Period

= _ _ _ _. .:;1_ _ __

40 * 440 * 28 * 10- 8

202.922 .. 203

The following routine performs period calculation. We wanted to

minimize floating point arithmetic. so we multiplied the above fraction
by 1()A8 (28*1()A8seconds = 280 nanoseconds [the time in which one
byte can be output]), and we get the following routine:
/***************************************************************

*
*

Audio_Period()

(Audio_Support) *

* Function: Calculate the number of bytes to play and

*
*
the frequency needed for it.
*
*--------------------------------------------------------------*
* Input - Parameter:
*

*
*

152

Bytes: Number of bytes to play

*
*

4.11 THE AUDIO DEVICE

ABACUS

* Hz: Frequency, at which the byte samples should be played *

*--------------------------------------------------------------*
* Return value:

*
*

* Calculated period

*~**************************************************** *********1

UWORD Period (Bytes, Hz)

UWORD
Bytes, Hz;
{

return UNORD) (1000000001 1 (Bytes * Hz * (UNORD)28);

Remember that this routine returns only variables of type UWORD.

The value region ranges from 0 to 65535. If the period is larger than
65535, only the lower 16 bits of the calculation are used. The top 16
bits are truncated (see hardware register). In certain cases this can be
done to very small values that lie outside of the allocated region. The
period may not be smaller than 124. The frequency with which the
bytes are displayed is found as follows:
Period = 100000000L/(Bytes*Hz*28)
<=> Hz
= 100000000L/(Bytes*Period*28)

Assuming that our waveform only consists of one byte, this is then
given as the highest frequency:
Hz

10000000L/(1*124*28) = 28800

s~-1;

We need a little more arithmetic to set the volume. The volume can
range from zero (soft) to 64 (loud). The volume curve is linear.

Note:

Set the period and volume to zero before using CMD_WRITE for the
fust time. If you don't do this, data displayed through CMD_ WRI TE
may also play over the sound channels as blips.

4.11.3

Play it
Now we come to the frequently mentioned CMD_WRITE command We
have also included this in a short routine:
1***************************************************** **********

Audio_Write()

(Audio_Support) *

* Function: OUtput data through channel

*
*--------------------------------------------------------------*
* Input - Parameter:
*
* AudiO_Device_Block: Device-Block
* WaveForm:
Addess of the waveform array
* WaveLength:
Number of bytes to play

*
*

*
153

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

* Cycles:
* ComeBack:

Number of waveform repetitions

Wait until end of CMD_WRITE (FALSE) ?

*
*

*--------------------------------------------------------------*

* Return value:

*
*

* Error during command execution

*
***************************************************************/
BYTE Audio Write (Audio Device Block, WaveForm, Wavelength,
Cycles, ComeBack)
struct IOAudio
*Audio_Device_Block;
UBYTE
*WaveForm;
Wavelength;
ULONG
Cycles;
UWORD
ComeBack;
BOOL
{

Audio- Device- Block->ioa- Data

Audio Device Block->ioa Length
AUdio-Device-Block->ioa-Cycles
Audio-Device-Block->ioa-Request.io Flags
Audio=Device=Block->ioa=Request.io=Command

= WaveForm;
Wavelength;
Cycles;
(UBYTE) 0;
= (OWORD)
=
=

CMD_WRlTE;

if (ComeBack) SendIO
else
0010

(Audio Device Block);

(Audio=Device=Block);

We must provide the device block with which the device was opened, as
with all of the audio_support routines.
WaveForm and WaveLength designate the waveform to be
displayed. WaveForm contains the starting address of the byte array in
which the wavefonn is located. WaveLength contains the number of
bytes needed to describe the wavefonn, rather than the wave length of
the resulting sound
Cycles designates the repetition rate of a wavefonn. For example, if
you want the given wavefonn to play only once, you must state the
value 1 for Cycles. The higher the value for Cycles, the more
times the wavefonn repeats.

When you want unlimited repetitions, enter the value zero for
Cycles. Then your wavefonn plays for eternity, assuming that your
channels aren't stolen. A change in the wavefonn can occur when the
indicated location is displayed Please remember that the sound data in
the chip memory must be released As you know, the address bus of the
custom chips (Blitter, Paula, Agnus, Denise, Copper) contains only 19
address connections. This addresses the bottom section of memory (or
the bottom 512K).

154

4.11 THE AUDIO DEVICE

ABACUS

4.11.4

Additional audio device features

Now you can produce sound on your Amiga. You can allocate the
necessary channels, detennine the frequency and volume and make the
data audible. Suppose you're working with your audio device and
suddenly you don't hear anything anymore, or you don't hear what you
expected to hear. The solution: You've been robbed of your channels.
What can you do? You can either leave the program, or reset the
computer if you cannot leave the program. One possibility exists for
consistently stealing channels, which involves the ADCMD _LOCK
command:
'define AUDIO LEN (ULONG) (sizeof(struct lQAudio
VOID *GetDeviceBlock();
1**************************************************************

*
Audio Lock()
* Function: Protect channel before new access

(Audio_Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
*
* Audio Device Block: Device-Block of the channels that
*
should be protected.

* Return value:
* Addess of the Lock

*
*

*
*--------------------------------------------------------------*
****************************************************** *********1

struct IOAudio *Audio Lock (Audio Device Block)

struct IOAudio
*Audio=Device=Block;
{

struct IOAudio *Lock;

Lock = (struct IOAudio *)GetDeviceBlock(AUDIO_LEN);
Audio Copy (Audio Device Block,Lock);
Lock->ioa_Request~io_Command = (UWORD)ADCMD_LOCK;
SendIO (Lock);
return (Lock);
ADCMD LOCK is a command that executes first when the allocated
channels are stolen. That means that as long as ADCMD _LOCK

executes, everything is OK. If you want to use your audio channels,

you should make sure you have access rights. The following routine
should help you:
/***************************************************************

AUdio_Channel_StolenO

* Function: Was channel stolen?

(Audio_Support) *

*
*

*--------------------------------------------------------------*

ISS

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

*
*
* Lock: Device-Block of the Lock, that should be tested.
*
*--------------------------------------------------------------*
* Return value:
* Input - Parameter:

*
*

*
*
*

TRUE: Channel was stolen => Exit progra

FALSE: Channel is under your control
*
****************************************************** *********1
800L Audio Channel Stolen (Lock)
struct IOAudio
*Lock;
{

if (CheckIO (Lock) != 0)
return (TRUE);
else
return (FALSE);

This short routine tests if the LOCK command has ended (CheckIO ()
!... 0) or if the access right consists of the allocated channels. You
may be wondering how you can OU!put the data if you locked the audio
channels. The ADCMD_LOCK command ends these channels when the
channels are stolen. Processing the two device commands with the
device block cannot be done at the same time.
A second device block must come into play. This is configured the
same as other device blocks, using GetDeviceBlock () Then it
must ensure that you can also use the new device block. For this we
have developed a copy function that also copies the AllocKey that is
necessary for identifying the user of the audio device:
1***************************************************** **********
*
Audio Copy ()
* Function: Device-Block copy-

(Audio Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
*
*
* Old Audio Block: Original
*
* New-Audia-Block: Copy
****************************************************** *********1
VOID Audio Copy (Old Audio Block, New Audio Block)
struct IOAudio *old-Audio-Block, *New-Audio-Block;
{

--

New Audio Block->ioa Request.io Device =

Old_Audio_Block->Ioa_Request~io_Device;

New Audio Block-d>ioa Request.io Unit =

Old_Audio_Block->ioa_Request.Io_Unit;
New Aiudio Block->ioa AllocKey =
Old_AudIo_Block->ioa_AllocKey;

When you want to leave the program. you cannot simply exit and leave
the locked channels locked. In certain cases this would hinder every
other sound output. because only channel applications with a lower

156

4.11

ABACUS

THE AUDIO DEVICE

precedence are executed. To prevent this from happening you must

release the locked channels again, as shown in the following routine:
1***************************************************** **********
*
Audio_Free()
(Audio_Support)

* Function: Remove protection from channels

*
*

*--------------------------------------------------------------*
* Input - Parameter:
*

* Lock:

Device-Block of the freed lock

*
*

***************************************************************/

VOID Audio Free (Lock)

struct IOAudio *Lock;
{

Lock->ioa Request.io Command

DolO (Lock);
-

(UWORD)ADCMD_FREE;

FreeDeviceBlock(Lock);

This routine frees the channels from your exclusive access and frees the
previously allocated device block. Another, less elegant option exists
for protecting channels from outside access: Set the precedence at 127.
You can do this during allocation, or using the ADCMD_SETPREC

command:
/***************************************************************

*
Audio SetPrecedence ()
(Audio Support) *
* Function: Chaneg precedence
*
*--------------------------------------------------------------*
* Input - Parameter:
*

* Audio Device Block: Device-Block

*
* Precedence:
New precedence
*
***************************************************************/
VOID Audio SetPrecedence (Audio Device Block,Precedence)
struct IOAudio
*Audio=Device=Block;
BYTE
Precedence;
{

Audio Device Block->ioa Request.io Message.mn Node.ln Pri

(BYTE)PrE;"cedence;
Audio Device Block->ioa Request.io Command
(UWORD)ADcMD_SETPREC;
DolO (Audio_Device_Block);

Each call of ADCMD SETPREC allows the check of ALLOCATE

commands whether or not the new precedence is less than the old
precedence. If this is the case, ALLOCATE can address the supplied
channels for you.
When setting the precedence at 127 (the highest precedence possible)
there is no chance for other ALLOCATE commands to get access to
your channels. This occurs because the precedence of the channels that
might steal them must be less than yours.

157

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

You now have the software means of writing your own sound
programs. The following example is an example sound program.
Combine the Audio_Support routines to form the Audio_Support.c
fIle, don't forget the proper include fIles. Be careful of the order of the
routines since Audio_Lock calls Audio_Copy.
1***************************************************** **********

*
*

SoundEdi tor. c
(c) Bruno Jennrich
August 1988

*
*

***************************************************************1
1***************************************************** **********

* Compile-Info:
* cc SoundEditor
* In SoundEditor.o Audio_Support.o Devs_Support.o -lc

*
*
*

***************************************************************1

ilinclude "exec/types.h"
'include "exec/memory.h n
'include "exec/devices.h"
ilinclude "intuition/intuition.h"
tinclude "intuition/intuitionbase.h"
tinclude "graphics/gfxbase.h"
tinclude "graphics/gfxmacros.h"
'include "devices/audio.h"
'define ScreenHeight 200L
/* Editor-Screen */
'define ScreenWidth 3120L
'define ScreenDepth 2L
'define ScreenMiode
OL
'define ERROR
100
'define AUDIO LEN
(ULONG) (sizeof (struct IOAudio))
VOID *OpenLibrary();
VOID *OpenScreen();
VOID *OpenWindow();
VOID *AllocMem();
VOID *GetDeviceBlock()
VOID *Audio Lock();
struct Screen *Screen=Ol;
struct Window *Window=Ol;
struct NewScreen NewScreen;
struct NewWindow NewWindow;
struct GfxBase
*GfxBase=Ol;
struct IntuitionBase *IntuitionBase=Ol;
/* Audio-Device relevant structures */
'define Left Channel 0 1
'define Right Channel 1 2
'define Right-Channel-2 4
'define Left Channel 3 8
'define SoundPrecedence (BYTE) -40
struct IOAudio *Left Side
=01,
*Right Side
=01,
*Left Lock
=01,
*Right Lock
=01;
BYTE *WaveLeft = 01;/* Wave form definition (signed) */
BYTE *WaveRight = 01;
UBYTE
Left_Channels[]
{Left_Channel_O, Left_Channel_3};
UBYTE
Right_Channels[]
(Right Channel I, Right Channel 2);
/*-Channel-Map */
/* allocat; right and left */
/* channels
*/
'define CHANNELS LEFT
(ULONG) sizeof ( Left_Channels)

158

4.11 THE AUDIO DEVICE

ABACUS

'define CHANNELS_RIGHT

(ULONG) sizeof (Right Channels)

1* Mask size *1

1***************************************************** **********

*
Closelt ()
* Function: Close and free everything

(User) *
*

*--------------------------------------------------------------*
* Input - Parameter:
* String: Error-String

*
*

****************************************************** *********1

VOID Closelt (String)

char
*String;
{
UWORD i;

UWORD *dff180 = (UWORD *)Oxdff180;

UWORD Error;

if (strlen (String) > 0)

for (i=O;i<Oxffff;i++) *dff180 = i;
puts (String);
CloseWindow (Window) ;
if (Window != OL)
if (Screen != OL)
CloseScreen (Screen);
if (GfxBase != OL)
CloseLibrary (GfxBase);
if (IntuitionBase != OL) CloseLibrary (IntuitionBase);
if (Left_Lock != OL)
Audio Free (Left Lock);
if (Right Lock != OL)
Audio-Free (Right Lock);
if (Left_Side != OL)
Close-A Device (~ft Side);
if (Right Side != OL)
FreeoevIceBlock (Right Side);
if (WaveLeft != OL)
FreeMem(WaveLeft,
(ULONG)ScreenWidth);
if (WaveRight != OL)
FreeMem(WaveRight, (ULONG)ScreenWidth);
exit (10);
1***************************************************** **********

InstallScreenWindow ()
Function: Editor Window and Screen initialization

(User) *

***************************************************************/

VOID Insta11ScreenWindow ()
{

NewScreen.LeftEdge
NewScreen.TopEdge
NewScreen.Width
NewScreen.Height
NewScreen.Depth
NewScreen.DetailPen
NewScreen.B1ockPen
NewScreen.ViewModes
NewScreen.Type
NewScreen.Font
NewScreen.Defau1tTit1e
NewScreen.Gadgets
NewScreen.CustomBitMap
NewWindow.LeftEdge
NewWindow.TopEdge
NewWindow.Width
NewWindow.Height
NewWindow.DetailPen
NewWindow.BlockPen
NewWindow.IDCMPF1ags
NewWindow.Flags
NOCAREREFRESH;
NewWindow.FirstGadget =

0;
0;
ScreenWidth;
ScreenHeight;
ScreenDepth;
1;

0;
ScreenMode;
CUSTOMSCREEN;
(struct TextAttr *) 01;
(UBYTE *) " (c) Bruno Jennrich";
(struct Gadget *) 01:
(struct BitMap *) 01;
0;
0;
ScreenWidth;
ScreenHeight;
1;
0;
0;
BORDERLESS I ACTIVATE I RMBTRAP I
(struct Gadget *) 01;

159

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

(struct Image *) 01;

(UBYTE *) n Waveform-Editor n;
(struct Screen *) 01;
(struct BitMap *) 01;

NewWindow.CheckMark
NewWindow.Title
NewWindow.Screen
NewWindow.BitMap
NewWindow.MinWidth
NewWindow.MaxWidth
NewWindow.MinHeight
NewWindow.MaxHeight
NewWindow.Type

0;
0;

0;
0;
CUSTOMSCREEN;

/***************************************************************

OpenScreenWindow ()

* Function: Screen and Window open

(User) *

***************************************************************/

VOID OpenScreenWindow ()
{

InstallScreenWindow();
Screen = (struct Screen *) OpenScreen (&NewScreen);
if (Screen == 01) Closelt ("Couldn4t get Screen !n);
NewWindow.Screen = Screen;
Window = (struct Window *) OpenWindow(&NewWindow);
if (Window == 01) Closelt ("Couldn4t get Window !n);
1***************************************************** **********

CloseScreenWindow ()

* Function: Screen and Window close

(User) *

***************************************************************/

VOID CloseScreenWindow()
{

CloseWindow (Window);
CloseScreen (Screen);
1***************************************************** **********

OpenLibs ()
Function: Open libraries

(User) *

***************************************************************/

VOID OpenLibs ()
{

GfxBase = (struct GfxBase *) OpenLibrary

(ngraphics.library", 01);
if (GfxBase = 01)
CloseIt ("Couldn4t get Grahpics ! n);
IntuitionBase =
(struct IntuitionBase *) OpenLibrary
(nintuition.library", 01);
if (IntuitionBase == 01) Closelt (nCouldn4t get Intuition
p.) ;
1***************************************************** **********

*
CloseLibs ()
* Function: Libraries close

(User) *

****************************************************** *********1

VOID CloseLibs ()
{

CloseLibrary (GfxBase);
CloseLibrary (IntuitionBase);

1***************************************************** **********
(User) *

*
The Audio Device ()
* Function: Use Audio-Device
-

****************************************************** *********1

160

4.11 THE AUDIO DEVICE

AIACUS

The_Audio_Device()
{

UWORD i,j;

Open A Device (naudio.device",OL,&Left Side,OL,AUDIO LEN):

Right Side = (struct IOAudio*) GetDevieeBlock (AUDIO:=LEN):
AUdio-Copy (Left Side,Right Side);
/* allocate channel */
if (Audio Allocate (Right Side,
Right=Channels,
CHANNELS RIGHT,
SoundPreCedence,
FALSE) == ADIOERR ALLOCFAILED)
CloseIt ("Couldn4t get Right-Channel !");
if (Audio Allocate (Left Side,
Left=Channels,
CHANNELS LEFT,
SoundPreCedence,
FALSE) == ADIOERR ALLOCFAILED)
CloseIt ("Couldn4t get Left-Channel !n):
/* secure channels before foreign access */
Left Lock = Audio Lock (Left Side);
Right Lock = Audio-Lock (Right Side):
if (Right Lock == 01) CloseIt ("Right Lock failed !"):
if (Left Lock == 01) CloseIt ("Left Lock failed !"):
/* No sound output */
Audio Pervol (Left Side, (UWORD) 0, (tJWORD) 0);
Audio-Pervol (Right Side, (UWORD) 0, (tJWORD)O);
/* Begin data output * /
Audio_Write (Left_Side,WaveLeft, ScreenWidth,
(UWORD) 0, (BOOL) TRUE):
Audio Write (Right Side,WaveRight, ScreenWidth,
(UWORD) 0, (BOOL) TRUE):
/* Increase volume */
Audio Pervol (Right Side, (tJWORD) 1500, (UWORD)64);
Audio=Pervol (Left~ide, (tJWORD) 1500, (tJWORD) 64);
/***************************************************************

*
Close Audio Device ()
* Function: Free channels and-close-Audio-Device

(User) *
*

***************************************************************/

Close Audio Device()

Audio Free (Left Lock);

Audio-Free (Right Lock);
C1ose-A Device (Left Side);
FreeoeviceBlock (Right_Side);
1***************************************************** **********

*
* Function: Wave form editor

Edit()

(User) *

***************************************************************/
Edit ()
{

WORD
ULONG

i;
x,y;

UBYTE *LeftMouse = (UBYTE *) OxbfeOOl;

UWORD *RightMouse = (UWORD *) Oxdff016;
Move (Window->RPort,OL,ScreenHeight/2L);
Draw (Window->RPort,ScreenWidth,ScreenHeight/2L):
for (i=O;i<ScreenWidth; i++)
{

WaveLeft [i] = 0;

161

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

WaveRight[i] = 0;
}

SetDrMd (Window->RPort, (ULONG) COMPLEMENT);

The Audio Device();
while *RightMouse , Ox0400) == Ox0400)
{

if (Audio Channel Stolen (Left Lock) I I

Audio- Channel-Stolen (Right Lock) )
CloseIt ("Chan~el stolen"); 1* In case challels were stolen! *1
if *LeftMouse , Ox40) == 0)
{

x = Screen->MouseX;
y = Screen->MouseY;
if (WaveLeft~x] != (ScreenHeight/2-y
(

Move (Window->RPort,x,ScreenHeight/2);
Draw (Window->RPort,x,ScreenHeight/2-WaveLeft[x]);
WaveLeft[x] = (ScreenHeight/2-y);
WaveRight[x] = WaveLeft[x];
Move (Window->RPort,x,ScreenHeight/2);
Draw (Window->RPort,x,ScreenHeight/2-WaveLeft[x]);

1***************************************************************
main()
(User) *
*
***************************************************************/

main 0
{

WaveLeft = (BYTE*) AllocMem (ScreenWidth, (ULONG)

MEMF CHIPIMEMF CLEAR);
WaveRight =-(BYTE*) AllocMern (ScreenWidth, (ULONG)
MEMF CHIPIMEMF CLEAR);
if WaveLeft == 01) I I (WaveRight == 01
CloseIt ("No Wave Buffer !");
OpenLibsO;
OpenScreenWindow();
Edit 0;
CloseScreenWindow();
CloseLibs () ;
FreeMem (WaveLeft, ScreenWidth);
FreeMem (WaveRight, ScreenWidth);

Double
buffering

The next program presents a novel method of sound generation. For

example, if you want to continuously play a sound, you know that
your Amiga simply hasn't enough memory for playing 30 minutes of
sampled sounds. Let's say you need a constant stream of background
sound. You can play multiple samples repeatedly, using
CMD_ WRI TE S. For example:
Audio Write (/* Sound 1 */)
Audio Write (/* Sound 2 */)
Audio-Write (/* Sound 3 */)

162

4.11 THE AUDIO DEVICE

ABACUS

This has a disadvantage: You can hear blips between the end of the
previous sound and the start of the next sound. This is because the
audio DMA channels pause long enough to look for the next ftle. This
can be heard in the form of noise between the end of the old
CMD_ WRI TE and the beginning of the new one.
You can create a double buffer for holding data. Double buffers are most
often used in graphic programming. When you employ the technique of
double buffering, these disturbing noises are no longer heard. The sound
output results in the following scheme:
Play start sound
Loop:
calculate new sound
(or load this from diskette)
send write command for the new sound
wait until the end of the old sound
(here the new sound is played)
calculate another sound
send write command for another sound
wait for the old sound
repeat loop

Write commands and copies from the device blocks are listed internally
and processed according to the order. For this reason the CMD_WRITE
command does not break out for the same channels. Here's the double
buffer program:
/***************************************************************

*
*

*
*
*

Double.c
(c) Bruno Jennrich
August 1988

* Compile-Info:
* cc Double
* In Double.o Audio Support.o Devs Support.o -lc

*
*

***************************************************************/

!tinclude "exec/types.h"
!tinclude "exec/memory.h"
!tinclude "exec/devices.h"
!tinclude "devices/audio.h"
IIdefine AUDIO_LEN
(ULONG) (sizeof (struct IOAudio
VOID *OpenLibrary();
VOID *AllocMem();
VOID *GetDeviceBlock();
VOID *Audio Lock();
/* Audia-Device relevant structures */
IIdefine Left Channel 0 1
idefine Right Channel 1 2
idefine Right=Channel=2 4
!tdefine Left Channel 3 8
IIdefine SoundPrecedence (BYTE) -40
Ide fine WaveLength1 3201
IIdefine WaveLength2 6001
struct IOAudio *FirstPlay
=01,
*SecondPlay
=01,
*FirstLock
=01,
*secondLock
=01;
char *FirstWave = 01;
/* Wave form definition (signed) */

163

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

char *SecondWave = 01;

{Left_Channel 0, Left Channel 3};
UBYTE
Channel s [ 1
/* Channel_Map */
/* link */
/* allocate channel */
(ULONG) sizeof (Channels)
'define CHANNEL SIZE
/* Mask size */
1***************************************************** **********

*
CloseIt ()
* Function: Close and free everything

(User) *
*

*--------------------------------------------------------------*
* Input - Parameter:
* String: Error-String

*
*

***************************************************************/

VOID Closelt (String)

char
*String;
{

UWORD i;
UWORD *dff180 = (UWORD *)Oxdff180;
UWORD Error;
if (strlen (String) > 0)
for (i=O;i<Oxffff;i++) *dff180 = i;
puts (String);
if (FirstLock != 0)
Audio Free (FirstLock);
Audio-Free (SecondLock);
i f (SecondLock ! = 0)
if (SecondPlay != OL)
FreeDeviceBlock (SecondPlay);
if (FirstPlay != OL)
Close A Device (FirstPlay);
if (FirstWave != 0)
FreeMem-(FirstWave,WaveLengthl);
FreeMem (SecondWave,WaveLength2);
if (SecondWave != 0)
exit (10);
1***************************************************** **********
*
The_Audio_Device!)
(User) *

* Funktion: Use Audio-Device

*
*

***************************************************************/

The_Audio_Device()
{

UWORD i, j;
UBYTE *bfeOOl = (UBYTE*) OxbfeOOl;
FirstPlay = (struct IOAudio *) GetDeviceBlock (AUDIO_LEN);
SecondPlay = (struct IOAudio *) GetDeviceBlock (AUDIO_LEN);
FirstPlay->ioa Data
= (UBYTE *)Channels;
FirstPlay->ioa-Length = CHANNEL SIZE;
FirstPlay->ioa-Request.io Message.mn Node.ln Pri =
SoundPrecedence; Open_A_Device ("audio.device",OL,&FirstPlay,Ol,Ol);
Audio Copy (FirstPlay,SecondPlay);
FirstLock = Audio Lock (FirstPlay);
SecondLock = Audio-Lock (SecondPlay);
/* No sound output-*/
Audio Pervol (FirstPlay, (UWORD) 0, (UWORD) 0);
for (i=O;i<WaveLengthl;i++)
FirstWave[il
= 0;
for (i=0;i<WaveLength2;i++)
SecondWave[il
= 0;
Audio Pervol (FirstPlay, (UWORD) 1500, (UWORD)64);
for (i=0;i<WaveLengthl;i+=2) FirstWave[il = 128;
for (i=0;i<WaveLength2;i+=4) SecondWave[il = 128;
/* Calculate FirstWave (already done ) */
Audio_Write (FirstPlay,FirstWave, (ULONG) 320,
(OWORD) 1, (BOOL) TRUE);

164

4.11 THE AUDIO DEVICE

ABACUS

while *bfe001 , Ox40)

== Ox40)

/* Calculate SecondWave (already done) */

Audio Write (SecondPlay,SecondWave, (ULONG) WaveLength2,
-

(UWORD) 1, (BOOL) TRUE);

WaitIO (FirstPlay);
/* FirstWave new calculation (not already done here!) */
Audio Write (FirstPlay,FirstWave, (ULONG) WaveLength1,
(UWORD) 1, (BOOL) TRUE);
WaitIO (SecondPlay);
Audio Free (FirstLock);
Audio:=Free (SecondLock);
FreeDeviceBlock (SecondPlay);
Close_A_Device (FirstPlay);

1***************************************************************
*
main 0
(User) *
***************************************************************/
main()
I
FirstWave = (BYTE *) AllocMem
(WaveLength1, (ULONG)MEMF CHIPIMEMF CLEAR);
SecondWave = (BYTE *) -AllocMem (WaveLength2, (ULONG)MEMF CHIP IMEMF CLEAR);
if (FirstWave == 0) CloseIt ("No Memory for Wave 1 ! ");
if (SecondWave == 0) Closelt ("No Memory for Wave 2 !");
The Audio Device();
FreeMem (FirstWave,WaveLength1);
FreeMem (SecondWave,WaveLength2);

The audio device uses commands other than those described above.
These are not especially important. and you may never need them.
We1llist the rest for the sake of completeness. though:
1***************************************************************
*
Audio Read()
* Function: Find out actual Write-Device-Block

(Audio Support)*
*

*--------------------------------------------------------------*
* Input - Parameter:
*
*

* ReadRequest: Device-Block
* Channel:
Channel (0,1,2,3) whose Write-Block should
*
be found

* Return value:
* Addressof the Device-Block, for the output of the given
* channel or -1 if no CMD WRITE is in operation

*
*

*--------------------------------------------------------------**

***************************************************************1
UBYTE *Audio Read (Read Request,Channel)
struct IOAudio
*Read:=Request;
ULONG
Channel;
I
Read Request->ioa Request.io Unit
(struct Unit *)
Channel;
printf (nio Unit %ld\n",Read Request->ioa Request.io Unit);
Read_Request->ioa_Request.io:=Flags
(uBYTE)
ADIOF SYNCCYCLE;
Read Request->ioa Request.io Command = (UWORD) CMD_READ;
DOIO-(Read Request);
if (Read_Request->ioa_Request.io_Error != 0)

165

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

return UBYTE*)Oxffffffff);
return(Read_Request->ioa_Data);

This function gives you the address of the audio device block. The
device block is necessary for sound output on a specific channel. The
bit belonging to the channel is given in the channel and passed to the
unit element of the audio device block. After CMD_READ. either the
address of the audio device block that propels a CMD_ WRI TE command
to the given channel or the value zero is in i oa_ Da t a when the given
channel is not currently described.
The CMD_READ function determines the sound precedence of another
audio device user. This helps improve your odds of getting a channel.

ADCND WAITCYCLE
The above routine syncronized the execution of the command with the
end of the sound output using the SYNCCYCLE flag. We can also
perform this synchronization through an audio device command:

This command first returns to the program when the played cycle ends.

ADCND RESET
This command resets the audio device to exit status:

The CMD_FLUSH command is executed, the sound interrupt vectors are

initialized again, and a previous CMD_STOP command is executed.

CND FLUSH
This command stops all current write requests and all of the listed
(double buffering) write requests:

This command ends the sound output:

1***************************************************** **********
*
Audio Finish ()
* Function: Stop sound output -

(Audio_Support) *

*--------------------------------------------------------------*
* Input - Parameter:
* AudiO_Device_Block: Device-Block, whose sound should be
*
stopped
* Sync:
Is end of sound schronized with end of
cycle
*

*
*
*
*
*

***************************************************************/
VOID Audio Finish (Audio Device Block,Sync)
struct IOA~dio
*Audio=Device=Block;

166

4.11 THE AUDIO DEVICE

ABACUS

Sync;

BOOL
{

Audio Device Block->ioa Request.io Command

(UWORD)ADCMD FINISH;
if (Sync)- Audio Device Block->ioa Request.io Flags 1=
(OOYTE) ADIOF SYNCCYCLE;
else
- Audio Device Block->ioa Request.io Flags &=
(OOYTE)-ADIOF_SYNCCYCLE;
-

If you want to synchronize the interruption of the actual sound with the
end of the sound output, you must give the value TRUE as the Sync
parameter in Audio_Finish (). Now the SYNCCYCLE flag is seL
This flag is responsible for the synchronization. ADCMD_FINISH
ensures that the listed write requests are acquired for execution. That is
the difference between this command and CMD FLUSH.

am

START

and

CMD STOP

These commands stop (Do_Command (Audio_Device_Block,

(DWORD) CMD_STOP)andstart(Do_Command(Audio_Device
_Block, (UWORD) CMD_STOP) sound outpuL

4.11.5

Sound in the interrupt code

The following audio device commands cannot be used in conjunction
with interrupt level 5 or higher:
ADCMD FINISH
ADCMD FREE
ADCMD LOCK

(not used in the interrupt code!)

(not used in the interrupt code!)

ADCMD PERVOL

ADCMD SETPREC
ADCMD WAITCYCLE
CMD FLUSH
CMD RESET
CMD START
CMD STOP
CMD WRITE

(not used in the interrupt code!)

This appears to be completely logical since the interrupts that announce

that the DMA is done with sound output lies on level 4. The interrupts
with higher CPU priorities should be reserved by the system.

167

4.

DEVICES

4.12

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The narrator device

Now we come to a derivative of the audio device: the narrator device.
The narrator device makes it possible for you to access the speech
synthesizer of the Amiga. Unfortunately this synthesizer only speaks
one form of English. If you want to output sentences in different
accents or even foreign languages, the speech comes out in plain, media
English.
Through some tricks you can get the synthesizer to speak a somewhat
understandable accent, or even a foreign language. The synthesizer's
speech system is conslructed of phoneme codes. This means that each
sound has a specific phoneme code (e.g., "a", "t"). By assembling these
codes in the correct order, words and sentences can be made.
Because literal translation of words into phonemes can become very
complicated, Commodore supplied the translator library which contains
the t ran S 1 ate () routine as a single command. This routine
translates all of the English words in your phoneme codes.
T ran S 1 ate () can translate most of the words in the English
language. Because there are also some irregularities in the English
language, translate () also uses its own table to convert words.

Translate () also governs the different phonetics. Take the phrases

"the car" and "the others". The word "the" in "the car" ends with a short
E sound because the following word begins with a consonant. The word
"the" as it appears in "the others" ends with a long E sound because the
next word begins with a vowel. The phonemes are: DHAX CAA3R
(the car) and DHIY AH2DHERZ (the others).
After the translator library opens (TranslatorBase
OpenLibrary ("translator. library", 0,
t ransla te () is called with the string to be spoken, the string's
length and the address of the memory region for the phoneme as well as
its length:
char *String;
/* Ends with a null */
char Phoneme[lOOO];
'define LEN sizeof(Phoneme)
Error = Translate(String, strlen(String), Phoneme, LEN);

If enough memory exists for the phoneme, Error contains the value
zero. If E r ro r is unequal to zero, the absolute value of the error
(Error is given with a minus sign) gives the location in the input

168

4.12

ABACUS

THE NARRATOR DEVICE

string that can no longer be translated because of insufficient phoneme

memory. The example above could have made out this location using
String[-EtmrJ. If we add this data, we can find the error:
Error = Translate (&String[-Error], strlen (&String[-Error]),
NewMemory, Length);

You can then output the phoneme string that was created from
Translate through the narrator device. For this you must open the
narrator device:
ide fine NARRAT RB LEN sizeof(struct narrator_rb)
struct narrator_rb *WriteRequest = OL;
Open_A_Device("narrator.device", OL, &WriteRequest, OL,
NARRAT_ RB_LEN) ;

The narrator device block (n a r rat 0 r _ r b) has the following

structure:
Offset

Structure
struct narrator rb
!/* defined in "devices/narrator.h" */

0
14
16
18
20
22
26
28
30
32
33

OxOO
OxOe
OxlO
Ox12
Ox14
Ox16
Oxla
Oxlc
Oxle
Ox20
Ox21

struct IOStdReq message;

/* as always !
/* Words per minute
UWORD
rate;
UWORD
pitch;
/* basic frequency
UWORD
mode;
/* human//robotics
/* sex
UWORD
sex;
UBYTE
* ch_masks;
/* Channel Allocation Map
UWORD
nm_masks;
/* sizeof (ch masks)
/*-volume
UWORD
volume;
UWORD
sampfreq;
/* Sampling Frequency
/* Mouth form Flag
UBYTE
mouths;
UBYTE
/* Which channel was
chanmask;
/* actually used
UBYTE
numchan;
/* how many masks?
UBYTE
pad;
/* for even address

34 Ox22
35 Ox23
36 Ox24

*/
*/
*/

*/
*/
*/
*/

*/
*/

*/
*/
*/
*/

*/

The narrator device uses the above device block mainly for output. For
reading it uses another block:
Offset

Structure

-------{f*

0
36
37
38
39
40

OxOO
Ox24
Ox25
Ox26
Ox27
Ox28

struct mouth rb
defined in "devices/narrator.h" */
narrator_rb voice;
struct
UBYTE
width;
/* Mouth width */
UBYTE
height;
/* Mouth height */
shape;
/* internal ! */
UBYTE
pad;
/* even address */
UBYTE

As you can see from the name of this structure (mouth) and the
comments, this structure reads the mouth form created through the
spoken word.

169

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Now we come to the narrator device commands themselves. The most

important command is CMD_WRITE. This command allows the
phoneme code to be output:
'define MOUTH RB LEN
(ULONG) sizeof(struct mouth_rb)
1***************************************************** *****/
1*
Narrator Write ()
(Narrat Support) * I

1*
*1
1* Function:
Narrator-Output
*1
1*--------------------------------------------------------*1
1* WriteRequest: IO-Block, through twhich the speech
*1
1*
output should be directed
*1
1* string:
string to be output
*1
1* rate:
Words per minute (40-400)
*1
1* pitch:
Basic tone pitch (65-320)
*1
1* mode:
robot (1) or natural (0)
*1
1* sex:
Sex (0 manl11 female)
*I
1* Channels:
Channel-Map
*1
/* Size:
sizeof (Channel-Map)
*/
/* vol:
Vlourre (0-64)
*/
/* freq:
Output frequency (5000-28000)
*I
1* mouths:
Generate mouth form (1)
*1
1***************************************************** *****/
VOID Narrator Write
(WriteRequest,string, rate, pitch, mode, sex,Channels,Size,vol,freq,
mouths)
struct narrator rb
*WriteRequest;
char
*string;
UWORD
rate, pitch, mode, sex;
UBY'l'E
*Channels;
UWORD
Size,vol,freq,mouths;
(

struct mouth_rb *ReadRequest;l*

UBYTE SpokenString[1000];
/*
ULONG Mouth_Rout_Count;
1*
/*
WriteRequest->rate
WriteRequest->pitch
WriteRequest->mode
WriteRequest->sex
WriteRequest->ch_masks
WriteRequest->nm masks
WriteRequest->volurre
WriteRequest->sampfreq
WriteRequest->mouths

Request for mouth form

Phonetic memory
how often was
Mouth_Routine() called
= rate;
= pitch;
= mode;

*1
*/

*1
*1

sex;

Channels;
Size;
vol;
freq;
= mouths;

if (Translate (string, (ULONG) strlen

(string),SpokenString,1000L) != 0)
Closelt ("TranslateError");
/* phonetic English string *1
WriteRequest->rressage.io Data
WriteRequest->rressage.io-Length
(SpokenString) ;
WriteRequest->message.io_Command
i f (mouths == 1)

170

(APTR) SpokenString;
(ULONG) strlen
(UWORD) CMD_WRITE;

/* for Mouth form generation *1

4.11

ABACUS

THE NARRATOR DEVICE

ReadRequest = (struct mouth_rb *) GetDeviceBlock

(MOUTH_RB_LEN) ;

Narrator_Copy (WriteRequest, ReadRequest);

1* Prepare ReadRequest *1
Mouth_lnit();
1* Mouth-Routine initialization *1
ReadRequest->width
ReadRequest->height
ReadRequest->voice.message.io Command
ReadRequest->voice.message.io-Error
I*-Prepare

- (UBYTE) 0;
= (UBYTE) 0;
= (UWORD) CMD READ;

= (UBYTE) 0; Read command *1

if (SendlO (WriteRequest) != 0) Closelt ("SpeakError

1* send Write command *1
Mouth_Rout_Count

0:

U );

1* Mouth-Routine called 0 times *1

while (ReadRequest->voice.message.io Error != ND NoWrite)

--

DolO (ReadRequest):
Mouth Routine (ReadRequest->width, ReadRequest>height,Mouth Rout Count);
-1* as long as it can be read, it is read *1
1* and Mouth Routine() is called
*1
Mouth_Rout_Count++;
FreeDeviceBlock (ReadRequest);
Mouth_Expunge();

1* End Mouth_Routine *1
else DolO (WriteRequest):

1* no mouth form generation *1

1* only speech output
*1
The routine joins the speech output (CMD_WRITE) with the discovery
of the mouth form (CMD_READ). Next the necessary parameters are set
in WriteRequest. and in the speech output requirement. Parameters
like Channels. Size and Vol are self-explanatory. or were described
in Section 4.11. We11 look at the other parameters used in this routine.
The fIrst parameter to be given from N a r rat a rW r i t e () is the
narrator device block (for the writing or for the speech output)
initialized from Open_A_Device () . The string that should be
output follows in letters (not in phonemes).

Rate represents the number of words per minute output. The larger
rate is. the faster the words are spoken. Values for rate can range
from 40 to 400.
The pi tch parameter represents the pitch at which the Amiga should
speak. Values for pi tch range from 65 to 320.
A natural voice deviates from its standard pitch (Le. the voice's pitch
,raises and lowers). The mode parameter controls this deviation. If you
want the Amiga voice to speak in a monotone fashion. set the mode

171

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

parameter to 1. Setting the mode parameter to 0 enables natural

speech.
The sex parameter specifies the gender of your computer voice.
Setting sex to 1 enables the female voice, while setting sex to 0
enables the Inale voice.
The f req parameter controls the frequency at which speech synthesis
works. The higher this frequency is, the better and more natural the
output sounds. The more exact and precise the waveforms for the
speech output are calculated or output, the better the result sounds. For
example, with a f req of 5000 you cannot actually understand what
was said. A freq equal to 28000 gives the best result (for the Amiga).
The last parameter for Narrator_Write () tells if the mouth form
should be read (mouths = 1). Just as you move your mouth when
speaking, you can instruct the Amiga to display a mouth on the screen
as it speaks. We'll work more with the mouth at a later time. For now,
let's see what happens to the speech output.
Next the variables given above (vol, freq, sex, etc.) must be added
to the WriteRequest (10 block of the narrator device). Then we can
translate the string to be output using Translate (). Now we need
the phoneme code, ended by a null character. It was also ended with the
string end character ~, in which the i 0 _ D a t a pointer of the
Wr it e Reque s t is given as well as the length of this string in the
io_Length variable of the Wri teRequest.
After determining the command (WriteRequest->message. io_
Command = (UWORD) CMD_WRITE;) the speech output can be
started by means of DolO () . In addition to this simple case (only
speech output), Na r rat 0 r _ Wr i t e () offers another option for
fmding the mouth form. This is, as mentioned above, accessed from the
Narrator_Device () by meanSOfCMD_READ.
When you have set the parameter mouths to 1, a ReadRequest and
a device block are created for reading (GetDeviceBlock () ). Then
the variables io_ uni t and io_Device are copied from the original
device block into the ReadRequest. Here are the frrst two lines of
the function's defmition:
VOID Narrator Copy (Old Request, New Request)
struct narrat;r rb *Old-Request;
struct mouth rb*New Request;
{
}
-

...

After the ReadRequest the routine Mouth_init () is called. This

routine belongs to the Mouth_Init (), Mouth_Routine () and
Mouth_Expunge () commands. These routines are required for

172

4.12 THE

ABACUS

NARRATOR DEVICE

mouth formation. For example, in Mouth_lni t () screens and

windows are opened in which the mouth movement from the
Mouth_Routine () is drawn. When the speech output ends, the
screens and windows opened from Mouth_ I ni t () are closed again
from Mouth_Expunge ( ) .
Before we call Mouth_Routine () or Mouth Expunge () , we
must ftrst process the ReadRequest. Next the mouth form must be
initialized. The mouth form given by the width and height of the
mouth must be set to zero. Next we assign the ReadRequest block
its task, speaking the command to be executed (CMD_READ).
Now we read the mouth form until the previous Wri te command
ends, and also until the last word is spoken. When the narrator device
has nothing more to say, the error ND _N oWr i t e is encountered when
trying to read more mouth forms. CMD _READ is a synchronized
command and should be called through DolO () . DolO () returns with
CMD_READ if a mouth form change is encountered.
When such a change has been found, the routine Mouth_Routine ()
is called in N a r rat 0 r _ writ e ( ) , and the width, height and the
number of the call of this routine is given. The following program uses
the previously prepared narrator write routine:
/************************************************/

/*
/*
/*

The-Narrator-Device
(c) Bruno Jennrich

*/
*/
*/

/************************************************/

1************************************************/
/* Compile
info:
*/

/*----------------------------------------------*/

/* cc Say.c
*/
/* In Narrat Support.o Say.o Devs Support.o -lc */
/************************************************/

#include "exec/types.h"
#include "exec/types.h"
#include "exec/memory.h"
ilinclude "exec/devices.h"
hnclude "intuition/intuition.h"
hnclude "intuition/intuitionbase .h"
hnclude "graphics/gfxbase.h"
#include "graphics/gfxmacros.h"
#include "libraries/translator. h"
#include "Narrat_Support.h"
#include "devices/narrator.h"
#define WIDTH 150
/* size of the mouth window */
ildefine HEIGHT 75
/* functions used */
VOID *OpenLibrary();
VOID *OpenWindow();
OL; /* Libraries*/
struct Library
*TranslatorBase
struct IntuitionBase *IntuitionBase
OL;
OL;
*GfxBase
struct GfxBase
/* Window Defs */
NewWindow;
struct NewWindow
OL;
struct Window
*Window

173

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

OL; /* Narrator device

blocks */
/* Channel allocations
UBYTE Channels[4] = {3, 5, 10, 12};
mask */
/* see Audio Device
*/
#define MOUTH RB LEN
(ULONG) sizeof(struct mouth rb)
/* how often was */
ULONG Mouth_Rout=Count;
/* Mouth Routine() called */
1***************************************************** *****/
/*
Closelt ()
(User) * /
/*
*/
/* Function: Free all of the allocated structures
*/
/*--------------------------------------------------------*/
/* String:
Error message
*/
1***************************************************** *****/
VOID CloseIt(String)
char
*String;
struct narrator rb

*WriteRequest

UWORD Error = 0, i;
UWORD *dff180
(UWORD *)Oxdff180; /* background color
register */
if (strlen(String) > 0)
{

for (i=O;i<Oxffff;i++) *dff180 = i;/* screen blink */

puts (String);
/* display string */
Error = 100;
/* Error Code != 0 (EXIT( */
if WriteRequest != OL) && (WriteRequest->message.io_Device
!= OL
Close A Device (WriteRequest);
if (TranslatorBase != OL)
CloseLibrary(TranslatorBase);
exit (Error);
/**********************************************************/

/*
Mouth Init ()
(User) * /
/* Function: Mouth initialization routine
*/
1**********************************************************1
VOID Mouth_Init()
{

if GfxBase = (struct GfxBase *)

OpenLibrary("graphics.library", OL == 0)
CloseIt ("No Graphics !!! ");
if IntuitionBase = (struct IntuitionBase *)
OpenLibrary("intuition.library", OL ==0)
CloseIt("No Intuition!! !");
NewWindow.LeftEdge
640/2-WIDTH/2;
NewWindow.TopEdge
200/2-HEIGHT/2;
WIDTH;
NewWindow.Width
NewWindow.Height
HEIGHT;
NewWindow.DetailPen
0;
NewWindow.BlockPen
1;
NewWindow.IDCMPFlags
0;
NewWindow.Flags
ACTIVATE I RMBTRAP I NOCAREREFRESH;
NewWindow.FirstGadget
(struct Gadget *) OL;
NewWindow.CheckMark
(struct Image *) OL;
NewWindow.Title
(UBYTE *) " Mouth-Shape";
NewWindow.Screen
(struct Screen *) OL;
NewWindow.BitMap
(struct BitMap *) OL;
NewWindow.MinWidth
0;
NewWindow.MaxWidth
0;
NewWindow.MinHeight
0;

174

4.12 THE NARRATOR DEVICE

ABACUS

NeWWindow.MaxHeight
= 0;
NeWWindow.Type
= WBENCHSCREEN;
if Window = (struct Window
OpenWindow(&NewWindow
Closelt (IfNo Window !!! If);
SetAPen(Window->RPort, 2);
SetDrMd(Window->RPort, (ULONG) (COMPLEMENTIJAM1;

*)

0)

1***************************************************** *****/

/*

Mouth Expunge ()

/*

(User) * /

/* Function:

*/

Mouth Expunge Routine

*/

1**********************************************************1

VOID Mouth Expunge()

{
if (Window != OL)
CloseWindow(Window);
if (GfxBase != OL)
CloseLibrary(GfxBase);
if (IntuitionBase != OL) CloseLibrary(IntuitionBase);
/**********************************************************/

/*
/*
/* Function:

Mouth Routine ()
Mouth Routine

/* width:
/* height:

Mouth form width

Mouth form height

(User) * /
*/
*/

/*--------------------------------------------------------*/

*/
*/

/**********************************************************/

VOID Mouth_Routine(width, height, Count)

UBYTE
width, height;
ULONG
Count;
{

static ULONG old width,

if (Count != OL)I
/* erase old shape */
Move (Window->RPort, (ULONG)
height;
Draw (Window->RPort, (ULONG)
(ULONG) (HEIGHT/2+height;
Move (Window->RPort, (ULONG)
(ULONG) (HEIGHT/2;
Draw (Window->RPort, (ULONG)
(ULONG) (HEIGHT/2;

(WIDTH/2),

(ULONG) (HEIGHT/2-

(WIDTH/2),
(WIDTH/2-width),
(WIDTH/2+width),

/* draw new shape*/

width *= 2;
WaitTOF ();
Move (Window->RPort, (ULONG)
height ;
Draw (Window->RPort, (ULONG)
(ULONG) (HEIGHT/2+height;
Move (Window->RPort, (ULONG)
(ULONG) (HEIGHT/2;
Draw (Window->RPort, (ULONG)
(ULONG) (HEIGHT/2;
old width
(ULONG) width;
old=height = (ULONG)height;

(WIDTH/2),

(ULONG) (HEIGHT/2-

(WIDTH/2),
(WIDTH/2-width),
(WIDTH/2+width),

1*****************************************************/

/*
The Narrator Device ()
(User) * /
/*
*/
/* Function: use narrator device
*/
/*---------------------------------------------------*/

175

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

1*
1*
1*
1*
1*
1*
1*
1*
1*
1*

*1
*1
*1
*1
*1
*1
*1
*1
*1
*1

Input Parameters:
string:
rate:
pitch;
mode:
sex:
vol:
freq:
mouths:

output string
Words per minute
basic frequency
robotic or human
sex
volume
Sampling frequency
generate mouth form?

1*****************************************************/

VOID The Narrator Device(string, rate, pitch, mode, sex, vol,

freq, mouths)
char
*string;
UWORD
rate, pitch, mode, sex, vol, freq, mouths;
(

TranslatorBase
OpenLibrary(ntranslator.library", OL);
if (TranslatorBase == OL) Closelt ("NoTranslatorBase n );
Open_A_Device(nnarrator.device n , OL, &WriteRequest, OL,
MOUTH RB LEN);
Narrator Write
~rlteRequest, string, rate, pitch, mode, sex, Channels,
(UWQRD)sizeof (Channels), vol, freq, mouths);
Close A Device(WriteRequest);
CloseLibrary(TranslatorBase);
/*****************************************************/

1*
AtoUWORD ()
(User) * 1
1*
*1
1* Function: change number string (ASCII) after UWORD*I
1*---------------------------------------------------*1
1* Input Parameters:
*1
1*
*1
1* Bufpointer: number string to change
*1
1*---------------------------------------------------*1
1* Return value: value of the numeral string
*1
/*****************************************************/

UNORD AtoUNORD(BufPointer)
char
*BufPointer;
{

UWOlID Result;
Result = 0;
while (*BufPointer

, ') BufPointer++;

1* read over Spaces

*1
while (*BufPQinter != '\000')
{

Result *= 10;
Result += * (BufPointer++) - '0';
return (Resul t) ;
/*****************************************************/

1*

main()

*1

/*****************************************************/

main (arge, argyl

UIiiJORD arge;
char
**argv;
{

UWORD Param[7];
ULONG i;

Param[O]
Param[l]

176

DEFRATE;
DEFPITCH;

1* rate
1* piteh

*1 1* Defaults *1
*1

4.12 TID: NARRATOR DEVICE

ABACUS

Pararn[2]
DEFMODE;
1* mode
*1
Pararn[3]
DEFSEX;
1* sex
*1
Pararn[4]
DEFVOL;
1* volume
*1
Pararn[S] = DEFFREQ;
1* frequency *1
Pararn[6]
1;
1* mouths
*1
if ((arge < 2) II (arge > 9
printf ("Usage: SAY \ "string" U [rate] [pitch] [mode] [sex]
[volume] [sampfreq] [mouths]\n");
else
{

for (i z O;iargc-2);i++)
Param[i] = AtoUWORD (argv[i+2]);
The Narrator Device
(argv[l],-Param[O], Param[l], Param[2], Param[3],
Pararn[4], Param[S], Param[6]);
}
}

The f-ollowing routine lists still more narrator iupport routines. From
these yoo can see which col'l!UB8Dds t.hI narrator device supports:
/**********************************************************/

1*
Narrator Copy ()
(Na.rrat Support) * I
1*
*1
1* Function: Narrator-Device-BlocK copy
*1
1*--------------------------------------------------------*1
1* Old_Request: Original IG-BlocK
*1
1* New Request: CGPY of the IO-JUocka
*I
'***************************************************** *****1

VOID Narrator_Copy (Old Request, New Request)

struct narrator rb *Old-Request;
struct mouth rb*New_Request;
New_Request->voice.message.io_Devioe =
copy
*/
Old Request->message.io Device;
4io_Unit4 */
New_Request->voice.message.io_Unit
Old_Request->message.io_Unit;

/* you only need to

/* 4io Device4and

/**********************************************************/

1*
1*

Narrator stop ()

/* Function:

(lliarrat Support) * /

Stop Narrator output

*1
*/

1*--------------------------------------------------------*1
1* WriteRequest: IO-BlocK, whose output should IDe stoppea *1
/*********** ***************************************.*****/

VOID Narrator Stop (WriteReqwest)

struet narrator rb *WriteRequest;
WriteRequest->message.io_COlI'ftl8.M
DolO (WriteRequest);

/***************************************************** *****1
Narrator start ()
(lIIarra.t Support) *1

1*
1*

*1

177

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

/* Function:

Start Narrator output

*/

/*---------------------------------------------------- ----*/
/* WriteRequest: IO-Block, whose output should be started */
/*
(after Narrator Stop () )
*/
1***************************************************** *****/

VOID Narrator Start (WriteRequest)

struct narrator_rb *WriteRequest;
{

WriteRequest->message.io Command
DoIO (WriteRequest);
-

(UWORD) CMD_START;

/**********************************************************/

/*
/*
/* Function:

Narrator Flush ()
End Narrator output

(Narrat Support) * /
*/
*/
/*---------------------------------------------------- ----*/
/* WriteRequest: la-Block, whose outpur should be ended
*/
1**********************************************************1

VOID Narrator_Flush (WriteRequest)

struct narrator rb *WriteRequest;
{
WriteRequest->message.io Command
DolO (WriteRequest);
-

(UWORD) CMD_FLUSH;

1***************************************************** *****/

/*
/*
/* Function:

Narrator Reset ()
(Narrat Support) */
*/
Narrator-Device rest to known condition */
/*---------------------------------------------------- ----*/
/* WriteRequest: la-Block, through which the Narrator
*/
/*
Device is reset
*/
1***************************************************** *****/

VOID Narrator Reset (WriteRequest)

struct narrator rb *WriteRequest;
(
WriteRequest->message.io Command
DolO (WriteRequest);
-

(UWORD) CMD_RESET;

The NarratocSupport.h file is listed below:

VOID
VOID
VOID
VOID
VOID
VOID

178

Narrator_Copy();
Narrator_Stop();
Narrator Start();
Narrator=Flush();
Narrator_Reset();
Narrator_Write();

4.12 THE NARRATOR DEVICE

ABACUS

4.13

The timer device

The timer device accesses the Amiga's internal timer. This timer serves
two purposes. You can measure time through the vertical blank, or you
can measure time through the CIA timer. Both have advantages and
disadvantages: The vertical blank timer is constant over a long period of
time. It has accuracy of only a SOth of a second
The CIA timer has an accuracy of a microsecond. The disadvantage is
that it is inaccurate over a long period of time. The user must decide for
himself which timer to use. The timer to be used is established by the
OpenDev ice () command. The uni t parameter specifies which
timer you want to use:
UNIT MICROHZ 0 (CIA Timer)
UNIT_ VBIANK 1 (Vertical Blank Timer)

The vertical blank timer is opened as follows:

struct timerequest *TirreRequest = OL;
'define TIME_LEN (ULONG) (sizeof (struct timerequest
Open A Device("timer.device", (ULONG) UNIT VBLANK,
- &TimeRequest, TIME_LEN);
-

The timer device supports the following primary commands:

TR_ADDREQUEST
TR GETSYSTlME
TR SETSYSTlME

wait for a determined time

get system time
set system time

The timer device also supports three additional commands:

AddTirne ()
SubTirne ()
CrnpT irne ()

Ox2a
-Ox30
-Ox36

The following routine allows a predetermined time to elapse:

1***************************************************** **********

*
Wait Time ()
(Timer Support) *
* Function: Wait for a predetermined amount of time
*

*--------------------------------------------------------------*
* Input - Parameter:
*
* TimeRequest: Timer-Device-Block
*
*
* Secs,Micro: Wait for how many seconds and microseconds?
***************************************************************/

179

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

VOID WaitTime (TimeRequest,Secs,Micro)

struct timerequest
*TimeRequest;
ULONG
secs,Micro;
(

TimeRequest->tr time.tv secs

TimeRequest->tr=time.tv=micro

Sees;

Micro;

TimeRequest->tr_node.io_Command = TR_ADDREQUEST; /* Command

*/
0010 (TimeRequest);

The seconds and microseconds are given to the timer device block as
parameters. and the TR ADDREQUEST command is called. This
routine flfSt returns when-the given time elapses. Remember that with
UBIT_ VB LANK the exact statement of microseconds is meaningless.
Enter the value zero here.
Let's take a closer look at the timer request structure:
Offset

Structure
struct timerequest

D DxDO
32 Dx2D
40 Dx2B

struct IORequest tr node;

struct timeval
tr-time;
/* defined in "devic;s/timer.h" *1

The tirneval structure contained in this structure looks like the

following:
Offset

Structure
struct timeval

o OxOD
4 Ox04
B Ox08

ULONG tv_secs;
ULONG tv micro;
/* defined in "devices/timer.h" */

This structure contains all of the times to be set or read. For example.
if you want to read the system time, it is transferred to these variables:
1***************************************************** **********

GetSysTime()
* Function: Find out system time

(Timer_Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
* TimeRequest: Timer-Device-Block

* Return value:
* Pointer to Timeval structure of the Timer-Device-Block

*
*--------------------------------------------------------------*

***************************************************************/

struct timeval *GetSysTime (TimeRequest)

struct timerequest
*TimeRequest;
{

Do Command (TimeRequest,TR GETSYSTlME);

return (&TimeRequest->tr_time);

180

4.12

ABACUS

THE NARRATOR DEVICE

You get the timeval Structure of the device block with the actual
system time with Timel
(struct
timeval
*)
Get SysTime
(timeRequest) . The system time returns the
current system time and the current date.
There's no problem calculating the system time with the realtime
clock. What does the user do if he doesn't have such a clock? He must
always set the time and date by hand. When writing to disk, the time of
this disk change is saved to the boot block, which is read with every
boot and declares the current system time. Naturally many
inconsistencies are encountered which you should be able to fix with
the help of eLI commands.
Now we come to how the system is decoded. The internal clock counts
in seconds, starting from January 1, 1978. When you want to display
the system (given in seconds and microseconds) in a format that the
user can understand, some calculations must be made:
ULONG Days_of_Months[]

char *Days_of_Week[]

{311,
281,
311,
301,
311,
301,
311,
311,
301,
311,
301,
311

/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

Jan
Feb
Mdr
Apr
Mai
Jun
Jul
Aug
Sep
Okt
Nov
Dez

{"Sunday",
"Monday",
"Tuesday",

*/ /* How many days does*/

*/ /* each month have? */
*/ /* (Timer Support) */
*/
*/
*/
*/
*/
*/
*/
*/
*/};
/* Week day names */

"Wednesday",
"Thursday ",
"Friday",

"Saturday "};
1***************************************************** **********

*
LeapYear ()
* Function: Is year a LeapYear?

(TimerSupport) *
*

*--------------------------------------------------------------*
* Input - Parameter:
*
* Year: Year to select
*
*--------------------------------------------------------------*
* Return value:
* TRUE: Year IS LeapYear
* FALSE: Year is NOT LeapYear

*
*
*

***************************************************************/

BOOL LeapYear (Year)

ULONG Year;
{

if Year/4l)*4l) == Year) &&

(Year/l00l)*100l) != Year return (TRUE);
else return (FALSE);
/* When year is divisible by 4, but nor by */
/* 100, it is a Leap Year */

181

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

1***************************************************** **********

HakeMonthTable ()
(TimerSupport) *
*
* Function: Update month day table (29 or 28. February?)

*--------------------------------------------------------------*
* Input - Parameter:
*
*
* Year: Year to select
* Table: Address of th Month day table (i.e. Days of Month)
*
****************************************************** *********1
VOID HakeMonthTable (Year, Table)
ULONG
Year;
ULONG
*Table;
{

if (LeapYear (Year
Table [1]
29;
else
Table [1]
28;
1* If year u sleapyear, set February to
1* instead of 28

29 days *1

*1

1***************************************************** **********

*
SysTime to TimeDate ()
(TimerSupport) *
*
* Function: Transfer system time to Timedate structure

*--------------------------------------------------------------*
*
*
*

* Input - Parameter:
* TimeRequest: Timer-Device-Block
* TimeDate:
TimeDate structure to fill

***************************************************************/

VOID SysTime to TimeDate (TimeRequest,TimeDate)

struct timerequest
* TimeRequest;
struct TimeDate
*TimeDate;
(

struct timeval *SysTime;

1* for GetSysTime *1
ULONG SysTimeSecs;
ULONG all_Days;
1* Days since 1.1 1978 *1
ULONG year Days;
1* Days in year
*1
UWORD leap~ear, years;
1* Loop variables
*1
ULONG month;
SysTime = GetSysTime(TimeRequest);
1* Get system time *1
SysTimeSecs = SysTime->tv secs;
1* get seconds *1
if (SysTimeSecs>Secs 1980)
1* later than 1980 ? *1
{
SysTimeSecs -= Secs 1980;
1* Yes, then subtract
*1
TimeDate->Year = 19801;
1* (1980-1978=2) year from
system *1
all_Days
(ULONG) (2*365); 1* Set year to 1980 and the *1
'l* number of days past since*1
1* "zero hours" (1/1/1978) at 2*365 *1
else
{

all Days = 01;

1* Time smaller than 1980
TimeDate->Year = 19781; 1* year = 1978, days elasped
if (SysTimeSecs > SecondsPerYear)
{
1* 1979 ? *1
SysTimeSecs-= SecondsPerYear;
1* yes *1
all_Days += 3651;
TimeDate->Year++;
goto Get_Month;

*1
0*1

1* since year i sknown *1

1* calculate new month *1

for (leap-year = 0; leap-year < 34; leap_year++)

{
1* calculate exact year*1
if (SysTimeSecs >z SecondsPerLeapYear) 1* (later than 1980)*1

182

4.11 THE NARRATOR DEVICE

ABACUS

SysTimeSecs -= SecondsPerLeapYear;
TimeDate->Year++;
all_Days += 3661;

/* a LeapYear */

for (years = 0; years < 3; years++)

1* three normal years *1

if (SysTimeSecs >= SecondsPerYear)
{

SysTimeSecs -= SecondsPerYear:
TimeDate->Year++;
all_Days += 3651;

MakeMonthTable (TimeDate->Year,Days of Months);

/* February = 28 or 29 days? *1
1* ! 1978 & 1979 no LeapYear!*/
Get Month:
year Days = 01;
1* day of the year = 0 *1
for (month = 01; month < 111; month++)
{

if (SysTimeSecs >= (Days of Months[month]*SecondsPerDay

- {
/* calculate month */
(Days of Months[month]*SecondsPerDay);
SysTimeSecs
all_Days
+= Days-of-Months[month];
year_Days
+= Days=of=Months[month];
else break;
TimeDate->Month = month+1; 1* Otherwiset 0 = January etc. *1
TimeDate->Day = (SysTimeSecs/SecondsPerDay)+11;
1* day 0 = first.
Month is first *1
SysTimeSecs
(SysTimeSecs/SecondsPerDay)*SecondsPerDay;
+= TimeDate->Day-11;
1* exp: 02.02. a11*1
year_Days
all Days
+= TimeDate->Day-11;
1* 32 days elapsed *1
TimeDate->Hour = SysTimeSecs/SecondsPerHour;
/* hour *1
SysTimeSecs
(SysTimeSecs/SecondsPerHour)*SecondsPerHour;
TimeDate->Mins = SysTimeSecs/SecondsPerMinute; 1* Minute *1
SysTimeSecs
(SysTimeSecs/SecondsPerMinute)*SecondsPerMinute;
TimeDate->Secs = SysTimeSecs;
1* Second *1
1* week of the year*1
TimeDate->Week = year Days/7;
TimeDate->Week Day = all Days' 7;
1* Weekday (1/1/1978 waa a Sunday (0 *1

Of these three routines only the System_to_TimeDate () function

is of importance. This routine fills a structure given by us, which can
be easily interpreted:
Offset

Structure
struct TimeDate

o
4
8
12
16
20
24
28

OxOO
Ox04
Ox08
OxOc
Ox10
Ox14
Ox18
Ox2c

ULONG
ULONG
ULONG
ULONG
ULONG
ULONG
ULONG
ULONG

Year;
Month;
Day;
Week;
Week Day;
Hour;
Mins;
Secs;

1*
1*
1*
1*
/*
/*

1*
1*

year *1
Month */
day of the month */
week of the year */
Week day (O==Sonntag etc.) *1
hour *1
Minute *1
Seconds *1

183

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Program description
After the system time loads and the program is instructed to read
seconds instead of microseconds, the routine checks for a current system
date earlier than 1980. Because 1980 is a leap year, a loop searches
through proceeding years.
To find out the number of years that have elapsed, the program
subtracts the number of seconds that have elapsed in a year from the
current system time until the result of this subtraction is less than a
year. Leap years are determined using the Leapyear () function.
Once you determine the correct year, you can calculate the month.
Because the 12 months in a year have different number of days, the
subtraction from the current system time becomes more complicated. If
a year is a leap year, the MakeMonth () routine sets the number of
days in February to 29 rather than 28.
Dividing the remaining number of seconds by the number of seconds in
a day gives us the day of the month. This method is adapted to find the
hours, minutes and seconds. When subtracting seconds you subtract the
calculated number of days/hours/minutes/etc. The remaining seconds
give the seconds within the current minute.
Adding the number of elapsed days gives us the weekday. Next the
program divides the number of days elapsed since January I, 1978 by
seven; the remainder gives the current weekday. You can display the
corresponding weekday with printf ("%s\n", Days_of_Week
[TimeDate->WeekDay] ) ;.

We needed the following constants for the calculations in the above

routine:
'define
'define
'define
'define
'define

SecondsPerMinute
SecondsPerHour
SecondsPerSay
SecondsPerYear
SecondsPerLeapYear

'define Secs 1980

(ULONG)
(ULONG)
(ULONG)
(ULONG)
(ULONG)

(60L)
(60L*60L)
(60L*60L*24L)
(60L*60L*24L*365L)
(60L*60L*24L*366L) 1* leap
year *1
(ULONG) (2L*SecondsPerYear)
1* Seconds from *1
1* 1.1 1978 up *1
1* to 1.1 1980 *1

We also wrote a routine to perform the opposite function. The new

system time is calculated and set from a given Timedate structure:
1***************************************************** **********
*
TimeDate to SysTime()
(TimerSupport)*
* Function: TimeDate becomes system-time
*
*--------------------------------------------------------------*
* Input - Parameter:
*
* TimeRequest: Timer-Device-Block
*

184

4.12 THE

ABACUS

* TimeDate:

NARRATOR DEVICE

TimeDate-Structure, to become system time

***************************************************************/

BYTE TimeDate to SyaTime (TimeRequest,TimeDate)

s~ruct timerequest
*TimeRequest;
struct TimeDate
*TimeDate;
{

ULONG i;
ULONG SysTimeSecs=Ol;
if (TimeDate->Hour > 24) return (TDERR HOUR OUT OF RANGE);
if (TimeDate->Mins > 59) return (TDERR-MINS-OUT-OF-RANGE);
if (TimeDate->Secs> 59) return (TDERR=SECS=OUr::~OF=RANGE);
i f TimeDate->Year < 19781) "
(TimeDate->Year > 21141
return (TDERR_YEAR_OUT_OF_RANGE);
1* TimeDate test *1
if (TimeDate->Month > 12)
return (TDERR MDNTH OUT OF RANGE);
if TimeDate->D~y > D~ys of Months[TimeDate->Month-1) I I
(TimeDate->Day == 0- return (TDERR DAY OUT OF RANGE);
SysTimeSecs = TimeDate->Hour*SecondsPerHour+
TimeDate->Mins*SecondsPerMinute+
TimeDate->Secs+
(TimeDate->Day-1)*SecondsPerDay;
1* hours, minutes, seconds and *1
1* days change after seconds *1
MakeKonthTable (TimeDate->Year,Days of Months);
1* February 28 or 29 days? *1
for (i=01;iTimeDate->Month-11);i++)
SysTimeSecs += Days of Months[ij*SecondsPerDay;
- 1* Month after seconds *1
for (i=19781;i<TimeDate->Year;i++)
if (LeapYear (i SysTimeSecs += SecondsPerLeapYear;
else
SysTimeSecs += SecondsPerYear;
1* Year after seconds *1
SetSysTime(TimeRequest,SysTimeSecs,Ol);
1* Set new system time *1

This routine multiplies the values of the Timedate structure by the

number of seconds for the year, day, month, etc. and adds these
products, perfonning any compensation needed for leap years. The
calculated system time is reset:
1***************************************************************
*
SetSysTime ()
(TimerSupport) *
*
* Funktion: Set system time

*--------------------------------------------------------------*
* Input - Parameter:
* TimeRequest: Timer-Device-Block
* Secs,Micro: New system time in seconds and microseconds

*
*
*

***************************************************************/

VOID SetSysTime (TimeRequest,Secs,Micro)

struct timerequest
*TimeRequest;
ULONG
Sees, Micro;
{

TimeRequest->tr time.tv sees = Secs;

TimeRequest->tr-time.tv-micro = Micro;
TimeRequest->tr-node.io-Command a TR_SETSYSTlME;
DolO (TimeRequest);
-

185

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

You've now seen the most common timer device commands. Let's look
at the remaining three device commands (SubTime (), AddTime ()
and CmpTime (. These commands always supply two timeval
structures which contain two times (for example, Sub Time
(timevall, timeva12);). The names of these commands contain
these results. SubTime () subtracts the time of the second timeval
structure from the frrst, and saves the result in the first timeval

structure.
AddTime () adds the two timeval structures and places the result in
the frrst timeval structure. CmpTime () compares the two given
timeval structures. The result of this function is zero for equality,
>0 when timevall > timeva12, and <0 when timevall <
timeva12. You must frrst open TimerBase before this function

can be called:
struct Device *TimerBase;
TimerBase = TimerRequest->tr_node.io_Device;

Now you know the basics of the AddTime () , SubTime () , and

CmpTime () routines. The following program applies these to the
system time:
/***************************************************************
*
*

*
*
*
*

Timer-Device
(c) Bruno Jennrich
Juni 1988
Compile-Info: (TimerComp)
cc Timer
ln Timer.o Timer Support.o Devs Support.o -lc

*
*

*
*
*
*

***************************************************************1

tinclude "exec/types.h n
'include "exec/nodes.h"
'include nexec/lists.h"
'include nexec/memory.h"
'include "exec/ports.h n
'include "exec/libraries.h n
'include nexec/io.h"
'include nexec/devices.h n
'include "devices/timer.h"
'include nTimer_Support.h n
VOID *GetSysTime();
extern ULONG Days of Month[];
extern char *Days-of-Week[];
struct TimeDate TimeDate;
struct timerequest *TimeRequest=Ol;
struct timeval
*SystemTime=Ol,
OneDay = {(ULONG)SecondsPerDay,Ol);
struct Device *TimerBase;

1***************************************************** **********
*
CloseIt()
* Function: Display erro rand close everything

(User) *
*

*--------------------------------------------------------------*
186

4.12 THE

ABACUS

NARRATOR DEVICE

* Input - Parameter:
*
*
* String: Error-String
***************************************************************/
VOID CloseIt (String)
char
*String;
{

UWORD i;
UWORD *dffl80 = (UWORD *)OxdffI80;
UWORD Error
= 0;
if (strlen (String) > 0)
{

for (i=O;i<Oxffff;i++)
puts (String);
,
Error = 100;
if (TimeRequest != 01)
exit (Error);

*dffl80 = i;

Close A Device (TimeRequest);

/***************************************************************

*
TimePrintout()
(User) *
* Function: Display TimeDate-Structure (Time)
*
*--------------------------------------------------------------*
* Input - Parameter:
*
* TimeDate: TimeDate structure to dislpay
*
****************************************************** *********1
VOID TimePrintout (TimeDate)
struct TimeDate
*TimeDate;
{

printf ("%s %021d %021d %04ld Time: %021d: %021d: %021d\n" ,

Days_of_Week[TimeDate->Week_Dayl,
TimeDate->Month,
TimeDate-> Day,
TimeDate->Year,
TimeDate->Hour,
TimeDate->Mins,
TimeDate->Secs);
1***************************************************** **********
*
The_Timer_Device()
(User) *
* Function: Timer-Device and Timer-Support support
*

***************************************************************/

VOID The Timer Device()

{

Open A Device ("timer.device", (ULONG) UNIT VBLANK,

- &TimeRequest,OI,TIME_LEN);
TimerBase = TimeRequest->tr node.io Device;
printf ("System Time is: \n");
SysTime to TimeDate (TimeRequest,&TimeDate);
TimePrintout (&TimeDate);
printf ("Now add one Day to System Time\n");
SystemTime = (struct timeval*) GetSysTime(TimeRequest);
AddTime (SystemTime,&OneDay);
SetSysTime (TimeRequest,SystemTime->tv_secs,SystemTime>tv micro);
printf ("System Time now is:\n");
SysTime_to_TimeDate (TimeRequest,&TimeDate);
TimePrintout (&TimeDate);
printf ("Subtract the Day from System Time and wait 15
Seconds\n") ;
SubTime (SystemTime,&OneDay);
SetSysTime (TimeRequest,SystemTime->tv_secs,SystemTime>tv_micro) ;

187

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GmDE

WaitTime (TimeRequest,151,01);
printf (nThis is Northern-System-Time:\nn);
SysTime_to_TimeDate (TimeRequest,&TimeDate);
TimePrintout (&TimeDate);
C1ose_A_Device (TimeRequest);
1***************************************************** **********

main()

***************************************************************/

main()
(

The following is the TimecSupport.h file used by the Timer.c

program:
1***************************************************** **********
*
Timer Support. h
*
* Include File for Timer supPOrt.c and the timer program
*

*.*** *********/

'define
'define
'define
'define
'define
'define

SecondsPerMinute
(601)
SecondsPerHour
(601*601)
SecondsPerDay
(601*601*241)
SecondsPerYear
(601*601*241*3651)
/* Year */
SecondsPerLeapYear
(601*601*241*3661)
/* Leapyear */
Secs_1980
(21*SecondsPerYear) /* Seconds from */
/* 1.1 1978 to */
/* 1.1 1980 */
'define TDERR_HOUR_OUT_OF_RANGE -2 /* Timer-Device Errors */
'define TDERR MINS OUT OF RANGE -3
'define TDERR_SECS_OUT_OF_RANGE -4
'define TDERR YEAR OUT OF RANGE -5
'define TDERR=MONTH_OUT_OF_RANGE -6
'define TDERR DAY OUT OF RANGE
-7
'define TIME LEN (ULONG)-sizeof (struct timerequest)
/* Size of Device-Block */
struct TimeDate
/* Structure * /
ULONG Year;
/* Yearr */
ULONG Month;
/* Monht */
ULONG Day;
/* Month day */
ULONG Week;
/* Week of year */
ULONG Week_Day;
/* Weekday (O=Sunday etc) */
ULONG Hour;
/* hours */
ULONG Mins;
/* minutes */
ULONG Secs;
/* seconds */
};

188

4.14 THE TRACKDISK DEVICE

ABACUS

4.14

The trackdisk device

The ttackdisk device controls the Arniga's disk drives. This device uses
another IOStdReq block for its operation (we'll discuss the variables
used in this sb'uCture later):
Offset

Structure
struct IOExtTD

OxOO
48 Ox30
52 Ox34
56 Ox38

struct IOStdReq iotd_Req;

ULONG
iotd Count;
ULONG
iotd-SecLabel;
/* defined in "devices/trackdisk.h" */

The trackdisk device supports the following commands:

CMD READ
CMD WRITE
CMD UPDATE
CMD CLEAR
TD MOTOR
TD SEEK
TD FORMAT
TD REMOVE
TD CHANGENUM
TD CHANGES TATE
TD PROTSTATUS
TD RAWREAD
TD RAWWRITE
TD GETDRIVETYPE
TD GETNUMTRACKS
TD ADDCHANGEINT
TD REMCHANGEINT
TD LASTCOMM

(2)
(3)
(4)
(5)
(9)

(10)
(11)

(12)
(13)

(14)
(15)
(16)

(17)
(18)
(19)
(20)

(21)
(22)

read sector
write sector in TrackBuffer
write TrackBuffer to disk
declare TrackBuffer invalid
turn motor on/off
position read/write head
fonnat ttack
install media change interrupt
detennine disk change number
check for inserted disk
test write protect
read tr.K:k (raw data)
write ttack (raw data)
detennine drive type (3-1/2" or 5-1/4 ")
detennine number of tracks
add media change interrupt
remove media change interrupt
detennine last command executed (not
currently implemented)

The ttackdisk device includes extended commands, which set command

number bit 15. These commands perform the same functions as the
ones listed above, except that these commands don't execute
immediately after a disk change:
ETD
ETD
ETD
ETD

READ
WRITE
UPDATE
CLEAR

(32770)
(32771)
(32772)
(32773)

read sector

write sector in TrackBuffer

write TrackBuffer to disk
TrackBuffeI'declared invalid
189

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ETD
ETD
ETD
ETD
ETD

MOTOR
SEEK
FORMAT
RAWREAD
RAWWRITE

(32777)
(32778)
(32779)
(32784)
(32785)

tum motor on/off

position read/write head

format ttack
read tmck (raw data)
write track (raw data) (not currently
implemented)

The iotd_Count variable is important to this command (see

IOExt TD). This variable contains the number of disk swaps made
since the last booting procedure. One disk removal counts as one disk
swap; one disk insertion counts as one disk swap. Therefore, removing
one disk from a drive and inserting another counts as 2 disk swaps.

The following sequence opens the trackdisk device:

struct IOExtTD *DiskExtIO=OL;
'define TD_LEN (ULONG) (sizeof (struct IOExtTD
OpenDevice(ntrackdisk.device n , Unit, &DiskExtIO, OL, TD_LEN);

Remember that you must specify which drive you want to address when
you open the device. The Uni t parameter accepts the values 0 (for
OFO:), 1 (for OFl:), 2 (for OF2:) or 3 (for OF3:). You can always
open only one drive with Open_A_Device (). If you want to access
multiple drives, you must call Open_A_Device () twice with two
different device blocks and different values for Uni t.

4.14.1

Reading and writing sectors

Mter Open_A_Device () you can begin. The following routine
shows how to read a sector using the trackdisk device:
1***************************************************************
*
TrackDisk ReadSectorO
* Function: Read sector
-

(Track_Support) *
*

*--------------------------------------------------------------*
Input - Parameter:

* DiskExtIO:
* SectorBuffer:
* LabelBuffer:
* offset:

Device-Block
Sector-Data
Label-Area data
Sector number

*
*
*

*
*

***************************************************************/
VOID TrackDisk ReadSector
(DiskExtIO,SectorBuffer,LabelBuffer,Offset)
struct IOExtTD
*DiskExtIO;
APTR
SectorBuffer;
APTR
LabelBuffer;
ULONG
Offset;
{

190

ABACUS

4.14 THE TRACKDISK DEVICE

OiskExtIO->iotd Count
= TrackOisk_GetOiskChangeCount
(OiskExtIO) ;
DiskExtID->iotd Req.io Offset = Offset*5121;
DiskExtIO->iotd-Req.io-Oata
= (APTR) SectorBuffer;
DiskExtIO->iotd-Req.io-Length = (ULONG) TO SECTOR;
DiskExtIO->iotd-SecLabel
= (ULONG) LabelBuffer;
Do_Command (OiskExtIO, (UWORD) ETD_READ);

This routine uses the ETD READ command to read a sector from the
disk. The number of disk swaps is saved in iotd_Count using
TrackDisk_GetDiskChangeCount () . If the disk is swapped
before the E TO_READ command, when the E TO_READ command is
executed it determines that the value in iotd Count is less than the
value of the disk swap, and ETD_READ is not executed. Along with
ETD_ READ all of the EID commands function after being checked by
iotd Count.
You can bypass this by saving the value Oxffffffffin iotd_Count.
Here iotd_Count is always greater than or equal to the number of
disk swaps. Use the CMD READ command instead of ETD READ,
since CMD_READ does notdisturb the iotd_Count.
To inform the trackdisk device which sector should be read, the offset of
the sector to be read is given in iotd_Req. io_Offset. Notice that
the trackdisk device numbers all of the sectors by byte. To read sector
0, the trackdisk device must be given the value O. To read sector I, the
trackdisk device must be given the value 512 (a sector contains 512
bytes). To read sector 2, the trackdisk device must be given the value
1024, and so on. The device block performs the offset assignments, so
you don't have to constantly multiply the sector number you want read
by 512. All you need to do is specify the number of the sector to be
read (0-1759).
Perhaps you want to read the lower portion of sector 0, or the top
portion of sector 1. You can't read just parts of a sector-the offset
must always be a factor of 512. The buffer in which you want to read
the data of the sector should be a minimum size of 512 bytes, and
should be in Chip memory. If you want to read more than one sector
you must allocate more memory. The above routine reads only one
sector. SectorBuffer contains the starting address of the data
memory that must contain the 512 bytes.

If you enter a number for SectorBuffer less than 512 bytes, only
the first 200 bytes are read. The other bytes stay protected from access.
A sector on a disk also contains another data region beside the sector
data-the label buffer. This 16-byte label buffer is placed before the
actual buffer. Usually 0 bytes precede the actual buffer. You can use

191

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

this label buffer as additional data memory. or write copyright messages

in iL
You must provide a l~byte label buffer for each secur to be read. This

memory must be combined for multiple sector reading.

The following routine writes trackdisk data to a sector:
1***************************************************************
*
TrackDisk WriteSector ()
(Track Support) *
* Function: Write track
*

*--------------------------------------------------------------*
*

Input - Parameter:
* DiskExtIO:
Device-Block
* SectorBuffer: Sector-Data (Ox397c Bytes)
* offset:
Sector number

*
*

*
*

***************************************************************/

VOID TrackDisk WriteSector

(DiskExtlo,SectorBuffer,LabelBuffer,Offset)
struct IOExtTD
*DiskExtIO;
APTR
SectorBuffer;
APTR
LabelBuffer;
ULONG
Offset;
{

= TrackDisk_GetDiskChangeCount
DiskExtI0->iotd Count
(DiskExtIO) ;
DiskExtI0->iotd Req.io Offset = Offset*512l;
DiskExtIO->iotd-Req.io-Data
= (APTR) SectorBuffer;
(ULONG) TD_SECTOR;
DiskExtIO->iotd=Req.io=Length
DiskExtIO->iotd SecLabel

(ULONG) LabelBuffer;

Do Command (DiskExtIO, (UWORD) ETD WRITE);

Do COl!ll1and (DiskExtIO, (UWORD) ETD=UPDATE);

This command sequence includes variables named SectorBuffer

and LabelBuffer. This time the buffer contains the data that should
be written to the disk. The offset is also given as with
TrackDisk_ ReadSector () . The main difference is that after the
WRITE command an UPDATE command executes. This command
ensures that the sector is physically written to the disk.
ETD_WRITE and CMD_WRITE ensure that the data written in the
ttackdisk device is the flI'St written in a new track when accessed. This
internal buffer contains enough memory to store an entire track (11
sectors). This buffer is usually the only one accessed with the WRITE
and READ commands. Accesses through this buffer are very fast. If
another track should be accessed, either the old trackbuffer is written
again, or it reads a new track in the internal buffer. You can enlarge the
internal buffer using AddBuffers.

192

4.14 THE TRACKDISK DEVICE

ABACUS

Problems occur when you write a sector in the internal buffer by means
OfETD_WRITE or CMD_WRITE, and then try to exit the program. The
new data may not be written to the disk under certain conditions. This
is why the UPDATE command executes after the WRITE command.
This ensures that the internal buffer is written to the disk.
Knowing the current number of disk swaps is vital to the use of the
extended commands. The following routine shows how the
TD CHANGENUM command finds this number:
1***************************************************** **********
*
TrackDisk GetDiskChangeCount ()
(Track Support)*
* Function: Get number of disk changes
*

*--------------------------------------------------------------*
* Input - Parameter:
* DiskExtIO: Device-Block

*
*

*--------------------------------------------------------------*

* Retrun value:
*
*
* Number of disk changes
****************************************************** *********1
ULONG TrackDisk GetDiskChangeCount(DiskExtIO)
struct IOExtTD *DiskExtIO;
{

Do Command (DiskExtIO, (UWORD) TD CHANGENUM);

return (DiskExtIO->iotd_Req.io_Actual);

After TD _ CHANGENUM the actual number of disk swaps is stored in

io Actual.
We should also have control over the disk drive motor (on or off). The
following routine controls the motor:
1***************************************************** **********
*
TrackDisk_Motor()
(Track_Support) *
* Function: Motor on/off
*
*--------------------------------------------------------------*
* Input - Parameter:
*
* DiskExtIO: Device-Block
*
* Flag: TRUE => Motor on
*
*
FALSE => Motor off
*
***************************************************************/
VOID TrackDisk Motor (DiskExtIO,Flag)
struct IOExtTD
*DiskExtIO;
BOOL
Flag;

if (Flag)
else

DiskExtIO->iotd Req.io Length

DiskExtIO->iotd=Req.io=Length

11; /* Motor on */
01; /* Motor off*/

Do Command (DiskExtIO, (UWORD) TD_MOTOR);

This command is important because the read and write commands turn
the motor on but not off: The user must tum off the motor. The
command TrackDisk Motor (DiskExtIO, FALSE) writes a 0

193

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

in the length element of the Dis k Ext I 0

structure.
TrackDisk Motor (DiskExtIO, TRUE) writes a 1 into
io Length.This sets the motor high and addresses motor operation.
You get the previous motor status from iO_Actual (O=off. l=on).

4.14.2

Reading and writing raw tracks

In addition to reading and writing of individual sectors. the trackdisk
device also provides commands for reading and writing entire tracks.
There is a small problem. Raw data doesn't appear in the usual byte
format used by ETD_ READ and ETD_WRITE.
The bits are encrypted (coded) before they are physically written to the
disk. The Amiga uses MFM (Modified Frequency Modulation) coding.
This means that the commands which read and write the track data are
accessed physically. as if the data is really on the disk. Entire sync and
clock bits are read consistently. This gives us the capability of reading
data from foreign formats such as Atari.
You can also read disks that use the GCR (Group Code Recording)
formaL When writing you should specify which format the data should
be written in. The following routines perform these read and write
operations.
jdefine RAW TRACK LEN Ox397cl
/***************************************************************

*
*

TrackDisk_RawReadSector()

(Track_Support) *

Function: Read raw track (not processed!)

*
*

*--------------------------------------------------------------*
* Input - Parameter:
*
*
*
* DiskExtIO: Device-Block
*
* TrackBuffer: Track-Data (Ox397c Bytes)
*

Offset:

Track number

***************************************************************/

VOID TrackDisk_RawReadSector (DiskExtIO,TrackBuffer,Offset)

struct IOExtTD
*DiskExtIO;
APTR
TrackBuffer;
ULONG
Offset;
{

if (Offset> 159) DiskExtIO->iotd_Req.io_Error = Oxfc;

else
{

DiskExtIO->iotd Count
TrackDisk_GetDiskChangeCount (DiskExtIO);
DiskExtIO->iotd Req.io Offset = Offset;
DiskExtIO->iotd-Req.io-Data
= (APTR) TrackBuffer;
DiskExtIO->iotd-Req.io-Length = RAW TRACK LEN;
DiskExtIO->iotd=Req.io=Flags
= (BYTE) IOTDF_INDEXSYNC;

194

4.14

ABACUS

THE TRACKDISK DEVICE

DiskExtID->iotd_Req.io_Actual = 01;
Do_Command (DiskExtIO, (OWORD) ETD_RAWREAD);

1***************************************************************

TrackDisk_ RawWriteSector ( )

(Track_Support) *

*
*

* Function: Write raw track (unprocessed)

*--------------------------------------------------------------*

Input - Parameter:

*
*
*

* DiskExtIO: Device-Block
* TrackBuffer: Track-Data
* Offset:
Track number

***************************************************************/
VOID TrackDisk_RawWriteSector (DiskExtIO, TrackBuffer, Offset)
struct IOExtTD
*DiskExtIO;
APTR
TrackBuffer;
ULONG
Offset;
{

if (Offset> 159) DiskExtIO->iotd Req.io Error = Oxfc;

else
DiskExtIO->iotd Count
TrackDisk GetDiskchangecount (DiskExtIO);
DiskExtID->iotd Req.io Offset = Offset;
DlskExtIO->lotd-Req.io-Data
(APTR) TrackBuffer;
DiskExtIO->iotd-Req.io-Length = (ULONG) RAW_TRACK_LEN;
DiskExtIO->iotd-Req.lo-Flags
= (BYTE) IOTDF_INDEXSYNC;
Do Command (DiskExtIO,(UWORD) ETD_RAWWRITE);

Notice that a track now needs Ox397c bytes instead of 11*512 =

Oxl600 bytes. This command should make it possible to wait for the
exchange of the index locks and then begin reading and writing data.
For this the IOTDF _INDEXSYNC flag is set. Unfortunately, a
hardware error clears the hardware register before disk access. This
makes the flag meaningless.
Because these commands do not leave the data format, only tracks 0160 can be read and written. This is because the position of the
read/write head is predetermined for each track. You don't need to
multiply the sector number by 512 as with E T D _ REA D and
ETD_ WRI TE. You simply give the number of the track to be read.

195

4. DEVICES

4.14.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Formatting a disk
You've seen the most frequently used trackdisk commands. However,
you can still do more with this device. For example, you have the
option of formatting individual tracks. This is useful, for example,
when the boot block on a disk was destroyed for some reason and so
ooS cannot access the disk. Assuming that there is no important data
on track 0 (sectors 0 through 10), you can format track 0 and copy the
boot block of an intact disk to the disk whose boot block you
reformatted, by means of READ and WRITE. Then you can rescue the
most important files to the new disk, assuming the rest of the disk is
in order. The following routine shows how a single track can be
formatted:
'define MEMTYFE (ULONG) MEMF_CLEAR I MEMF_CHIP
/***************************************************************

TrackDisk_Format ()

(Track_Support) *

*
*
*--------------------------------------------------------------*
* Function: Format track
* Input - Parameter:

* DiskExtIO: Device-Block
* Offset:
Track number

***************************************************************/

VOID TrackDisk Format (DiskExtIO, Offset)

struct IOExtTD
*DiskExtIO;
ULONG
Offset;
{

BYTE *FormatData=Ol;
UWORD i;
FormatData = (BYTE *) AllocMem (NUMSECS*TD SECTOR, MEMTYFE);
if (FormatData == 01)
Closelt(nNo FormatData Buffer!! !");
for (i=O; i<NUMSECS*TD SECTOR; i+= 4)

FormatData [i 1
FormatData [i+ 11
FormatData[i+2]
FormatData [i+31

';

'd t ;
'b';

':

1* data *1
1* becker *1

DiskExtIo->iotd Count
= TrackDisk_GetDiskChangeCount
(DiskExtIO) ;
DiskExtIO->iotd Req.io Data
= (APTR) FormatData:
DiskExtIO->iotd-Req.io-Length = (ULONG) (NUMSECS*TD_SECTOR):
DiskExtIO->iotd-Req.io-Offset = Offset:
Do_Command (DiskExtIO,(UWORD)ETD_FORMAT);
FreeMem (FormatData,NUMSECS*TD_SECTOR);

196

4.14

ABACUS

THE TRACKDISK DEVICE

Unlike READ and WRITE, the number of the tracks to be formatted (0160) is given in io_Offset. Also, a multiplication by 512 is
unnecessary. Memory for an entire track is reserved for this command
and it is written with db. Then the format buffer is given in the
i 0_Oa t a pointer. Be aware that you can only format one or more
complete tracks with TO_FORMAT and ETO_FORMAT. with one of the
tracks to format the size of the fonnat buffer NUMSECS *TO SECTOR
is (11*512). The memory size adjusts accordingly with multiple tracks
to be fonnatted.
Tracks and sectors are described according to a certain pattern when
formatting. Whoever has the time and the inclination can look at a
newly formatted disk with the disk monitor listed in this chapter and
analyze the fonnatting pattern.

4.14.4

Status commands
A number of ttackdisk commands indicate the status of the disk and
disk drive. The following routine demonsttates this command set:
1***************************************************** **********
*
TrackDisk GetProtStatus() (Track Support)*
* Function: Write-Protect on/off ?
*
*--------------------------------------------------------------*
* Input - Parameter:
*
* DiskExtIO: Device-Block
*
*--------------------------------------------------------------*
* Return value:
*
<>0: write protected
*
* 0: not write protected

***************************************************************/
ULONG TrackDisk GetProtStatus (DiskExtIO)
struct IOExtTD *DiskExtIO;
{

Do Command (DiskExtIO, (UWORD) TD PROTSTATUS);

return (DiskExtIo->iotd_Req.io_ACtual);

/***************************************************************

TrackDisk GetChangeState ()
* Function: Is disk inserted?

(Track_Support) *

*--------------------------------------------------------------*
* Input - Parameter:
* DiskExtIO: Device-Block

*--------------------------------------------------------------*
* Return value:
*
* 0: Diskette inserted
<>0: Diskette removed
*
***************************************************************/
ULONG TrackDisk GetChangeState (DiskExtIO)
struct IOExtTD *DiskExtIO;
{

Do Command (DiskExtIO, (UWORD) TD CHANGESTATE);

return (DiskExtIo->iotd_Req.io_Actual);

197

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

TD_PROSTATUS places the write protect status in iO_Actual. If

i 0_ Act u a 1 equals zero, the disk is not write protected.
TD_CHANGESTATE operates in a similar manner. If iO_Actual

equals zero following this command, there is no disk in the disk drive.
The following commands also place return values in io_Act ual :

TD_GETDRIVJ:TYPB
This command helps you determine what disk drive should be accessed.
If iO_Actual equals I, a 3-1/2" drive is connected. If iO_Actual
equals 2, a 5-1/2" drive is connected.

TD_GBTNUMTRACKS
This command returns the number of tracks that the connected disk
drive can handle. The standard 3-1/2" Amiga disk drives manage 160
tracks.

This command lets you set and test the read/write head on the given
track to see if it is positioned at a certain track. You supply the number
of the fIrst sector of the given track (factor of 11). If the track was
incorrect. this quits with an error (ioyrror !=O):
1***************************************************************

*
*

TrackDisk_SeekSector()
Function: Position read head

(Track_Support) *

*--------------------------------------------------------------*
* Input - Parameter:

* DiskExtIO: Device-Block
* Offset:
Sector number

*
*

***************************************************************/
VOID TrackDisk SeekSector (DiskExtIO, Offset)
struct IOExtTD*DiskExtIO;
ULONG
Offset;
{

DiskExtIO->iotd Req.io Offset = Offset*5121;

Do_Command (DiskExtIO,(UWORD) TD_SEEK);

Should this command return an error, this may mean that your disk

drive is damaged.

198

4.14 THE TRACKDISK DEVICE

ABACUS

4.14.5

Disk interrupts
Another interesting feature of the trackdisk device is the possibility of
installing an interrupt that executes with each disk swap. The
TD_REMOVE command performs this task.
struct Interrupt *Interrupt = 01;

1***************************************************** **********
*

TrackDisk_InterruptOnO

(Track_support) *

* Function: Install disk change interrupt

* Input - Parameter:

*--------------------------------------------------------------*

* DiskExtIO:
Device-Block
* TrackDisk DiskRemove: Interrupt-Routine

***************************************************************/
VOID TrackDisk_InterruptOn (DiskExtIO,TrackDisk_DiskRemoved)
struct IOExtTD
*DiskExtIO;
VOID
(*TrackDisk DiskRemoved) ();

Interrupt = (struct Interrupt *) AllocMem

ULONG) (sizeof(struct Interrupt)),MEMTYPE);
if (Interrupt == 01) closelt ("Nolnterrupt");
Interrupt->is Code
(VOID (*) ())
TrackDisk_DiskRemoved;
(APTR) Interrupt;
DiskExtIO->iotd Req.io Data
(UWORD) TD_REMOVE;
DiskExtIO->iotd=Req.io=Command
DolO (DiskExtIO);

This routine allocates memory for an interrupt. The name interrupt

may not be used in your program if you want to use this routine. The
interrupt structure stores the address of your interrupt routine in the
i s _Code pointer. The interrupt structure is not assigned a value in the
i s _ D a t a array. It is erased from the memory allocation
(MEMF _CLEAR). Should you give a memory region here, this is given
to the interrupt routine in AI.
After interrupt structure initialization, your address is given in the
iO_Data pointer of the device block and TD_REMOVE is called. Now
the interrupt is installed. To release the interrupt again, you can use the
following routine:
/***************************************************************

*
*

TrackDisk InterruptOff ()
Function: Remove Disk-Interrupt

(Track Support) *
*

*--------------------------------------------------------------*
* Input - Parameter:
* DiskExtIO: Device-Block

*
*

***************************************************************/

199

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

VOID TrackDisk_InterruptOff (DiskExtIO)

struct IOExtTD
*DiskExtIO;
{

DiskExtIO->iotd Req.io Data

= 01;
DiskExtIO->iotd-Req.io-Command = (UWORD) TD_REMDVE;
0010 (DiskExtIO);
if (Interrupt != 01)
FreeMem (Interrupt, (ULONG) (sizeof (struct Interrupt);
Interrupt = (struct Interrupt *) 01; /* fir Closelt() */

This routine sets the i 0 _ D a t a pointer (which points to the interrupt

structure) to 0 and calls TD_REMOVE a second time. Then the program
releases the interrupt structure's memory. This is why interrupt is
globally defined and may not be used in your programs.
TrackDisk_Interruptcn () and T rackDisk_InterruptOff () access
interrupt.

In addition to TD _REMOVE, KICK1.2 includes some disk interrupt

processing commands: 'ID_~IN1' and 'I'D_ ~IN1'. You
can install an interrupt with TD _ ADDCHANGEINT just like you did
with TD REMOVE:
1***************************************************** **********
*
TrackDisk AddChangelnt()
(Track Support)*
* Function: Disk-Interrupt install
*
*
Attention: TO REMCHANGEINT does not function!!!!
*

*------------------------=-------------------------------------*
* Input - Parameter:
* DiskExtIO:
Device-Block
* TrackDIsk DiskRemoved: Interrupt-Routine

*
*

***************************************************************/

VOID TrackDisk AddChangelnt (DiskExtIO,TrackDisk DiskRemoved)

struct IOExtTD*DiskExtIO;
VOID

(*TrackDisk_DiskRemoved) ();
{

InterruptIO = (struct IOExtTD *)GetDeviceBlock (TD_LEN);

TrackDisk_Copy (DiskExtIO,InterruptIO);
Interrupt = (struct Interrupt *)
AllocMem ULONG) (sizeof(struct Interrupt,MEMTYFE);
if (Interrupt == 01) Closelt ("NoInterrupt");
Interrupt->is Code
= (VOID (*) ()
TrackDisk_DiskRemoved;
InterruptIO->iotd Req.io Data
(APTR) Interrupt;
InterruptIO->iotd-Req.io-Command = (UWORD) TD_ADDCHANGEINT;
SendIO (InterruptIO);
-

Memory for the interrupt structure is allocated in this routine. Another

device block is also constructed, because the TD _ADDCHANGEINT
command returns to the program when the interrupt is released. Since
you want to work with the trackdisk device in the meantime, a second
device block must be added. The most important variables are copied
into this one by means of TrackDisk_Copy ():

200

4.14 THE TRACKDISK DEVICE

ABACUS

1***************************************************** **********
*

TrackDisk_Copy()

(Track_Support) *

*
*

* Function: Device-Block copy

*--------------------------------------------------------------*
* Input - Parameter:

*
*

* OldExtIO: Original
*
* NewExtIO: Copy
*
***************************************************************/
VOID TrackDisk Copy (OldExtIO, NewExtIO)
struct lOExtTD*OldExtIO,*NewExtIO;
(

NewExtIo->iotd Req.io Device =

OldExt Io->iotd_Req:io_Devi ce;
NewExtIO->iotd Req.io Unit =
OldExtIo->iotd_Req~io_Unit;

NewExtIO->iotd Count =
OldExtIo->iotd_Count;

Unfortunately there is a problem with using TD_ADDCHANGEINT or

TD_REMCHANGEINT. The interrupts must be removed before closing
the trackdisk device. The command provided to do this is
TD _REMCHANGE I NT. but this command is not currently
implemented. We recommend that you install a disk interrupt using
TrackDisk_AddChangelnt () because you can never remove
these. and you can run into big trouble with these after the trackdisk
device closes.

4.14.6

Error handling
Many inexperienced trackdisk programmers encounter program errors.
We recommend that you use our track support routines to minimize
problems. In addition to the normal device errors. the trackdisk device
has device specific errors:
'IDERR_NotSpecified
'IDERR NoSecHdr
'IDERR BadSecPmarrble
'IDERR BadSecID
'IDERR BadHdrSlIml
'IDERR BadSecSt:m
'IDERR TooFewSecs
'IDERR BadSecHdr
'IDERR WriteProt
'IDERR_DisJcChan3ed
'IDERR SeekError

(20)
(21)
(22)
(23)

(24)
(25)
(26)
(27)
(28)
(29)
(30)

error could not be determined

sector header not found
error in sector preamble
error in sector identifier
checksum error in header
checksum error in sector
too few or too many sectors on track
sector header unreadable
disk write protected
no disk inserted or disk changd
seek error during seek position
verification

201

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

'IDERR NcMam
'IDERR BadUnitNum
'IDERR_ BacDriveType
'IDERR DriveInUse
'IDERR PostReset

(31) insufftcient memory

(32) drive addressed not cmnected
(33) incompatible disk drive
(34) drive already in use
(35) user hit reset, waiting for reboot

The following routine returns either the error number (for a device
unspecified error), or the error in text format
struct StrPack
{

BYTE *String;
ULONG Len;
};

HTab [1 = {' 0' , '1' , , 2' , '3', '4' , 'S' , '6' , '7' ,

BYTE

'S','9','A','B','C','D','E','F'};

BYTE *ErrorStrings [1 = {"Not Specified\012\01S",

"No Sector Header\012\01S",
"Bad Sector Preamb1e\012\01S",
"Bad Sector ID\012\01S",
"Bad Header Sum\012\01S",
"Bad Sector Sum\012\01S",
"Too Few Sectors\012\01S",
"Bad Sector Header\012\01S",
"Write Protected\012\01S",
"Disk Changed\012\01S",
"Seek Error\012\01S",
"Not enough memory\012\01S",
"Bad Unit Number\012\01S",
"Bad Drive Type\012\01S",
"Drive In Use\012\01S",
"Post Reset\012\01S"}:
1***************************************************** **********

TrackDisk ProcessError ()

(Track Support) *

* Function: Processes Trackdisk-Error

*
*--------------------------------------------------------------*
* Input - Parameter:
*
* DiskExtIO: Device-Block
* StrPack: String-Packet for Error-String

*
*

***************************************************************/

VOID TrackDisk_ProcessError (DiskExtIO,StrPack)

struct IOExtTD
*DiskExtIO;
struct StrPack
*StrPack;
BYTE Error;
static BYTE *ErrStr;
Error = DiskExtIO->iotd Req.io Error;
StrPack->String = 01; StrPack->Len
= 01;
if (Error != (BYTE) 0)
{

if Error >= (BYTE) 20) && (Error <= (BYTE) 3S

{

StrPack->String
StrPack->Len
else

202

ErrorStrings[(Error-(BYTE)20)1;
(ULONG) str1en (StrPack->String);

4.14 THE

ABACUS

TRACKDlSK DEVICE

ErrStr
= n\012\015Error. \012\015";
ErrStr[9] = HTab[(Error4)&15];
ErrStr[lO] = HTab[Error&15];
StrPack->String = ErrStr;
StrPack->Len
= 131;

When you call this routine you must give the address of a string packet
as a parameter. Either the text of the error or a string in the format
Error tnn is given in this packet. You can then display ti"tis string.
This routine must be called directly after executing READ or WRITE
(TD_MOTOR is usually executed without an error). There is no problem
with the routine TrackDisk_WriteSector () because the
UPDATE command executes after WRITE. Here, as the user, you must
either call UP D ATE after Pro c e sSE r r 0 r () or integrate
ProcessError () into WriteSector ().
Combine the listed Track_Support fIles to form the Track_Supportc
file. The file header appears as follows:
1***************************************************** **********

*
Track Support. c
*
AugUst 1988
*
(c) Bruno Jennrich
* Compile-Info:
* cc Track Support.c

*
*
*

*** **.***.* *** * ***.****.*** *****.** ***.*********/

~include "exec/types.h n
'include nexec/memory.h n
iinclude Rexec/devices.h"
iinc1ude Rexec/interrupts.h"
~include "devices/trackdisk.h"

ide fine RAW- TRACK- LEN Ox397c1

'define MEMTYFE (ULONG) MEMF_CLEARIMEMF_CHIP
ide fine TD_LEN (ULONG) (sizeof (struct IOExtTD))
struct IOExtTD *InterruptIO = 01;
struct Interrupt *Interrupt = 01;
VOID *AllocMem () ;
VOID *GetDeviceB1ock();

203

4. DEVICES

4.14.7

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The disk editor

The following program allows you to read and write sectors, format
tracks and read disk status. You also have the option of writing the
sector contents to a ftle.
1***************************************************** **********

DiskEd.c
(c) Bruno Jennrich

* Compile-Info:
*
* cc DiskEd.c
*
* In DiskEd.o Track Support.o Con Support.o Devs Support.o -lc *
*** *** *** *********1
'include "exec/types.h"
'include "exec/memory.h"
'include "exec/devices.h"
'include "exec/interrupts.h"
'include "graphics/gfxbase.h"
'include "libraries/dos.h"
Unclude "devices/trackdisk. h"
'include "devices/console.h"
'include "devices/keymap.h"
'include "intuition/intuitionbase.h"
'include "intuition/intuition.h"
'define HEMTYPE
(HEME' CHIP I HEME' CLEAR)
'define CON LEN (ULONG)-(sizeof (struct IOStdReq
.define TD LEN (ULONG) (sizeof (struct IOExtTD))
'define RAW TRACK LEN
Ox397cl
VOID *CreatePort (f;
VOID *CreateExtIO();
VOID *Open () ;
VOID *AllocMem();
VOID *GetDeviceBlock();
VOID *OpenLibrary();
VOID *OpenScreen();
VOID *OpenWindow();
extern VOID TrackDisk DiskRemoved();
struct IntuitionBase *IntuitionBase
01;
struct Screen
*Screen
01;
struct Window
*Window
01;
struct NewScreen
NewScreen
0,0,640,200,4,
0,1,
HIRES,
CUSTOMSCREEN,
01,
(UBYTE*) "No Name",
01,
01
struct NewWindow

NewWindow

};
{

0,0,
640,200,
0,1,
01,
(ULONG) ACTIVATE,

204

4.14

ABACUS

THE TRACKDISK DEVICE

01,
01,
(UBYTE*) "TrackDisk-Editor (c) Bruno Jennri ch " ,

01,
01,

0,0,
0,0,
CUSTOMSCREEN

);
extern
extern
struct
struct

struct Interrupt *Interrupt;

struct IOExtTD
*InterruptIO;
IOExtTD
*DiskExtIO
= 01;
IOStdReq *ConsoleRead = 01,
*ConsoleWrite = 01;
awORD
*File
= 01;
BYTE
*SectorBuffer
01;
BYTE
*TrackBuffer = 01;
BYTE
*LabelBuffer = 01;
BYTE
ReadBuffer[256];
1* Keyboard-Buffer *1
HexTab [ ] = ( I 0 I , 11 I , I 2 I , I 3 I , I 4 I , I 5 I , I 6 I , I 7 I ,
BYTE
'S', '9', 'A', 'B', 'C', ID', 'E', IFI};
BYTE
ConversionTable[256];
struct StrPack
(

BYTE *String;
ULONG Len;
);

struct Offset
{

ULONG Track;
ULONG Sector;
ULONG Side;
};

/***************************************************************
*
CloseIt ()
(User) *
* Function: In case of erro close everything
*
* Input - Parameter:
*
* String: Error-Message
*
***************************************************************/
VOID Closelt (String)
char
*String;
{

awORD i;
awORD *dff180 = (awORD *)Oxdff180;
awORD Error = 0;
if (strlen (String) > 01)
{

for (i=O;i<Oxffff;i++)
puts (String);
Error = 10;

*dff180

i;

if (Window != 01)
CloseWindow (Window);
if (Screen != 01)
CloseScreen (Screen);
if (IntuitionBase != 01) CloseLibrary (IntuitionBase);
if (Interrupt != 01)
TrackDisk InterruptOff(DiskExtIO);
if (DiskExtIO->iotd Req.io Device != -11) Close A Device
(DiskExtIO) ;
-else FreeDeviceBlock (DiskExtIO);
if (SectorBuffer != 01)
FreeMem (SectorBuffer,TD SECTOR);
if (TrackBuffer != 01)
FreeMem (TrackBuffer, RAW_TRACK_LEN);

205

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

if (LabelBuffer != 01)
FreeMern (LabelBuffer,
if (ConsoleRead != 0)
if (ConsoleWrite != 0)
i f (File ! = 01)
exit (Error);

(ULONG) (NUMSECS;
Close A Device (ConsoleRead);
FreeD~viceBlock (ConsoleWrite);
Close (File);

1***************************************************** **********

*
TrackDisk DiskRemoved()
* Function: Interrupt-Routine ~alled by disk change

(User) *
*

****************************************************** *********1
'asrn

public
TrackDisk DiskRernoved
TrackDisk DiskRemoved:
move.w '$ffff,dO
loopa:
move.w
dO, $dffl80
dbra
dO,loopa
rts
ilendasm

1***************************************************** **********

*
*
*
*
*

ReadCornmand ()
Function: Read keyboard input (Console-Device)
Input - Parameter:
Buffer: Go to where with the input?
MaxLength: Maximum number of key presses

(User) *
*
*
*
*

***************************************************************/

VOID ReadCornmand (Buffer, MaxLength)

BYTE
*Buffer;
ULONG
Max Length;
{

BYTE *BufPointer;
BYTE Character;
ULONG Length;
Character = (BYTE) 0;
Length = (ULONG) 0;
BufPointer = Buffer;
while (Character != (BYTE) 13)
{

/* <RETURN> */
Console Read (ConsoleRead, &Character,ll);
if (Character == (BYTE) 8)
/* Backspace */
{

i f (Length> 01)
{

*BufPointer-- = (BYTE) '\000'; /* mark String end*/

Console Write (ConsoleWrite,&Character,11);
/* Backspace */
Console Write (ConsoleWrite," ",11); /*Delete char*/
Console Write (ConsoleWrite,&Character,11);
/* Backspace * /
Length--;
else
i f (Length < MaxLength)
{

if (Character ==
(ConsoleWri te, "\012",11) ;
i f (Character I
(Character I
*BufPointer++

206

(BYTE) 13) Console Write

(BYTE) Ox20) >= 'a') &&
(BYTE) Ox20) <= 'z'
= (Character I (BYTE) Ox20);

4.14

ABACUS

THE TRACKDlSK DEVICE

else
*BufPointer++ = Character;
Length++;
Console_Write (ConsoleWrite,&Character,ll):
*BufPointer = (BYTE)D;
1***************************************************** **********
*
HEXAtoULONG()
(User) *
* Function: Convert Hex-String to ULONG
*
* Input - Parameter:
*
* BufPointer: Addess of the Hex-String
*
* Return value:
*
* Valuse of the Hex-Strings (RABe" = Dxabc)
*
****************************************************** *********1
ULONG HEXAtoULONG (BufPointer)
BYTE
*BufPointer:
(

UWORD i;
ULONG Val = 01;
OWORD Len;
Len = strlen (BufPointer);
for (i=O;i<Len;i++)
(

if *BufPointer>= 'A') && (*BufPointer <= 'F'

(

Val *= 161;
Val += *BufPointer && (Oxff-Dx20-'A'+(BYTE)10);
else
if *BufPointer>= '0') && (*BufPointer <= '9'
{

Val *= 161;
Val += (ULONG) (*BufPointer-'O');
BufPointer++:
return (Val);
1***************************************************** **********

*
*
*
*
*
*

DEZAtoULONG ()
Function: Convert Decimal-String to ULONG
Input - Parameter:
BufPointer: Address of the Decimal-Strings
Return value:
Value of the Decimal-Strings (R123" = 123)

(User) *
*
*
*
*
*

***************************************************************1

ULONG DEZAtoULONG (BufPointer)

BYTE
*BufPointer;
(

UWORD i;
ULONG Val = 01;
UWORD Len:
Len = strlen (BufPointer):
for (i=O:i<Len;i++)
{

if *BufPointer>= '0') && (*BufPointer <= '9'

{

Val *= 101;
Val += (ULONG) (*BufPointer-'O');

207

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

Bufpointer++ ;
return (Val);
1***************************************************** **********

*
LONGtoA()
* Function: Convert LONG value to ASCII and display
* Input - Parameter:
* Val: LONG value

(User)*
*

****************************************************** *********1

VOID LONGtoA (Val)

ULONG
Val;
{

ULONG Start - 10000000001;

BYTE Ascii[ll];
UWORD i;
i=O;
do
{

Ascii[i] = '0';
while (Val >= Start)
{

Val -= Start;
Ascii[i]++;
i++;

Start /= 101;
while (Start != 01);
Console_Write (ConsoleWrite,Ascii,101);
1***************************************************** **********
*
UWORDtoHex()
(User) *
*
* Function: Convert UWORD value to Hex-String
*
* Input - Parameter:
*
* Val: UWORD value
* Buffer: where with Hex-Strings
*
***************************************************************/

VOID UWORDtoHex (Val ,Buffer)

UWORD
*Val;
BYTE
*Buffer;
{

UWORD Hex;
Hex
Hex
Buffer[O]
Hex
Hex
Buffer[l]
Hex
Hex
Buffer[2]
Hex
Buffer [3]

*Val , OxfOOO;
Hex 12;
HexTab[Hex] ;
*Val , OxOfOO;
Hex 8;
HexTab[Hex] ;
*Val , OxOOfO;
Hex 4;
HexTab[Hex] ;
*Val & OxOOOf;
HexTab[Hex] ;

1***************************************************** **********

Display ()
* Function: Display sector contents
* Input - Parameter:
* Offset: Sector number

(User) *

*
*

***************************************************************1

208

4.14 THE TaACKDISK DEVICE

ABACUS

VOID Display (SectorBuffer, LabelBuffer, Offset)

*SectorBuffer;
BYTE
* LabelBuffer;
BYTE
Offset;
ULONG
{

UWORD i, j;
UWORD BufPos = 0;
BYTE Strinq[20];
BYTE HexBuffer[72*16];
BYTE AsciiBuffer[72*8];
BYTE LabelBuff[8*SJ;
BYTE LabelAscii[17];
BYTE OffsetBuffer[14];
UNORD Offs;
OffsetBuffer[ 0]
'B':
OffsetBuffer[ I] - 'I';
OffsetBuffer[ 2]
'0':
OffsetBuffer[ 3]
'c':
OffsetBuffer[ 4J e 'k':
OffsetBuffer[ SJ = ':':
OffsetBuffer [ 6]
OffsetBuffer[ 7] = '$';
OffsetBuffer[ 8]
";
OffsetBuffer[ 9] = , ':
OffsetBuffer[10]
":
OffsetBuffer[11] - , ';
OffsetBuffer[12]
'\012';
OffsetBuffer[13] - '\015':
Offs - (tJWORD) Offset; 1* convert to tJWORD for UWORDtoHex () *1
UWORDtoHex (&Offs,&OffsetBuffer[8J):
Console Write (ConsoleWrite,OffsetBuffer,14l):
Console-Write (ConsoleWrite,"Labelbuffer:\012\01S",-1l):
for (i-0:i<8:i++)
2

':

LabelBuff [i*S] - , ':

UWORDtoHex LabelBuffer+i*2),&LabelBuff[i*S+1]):
Console Write (ConsoleWrite,LabelBuff,8l*Sl);
Console-Write (ConsoleWrite,"\012\01S",-ll):
LabelAscii[O] - ' ';
for (i=0:i<16:i++)
(

LabeIAscii [i+1] ConversionTable[(UBYTE)*(LabelBuffer+i)]:

}

Console Write (ConsoleWrite,LabelAscii,17l);

Console=Write (ConsoleWrite,"\012\OlS\012\01S",-11);
for (i-o:i<16:i++)
1* 16 Lines *1
(

HexBuffer[i*72] - , ';
tJWORDtoHex(&BufPos,&HexBuffer[i*72+1]);
HexBuffer[i*72+S] - , ':
for (j=0;j<16:j++)/* 32 Bytes (16 UWORDS}=64 chAracters *1
{

UNORDtoHex
(&SectorBuffer[BufPos],&HexBuffer[l*72+6+j*4]}:
BufPos += 2;
}

HexBuffer[i*72+70) - '\012';
HexBuffer[i*72+71] - '\015':
Console Write (ConsoleWrite,HexBuffer,16l*72l):

209

4.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DEVICES

BufPos = 0;
for (i=0;i<8;i++)
(

AsciiBuffer[i*72) = ' ';

UWORDtoHex(&BufPos,&AsciiBuffer[i*72+1);
AsciiBuffer[i*72+s)
";
for (j=0;j<64;j++)
(

AsciiBuffer[i*72+6+j)
ConversionTable[(UBYTE)SectorBuffer[i*64+j));
BufPos ++;
)

AsciiBuffer[i*72+70] - '\012';
AsciiBuffer[i*72+71I
'\015';
Console Write (ConsoleWrite,AsciiBuffer,8l*72l);
i f (File ! = 0)
{

Write (File,ft\012 ft ,-ll);

Write (File,OffsetBuffer,131);
Write (File, "Labelbuffer: \012 ft ,14l);
Write (File,LabelBuff,8l*sl);
Write (File,ft\012",1l);
Write (Fi1e,LabelAscii,17l);
Write (File,,.\012------------------------------\012,.,73l);
for (i=0;i<16;i++)
(

HexBuffer[i*72+70)
HexBuffer[i*72+71)

';

'\012' ;

for (i=0;i<8;i++)
{

AsciiBuffer[i*72+70)
AsciiBuffer[i*72+71)

';

'\012';

Write (File, HexBuffer, (721*161;

Write (File,"\012 ft ,11);
Write (File,AsciiBuffer, (721*81;
1***************************************************** **********

*
GetOffset ()
(User) *
*
* Function: Get offset for READ/WRITE from input string
*
* Input - Parameter:
*
* BufPointer: Addesseof the Input - Strings (HEX or DEC)
* Return value:
*
* Offset recieved
*
***************************************************************/
ULONG GetOffset (BufPointer)
BYTE
*BufPointer;
{

BYTE *SecBuf;
SecBuf = BufPointer;
while *BufPointer != (BYTE) 0) && (*BufPointer != '$') &&
(*BufPointer != "' BufPointer++;
if (*BufPointer
(BYTE) 0) return (-11);
else
if (*BufPointer
'$') return (HEXAtoULONG (BufPointer+1) ) ;
else
if (*BufPointer
',') return (DEZAtoULONG (BufPointer+1) );
else
if *BufPointer >= '0') ,& (*BufPointer <= , 9'

210

4.14

ABACUS

THE TRACKDlSK DEVICE

return(DEZAtoULONG (SecBuf;
1***************************************************** **********

HandleCorrrnands ()
(User) *
* Function: Process commands entered
*
***************************************************************/
VOID HandleCommands ()

BYTE *Bufpointer;
BYTE
Command;
BOOL
QuitFlag;
struct StrPack StrPack;
ULONG Count;
ULONG Offset = 01;
QuitFlag = FALSE;
while (!QuitFlag)
{

ReadCommand (ReadBuffer,2561);
Bufpointer = ReadBuffer;
while (*Bufpointer == , ') BufPointer++;
/* skip spaces */
Command = *BufPointer;
/* the first character after ' , is the commnand */
switch (Corrrnand) /* Which command? */
{

case (BYTE)' h' :

/* help */
Console Write (ConsoleWrite, "\012\015r/1/$ [Block]
- Read Sector\012\015",43l);
Console Write (ConsoleWrite, "wlt/$ [Bl,ock]
- Write Sector\012\015",41l);
Console Write (ConsoleWrite,"f[Track]
- Format Track\012\Ol5",41l);
Console Write (ConsoleWrite,"s
- Disk Status\012\015",40l);
Console Write (ConsoleWrite,"d
- Display Sector\012\015",43l);
Console Write (ConsoleWrite,"q
- Quit \012\015",341);
Console Write (ConsoleWrite,"h
- This Reference\012\015",431);
break;
case (BYTE)' r':
/* Read */
Offset = GetOffset (Bufpointer);
TrackDisk_Motor(DiskExtIO,TRUE);
TrackDisk ReadSector
(DiskExtIO,SectorBuffer,LabelBuffer,Offset);
TrackDisk_ProcessError (DiskExtIO,&StrPack);
TrackDisk Motor(DiskExtIO,FALSE);
Console Wi"ite
(ConsoleWrite,StrPack.String,StrPack.Len);
break;
case (BYTE) 'w':
/* Write */
Offset = GetOffset (BufPointer);
TrackDisk_Motor(DiskExtIO,TRUE);
TrackDisk WriteSector
(DiskExtIO,SectorBuffer,LabelBuffer,Offset);
TrackDisk ProcessError (DiskExtIO,&StrPack);
TrackDi sk=Mot or (DiskExtIO,FALSE);

211

4.

DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

console Write
(ConsoleWrite,StrPack.String,StrPack.Len);
break;
case (BYTE)' f':
Offset = GetOffset (BufPointer);
TrackDisk Motor(DiskExtIO,TRUE);
TrackDisk-Format (DiskExtIO,Offset);
TrackDisk-ProcessError (DiskExtIO,&StrPack);
TrackDisk=Motor(DiskExtIO,FALSE);
Console Write
(ConsoleWrite,Strpack.String,StrPack.Len);
break;
case (BYTE)' s' :
Console Write (ConsoleWrite,"\012\01SDiskChangeCount
",-II);
DiskExtIO->iotd Count =
TrackDisk_GetDiskChangeCount(DiskExtIO);
LONGtoA (DiskExtIO->iotd Count);
Console Write (ConsoleWr"ite,"\012\01S",-11);
if (TrackDisk GetProtStatus(DiskExtIO) != 01)
Console Write (ConsoleWrite,"Disk
protected\012\01S", -ll);
else
Console Write (ConsoleWrite,"Disk not
protected\012\01S", -11);
if (TrackDisk GetChangeState(DiskExtIO)
01)
Console Write (ConsoleWrite,"Disk
inserted\012\01S",-11)~

else
Console Write (ConsoleWrite,"Disk
removed\012\01S",-11);
/* Status */
break;
case (BYTE)' d' :
/* Display */
Display (SectorBuffer,LabelBuffer,Offset);
break;
case (BYTE) 'q':
QuitFlag = (BOOL)TRUE;
break;
case (BYTE) 13:
/* Intercept Return */
break;
default:
Console Write (ConsoleWrite,"\012\OlS\Bad
Command! ! ! \012\OlS"~-11);
break;

1***************************************************** **********

The TrackDisk Device ()

* Function: Use Trackdisk-Devioe

Input - Parameter:
* Unit: Which disk drive?

(User) *

*
*
*

***************************************************************/

VOID The_Trackdisk Device (Unit)

ULONG
Unit;
(

ULONG Offset;
Open_A_Device ("trackdisk.device",Unit,&DiskExtIO,Ol,TD LEN);
TrackDisk_InterruptOn(DiskExtIO,TrackDisk_DiskRemoved);

212

4.14

ABACUS

THE TRACKDISK DEVICE

HandleComnands ();
TrackDisk InterruptOff(DiskExtIO);
Close_A_Device (DiskExtIO);
1***************************************************** **********
*
Open Screen and Window ()
(User) *
* Function: Editor Screen and Window open
*
****************************************************** *********1

VOID Open_Screen_and_Window()
{

IntuitionBase = (struct IntuitionBase*)

OpenLibrary ("intuition. library" ,01);
if (IntuitionBase = 01) CloseIt ("No IntuitionBase rtf);
Screen = (struct Screen *) OpenScreen (&NewScreen);
if (Screen == 01) CloseIt ("No Screen rtf);
NewWindow.Screen = Screen;
Window = (struct Window *) OpenWindow (&NewWindow);
if (Window = 01) CloseIt ("No Window!");
1***************************************************** **********

*
Open Screen and Window ()
* Function: Editor Screen and Window ~lose

(User) *
*

***************************************************************/

VOID Close Screen and Window()

--

CloseWindow (Window);
CloseScreen (Screen);
CloseLibrary (IntuitionBase);
1***************************************************** **********

main ()

(User) *

*--------------------------------------------------------------*
* Input - Parameter:
* argv[l]: Disk drive (dfO:, df1: etc.)
* argv[2]: Output_file

*
*

***************************************************************/

main (argc,argv)
UWORD argc;
BYTE
*argv[];
{

UWORD i;
ULONG Unit=Ol;
BYTE *InputString;
UWORD Len;
InputString = argv[l];
i f (argc >= 2)
(

Len = strlen(InputString);
for (i=O;i<Len;i++)
{

if *InputString >= 'A') && (*InputString <= 'Z'

*InputString 1= (BYTE) Ox20; 1* lowercase letters *1
InputString++;
}

i f (strcmp ("dfO: ", argv[l])

else
i f (strcmp ("dfl:", argv [1] )
else
i f (strcmp ("df2:",argv[1] )
else
i f (strcmp ("df3:", argv [1] )

01) Unit

0;

01) Unit

1;

01) Unit

2;

01) Unit

3;

213

4. DEVICES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

i f (argc == 3)
(

File = Open (argv[2] ,MODE NEWFILE);

if (File == 01)
(

printf ("Can't open %s!",argv[2]);

CloseIt (n ");
}

i f (argc > 3)
{

printf ("USAGE: b

[[DF?:] [ListFile]]!\n",argv[O]);

exit (0);

Open Screen and Window(};

SectorBuffer = (BYTE*) AllocMem ULONG) (TD SECTOR) ,MEMTYPE);
/* ffor one sector (Read/Write) */
if (SectorBuffer == 0) CloseIt ("No SectorBuffer !");
TrackBuffer = (BYTE*) AllocMem (RAW_TRACK_LEN,MEMTYFE);
/* for one track (RAWREAD/WRITE) */
if (TrackBuffer == 0) CloseIt ("No TrackBuffer ! ") ;
LabelBuffer = (BYTE*) AllocMem ULONG) (NUMSECS), MEMTYFE) ;
/* for Label-Area */
if (LabelBuffer == 0) CloseIt ("No LabelBuffer ! ");
for (i=O ;i<32 ;i++) ConversionTable[i]
(BYTE) '. ';
for (
;i<128;i++) ConversionTable[i]
(BYTE)i;
for (
;i<160;i++) ConversionTable[i]
(BYTE)', ';
for (
; i<256; i++) ConversionTable [i]
(BYTE) i;
ConsoleRead = (struct IOStdReq *)GetDeviceBlock (CON_LEN);
ConsoleWrite = (struct IOStdReq *)GetDeviceBlock (CON LEN);
ConsoleRead->io Data
= (APTR) Window;
ConsoleRead->io Length = (ULONG) (sizeof (struct Window;
Open_A_Device ("console.device",Ol,&ConsoleRead,Ol,Ol);
Console Copy (ConsoleRead,ConsoleWrite);
Console=Write (ConsoleWrite,
"Welcome to the wonderful World of TrackDisk !\n",-ll);
The_Trackdisk_Device(Unit);
Close A Device (ConsoleRead);
FreeoevIceBlock (ConsoleWrite);
if (File != 01) Close (File);
FreeMem (SectorBuffer, (ULONG) (TD SECTOR;
FreeMem (TrackBuffer ,RAW TRACK LEN);
FreeMem (LabelBuffer ,(ULONG) (NUMSECS;
Close_Screen_and_Window();

The program is called using its name and an argument representing a

filename to which you would like the data saved. For example, the
following command sequence invokes the disk editor, reads the disk in
drive DF1: and creates a file named listfile:
DiskEd dfl: listfile

The disk sector contents appear on the screen. Entering <d><Return> ,

writes the data to the file l i st file. Pressing <h><Return> lists the
command overview. The following command calls the disk editor and
loads the sector data from the disk in DFO: (no file is created):
DiskEd

214

5.1

ABACUS

5.

IFF

Standard File Formats

Software developers have invented file fonnats based on specific
standards. File standards allow a user to pass data between drawing
programs, word processors and even sound programs.

5.1

IFF
Most commercial software developers used their own file fonnats. It
was easier to implement file systems in house, rather than try
confonning to a standard. On one hand, this costs money because the
buyer must finance each development. On the other hand, independent
file formats make it impossible to exchange data between two different
programs if they are incompatible. A universal file fonnat would make
applications more marketable for their flexibility.

Enter Electronic Arts

The staff of Electronics Arts discussed this very problem. The Apple
Macintosh had a generally accepted set of fonnats for exchanging data
between programs. EA felt that a file standard could be created for the
Amiga that could be used for text, graphics and sound files alike.
The format is called IFF (Interchange File Fonnat). Electronic Arts
developed the fonnat in 1984 and made it available to the public in
January 1985. Developers have expanded IFF to fit the requirements of
their programs. And although IFF saves more data in a file than other
file fonnats under certain conditions, error free file reading is almost

guaranteed.
This chapter splits IFF into many different forms. All are IFF, but all
have their own qualities. We divided the chapter to keep parameters and
IFF factors consistent with each format category.

The philosophy of IFF

All IFF systems have a standardized design. This makes processing
simple. You'll always find the following items in an IFF file:

215

5.

STANDARD FILE FORMATS

Header

ADVANCED SYSTEM PROGRAMMER'S GUIDE

A header always exists at the beginning of each file. The header retains

all the infonnation that informs the program of data found in this file,
as well as the type of data in the file (i.e., graphic data, sound data or
text data).

Chunks

Chunks comprise the remainder of the file. Chunks are blocks of data
that contain groups of data. For example, an IFF me containing music
data has a chunk outlining the parameters of each musical voice's sound
capabilities. A graphic IFF me has a color chunk in which it stores all
the cob data needed for the graphic. Chunks provide the developer with
a system of data building blocks which, like a set of toy building
blocks, can be expanded as much as possible. This open format ensures
that IFF will be around for a long time, since it is so open to
expansion.
Each of the chunks discussed here is identified in the header by four
characters. The data follows the chunk (we'll spend most of this chapter
looking at chunk data).

5.1.1

The IFF ILBM graphic format

IFFs popularity is mostly attributable to the drawing program
DeluxePaint, which many users consider the standard among drawing
programs. This is partly why many programs which make use of
graphics use IFF for file management Let's take a closer look at the
ILBM (interLeaved BitMap) and how it is consbUCted.
The form makes up a large part of an IFF graphic file. This form
combines many chunks into a single file. And because all of the
chunks belong to one graphic file, they are packed. The form contains a
single item of information- the length of the data file and the data
type. So the read routine can later determine if all of the data is actually
present
'define ID_ILBM MakeID('I', 'L', 'B','M')

Next comes the labeling of the ILBM format. The four letters "ILBM"
indicate this particular format. The individual chunks of our data file
follow. Let's look at them one at a time.

BHHD

(BitHapHeaDer)
'define ID_BMHD MakeID('B', 'M', 'H','O')

lU

5.1

ABACUS

IFF

This chunk contains the data that cover the fonnal attributes of our
graphic. It is handled as a structure that is important later for opening
the screen, because it acts as a storage space for measurements, depth
and other values. Take a closer look at this structure:
typedef struct
(

UWORD w, h;
WORD x, y;
UBYTE nPlanes;
Masking masking;
Compression compression;
UBYTE padl;
UWORD transparentColor;
UBYTE xAspect, yAspect;
WORD pageWidth, pageHeight;

/* Width and height

/* Position
/* Depth of the screen
/* Contains mask flags
/* Compression Type
/* Fill byte
/* Number of trns. color
/* Aspects
/* Screen width & height

*/
*/
*/
*/
*/

*/
*/
*/
*/

BitMapHeader;

The w (width) and h (height) variables define the graphic's size in

pixels. A graphic doesn't have to be saved at the same size as the
screen. The brushes that are managed by the drawing program are also
saved as ILBMs, and in most cases do not encompass the full screen
dimensions.
The x and y variables specify the position of the graphic section. When
an entire screen is saved, these parameters contain the value O.
The nPlanes variable state the number of bit-planes used in the
graphic. This is different from the colonnap, because the number of
colors calculated is derived from the number of bit-planes.
The Masking variable specifies the type of masking used by the
graphic. You can select from mskNone (where no masking results) or
mskHasMask. In addition to the nonnal bit-planes, aMaskPlane is
saved that designates the masking for the graphic. The flag
mskHasTransparentColor announces that the graphic includes a
transparent color (the number of this transparent color lies in the
transparentColor variable). A setting named mskLasso is
taken from the Apple Macintosh. This encircles the graphic like a
lasso. This makes it possible to remove the border of the graphic,
which reduces the size of the graphic and saves memory.
typedef
#define
#define
#define
#define

UBYTE Masking;
mskNone OL
mskHasMask lL
mskHasTransparentColor 2L
mskLasso 3L

217

s.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

STANDARD Fn.E FORMATS

The compression variable specifies the type containing the bit-map

data. Either this variable contains nothing, which means the data is
taken from the memory and saved exactly as it is, or a number which
designates the method by which the data is keyed and packed.
typedef UBYTE Compression;
'define cmpNone OL
'define cmpByteRunl lL

The Padl variable contains a fill byte, ensuring that the structure
contains an even number of bytes. This byte is currently unused, so it
contains zero. In every case this should be watched because later
versions may make other use of this, and a value other than zero may
cause problems.
The xAspect and yAspect variables contain the ratio between the X
side and Y side of the graphic. This information is important for
programs that transport graphics from one resolution to another, or
transport graphics from one brand of computer to another brand
altogether.
ide fine
'define
'define
'define
'define
'define
'define
'define

x320x200Aspect
y320x200Aspect
x320x400Aspect
y320x400Aspect
x640x200Aspect
y640x200Aspect
x640x400Aspect
y640x400Aspect

10L
llL
20L
llL
SL
llL
10L
llL

The pageWidth and pageHeight variables supply additional

information about the graphic that can actually be larger or smaller than
the screen on which it is displayed.
CHAP

(Col.orHAP)
'define ID_CMAP MakeID('C', 'M', 'A', 'P')

The colormap is the opposite of the bit-map header of a chunk that

doesn't always have the same length. The length depends on how many
bit-planes the graphic has, since the colormap computes the number of
colors saved from the bit-planes.
Each color register stores three byte values (red, green and blue). Values
for these section colors can range from 0 to 255. The Amiga doesn't
have that many shades. But because the IFF format was developed for
more than one computer, some extra flexibility was added. This is why
we must move all of the color values into the higher placed bit (i.e.,
multiply it by 16). Each color register also has a structure:

218

5.1

ABACUS

IFF

typedef struct
{

UBYTE red, green, blue;

}

ColorRegister;

Please bear in mind that creating and reading an IFF file may give the
colormap an odd number of bytes. Then the list must be completed
with a null byte.
CRHG

(ColorRaKG)
'define ID_CRNG MakeID('C', 'R', 'N', 'G')

It's possible to cycle through a color region, creating very interesting

effects. The CRNG chunk supports this function. It gives an area in the
color table that should be washed out The structure for this looks like
the following:
typedef struct
{

WORD padl;
WORD rate;
WORD active;

UBYTE low, high;

) CRange

padl supplies the necessary fill character.

Ra t e specifies the speed at which the colors are exchanged. For
example, 16384 sets 60 changes per second. One rule: the larger the
number, the more steps per second.

CCR'l'

(Color

Cycling

Range

and

'l'iming)

'define ID_CRNG MakeID('C','C', 'R', 'T')

The CCRT chunk also controls color cycling. Both chunks are treated
by independent tasks, depending on the manufacturer. CommodoreAmiga's GraphiCraft uses the CCRT chunk, while DeluxePaint uses
the CRNG chunk.
We must read both chunks into our program and process them to make
them completely compatible with colorcycling. Because both chunks
are somewhat different, there is another structure:
typedef struct {
{

WORD direction;

UBYTE start, end;

seconds;
microseconds;
WORT pad;
} Cyclelnfo;
WNG
WNG

219

s.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

STANDARD Fn.E FORMATS

The direction variable gives the direction in which the color should
be cycled. 0 no movement, 1 forward and -1 reverse. Start and
end give the starting and ending number of both color registers
between which color change occurs.

The CCRT chunk handles time differently from the CRNG chunk.
Commodore-Amiga gives the seconds and microseconds
variables. This is the same as the other functions in the Amiga library.
Then this division also takes place there (look at the Preferences
structure and the Intuition library).
Pad acts as the fill byte to keep the structure set at an even number of
bytes.
Before we examine the most important of all of the chunks (the BODY
chunk), we must address some lesser used chunks.

GRAB

(GRAB

position)
jdefine ID_GRAB MakeID ('G', 'R', 'A', 'B')

The GRAB chunk indicates the relative position of the cursor. This is
useful for placing brushes, which can be placed at any point on the

screen.
typedef struct
(

WORD x, y;
)

Point2D;

The x and y coordinates specify the upper left comer of the graphic.
The entire GRAB chunk consists only of this point2D structure.

DEST

(DESTination

bitp~anes)

jdefine ID_DEST MakeID('D', 'E', 'S','T')

This chunk allows placement of the available bit-planes of the BODY

chunk in other bit-planes of the graphic, while filling the unused bitplanes with 0 or 1 bit values. So you can easily change the colors of
the original graphic. This chunk also consists of a data structure
containing all of the applications:

220

5.1

ABACUS

IFF

typedef struct
{

UBYTE
UBYTE
UWORD
UWORD
UWORD

depth;
padl;
planePick;
planeOnOff;
planeMask;

DestMerge;

The depth variable designates the depth of the screen in which the
data should be entered.
The padl variable represents a ftll byte (currendy unused here).

The planePick variable examines the set bits. Each set bit is named:
packs the next bit-plane from the file in the bit-plane of the screen with
the number oflhe set bit. When a bit is not set, the same bit is
considered under planeOnOff. When this is set the entire bit-plane is
filled with I, otherwise you clear it.
planeMask has the task of suppressing writing to a bit-plane. The
corresponding bit for a bit-plane is set if it should be written in this
variable. In the opposite case, this bit is cleared and the bit-plane
remains undisturbed. The planePick and planeMask variables
contain the default value 2"nPlanes - 1. This ensures all set bits
for each plane, as well as the use of all available bit-planes.

SPRT

(SPRiTe)
'define ID_SPRT MakeID('S', 'P', 'R','T')

Sprites can also be saved in ILBM files with the help of this chunk.
The chunk's single value designates the precedence of the sprite. The
value 0 represents highest precedence. The higher the value, the lower
the sprite precedence. The sprite with the highest precedence is
graphically placed ahead of all others.
typedef UWORD SpritePrecedence;

CANG

(Commodore

AMiGa

computer)

'define ID_CAMG MakeID('C', 'A','M','G')

Unlike the other computers that have IFF file systems, the Amiga
includes a set of ViewModes. These display modes include HAM and
interlace mode. A new chunk (the CAMG chunk) compensates for the
support not given by normal IFF ILBM chunks. The CAMG chunk
contains only the ViewMode register:

221

5.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

STANDARD Fn.E FORMATS

typedef struct
(

ULONG ViewHodes;
)

CarrqChunk;

BODY

(all Bit-planes and the

interleaveD bY row)

Optional

mask,

'define ID_BODY MakeID('B', 'O','D','Y')

The BODY chunk contains the bit-map-the most important section of

the IFF graphic file. This chunk operates under certain rules set by the
other data.
After the number of the colors and bit-planes. the BODY chunk lists
the data report. This report contains the bit-map in a linear (line
oriented) formal This means that the report saves the first row of the
first bit-plane. then the first row of the second bit-plane. and so on.
When the fast rows of all the bit-planes and the optional masks are
saved. the next row is written in the same order (frrst bit-plane. second
bit-plane. etc.). This continues until the last row of the last bit-plane.
1benthe BODY chunk ends.
This knowledge of the memory layout is very important. especially for
graphics that consist of very large color areas. When you add the
information about compression covered earlier in this chapter. you can
actually save some memory when saving these files.
The following program reads and displays IFF files.
1***************************************************** *********/
/*
Simpler IFF-Read und Di splay
*/
/*
(ONE SPEED-UP)
*/
/* (c) Bruno Jennrich
*/
/**************************************************************/
'include "exec/types.h"
'include "exec/memory.h"
'include "exec/devices.h"
'include "devices/keymap.h"
'include "graphics/gfxmacros.h"
'include "graphics/regions.h"
tinclude "graphics/copper.h"
tinclude "intuition/intuition.h"
'include "graphics/gfxbase.h"
iinclude "graphics/gels.h"
iinclude "hardware/custom.h"
iinclude "hardware/blit.h"
struct IntuitionBase *IntuitionBase;
struct GfxBase
*GfxBase;
long
char Mask[9]

222

*DosBase;
(0,1,2,4,8,16,32,32);

/* color number */

5.1

ABACUS

IFF

typedef struct BitMapHeader {

UWORD
WORD
UBYTE
UBYTE
UBYTE
UBYTE
UWORD
UBYTE
WORD

w/h;

x,y:
BitPlanes;
Masking;
Compression;
PadByte;
TransCol;
XAspect,YAspect;
Width, Height;

};
typedef struct ColorRegister

UBYTE red;
UBYTE green;
UBYTE blue;
typedef struct CommodoreAmiga

};
{

UWORD PadWord;
UWORD ViewModes;

};
struct BitMapHeader BMHD;
struct ColorRegister Colors [32];
struct CommodoreAmiga CAMG;
struct Screen *Screen;
struct NewScreen NewScreen;
LONG FileHandle;
LONG Len;
ULONG ChunkLen;
BOOL BMHDFlag;
BOOL CMAPFlag;
BOOL CAMGFlag;
BOOL BODYFlag;
BOOL FoundChunk;
BOOL ShowFlag = FALSE;
UBYTE Buffer [300];
/* General Counter */
LONG i;
LONG x;
/* Column Counter */
LONG y;
/* Line Counter */
/* BitPlane Counter */
LONG b;
UBYTE ByteCount;
UBYTE BytesPerRow;
/* BitPlane Address */
char *WhereIsIt;
char *MouseButton
(char *) OxBFEOOl;
CloseIt (s)
char *s;
{

printf ("%s\n",s);
if (FileHandle != 0) Close (FileHandle);
if (Screen != 0) CloseScreen (Screen);
if (DosBase != 0) CloseLibrary (DosBase);
if (IntuitionBase != 0) CloseLibrary (IntuitionBase);
if (GfxBase != 0) CloseLibrary (GfxBase);
exit (0);
Lread (Buffer,Num,Flag)
LONG Buffer;
WORD Num;
BOOL Flag;
{

Len = Read (FileHandle,Buffer,Num);

if Flag == TRUE) && (Len < 0 Closelt ("File-Error
!! ! ! ! ! ! !\n");

223

5.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

STANDARD FaE FORMATS

main (argc, argYl

1* Argument Counter *1
1* Argument Value *1

int argc;
char **argv;
i f (argc ! = 2)
(

printf (" USAGE: \"ShowILBM IFF-Filenarne\"\n");

else
(

printf (" End by clicking in the upper left hand corner. \n");
DosBase= (LONG *) OpenLibrary("dos.library",O);
GfxBase= (struct GfxBase *) OpenLibrary ("graphics.library", 0);
IntuitionBase=(struct IntuitionBase *)
OpenLibrary("intuition.library",O);
if DosBase == 0) I I (GfxBase == 0) I I (IntuitionBase
0
CloseIt ("Librarys ?!?!?!?!?!?!?!?!?!?!?\n");
FileHandle = Open (argv[1],1005);
if (FileHandle == 0) CloseIt ("File OPEN Error ! \n");
Lread (Buffer,12,TRUE);
if (strncmp(&Buffer[0],"FORM",4) != 0) CloseIt ("Not
IFF-File !!! \n");
if (strncmp(&Buffer[8] ,"ILBM",4) != 0) CloseIt ("Not
ILBM-File !!! \n");
BMHDFlag = FALSE;
CMAPFlag = FALSE;
CAMGFlag = FALSE;
BODYFlag = FALSE;
Loop:
FoundChunk = FALSE;
Lread (Buffer,8,FALSE);
i f (Len <= 0)
i f BMHDFlag == TRUE) && (BODYFlag
TRUE) &&
(CMAPFlag == TRUE
(

if (CAMGFlag == FALSE) printf (" No CAMG !!! \n");

LoOpA:
while *MouseButton & Ox40) == Ox40);
if Screen->MouseX == 0) && (Screen->MouseY
CloseIt ("");
else goto LoopA;

else
if BMHDFlag != TRUE) I I (BODYFlag != TRUE) I I
(CMAPFlag ! = TRUE
(

i f (BMHDFlag == FALSE) CloseIt (" No BMHD ! ! ! \n");

i f (BODYFlag == FALSE) CloseIt (" No BODY ! ! ! \n");
i f (CMAPFlag == FALSE) CloseIt (" No CMAP ! ! ! \n");
)

Chunk Len
Buffer[4]*16777216+Buffer[5]*65536+Buffer[6]*256+Buffer[7];

224

S.l

ABACUS

if (strncmp (Buffer, "BMHD",4)

IFF

0)

if (BMHDFlag == TRUE) CloseIt (" Two BMHD's ?\n");

Lread (&BMHD,ChunkLen,TRUE);
/* BMHD Read */
NewScreen.LeftEdge = 0;
NewScreen.TopEdge = 0;
NewScreen.Width = BMHD.Width;
NewScreen.Height = BMHD.Height;
NewScreen.Depth = BMHD.BitPlanes;
if (CAMGFlag = TRUE) NewScreen.ViewModes
CAMe;. ViewModes;
else
{

NewScreen.ViewModes = 0;
if (NewScreen.Width > 320)
NewScreen.ViewModes 1= HIRES;
if (NewScreen.Height > 200)
NewScreen.ViewModes 1= LACE;
NewScreen.Type = CUSTOMSCREEN;
NewScreen.Font = NULL;
NewScreen.DefaultTitle = (UBYTE *) argv[I);
NewScreen.Gadgets = NULL;
NewScreen.CUstomBitMap = NULL;
Screen = (struct Screen*) OpenScreen (&NewScreen);
if (Screen == 0) CloseIt (" No Screen !!! \n");
BytesPerRow = BMHD.Width/B;
ShowTitle (Screen,FALSE);
BMHDFlag = TRUE;
FoundChunk = TRUE;
if (strncmp (Buffer, "CMAPR,4) == 0)
{

before CMAP

if (CMAPFlag == TRUE) CloseIt("Two CMAP's ?\n");

i f (BMHDFlag == FALSE) CloseIt("BMHD must be
! ! ! \n");
Lread (Colors,ChunkLen,TRUE); /* BMHD read */

for (i=O; i<Mask[BMHD.BitPlanes); i++)

SetRGB4(&Screen->ViewPort,i,Colors[i] .red4,Colors[i] .green4,
Colors[i) .blue4);
CMAPFlag = TRUE;
FoundChunk = TRUE;
if (strncmp (Buffer, "BODY", 4)

0)

if (BODYFlag == TRUE) CloseIt ("Two Body's ???\n");

if (BMHDFlag == FALSE)
CloseIt ("BMHD must come before BODY !!!\n");
for (y=O; y<BMHD. Height;y++)
for (b=O;b<BMHD.BitPlanes;b++)
{

Bytecount = 0;
WhereIsIt =
(char *) Screen->RastPort.BitMap>Planes[b)+y*BytesPerRow;
if (BMHD.Compression == 0)
{

Lread (WhereIslt,BytesPerRow,TRUE);
}

if (BMHD.Compression == 1)

225

S.

STANDARD Fn.E FORMATS

ADVANCED SYSTEM PROGRAMMER'S GUIDE

while (ByteCount<BytesPerRow)
{

Lread (&Buffer[0],1,TRUE);
if (Buffer [0] < 128)
{

Lread (WhereIslt+ByteCount,Buffer[0]+1,TRUE);
ByteCount += Buffer[0]+1;
}

/* Buffer[O]

128 => Nop */

if (Buffer [0] > 128)
==

Lread (&Buffer[1],1,TRUE);
for (i=ByteCount;iByteCount+257-Buffer[0]);i++)
* (Wherelslt+!) = Buffer[1];
ByteCount += 257-Buffer[0];
}

BODYFlag = TRUE;
FoundChunk = TRUE;
if (strncmp (Buffer, "CAMG",4)

== 0)

if (CAMGFlag == TRUE) Closelt ("Two CAMG's !!!\n");

if (BMHDFlag == FALSE)
Closelt ("BMHD must come before CAMG !!! \n");
Lread (&CAMG,ChunkLen,TRUE);
Screen->ViewPort.Modes = CAMG.ViewModes;
RemakeDisplay();
CAMGFlag = TRUE;
FoundChunk = TRUE;
}

if (FoundChunk == FALSE)
{

Lread (Buffer,ChunkLen,FALSE);
if ChunkLen & 1) == 1) Lread
(Buffer,1,FALSE);
}

goto Loop;

Program description
The program uses two universally supported routines. The
CloseIt () function closes the program in case of an error or the end
of the program. It checks what was opened and closes open files to
prevent system errors. The Readlt () function reads a certain quantity
of data.
The main program begins by opening the libraries and files, then
reading the data. First a test is performed for the existence of an IFF
ILBM , then the fIrst chunk in the main loop is selected. If recognized
by the program, its data is read in according to the rules described
above. Unknown chunks or those not supported by the program are
simply ignored.

226

5.1

ABACUS

IFF

When the necessary data is present, the BMHD reader opens a screen in
which the bit-map data with the BODY chunk: is entered. The program
waits for a mouse click in the upper left corner to close everything and
create its work. Next we see the ILBM format of an arrangement of all
of the chunks that can be encountered when you read an ILBM FORM.
Remember when writing that all of the chunks that are read, including
those that your program does not process, are written back to disk.
iHndef
'define
'define
'define
'define
'define
'define
'define

1LBM H
1LBM H
1D AN:FR
1D-MAHD
1D=MFHD
1D CMI6
ID-ILBM
ID=ILBM

'define
idefine
'define
'define
'define

ID_ANIM
ID_BMHD
ID_ANHD
ID CHAP
ID=GRAB

'define ID_DEST
'define ID_SPRT
'define ID_CAMG
'define
'define
'define
'define

ID BODY
1D-ATXT
ID-PTXT
ID=DLTA

'define ID_CRNG

Make1D('A','N",'F','R')
Make1D('M', 'A', 'H','D')
Make1D('M', 'F', 'H','D')
Make1D('C', 'M', '1','6')
MakeID('I', 'L','B','M') 1* Interleaved BitMap *1
MakeID('S', 'H', 'A', 'K') 1* Shakespeare-Chunk,
that contain the
ILBMs *1
MakeID('A', 'N', 'I','M') 1* Animation format *1
MakeID('B', 'M', 'H','D') 1* BitMap Header *1
MakeID('A','N','H','D') 1* Animations Header *1
MakeID('C','M', 'A','P') 1* Color Map *1
MakeID('G', 'R', 'A', 'B') 1* Hot Spot of the
BitMap *1
MakeID('D', 'E','S', 'T') 1* Bitplane
distribution *1
MakeID('S', 'P','R','T') 1* Sprite recognition *1
MakeID('C', 'A', 'M', 'G'l 1* Commodore Amiga
View *1
MakeID('B', 'O','D', 'Y') 1* BitMap Data *1
Make1D('A','T','X','T') 1* are used *1
MakeID ('P', 'T', 'X', 'T') 1*
h time *1
MakeID('D', 'L','T','A') 1* Anim Delta
movement *1
MakeID('C', 'R','N','G') 1* Color Cycling
Chunk *1

Well conclude this part by mentioning a few problems with IFF, and
possible solutions.
1.) Display screen size

Usually the size of the graphic and the size of the screen are found in
the bit-map header, on which the graphic is constructed. The value in w
and h always correspond to the number of pixels in the x and y
directions of the graphic. The values in p age wid t h and
pageHeight comprise the number of pixels of the screen in the x
and y directions. The values from DPaintII are also written in the
structure. This makes sense, because you can save a picture that is
much larger than the screen and display on a 320 x 200 pixel screen
using them.
Many programs that also support the OverScan mode, enter larger
values in the pageWidth and pageHeight than can be selected
because of the OverScan. This causes some problems because
227

s.

STANDARD FILE FORMATS

ADVANCED SYSTEM PROGRAMMER'S GUIDE

although the value is over 320, no HIRES screen has to be opened. To

get around this problem we recommend that you save the ViewMode
and load it when reloading the graphic. This keeps the selected
resolution clearly defined. Make sure your program reads the CAMG
chunk as well.
2.) Forgotten chunks
Many non-Amiga IFF compatible applications simply ignore the
CAMG chunk, although the Amiga may not use the same resolution as
the other progmms. The HAM or HALFWIDTH graphics are saved by
section. The developer assumes that the program recognizes six
bit-planes. No thought was given to the other modes. because the
program should be able to distinguish a HAM graphic from a
HALFWIDTH graphic.
Another problem is that many programs write directly in the Screen
Register when they are saved. This can cause problems when the flags
SPRITES, VP _HIDE, GENLOCK_AUDIO and GENLOCK_VIDEO are
set. You clear these flags when you save the CAMG chunk.
3.) Color cycling
DeluxePaintII writes all of the cycling ranges on the diskette as active
without giving any thought as to if the picture is cycled or not. This
saves the CRNG chunk incorrectly.
That makes it impossible for other programmers to determine whether a
picture should be actively cycled or not, because all of the graphics
created in DeluxePaintII suffer from this problem. The only solution is
through an extra setting with the Slide Show program, either as a
parameter in the CLI or setting a ToolType with the entry

CYCLING=ON.
4.) The number of colors of a CMAP chunk
Other colormap problems occur when using HAM pictures. This
should contain all of the colors needed for the picture. But although six
bit-planes are used, this graphic type only uses 16 colors. There is
some disagreement about this because many programs save 16 colors,
some save 32 and still others save 64, because an IFF rule calculates
the number of colors based on I bitmap depth. and that results in 64.
A CMAP chunk never has the complete number of colors that can be
given through the BMHD chunk. Read the byte statement at the
beginning of the chunk, and never place the number of the color
register after the entry in the CMAP.

228

5.1

ABACUS

5.1.2

IFF

The IFF FTXT text format

This IFF fonnat was developed to allow free file exchange between
word processing systems. Unfortunately this fonnat didn't catch on. For
example, WordPerfect and BeckerText file types are incompatible.
The only program that uses the FTXT fonnat is TextCraft, which was
initially bundled with the Amiga 1000.
The FTXT fonnat has the following fonnat:
FORMUlllI
FTXT
[FONS]lIlIlIlIFontData
CHRSlIlIllllcharacters ... <END>
(11111111 equals file length or chunk length)

The FTXT string indicates that this file is a fonnatted text me (FTX1).
The two chunks supported by the FTXT fonnat are CHRS and FONS.
The FONS chunk consists of a font specifier structure that determines
which font should be used:
offset

Structure
FontSpeci fie r
{

OxOO
1 OxOl
2 Ox02
3 Ox03

4 Ox04

UBYTE id;
/* Font number /* 0 - 9 */
UBYTE padl;
UBYTE proportional; /* Proportional font ? */
/* 0 ~ unknown, 1 ~ yes, 2 ~ no */
UBYTE serif;
1* Serifs ? * /
1* 0 ~ unknown, 1 ~ yes, 2 ~ no */
char name[];
/* Font name (e.g. "topaz/S") */
)

The length of this chunk depends on the number of characters in the

font name. The brackets surrounding the FONS keyword indicate that
this chunk is optional in creating a complete IFF file.
The CHRS chunk consists of the actual text (ASCII codes Ox20 to
Ox7!). The number of characters contained in this chunk follow the
CHRS mark. CHRS and FONS chunks can be swapped in an FTXT file.

229

S. STANDARD Fn..E FORMATS

5.1.3

ADVANCED SYSTEM PROGRAMMER'S GUIDI

The IFF SMUS music format

This format allows the exchange of musical compositions between
music development applications. The system must determine the
notation of each voice, as well as the instrumental quality of each
voice.

An SMUS ftle has the following format:

FORMU"
SMUS

SHDR SSeoreHeader
[NAME] fll/U" "

UUI" .. "
[AUTH] HU" .. "
[IRev] HU????
[(e)

ANNOUfII/" "

INSlllltRevlnstrument
TRAKltl'SEvents . <End>

The chunks

SMUS indicates that this IFF file is an SMUS (Simple MUsic Score)

ftle.
The SHDR chunk contains a ScoreHeader structure:
Offset

Structure
struet SSeoreHeader
(

o
2
3
4

OxOO
Ox02
Ox03
Ox04

UWORD tempo;
UBYTE volume; 1* volume (0-127) *1
UBYTE ctTraek; 1* number of voices *1

The tempo variable of a piece of music is given in increments of a

quarter note note per 128 minutes. If tempo = I, a single quarter note
plays for a 128-minute period.
The NAME chunk contains the name of the piece of music (e.g., "Fugue
in D").

The (c) chunk contains the copyright notice (e.g., "(c) Helmut
Beethoven 1988").
The AUTH chunk contains the name of the author/composer (e.g.,
"Michael Sting").
The I Rev chunk can be used for storing other information pertaining
to the composition (e.g., revision).

230

5.1

ABACUS

IFF

The ANNO chunk contains comments (annotations) about the piece of

music. This chunk must be present, but can consist of 0 bytes.
The INSl chunk contains data about the instrument to be used. The
following structure specifies the instrument data:
Offset

Structure
struct Ref Instrument

1
2
3

OxOO
OxOl
Ox02
Ox03

Ox04

UBYTE register;
UBYTE type;
UBYTE datal,
data2;
char name[];

The register variable contains the number of the instrument. This

allows the selection of a new instrument as a voice is playing.
The type variable lets you specify the instrument name (type = 0)
or the use of a MIDI channel (type = 1). In the latter case, the bytes
datal and data2 designate the MIDI channel and the MIDI preset to
be used. The name array is not used in conjunction with MIDI.
The INSl sets the instrument type, but not the tuning. Instrument 0
represents voice 0, instrument 1 represents voice 1, etc. This order can
be changed later.
The TRAK chunk contains the notes to be played and other infonnation.
Each entry in TRAK is two bytes long. The first byte specifies how the
second byte should be interpreted:
offset

Structure
struct SEvent /* Simple Musical Event */
{

o OxOO
1 OxOl
2 Ox02

UBYTE SID;
UBYTE data;

Here are the values allowed within SID's SEvents:

0-127 (note)

These values specify the pitch of the tone to be played. The data byte
designates the length of the tone:
Bit 7

If this byte is set, the current note and the following note are
played as a chord.

Bit 6

If this bit is set, the current note and the following note are
played without interruption.

231

5.

STANDARD Fn.E FORMATS

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Bits 4 and 5
These bits test for unusual note rhythms:
lictl: :!I:illl.ll:
Triplet
Quintuplet
Septuplet
"Normal" note

Bit 3

j3lcila
01
10
11
00

Dl::;!;illlill

1
2
3

If this bit is set. the current note is played as a dotted note (a

dot makes the note 1.5 times its normal duration).

Bits 0-2
These bits indicate note length:
lic:t s;: lla Jus;:
Whole
Half
Quarter
Eighth
Sixteenth
Thirty-second
Sixty-fourth
12Bth

128 (rest)

BjcaIl!
000
001
010

all

100
101
110
111

j&!;lIIlilJ

a
1
2
3
4

5
6
7

If SID contains the value 128, a rest is played. The duration of the rest
length is specified in the da t a byte.

129 (instrument)
This SEvent changes the instrument for this particular voice. The
data byte contains the number of the instrument
130 (time)

232

This SEvent states the time. The quotient of the top 5 and bottom 3
bits give the time. The top 5 bits are given in beats per second (1-32),
while the bottom 3 bits are given in SID = note. To create 4/4 time,
the value 3 must be given in the top 5 bits and the value 2 (quarter
note) in the bottom 3 bits. A value of 0 in the top 5 bits specifies one
beat per second.

S.l

ABACUS

131 (pitch)

This SEvent establishes the pitch of a note:

~

llim

0
1
2
3
4
5
6
7
8
9

10
11

12
13
14

132 (volume)

IFF

C
G

D
A

E
B

FI
CI
F
Bb
Eb
Ab

Db
Gb

Cb

This SEvent assigns a new volume to this voice. Values can range
from 0 to 127.

133 (MIDI channel)

This SEvent allows you to select a new MIDI channel for subsequent
notes (data =0-255).
134 (MIDI presets)
This SEvent allows you to select new MIDI presets (data = 0-255).

5.1.4

The IFF 8SVX sample format

The 8SVX IFF format is used for the open exchange of digitized sounds
between sampler/sound digitizing applications.
An 8SVX (8-bit Sampled VoX [Voice]) IFF me has the following
fonnat:
FORMUU
8SVX

VHDRIlliVoiee8Header
[NAME]UU" .. "
[Ie) ] UU" .. "
[AUTH]UU" . "
ANNOnU" "
ATAKUUEGPoint
RLSEUUEGPOINT
BODYilliSamples ... <End>

The 8 Svx chunk is the identification string for 8-bit sampled voice
meso

233

5. STANDARD FILE FORMATS

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The VHDR chunk contains a voice8Header structure:

offset

Structure
struct Voice8Header
{

OxOO
4 Ox04
8 OxOO
12 OxOc
14 OxOxe
15 OxOf
16 OxlO
20 Ox14

ULONG oneShotHiSamples,
repeatHiSamples,
samplesPerHiCycle;
UWORD samplesPerSec;
1* Sampling Frequency
UB'lTE ctOctave,
1* number of octaves
sCompression;
1* Data compression?
LONG volume;
1* see EGPoint.dest

*1
*1
*1
*1

The NAME chunk contains the name of the sound (e.g.,

"AAAAHHHHI").
The

(c)

chunk contains the copyright notice (e.g., "(c) Dirty Harry").

The AUTH chunk contains the names of the author (e.g., "Jim
Cottonfield fi").
The ANNO chunk contains comments (annotations) about the sound.
This chunk must be nominally present but can consist of 0 bytes.
The ATAK chunk contains the EGPoint structure which allows you to
control the attack of the sound (start at a certain volume and reach a
certain volume in a certain amount of time). The EGPoint structure
looks like this:
offset

Structure
struct EGPoint
{

o OxOO
2 Ox02
6 Ox06

UWORD duration; 1* in Milliseconds *1

LONG dest;
1(* volume factor *1

The duration variable specifies the time the volume has to reach the
new value. The dest variable specifies the factor by which the volume
should be increased. This latter variable is a fixed-point variable: The
top 16 bits indicate the amount to the left of the decimal point, while
the bottom 16 bits indicate the amount to the right of the decimal
point. A value of OxOOO15000 means a factor of 1.5.
The RLSE chunk contains an EGPoint structure used for controlling
the decay (volume fade).
The BODY chunk contains the sample itself.

234

ABACUS

6.

6. THE AMIGA LIBR.ARIES

The Amiga Libraries

This chapter describes all available library functions. The functions are
arranged according to the libraries, and within the libraries they are
arranged 8CC<X'ding to function groups. The basic layout is as follows:

Library:

Description of the library's purpose.

Functions:

Listing of all of the function divisions in the group, including the

number of the page on which the function is printed.

Description:

Descriptions of the functions according to group.

Structures:

Listing of all of the important structures that are used by the functions
of this library. The name of the include file which contains the
definition follows the structure, enclosed in <>. A hexadecimal and
decimal offset of the start of the structure elements in bytes precedes
each structure element, so that you can find the elements with your
debugger. Rember structures can change, so do not depend on addresses
of system structures.
Each function is described as follows:

Name:

Short descriptioo.

Syntax:

Syntax of the function, the assembly language registers, the offset and
the parameter types.

Description:

Description of the function's exact purpose.

Parameter:

Listing of the parameters needed by the function.

Result:

Description of the value(s) returned by the function (if any).

Explanation:

Description of any other data returned by the function (e.g., errors).

Warning:

You must remembct this information when you call the function. Read
this if you read nothing else in the function description.

Comments:

Additional commentary goes here, if any is needed.

Example:

Demonstratioo program code (if needed).

See Also:

Refers the reader to other functions in this book.

235

6. THE AMIGA LIBRARIES

6.1

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The exec library

The exec library is the only library that we can access without the
OpenLibrary () command. The system has a pointer to your basis
address at memory location OxOOOOOOO4. It is the only consistent
address in the entire Amiga operating system.
When you program in C, you can use all of the commands. The
compiler takes the basis address and correctly calls all of the functions.
In assembly language you simply load the value from the named
address and use this as the basis address.
This library performs all of the elementary system tasks. It supports
other library tasks like data exchange and multitasking, and more. Its
main purpose lies in executing the Amiga's essential survival tasks.

Exec Library Functions

6.1.1

Special functions

InitCode
InitStruct
FindResident
InitResident
Alert

Debug

6.1.2

241
241
241
242

Interrupt functions
Disable
Fnable
Forbid
Permit
SetSR
SuperState
UserState
SetIntVector

AddIntServer
RemIntServer
Cause

236

240
240

242
242
243
243
243
243
244
244
245

245
245

6.1

ABACUS

6.1.3

Memory functions
Allocate
DeaJlocate
AllocMem
AllocAbs
FreeMem
AvailMem
AllocEntry
FreeEntry

6.1.4

F.nJ.ueue
FindName

250
251
251
252
252
252
252
253

Task functions

AddTask
RemTask
FindTask
SetTaskPri
SetSignal
SetExcept
Wait

Signal
AllocSignal
FreeSignal
AllocTrap
FreeTrap

6.1.6

246
246
247
247
248
248
248
249

List management functions

Insert
AdcHead
AddI'ail
Remove
RernHead
RemTail

6.1.5

THE EXEC UBRARY

253
255
255
255
256
256
256
257
257
257
258
258

Message functions
AddPort
RemPort
PutMsg
GetMsg
ReplyMsg
WaitPort

FindPort

258
259
259
260
260
260
261

237

6.

TB AMiGA LIBRARIES

6.1. 7

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Library functions
AddLi1nry
CloseLibrary
MakeFunctions
MakeUbrary
RemUbrary
OldOpenUbrary
OpenLibrary
SetFunction
SumLibrary

6.1.8

261
262
262
263
263
264
264
264

265

Device functions
AddI:levre
RemDevice
0penDevice
CloseDevice
DolO
SeOO.IO
CheckIO
WaitIO
AbortIO

265
266
266
266

267
268
268
269

269

Resource functions

6.1.10

AddResource

269

RernResource
OpenResource

270
270

Semapbore supported functions

IoitSemaphore
ObtainSemaphore

ReleaseSemaphore
AttemptSemaphore
ObtainSemaphoreList
ReleaseSemaphaeList
FindSemaphore
AddSemaph<re
RemSemaphore

6.1.11

272

273
273
273
274

Kickstart and memory functions

SumKickData
AddMemList
CopyMem
CopyMemQuick

238

270
271
271
272

274
274
275
275

6.1

ABACUS

6.1.12

THE EXEC UBRARY

Additional functions

RawDoFmt
GetCC
TypeOtMem

27S
276
276

Before we go on to the functions, let's look at the structure which acts

as this function's base:
struct ExecBase <exec/execbase.h>
{

Oxoo
0x22
Ox24

Ox26
Ox2A
Ox2E
Ox32
Ox36
Ox3A
Ox3E
Ox42
Ox46
Ox4A
Ox4E
Ox52
Ox54
Ox1l4
Ox1l8
Oxllc
Ox120
Ox122
Ox124
Ox126
Ox127
Ox128
Ox12A
Ox12C
Ox130
Ox134
Ox138
Ox13C
Ox140
Ox142
Ox146
Ox15E
Oxl6C
Ox17A
Ox188
Ox196
Ox1A4
OxIB2
Ox202
Ox2l2
Ox213
Ox2l4
Ox222
Ox226

struct Library LibNode;l* Library structure *1

UWORD SoftVer;
1* Version number of Kickstart *1
WORD LowMemChkSum;
1* Checksum for the bottom
range of memory *1
38 ULONG ChkBase:
1* System basis address *1
42 APTR ColdCapture;
1* Cold start vector *1
46 APTR CoolCapture:
50 APTR WarmCapture;
1* Warm start vector *1
54 APTR SysStkUpper;
1* System stack: top limit *1
58 APTR SysStkLower;
1* System stack: bottom limit *1
62 ULONG MaxLocMem;
1* Maximum accessible memory *1
66 APTR DebugEntry:
1* Debugger's starting address *1
70 APTR DebugData;
1* Debugger pointer and data *1
74 APTR AlertData;
/* Alert data pointer */
78 APTR MaxExtMem; 1* Maximum allowable expansion RAM *1
82 UWORD ChkSum;
/* Operating system checksum *1
84 struct IntVector IntVects[16]; /* Interrupt vector
table *1
276 struct Task *ThisTask;/* Pointer to active task *1
280 ULONG IdleCount;
/* Unused counter *1
284 ULONG DispCount;
1* Dispatch counter *1
288 UWORD Quantum;
/* Processor time for each task*1
290 UWORD Elapsed;
/* Elapsed time units */
292 UWORD SysFlags;
294 BYTE IDNestCnt:
295 BYTE TDNestCnt;
296 UWORD AttnFlags;
298 UWORD AttnResched;
300 APTR ResModules;
304 APTR TaskTrapCode;
1* Task pointer *1
308 APTR TaskExceptCode;
312 APTR TaskExitCode;
316 ULONG TaskSigAlloc; 1* Key signal/traps */
320 UWORD TaskTrapAlloc;
322 struct List MemList; 1* System lists *1
336 struct List ResourceList;
350 struct List DeviceList;
364 struct List IntrList;
378 struct List LibList;
392 struct List PortList;
406 struct List TaskReady;
420 struct List TaskWait;
434 struct SoftIntList SoftInts[5];
514 LONG LastAlert[4];
1* Last alert number *1
530 UBYTE VBlankFrequency;
1* Video frequency *1
531 UBYTE PowerSupplyFrequency; 1* Power supply freq. *1
532 struct List SemaphoreList;
546 APTR KickMemPtr;
550 APTR KickTagPtr;

00
34
36

239

6. THE AMIGA LIBRARIES

Ox22A
Ox22C
Ox238
Ox24C

ADVANCED SYSTEM PROGRAMMER'S GUIDE

554 APTR KickCheckSum;

/* Kickstart checksum */
558 UBYTE ExecBaseReserved[10];
568 UBYTE ExecBaseNewReserved[20];
588

};

SYSBASESIZE long)sizeof(struct ExecBase

Processor Bitnumber:
AFB 68010-0L
AFB-68020 1L
AFB-68881 4L
Pro~ssor Flags:
AFF 68010-(lLO}
AFF-68020 (lLl)
AFF=68881 (lL4)
Bytes:
AFB RESERVED8 8L
AFB-RESERVED9 9L

6.1.1

Special functions

bnitCode

Initializes a resident code modulel

Syntax:

InitCode(StartClass, Version);
-72
DO
D1
ULONG StartC1ass;
ULONG Version;

Description:

This function initializes all of the modules with the given features, and
a version number greater than or equal to the one given.

Parameters:

StartClass:
Version:

Flag value with class of code (warmstart, coldstart,

coolstart).
Version number.

InitStruct
Syntax:

Description:

Initializes a table in memor

InitStruct(InitTable, Memory, Size);
-78
A1
A2
DO
ULONG *InitTable;
ULONG *Memory;
ULONG Size;

This function initializes a table at the memory location of a structure

based on the given values.

Parameters:

240

InitTable:
Memory:
Size:

Pointer to the data table.

Pointer to the memory region.
Size of the structure to initialize.

6.1 THE

ABACUS

FindResident

EXEC LIBRARY

Search resident module for its name

Syntax:

Resident = FindResident (Name);

00
-96
Al
ULONG *Resident;
char *Name;

Description:

This function searches through the system list for a resident module
with the given name.

Parameters:

Name:

Result:

Resident

Pointer to the name being searched for.

Address of the found resident module, or null if none

was found.
IInitResident

Initializes a resident module

Syntax:

InitResident(Resident, SegList);
-102
Al
01
ULONG *Resident;
struct List *SegList;

Description:

This function initializes a resident module.

Parameters:

Resident
SegList:

Pointer to the module.

Pointer to a segment list.

struct Resident <exec/resident.h>

{

OxOO
Ox02
Ox06
OxOA
OxOB
OxOC
OxOO
OxOE
Ox12
Ox16
OxlA

00
02
06
10
11
12
13
14
18
22
26

UWORD rt_MatchWord;
struct Resident *rt_MatchTag;
APTR rt_EndSkip;
UBYTE rt_Flags;
UBYTE rt_Version;
UBYTE rt_Type;
BYTE rt _P ri;
char *rt Name;
char *rt=IdString;
APTR rt_Init;

};

RTC MATCHWORD Ox4AFCL

RTF_AUTOINIT (lL7)
RTF _ COLOSTART (ILO)
RTM WHEN 3L

RTW-NEVER OL
RTW COLDSTART 1L

Informs user of an errorl

IAlert
Syntax:

A1ert(AlertNum, Parameters);
-108
07
A5
ULONG A1ertNum;
ULONG *Parameters;

241

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This function displays an error message to the user. For this it

performs all necessary work.

Parameters:

AlertNum:
Parameters:

Number describing the error.

Pointer to the parameters.

Starts system debuggerl

IDebug
Syntax:

Debug();

-114

Description:

This function starts the system debugger. If the address was changed
through SetFunction () , then another debugger can be used.

6.1.2

Interrupt functions

IDisable
Syntax:

Disables system interruptsl

Disable ();

-120

Description:

This function disables interrupts within the system.

Result:

All interrupts are suppressed until either Enable () is called or the

task moves into Wait status.

Comments:

There should be one Enable () call for each call of Di sable ( ) .

See Also:

Enable (),Forbid(),Perrnit()

IEnable
Syntax:

Enables system interruptsl

Enable ();

-126

Description:

This function enables interrupts within the system.

Result:

All interrupts are accessible until Disable () is called.

Comments:

There should be one Disable () call for each call of Enable () .

See Also:

Disable() ,Forbid() ,Perrnit ()

242

6.1 THE EXEC LDRARY

ABACUS

IForbid

Forbids task reschedulingl

Syntax:

Forbid 0 ;
-132

Description:

This function forbids the dispatching program from assigning a certain

amount of execution time to each task until Pe rmi t () is called.

Explanation:

Other tasks also receive execution time if the called tasks are set in the

Wait status.
See Also:

Permit (),Disable(),Enable()

IPermit

Permits task reschedulinsl

Syntax:

Permit 0
-138

Description:

This function negates a Forbid () and allows the dispatcher to give

other programs processor time. Only one call of P e rmi t () may be
used for each call of Forbid () .

See Also:

Forbid(),Disable(),Enable()

ISetSR

Sets/changes processor status registerl

Syntax:

oldSR = SetSR(NewSR, Mask)

DO
-144
DO
Dl
LONG OldSR;
LONG NewSR;
LONG Mask;

Description:

This function allows changes to the value of the CPUs status register.

Parameters:

NewSR:

Mask:

New bit values for status register.

Contains set bits where the value of NewSR should be

transmitted.
The value of the status register before the call.

Result:

OldSR:

Example:

You get the value of SR: actual = SetSR(OL, OL);.

Enables supervisor statusl

ISuperState
Syntax:

OldSysStack = SuperState()
DO
-150

Description:

This function sets the processor to supervisor status.

Result:

OldSysStack: Value restored when user status returns.

243

6.

THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Explanation:

The function does not work when you are already in the supervisor
status. Then the value of OldSysStack is zero.

See Also:

UserS tate ()

luserState

Enables user statusl

Syntax:

UserState(SysStack)
-156
DO

Description:

This function sets the processor to user status.

Parameter:

SysStack:

See Also:

SuperState ()

Value returned from SuperState () .

ISetlntVector

Sets system interrupt vector

Syntax:

Oldlnterrupt = SetlntVector(IntNumber, Interrupt)

DO
-162
DO
A1
struct Node *Oldlnterrupt;
LONG IntNumber;
struct Node *Interrupt;

Description:

This function defines a new interrupt based on the IntNumber

parameter.

Parameters:

IntNumber:
Interrupt:

Interrupt number (fIrSt five bits only).

Pointer to the interrupt node structure, containing the
jump point for the interrupt handler and a pointer to the
data segment

Result:

Oidinterrupt:

Pointer to the old node structure which previously

defined the interrupt.

struct Interrupt <exec/interrupts.h>

{

OxOO
OxOE
Ox12

00
14
18

Ox16

22

struct Node is Node;

APTR is Data; -/* pointer to the data of the server */

VOID (*1s Code) ();

-

/* Program code beginning of the

server */

};

struct IntVector <exec/interrupts.h>

(

OxOO
Ox04
OxOB
OxOC

00
04
08
12

APTR iv Data; /* not tested for the general use*/

VOID (*iv_Code) ();

struct Node *iv_Node;

);

struct SoftlntList <exec/interrupts.h>

{

OxOO

244

00

struct List sh_List; /* Not tested for the general

use*/

6.1 THE EXEC LIBRARY

ABACUS

OxOE
Ox10

14
16

UWORD sh Pad;
-

};

SIH PRIMASK (OxfOL)

INTB_NMI 15L
INTF NMI (lL15)

AddInitServer

Inserts interru t server

Syntax:

AddIntServer (IntNumber, Interrupt)

-168
DO
AI
LONG IntNumber;
struct Node *Interrupt;

Description:

This function adds another interrupt to the interrupt server list. The
priority of the interrupt is tested when it is executed.

Parameters:

IntNwnber:
Interrupt:

See Also:

RemlntServer (), Cause (), SetlntHandler ()

RemIntServer

Interrupt nwnber.
Pointer to the interrupt node structure.

Removes interru t server

Syntax:

RemIntServer (IntNumber, Interrupt)

-174
DO
AI
LONG IntNumber;
struct Node *Interrupt;

Description:

This function removes the given interrupt structure from the interrupt
server list.

Parameters:

IntNwnber:
Interrupt:

See Also:

AddlntServer(),Cause(),SetlntHandler()

Interrupt nwnber.
Pointer to the interrupt node structure.

Icause

Executes a software interrupt!

Syntax:

Cause (Interrupt)
-180
A1
struct Node *Interrupt;

Description:

This function causes a software interrupt to execute.

Parameters:

Interrupt:

See Also:

AddlntServer(),RemIntServer(),SetlntHandler()

Pointer to an initialized interrupt node structure.

245

6. THE AMIGA LIBRAIliES

6.1.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Memory functions
Allocates memory blockl

IAlIocate
Syntax:

MemoryBlock - Allocate(FreeList, ByteSize) ;

DO
-186
AO
DO
ULONG '*HemoryBlock;
struct MemHeader '*FreeList;
ULONG ByteSize;

Description:

This function searches through the FreeList for a memory block of

the desired size, allocates this blocJc and returns a pointer.

Parameters:

FreeList:
ByteSize:

Result:

MemoryBlocJc:

Pointer to a memory list header.

Size of the desired memory block in bytes.
Pointer to the allocated memory block. This parameter

contains zero if an emx- occurs.

See Also:

Deallocate(),
AllocAbs(),
AllocEntry(), AllocRememher()

AllocMem() ,

struct MemHeader <exec/memory.h>

(

Oxoo
OxOE
OxlO

00
14
16

Ox14

20

Ox1S
OxlC

24

Ox20

32

28

struct Node mh Node; 1'* Node to add more MemHeader *1

UWORD mh Attributes; 1* Type of this memory region *1
struct Ml!nChunk "mh First;
1* first element of this
memory list *1
APTR mh_Lower; 1'* top and bottom list of the entire
mBIlIOry region *1
APTR mh_Upper;
ULONG mh_Free; 1* number of all the free bytes of
this memory region "I

);

struct MemChunk <exec/memory.h>

{

OxOO

00

Ox04

04

Ox08

08

struct MetTChunk *me_Next; 1* left to the next memory

chunk *1
ULONG me_Bytes; 1* size of the chunk in bytes *1

};

IDeallocate
Syntax:

246

Releases memory blockl

Deallocate (FreeList, MemoryBlock, ByteSize);
-192
AO
Al
DO
struct MemHeader *FreeList;
ULONG *MemoryBlock;
UUlNG ByteSize;

6.1 THE EXEC LIBRARY

ABACUS

Description:

This function releases the previously allocated memory block and

inserts it in the FreeList again.

Parameters:

FreeList
Pointer to a memory free list.
MemoryBlock:
Pointer to the memory block.
ByteSize:
Size of the memory block.

See Also:

Allocate ()

IAllocMem

Allocates system memoryl

Syntax:

MemoryBlock ~ AllocMem(ByteSize, Requirements);

DO
-198
DO
Dl
ULONG *MemoryBlock;
ULONG ByteSize;
ULONG Requirements;

Description:

This function allocates memory from the system memory list. This
memory must meet the given requirements and have the desired size.

Parameters:

ByteSize:
Size of the requested memory block in bytes.
Requirements: Flags value that specifies memory attributes.

Result:

MemoryBlock:
Pointer to the allocated memory block. This parameter
contains zero if an error occurs.

See Also:

FreeMem(),Allocate(),AllocEntry(),AllocAbs(),
AllocRemember ()

IAlioCAbs

Allocates absolute memoryl

Syntax:

MemoryBlock = AllocAbs(ByteSize, Location);

DO
-204
DO
Al
ULONG *MemoryBlock;
ULONG ByteSize;
ULONG Location;

Description:

This function attempts to allocate a memory range of specific size in a

specific location.

Parameters:

ByteSize:
Location:

Result:

MemoryBlock:

Size of the required memory range in bytes.

Basis address of the memory range.

Pointer to the allocated memory range. This parameter

contains zero if an error occurs.

247

6. THE A MIGA LIBRARIES

See Also:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

FreeMem(),AllocMem(),AllocEntry(),Allocate(),
AllocRemember ()

Frees known memory rangel

IFreeMem
Syntax:

FreeMem(MemoryB1ock, ByteSize);
-210
Al
DO
ULONG *MemoryBlock;
ULONG ByteSize;

Description:

This function releases the memory range allocated at the specific

location. This range can be accessed again.

Parameters:

MemoryBlock:
ByteSize:

See Also:

Pointer to the memory range.

Size of the memory range in bytes.

AllocMem(),FreeEntry(),FreeRemember(),
Deallocate ()

IAvaiIMem

Finds available memory rangel

Syntax:

Size = Avai1Mem(Requirements);
DO
-216
D1
ULONG Size;
ULONG Requirements;

Description:

This function searches the system list for the largest memory range that
has the necessary requirements.

Parameter:

Requirements: Flags value that characterizes the memory range.

Result:

Size:

Memory size in bytes.

Allocates
Syntax:

MemList = A11ocEntry(Entry);
DO
-222
AO
struct MemList *MemList;
struct MemList Entry;

Description:

This function attempts to allocate all memory stated in the memory

list. Then it returns a pointer to a memory list in which all of the
addresses are entered

Parameter:

Entry:

Pointer to a meml i s t structure which lists all

memory ranges' features and size.

Result:

MemList:

List containing all memory range addresses.

248

6.1

ABACUS

See Also:

THE EXEC LIBRARY

FreeEntry(),AllocMem(),AlloCAbs(),Allocate(),
AllocRernember ()
struct MemList <exec/memory.h>
{

OxOO

00

OxOE

14

OxlO
Ox18

16
24

struct Node ml_Node;

/* Node to link more

MemLists */
UWORD ml_NumEntries; /* number of entries in this
Structure */
struct MemEntry ml_HE[l]; /* the first entry */

};

mlmemlHE
Memory_Types:
HEMF PUBLIC (lLO)
HEMF=CHIP (lLl)

/* memory adds more tasks for use * /

/* memory can be addressed from certain
chips */
HEMF FAST (IL2)
/* the memory cannot be addressed through
the certain chips, through which access
is faster * /
HEMF_CLEAR (lL16) /* the memory should be erased at the same
time it is being occupied */
HEMF_LARGEST (lL17) /* the largest memory region with the
given criteria is searched for */
HEM BLOCKSIZE 8L /* Minimum size of a memory region in bytes */
HEM- BLOCKMASK 7L
struct MemEntry <exec/memory.h>
{

union
ULONG meu Reqs; /* Type of the memory * /
APTR meu_Addr; /* Address of the memory region */
}

OxOO
Ox04
Ox08

me Un;
04- ULONG me_Length;
08

/* Length of the memory region */

};

Defmition:

me un me Un
me Reqs me Un. meu Reqs
me-Addr me-Un.meu-Addr

IFreeEntry

Frees multiple memory rangesl

Syntax:

FreeEntry(Entry);
-228
AD
struct MemList *Entry;

Description:

This function restores all of the memory ranges to the list.

Parameter:

Entry:

See Also:

AllocEntry(),FreeMern(),Deallocate(),
FreeRernember ()

Pointer to list containing all memory ranges.

249

6. THE AMIGA LIBRARIES

6.1.4

ADVANCED SYSTEM PROGRAMMER'S GUIDE

List management functions

Inserts node in list!

IInsert
Syntax:

Insert(List, Node, Predecessor);

-234
AD
Al
A2
struct List *List;
struct Node *Node;
struct Node *Predecessor;

Description:

This function inserts a new node in the list. following the specified
node.

Parameters:

List:
Node:
Predecessor:

See Also:

Remove () AddHead () RernHead () AddTail () RemTail ()

Pointer to the head of the list.

Pointer to the node structure to be inserted in the list.
Pointer to the node preceding Node's insertion point.

struct List <exec/1ists.h>

(

OxOO

00

Ox04

04

Ox08

08

OxOC
OxOD
OxOE

12
13
14

1* pointer to head node of the

list *1
struct Node *lh_Tai1; 1* pointer to the last
node of the list *1
struct Node *lh_TaiIPred; 1* pointer to the previous
node of list *1
UBYTE lh Type; 1* Type of this Node *1
UBYTE I_pad; 1* unused full byte *1
struct Node *lh_Head;

);

struct MinList <exec/lists.h>

(

Ox08

1* pointer to your head

node of the list *1
04 struct MinNode *mlh_Tail; 1* pointer to the last
Node of the list *1
08 struct MinNode *mlh_ TailPred; 1* pointer to the

Ox DC

12

OxOO
Ox04

00

struct MinNode *mlh_Head;

previous Node of list *1

);

struct Node <exec/nodes.h>

(

OxOO
Ox04
Ox08
Ox09
OxOA
OxOE
);

250

00
04
08
09
10
14

struct Node *In_Succ; 1* following Node *1

struct Node *In Pred; 1* previous Node *1
UBYTE In Type; -1* Node Type *1
BYTE In_Fri; 1* Node Priority *1
char *In_Name; 1* pointer to a string *1

6.1

ABACUS

THE EXEC UBRARY

struct MinNode <exec/nodes.h>

{

OxOO
Ox04
Ox08

00
04
08

struct MinNode *mln Succ;

struct MinNode *mln-Pred;
-

/* following Node */
/* previous Node */

};

Node_Type:
NT UNKNOWN OL
NT-TASK 1L
NT INTERRUPT 2L
NT-DEVICE 3L
NT- MSGPORT 4L
NT-MESSAGE SL
NT FREEMSG 6L
NT- REPLYMSG 7L
NT RESOURCE 8L
NT-LIBRARY 9L
NT MEK>RY 10L
NT-SOFTINT llL
NT FONT 12L
NT-PROCESS 13L
NT SEMAPHORE 14L
NT-SIGNALSEM 1SL

IAddHead

Inserts new node at head of list!

Syntax:

AddHead(List, Node);
-240
AO
A1
struct List *List;
struct Node *Node;

Description:

This function inserts a new node in the head of the list

Parameters:

List:

Node:

See Also:

Pointer to the list.

Pointer to the node structure that should be inserted.

Insert (),Remove(),RemHead(),AddTail () ,RemTail ()

IAddTail

Inserts new node at end of list!

Syntax:
AddTai1(List, Node);
-246
AO
A1
struct List *List;
struct Node *Node;

Description:

This function inserts a new node at the end of the list

Parameters:

List:

Node:

See Also:

Pointer to the list.

Pointer to the node structure that should be inserted.

Insert () ,Remove(),AddHead(),RemHead() ,RemTail ()

251

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Removes node from list!

IRemove
Syntax:
Remove{Node);
-252
A1
struct Node *Node;

Description:

This function removes a node from a list.

Parameter:

Node:

See Also:

Insert () ,Remove() ,AddHead(),AddTail () ,RemTail ()

Pointer to the node structure that should be removed.

Removes first node from list!

IRemHead
Syntax:

Node = RemHead(List);
DO
-258
AO
struct List *List;

Description:

This function removes the head (fIrSt) node from a list.

Parameter:

List:

See Also:

Insert(),Remove(),AddHead(),AddTail(),RemTail()

Pointer to the list from which the head node should be

removed.

IRemTail

Removes last node from Iistl

Syntax:

Node = RemTail(List);
DO
-264
AO
struct List *List;

Description:

This function removes the tail (last) node from a list.

Parameter:

List:

See Also:

Insert () ,Remove() ,AddHead() ,RemHead() ,AddTail ()

Pointer to the list from which the tail node should be

removed.

En ueue

Inserts node in list based in

Syntax:

Enqueue(List, Node);
-270
AO
Al
struct List *List;
struct Node *Node;

Description:

This function inserts the given node in the list. The priority of the node
determines the position of insertion. The higher the priority. the closer
to the head of the list the node is inserted.

151

6.1

ABACUS

Parameters:

List:
Node:

THE EXEC LIBRARY

Pointer to the list in which the node should be inserted

Pointer to the node to be inserted.

FindName

Searches for node with matchin

Syntax:

Node = FindName(List, Name);

DO
-276
AO
Al
struct Node *Node;
struct List *List;
char *Name;

Description:

This function searches the specified list for a node of the same name. A
pointer to the found node structure is returned.

Parameters:

List:
Name:

Pointer to the list that should be searched through.

Pointer to a string that identifies the node.

Result:

Node:

Pointer to the found node, or zero if an error occurs.

6.1.5

Task functions

IAddTask

Adds task to systeml

Syntax:

AddTask(Task, InitPC, FinalPC);

-282
Al
A2
A3
struct Task *Task;
ULONG InitPC;
ULONG FinalPC;

Description:

This function installs a new task in the system.

Parameters:

Task:

InitPC:
FinalPC:
See Also:

Pointer to an initialized task structure.

Starting address of the task.
Return address of the task, or zero for the system
routine F inalPC.

RemTask(),FindTask()
extern struct Task <exec/tasks.h>
{

OxOO

00

OxOE
OxOF
Oxl0
Oxll
Ox12
Ox16
OxlA

14
15
16
17
18
22
26

struct Node tc_Node; /* Node for the chaining of

multiple tasks */
/* Flags value */
UBYTE tc_Flags;
UBYTE tc_State;
/* Status * /
/* number of connected intr */
BYTE tc_IDNestCnt;
/* number of connected Tasks*/
BYTE tc TDNestCnt;
ULONG tC_SigAlloc;
/* signal provided for task*/
/* Signal that was waited for */
ULONG tc SigWait;
/* Signal that was received */
ULONG tc=SigRecvd;

253

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Ox1E
Ox22
Ox24
Ox26

30
34
36
38

Ox2A

42

Ox2E

46

Ox32

50

Ox36

54

Ox3A

58

Ox3E

62

Ox42

66

Ox46

70

Ox4A

74

Ox58

88

Ox5c

92

Signal that was taken out */

Traps provided for this task*/
Traps that are allowed */
pointer to the data that is
taken out */
APTR tc_ExceptCode; /* Programmcode code that is
taken out */
APTR tc_TrapData;
/* pointer to data for the
traps* /
APTR tc_ TrapCode;
/* pointer to the program code
for the Traps */
APTR tc_SPReg;
/* pointer to the stack of this
task */
APTR tc_SPLower;
/* bottom limit of the stack
memory */
APTR tc_ SPUpper;
/* top limit of the stack memory
+ 2 */
VOID (*tc_Switch) (); /* pointer to the switch routine:
Task is disengaged from the
CPU */
VOID (*tc_Launch) (); /* pointer to the switch routine:
Task is assigned by the CPU */
struct List tC_MemEntry; /* pointer to the memory list
with the memory that is
provided for this task */
APTR tc_UserData;
/* pointer to the data of the
users of this Task */
ULONG tc_SigExcept;
UWORD tc TrapAlloc;
UWORD tC::::TrapAble;
APTR tc_ExceptData;

/*
/*
/*
/*

};

Task_Bytes:
TB PROCTlME OL
TB STACKCHK 4L
TB EXCEPT 5L
TB SWITCH 6L

/* the task has Processor time */

/* the stack is examined */
/*the task is excluded from the processor */
/* the task is disengaged from the
processor * /
/* the task gets processor time again */

TB LAUNCH 7L
Task_Flags:
TF ]ROCTlME (1LO) /* See above */
TF_ STACKCHK (lL4)
TF EXCEPT (lL5)
TF_SWITCH (lL6)
TF_LAUNCH (1L7)
Task State:
TS INVALID OL
/* invalid task */
TS ADDED 1L
/* the task is inserted in the list */
TS RUN 2L
/* the task is running at the moment */
TS-READY 3L
/*the task is ready to run with the processor */
TS WAIT 4L
/* the task waits for a signal */
TS EXCEPT 5L
/* the task is disengaged from the processor */
TS REMOVED 6L
/*the task is removed */
Signal_Byte:
SIGB ABORT OL
SIGB CHILD 1L
SIGB BLIT 4L
SIGB SINGLE 4L
SIGB DOS 8L
Signal_Flag:
SIGF_ABORT (lLO)
SIGF_CHILD (lLl)
SIGF_BLIT (lL4)
SIGF_SINGLE (lL4)
SIGF DOS (1L8)

254

6.1

ABACUS

IRemTask

THE EXEC LIBRARY

Removes task from systeml

Syntax:
RemTask(Task);
-288
Al
struct Task *Task;

Description:

This function removes the given task from the system. All previous
accesses to resources must be returned as well.

Parameter:

Task:

See Also:

AddTask(),FindTask()

Pointer to the task structure, or zero for the separate

task.

IFindTask

Searches task for namel

Syntax:

Task = FindTask(Name);
DO
294
A1
struct Task *Task;
char *Name;

Description:

This function searches the system list for the task of the same name.
The separate task is searched with a null pointer.

Parameter:

Name:

Pointer to the search task's name.

Result:

Task:

Pointer to the found task, or zero if an error occurs.

See Also:

AddTask(),RemTask()

ISetTaskPri

Sets task priorityl

Syntax:

OldPriority = SetTaskPri(Task, Priority);

DO
-300
Al
DO
BYTE OldPriority;
struct Task *Task;
BYTE Priority;

Description:

This function assigns the given task a new priority. The system then
re-calculates the times assigned to each task. The task with the highest
priority is assigned to the processor.

Parameters:

Task:

Result:

Priority:

Pointer to the task.

New priority value of the task.

OldPriority:

Old priority value of the task.

255

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Defines task's signal status!

!SetSignal
Syntax:

OldSignals = SetSignal(NewSignals, SignalSet);

DO

-306

DO

01

ULONG OldSignals;
ULONG NewSignals;
ULONG SignalSet:

Description:

This function assigns a new signal arrangement to the task. This is

calculated from the mask and the new signals. The program gets the old
signal arrangement back.

Parameters:

NewSignal:
SignaiSet:

New signal value.

Masks from which the signals should be changed.

Result:

OldSignal:

Old signal value.

See Also:

AllocSignal(),FreeSignal()

!SetExcept
Syntax:

Sets certain signals as exception triggers!

OldSignals = SetExcept(NewSignals, SignalSet);
DO

-312

DO

01

ULONG OldSignals:
ULONG NewSignals:
ULONG SignalSet:

Description:

This function dermes which signals can generate an exception.

Parameters:

NewSignals:
SignaiSet:

New exception signals.

Mask which specifies the signal bits to be changed.

Result:

OldSignals:

Old exception signals.

!Wait
Syntax:

Waits for signal(S)!

Signals = Wait (SignalSet):
DO

-318

DO

ULONG Signals:
ULONG SignalSet;

Description:

This function waits until one or more signals occur. The task is set in
the Wai t status, thus requiring no processor time.

Parameter:

SignalSet:

Mask containing the desired signal(s).

Result:

Signals:

Value received that the signal contains.

See Also:

Signal ()

256

6.1 THE EXEC UBRARY

ABACUS

ISignal

Signals report to another taskl

Syntax:

Signal(Task, SignalSet);
-324
Al
DO
struct Task *Task;
ULONG SignalSet;

Description:

This function sends a signal to another task. This can be taken from the
wai t status, thus requiring no processor time.

Parameters:

Task:
SignalSet:

See Also:

Wait ()

IAIIocSignal

Task in which the signal should be sent

Mask that contains all of the set bits.

Allocates signal bit

Syntax:

SignalNum = AllocSignal(SignalNum);
DO
-330
DO
LONG SignalNum;
LONG SignalNum;

Description:

This function attempts to allocate a signal of a task. When you know

the number of a free signal, this function can search for a free signal.
The function returns a value of -1 back when no signal is free, or when
the desired signal was not free.

Parameter:

Signa1Num:

Signal number.

Result:

SignalNum:

Number of the allocated signals. SignalNum contains

-1 if no signal was free.

See Also:

FreeSignal ()

Frees signal bit!

IFreeSignal
Syntax:

FreeSignal(SignalNum);
-336
DO
LONG SignalNum;

Description:

This function frees a signal allocated by AllocSignal () .

Parameter:

Signa1Num:

See Also:

AllocSignal ()

Number of the signal to be freed.

257

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Allocates processor trapl

IAllocTrap
Syntax:

TrapNum = AllocTrap(TrapNum);
DO
-342
DO
LONG TrapNum;
LONG TrapNum;

Description:

This function allocates one Of 68000 trap instructions. Values for

TrapNum can range from -1 to +15. If TrapNum = -I, the system
allocates the next free trap.

Parameter:

TrapNum:

Trap number to allocate.

Result:

TrapNum:

Number of the allocated ttap, or -1 if no free ttaps exist

See Also:

FreeTrap ()

Frees processor trapl

IFreeTrap
Syntax:

FreeTrap(TrapNum);
DO
-348
LONG TrapNum;

Description:

This function frees a trap allocated by AllocTrap () .

Parameter:

TrapNum:

See Also:

AllocTrap ( )

6.1.6

Message functions

Trap number to free.

IAddPort

Adds new message port to system I

Syntax:

AddPort (Port);
-354
Al
struct MsgPort *Port;

Description:

This function inserts a new message port in the system list. The name
and the priority of the structure are initialized so the port can sort
correctly, and so all of the other tasks can search for the port in which
the name is used.

Parameter:

Port:

See Also:

RemPort(),FindPort()

258

Pointer to a half-initialized MsgPort structure.

6.1 THE EXEC LIBRARY

ABACUS

struct MsgPort <exec/ports.h>

{

OxOO

00

OxOE

14

OxOF

15

OxlO

16

Ox14

20

Ox22

34

struct Node mp_Node;

/* for connecting a constructed

node */
UBYTE mp_Flags;
/* Flags for the announcement of
the arrival of the reports */
UBYTE mp_SigBit;
/* is the number of the signal
bit that is assigned to this
port */
struct Task *mp_SigTask; /* pointer to the task
that should be signalled */
struct List mp_MsgList; /* head of the list of all of
the reports */

};

mp_Softlnt mp_SigTask
mp_Flags:
PF ACTION 3L
PA-SIGNAL OL
PA SOFTINT lL
PA IGNORE 2L

IRemPort

Removes message port from systeml

Syntax:

RemPort (Port)
-360
A1
struct MsgPort *Port;

Description:

This function removes a port from the system list. This port is no
longer accessible through a pointer, and the FindPort () function no
longer finds this port. After calling this function the memory should be

freed again.
Parameter:

Port:

See Also:

AddPort(),FindPort()

Pointer to a message port

IPutMsg

Puts message in message port!

Syntax:

PutMsg(Port, Message);
-366
AO
A1
struct MsgPort *Port;
struct Message *Message;

Description:

This function places a message in the specified port. A pointer to the

message should be used, instead of memory reallocation.

Parameters:

Port:
Message:

See Also:

GetMsg () ReplyMsg ()

Pointer to the message port.

Pointer to the message structure.

259

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct Message <exec/ports.h>

{

OxOO

00

OxOE

14

OxI2
OxI4

18
20

struct Node mn_Node;

/* Node to tie together multiple

Messages */
struct MsgPort *mn ReplyPort; /* pointer to the port
in which the report
is sent when the
answer follows */
UWORD mn_Length; /* Byte number of the report */

};

IGetMsg

Gets message from message port!

Syntax:

Message = GetMsg(Port)
DO
-372
AD
struct Message *Message;
struct MsgPort *Port;

Description:

This function gets the fIrst available message from the message port
list. If no message currently exists in the port, the function returns a
value of zero.

Parameter:

Port:

Pointer to the message port.

Result:

Message:

Pointer to the fIrst message of the message port. A zero

is returned if no message exists there.

See Also:

PutMsg(),ReplyMsg(),WaitPort()

IReplyMsg

Puts message in reply port!

Syntax:

RepIyMsg(Message);
-378
Al
struct Message *Message;

Description:

This function places a received message in the message's reply port,

indicating that the receiver of the message has processed it. The task
sent by the report can then free the memory.

Parameter:

Message:

See Also:

PutMsg(),GetMsg(),WaitPort()

WaitPort

Pointer to the message structure.

Waits

Syntax:

Message = WaitPort(Port);
DO
-384
AO
struct Message *Message;
struct Port *Port;

Description:

This function waits until a report appears in the given port. If a

message exists, the function returns the pointer to this message.

260

6.1 THE EXEC LIBRARY

ABACUS

Parameter:

Port:

Pointer to the message port.

Result:

Message:

Pointer to the message structure received.

See Also:

GetMsg () , PutMsg () ,ReplyMsg ()

IFindPort

Searches for message port!

Syntax:

Port = FindPort(Name)
DO
-390
A1
struct MsgPort *Port;
char *Name;

Description:

This function searches the system list for the port of the same name. If
the name is found, a pointer is returned. A zero is returned if the name
is not found.

Parameter:

Name:

Pointer to the name of the port to search.

Result:

Port:

Pointer to the port, or zero.

6.1.7

Library functions

IAddLibrary

Adds library to systeml

Syntax:

AddLibrary(Library);
-396
A1
struct Library *Library;

Description:

This function inserts a new library in the system list. The library can
then be accessed by any task. The function calculates the checksum of
the library entries.

Parameter:

Library:

See Also:

MakeLibrary(),RemLibrary(),OpenLibrary(),
CloseLibrary ()

Pointer to a previously initialized library structure.

extern struct Library <exec/libraries.h>

{

OxOO

00

struct Node lib_Node;

OxOE
Ox OF
Ox10

14
15
16

UBYTE lib_Flags;
UBYTE libyad;
UWORD lib_NegSize;

Ox12

18

UWORD lib_PosSize;

Ox14

20

UWORD lib_Version;

/* node to tie the library into

the system */
/* Flags s.u. */
/* unused fill byte */
/* size of the vector table in
bytes */
/* size of the data (also in
bytes) */
/* Version number of library */

261

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Oxl6
Oxl8

22
24

OxlC
Ox20

28
32

Ox22

34

UWORD lib Revision; 1* revision number *1

APTR lib_IdString; 1* pointer to an identification
text */
1* checksumof the library *1
ULONG lib Sum;
UWORD lib:=OpenCnt; 1* counter that counts how often
this Library was accessed *1

};

Lib_Flags:
LIBF SUMMING (lLO)
LIBF CHANGED (lLl)
LIBF SUMUSED (lL2)
LIBF DELEXP (lL3)

1* the checksum was calculated from a used

task *1
/* one or more of the functions of the
library were changed *1
1* one checksum should release reset *1
1* the library should be closed, but
another task is still using it: Wait
status *1

Definition:
lh Node lib Node
Ih:=Flags lib_Flagslh~d lib-pad
Ih_NegSize lib_NegSize
lh PosSize lib PosSize
lh Version lib Version
lh-Revision lib Revision
lh:=IdString lib:=IdString
lh Sum lib Sum
Ih-OpenCnt-lib OpenCnt
LIB VECTSIZE 61:
LIB RESERVED 4L
LIB BASE (-LIB VECTSIZE)
LIB:=USERDEF (LIB_BASE-(LIB_RESERVED*LIB_VECTSIZE)}
LIB NONSTD (LIB USERDEF)
lib-Vectors:
LIB OPEN (-6L)
LIB:=CLOSE (-12L)
LIB EXPUNGE (-l8L)
LIB-EXTFUNC (-24L)

ICloseLibrary

Closes libraryl

Syntax:

CloseLibrary (Library);
-414
A1
struct Library *Library;

Description:

This function closes a library to access from a task.

Parameter:

Library:

See Also:

OpenLibrary ()

IMakeFunctions
Syntax:

262

Pointer to the library node.

Makes function tablel

TableSize = MakeFunctions(Target, FunctionArray, FuncDispBase);
DO
-90
AO
Al
A2
ULONG TableSize;
ULONG Target;
ULONG *FunctionArray;
ULONG FuncDispBase;

ABACUS

6.1 THE EXEC LIBRARY

Description:

This function creates a function jump table from a table containing

function addresses. Libraries, devices and resources require this table,
usually calculated using absolute jumps. Relative tables can also be
created, using FuncDispBase.

Parameters:

Target
Function jump table address.
FunctionArray:
Pointer to table containing the addresses.
FuncDispBase:
Pointer to basis address to which all of the addresses
should be relatively calculated, or zero.

Result:

TableSize:

Table size in bytes.

IMakeLibrary
Syntax:

Creates library

Library = MakeLibrary(Funclnit, Structlnit, Liblnit,

DO

-84

AO

Al

A2

DataSize, CodeSize);
DO
Dl
ULONG
ULONG
ULONG
ULONG
ULONG
ULONG

*Library;
*Funclnit;
*Structlnit;
*Liblnit;
DataSize;
*CodeSize;

Description:

This function makes an entire library. For this the vector table and a
data list are combined. In addition, the routine allocates enough
memory, and starts an existing initialization routine.

Parameters:

Funclnt:
StructInt:
LibInt:
DataSize:
CodeSize:

Pointer to a table containing all of the table jumps.

Pointer to an InitStruct data list
Address of initialization routine.
Size of this library's data range.
Pointer to a segment list.

Result:

Library:

Pointer to a library.

See Also:

Ini tStruct ()

IRemLibrary

Removes Iibraryl

Syntax:

Error = RemLibrary (Library) i

DO
-402
Al
LONG Error;
struct Library *Library;

Description:

This routine removes a library from the system list. Once removed,
this library can no longer be opened through OpenLibrary () .

263

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Parameter:

Library:

Pointer to a library node.

Result:

Error:

Zero if no error occurs.

See Also:

AddLibrary(),MakeLibrary()

IOldOpen Library
Syntax:

absolute OpenLibraryl

Library = OldOpenLibrary(LibName);
DO

-408

Al

struct Library *Library;

char *LibNarne;

Description:

This function is the old version of the OpenLibrary () function.

The version number of the library that should be opened is not checked.
This function is implemented only so older versions of source texts can
be complied and executed without changes.

Parameter:

LibName:

Pointer to name of the library.

Result:

Library:

Pointer to opened library; returns zero if an error occurs.

See Also:

OpenLibrary () ,CloseLibrary ()

IOpenLibrary
Syntax:

Opens Iibraryl
Library = OpenLibrary (LibNarne, Version);
DO

-552

A1

DO

struct Library *Library;

char *LibNarne;
LONG Version;

Description:

This function opens a library and its functions for access.

Parameters:

LibName:
Version:

Name of the library to open.

Version number of the library to be opened.

Result:

Library:

Pointer to the opened library; returns zero if an error

occurs.

See AlSO:

OldOpenLibrary(),CloseLibrary()

SetFunction
Syntax:

Sets Iibrar

OldFunct = SetFunction(Library, Offset, FunctEntry);

DO

-420

LONG OldFunct;
struct Library *Library;
LONG Offset;
ULONG FunctEntry;

264

function vector

Al

AD

DO

6.1

ABACUS

THE EXEC LIBRARY

Description:

This routine changes a function of the library by replacing the old

address with the new in the offset

Parameters:

Library:

Result:

Offset:
FunctEntry:

Pointer to the library in which a function should be

changed.
Offset of the function to be changed.
Pointer to the new function.

OldFunct:

Pointer to the old function in the offset.

ISumLibrary

Computes/views library checksuml

Syntax:

SumLibrary(Library);
-426
Al
struct Library *Library;

Description:

This function calculates the checksum of the library. This can verify
whether the library has been illegally tampered with.

Parameter:

Library:

Explanation:

When an error occurs, the user receives an Alert.

6.1.8

Device functions

Pointer to the library.

IAddDevice

Adds device to system

Syntax:

AddDevice(Device);
-432
Al
struct Device *Device;

Description:

This function adds a new device to the system. Any program can use
this device.

Parameter:

Device:

See Also:

RemDevice(),OpenDevice(),CloseDevice()

Pointer to an initialized device node.

struct Device <exec/devices.h>

{

OxOO

00

struct Library dd_Library;

1* Device Structure

Library Structure *1
Ox22

34

};

265

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Removes device from system I

IRemDevice
Syntax:

Error = RemDevice(Device);
DO
-438
Al
LONG Error;
struct Device *Device;

Description:

This function removes a device from the system. The device cannot be
accessed or opened by name.

Parameter:

Device:

Pointer to an existing device node.

Result:

Error:

Returns zero if no error occurs during execution.

See Also:

AddDevice(),OpenDevice(),CloseDevice()

IOpenDevice

Opens devicel

Syntax:

Error = OpenDevice(DevName, Unit, IORequest, Flags);

DO
-444
AO
DO
Al
Dl
LONG Error;
char *DevName;
ULONG Unit;
struct IORequest *IORequest;
ULONG Flags;

Description:

This function opens the specified device and initializes the given I/O
request block.

Parameters:

DevName:
Unit:
IORequest
Flags:

Pointer to the device name.

Device dependent unit number.
1/0 request block to be filled with data.
Mode setting flags (not always used).

Result:

Error:

Returns zero if no error occurs during execution.

See Also:

AddDevice () , RemDevice () ,CloseDevice ()

IcloseDevice

Closes devicel

Syntax:

CloseDevice (IORequest) ;
-450
Al
struct IORequest *IORequest;

Description:

This function closes an open device. Access ends and the IORequest
structure is freed for further use.

Parameter:

IORequest

See Also:

AddDevice(),RemDevice(),OpenDevice()

266

Pointer to an IORequest structure.

6.1

ABACUS

IDolo

THE EXEC UBRARY

Executes I/O commandl

Syntax:

Error = DoIO(IORequest);
DO
-456
AI
LONG Error;
struct IORequest *IORequest;

Description:

This function assigns a device that executes the given command in the
IORequest structure. The command accesses the task as long as
necessary.

Parameter:

IORequest

Pointer to an initialized IORequest structure.

Resule

Error:

Returns zero if no error occurs.

See Also:

SendIO(),WaitIO()
struct IORequest <exec/io.h>
(

Oxoo
OxOE

00
14

Ox12

18

Ox16
Ox18
Ox19

22
24
25

Ox1A

26

struct Message io Message;/* Message Structure */

struct Device *io_Device; /* pointer to the device to
be addressed */
struct Unit *io_Unit; /* pointer to the Unit
(which has a different
meaning with each device) */
UWORD io_Command;
/* Device command */
UBYTE io_Flags;
/* Device dependent flags */
BYTE iO_Error;
/* Device dependent error
message */

};

Unit_Flags:
UNITF ACTIVE (lLO)
UNITF INTASK (lLl)
struct Unit <exec/devices.h>

/* Unit is addressable */
/* Unit is working */

OxOO

00

struct MsgPort *unit_MsgPort;

Ox04
Ox05
Ox06

04
05
06

UBYTE unit_flags;
UBYTE unit~d;
UWORD unit_OpenCnt;

Ox08 08
l;
I/O-Errors:
IOERR OPENFAIL -lL
1*
IOERR-ABORTED -2L
/*
IOERR NOCMD -3L
1*
IOERR BADLENGTH -4L
/*
struct IOStdReq <exec/io.h>

/* pointer to the
message port of the
Unit */

/* number of the inquiry

opened *1

has not failed *1

was aborted *1
no existing command *1
falsche Lange *1

/* Message Structure */

OxOO
OxOE

00
14

struct Message io Message;

struct Device *io=Device;

Ox12

18

struct Unit *io_Unit; 1* pointer to the Unit (which

has a different meaning for
each device) *1

1* pointer to the device

to be addressed *1

267

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMERtS GUIDE

Ox16
Ox18
Ox19

22
24
25

UWORD io_Command;
UBYTE io_Flags;
BYTE io_Error;

OxlA

26

ULONG iO_Actual;

OxlE
Ox22
Ox26

30
34
38

ULONG iO_Length;
APTR io Data;
ULONG ie_Offset;

Ox2A

42

/* Device command */
/* Device dependent flags */
/* Device dependent error
IT'essage */
/* number of the data bytes sent
up to now */
/* number of bytes to transfer */
/* pointer to the data buffer */
/* Variable for the block
structured devices */

};

io COllllland:
DEV BEGINIO (-30Ll
DEV ABORTIO (-36Ll
io_Fags:
lOB_QUICK OL
IOF_QUICK (lLO)
io Command:
CMD INVALID OL
CMD RESET lL
CMD READ 2L
CMD-WRITE 3L
CMD UPDATE 4L
CMD CLEAR 5L
CMD STOP 6L
CMD START 7L
CMD FLUSH 8L
CMD-NONSTD 9L

ISendIO

Sends I/O commandl

Syntax:

SendIO(IORequest);
-462
Al
struct IORequest *IORequest;

Description:

This function assigns a device to execute the command given in the

lORequest structure. It returns to program execution, instead of
waiting for the I/O command to execute.

Parameter:

IORequest

See Also:

DolO (), WaitIO ()

Pointer to the initialized IORequest structure.

ICbecklO

Returns 10Request statusl

Syntax:

Result = CheckIO(IORequestl;
DO
-468
Al
struct IORequest *Result
struct IORequest *IORequest;

Description:

This function determines whether an I/O process begun earlier has

fmished processing. It either returns the pointer to the request structure,
or zero if the request is still executing.

Parameter:

10Request

268

Pointer to the initialized lORequest structure.

6.1 THE EXEC LIBRARY

ABACUS

Result:

Result:

IWaitlO

Returns zero if the I/O request is still executing; returns

a pointer to the I/O request block in any other case.
Waits until I/O request finishes processingl

Syntax:

Error = WaitIO(IORequest);
DO
-474
Al
LONG Error;
struct IORequest *IORequest;

Description:

This function waits until the I/O request is processed.

Parameter:

IORequest:

Pointer to the initialized IORequest structure.

Result:

Error:

Returns zero if no errors occur during execution.

Warning:

If the 1/0 request is not answered. the function never returnsl

See Also:

SendIO () .0010 ()

IAbortlO

Aborts running 110 processl

Syntax:

Error = AbortIO(IORequest)
DO
-480
A1
LONG Error;
struct IORequest *IORequest;

Description:

This function aborts the specified 110 request. If termination is not

successful. the function returns an error message.

Parameter:

IORequest:

Pointer to the initialized IORequest structure.

Result:

Error:

Returns zero if no errors occur during execution.

See Also:

SendIO () Wai tIO () 0010 ()

6.1.9

Resource functions

IAddResource

Inserts resource in systeml

Syntax:

AddResource (Resource);
-486
Al
struct Node *Resource;

Description:

This function inserts a new resource in the system list. Then it can be
accessed by all of the other tasks. The resource should already be
addressable before addition to the list.

269

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Parameter:

Resource:

See Also:

RemResource () , OpenResource ()

Pointer to an initialized resource node structure.

RemResource
Syntax:

Removes
RemResource (Resource);
-492

Al

struct Node *Resource;

Description:

This function removes a resource from the system list.

Parameter:

Resource:

See Also:

AddResource () , OpenResource ()

Pointer to the resource node.

IOpenResource
Syntax:

Opens resource to accessl

Resource = OpenResource (Resname, Version);
DO

-498

Al

DO

struct Node *Resource

char *ResName;
ULONG Version;

Description:

This function opens a resource to access. The call returns the pointer to
the desired resource. The function fast searches to see if a resource with
the given name is present. Then the version number of the found
resource is compared to the Version parameter. If the present resource
has an older version number, the resource is not opened.

Parameters:

ResName:
Version:

Pointer to the desired resource name.

Version number.

Result:

Resource:

6.1.10

Semaphore supported functions

hore

Returns zero if no error occurs during execution, or a

pointer to the resource if an error occurs.

Initializes

Syntax:

InitSemaphore (Signal Semaphore) ;

-558
AO
struct Signal Semaphore *SignalSemaphore;

Description:

This function initializes a SignalSemaphore structure. It initializes

pointers and the semaphore counter.

270

6.1

ABACUS

THE EXEC LIBRARY

Parameter:

SignalSemaphore:

See Also:

ObtainSemaphore() ,ReleaseSemaphore (),Procure()

Pointer to the Signal Semaphore structure.

struct SignalSemaphore <exec!semaphores.h>

{

OxOO
OxOe
OxlO
OxIC
Ox28
Ox2C
Ox2E

00
14
16
28
40
44
46

struct Node 55_Link;

SHORT sS_NestCount;
struct MinList 55 WaitQueue;
struct SemaphoreRequest ss_MultipleLink;
struct Task *ss_Owner;
SHORT ss_QueueCount;

);

struct Semaphore <exec!semaphores.h>

{

OxOO
Ox22
Ox24

00
34
36

struct MsgPort sm_MsgPort;

WORD sm_Bids;

};

struct SemaphoreRequest <exec!semaphores.h>

{

OxOO
Ox08
OxOC

00
08
12

struct MinNode sr Link;

struct Task *sr_Waiter;

);

IObtainSemaphore

Allows semaphore accessl

Syntax:

ObtainSemaphore(SignalSemaphore);
-564
AO
struct SignalSemaphore *SignalSemaphore;

Description:

This function allows access to a MsgPort. If another task is currently

accessing the same MsgPort, this function waits until the "lock" is
released.

Parameter:

Signal Semaphore:
Pointer to the initialized SignalSemaphore
structure.

See Also:

ObtainSemaphoreList(),InitSemaphore(),
ReleaseSemaphore(),TransferSemaphore(),
AttemptSemaphore(),Procure()

ReleaseSema hore

Releases si

Syntax:

ReleaseSemaphore(SignalSemaphore);
-570
AO
struct SignalSemaphore *SignalSemaphore;

Description:

This function releases the access to a Ms gPo r t locked by

ObtainSemaphore () . All waiting tasks can now access the
unlocked MsgPort.

271

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

Parameter.

SignalSemaphore:
Pointer to the initialized SignalSemaphore
structure.

Warning:

Never try to free an already free Signal Semaphore!

See Also:

ObtainSemaphore(),ObtainSemaphoreList(),
Procure ()

Semaphore access (no task wait)l

lAttemptSemaphore
Syntax:

Success = AttemptSemaphore(SignalSemaphore);
DO
-576
AD
BOLL Success;
struct SignalSemaphore *SignalSemaphore;

Description:

This function allows access to a Ms gPo r t (similar to

ObtainSemaphore ( ) ), except the task is not placed in wai t status
if the port is locked to another task. If another task is currently
accessing the same MsgPort, this function ends and returns control to
the task.

Parameter:

SignalSemaphore:
Pointer to an initialized SignalSemaphore

structure.
Returns TRUE if the semaphore can be accessed, and
FALSE if another task has locked it

Result:

Success:

See Also:

ObtainSemaphore(),ObtainSemaphoreList(),
ReleaseSemaphore(),Procure()

IObtainSemaphoreList

Allows semaphore list accessl

Syntax:

ObtainSemaphoreList(List);
-582
AD
struct Signal Semaphore List;

Description:

This function allows access to a Ms gPo r t (similar to

ObtainSemaphore (), except that a list can be linked from
multiple SignalSemaphore structures with the value ss_Link.

Parameter:

List:

See Also:

ObtainSemaphore(),ReleaseSemaphore(),
ReleaseSemaphoreList(),Procure()

272

Linked list from the Signal Semaphore structure.

6.1 THE EXEC LIBRARY

ABACUS

ReleaseSema horeList
Syntax:

Releases sema hore list aeees

ReleaseSemaphoreList(List);
-588

AO

struct Signal Semaphore List;

Description:

This function releases access to a Ms gPo r t (similar to

ObtainSemaphore () ), freeing both the Signal Semaphore and
the entire linked list

Parameter:

List:

See Also:

ObtainSempaho re () , Obt ainSemapho reLi s t ( ) ,

ReleaseSemaphore()

Linked list from the Signal Semaphore structure.

IFindSemaphore
Syntax:

Finds SilnalSemaphore!
SignalSemaphore = FindSemaphore (Name);
DO

-594

AO

struct SignalSemaphore *SignalSemaphore;

char *Name;

Description:

This function searches the SignalSemaphore list and returns a

pointer to the flISt semaphore whose name corresponds with the given
name. Remember to assign a name to each semaphore.

Parameter:

Name:

Result:

SignalSemaphore:
Pointer to the Signal Semaphore if found, or zero if
the signal semaphore could not be found.

Pointer to the name of the Signal Semaphore to be

found.

!AddSemaphore
Syntax:

Adds signalsemaphore!
AddSemaphore (SignalSemaphore);
-600

AD

struct SignalSemaphore *SignalSemaphore;

Description:

This function inserts a new semaphore in the system list. The name
and the priority should be initialized to ensw-e proper processing.

Parameter:

Signal Semaphore:
Pointer to an initialized SignalSemaphore
structure.

See Also:

RemSemaphore(),InitSemaphore(),FindSemaphore()

273

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Removes signalsemaphorel

IRemSemaphore
Syntax:

RemSemaphore(SignalSemaphore);
-606
AO
struct SignalSemaphore *SignalSemaphore;

Description:

This function removes a semaphore that was inserted in the system list
by AddSemaphore () .

Parameter:

SignalSemaphore:
Pointer to existing semaphore in the system list.

See Also:

AddSemaphore ( ) FindSemaphore ( )

6.1.11

Kickstart and memory functions

ISumKickData

Calculates Kickstart delta list checksum(

Syntax:

SumKickData ()
-612

Description:

This function calculates the checksum of the KickMemPrt structure

and the K i c k Tag P r t array. This value is stored in the
KickCheckSum array of the ExecBase structure.

See Also:

InitResident (). FindResident ()

IAddMemList

Adds free memoryl

Syntax:

Error = AddMemList(Size, Attributes, Pri, Base, Name);

DO
-618
DO
Dl
D2
AO
Al
LONG Error;
ULONG Size;
UWORD Attributes;
BYTE Pri;
ULONG Base;
char *Name;

Description:

This function defines a new memory range that is added to the list of
free memory.

Parameters:

Size:
Attributes:
Pri:

Base:
Name:

274

Size of new memory region in bytes.

Memory attributes.
Priority of memory (-10 = Chip. 0 = Fast).
Basis address of memory.
Name entered in the memory header.

6.1

ABACUS

Error number.

Result:
See Also:

THE EXEC LIBRARY

Allocate(),AllocMem(),AllocEntry(),
AllocRemember ( )

lcOpyMem

Copies memoryl

Syntax:

CopyMem(Source, Dest, Size);

-624
AO
Al
DO
ULONG Source, Dest;
ULONG Size;

Description:

This function copies the given memory range to a new position by the
fastest means.

Parameters:

Source:
Dest:

Size:
See Also:

Basis address of the source range.

Basis address of the destination range.
Size of the memory region to copy in bytes.

CopyMemQuick ()

ICopyMemQuick

Copies memory quiCklyl

Syntax:

CopyMemQuick(Source, Dest, Size);

-630
AO
Al
DO
ULONG Source, Dest;
ULONG Size;

Description:

This routine is the improved version of the CopyMem () function. It

copies faster. The basis addresses and memory size must be given in
LONG format, which means only four divisible addresses may be
accessed at a time.

Parameters:

Source:
Dest:

Size:

Basis address of the source range.

Basis address of the destination range.
Size of the memory region to copy in bytes.

Warning:

System interrupt will occur if you do not follow address conventions.

See Also:

CopyMem()

275

6. THE AMIGA LIBRARIES

6.1.12

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Additional Functions
Formats character string datal

IRawDoFmt
Syntax:

RawDoFmt(FormatString, DataStream, PutChProc, PutChData);

-552
AO
Al
A2
A3
ULONG *FormatString;
ULONG *DataStream;
ULONG PutChProc;
ULONG PutChData;

Description:

This function displays a string. Numeric values are converted as usual

in C. The function needs a pointer to the string, a pointer to the data,
the address of a routine that displays each character and the register to
which the character code should be transferred.

Parameters:

FormatString:
DataStream:
PutChProc:
PutChData:

Pointer to a string containing format elements.

Pointer to the data to be replaced.
Address of the character display routine.
Address register to which the data should be given.

IGetCC

Condition codes for compatible processor I

Syntax:

Conditions = GetCC();
DO
-528
ULONG Conditions;

Description:

This function supplies the condition codes to allow compatibility with

a 68010 processor.

Result:

Condition codes

ITypeOfMem

Returns memory attributesl

Syntax:

Attributes = TypeOfMem(Address);
DO
-534
Al
ULONG Attributes;
ULONG Address;

Description:

This function returns the attributes of the specified memory range.

Parameter:

Address:

Address of memory range.

Result:

Attributes:

Attributes and type of memory range.

6.2 THE DOS LIBRARY

ABACUS

6.2

The DOS library

The DOS library provides the flI'St line of communication with the disk
drives or the hard disk. Some DOS functions can be found in the C
standard library. C limits the number of files that may be open at the
same time, while the DOS library allows as many files open at the
same time as memory permits.
If you intend to use your program in conjunction with other programs
later, use the C standard functions to make transportation of the
program easier. The DOS library also contains functions that allow
creation of a new process (loading and starting new programs from
disk), pausing a program for a specified time and protecting files from
accidental deletion.

This list includes the DOSBase structure, in which you'll see different
devices. Through that you can determine which drives are connected to
the Amiga, because a drive is also a device (DFO:, DFl:, ...).

DOS library functions

6.2.1

6.2.2

Input and output

Close
Open
ReOO

278
279
279

Seek
Write

280
281

File management
CreateDir
CurrentDir
DeleteFile
Examine
ExNext
Info
ParentDir
Rename
SetComment
SetProtection

282
282
283
283
283
284

285
285
285
286

277

6. THE AMIGA LIBRARIES

6.2.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

File management utility functions

22,7
22,8
22,8
22,9
22,9

DupLock
Input
IoErr
IsInteroctive
Lock
Output
UnLock

6.2.4

290

290

Process management

291
292

CreateProc
DateStamp
Delay
DeviceProc
Exit
WaitForChar

6.2.5

292

293
293
293

Loading programs

295
295
296

Execute
LoadSeg
UnLoadSeg

6.2.6

Internal DOS commands

GetPacket
QueuePacket

6.2.1

296

297

Input and output

!close

Closes filel

Syntax:

Close (File)
-36
01
struct FileHandle *File;

Description:

This function closes a file opened by Open.

Parameter:

File:

Comments:

You must close any open files before ending a program. Unclosed files
stay open until the next reset

278

File specifier.

6.2 THE DOS LIBRARY

ABACUS

Warning:

Do not confuse the DOS C los e function with the C functions

close () or fclose () The three functions use three different fIle
specifiers.

See Also:

Open

lopen
Syntax:

Opens filel
File = Open(Name,Mode)
00
-30
01
02
struct FileHandle *File;
UBYTE *Name;
LONG Mode;

Description:

This function opens a file for reading or writing. If the Mode is

an existing fIle opens. MODE_NEWFILE creates a
new file and deletes an existing file of the same name.
MODE_ READWRI TE opens an existing fIle but allows exclusive access
to this fIle. Exclusive access means that when you open a fIle with
MODE_READWRITE, no other task can open this file. The Mode
parameter has no meaning if you read the fIle.
MODE_OLDFILE,

Parameters:

Name:

Mode:

Pointer to the filename.

Tests for mode (MODE_OLDFILE for opening existing
file. MODE_READWRITE for exclusive mode or
MODE_NEWFILE for creating a new fIle).

Result:

File:

Exception:

The function returns a zero if the fIle cannot be opened. I oE r r returns

the exact error message.

Warning:

Do not confuse the DOS Open function with the C functions open ()
or fopen () . The three functions use three different file specifiers.

Comments:

Use Lock () if you only want to see if a file exists.

See Also:

Close, IoErr

File specifier.

IRead

Reads file datal

Syntax:

Number = Read(File,Buffer,Length)
00
-42
01
02
03
LONG Number;
struct FileHandle *File;
UBYTE *Buffer;
LONG Length;

Description:

This function reads data from a ftIe into a buffer.

279

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Parameters:

File:
Length:

File specifier.
Pointer to the data buffer.
Number of bytes to be read.

Result:

Number:

Number of bytes actually read

Exceptions:

If n urnbe r =zero,this indicates the end of the file. If n urnbe r < 0, an

error occurred. IoErr returns the exact error message.

Comments:

The value that IoErr returns is changed every time by Read. When
no error is encountered, IoErr indicates whether data can still be
inserted in the file.

See Also:

Open,Close,Write

Buffer.

ISeek
Syntax:

Sets file pointer I

oldPosition
DO

Seek(File,Position,Mode)
-66

Dl

D2

D3

LONG oldPosition;
struct FileHandle *File;
LONG Position, Mode;

Description:

This function sets the file pointer at posi tion. The file pointer can
be set based on three mode options:
OFFSET BEGINNING
Sets the file pointer to po sit ion bytes after the
beginning of the file. po sit i on must be a positive
value.
OFFSET END
Sets the file pointer to posi tion bytes before the end
of the file. position must be a negative value.
OFFSET CURRENT
Sets the file pointer to po sit ion bytes from the
current file position. posi tion can be a positive or
negative value.

Parameters:

File:
Position:

Mode:

File specifier.
The number of bytes the file pointer should be moved.
Movement mode.

Result:

oldPosition:

Exceptions:

If oldPosition
error message.

Comments:

Calling Seek returns the position of the current fIle pointer:

280

Old file pointer position relative to the beginning of the

file.

= -1, an error occurred.

IoErr returns the exact

6.2

ABACUS

THE

DOS

LIBRARY

pos = Seek(file,OL,OFFSET_CURRENT);

You can easily set the file pointer to the beginning or the end of the
file by calling Seek with position equal to zero and calling
Ot'FSET BEGINNING and OFFSET END as mode.

Writes data to filel

IWrite
Syntax:

Number = Write (File, Buffer, Length)

DO
-48
D1
D2
D3
LONG Number;
struct FileHandle *File;
UBYTE *Buffer;
LONG Length;

Description:

This function writes data from a buffer into a file.

Parameters:

File:
Buffer:
Length:

File specifier.
Pointer to the data buffer.
Number of bytes that should be written.

Result:

Number:

Number of bytes actually written.

Exceptions:

If number is negative, an error occurred. IoErr returns the exact error

message.

See Also:

Open, Close, Read

Structures:

MODE READWRITE
MODE OLDFILE
MODE NEWFILE
OFFSET BEGINNING
OFFSET CURRENT
OFFSET END

1004
1005
1006
-1
0
1

struct FileHandle <libraries/dosextens.h>

{

OxOO
Ox04
Ox08
OxOC
Ox10
Ox14
Ox18
Oxlc
Ox20
Ox24
Ox28
Ox2C

0 struct Message *fh_Link;

4 struct MsgPort *fh Port;
8 struct MsgPort *fh~Type;
12 LONG fh Buf;
16 LONG fh::)os;
20 LONG fh End;
24 LONG fh-Funcs;
28 LONG fh-Func2;
32 LONG fh=:Func3;
36 LONG fh Args;
40 LONG fh=:Arg2;
44

/* <> 0 => Interactive */

};

281

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

6.2.2

File management
Creates new subdirectoryl

ICreateDir
Syntax:

Lock = CreateDir(Name)
DO

-120

D1

struct FileLock *Lock;

UBYTE *Narne;

Description:

This function creates a new subdirectory within the current directory, if

possible. You can create a subdirectory on a floppy or hard disk, but
not on CON:, PRT:, or other devices that cannot support
subdirectories.

Parameter:

Name:

Result:

Lock:

Pointer to the directory name. You can also give a path

name. If you enter a path, all directories entered in the
path (except the one you wish to create, which must be
listed last) must already exist.
BCPL pointer to the lock of the new directory (type
ACCESS_READ).

Exceptions:

If the subdirectory cannot be added, the function returns zero. I 0 Err

returns the exact error message.

See Also:

IoErr,Lock,UnLock

CurrentDir
Syntax:

S eciries the current director

oldLock = CurrentDir(Lock)
DO

-126

D1

struct FileLock *oldLock;

struct FileLock *Lock;

Description:

This function sets the current directory. All of the relative path names
(path names that have either a device name ["DFO:s/StartUp-Sequence
or a colon (It :c/dir") at the beginning) can be the current directory. The
CLI command cd directory specifies the current directory.
lt

Parameter:

Lock:

BCPL pointer to the lock representing a directory .

Result:

oldLock:

BCPL pointer to the lock that represented the previous

current directory. If oldLock contains a zero, the old
directory was the root directory of the boot disk.

See Also:

Lock, UnLock

181

6.2 THE DOS LIBRARY

ABACUS

IDeleteFile

Deletes file or directoryl

Syntax:

ok = DeleteFile(Name)
DO
-72
D1
BOOL OK;
UBYTE *Name;

Description:

This function deletes the specified file or empty directory.

Parameter:

Name:

Pointer to the filename.

Result:

OK:

Returns FALSE if the file or directory cannot be

deleted. I oE rr returns the exact error message.

See Also:

IoErr

Examine

Reads file/director

information

Syntax:

ok = Examine(Lock,infoBlock)
DO
-102
D1
D2
BOOL ok;
struct FileLock *Lock;
struct FilelnfoBlock *infoBlock;

Description:

This function fills the FilelnfoBlock with information about the

me or directory. The information can be file size, file type or creation
date as represented by the lock.

Parameters:

Lock:
infoBlock:

BCPL pointer to the lock of the file or directory about

which information is desired.
Pointer to the FilelnfoBlock to which the
information should be written.
Returns FALSE if information cannot be used.

Result:

OK:

Warning:

The FilelnfoBlock must be at an address that is divisible by four.

For optimum memory use, All ocMem allocates memory an address
that is divisible by eight.

See Also:

ExNext

Reads next directory entryl

IExNext
Syntax:

ok = ExNext(Lock,infoBlock)
DO
-108
D1
D2
BOOL OK;
struct FileLock *Lock;
struct FilelnfoBlock *infoBlock;

283

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This function reads the entries in a directory or subdirectory, as well as

the directory's lock. Examine must be called before you call ExNext,
so that the FilelnfoBlock is filled with the necessary starting
values. Then you call ExNext until the function returns FALSE.

Parameters:

Lock:
infoBlock:

BCPL pointer to the lock of the specified directory

Pointer to the FilelnfoBlock previously initialized
by a call to Examine.

Result:

OK:

Returns FALSE when an error occurs, or when no more

files exist in the directory. 10 Err returns the exact
error message. When no more files were present,
IoErr displays the ERROR_NO_MORE_ENTRIES
error message.

Warning:

The FilelnfoBlock must be at an address that is divisible by four.

For optimum memory use, AllocMem allocates memory an address
that is divisible by eight.

Warning:

The FilelnfoBlock must be at an address that is divisible by four.

For optimum memory use, AllocMem allocates memory an address
that is divisible by eight.

Comments:

If you don't know exactly what you're searching for (e.g., filename
from an external source), the type array of the FilelnfoBlock
structure can be selected.

See Also:

Examine

hnfo
Syntax:

Reads disk informationl

ok = Info(Lock,parameterBlock)
DO
-114 01
02
BOOL OK;

struct FileLock *Lock;

struct InfoOata *parameterBlock;

Description:

This function supplies information about the disk on which the file or
directory lies, represented by Lock. This information includes the size
of the diskette and the number of free and used blocks.

Parameters:

Lock:

BCPL pointer to the lock of a fIle or a directory on the

disk.
parameterBlock:
Pointer to the InfoData structure.

Result:

OK:

284

Returns FALSE if the information cannot be used.

6.2 THE DOS LIBRARY

ABACUS

Warning:

The ParameterBlock must be at an address that is divisible by

four. For optimum memory use, All 0 cMem allocates memory an
address that is divisible by eight

IParentDir
Syntax:

Description:

Gets lock of higher directory I

newLock = ParentDir(Lock)
DO
-210
D1
struct FileLock *newLock;
struct FileLock *Lock;

This function returns the lock of the next directory up in the directory

structure.
Parameter:

Lock:

BCPL pointer to the lock.

Result:

newLock:

BCPL pointer to the lock of the next directory up.

Comments:

If newLock returns a zero, the next directory is the root directory.

See Also:

CurrentDir

IRename
Syntax:

Renames file or directoryl

OK = Rename (oldName,newName)

DO

78

D1

D2

BOOL OK;

UBYTE *oldName,*newName;

Description:

This function renames the file or directory called 0 I dN ame to

newName. Both names may contain paths (i.e., the file can be placed
in another directory using this function).

Parameters:

oldName:

newName:

(path) name of the file to be renamed.

(Path) name of the new filename.

Result:

OK:

Comments:

You can move a file from one directory to another very easily by
renaming paths but retaining the original filename.

Warning:

You cannot rename devices using this function.

Returns FALSE if a file with the same name already

exists.

ISetComment
Syntax:

Places comments in file I

OK

= SetComment (Name, Comments)

DO

-180

D1

D2

BOOL OK;

UBYTE *Name,Comments;

285

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

Description:

Parameters:

This function places comments in a file. The comments can be a

maximum of 80 characters in length and must end with a null byte.

Name:
Comments:

Result:

Pointer to the filename.

Pointer to the comments.
Returns FALSE if the comments cannot be written
(e.g., disk is write protected).

OK:

ISetProtection

Sets protection bits in filel

Syntax:

OK = SetProtection(Name,Mask)
DO
-186
D1
D2
BOOL ok;
UBYTE *Narne;
LONG Mask;

Description:

This function sets the protection bits of a file or a directory. The bits
have the following meanings:
Bit 0:
Bit 1:
Bit 2:
Bit 3:
Bit 4:

1 = File not deletable.

1 =File not executable (applies to program files only).
1 =File cannot be overwritten.
1 =File cannot be reaci.
Archive bit-deleted every time a file is closed after write

access.
Only bits 0 and 4 are currently supported by AmigaOOS.
Parameters:

Name:

Pointer to the filename.

Bit mask:.

Mask:
Result:

OK:

Comments:

Bit 4 can be used to determine if a file has been changed since the last
(read) access, provided that the archive bit can be set after the read

Returns FALSE when the changes to the protection

bits cannot be processed.

access.
Structure:

struct FileLock <libraries/dosextens.h>

{

Oxoo
Ox04
Ox08
OxOC
Ox10
Ox14

OBPTR
fl Link;
4 LONG
fl::)ey;
8 LONG
fl Access;
12 struct MsgPort *fl::::Task;
16 BPTR
fl_Volume;
20

/* Linked list */
/* Disk block no */
/* Access mode */
/* in device list */

};

Access modes
ACCESS READ
ACCESS WRITE

286

(fl~ccess):

-2
-1

/* Read access * /
/* Write access */

6.2 THE DOS LIBRARY

ABACUS

struct FilelnfoBlock <libraries/dos.h>

{

OxOO
Ox04

o LONG
4 LONG

fib DiskKey;
fib-DirEntryType; 1* If < 0 => file *1
1* If > 0 => directory *1
fib FileName[108];
fib-Protection;
fib-EntryType;
fib-Size; 1* Size in bytes *1
fib-NumBlocks; 1* no. blocks *1
DateStamp fib Date;
fib_Comment [16];

Ox08
8 char
Ox74 116 LONG
Ox78 120 LONG
Ox7C 124 LONG
Ox80 128 LONG
Ox84 132 struct
Ox90 144 char
Ox104 260
I;
Protection-Flags (fib Protection):
FIBF ARCHIVE
16
FIBF-READ
8
FIBF-WRlTE
4
2
FIBF-EXECUTE
FIBF-DELETE
1
struct InfoData ,libraries/dos.h>
{

OxOO
id NumSoftErrors; 1* Number of errors *1
o LONG
id-UnitNumber;
Ox04
4 LONG
id-DiskState;
Ox08
8 LONG
Oxoc
12 LONG
id::::NumBlocks;
Ox10
16 LONG
id NumBlocksUsed;
id-BytesPerBlock;
Ox14
20 LONG
id-DiskType;
Ox18
24 LONG
id-VOlumeNode;
Ox1c
28 BPTR
Ox20
id::::lnUse 1* 0 if not used *1
32 LONG
36
Ox24
I;
Disk-Status (id_DiskState):
ID_WRITE]ROTECTED 80
ID VALIDATING
81
ID VALIDATED
82
Disk-Type (id_DiskType) :
ID- NO- DISK- PRESENT
-1
ID- UNREADABLE- DISK
'BAD'
ID DOS DISK
' 005 '
ID-NOT-REALLY DOS
'NOOS'
ID- KICKS TART- DISK
'KICK'

6.2.3

File management utility functions

Creates duplicate lockl

IDupLock

Syntax:

newLock = DupLock (Lock I

DO
-96
01
struct FileLock *newLock;
struct FileLock *Lock;

287

6. THE AMIGA LIBRARIES

ADVANCED SYSfEM PROGRAMMER'S GUIDE

Description:

Creates a duplicate of the specified lock. DupLock copies only read

locks and locks of type ACCESS_READ because write locks
(ACCESS_WRITE) require exclusive access.

Parameter:

Lock:

BCPL pointer to the read lock.

Result:

newLock:

BCPL pointer to the copy of the lock.

See Also:

Lock, UnLock

Determines file input channed

!Input
Syntax:

file = Input ()
DO
-54
struct FileHandle *file;

Description:

This function returns the handle of the standard input channel.

Result:

File:

Comments:

The standard input appears in a CLI window. You can redirect this
using <Filename. If you want to get input from the standard input
device of your program, you must identify the file specifier from the
Input function. If you use the C standard functions (e.g., scan f),
the C compiler performs this task for you.

See Also:

Output

IoErr

File specifier for output

Converts error Messa e from last error number

Syntax:

Error = IoErr ()
DO
-132
LONG Error;

Description:

This function returns an error message based on the most recent DOS
error. Most of the DOS functions return zero when an error is
encountered; IoErr gives the user a text message.

Result:

Error:

Comments:

The DeviceProc function returns a second result value through

IoErr.

See Also:

Open, Read, ExNext,DeviceProc

288

Error code of the last DOS command.

6.2 THE DOS LIBRARY

ABACUS

IsInteractive
Syntax:

Identifies virtual terminal

Status = IsInteractive (Ffile)
DO

-216

Dl

BOOL Status;
struct FileHandle *File;

Description:

This function determines whether or not to handle a file as a virtual

terminal (e.g., CON:).

Parameter:

File:

File specifier.

Result:

Status:

Returns TRUE if file is a virtual terminal.

ILock
Syntax:

Determines file lockl

lock = Lock(Name,AccessMode)
DO

-84

Dl

D2

struct FileLock *Lock;

UBYTE *Name;
LONG AccessMode;

Description:

This function identifies the lock of a file or directory. The DOS library
accesses many ftles through locks because of the Amiga's multitasking
operating system. If you want to work with a ftle or a directory, a lock
ensures that no other task will delete or change the file/directory during
your access.
There are two types of locks: locks for reading and locks for writing. A
ftle can have any number of read locks at one time. Only one write lock
can exist at a time, provided the ftle has no read lock attached.

Parameters:

Name:

AccessMode:

Pointer to the file or directory name.

Access mode of the file. A c c e ssM 0 d e =
ACCESS_READ requests a read lock, while
AccessMode = ACCESS_WRITE requests a write
lock.

Result:

Lock:

Exceptions:

If the lock cannot be used (e.g., trying to place a write lock on a ftle on
which a read lock already exists), a zero is returned.

Comments:

If you want to know if a file or a directory exists, try placing a lock on

the file. This is more efficient than trying to open the file. If you want
to actually open the file, don't use the Lock function-just open the
ftle.

BCPL pointer to the lock.

289

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Warning:

Release a lock when you're finished with the ftle. Locked ftles remain
locked until unlocked or until the next reset, and locked ftles cannot be
deleted or edited.

See Also:

UnLock. DupLock

IOutput

Determines file input channed

Syntax:

File = Output ()
DO
-60
struct FileHandle *File;

Description:

This function returns the handle of the standard output channel.

Result:

File:

Comments:

The standard output appears in a CLI window. You can redirect this
using >Filename. If you want to send output from the standard
output device of your program, you must identify the file specifier from
the output function. If you use the C standard functions (e.g .
print f), the C compiler performs this task for you.

See Also:

Input

File specifier for output

IUnLock
Syntax:

Releases lock from file or directoryl

UnLock (Lock)
01

-90

struct FileLock *Lock;

Description:

This function frees the lock on a ftle or a directory placed there by the
Lock or DupLock function.

Parameter:

Lock:

Warning:

Release a lock when you're finished with the ftle. Locked files remain
locked until unlocked or until the next reset, and locked files cannot be
deleted or edited.

See Also:

Lock, DupLock

Structure:

struct FileLock <libraries/dosextens.h>

BCPL pointer to the lock.

OxOO

0 BPTR

Ox04

fl Link;
LONG
fl-Key;
OxOS S LONG
fl:)ccess;
Oxoc 12 struct MsgPort *fl Task;
OxlO 16 BPTR
fl:':'Volume;

Ox14 20
};

290

/* Linked list */
/* Disk block no. */
/* Access mode */
/* in device list */

6.2 THE DOS LIBRARY

ABACUS

Access-modes (f1 Access):

ACCESS READ
-2 1* Read access *1
ACCESS WRITE
-1 1* Write access * 1
Fehlerme1dungen
ERROR- NO- FREE- STORE
103
ERROR- TASK- TABLE- FULL
105
ERROR LINE TOO LONG
120
ERROR FILE NOT OBJECT
121
122
ERROR INVALID RESIDENT LIBRARY
ERROR NO DEFAULT DIR
201
ERROR OBJECT IN USE
202
ERROR OBJECT EXISTS
203
ERROR DIR NOT FOUND
204
ERROR OBJECT NOT FOUND
205
ERROR BAD STREAM NAME
206
207
ERROR OBJECT TOO LARGE
ERROR ACTION NOT KNOWN
209
ERROR INVALID COMPONENT NAME
210
ERROR-INVALID-LOCK
211
ERROR- OBJECT- WRONG- TYPE
212
ERROR DISK NOT VALIDATED
213
ERROR- DISK- WRITE- PROTECTED
214
ERROR- RENAME- ACROSS DEVICES
215
ERROR DIRECTORY NOT EMPTY
216
ERROR TOO MANY LEVELS
217
ERROR- DEVICENOT
218
-MOUNTED
ERROR SEEK ERROR
219
ERROR- COMMENTTOO
BIG
220
ERROR DISK FULL
221
ERROR DELETE PROTECTED
222
ERROR WRITE PROTECTED
223
ERROR READ PROTECTED
224
ERROR NOT A DOS DISK
225
-ERROR NO DISK
226
ERROR NO MORE ENTRIES
232

6.2.4

ICreateProc

Process management
Creates new processl

Syntax:

process = CreateProc(Name,Pri,Segment,StackSize)
DO
-138
D1
D2
D3
D4
struct Process *process;
UBYTE *Name;
LONG Pri;
BPTR *Segment;
LONG StackSize;

Description:

This function initializes and accesses a process data structure. The

segment list is obtained by calling the LoadSeg function.

291

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Segment

Name of the process (a different name from the filename

under which the program is saved on disk).
Task priority. Values for pri may range from -128 to
+ 127, but not within the range from -20 to 20 (values
within this range may cause memory conflicts with the
operating system).
BCPL pointer to the segment list as stated in

StackSize:

Program stack size in bytes.

Result:

Process:

BCPL pointer to the MsgPort of the process data

structure.

Exceptions:

If the process cannot be started, a zero is returned. 10 Err returns the

exact error message.

See Also:

LoadSeg,UnLoadSeg

Parameters:

Name:

Pri:

LoadSeg.

Gets current time and datel

IDateStamp
Syntax:

OateStamp (ptr)

-192

01

LONG *Ptr;

Description:

This function fills three long words with the current time.

Parameter:

Ptr:

See Also:

Data structure of DateStamps

IDelay

Pointer to a data buffer that must contain at least three

long words (12 bytes). The first long word gives the
number of days since l/ln8, the second long word
gives the number of minutes since midnight, and the
third gives the number of ticks since the full minute (1
tick = 1/60 second).

Waits a certain time spanl

Syntax:
Delay (Ticks)
-198
01
LONG Ticks;

Description:

This function pauses a program for the amount of time specified.

Parameter:

Ticks:

292

Length of delay (one tick = 1/60 second).

6.2 THE DOS LIBRARY

ABACUS

Comments:

If you want a program to wait for a certain time span for any reason,
use the Delay function instead of a wait loop: The Delay function is
more reliable.

DeviceProc

Tests

rocess ID of a device driver

Syntax:

Process = DeviceProc(Name)
DO
-174
D1
struct Process *Process;
UBYTE *Name;

Description:

This function tests the device driver that belongs to the specified device.

Parameter:

Name:

Device name or filename on which the device driver

should be tested.

Result:

Process:

BCPL pointer to the message port of the device driver's

process structure.

Exceptions:

If the function returns a zero, the device driver cannot be tested. IoErr
returns the exact error message.

Comments:

When it handles the "device" as a file on an inserted diskette, you get a

BCPL pointer over IoErr to the lock of the directory in which the file
is (assuming no error occurred).

Ends program I
Syntax:

Exit (errorCode)

-144
D1
LONG errorCode;

Description:

This function ends the currently running program, and returns the error
code if the program was started from the CLI.

Parameter:

emxCode:

Warning:

Exi t ends the program without closing open files, windows or

screens, and without freeing locks. Call the Exi t function only when
you are sure that everything open has been closed or released (locks, file
identifications, windows, memory, etc.).

Errortype (0 = no error).

IWaitForChar
Syntax:

Waits for available characterl

ok = WaitForChar (File, Time)
DO
-204
D1
D2
oooL OK;
struct FileHandle *File;
LONG Time;

293

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Description:

This function waits for a character to be entered within a defined time

span. The file must be handled as a virtual terminal (CON:-see
IsInteractive). WaitForChar only determines if characters can
be inserted. You must then read this using the Read function.

Parameters:

File:
Time:

File specifier of a virtual terminal.

Time in microseconds that wai tForChar waits for a
character until it returns a value.

Result:

OK:

Returns FALSE if no characters were entered within the

specified time.

See Also:

IsInteractive

Structure:

struct DateStamp <libraries/dos.h>

{

Oxoo 0
Ox04 4
Ox08 8
OxOC 12

LONG
LONG
LONG

ds Days;
/* days since 1.1.78 */
ds-Minute; /* Minutes since midnight */
ds=Tick;
/* number of ticks */

};

TICKS PER SECOND

60
struct Pr~cess <libraries/dosextens.h>
{

OxOO
Ox5c

Ox7E
Ox80
Ox84
OxB8
Ox8C
Ox90
Ox94
Ox98
Ox9C
OxAO
OxA4
OxA8
OxAC
OxBO
OxB4
OxB8
OxBC

0
92

126
128
132
136
140
144
148
152
156
160
164
168
172
176
180
184
188

};

struct
struct

WORD
BPTR
LONG
APTR
LONG
BPTR
LONG
BPTR
BPTR
BPTR
APTR
APTR
BPTR
APTR
APTR
APTR

Task
pr_Task;
MsgPort pr_MsgPort; /* CreateProc and
/* DeviceProc supply a
/* BCPL pointer to this
/* Message Port.
pr Pad;
pr::::SegList;
pr StackSize;
pr-GlobVec;
pr-TaskNum; /* =0, if not from the CLI*/
pr=StackBase;
pr Result2;
pr::::CurrentDir;
pr_CIS;
/* input channel */
pr_COS;
/* output channel */
pr ConsoleTask;
pr::::FilesystemTask;
pr_CLI;
pr_ReturnAddr;
pr PktWait;
pr=WindowPtr;

*/

*/
*/
*/

/)

A segment is constructed as follows:

-4

LONG
BPTR
4 Code

Segment length + 8;
Next segment (0 if none);

You always receive a pointer to the element containing index 0 from

LoadSeg. The actual code begins 4 bytes later.

294

6.2 THE DOS LIBRARY

ABACUS

6.2.5

Loading programs

\Execute
Syntax:

Executes CLI command\

ok = Execute (Command, Input, Output)
DO

-222

Dl

D2

D3

BOOL OK;
UBYTE *Command;
struct FileHandle *Input,*Output;

Description:

This function executes a CLI command as if you had entered this

directly in the CLI. Input and output can be redirected. When the input
file is unequal to zero, commands are read from the input file after
command processing until the end of the file is reached. If the output
file is zero, the current window ("*") is used, which may not function
properly if the program is started from the Workbench.

Parameters.

Command:
Input:
Output:

Pointer to the command(s) to be executed.

File specifier for input (usually 0).
File specifier for output, (usually the current [CLI]
window).

Result:

OK:

Returns FALSE if it cannot be processed as usual.

\LoadSeg

Loads a program

Syntax:

Segment = LoadSeg(name)
DO
-150
Dl
BPTR Segment;
UBYTE *Name;

Description:

This function loads the specified program into memory. The program
can be started using CreateProc.

Parameter:

Name:

Pointer to the filename of the program.

Result:

Segment:

BCPL pointer to the first segment

Exceptions:

If the program could not be started (e.g., not an executable program),

the function returns a zero and releases memory.

See Also:

UnLoadSeg,CreateProc

295

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Removes programl

IUDLoadSeg
Syntax:

OK = UnLoadSeg(Segment)
DO
-156
01
BOOL OK;
BPTR Segrrent;

Description:

This function removes the program previously loaded into memory

using the LoadSeg function.

Parameter:

Segment:

BCPL pointer to the segment.

Result:

OK:

Returns FALSE if an error occurs.

Comments:

If you started the program with CreateProc, you won't have to free
the segment because C re ate Pro c automatically removes the
segment when the program ends.

See Also:

LoadSeg

StructureS:

A segment is constructed as follows:

-4

LONG

BPTR
4 Code

Length of the segment + 8;

Next Segment (0 if none);

You always get a pointer to the element with the index of 0 from
LoadSeg. The actual code begins 4 bytes later.

6.2.6

Internal DOS functions

IGetPacket

Gets DOS packet!

Syntax:

OK = GetPacket(WaitForIt)
DO
-162
01
BOOL OK;
BOOL WaitForIt;

Description:

This function gets a DOS packet sent from another process.

Parameter:

WaitForIt:

Ready status-registers TRUE while waiting for a DOS

packet

Result:

OK:

Packet status-returns a zero if no packet exists and

WaitForIt registers FALSE.

296

6.2 THE DOS LIBRARY

ABACUS

IQueuePacket

Sends DOS packet to another process

Syntax:
Error = QueuePacket(Packet)
DO
-168
D1
LONG Error;
struct DosPacket *Packet;

Description:

Sends a DOS packet to the process stated in the DOSPacket structure.

Parameter:

Packet:

Result:
Structures:

Pointer to the DOS packet to be sent.

Returns zero if an error occurs.

struct DosPacket <libraries/dosextens.h>

{

OxOO
Ox04
OxOS
OxOC
Ox10
Ox14
Ox1S
Ox1C
Ox20
Ox24
Ox2S
Ox2C
Ox30

0
4
8
12
16
20
24
28
32
36
40
44
48

struct Message *dp_Link;

1* set to zero *1
struct MsgPort *dp_Port;
LONG dp_Type;
LONG dp_Res1;
1* result *1
LONG dp_Res2;
1* 2. result => IoErr () *1
LONG dp_Arg1;
LONG dp_Arg2;
LONG dp_Arg3;
LONG dp_Arg4;
LONG dp_Arg5;
LONG dp_ Arg6;
LONG dp_ Arg7;

};

struct StandardPacket <libraries/dosextens.h>

{

OxOO 0
Ox14 20
Ox44 68

struct Message
sp_Msg;
struct DosPacket sp~kt;

);

Packet-type (dp_Type) :
ACTION NIL
ACTION GET BLOCK
ACTION SET MAP
ACTION DIE
ACTION EVENT
ACTION- CURRENT- VOLUME
ACTION- LOCATE- OBJECT
ACTION RENAME DISK
ACTION WRITE
ACTION READ
ACTION FREE LOCK
ACTION DELETE OBJECT
ACTION- RENAME- OBJECT
ACTION COPY DIR
ACTION WAIT CHAR
ACTION SET PROTECT
ACTION CREATE DIR
ACTION- EXAMINE- OBJECT
ACTION EXAMINE NEXT
ACTION DISK INFO
~CTION INFO

0
2
4
5
6
7
8
9
'WI
'R'
15
16
17

19
20
21
22
23
24
25
26

297

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

ACTION
ACTION
ACTION
ACTION
ACTION
ACTION

SET COMMENT
PARENT
TIMER
INHIBIT
DISK TYPE
DISK CHANGE

28
29
30
31
32
33

6.2.7

DosBase

Structures:

struct DosLibrary <libraries/dosextens.h>

(

OxOO
Ox22
Ox26
Ox2A
Ox2E
Ox32
Ox36

0
34
38
42
46
50
54

struct
APTR
APTR
LONG
LONG
LONG

Library dl lib;
dl Root; dl-GV;
dl=A2;
dl AS;
dl=A6;

1* pointer to the RootNode *1

);

struct RootNode <libraries/dosextens.h>

(

OxOO
Ox04
OxOS
Ox14
Ox18
Ox1C
Ox20

rn TasKArray; 1* [0) = Maximum number of CLIs

1* [n) APTR to process from CLI n
4 BPTR
rn_ConsoleSegment;
1* Current time
8 struct DateStamp rn_Time;
rn_ RestartSeg;
20 LONG
24 BPTR
rn Info;
1* pointer to Doslnfo
28 BPTR
rn=FileHandlersegment;
32
0 BPTR

*1
*1
*1
*1

};

struct Doslnfo <libraries/dosextens.h>

(

OxOO 0
Ox04 4
Ox08 8
OxOC 12
Ox10 16
Ox14 20

BPTR di McName;
BPTR di-Devlnfo; 1* pointer to list of all devices *1
BPTR di -Devices;
BPTR di-Handlers;
APTR di=NetHand;

);

struct DeviceList <libraries/dosextens.h>

(

OxOO
Ox04
Ox08
OxOC
Ox10
Ox1C
Ox20
Ox24
Ox28
Ox2C

0 BPTR
dl Next;
1* BPTR to next device
4 LONG
dl=Type;
8 struct MsgPort *dl Task;
dl-Lock;
12 BPTR
1* Not for disks
16 struct DateStamp dl=VolumeDate;
28 BPTR
dl_LockList; 1* List of all locks
32 LONG
dl_DiskType; 1* e.g . "DOS"
36 LONG
dl_unused;
40 BSTR
*dl_Name;
1* BPTR to BCPL string
44

);

Device Type (dl Type):

DLT DEVICE
-0
DLT DIRECTORY
1
DLT VOLUME
2

298

*1
*1
*1
*1
*1

6.3

ABACUS

6.3

THE INTUITION LIBRARY

The Intu ition library

The Intuition library is resident, which means that it stays in memory
right after the computer is booted. Intuition handles everything
concerning the graphic user interface, from screen and window
management to the report transfer between gadgets and programs. The
OpenLibrary function allows us access to all the programs
("intuition.library" OL). This library has a wealth of functions for
controlling the windows, gadgets, menus, graphics and screens.
Blruet Rootnode:

IIlruet OosLibrary:
Blruet
d,-Ub
APTA
d,-Rool
APTA
cI_GV

LaG
dl_A2

Library

BPTR
rn_ TaskArray

r-

IIIrucl OevlceLlIII:

lllruct DOIIlnfo:

r-

8PTR
cI_McName
8PTR
d'-Devlnfo

BFTA
m_ConaoleSegmenl

8PTR
dl_Devlc811

slruet DaleStamp
rn_Tlme

r'I"'"

BFTA
dl_Nexl

LaG
dl_Type
IItruet MsgPort
dl_Task

BPTR
dLHandlera

LaG

BPTR

rn_AeslartSeg

BFTA
dl_Lock

cI_NetHand

LaG
dl_AS

BFTA
rn_lnfo

LaG
dl_AS

BFTA
m_FUeHandlerSeg.

slruet DaleStamp
dLVoIumeDale
BFTA
d'-LockLlst

LaG
d,-OlskType

LaG
d,-unused
BSTA
dl_Name

.,

The Intuition library operates in conjunction with the Graphics and the
Layers libraries. Intuition uses the Layers library to represent the
gadgets and window overlapping. It also uses the Graphics library for
graphic output and formatting, fonts, the bit-map, ViewPort
management and everything else that has a task.

299

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Intuition library functions

6.3.1

Window functions
ActivateWindow
CloseWindow
ModifyIDCMP
MoveWindow
OpenWindow
RefreshWindowFrame
SetWindowTitles
SizeWindow
WindowLimits
WindowToBock
WindowToFront

6.3.2

309

310
313
314
314
315
315
316
316
317
317

318
318
319
319
319

Requester and alert functions

AutoRequest
BuildSysRequest
ClearDMRequest
DisplayAlert
EndRequest
FreeSysRequest
InitRequester

300

306
307
307
308
308
309

Menu functions
ClearMenuStrip
ltemAddress
OffMenu
OnMenu
SetMenuStrip

6.3.4

303
303
304

Gadget functions
ActivateGadget
AdlGOOget
AddGList
ModifyProp
NewModifyProp
OftGadget
OnGadget
RefreshGadgets
RefreshGList
RemoveGadget
RemoveGList

6.3.3

302
302

321
322
322
323
323
324
324

6.3

ABACUS

Request
SetDMRequesl

6.3.5

335
336

Refresh functions
BeginRefresh
EndRefresh
RemakeDisplay
RethinkDisplay

6.3.9

332
332
333
333
334
334

Memory functions
AllocRemember
FreeRemember

6.3.8

326
326
327
327
327
328
328
330
330
330
331
331
331

Graphic functions
ClearPointer
DtawBonler
DrawImage
IntuiTextLength
PrintIText
SetPointer

6.3.7

325
325

Screen functions
OoseScreen
CloseWorkBench
DisplayBeep
GetScreenData
MakeScreen
MoveScreen
OpenScreen
OpenWorkBench
ScreenToBack
ScreenToFront
ShowTitle
WBenchToBack
WBenchToFront

6.3.6

THE INTUITION LIBRARY

336
336
337
337

Other functions
CurrentTime
DoubleClick
GetDefPrefs
GetPrefs
LockIBase
ReportMouse

337
338
338
338
342
343
301

6. THE AMIGA LIBRARIES

6.3.1.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

SetPrefs
UnlockIBase

343
343

ViewAddress
ViewPortAddress

344
344

Window fu nctions
Activates Intuition window

ActivateWindow
Syntax:
ActivateWindow(Window);
-450
AO
struct Window *Window;

Description:

This function activates a window controlled by Intuition.

Menu or gadget access can slow execution speed. When the window is
really active, then it can easily be checked using the ACTIVEWINDOW
IDCMP flags.
The function should be used with caution because keyboard input gives
you a new active window.

Parameter:

Window:

Warning:

Intuition report processing can be paralyzed if the function is called

frequently.

See Also:

Openwindow () , IDCMP flags (ACTIVEWINDOW)

Pointer to an Intuition window structure.

\closeWindow

Closes an Intuition windowl

Syntax:
CloseWindow(Window);
-72
AO
struct Window *Window;

Description:

This function closes a window managed from Intuition, removes the

window from the system list and releases allocated memory, closing the
system screen if needed. The system ignores any reports in the IDCMP.
When a message port to the window is opened, you should ensure that
there are no unprocessed reports there. The access to a memory buffer
that no longer exists can cause a system error.

302

6.3

ABACUS

THE

INTUITION

LIBRARY

You should also know that a previously added menu strip must be
removed before you may close a window. This Intuition function
blocks all other functions until it has ended the task.
Parameter:

Window:

See also:

OpenWindow () , CloseScreen ( )

Pointer to an Intuition window structure.

IMOdiryIDCMP

Changes IDCMP nag settingsl

Syntax:
ModifyIDCMP(Window, IDCMPFlags);
-150

AD

DO

struct Window *Window;

ULONG IDCMPFlags;

Description:

This function changes the IDCMP (Intuition Direct Communication

Message Port) flags of an Intuition window and places it in a new
status. A port may be added where one did not previously exist by
setting unset flags; some flags may. be unset by setting others; and a
port may be removed by entering a zero.

Parameters:

Window:
Pointer to an Intuition window structure.
IDMCPFlags: Flag bits describing the status of the IDCMP.

See Also:

Openwindow () , Closewindow ( )

MoveWindow
Syntax:

Moves window to another

MoveWindow (Window, DeltaX, DeltaY);
-168

AD

DO

D1

struct Window *Window;

SHORT DeltaX, DeltaY;

Description:

This function moves an Intuition window in the DeltaX and DeltaY

directions. The new positioning does not execute immediately. When
Intuition receives an input event (which it does at a rate of 10 times per
second), the function executes.

Parameters:
Window:
DeltaX:
DeltaY:

Pointer to an Intuition window structure.

Integer value specifying movement in the X direction.
Integer value specifying movement in the Y direction.

Warning:

This functions does not check the movement values for accuracy. Make
sure that your coding doesn't try moving the window to a nonexistent
location, or a system error may result.

See Also:

Sizewindow ()

303

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Opens an Intuition windowl

IOpenWindow
Syntax:

Window = OpenWindow(NewWindow);
DO
-204
AO
struct NewWindow NewWindow;

Description:

This function opens an Intuition window with the values specified in

the structure. A win do w structure is added to the window. The
NewWindow structure is no longer needed and can be removed.
IT the window appears on a CUSTOMSCREEN, this screen can be
opened before opening the window. IT the window should include
gadgets, a linked list of these must be included in the Newwindow
structure.

Parameter:

NewWindow: Pointer to a Newwindow structure that was installed

beforehand by the programmer.

Result:

Window:

See Also:

CloseWindow(),MOdifyIDCMP(),OpenScreen(),
CloseScreen(),WindowTitles()

Pointer to an Intuition window structure.

Structures:
struct NewWindow <intuition/intuition.h>
{

Oxoo

00

Ox02
Ox04
Ox06
Ox08
Ox09

02
04
06
08
09

OxOA
OxOE
Ox12

10
14
18

Ox16

22

Ox1A
Ox1E
Ox22

26
30
34

Ox26
Ox28
Ox2A
Ox2C
Ox2E
Ox30

38
40
42
44
46
48

};

304

SHORT LeftEdge; /* Upper left corner of window

relative to the screen */
SHORT TopEdge;
SHORT Width;
/* Window width and height in pixels */
SHORT Height;
UBYTE DetailPen; /* Color number of foreground pen */
UBYTE BlockPen; /* Color number of the background
pen */
ULONG IDCMPFlags;
/* All of the set IOCMP flags */
ULONG Flags;
/* All of the set window flags */
struct Gadget *FirstGadget; /* Pointer to the first
gadget */
struct Image *CheckMark; /* Pointer to the graphic
from the checkmark */
UBYTE *Title;
/* Pointer to the title text string */
struct Screen *Screen;
/* Pointer to the screen */
struct Bitmap *Bitmap;
/* Pointer to a bitmap
for the window */
SHORT MinWidth;
/* Minimum window size */
SHORT MinHeight;
USHORT MaxWidth;
/* Maximum window size */
USHORT MaxHeight;
USHORT Type;
/* Window type */

ABACUS

6.3 THE INTUITION LIBRARY

struc~

Window <intuition/intuition.h>

OxOO

00

Ox04

04

Ox06
Ox08

06
08

OxOA 10
Oxoc 12
OxOE
Ox10
Ox12
Ox14
Ox16
Ox18
Ox1C

16
18
20
22
24
28

Ox20

32

Ox24

36

Ox28

40

Ox2C

44

Ox2E
Ox32

46
50

Ox36
Ox37
Ox38
Ox39
Ox3A

54
55
56
57
58

Ox3E

62

Ox42

66

Ox46

70

Ox4A

74

Ox4E
Ox4F
Ox50
Ox51
Ox52
Ox56
Ox5A

78
79
80
81
82
86
90

Ox5E

94

14

Ox62 98
Ox63 99
Ox64 100
Ox68 104

struct Window *NextWindow; /* Pointer to other windows

in the screen */
SHORT LeftEdge; /* Top left corner of window relative
to the screen */
SHORT TopEdge:
SHORT Width:
/* Width and height of the window in
pixels */
SHORT Height;
SHORT MouseY;
/* Mouse position relative to the
window */
SHORT MouseX;
SHORT MinWidth;
/* Minimum window size */
SHORT MinHeight;
USHORT MaxWidth;
/* Maximum window size */
USHORT MaXHeight;
ULONG Flags;
/* Window flags */
/* Pointer to the menu
struct Menu *MenuStrip;
list of this Window */
UBYTE *Title;
/* Pointer to the title text of the
window */
struct Requester *FirstRequest;
/* Pointer to the
first requester
in the window */
/* Pointer to the
struct Requester *DMRequest;
DoubleMenuRequester
of the window */
SHORT ReqCount;
/* Number of opened requester in
window */
struct Screen *WScreen;
/* Pointer to WB screen */
struct RastPort *RPort;
1* Pointer to Rastport of
window */
BYTE BorderLeft;
/* Margin width */
BYTE BorderTop;
BYTE BorderRight;
BYTE BorderBottom;
struct RastPort *BorderRPort; /* Pointer to RastPort
of the window margin */
struct Gadget *FirstGadget;
1* Pointer to the first
gadget in the window */
struct Window *Parent
/* Pointer to the previous
window */
struct Window *Descendant;
/* Pointer to window to
close */
USHORT *Pointer;
/* Pointer to the mouse pointer
graphic */
BYTE PtrHeight;
/* Mouse pointer height */
BYTE PtrWidth;
/* Mouse pointer width*/
BYTE XOffset;
/* Marking HotSpot */
BYTE YOffset;
ULONG IDCMPFlags;
/* All IDeM? flags */
struct MsgPort *UserPort; 1* Message Port for user */
struct MsgPort *WindowPort;
/* Message Port for
window */
struct IntuiMessage *MessageKey; /* Report from
Intuition */
UBYTE DetailPen;
/* Foreground character color */
UBYTE BlockPen;
/* Background character color */
struct Image *CheckMark; /* Pointer to graphic for
checkmark */
UBYTE *ScreenTitle;
/* Pointer to the screen title

305

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Ox6C 108

SHORT GZZMouseX;

Ox6E
Ox70
Ox72
Ox74

SHORT
SHORT
SHORT
UBYTE

llO
ll2
ll4
ll6

Ox78 120
Ox7C 124
Ox80 128

GZZMouseY;
GZZWidth;
GZZHeight;
*ExtData;

text */
/* Mouse position in the GZZ
Window */

1* GZZ window width and height */

/* Pointer to more data

(Expansions) */
BYTE *UserData;
/* Pointer to window user data *1
struct Layer *WLayer;
1* Pointer to window layer */
struct TextFont *IFont; 1* Pointer to standard
character set in this
window */

Ox84 132
);

Window_Flags:
WINDOWSIZING
WINDOWDRAG
WINDOWDEPTH
WINDOWCLOSE
SIZEBRIGHT
SIZEBBOTTOM
REFRESHBITS
SMART REFRESH
SIMPLE REFRESH
SUPER BITMAP
OTHER REFRESH
BACKDROP
REPORTMOUSE
GIMMEZEROZERO
BORDERLESS
ACTIVATE
WINDOWACTIVE
INREQUEST
MENUSTATE
RMBTRAP

NOCAREREFRESH
WINDOWREFRESH
WBENCHWINDOW
WINDOWTICKED
SUPER UNUSED

OxOOOlL 1* Window gadgets */

Ox0002L
Ox0004L
Ox0008L
OxOOlOL
Ox0020L
OxOOCOL /* Refresh modes */
OxOOOOL
Ox0040L
Ox0080L
OxOOCOL
OxOlOOL
Ox0200L
Ox0400L
Ox0800L
OxlOOOL
Ox2000L
Ox4000L
Ox8000L
OxOOOlOOOOL
Ox00020000L
OxOlOOOOOOL
Ox02000000L
Ox04000000L
OxFCFCOOOOL

IRefreshWindowFrame

Redraws windowl

Syntax:

RefreshWindowFrame(Window);
-456
AO
struct Window *Window;

Description:

This function redraws the border, tide and gadgets of a window, keeping
graphic distortion to a minimum.

Pammeter:

Window:

See Also:

RefreshGadgets(),RefreshGList()

306

Pointer to an Intuition window structure.

6.3 THE INTUITION LIBRARY

ABACUS

SetWindowTities

Sets window/screen titles

Syntax:

SetWindowTitles(Window, WindowTitl~, ScreenTitle);

-276
AD
Al
A2
struct Window *Window
UBYTE *WindowTitle, *ScreenTitle

Description:

This function specifies the screen or window title text.

The window title is announced from Intuition. The window title only
appears in the screen title list if the window is also active. After the
call of the routine the titles of the screen and window change. If you
only want to change one of the two titles, you replace the other pointer
with a -1. This informs Intuition that the previous text should be
retained.

Parameters:

Window:
Pointer to an Intuition window structure.
WindowTitle: Pointer to a string that ends with zero that represents
the text. This string can also contain a value of -1 for
original text or a value of 0 for no text
ScreenTitle:
Pointer to a string representing the text, that ends with
zero. This string can also contain a value of -1 for the
original text or a value of 0 for no text

See Also:

OpenWindow(),RefreshWindowFrame(),OpenScreen()

ISizeWindow

Changes window sizel

Syntax:

SizeWindow(Window, DeltaX, DeltaY);

-288
AD
DO
Dl
struct Window *Window;
SHORT DeltaX, DeltaY;

Description:

This function changes an Intuition window's size in the Del taX and
Del taY directions. The new size does not execute immediately. When
Intuition receives an input event (which it does at a rate of 10 times per
second), the function executes.

Parameters:

Window:
DeltaX:
DeltaY:

Pointer to an Intuition window structure.

Integer value which specifies resizing in the X
direction.
Integer value which specifies resizing in the Y
direction.

Warning:

This function does not check the sizing values for accuracy. Make sure
that your coding doesn't try resizing thl'! window in a nonexistent
location, or a system error may result.

See Also:

MoveWindow(),OpenWindow()*

307

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Window's minimum/maximum values

WindowLimits
Syntax:

Settings = WindowLimits(Window, MinWidth, MinHeight, MaxWidth,

DO

-318

AO

00

Dl

02

MaxHeight);
03
BOOL Settings;
struct Window *Window;
USHORT MinWidth, MinHeight;
USHORT MaxWidth, MaxHeight;

Description:

This function determines the minimum and maximum sizes of the

window. After the call the window size can be changed to match these
values.

If you don't want to change these values, set them to zero. The function
then ignores further entries and maintains the original settings.
Entering -1 changes the window to maximum (screen) size.
Parameters:

Window:
MinWidth:
MinHeight:
MaxWidth:
MaxHeight:

Result:

Returns TRUE if all parameters are within allowable limits. If a value

does not lie in the region (too large or too small), FALSE is returned
to you.

Comments:

When the function is called during resizing of the window, the new
values take effect after this operation.

See Also:

GetScreenData ()

Pointer to an Intuition window structure.

New minimum window width.
New minimum window height.
New maximum window width.
New maximum window height.

IWindowToBack

Moves window to back\

Syntax:

WindowToBack (Window);
-306
AO
struct Window *Window;

Description:

This function moves the specified window behind all others on the
screen.
The function does not execute immediately. When Intuition receives an
input event (input events occur 10 times per second), the function
executes.

Parameler:

308

Window:

Pointer to an Intuition window structure.

6.3

ABACUS

THE INTUITION LIBRARY

Comments:

The function does not operate with BACKDROP windows.

See Also:

WindowToFront(),MoveWindow(),Sizewindow()

IWindowToFront

Moves window to rrontl

Syntax:
WindowToFront(Window);
-312
AO
struct Window *Window;

Description:

This function moves the specified window in front of all others on the
screen.
The function does not execute immediately. When Intuition receives an
input event (input events occur 10 times per second), the function
executes.
Pointer to an Intuition window structure.

Parameter:

Window:

Comments:

The function does not operate with BACKDROP windows.

See Also:

WindowToBack () ,MoveWindow () , SizeWindow ()

6.3.2

Gadget functions

IActivateGadget

Activates string gadget!

Syntax:

Succes = ActivateGadget(Gadget, Window, Requester);

DO
-462
AO
Al
A2
BOOL Succes;
struct Gadget *Gadget;
struct Window *Window;
struct Requester *Request;

Description:

This function activates a string gadget, provided the REQGADGET flag

in the gadget structure is set.

Parameters:

Gadget

Window:
Requester:
Result:

Pointer to the string gadget to be activated.

Pointer to the window structure linked in the gadget.
Pointer to a requester when the string gadget is found in
such.

Returns 1RUE if all conditions are fulfilled (see Comments below), or

FALSE if conditions are unfulfIlled.

309

6. THE AMIGA LIBRARIES

Comments:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The window containing the gadget must be active before execution.

No other gadgets may be in use during the function call (including
system gadgets).
If this function involves a requester, the requester must also be active.

The fuoction does not operate during a menu choice.

IAddGadget

Adds gadget to window's gadget listl

Syntax:

RealPosition = AddGadget(Window, Gadget, Position);

DO
-42
AO
Al
DO
USHORT RealPosition;
struct Window *Window;
struct Gadget *Gadget;
USHORT Position;

Description:

This function adds the specified gadget to the active window's list of
gadgets.
If you use system gadgets, these are placed at the beginning of the
gadget list so that they are always checked first

Intuition does not support user-inserted screen gadgets. Instead you can
open a BACKDROP window, which looks similar to a screen, and add
gadgets to the BACKDROP window.
Parameters:

Window:

GOOget
Position:

Pointer to an Intuition window structure.

Pointer to a gadget structure.
Gadget's position number:
Po sit ion = 0: First gadget in list.
position = 1: Second gadget in list
Posi tion = 2: Third gadget, etc.
Posi tion = -1: Last gadget in list.

Result:

Returns the position at which the gadget is inserted.

See Also:

AddGList(),RemoveGadget(),RemoveGList()

Structures:

struc:t Gadget <intuition/intuition.h>

310

OxOO

00

Ox04

04

Ox06
OxOS

06
OS

OxOA
OxOC
OxOE

10
12
14

struct Gadget *NextGadget; /* Link to next gadget in

list * /
SHORT LeftEdge; /* Pixel position of the click region:
upper left corner */
SHORT TopEdge;
SHORT Width; /* Width and height of click region in
pixels */
SHORT Height;
USHORT Flags;
/* Gadget flags */
USHORT Activation; /* Activation mode */

6.3 THE INTUITION LIBRARY

ABACUS

Ox10
Ox12
Ox16
Ox1A
Ox1E
Ox22
Ox26
Ox28
Ox2C

16 USHORT GadgetType; /* Flags for gadget types */

18 APTR GadgetRender; /* Pointer to structure of
gadget's appearance */
22 APTR SelectRender; /* Pointer to graphic
activation * /
26 struct IntuiText *GadgetText; /* Pointer to gadget's
text */
30 LONG MutualExc1ude;/* Deactivation of other gadgets
(not currently implemented) */
34 APTR SpecialInfo; /* Pointer to additional
information */
38 USHORT GadgetID;
/* Gadget identification number */
40 APTR UserData;
/* Pointer to program data */
44

};

GADGHIGHBITS Ox0003L/*
GADGHCOMP OxOOOOL
/*
GADGHBOX Ox0001L
/*
GADGHIMAGE Ox0002L /*
GADGHNONE Ox0003L
/*
GADGIMAGE Ox0004L
/*
GRELBOTTOM Ox0008L /*
GRELRIGHT Ox0010L
/*
GRELWIDTH Ox0020L
/*
GRELHEIGHT Ox0040L /*
SELECTED Ox0080L
/*
GADGDISABLED Ox0100L/*

Gadget highlighting flags */

click region inverted */
Draws box around the click region */
New graphic displayed */
No reaction from gadget */
Graphic displayed instead of a margin */
Position relative to bottom
window border */
Position relative to right border */
Relative width */
Relative height */
Gadget selected */
Gadget cannot be selected */

Gadget_Activation:
RELVERIFY Ox0001L
/* Verifies selection */
GADGIMMEDIATE Ox0002L /* Selection executes on 1 click */
ENDGADGET Ox0004L
/* Requester gadget that goes to the end */
FOLLOWMOUSE Ox0008L
/* Follows mouse coordinates */
RIGHTBORDER Ox0010L
/* Gadget placed in right window border */
LEFTBORDER Ox0020L
/* Gadget placed in left window border */
TOPBORDER Ox0040L
/* Gadget placed in top window border */
BOTTOMBORDER Ox0080L /* Gadget placed in bottom window border */
TOGGLESELECT Ox0100L /* Toggles gadget on/off */
STRINGCENTER Ox0200L /* Shoe text in middle of string gadget */
STRINGRIGHT Ox0400L
/* Displays text in right margin */
LONGINT Ox0800L
/* Long word integer gadget */
ALTKEYMAP Ox1000L
/* Gadget uses alternate keymap */

Gadget_GadgetType:
BOOLEXTEND Ox2000L
GADGET TYPE OxFCOOL
SYSGADGET Ox8000L
SCRGADGET Ox4000L
GZZGADGET Ox2000L
REQGADGET Ox1000L
SIZING OxOOlOL
WDRAGGING Ox0020L
SDRAGGING Ox0030L
WUPFRONT Ox0040L

/*
/*
/*
/*
/*
/*
/*
/*
/*

Gadget types */
System gadget */
Screen gadget */
GimmeZeroZero gadget */
Requester gadget */
Sizing gadget */
Window Drag gadget */
Screen Drag gadget */
Window Up Front gadget */

311

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

SUPFRONT Ox0050L
/* Screen Up Front gadget */
WDOWNBACK Ox0060L
/* Window Down Back gadget */
SDOWNBACK Ox0070L
/* Screen Down Back gadget */
CLOSE Ox0080L
/* Close gadget */
BOOLGADGET Ox0001L
/* Boolean gadget (in/out) */
GADGET0002 Ox0002L
/* Type 0002 gadget */
PROPGADGET Ox0003L
/* Proportional gadget */
STRGADGET Ox0004L
/* String gadget */
struct Boollnfo <intuition/intuition.h>
{

OxOO

00

Ox02
Ox04
Ox08

02
04
08

USHORT Flags; /* addition structure for Boolean

gadgets */
UWORD *Mask;
ULONG Reserved;

};

Boollnfo_Flaqs:
BOOLMASK Ox0001L /* User-defined Boolean mask */
struct Proplnfo
{

OxOO
Ox02
Ox04
Ox06
Ox08
OxOA
OxOC
Ox DE
Ox10
Ox12

00
02
04
06
08
10
12
14
16
18

Ox14
Ox16

20
22

USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT

Flags;
/* Proportional gadget flags*/
HorizPot; /* Horizontal position of slider */
VertPot;
/* Vertical position */
HorizBody; /* Horizontal size of slider */
VertBody; /* Vertical size */
CWidth;
/* Container width*/
CHeight;
/* Container height */
HPotRes; /* Horizontal resolution of slider */
VPotRes;
/* Vertical resolution */
LeftBorder;/* Left border of proportional
gadget */
USHORT TopBorder; /* Top border */

};

Proplnfo_Flaqs:
AUTOKNOB Ox0001L /* Default slider knob */
FREEHORIZ Ox0002L /* Slider can be moved horizontally */
FREEVERT Ox0004L /* Slider can be moved vertically */
PROPBORDERLESS OxOOOBL /* No box around slider */
KNOBHIT Ox0100L
/* Set when slider is active */

Proplnfo_Values:
KNOBHMIN 6L
/* Minimum horizontal knob resolution */
KNOBVMIN 4L
/* Minimum vertical resolution */
MAXBODY OxFFFFL / * Maximum * /
MAXPOT OxFFFFL
struct Stringlnfo <intuition/intuition.h>
{

312

OxOO
Ox04
Ox08
OxOA

00
04
08
10

UBYTE
UBYTE
SHORT
SHORT

OxOC
OxOE

12
14

SHORT DispPos;
SHORT UndoPos;

*Buffer;
*UndoBuffer;
BufferPos;
MaxChars;

/*
/*
/*
/*

Pointer to text buffer */

Pointer to undo buffer */
Cursor position in buffer */
Maximum number of characters in
buffer */
/* Buffer position in display *1
/* Cursor position in undo buffer */

ABACUS

6.3 THE INTUITION LIBRARY

Ox10
Ox12
Ox14
Ox16
Ox18
OxIC

16
18
20
22
24
28

Ox20

32

Ox24

36

SHORT NUmChars;
/* Number of characters entered */
SHORT DispCount; /* Number of characters in display */
SHORT Cleft;
/* Left border of container */
SHORT CTop;
/* Top border */
struct Layer *Layerptr; /* Pointer to gadget layer */
LONG Longlnt; /* Number re-converted for integer
gadget */
struct KeyMap *AltKeyMap; /* Pointer to an alternate
keymap */

};

IAddGList

Inserts gadget Iistl

Syntax:

RealPosition = AddGList(Window, Gadget,

DO
-438
AD
Al
Position, Numgad, Requester);
DO
Dl
D2
USHORT RealPosition;
struct Window *Window;
struct Gadget *Gadget;
USHORT Position;
USHORT Numgad;
struct Requester *Requester;

Description:

This function inserts a list of gadgets in an existing window gadget list

or requester gadget list. The *Requester pointer comes into play
only when gadgets must be added to a requester contained in a given
window.
The AddGList function adds as many gadgets of the linked list to that
of the window as are given with Numgad. It is interrupted when a
pointer to the next gadget is set to zero.

Parameters:

Window:
Gadget
Position:
Numgad:
Requester:

Pointer to window structure in which the new gadget

should be inserted.
Pointer to gadget structure.
Gadget's position number.
Number of the gadget to be added to the list.
Pointer to gadget's request structure.

Result:

Returns the position at which the gadget was actually inserted. This
number is in effect until no other gadgets are inserted.

Warning:

If you don't use all of the gadgets of a linked list for the window or the
requester, make sure that Intuition changes the pointer of the last gadget
inserted.

See Also:

AddGadget(),RemoveGadget(),RemoveGList()

313

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

IModifyProp
Syntax:

Changes proportional gadget settingsl

Modi fyP rop (Gadget, Window, Requester, Flags,
-156

AO

Al

A2

00

HorizPot, VertPot, HorizBody, VertBody);

01

struct
struct
struct
USHORT
USHORT
USHORT

02

03

04

Gadget *Gadget;
Window *Window;
Requester *Requester;
Flags;
HorizPot, VertPot;
HorizBody, VertBody;

Description:

This function changes the settings assigned to a proportional gadget,

then displays the new gadget. The normal Re f res h function
redisplays the other gadgets on the list as well as the proportional
gadget The settings are similar to those used for a requester.

Parameters:

Gadget:
Window:
Requester:
Flags:
HorizPot:
VertPot:
HorizBody:
VertBody:

See Also:

Pointer to proportional gadget structure.

Pointer to window structure containing the gadget.
Pointer to requester structure containing the gadget
Value that should be transferred to the Flags variable
of the gadget.
Value that should be transferred to the H0 r i z Pot
variable of the gadget.
Value that should be transferred to the Ve r t Pot
variable of the gadget
Value that should be transferred to the HorizBody
variable of the gadget.
Value that should be transferred to the VertBody
variable of the gadget.

NewModi fyP rop ( )

INewMOdifyProp
Syntax:

Changes proportional gadget settingsl

NewModifyProp(Gadget, Window, Requester, Flags, HorizPot,

-468

AO

Al

A2

00

01

VertPot, HorizBody, VertBody, Numgad);

02

03

04

05

struct Gadget *Gadget;

struct Window *Window;
struct Requester *Requester;
USHORT Flags;
USHORT HorizPot, VertPot;
USHORT HorizBody, VertBody;
int Numgad

Description:

314

The command has the same function as the Modi fyP rop ( )
command. How many gadgets should be re-drawn can also be set
through Numgad.

6.3 THE INTUITION UBRARY

ABACUS

Description:

This function changes the settings assigned to a proportional gadget,

then displays the new gadget, refreshing only the gadgets specified by
the Numgad parameter.

Parameters:

Gadget

Pointer to proportional gadget structure.

Pointer to window structure containing the gadget.
Pointer to requester structure containing the gadget.
Value that should be transferred to the Flags variable
of the gadget.
Value that should be transferred to the H0 r i z Pot
variable of the gadget.
Value that should be transferred to the VertPot
variable of the gadget.
Value that should be transferred to the Hori zBody
variable of the gadget.
Value that should be transferred to the VertBody
variable of the gadget.
Number of gadget that should be re-drawn. Entering -1
is the same as accessing ModifyP rop.

Window:
Requester:
Flags:
HomPot:
VertPot:
HorizBody:
VertBody:
Numgad:

See Also:

ModifyProp ()

IOrrGadget
Syntax:

Disables gadget!
OffGadget (Gadget, Window, Requester);
-114

AO

A1

A2

struct Gadget *Gadget;

struct Window *Window;
struct Requester *Requester;

Description:

Parameters:

This function makes it impossible for the user to choose a gadget. A

disabled gadget appears in ghost print. The GAD GO I SABLED flag can
also be set through programming to get the same result.
Pointer to gadget structure.
Pointer to window structure containing the gadget.
Pointer to requester structure containing the gadget.

Gadget

Window:
Requester:
See Also:

OnGadget ()

Enables gadget!

IOn Gadget
Syntax:

OnGadget(Gadget, Window, Requester);

-186

AO

A1

A2

struct Gadget *Gadget;

struct Window *Window;
struct Requester *Requester;

315

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Description:

Parameters:

This function makes it possible for the user to choose a previously

disabled gadget. A disabled gadget appears in ghost print. The
GADGDISABLED flag can also be unset through programming to get
the same result. The OnGadget function executes a refresh that.
applies to this gadget and any gadget following in the window list.

GOOget
Window:

Requester:
See Also:

Pointer to gadget structure.

Pointer to window structure containing the gadget.
Pointer to requester structure containing the gadget

Off Gadget ()

IRerreshGadgets
Syntax:

Redraws gadgetsl
RefreshGadgets (Gadgets, Window, Requester);
-222

AO

Al

A2

struct Gadget *Gadget;

struct Window *Window;
struct Requester *Requester;

Description:

This function redraws all of the gadgets in a window list, beginning

with the specified gadget. A window graphic may be disturbed by
drawing a new graphic, and require a gadget refresh. For example, if you
want to change a gadget's settings, you must remove the gadget from
the window with RemoveGadget () or RemoveGList () , change
your settings and re-insert the gadget in the list using AddGadget ()
or AddGList (). The gadget may not always be represented again.
Invoking RefreshGadgets () allows Intuition to redisplay the
gadget graphic.

Parameters:

Gadget.:
Window:

Requester:
See Also:

Pointer to gadget structure.

Pointer to window structure containing the gadget.
Pointer to requester structure containing the gadget

RefreshGList(),RemoveGadget(),RemoveGList(),
AddGadget(),AddGList()

IRerreshGList
Syntax:

Redraws gadget list!

RefreshGList (Gadgets, Window, Requester, Numgad);
-432

AD

Al

A2

DO

struct Gadget *Gadget;

struct Window *Window;
struct Requester *Requester;
SHORT Numgad;

Description:

316

This function redraws a certain number of gadgets in a window list,

beginning with the specified gadget. The RefreshGList function
operates in a manner similar to the RefreshGadgets function.

6.3 THE INTUITION UBRARY

ABACUS

Parameters:

o.Iget
Window:
Requester:
Numgad:

See Also:

Pointer to gadget structure.

Pointer to window StruclUre containing the gadget.
Pointer to requester structure containing the gadget.
Number of gadgets that should be redrawn. Entering a
-1 for this parameter has the same effect as selecting
RefreshGadgets (). Entering a -2 for this
parameter redraws all of the gadgets in the requester list
(applies to requester gadgets only).

RefreshGadgets (), RemoveGadget (), RemoveGList (),

AddGadget () ,AddGList ()

IRemoveGadget
Syntax:

Removes gadget from window list!

Position = RemoveGadget(Window, Gadget);
DO

-228

AO

Al

USHORT Position;
struct Window kWindow;
struct Gadget *Gadget;

Description:

This function removes the specified gadget from the window list
Gadgets that are present in a window's requester.

Parameters:

Window:

Pointer to the window containing the gadget or

Gadget

Pointer to the gadget structure that should be removed

(user must specify whether the gadget is part of a
window or requester).

requester.

Result:

Returns either the gadget's previous position or a value of -1. The -1

can mean that the gadget was not present in the list, the list has no
gadgets at all or that the 65535th gadget was removed.

See Also:

AddGadget () ,AddGList () ,RemoveGList ()

IRemoveGList
Syntax:

Removes gadgets from window list!

Position = RemoveGList (Window, Gadget, Numgad);
DO

-444

AD

Al

DO

USHORT Position;
struct Window *Window;
struct Gadget *Gadget;
SHORT Numgad

Description:

This function removes the specified number of gadgets, beginning with

the one defmed by Gadget. It defaults to the first gadget if the gadgets
are in a requester. See also RemoveGadget ( ) .

317

6. THE AMIGA LIBRARIES

Parameters:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Window:
Gadget

Numgad:

Pointer to window sbUcture containing the gadget or

requester to be removed.
Pointer to the fmt gadget to be removed.
Number of gadgets to be removed. Entering a -1 for this
parameter removes all gadgets up to the end of the
gadgetlisL

Result:

Returns either the gadget's previous position or a value of -1. The -1

can mean that the gadget was not present in the list, the list has no
gadgets at all or that the 65535th gadget was removed.

See Also:

RemoveGadget (),AddGadget (),AddGList ()

6.3.3

Menu functions

ClearMenuStri
Syntax:

Removes menu stri

from window

C1earMenuStrip(Window);
-54

AD

struct Window *Window;

Description:

This function removes the menu strip from the window. If menus are
currently being accessed,the ClearMenuStrip function executes
after the menu access ends.

Parameter:

Window:

Comments:

This function must be called before making any changes to the

structure.

See Also:

SetMenuStrip ()

Pointer to window containing the menu strip.

IItem Address
Syntax:

Returns menu item addressl

ItemAddress = ItemAddress(MenuStrip, MenuNumber);
DO

-144

AD

DO

struct Henultem *ItemAddress;

struct Menu *MenuStrip;
USHORT MenuNumber;

Description:

This function provides the pointer to a menu item's corresponding

structure. This pointer is required when you want to change a menu
item's settings.

Parameters:

MenuS trip:
Pointer to menu strip.
MenuNumber: Number of the (sub)menu item.

318

6.3 THE INTUITION LIBRARY

ABACUS

Result:

ItemAddress:

Pointer to the MenuI tern structure selected by

MenuNumber.

IOffMenu

Disables menu or menu iteml

Syntax:

OffMenu (Window, MenuNumber);

-180
AD
DO
struct Window *Window;
USHORT MenuNumber;

Description:

This function disables a menu item or entire menu. Submenu items in

a menu disabled using OffMenu are also inaccessible.

Parameters:

Window:
Pointer to window containing the menu strip.
MenuNumber: Menu/item that should be displayed in ghost print.

See Also:

OnMenu ()

IOnMenu

Enables menu or menu iteml

Syntax:

OnMenu(Window, MenuNumber);
-192
AD
DO
struct Window *Window;
USHORT MenuNumber;

Description:

This function enables a menu item or entire menu. Submenu items in a

menu enabled using OnMen u are also accessible.

Parameters:

Window:
Pointer to window containing the menu strip.
MenuNumber: Menu/item that should be enabled.

See Also:

OffMenu ()

SetMenuStri

removes menu stri

from window

Syntax:

Success = SetMenuStrip(Window, Menu);

DO
-264
AD
A1
struct Window *Window;
struct Menu *Menu;

Description:

This function adds the predefmed menu strip to the window.

Parameters:

Window:
Menu:

Result:

Success:

Pointer to window into which the menu strip should be

inserted.
Pointer to the linked list from the menu strip.
Returns TRUE if no error occurs. This result is
consistent, because the function waits until everything
executes without error.

319

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Warning:

When using a menu, make sure that a menu strip is removed from the
window before closing the window, or an error may occur.

See Also:

ClearMenuStrip()

Structures:

struct Menu <intuition/intuition.h>

(

OxOO

00

Ox04

04

Ox06
Ox08
OxOA
OxOC
OxOE
OxOF

06
08
10
12
14
18

Ox16
Ox18
Ox10
Ox12
Ox14B

22
24
26
28
30

struct Menu *NextMenu; /* Link to next menu

structure */
/* Pixel position of upper left
SHORT LeftEdge;
corner */
SHORT TopEdge;
SHORT Width;
/* Menu text width and height */
SHORT Height;
USHORT Flags;
/* Menu attribute flags */
BYTE *MenuName;
/* Pointer to menu string */
struct MenuItem *FirstItem; /* Pointer to first menu
item */
SHORT JazzX; /* Internal management values */
SHORT JazzY;
SHORT BeatX;
SHORT Beaty;

);

MENUENABLED Ox0001L /* Menu item enabled */

MIDRAWN OxOl00L
/* Menu item drawn */
struct Menultem <intuition/intuition.h>
(

OxOO

00

Ox04

04

Ox06
Ox08
OxOA
Oxoc
OxOE

06
08
10
12
14

Ox12
Ox16
OxlA

18
22
26

OxlB

27

OxlF

31

Ox21

33

struct MenuItem *NextItem; /* Link to next menu item

structure */
SHORT LeftEdge
/* Pixel position of menu item's
upper left corner*/
SHORT TopEdge;
SHORT Width;
/* Width in pixels */
SHORT Height;
/* Height in pixels */
USHORT Flags;
/* Menu attribute flags */
LONG MutualExclude; /* Exclude certain menu
items from activation */
APTR ItemFill;
/* Pointer to normal display */
APTR SelectFill; /* Pointer to selected display */
BYTE Command;
/* Keyboard character instead of menu
item */
struct MenuItem *SubItem; /* pointer to the first
submenu item in menu */
USHORT NextSelect;
/* Next menu number for
multiple select*/

);

Menultem_Flags:
CHECKIT OxOOOlL
/*
ITEMTEXT Ox0002L
/*
COMMSEQ Ox0004L
/*
MENU TOGGLE Ox0008L /*
ITEMENABLED OxOOl0L/*

320

Menu item checked

Text display only
One character for
Toggled menu item
Menu item enabled

*/
(no graphics) */
kbd shortcut */
*/
*/

6.3 THE INTUITION LIBRARY

ABACUS

HIGHFLAGS OxOOCOL
HIGH IMAGE OxOOOOL
HIGHCOMP Ox0040L
HIGHBOX Ox0080L

/*
/*
/*
/*

HIGHNONE OxOOCOL
/*
CHECKED OxOlOOL
/*
ISDRAWN OxlOOOL
/*
HIGHITEM Ox2000L
/*
MENUTOGGLED Ox4000L/*

6.3.4

All highlighting flags */

Graphic display */
Inverse menu item when selected */
Box appears around menu item
when selected */
Menu item does nothing when selected */
Checked menu item */
Drawn menu item */
Selected menu item */
Toggled menu item */

Requester and alert functions

IAutoRequest

Creates and processes requester I

Syntax:

Response = AutoRequest(Window, BodyText, PositiveText,

DO
-348
AO
Al
A2
NegativeText, PositiveFlags,
A3
DO
NegativeFlags, Width, Height);
D1
D2
03
BOOL Response;
struct Window *Window;
struct IntuiText *BodyText;
struct IntuiText *PositiveText;
struct IntuiText *NegativeText;
ULONG PositiveFlags, NegativeFlags;
SHORT Width, Height;

Description:

This function creates a requester from the available data and processes
the result selected by the user.

Parameters:

Window:

Result:

Response:

Warning:

If insufficient memory exists, this function displays an alert using

DisplayAlert () .

Pointer to window whose input channel should be

interrupted.
BodyText:
IntuiText structure for descriptive text.
PositiveText: IntuiText structure for right gadget text
NegativeText: IntuiText structure for left gadget text
PositiveFlags: IDCMP flags for display in right gadget.
NegativeFlags:
IDCMP flags for display in left gadget.
Width:
Requester window width.
Height:
Requester window height
Returns FALSE when the user clicks on the left gadget
and TRUE when the user clicks on the right gadget

321

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GVIDE

Comments:

The Workbench screen is always in the foreground when a system

requester is called.

See Also:

BuildSysRequest (),Request ()

IB uildSysRequest
Syntax:

Creates and displays requesterl

Reqwindow = BuildSysRequest(Window, BodyText, PositiveText,

~60

00

hl

NegativeText, IDCMPFlags, Width, Height);

A3

DO

02

D3

struct Window *Reqwindow;

struct Window *Window;
struct IntuiText *BodyText;
struct IntuiText *PositiveText;
struct IntuiText *NegativeText;
ULONG IDCMPFlags;
SHORT Width, Height;

Description:

This function creates a system requester borrowed by

AutoRequest () . You can also access this system requester and
create your own testing loop to access the requester.

Parameters:

Window:

Pointer to window whose input channel should be

interrupted.
BodyText:
IntuiText structure for descriptive text.
PositiveText: IntuiText structure for right gadget text
NegativeText: IntuiText structure for left gadget text
IDCMPFlags: IDCMP flags for requester window.
Width:
Requester window width.
Height:
Requester window height

Result:

ReqWindow:

Warning:

If insufficient memory exists, this function displays an alert using

DisplayAlert () .

Comments:

Requester gadgets are distinguishable by their IDs: FALSE and TRUE.

Both gadgets have the attributes BOOLGADGET, RELVERIFY,
REQGADGET, and TOGGLESELECT.

See Also:

AutoRequest (),FreeSysRequest(),DisplayAlert (),

ModifyIDCMP ()

Pointer to the requester window.

ClearDMRe uest
Syntax:

Removes double

Response
DO

ClearDMRequest(Window);
-48

BOOL Response;
struct Window *Window;

322

AO

ABACUS

6.3 THE INTUITION LIBRARY

Description:

This function clears a double menu request previously set using

SetDMRequest ( )

Parameter:

Window:

Pointer to window containing defined double menu

request.

Result:

Response:

Returns TRUE if requester is removed and inaccessible,

and FALSE in any other cases.

See Also:

SetDMRequest (), Request ()

IDisplayAlert

Creates and displays alert!

Syntax:

Response = DisplayAlert(AlertNumber, String, Height);

DO
-90
DO
AD
Al
BOOL Response;
ULONG AlertNumber;
UBYTE *String;
SHORT Height;

Description:

This function displays an alert, moving the screen down by the

specified number of lines.

Parameters:

AlertNumber: LONG value number displayed in alert box (highest bit

of number displayed only).
String:
Pointer to string to be displayed in alert box.
Height:
Height of alert box in screen lines.

Result:

Response:

Warning:

If the system crashes completely it changes the ALERT_TYPE into a

Returns FALSE after DEAD END ALERT. If a

RECOVER_ALERT occurs, then the user selection of a
mouse button dictates the response: TRUE for the left
mouse button, and FALSE for the right mouse button.

DEADEND_ALERT.

The DEADEND_ALERT can only be resolved by a

system reset.

uest

Removes re

Syntax:

EndRequest(Requester, Window);
-120
AD
Al
struct Requester *Requester;
struct Window *Window;

Description:

This function removes the specified requester from the window, and sets
the window's status to normal if this was the last requester in a group.

Parameters:

Requester:
Window:

Pointer to requester structure.

Pointer to window containing the requester.

323

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Releases memory allocated by request!

IFreeSYSRequest
Syntax:

FreeSysRequest(Window);
-372
AO
struct Window *Window;.

Description:

This function ends a requester added by Intuition and managed by the

program. It also releases any memory allocated by Intuition.

Parameter:

Window:

See Also:

BuildSysRequest(),AutoRequest()

uester

Pointer to a window used in BuildSysRequest ()

function.

Allocates a re uester with

eneral values

Syntax:

InitRequester(Requester);
-138
AO
struct Requester *Requester;

Description:

This function removes a requester structure and sets the necessary

values to zero.

Parameter:

Requester:

See AlSO:

Request (),EndRequest ()

StructureS:

struct Requester <intuition/intuition.h>

Pointer to requester structure.

324

OxOO

00

Ox04

04

Ox06
Ox08
OxOA
OxOC

06
08
10
12

OxOE
Ox10

14
16

Ox14

20

Ox18

24

Ox1C
Ox1E
Ox20

28
30
32

Ox24
Ox44

36
68

Ox48

72

struct Requester *OlderRequester

/* Internal pointer
to previous
requester */
SHORT LeftEdge; /* Upper left pixel position of
requester in window */
SHORT TopEdge;
SHORT Width;
/* Requester width in pixels */
SHORT Height;
/* Requester height in pixels */
SHORT RelLeft; /* Relative coordinates with a
relative position statement to
mouse pointer */
SHORT RelTop;
struct Gadget *ReqGadget; /* Pointer to first
requester gadget */
struct Border *ReqBorder; /* Pointer to first
requester border */
struct IntuiText *ReqText;/* Pointer to first
requester text */
USHORT Flags;
/* Flag settings for this requester */
UBYTE Backfill;
/* Requester background color */
struct Layer *ReqLayer;
/* Pointer to layer
structure managed by the
requester * /
UBYTE ReqPad1 [32];
/* More memory bytes * /
struct Bitmap *ImageBMapi /* Pointer to requester
bit-map */
struct Window *RWindow;
/* Pointer to window in

ABACUS

6.3 THE INTUITION LIBRARY

Ox4c
Ox70

76 UBYTE ReqPad2[36];
112

which the requester

appears */
/* More memory bytes * /

};

Requester_Flags:
POINTREL OxOOOIL
PREDRAWN Ox0002L
NOISYREQ Ox0004L
REQOFFWINDOW OxIOOOL
REQACTlVE Ox2000L
SYSREQUEST Ox4000L
DEFERREFRESH Ox8000L

/* Requester appears relative to the mouse

pointer */
/*
/*
/*
/*

Not a system requester */

Requester exists outside window */
Active requester */
Handle as system requester */

IRequest

Activates requesterl

Syntax:

Success = Request (Requester, Window);

DO
-240
AO
Al
BOOL Success;
struct Requester *Requester;
struct Window *Window;

Description:

This function opens a predefined requester in the given window.

Parameters:

Requester:
Window:

Pointer to requester.
Pointer to window whose input channel is interrupted.

Result:

Success:

Returns TRUE if the requester can be opened as usual,

and FALSE in any other case.

Comments:

The POINTREL requester is not currently implemented, but the double

menu requesters operate.

See Also:

EndRequest ()

ISetDMRequest

Determines DMRequest for windowl

Syntax:

Success = SetDMRequest (Window, DMRequester);

-258
AO
Al
BOOL Success;
struct Window *Window;
struct Requester *DMRequester;

Description:

This function defines the double menu requester (a requester which

requires a double-click). If a double menu requester is already defmed and
active, the function does not execute. You must then access
ClearDMRequest () until TRUE is returned.

Parameters:

Window:

Pointer to window in which DMRequest should be

defined.

325

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

DMRequester: Pointer to request structure representing DMRequest

Returns 1RUE if no requester was in use, FALSE if a
requester is in use.

Result:

Success:

See Also:

ClearDMRequest(),Request(),EndRequest()

6.3.5

Screen functions

ICloseScreen
Syntax:

Closes Intuition screenl

CloseScreen(Screen);
-66

AO

struct Screen *Screen;

Description:

This function closes the specified screen and frees bit-map memory and
any parameters used by openScreen ( ) .

Parameter:

Screen:

Warning:

CloseScreen does not affect open windows, requesters or menus.

Make sure that any windows, requesters and menus are closed before
invoking CloseScreen.

Comment:

If the screen closed was the last screen, Intuition tries to open the

Pointer to screen structure.

Workbench screen.
See Also:

OpenScreen ()

ICloseWorkbench

Closes Workbenchl

Syntax:

Success = CloseWorkBench();
DO
-78
BOOL Success;

Description:

This function closes the Workbench screen.

Result:

Success:

Exceptions:

If a window from a program is found on the Workbench screen, this

window remains open.

Warning:

Be aware of the fact that the control is taken from a program because by
closing this screen you have pulled the "floor from under your feet".

326

Returns 1RUE if the Workbench can be closed and

FALSE if it cannot be closed.

6.3

ABACUS

See Also:

THE INTUITION LIBRARY

OpenWorkbench(),CloseScreen()

IDisplayBeep

Blinks screenl

Syntax:

DisplayBeep(Screen);
-96
AO
struct Screen *Screen;

Description:

This function blinks the specified screen.

Parameter:

Screen:

Exceptions:

If zero is given as the screen pointer, all available screens blink.

Pointer to screen structure.

GetScreenData

Gets screen information

Syntax:

Success = GetScreenData (Buffer, Size, Type, Screen);

-426
AO
DO
Dl
A1
BOOL Success;
CPTR Buffer;
USHORT Size;
USHORT Type;
struct Screen *Screen;

Description:

This function gets screen structure data and places the data in a buffer.

Parameters:

BufftT.
Size:
Type:
Screen:

Result:

Returns TRUE if no error occurs and FALSE if the screen cannot be

acce&<led.

Exceptions:

No pointer is needed for the Workbench screen. This is opened if it was

previously closed.

MakeScreen

Pointer to buffer.
Data buffer size.
Type of screen (WBENCHSCREEN, CUSTOMSCREEN).
Pointer to screen structure.

Executes Intuition inte rated MakeVPort

Syntax:

MakeScreen(Screen);
-378
AO
struct Screen *Screen;

Description:

This function executes a MakeVPort () of a custom screen through

Intuition.

Parameter:

Screen:

See Also:

RethinkDisplay(),RemakeDisplay()

Pointer to screen structure.

327

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Moves the screen by given delta!

!MoveScreen
Syntax:

MoveScreen(Screen, DeltaX, DeltaY);

-162
AO
DO
D1
struct Screen *Screen;
SHORT DeltaX, DeltaY;

Description:

This function moves the screen by the specified delta values. The
distance is relative to the current location rather than by absolute

coordinates.
Parameters:

Screen:

Pointer to screen.
Horizontal movement value.
Vertical movement value.

DeltaX:
DeltaY:
Exceptions:

In the current version of the operating system the screen can only be
moved in the vertical direction. For compatibility reasons the De 1 t aX
value should always be set to zero.

! Open Screen

Opens Intuition screen!

Syntax:

Screen = OpenScreen(NewScreen);
DO
-198
AO
struct Screen *Screen;
struct NewScreen *NewScreen;

Description:

This function opens a new screen from the NewScreen structure. It

supplies the pointer to an added screen structure. Other operations can
be done with this pointer.

Parameter:

NewScreen:

Pointer to NewScreen structure.

Result:

Screen:

Pointer to the newly added screen structure.

See Also:

CloseScreen(),MakeScreen()
struct NewScreen <intuition/intuition.h>
{

328

OxOO

00

SHORT LeftEdge;

Ox02

02

SHORT TopEdge;

Ox04
Ox06
Ox08

04
06
08

SHORT Width;
SHORT Height;
SHORT Depth;

OxOA
OxOB
OxOC
OxOE
Ox10
Ox14

10

Ox18

24

11

12
14
16
20

/* left border of screen relative to

the View (not used) */
/* Top of screen relative to the
View */
/* Screen width and height */

/* Screen depth (changes with color

number) */
UBYTE DetailPen; /* Detail pen color number */
UBYTE BlockPen;
/* Block pen color number */
USHORT ViewModes; /* View mode flags */
USHORT Type; /* Screen type (Workbench/Custom) */
struct TextAttr *Font; /* Pointer to screen font */
UBYTE *DefaultTitle;
/* Pointer to default screen
title */
struct Gadget *Gadgets; /* Pointer to screen gadgets

ABACUS

6.3 THE INTUITION LIBRARY

OxIC

28

Ox20

32

(not used) */
struct Bitmap *CUstomBitmap; /* Pointer to added
screen bit-map */

};

struct Screen <intuition/intuition.h>

(

OxOOO

00

struct Screen *NextScreen;

/* Pointer next screen's

list */
Ox004 04 struct Window *FirstWindow; /* Pointer to screen's
first window */
Ox008 08 SHORT LeftEdge; /* Left border relative to the View
(not used) */
OxOOA 10 SHORT TopEdge; /* Top border relative to the View */
OxOOC 12 SHORT Width; /* Screen width and height in pixels */
OxOOE 14 SHORT Height;
Ox010 16 SHORT MouseY; /* Mouse coordinates on screen */
Ox012 18 SHORT MouseX;
Ox014 20 USHORT Flags; /* Screen flags */
Ox016 22 UBYTE *Title; /* Pointer to screen title text as a
string */
Ox01A 26 UBYTE *DefaultTitle; /* Pointer to default title
text */
Ox01E 30 BYTE BarHeight;
/* Height of the title bar in
pixels */
Ox01F 31 BYTE BarVBorder;
/* Vertical width of title bar
border */
Ox020 32 BYTE BarHBorder;
/* Horizontal border width */
Ox021 33 BYTE MenuVBorder;
/* Menu border width of
(vertical/horizontal) */
Ox022 34 BYTE MenuHBorder;
Ox023 35 BYTE WBorTop;
/* Window border width (top) */
Ox024 36 BYTE WBorLeft;
/* (left) */
Ox025 37 BYTE WBorRight; /* (right) */
Ox026 38 BYTE WBorBottom; /* (bottom) */
Ox028 40 struct TextAttr *Font;
/* Pointer to screen font */
Ox02C 44 struct ViewPort ViewPort; /* Pointer to ViewPort */
Ox054 84 struct RastPort RastPort; /* Connecting the RastPort
structure */
OxOB8 184 struct Bitmap Bitmap;
/* Connecting the bit-map
structure */
OxOEO 224 struct Layer_Info LayerInfo; /* Connecting the
layerinfo structure */
Ox13C 316 struct Gadget *FirstGadget; /* Pointer to first
screen gadget (not
supported) * /
Ox140 320 UBYTE DetailPen
/* Detail pen color number */
Ox141 321 UBYTE BlockPen;
/* Block pen color number */
Ox142 322 USHORT SaveColorO; /* Buffer memory for screen color
o when blinking */
Ox144 324 struct Layer *BarLayer;/* Pointer to title bar layer
when presenting the menu item */
/* Pointer to more data
Ox148 328 UBYTE *ExtData;
(Expansion) * /
Ox14C 332 UBYTE *UserData;
/* Pointer to user data of
this screen */
Ox150 336
};

329

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

SCREENTYFE OxOOOFL
WBENCHSCREEN Ox0001L
CUSTOMSCREEN OxOOOFL
SHOWTITLE Ox0010L
BEEPING Ox0020L
CUSTOMBITMAP Ox0040L
SCREENBEHINO OxOOBOL
SCREENQUIET Ox0100L
STDSCREENHEIGHT -1L

/*
/*
/*
/*
/*

workbench screen 10*/

Every other screen is a CustomScreen */
Title bar drawn */
Screen blinks */
User bit-map */
/* Screen opens behind all others */
/* Screen has no gadgets/menu strip */
/* Default screen height (200 pixels) */

IOpenWorkBench

Opens Workbenchl

Syntax:

WBScreen = OpenWorkBench();
DO
-210
struct Screen *WBScreen;

Description:

This function opens the Workbench screen and displays all Workbench
icons and windows.

Result:

WBScreen:

Exception:

Returns FALSE if not enough memory exists.

Warning:

Avoid using the pointer, because the Workbench screen can be affected
or even closed by external programs.

See Also:

CloseWorkBench ( ) ,OpenScreen () , CloseScreen ()

Pointer to Workbench screen structure.

IScreenToBack

Moves screen to backgroundl

Syntax:

ScreenToBack (Screen) ;
-246
AD
struct Screen *Screen;

Description:

This function places the screen of the given screen structure in the

background.
Parnmeter:

Screen:

See Also:

ScreenToFront(),WBenchToBack(),WBenchToFront()

Pointer to screen structure.

ScreenToFront
Syntax:

ScreenToFront(Screen);
-252
AD
struct Screen *Screen;

Description:

This function places the screen of the given screen structure in the

foreground.

330

6.3

ABACUS

THE INTUITION UBRARY

Parameter:

Screen:

See Also:

ScreenToBack(),WBenchToBack(),WBenchToFront()

Pointer to screen structure.

IShowTitie

Sets screen title bar displayl

Syntax:

ShowTitle(Screen, Showlt)
-282
AO
DO
struct Screen *Screen;
BOOL Showlt;

Description:

This function sets the display mode of the screen title bar. The screen
title bar covered by a BACKDROP window can be placed in front of or
behind the window.

Parameters:

Screen:
Showlt:

Pointer to screen structure.

Returns lRUE for overlay and FALSE for not drawing.

IWBenchToBack
Syntax:

Moves Workbench to backgroundl

WBenchToBack () ;
-336

Description:

This function places the Workbench behind all other screens.

Comments:

The function can be called by pressing the <right Amiga><M> key

combination.

See Also:

WBenchToFront () , ScreenToBack () , ScreenToF ront ()

IWBenchToFront

Moves Workbench to foreground I

Syntax:

WBenchToFront();
-342

Description:

This function places the Workbench in front of all other screens.

Comments:

Invoking a requester or pressing <right Amiga><N> executes this

function.

See Also:

WBenchToBack(),ScreenToBack(),ScreenToFront()

331

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

6.3.6

Graphic functions

IClearPointer

Clears mouse pointer

Syntax:

ClearPointer (Window) ;
-60
AO
struct Window *Window;

Description:

This function clears the custom mouse pointer from the window. After
the call the mouse cursor appears as set under Preferences.

Parameter:

Window:

See Also:

SetPointer ()

Pointer to the window in which the mouse pointer

should be changed to the default graphic.

DrawBorder

Draws border structure in RastPort

Syntax:

DrawBorder{RastPort, Border, LeftOffset, RightOffset);

-108
AO
Al
DO
D1
struct RastPort *RastPort;
struct Border *Border;
SHORT LeftOffset, RightOffset;

Description:

This function draws the given lines in the RastPort at the position
specified by the offsets. If the NextBorder array of the structure
contains more data, these lines are also drawn.

Parameters:

RastPort:
Boob:
LeftOffset
TopOffset

See Also:

Drawlmage(),PrintIText()

Structure:

struct Border <intuition/intuition.h>

Pointer to RastPort to receive the new border.

Border structure derIDing lines.
Offset value added to each X coordinate.
Offset value added to each Y coordinate.

OxOO

00

SHORT LeftEdge

Ox02
Ox04
OxOS
Ox06
Ox07
Ox08
OxOC

02
04
05
06
07
08
12

SHORT TopEdge;
UBYTE FrontPen /* Line drawing color */
UBYTE BackPen; /* Not used */
UBYTE DrawMode; /* Draw mode=JAMl */
BYTE Count;
/* Number of coordinate pairs */
SHORT *XY;
/* Coordinate table pointer to */
struct Border *NextBorder; /* Link to other
border structures */

Ox10

16

);

332

/* Pixel position of border

relative to the RastPort */

ABACUS

6.3 THE INTUITION LIBRARY

IDrawlmage

Draws image in RastPort!

Syntax:

DrawImage(RastPort, Image, LeftOffset, TopOffset);

-114
AO
A1
DO
D1
struct RastPort *RastPort;
struct Image *Image;
SHORT LeftOffset, TopOffset;

Description:

This function draws the given image in the RastPort at the position
specified by the offsets. If the Next Image array contains more data,
these images are also drawn.

Parameters:

RastPort:
Image:
LeftOffset:
TopOffset

See Also:

DrawBorder(),PrintIText()

Structure:

struct Image <intuition/intuition.h>

Pointer to RastPort to receive the new image.

Image structure deftning image.
Offset value added to each X coordinate.
Offset value added to each Y coordinate.

1* Pixel position of the graphic

relative to the RastPort *1

OxOO

00

SHORT LeftEdge;

Ox02
Ox04
Ox06
Ox08
OxOA
OxOE

02
04
06
08
10
14

OxOF

15

Ox10

16

SHORT TopEdge;
SHORT Width; 1* Graphic width and height in pixels *1
SHORT Height;
SHORT Depth;
1* depth of graphic bit-planes *1
USHORT *ImageData; 1* Pointer to image data *1
UBYTE PlanePick
1* Marking bit-planes
for picking *1
UBYTE PlaneOnOff; 1* Marking bit-planes for
turning off *1
struct Image *Nextlmage; 1* Link to more image
structures *1

Ox14

20

};

hn tuiTextLength

Returns pixel width

or

an IntuiText!

Syntax:

Width = IntuiTextLength(IText);
-330
DO
USHORT Width;
struct IntuiText *IText;

Description:

This function calculates the pixel width of an I n t u i T ext,

independently of the given character set

Parameter:

IText:

Pointer to Int ui Text structure.

Result:

Width:

Text width in pixels.

See Also:

PrintIText ()

333

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Writes text in RastPortl

IPrintIText
Syntax:

PrintIText(RastPort, IText, LeftOffset, TopOffset);

-216
AO
Al
DO
01
struct RastPort *RastPort;
struct IntuiText *IText;
SHORT LeftOffset, TopOffset;

Description:

This function writes the text of the IntuiText structure in the given
RastPort at the position specified through the offsets. If the
Next Text array contains more data, this data is also written.

Parameters:

RastPort:
IText:
LeftOffset:
TopOffset:

See Also:

IntuiTextLength(),DrawBorder(),Drawlmage()

Structure:

struct Intui Text <intuition/intuition .h>

OxOO

00

Ox01

01

Ox02

02

Ox04

04

Ox06
Ox08

06
08

OxOC
Ox10

12
16

Ox14

20

Pointer to RastPort to receive the new image.

Int ui Text structure containing the text.
Offset value added to each X coordinate.
Offset value added to each Y coordinate.

UBYTE FrontPen; /* Number of foreground drawing

color */
UBYTE BackPen; /* Number of background drawing
color */
UBYTE OrawMode; /* Draw mode: JAMl, JAM2,
COMPLEMENT, INVERSEVID */
SHORT LeftEdge; /* Pixel position of text relative to
RastPort */
SHORT TopEdge;
struct TextAttr *ITextFont; /* Pointer to character
set: Null = default */
UBYTE *IText;
/* Pointer to string */
struct IntuiText *NextText; /* Link to additional
IntuiText structures */

);

SetPointer

Defines custom mouse

ointer for window

Syntax:

SetPointer(Window, Pointer, Height, Width, XOffset, YOffset);

-270
AD
Al
DO
01
02
03
struct Window *Window;
USHORT *Pointer;
SHORT Height, Width;
SHORT XOffset, YOffset;

Description:

This function defines a custom mouse pointer for the given window.
This is always represented when the window is active. The offsets
specify the pointer's position and hot spot.

334

,.3

ABACUS

Parameters:

Window:
Pointer:
Height:
Width:
XOffset:
YOffset:

See Also:

ClearPointer ( )

6.3.7

Memory functions

THE INTUITION LIBRARY

Pointer to window structure.

Pointer to the mouse pointer sprite data.
Sprite height data.
Sprite width data =16).
X offset of sprite's hot spot.
Y offset of sprite's hot spot.

IAlIocRemember

Allocates memoryl

Syntax:

MemBlock = AllocRemember(RememberKey, Size, Flags);

DO
-396
AO
DO
01
CPTR MemB1ock;
struct Remember *RememberKey;
ULONG Size;
ULONG Flags;

Description:

This function allocates memory using the AllocMem () function of

the Exec library. In addition, it manages a list which allows easy
release of all allocated memory.

Parameters:

RememberKey:
Pointer to Remembe r structure. The pointer must be
set to zero on the initial call.
Memory block size.
Attributes of the desired memory block.

Size:
Flags:
Result:

MemBlock:

See Also:

FreeRemember (), AllocMem () , FreeMem ()

Structure:

struct Remember <intuition/intuition.h>

Returns the pointer to the desired memory block, or

zero if the function cannot be executed.

OxOO

00

Ox04
OxOB
OxOC

04
OB
12

struct Remember *NextRemember;/* Pointer to next

remember structure */
ULONG RememberSize; /* Memory range size */
UBYTE *Memory;
/* Pointer to memory range */

};

335

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

frees the noted memor

FreeRemember

in the list

Syntax:

FreeRemember(RememberKey, ReallyForget);
-408
AO
DO
struct Remember *RememberKey;
BOOL ReallyForget;

Description:

This function frees all of the memory regions that are entered in the
Link_list from RememberKey. You can also clear the
RememberKey structure through this function.

Parameters:

RememberKey:
Pointer to first remember structure of a list.
ReallyForget: Tests for release of just the structure or just the
memory range. TRUE releases both the memory and
the structure.

See Also:

AllocRemember (). AllocMem () FreeMem ()

6.3 8

Refresh functions

!BeginRefresh

Sets a window for optimum refreshl

Syntax:

BeginRefresh (Window) ;
-354
AO
struct Window *Window;

Description:

This routine prepares the given window for redrawing only in areas that
require refresh.

Parameter:

Window:

See Also:

EndRefresh ()

Pointer to the window.

!EndRefresh

Disables optimum refreshl

Syntax:

EndRefresh(Window, Complete);
-366
AO
DO
struct Window *Window;
BOOL Complete;

Description:

This window disables the status enabled by BeginRefresh.

Parameters:

Window:
Complete:

Pointer to the window containing the BeginRefresh

status.
Truth value that describes whether the refresh can be

released.

336

6.3 THE INTUITION UBRARY

ABACUS

See Also:

BeginRefresh ()

RemakeDis la

Redraws entire Intuition dis la

Syntax:

RemakeDispIay ()

-384

Description:

This function calls MakeScreen () and Rethinkdisplay () for

all screens, redrawing all display elements conb'olled through Intuition.

Warning:

This function can take some time to execute-use this function

sparingly. If RethinkDisplay () ,Forbid () and Permit () are
called several times, the multitasking system may slow down radically.

See Also:

MakeScreen () , RethinkDisplay () ,MakeVPort ()

IRethinkDisplay
Syntax:

Redraws Intuition displayl

RethinkDispIay ()

-390

Description:

This function works through all of the ViewPorts and selects the error,
corrects it and re-initializes the Copper lists.

Warning:

This function can take some time to execute-use this function

sparingly. If RethinkDisplay (), Forbid() and Permit () are
called several times, the multitasking system may slow down radically.

See Also:

RemakeDisplay () ,MakeVPorty () ,MakeScreen ()

6.3.9

Other functions

CurrentTime
Syntax:

Returns current time value

CurrentTime (Second, Micros);

-84

AD

Al

ULONG *Seconds, *Micros;

Description:

This function copies the current values of the system time into the
specified memory locations. This time is correct about 60 times per
second.

Parameters:

Seconds:
Micros:

Pointer to a LONG variable into which the seconds are

entered.
Pointer to a LONG variable into which the
microseconds are entered.

337

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DoubleClick

Tests for two clicks within a time s an

Syntax:

Is = DoubleClick(StartSecs, StartMicros, CurrentSecs,

DO
-102
DO
D1
D2
CurrentMicros) ;
D3
B<XlL IsDoub1e;
LONG StartSecs, StartMicros;
LONG CurrentSecs, CurrentMicros;

Description:

This function tests whether two clicks occur within the time span
specifIed under Preferences.

Parameters:

Time of the frrst click in seconds.

StartSecs:
StartMicros: Time of the frrst click in microseconds.
CurrentSecs: Time of the second click in seconds.
CurrentMicros:
Time of the second click in microseconds.

Result:

IsDouble:

See Also:

Current Time ()

GetDefPrefs

Returns TRUE if the time span corresponds to a

double-click.

Co ies Preferences settin s to buffer

Syntax:

Prefs = GetDefPrefs(PrefBuffer, Size);

DO
-126
AO
DO
struct Preferences *Prefs;
struct Preferences *PrefBuffer;
SHORT Size;

Description:

This function copies the default values from Preferences into the
specified buffer. These are the values set when the system is started.
Other values are searched for on the disk when it is frrst booted.

Parameters:

Preffiuffer:
Size:

Pointer to Preferences data buffer.

Buffer size.

Result:

Prefs:

Pointer to the buffer in which the data is placed (usually

the same as the Preferences buffer).

See Also:

GetPrefs ()

GetPrefs
Syntax:

338

Returns current Preferences settin s

Prefs = GetPrefs(PrefBuffer, Size);
DO
-132
AO
DO
struct Preferences *Prefs;
struct Preferences *PrefBuffer;
SHORT Size;

6.3

ABACUS

THE INTUITION UBRARY

Description:

This function copies the settings from Preferences into the given
buffer. These are the values set by the user through the Preferences
program.

Parameters:

PrefBuffer:
Size:

Pointer to Preferences data buffer.

Buffer size.

Result:

Prefs:

Pointer to the buffer in which the data is placed (usually

the same as the Preferences buffer).

See Also:

GetPrefs ()

Structure:

struct Preferences <intuition/intuition.h>

{

OxOO

00

OxOl

01

Ox02
Ox04

02
04

OxOC

12

Ox14

20

OxIC

28

Ox64
Ox65
Ox66
Ox68
Ox6A
Ox6C
Ox6E
Ox70
Ox72
Ox74
Ox76

100
101
102
104
106
108
110
112
114
116
118

Ox77 119
Ox78 120
Ox7A
Ox7C
Ox7E
Ox80

122
124
126
128

Ox9E 158
OxAO 160
0xA2 162
OxA4 164
OxA6 166
OxA8 168
OxAA 170

BYTE FontHeight;

/* character set: 60 or 80
characters */
UBYTE PrinterPort; /* PrinterPort: serial or
parallel */
USHORT BaudRate; /* BaudRate: bet ween 11 0 and 19200 */
struct timeval KeyRptSpeed; /* Keyboard repeat
speed */
struct timeval KeyRptDelay; /* Delay time until a
key repeat * /
struct timeval DoubleClick; /* Double-click
time interval */
USHORT PointerMatrix[36LJ; /* Mouse pointer graphic
data */
BYTE XOffset;
/* Hot spot offset */
BYTE YOffset;
USHORT color17;
/* Mouse pointer colors */
USHORT color18;
USHORT color19;
/* Mouse movement conversion */
USHORT PointerTicks;
USHORT colorO;
/* Workbench colors */
USHORT color1;
USHORT color2;
USHORT color3;
BYTE ViewXOffset;
/* Relative position of the
Workbench screen to the View */
BYTE ViewYOffset;
WORD ViewlnitX;
/* Initialization values for the
View */
WORD ViewlnitY;
BOOL EnableCLI;
/* Enable/disable CLI */
USHORT PrinterType;
/* Printer type */
UBYTE PrinterFilename[30LJ; /* Name of the printer
with CUSTOM */
USHORT PrintPitch;
/* Kind of type: Pica, Elite,
Fine */
/* Print quality: Draft, NLQ */
USHORT PrintQuality;
/* Print spacing: 6 LPI or 8
USHORT PrintSpacing;
LPI */
UWORD PrintLeftMargin; /* Left and right print
margin */
UWORD PrintRightMargin;
USHORT Printlmage;
/* Positive or negative graphic
imaging */
USHORT PrintAspect;
/* Print aspect: horizontal,
vertical */

339

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

OxAC 172

USHORT PrintShade;

OxAE
OxBO
OxB2
OxB4

WORD Print Threshold;

USHORT PaperSize;
UWORD PaperLength;
USHORT PaperType;

174
176
178
180

OxB6 182

UBYTE SerRWBits;

OxB7 183

UBYTE SerStopBuf;

OxB8 184
OxB9 185

UBYTE SerParShk;
UBYTE LaceWS;

OxBA 186

UBYTE WorkName[30Ll;

OxDS
OxD9
OxDA
OxDC
OxDE
OxEO
OxE1
OxE2

BYTE RowSizeChange;
BYTE ColumnSizeChange; /* Final Version 1.2 */
UWORD PrintFlags;
/* New graphic settings */
UWORD PrintMaxWidth;
UWORD PrintMaxHeight;
UBYTE Print Density;
UBYTE PrintXOffset;
/* Workbench width, height,
UWORD wb_Width;
depth */
UWORD wb_Height;
UBYTE wb_Depth;
/* Version 1.3 */
UBYTE ext_size;
/* Length of an integrated
expansion */

216
217
218
220
222
224
225
226

OxE4 228
OxE6 230
OxE7 231
OxES 232
};

Preferences_FontHeight:
TOPAZ__EIGHTY 8L
TOPAZ SIXTY 9L

Preferences LaceWB:
LACEWB Ox01L

Preferences_PrinterPort:
PARALLEL PRINTER OxOOL
SERIAL PRINTER Ox01L

Preferences_BaudRate:
BAUD 110 OxOOL
BAUD-300 OxOlL
BAUD 1200 Ox02L
BAUD-2400 Ox03L
BAUD 4800 Ox04L
BAUD 9600 Ox05L
BAUD 19200 Ox06L
BAUD MIDI Ox07L

340

/* Print type: black/white,

gray shade, color */
/* Gray scaling */
/* Paper size: Flags */
/* Paper length in lines */
/* Paper type: continuous feed,
single sheet */
/* Serial settings:
Read/Write Bits */
/* number of stop bits, buffer
size */
/* Parity and Shake */
/* Interlace Mode:
on, off */
/* Buffer storage of
printer name */

6.3

ABACUS

THE INTUITION LIBRARY

Preferences_PaperType:
FANFOLD OxOOL
SINGLE Ox80L

Preferences PrintPitch:
PICA OxOOOL
ELITE Ox400L
FINE Ox800L

Preferences_PrintQuality:
DRAFT OxOOOL
LETTER Oxl00L

Preferences_PrintSpacinq:
SIX LPI OxOOOL
EIGHT LPI Ox200L

Preferences_Printlmaqe:
IMAGE POSITIVE OxOOL
IMAGE-NEGATIVE Ox01L

Preferences_PrintAspect:
ASPECT HORIZ OxOOL
ASPECT-VERT Ox01L

Preferences PrintShade:
SHADE BW OxOOL
SHADE GREYSCALE OxOlL
SHADE COLOR Ox02L

Preferences_PaperSize:
US LETTER OxOOL
US-LEGAL Oxl0L
N TRACTOR Ox20L
W-TRACTOR Ox30L
CUSTOM Ox40L

Preferences_PrinterType:
CUSTOM NAME OxOOL
ALPHA P 101 OxOlL
BROTHER-15XL Ox02L
CBM MPSIOOO Ox03L
DIAB 630 Ox04L
DIAB- AnV D25 Ox05L
DIAB-C 150 Ox06L
EPSON Ox07L
EPSON JX 80 OxOeL
OKIMATE 20 Ox09L

341

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

QUME LP 20 OxOAL
HP rAsERJET OxOBL
HP- LASERJET PLUS OxOCL

Preference. SerialBuffer:
SBUF 512 OxOOL
SBUF-1024 Ox01L
SBUF-2048 Ox02L
SBUF-4096 Ox03L
SBUF--8000 Ox04L
SBUF--16000 Ox05L

Preference. SerRWBit.:
SREAD BITS OxFOL
SWRITE BITS OxOFL

Preference._SerStopBuf:
SSTOP BITS OxFOL
SBUFSIZE BITS OxOFL
Preferences SerParShk
SPARrTY BITS OxFOL
SPARITY NONE OL
SPARITY EVEN 1L
SPARITY-ODD 2L
SHSHAKE-XON OL
SHSHAKE RTS lL
SHSHAKE-NONE 2L

ILockIBase

Returns an Intuition lockl

Syntax:

Lock = LockIBase(LockNumber);
DO
-414
DO
ULONG Lock;
ULONG LockNumber;

Description:

This function locks the entire Intuition system. The function is called
from Intuition by any elementary change made to structures.

Parameter:

LockNumber: Number of the lock. A value of zero indicates a lock

that frees all of the elements for searching.

Result:

Lock:

Warning:

The entire Intuition system waits until UnlockIBase () is called.

Comments:

This function cannot be called if another lock is currently executing

Lock number used by UnlockIbase () .

(LayerInfo).
See Also:

342

UnlockIBAse(),LockLayerInfo(),ObtainSemaphore()

6.3 THE INTUITION LIBRARY

ABACUS

IReportMouse
Syntax:

Toggles mouse movement reportsl

ReportMouse (Boolean, Window);
-234

AO

DO

BOOL Boolean;
struct Window *Window;

Description:

Parameters:

This function toggles the REPORTMOUSE flag contained in the

window's IDCMP. If the mouse clicks on a gadget, this sets the
FOLLOWMOUSE flag.
Window:

Boolean:
Exceptions:

Pointer to the window.

Truth value which differentiates whether the flag should
be set (TRUE) or cleared (FALSE).

The AZTEC C compiler calls the function using the syntax

ReportMouse(Window, (ULONG)Boolean);.

ISetPrers
Syntax:

Sets Prererencesl
Prefs = SetPrefs(PrefBuffer, Size, Inform);
DO

-324

AO

DO

Dl

struct Preferences *Prefs;

struct Preferences *PrefBuffer;
int Size;
BOOL Inform;

Description:

This function copies the given number of bytes of the Preference

structure into the system preferences table. Inform can add other
items if NEWPREFS informs the program of this.

Parameters:

PretBuffer:
Size:
Inform:

Pointer to the buffer that contains the new data.

Number of bytes that should be copied.
Truth value which differentiates if NEWPREF S is set
(TRUE) or cleared (FALSE).

Result:

Prefs:

Pointer to the data buffer.

See Also:

GetDefPrefs (). GetP refs ()

IUnlockIBase
Syntax:

Frees Intuition lockl

UnlockIBase (Lock);
-420

AO

ULONG Lock;

Description:

This function frees the lock actuated using LockIBase () .

Parameter:

Lock:

Warning:

If you try to free a lock that that doesn't exist, the system crashes.

Value returned by LockIBase ()

343

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

See Also:

LockIBase ()

IView Address

Supplies View structure addressl

Syntax:

Address = ViewAddress();
-294
struct View *Address;

Description:

This function returns the pointer to the View, needed for every graphic
operation.

Result:

Adcb:ess:

IViewPortAddress

Intuition View address.

Supplies ViewPort structure address

Syntax:

Address = ViewPortAddress(Window);
-300
AO
struct View *Address;
struct Window *Window;.

Description:

This function returns the pointer to the ViewPort, needed for every
graphic operation performed within a window.

Parameter:

Window:

Pointer to a window structure.

Result:

Address:

ViewPort address of this window.

More Intuition Structures:

struct IntuiMessage <intuition/intuition.h>
(

344

OxOO

00

Ox14
Ox18
OxlA
OxlC

20
24
26
28

Ox20

32

Ox22
Ox24
Ox28
Ox2C

34
36

Ox30

48

Ox34

52

40
44

struct Message ExecMessage; /* ExecMessage structure

integration */
ULONG Class;
/* Report classification */
USHORT Code;
/* used for more values */
USHORT Qualifier; /* Identifies the keyboard plane */
APTR IAddress;
/* Pointer to an Intuition object
released by the report */
SHORT MouseX;
/* Current mouse position in
pixels, relative to the
window */
SHORT MouseY;
/* Clock time of report */
ULONG Seconds;
ULONG Micros;
struct Window *IDCMPWindow;
/* Pointer to the
IDCMPWindow that
sends the report */
struct IntuiMessage *SpecialLink; /* Pointer to the
next IntuiMessage
Structure * /

6.3

ABACUS

THE INTUITION LIBRARY

IntuiMessage_IDCMPFlags:
SIZEVERIFY Ox00000001L
NEWSIZE Ox00000002L
RRRRESHWINDOW Ox00000004L
MOUSEBUTTONS Ox00000008L
MOUSEMOVE Ox00000010L
GADGETDOWN Ox00000020L
GADGET UP Ox00000040L
REQSET Ox00000080L
MENUPICK Ox00000100L
CLOSEWINDOW Ox00000200L
RAWKEY Ox00000400L
REQVERIFY Ox00000800L

/* Changed window size */

/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

REQCLEAR Ox00001000L
MENUVERIFY Ox00002000L

/*
/*

NEWPREFS Ox00004000L
DISKINSERTED Ox00008000L
DISKREMOVED Ox00010000L
WBENCHMESSAGE Ox00020000L

/*
/*
/*
/*

ACTlVEWINDOW Ox00040000L /*
INACTlVEWINDOW Ox00080000L/*
DELTAMOVE Ox00100000L
/*
VANILLAKEY Ox00200000L

/*

INTUITICKS Ox00400000L
/*
LONELYMESSAGE Ox80000000L /*

MENUHOT Ox0001L
MENUCANCEL Ox0002L
MENUWAITING Ox0003L
OKOK MENUHOT
OKABORT Ox0004L
OKCANCEL MENUCANCEL

Redraw the window */

Mouse button pressed */
Mouse was moved */
Gadget pressed down */
Gadget released */
Requester added to window */
Menu item selected */
Window closed */
RAWKEY report sent * /
Requester should be checked
more closely */
Requester erased again */
Verification before menu
appears */
New Preferences added */
Disk inserted in a drive */
Disk removed from a drive */
Handle as report from
the WorkBench */
Window activated */
Window deactivated */
Mouse coordinates relative
to the last position */
Handle data as unprocessed
keyboard reports */
Clock time transferred */
No Message Type */

/* Menu Status */

Workbench_Flags:
WBENCHOPEN Ox0001L
WBENCHCLOSE Ox0002L

/* Workbench was opened */

/* Workbench was closed */

Intuition Macros:
Menu Macros:
MENUNUM(n) (n & Ox1F)
ITEMNUM (n) n 5) & OxOO3F)
SUBNUM(n) n 11) & OxOO1F)
SHIFTMENU(n) (n & Ox1F)
SHIFTlTEM(n) n & Ox3F) 5)

/*
/*
/*
/*
/*

Menu number */
Number of menu items */
Number of submenu items */
Shifted menu number */
Number of shifted menu
items */
SHIFTSUB(n) n & Ox1F) 11) /* Number of shifted submenu
items */

345

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Serial Macros:
SRBNUM(n)
SWBNIJM (n)
SSBNUM(n)
SPARNUM(n)
SHAKNUM(n)

(Ox08
(n 4
(Ox08
(n & OxOF
(Ox01 + (n 4.
(n 4)
(n & OxOF)

1* Number of read bits *1

1* Number of write bits *1

Preferences Definition:
NOMENU Ox001FL
NOITEM Ox003FL
NOSUB Ox001FL
MENUNull OxFFFFL
FOREVER fore;;)
1* Infinite loop *1
SIGN (x) ( x) > 0)
x) < 0) )
NOT !
CHECKWIDTH 19L
COMMWIDTH 27L
LOWCHECKWIDTH 13L
LOWCOMMWIDTH 16L
ALERT_TYPE Ox80000000L
1* Alert mask *1
RECOVERY ALERT OxOOOOOOOOL
1* Recoverable error *1
DEADEND ALERT Ox80000000L
1* Non-recoverable alert *1
AUTOFRONTPEN OL
1* Standard drawing colors *1
AUTOBACKPEN 1L
AUTODRAWMODE JAM2
1* Standard drawing mode *1
AUTOLEFTEDGE 6L
1* Standard coordinates *1
AUTOTOPEDGE 3L
AUTOITEXTFONT Null
1* Standard left *1
AUTONEXTTEXT Null
SELECTUP (IECODE_LBUTTON
IECODE UP PREFIX)
SELECTDOWN (mCODE LBUTTON)
MENUUP (IECODE RBUTTON I IECODE UP PREFIX)
MENUDOWN (IECODE RBUTTON)
- ALTLEFT (IEQUALIFIER LALT)
ALTRIGHT (IEQUALIFIER RALT)
AmigaLEFT (IEQUALIFIER LCOMMAND)
AmigaRIGHT (IEQUALIFIER RCOMMAND)
AmigaKEYS (AmigaLEFT I AmigaRIGHT)
CURSORUP Ox4CL
CURSORLEFT Ox4FL
CURSORRIGHT Ox4EL
CURSORDOWN Ox4DL
KEYCODE_Q Ox10L
KEYCODE X Ox32L
KEYCODE N Ox36L
KEYCODE-M Ox37L
KEYCODE V Ox34L
KEYCODE-B Ox35L

346

6.4 THE LAYERS LIBRARY

ABACUS

6.4

The layers library

Layers are rectangular graphic objects which can be overlapped. Each
layer has its own RastPort through which it can activate graphic
operations in the laytr. Before the layers can be used the layers library
must be opened:
Long *LayersBase;
layersBase = OpenLibrary (nlayers.libraryR,O);

In addition. you should open the graphics library because it contains

important functions used for creating clipping rectangles. Clipping
rectangles are layer sections. Graphic operations draw only the insides
of these clipping rectangles. Layers can be moved on the screen and

vary 1n size.
Intuition windows are represented by layers. Almost all of the attributes

used by windows are also used by the layers library.

6.4.1

Layer creation
Ot-ateBehindLayer

CreateUpfron<Layer
FattenLayerInfo

Ini<Layers
NewLayerInfo()

6.4.2

348
349

351
351
351

Layer processing
BeginUpdate
BehindLayer

EndUpdate
InstallClipRegion
LockLayer
LockLayerInfo
LockLayers
MoveLayer
MoveLayerInFrontOf
ScrollLayer
SizeLayer
SwapBitsRastPortClipRect

Upfron<Layer
WhichLayer

353
355
355
356
356
357
357
357
358
358
359
359
360
360

347

6. THE AMIGA LIBRARIES

6.4.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Releasing layers
DeleteLayer
DisposeLayerInfo
ThinLayerInfo
UnlockLayer
UnlockLayers
UnlockLayerInfo

6.4.1

361
361
362
362
362
363

Layer creation

ICreateBehindLayer

Creates background layerl

Syntax:

Layer = CreateBehindLayer (LayerInfo, Bit-map, xl, yl,x2, y2,

DO
-42
AD
Al
DO Dl D2 D3,
Flags [,Superbitmap])
D4
[ A2 ]
struct Layer *Layer;
struct Layer Info *LayerInfo;
struct Bit-~p *Bit-map;
LONG xl,yl,
x2,y2;
LONG Flags;
[struct Bit-map *Superbitmap;]

Description:

This function creates a layer which is placed behind other available

layers.

Parameters:

LayerInfo:
Bit-map:

Address of a completely initialized LayerInfo structure

Address of the bit-map in which the layer should be
displayed.

xl, yl, x2, y2:

Upper left and lower right corners of the layer.
Flags:
Describe layer type.
LayerSimple: Flag to test whether disturbed layer section should be
refreshed.
Layersmart:
A layer section overlapped by other layers is stored in a
memory range allocated by the system for easy refresh.
If insufficient memory exists, a Guru Meditation

occurs.
Layersuper:

348

Superbitmap support. Superbitmaps are bit-maps that

are too large to appear on the screen. This superbitmap
must be allocated by you but not displayed. The layer
draws a normal bit-map, and the superbitmap is
transferred to the layer containing the normal bit-map.

6.4 THE LAYERS LIBRARY

ABACUS

If you draw outside of the layer's border, these lines are

transferred directly into the superbitmap. If
SizeLayer () or ScrollLayer () are used, the
normal bit-map is copied into the correct position of
the superbitmap, and then the new section of the
superbitmap is copied back and displayed. When
enlarging the layer (SizeLayer) the section of the
layering coming back is direcdy displayed.

Ba:kdrq>:

Operates in conjunction with all other flags

(LAYERSIMPLE, LAYERSMART and LAYERSUPER
cancel out other flags). A BACKDROP layer stands
behind
all
other
layers
using
CreateBehindLayer (), or in front of all of the
other BACKDROPS and behind the rest of the layers
using CreateUpFrontLayers () .
SuperBitmap: Address of the superbitmap that must be presented in
conjunction with the LAYERSUPER flag.
Layer:
Address of a completely initialized layer structure.
Comments:

Certain flags must be set in conjunction with certain layer controls.

For example, if you want to refresh a LAYERSIMPLE layer, the
LAYERREFRESH flag must be set in Layer->Flags. This and the
other flags are defined in the include file g rap hie s / 1 aye r h .
When using the LA Y E R SUP E R flag you should also set the
LAYERS MART flag.

See Also:

CreateUpFrontLayer()

Syntax:

Layer = CreateUpfrontLayer (LayerInfo, Bit-map, xl, yl,

DO

-36

AO

Al

DO

Dl

x2, y2, Flags [,Superbitmap])

D2, D3, D4 [ A2 ]
struct Layer
*Layer;
struct Layer_Info *LayerInfo;
struct Bit-map
*Bit-map;
LONG
xl,yl,
x2,y2;
LONG
Flags;
struct Bitmap
*Superbitmap;]

Description:

This function creates a layer that is placed in front of all other layers or
before all other BACKDROP layers.

Parameters:

LayerInfo:
Bit-map:

Address of a completely initialized LayerInfo structure

Address of the bit-map in which the layer should be
displayed.

349

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

xl, yl, x2, y2:

Upper left and lower right corners of the layer.
Flags:
Describe layer type.
LayerSimple: Flag to test whether disturbed layer section should be

refreshed.
Layersmart:

Layersuper:

A layer section overlapped by other layers is stored in a

memory range allocated by the system for easy refresh.
If insufficient memory exists, a Guru Meditation
occurs.
Superbitmap support. Superbitmaps are bit-maps that
are too large to appear on the screen. This superbitmap
must be allocated by you but not displayed. The layer
draws a normal bit-map, and the superbitmap is
transferred to the layer containing the nonnal bit-map.

If you draw outside of the layer's border, these lines are

transferred directly into the superbitmap. If
SizeLayer () or Scroll Layer () are used, the
nonnal bit-map is copied into the correct position of
the superbitmap, and then the new section of the
superbitmap is copied back and displayed. When
enlarging the layer (SizeLayer) the section of the
layering coming back is directly displayed.
Bockdrq>:
Operates in conjunction with all other flags
(LAYERSIMPLE, LAYERSMART and LAYERSUPER
cancel out other flags). A BACKDROP layer stands
behind
all
other
layers
using
CreateBehindLayer () , or in front of all of the
other BACKDROPS and behind the rest of the layers
umngCreateUpFrontLayers() .
SuperBitmap: Address of the superbitmap that must be presented in
conjunction with the LAYERSUPER flag.
Layer:
Address of a completely initialized layer structure.
Comments:

Certain flags must be set in conjunction with certain layer controls.

For example, if you want to refresh a LAYERSIMPLE layer, the
LAYERREFRESH flag must be set in Layer->Flags. This and the
other flags are defined in the include file graphics/layer.h.
When using the LAY E R SUP E R flag you should also set the
LAYERSMART flag.

See Also:

CreateBehindLayer()

350

6.4 THE LAYERS LIBRARY

ABACUS

IFattenLayerInro

Allocates memory ror Layer Inrol

FattenLayerInfo (LayerInfo);

Syntax:

-156

AD

struct Layer_Info *LayerInfo;

Description:

This function allocates extra memory for the Layer_Info structure.

Kickstart Version 1.1 required further layer infonnation. Instead of
manually allocating and deallocating memory on each layers library
call, Fa t tenLayerInfo () predefines the memory allocation.
FattenLayerInfo () is an old function and should be replaced by
NewLayerInfo () whenever possible.

Parameter:

Layerinfo:

See Also:

InitLayers (),ThinLayerInfo ()

Address of the Layer_Info structure initialized

through I nit Layer s () that should allocate
additional memory.

ers

Initializes La er inro structure

Syntax:

InitLayers(LayerInfo);
-30
AD
struct Layer_Info *LayerInfo;

Description:

This function initializes the given Layer_Info structure for the

further layer access. After InitLayers () FattenLayerInfo ()
must be called. This method is outdated and should be replaced with
NewLayerInf 0 () whenever possible.

Parameter:

Layerlnfo:

See Also:

FattenLayerInfo(),ThinLayerInfo()

Address of the Layer_Info structure to be initialized.

Creates initialized La er Info structure

Syntax:

LayerInfo = NewLayerInfo()
DO
-144
struct Layer_Info *LayerInfo;

Description:

This function supplies a completely initialized Layer _ I n f 0

structure. This Layer_Info structure remains unlocked after
NewLayerInfo () .

Parameter:

None

Result:

Layerlnfo:

Address of the completely initialized Layer_Info

structure. When LayerInfo = zero, not enough

351

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

memory could be allocated from NewLayerlnfo ()

for the Layer_Info structure.
Comment:

Through the Layer_Info structure the layers created by means of

CreateBehindLayer () or CreateUpFrontLayer () are added
to a linked list

Structures:

offsets

Structure
struct Layer_Info <graphics/layers.h>
{

OxOO

Ox04
Ox08

4
8

OxOc
Ox18
Ox46
Ox54
Ox58
Ox5a
Ox5b
Ox5c
Ox5e
Ox62

12
24
70
84
88
90
91
92
94
98

struct Layer *top_layer;

/* Address of the top layer */
struct Layer *check_lp,
*obs;
/* System */
struct MinList FreeClipRects;
struct Signal Semaphore Lock;
struct List gs_Head;
LONG longreserved;
UWORD Flags;
BYTE fatten count;
BYTE LockLayersCount;
UWORD LayerInfo_extra_size;
WORD *bltbuff;
struct LayerInfo_extra *Layerlnfo_extra;
struct Layer <graphics/clip.h>
(

352

OxOO
Ox04

0
4

Ox08

OxOc

12

OxlO

16

Ox18
Oxlc
Oxle

24
28
30

Ox20

32

Ox22

34

Ox26

38

Ox2a
Ox2c

42
44

Ox30
Ox34
Ox38

48
52
56

Ox40
Ox44

64
68

Ox48

72

struct Layer *front,

*back;
/* For changing layers */
struct ClipRect *ClipRect;
/* Address of clipping rectangles */
struct RastPort *rp;
/* RastPorts of layers */
struct Rectangle bounds;
/* Sizes of layers */
UBYTE reserved[4];
UWORD priority;
UWORD Flags;
/* Flags variable */
struct Bit-map *Superbitmap;
/* For IAYERSUPER layer * /
struct ClipRect *SuperClipRect;
/* Clipping rectangle for superbitmap */
APTR Window; /* Interface to the Intuition
Windows */
SHORT Scroll X,
Scroll-Y;
/* See ScrollLayer{) */
struct ClipRect *cr,
*cr2,
*crnew; Ox3c
60
struct ClipRect *SuperSaveClipRects;
struct ClipRect * cliprects;
struct Layer Info-*LayerInfo;
/* Addre~s of the LayerInfo structure */
struct SignalSemaphore Lock;

6.4 THE LAYERS LIBRARY

ABACUS

Ox76
Ox7e
OxB2
OxB6
Ox9c

6.4.2

/* See LockLayer il * /
UBYTE reserved3[B);
struct Region *ClipRegion;
struct Region *saveClipRects;
UBYTE reserved2[22];
struct Region *DamageList;
/* see BeginUpdate() */

118
126
130
134
156

Layer processing

IBeginUpdate

Initializes layer updatel

Syntax:

Status = BeginUpdate (Layer)

DO
-7B
AO

Description:

This function ensures that the damage list that contains the sections of
the layers that must be redrawn is transferred into the ClipRect list
This cli pRect list contains all of the sections that must be redrawn.
When redrawing, only those sections that need redrawing are redrawn.
All other sections are undisturbed. BeqinUpdate () is usually used
in conjunction with the ClipRects. That way the old damage list is
saved:
struct Region *OldDamageList;
OldDamage-List = Layer->DamageList;

Then you make sure that the region that you have previously processed
with OrRectRegion () ,AndRectReqion (), etc. is declared as
the damage list:
struct Region *Region;
Layer->DamageList

Region;

Now you call BeqinUpdate ( ) . When you draw in the RastPort of

the layer, only the sections of the layer from the drawing operation are
met.

Parameter:

Layer.

Address of the layer whose damage list should function

as the ClipRect list

Result:

Status:

Returns the status of execution. If insufficient memory

exists, the status variable returns FALSE.

See Also:

EndUpdate ( )

353

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct Layer

rJ

struct Layer:
struct Layer:
*front

t--

struct Layer:
*front
struct Layer:
*baclt

struct Layer:
*baclt

struct OipRect:
*C\ipRect

struct OipRect:
*ClipRect

SIrUct RastPort:

struc:t RastPort:
*rp

*rp

f+

struct Rectangle:

struct Bit~:
*SuperBi ap
struct Layer_Info:

*LayerInfo

strut! Layer_Info:

r-

struct Region:
*OipRegion

struct Region:
*ClipRegion

struct Layer

~.

*LayerInfo

struct Layer:
*front

sttuct Layer:
*baclt

struct OipRect:
*C\ipRect

struct RastPort:
*rp

sttuct Rectangle:
bounds
struct BitMap:
*SuperBitMap

bounds

struct Rectangle:
bounds

sttuct BitMap:
*SuperBitMap

struct Layer_Info:
~

struct Region:
*DamageList

*LayerInfo

struct Region:
*ClipRegion
1

struc:t Region:
*DlmageUst

struct Region:
*DarnageUst
struct Layer_Info

....

struct Layer:

*t~_Layer

BYIE:
LockLayersCourt

354

6.4 THE LAYERS LIBRARY

ABACUS

IBehindLayer

Places layer in background

Syntax:

Status = BehindLayer (Dummy, Layer)

DO
-54
aO
al
BOOL
Status;
LONG
Dummy;
struct Layer *Layer;

Description:

This function places the given layer behind all other existing layers.
When sections of a REFRESH layer are visible, the LAYERREFRESH
bit for this layer is set.

If the layer in the background is a BACKDROP layer, it is placed behind

all of the other BACKDROP layers. Otherwise, the layer is placed
behind all other standard layers but in front of any BACKDROP layers.
Parameters:

Dummy:

Dummy variable (not used).

Address layer structure that should be placed in the
background.

Layer:
Result:

Status:

See Also:

UpFrontLayer ()

Returns TRUE when the process can be executed and

FALSE if insufficient memory exists.

IEndUpdate
Syntax:

Indicates end of updatel

EndUpdate (Layer, Flag);

-84

aO

dO

struct Layer *Layer;

BOOL
Flag;

Description:
Parameters:

This function ensures restoration of the ClipRects list after the layer
is refreshed.

Layer:
Flag:

Address of the layer that was refreshed.

Status of the layer's damage list. The value TRUE
means that the update was successful. If Flag contains
the value FALSE, the old damage list remains available
for use as a renewed update cycle
(BeginUpdate () ; ... EndUpdate () ;).

Comments:

If you use BeginUpdate () and EndUpdate () to manage your

own clippings, make sure that the old damage list is returned to the
layer after EndUpda te () (layer damage list = OldDamageList; ).

See Also:

BeginUpdate ()

355

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

Adds clipping regionl

hnstaIIClipRegion

Syntax:

OldClipRegion = InstallClipRegion (Layer, Region)

DO

-174

AO

Al

struct Layer *Layer;

struct Region *Region;

Description:

This function clips a specified region in a layer. This takes place after
creating a region using OrRectRegion () AndRectRegion () ,
etc.

Parameters:

Layer.
Region:

Result:

OldClipRegion:
Address of the previously installed clipping region.

Comments:

Before using DeleteLayer () make sure that the actual clipping

region is cleared using InstallClipRegion (layer, null);.
There may not be enough memory available for a normal layer
operation (Si zeLayer () , MoveLayer () , etc.). If this is the case,
the system uses the memory allocated for the clipping region. When
enough memory is present again, the clipping region is restored with a
call of a layers library function.

See Also:

BeginUpdate(),EndUpdate()

Address of the layer containing the clipping.

Address of the region that tests the active sections of
the layer through clipping rectangles.

ILockLayer

Syntax:

Denies task access to layerl

LockLayer (Dummy, Layer);
-96
AO
Al
LONG
Dummy;
struct Layer *Layer;

Description:

This function locks layer access away from other tasks.

LockLayer () waits until the layer is freed from the other tasks
(UnlockLayer (, and then locks this layer.

Parameters:

Dummy:
Layer.

Comments:

After executing LockLayer () execution of commands from Intuition

like Si zewindow () , Movewindow () , etc. are suppressed. Avoid
calling Intuition functions while a layer is locked.

See Also:

LockLayerInfo(),LockLayers()

356

Dummy variable (not used).

Address of layer that should be locked.

6.4

ABACUS

erInfo
Syntax:

THE LAYERS LIBRARY

Denies access to La er Info structure

LockLayerInfo (LayerInfo);
-120

AO

struct Layer_Info *LayerInfo;

Description:

This function locks access to the Layer_Info structure away from

other tasks. The layers library waits until the layer is freed from the
other tasks. UnlockLayerInfo () is called after the execution of
each layers function.
LockLayerInfo () and UnLockLayerInfo () are only needed
when the user wants to change a layer structure after it is installed.

Parameter:

LayerInfo:

See Also:

UnLockLayerInfo()

Address of the Layer_Info structure to be locked.

ILockLayers
Syntax:

Denies task access to all layersl

LockLayers (LayerInfo);
-108

AD

struct Layer_Info *LayerInfo;

Description:

This function locks all of the layers in the given Layer _ In f

structure, as well as the given Layer_info structure.

Parameter:

LayerInfo:

See Also:

LockLayer ()

IMoveLayer

Address of the LayerInfo_Structure whose layer

should be locked.

Moves layer on the screenl

Syntax:

Status = MoveLayer (Dummy, Layer, DeltaX, DeltaY);

DO
-60
AO
A1
DO
D1
BOOL
Status;
LONG
Dummy;
struct Layer *Layer;
LONG
DeltaX,
DeltaY;

Description:

This function moves a layer on the screen. If some sections of other

layers are visible, the system creates a damage list for these layers and
sets the LAYERREFRESH flag.

Parameters:

Dummy:
Layer:

Dummy variable (not used).

Address of the layer that should be moved (cannot be a
BACKDROP layer).

357

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DeltaX, DeltaY:
Number of pixels that the layer should be moved in the
X or Y direction.

If you move the layer to a point outside of the RastPort, a system crash

Comments:

may occur.

erlnFrontOr

Puts la er in rront or another

Syntax:

Status = MoveLayerlnFrontOf (Layerl, Layer2);

DO
-168
AD
A1
BOOL
Status;
struct Layer *Layerl,
*Layer2;

Description:

This function places Layerl in front of Layer2. The damage list

re-calculates all of the layers and sets the LAYERREFRESH flag in the
corresponding layers.

Parameters:

Layerl:
Layer2:

er

Address of the layer that should be positioned in front

of Layer2.
Address of the layer that Layer! should stand in front
of.

Chan es screen section or a la er

Syntax:
Scroll Layer (Dummy, Layer, DeltaX, DeltaY);
-72
AO
A1
DO
DO
LONG
Dununy ;
struct Layer *Layer;
LONG
Deltax,
DeltaY;

Description:

This function moves the contents of a superbitmap layer or normal

layer.

Parameters:

Dummy:
Dummy variable (not used).
Layer:
Address of the layer whose contents should be scrolled.
DeltaX, DeltaY:
Number of pixels that the layer should be moved.
Positive delta values move the contents toward the
upper left comer of the screen; negative delta values
move the contents toward the lower right comer.

358

6.4

ABACUS

ISizeLayer

THE LAYERS LIBRARY

Changes layer sizel

Syntax:

Status = SizeLayer (Dummy, Layer, DeItaX, DeItaY);

DO
-66
aO
Al
DO
Dl
BOOL
Status;
LONG
dummy;
struct Layer *Layer;
LONG
Deltax,
DeItaY;

Description:

This function changes the size of a layer. After sizing a layer, parts of
other layers may need to be covered or exposed. The
LA YERREFRESH bits are set after SizeLayer () to alleviate this.
When superbitmap layers are enlarged, the visible sections of the
superbitmap are copied into the new regions of the layer.

Parameters:

Dummy:

Dummy variable (not used).

Address of the layer that should be enlarged or reduced.
DeltaX, DeltaY:
Number of points that the layer should be enlarged or
reduced in the X or Y axis. Positive delta values enlarge
the layer; negative delta values reduce the size of the
layer.

Layer:

Result:

Status:

SwapBitsRastPortClipRect

Returns FALSE if insufficient memory exists for layer

enlargement

Exchanges RastPort and

clipping rectangle bits

Syntax:

SwapBitsRastPortClipRect (RastPort, CIipRect);

-126
AO
Al
struct RastPort *RastPort;
struct CIipRect *CIipRect;

Description:

This function exchanges the contents of a RastPort with a clipping

rectangle. You can then execute graphic operations in the given
RastPort that you don't want to execute in the RastPort of the layer
(e.g., graphic operations in the background).

Parameters:

RastPort:

ClipRect:

Address of the RastPort in which the contents of the

ClipRects should be copied and whose contents should
be copied into the bit-map of the ClipRect.
Address of the ClipRects whose bit-map should be
copied in the RastPorl

359

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

IUpFrontLayer
Syntax:

Moves layer to foreground

Status = UpfrontLayer (Dummy, Layer);
DO
-48
AD
AI
BOOL
Status;
LONG

dummy;

struct Layer *Layer;

Description:

This function moves a layer to the foreground. When the layer to be

moved is a BACKDROP layer, it can only be moved in front of other
BACKDROP layers. A BACKDROP layer still remains behind all
normal layers.

Parameters:

Dummy:
Layer:

Dummy variable (note used).

Address of the layer that should be moved to the
foreground.

Result:

Status:

Returns TRUE if the operation executes without error,

and FALSE if not enough memory was available to
complete the operation.

See Also:

BehindLayer ( )

Returns la er containin
Syntax:

Layer = WhichLayer (LayerInfo, x, y);

DO
-132
AD
DO 01
struct Layer
*Layer;
struct Layer_Info *LayerInfo;
SHORT
x,y;

Description:

This function returns the layer that contains the given pixel of the bitmap.

Parameters:

LayerInfo:

Address of the Layer_Info structure of the layer that

should be searched.
Screen coordinates of the pixel to be located.

x, y:

Result:

Layer:

Structures:

Offsets

Returns the address of the visible layers that contains

the given point, or the value 0 if the point cannot be
found in any layer.
Structure
struct ClipRect <graphics/clip.h>
{

360

OxOO
Ox04

0
4

Ox08
OxOc

8
12

struct
struct
/*
struct
struct
/*

ClipRect *Next;
ClipRect *prev;
For linking */
Layer *lobs;
Bit-map *Bit-map;
Bit-map of ClipRect */

6.4 THE LAYERS LIBRARY

ABACUS

6.4.3

Ox10

16

Ox18
Ox1c
Ox20

24
28
32

Ox24

36

struct Rectangle bounds;

/* size of ClipRect */
struct ClipRect *-p1,

*-p2;
LONG reserved;
'ifdef NEWCLIPRECTS_1_1
LONG Flags;
'endif

Releasing layers

IDeleteLayer

Deletes layerl

Syntax:

Status = DeleteLayer (Dummy, Layer);

DO
-90
aO
a1
BOOL
Status;
LONG
Dummy;
struct Layer *Layer;

Description:

This function removes the specified layer and frees memory allocated
for the layer structure by either CreateUpFrontLayer () or
CreateBehindLayer (). In addition the LAYERREFRESH flag is
set to accommodate the remaining layers.
When using a LAYERS MART layer, all of the backup memory is freed.
When using a superbitmap layer, the superbitmap remains and makes
further graphic manipulations available.

Parameters:

Dummy:
Layer.

Dummy variable (not used).

Address of the layer structure to be freed.

Result:

Status:

Returns TRUE if no error occurred and FALSE if an

enor occurred.

See Also:

DisposeLayerInfo()

IDisposeLayerInfo

Frees Layer Info structure I

Syntax:

DisposeLayerlnfo (Layerlnfo)
-150
aO
struct Layer_Info *LayerInfo;

Description:

This function frees the memory allocated by NewLayerlnfo () for

the Layer _ In f 0 structure of the layer. Before calling
DisposeLayerInfo (), DeleteLayer () must be called for each
layer of this Layer_Info structure.

361

6. THE AMIGA LIBRARIES

Parameter:

LayerInfo:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Address of the Layer_Info sbUcture to be freed.

!Thin LayerInfo
Syntax:

Releases memory for Layer Infol

ThinLayerInfo (LayerInfo);
-162

AD

struct Layer_Info *LayerInfo;

Description:

This function frees the memory locations allocated for the extra
information of a Layer_Info sbUcture. This memory was allocated
with Fa t tenLayerInfo () . ThinLayerInfo () is an old
function and should be replaced by DisposeLayerInfo ()
whenever possible.

Parameter:

LayerInfo:

See Also:

FattenLayerlnfo (). InitLayers ()

Address of the Layerlnfo structure whose extra

memory should be freed.

IUnlockLayer
Syntax:

Allows task access to layerl

UnlockLayer (Layer);
-102

AD

struct Layer *Layer;

Description:

This function unlocks the layer to all tasks. The access must have been
previously denied using LockLayer ().

Parameter:

Layer:

See Also:

LockLayer ()

Address of the layer that should be unlocked.

IUnlockLayers

Allows task access to all layersl

Syntax:

UnlockLayers (LayerInfo);
-114
AD
struct Layer_Info *LayerInfo;

Description:

This function unlocks the layers of the Layer_Info sbUcture to all

tasks. The access must have been previously denied using
LockLayers (). UnlockLayers () also ensures that the
Layer _ I n f 0
structure of the layer is freed
(UnlockLayerInfo () ).

Parameter:

LayerInfo:

See Also:

LockLayers ()

362

Address of the Layer_Info structure whose layers

should be unlocked.

6.4 THE LAYERS LIBRARY

ABACUS

IUnlockLayerInro

Allows access to Layer Inrol

Syntax:

Un1ockLayerInfo (LayerInfo)
-128
AO
struct Layer_Info *LayerInfo;

Description:

This function unlocks the Layer_Info structure to all tasks.

Parameter:

Layerlnfo:

See Also:

LockLayerInfo()

Address of the layer_info structwe to be unlocked.

363

6. THE AMIGA LIBRARIES

6.5

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The icon library

The icon library's main function is to serve the programmer and help
manipulate the Workbench. It makes functions available for loading and
saving icons. In addition, there are useful functions that manipulate
FreeLists, check the Tool Types array, and copy files.
When you create projects (data files) from a tool (application), the
project needs icon information to make it accessible from the
Workbench. It is easiest to read an icon that is already on the disk and
save it with the same name. For that you can use the functions
GetDiskObject, PutDiskObject, and FreeDiskObject.

Icon library functions

6.5.1

Workbench object functions

AIlocWBObject
FreeWBObject
GetWBObject
PutWBObject

6.5.2

Icon functions
GetIcon
PutIcon

6.5.3

365
365
365
366

367
368

Disk object functions

FreeDiskObject
GetDiskObject
PutDiskObject

368
369
369

6.5.4 FreeList functions

AddFreeList
FreeFreeList

370
371

6.5.5 Utility functions

BumpRevision
FindToolType
MatchTooIValoe

364

372
372

373

6.5 THE ICON LIBRARY

ABACUS

6.5.1.

Workbench object functions

IAllocWBObject
Syntax:

Allocates memory for a WBObjectl

Object = AllocWBObject ()
DO

-66

struct KBObject *Object;

Description:

This function uses memory for a Workbench object and initializes its
FreeLisl

Result:

Object

Exceptions:

The function returns a value of zero if the memory could not be

allocated.

Comments:

Avoid using this function, since it is intended for the internal

management of the Workbench. Use the disk object functions instead.

See Also:

AllocEntry, FreeEntry, FreeWBObject

Pointer to an initialized WBObject sttucture.

IFreeWBObject
Syntax:

Frees memory allocated (or a WBObjectl

FreeWBObject (Object)
-60

AO

struct WBObject *Object;

Description:

This function frees the memory that's allocated to the given

WBObject structure. the structure itself and all of the entries in the

sttucture's FreeLisl
Parameter:

Object

Comments:

Avoid using this function, since it is intended for the internal

management of the Workbench. Use the disk object functions instead.

See Also:

AllocEntry. FreeEntry. AllocWBObject

Pointer to a WBObject sttucture.

IGetWBObject
Syntax:

Reads WBObject (rom diskl

Object = GetWBObject (name)
DO

-30

AD

struct WBObject *Object;

UBYTE * name;

365

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This function reads a WBObject structure from disk. The function

inserts . in f 0 in the filename because it handles the file as an Info
file.

Parameter:

Name:

Pointer to the filename. . i n f

filename.

Result:

Object

Pointer to a WBObject structure.

Exceptions:

The function returns a value of zero if the file could not be loaded.
IoErr returns the exact error message.

Comments:

A void using this function, since it is intended for the internal

management of the Workbench. Use the disk object functions instead.

See Also:

PutWBObject

IputWBObject
Syntax:

is added to the

writes a WBObject in tbe diskette I

ok = PutWBObject (Name,Object)
DO
-36
AD
A1
BOOL OK;

UBYTE *Name;
struct WBObject *Object;

Description:

This function writes a WB Ob j e c t structure to disk. The function

inserts . in f 0 in the filename because it handles the file as an Info
file.

Parameters:

Name:
Object

Pointer to the filename.. info is added to the filename

Pointer to a WBObject structure

Result:

OK:

Comments:

Avoid using this function, since it is intended for the internal

management of the Workbench. Use the disk object functions instead.

See Also:

GetWBObject

Structures:

struct WBObject <no longer documented from V1.2>

Returns FALSE if the WBOb ject structure cannot be

written to disk. IoErr returns the exact error message.

OxOO
OxOE
Ox1C
Ox2A
Ox38
Ox3C
Ox3D
Ox3E
Ox40
Ox44

36'

0
14
28
42
56
60
61
62
64
68

struct
struct
struct
struct
struct
UBYTE
UBYTE
USHORT
char
SHORT

Node
Node
Node
Node
WBObject

wo MasterNode;
wo:::'Sibl ings;
wo Select Node;

wo~::UtilityNode;

*wo_P arent ;
wo_Flags;
wo_Type;
wo_UseCount;
*wo_Name;
wO_NameXOffset;

6.S

ABACUS

Ox46
Ox48
Ox4C
Ox50
Ox54
Ox58
Ox5C
Ox60
Ox64
Ox68
Ox6C
Ox70
Ox74

70

SHORT
char
struct
struct
LONG
LONG
char
struct
struct
char
LONG
LONG

72

76
80
84
88
92
96
100
104
108
112
116

THE ICON UBRARY

wo NameYOffset;
*wo=DefaultTool;
DrawerData *wo_DrawerData;
Window
*wo_IconWin;
wo_CUrrentX;
wo CurrentY;
**wo=ToolTypes;
Gadget
*wo_Gadget;
FreeList
*wo_FreeList;
*wo ToolWindow;
wo=StackSize;
wo_Lock;

struct DrawerData <workbench/workbench.h>

(

OxOO 0
Ox30 48
Ox34 52
Ox38 56

struct NewWindow
dd NewWindow;
LONG
dd=CurrentX;
LONG
dd CurrentY;
1* more extensive under Version 1.1

*1

);

6.5.2

Icon functions

IGetIcon
Syntax:

Reads DiskObject structure from diskl

ok
DO

GetIcon(Name,Icon,Free)
-42
AD
A1
A2

BOOL OK;

UBYTE *Name;
struct DiskObject *Icon;
struct FreeList *Free;

Description:

This function reads an Info file of the given DiskObject structure

and uses additional memory as noted in the FreeList. The function
inserts. info in the filename because it handles the file as an Info
file.

Parnmeters:

Name:
Object
Free:

Result:

OK:

See Also:

Put Icon

Pointer to the filename. . i n f 0 is added to the

ftlename.
Pointer to a DiskObject structure.
Pointer to a FreeList.
Returns FALSE if the Diskobject structure cannot
be loaded. IoErr returns the exact error message.

367

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Writes DiskObject structure to diskl

IPutIcon
Syntax:

OK = Putlcon(Name,Icon)
DO
-48
AO
AI
BOOL ok;
UBYTE *Narre;
struct Di skObject *Icon;

Description:

This function writes the given DiskObject structure to an Info file.

The function inserts. info in the filename because it bandIes the file
as an Info file.

Parameters:

Name:

Pointer to the filename. . in f 0 is added to the

ftlename.
Pointer to a DiskObject structure.

Icon:
Result:

OK:

Returns FALSE if the DiskObject structure could

not be written. IoErr returns the exact error message.

See Also:

Getlcon

Structures:

struct DiskObject <workbench/workbench.h>

{

Oxoo
Ox02
Ox04
Ox30
Ox32
Ox36
Ox3A
Ox3E
Ox42
Ox46
Ox4A
Ox4E

0
2
4
48
50
54
58

62
66
70
74
78

do_Magic;
UWORD
do Version;
UWORD
struct Gadget
dO=Gadget;
do Type;
UWORD
char
*do=DefaultTool;
char
**do ToolTypes;
LONG
do=CurrentX;
LONG
do_CurrentY;
struct DrawerData *do DrawerData;
*do-ToolWindow;
char
LONG
do=StackSize;

};

WE DISKMAGIC
WE DISKVERSION

NO ICON POSITION

6.5.3

Oxe310
1
(Ox80000000)

Disk object functions

IFreeDiskObject
Syntax:

368

1* do Magic *1
1* do-Version *1
1* dO=CurrentX/Y *1

Frees all DiskObject memoryl

FreeDiskObject (Object)
-90
AO
struct DiskObject *Object;

6.S THE ICON LIBRARY

ABACUS

Description:

This routine frees the memory that belongs to the given disk object.
The DiskObject sttucture should have been previously added using
GetDiskObject.

Parameter:

Object:

See Also:

GetDiskObject

Pointer to a DiskObject SbUcture.

!GetDiskObject
Syntax:

Loads DiskObject structure from diskl

Object = GetDiskObject (Name)
DO

-78

AO

struct DiskObject *Object;

UBYTE *Name;

Description:

This function allocates memory for a DiskObject sbUcture and reads

an Info file. The function inserts . in f 0 in the filename because it
handles the file as an Info file.

Parameters:

Name:

Pointer to the filename. . i n f

filename.

Result:

Object:

Pointer to the DiskObject sbUcture containing the

Info file data.

Exceptions:

The function returns zero if memory could not be allocated for the
DiskObject sbUcture, or if the file could not be loaded. IoErr
returns the exact error message.

Comments:

This function is similar to the Get Icon as it uses the allocation of

the DiskObject sbUcture and the FreeList.

See Also:

PutDiskObject

!PutDiskObject
Syntax:

is added to the

Writes DiskObject structure to diSk!

OK

PutDiskObject (Name, Object)

DO
-84
BOOL OK;
UBYTE *Name;

AO

Al

struct DiskObject *Object;

Description:

This function writes the given DiskObject SbUcture to an Info file.

The function inserts . in f 0 in the filename because it handles the file
as an Info file.

Parameters:

Name:
Object:

Pointer to the filename. . i n f 0 is added to the

filename.
Pointer to the DiskObject sbUcture containing the
Info file data.

369

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

RebJrns FALSE if the fIle could not be written. I oE r r

rebJrns the exact error message.

Result:

OK:

See Also:

GetDiskObject

Structures:

struct DiskObject <workbench/workbench.h>

{

OxOO
Ox02
Ox04
Ox30
Ox32
Ox36
Ox3A
Ox3E
Ox42
Ox46
Ox4A
Ox4E

o
2
4
48
50
54
58
62
66
70
74
78

};
WE
WE

UWORD
do Magic;
do-Version;
UWORD
struct Gadget
do=Gadget;
UWORD
do Type;
*do-DefaultTool;
char
**do-ToolTypes;
char
LONG
do=CurrentX;
do CurrentY;
LONG
struct DrawerData *do-DrawerData;
*do-ToolWindow;
char
LONG
do=StackSize;

DISKMAGIC
DISKVERSION
NO ICON POSITION

6.5.4

Oxe310
1

(Ox80000000)

/* do Magic */
/* do-Version */
/* do=CurrentX/Y */

FreeList functions

AddFreeList

Inserts a memor

in FreeList

Syntax:

OK = AddFreeList(Free,Mem,Length)
DO
-72
AO
Al
A2
BOOL OK;
struct FreeList *Free;
UBYTE *Mem;
ULONG Length;

Description:

This function inserts the memory region specified by Mem and

Length into the FreeList. Before accessing this function, the
memory must have been previously allocated using AllocMem.

Parameters:

Free:
Mem:
Length:

Pointer to a FreeList structure.

Pointer to the beginning of the memory range.
Length of the memory range in bytes.

Result:

OK:

See Also:

AllocEntry, FreeEntry, FreeFreeList

370

Returns FALSE when the memory could not be taken

into the FreeList.

6.5 THE ICON LIBRARY

ABACUS

IFreeFreeList

Frees all FreeList memoryl

Syntax:

FreeFreeList (free)
-54
AD
struct FreeList *free;

Description:

This function frees the FreeList sttucture, as well as all memory as

noted in the FreeList. A FreeList is a list whose elements are
MemList structures.

Pararne1er:

Free:

Comments:

If the FreeList structure itself is contained in the FreeList, it

must be noted in the first element of the FreeList.

See Also:

AllocEntry, FreeEntry, AddFreeList

Structures:

struct FreeList <workbench/workbench.h>

Pointer toa FreeList structure.

Oxoo 0 WORD
Ox02 2 struct List
Ox10 16

fl_NumFree;
fl_MemLi st;

};

struct

MemList <exec/memory.h>

OxDD 0
DxOE 14
Ox10 16
Ox18 24

struct Node
UWORD
struct MemEntry

m1 Node;

ml-NumEntries;
ml=ME[11;

};

struct

MemEntry <exec/memory.h>

OxOO 0 union
OxOO 0
DxOO 0

ULONG
APTR

meu Reqs;
meu=Addr;

/* memory flags or * /
/* pointer to memory */

me Un;
Ox04 4 ULONG me_Length;
Ox08 8
};

Speicherflags (meu Reqs);

MEMF PUBLIC (10)
MEMF CHIP
(11)
MEMF FAST
(12)
MEMF CLEAR
(116)
MEMF IARGEST (117)

371

6. THE AMIGA LIBRARIES

6.5.5

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Utility functions
Chan es filename to "co

Syntax:

Result = BumpRevision(newBuffer,oldName)
DO

-108

AO

Al

UBYTE *rResult;
UBYTE *newBuffer,oldName;

Description:

This function creates a copy of a file, appending "Copy of... " to the
beginning of the copy's filename.

Parameters:

newBuffer.

Pointer to a buffer in which the new name is stored.

This can be up to 31 characters in length (i.e., the
maximum length of the DOS filename plus one

oldName:

Pointer to the filename from which the copy should be

c~ter).

made.

Result:

Result:

Exceptions:

If the new name is longer than 30 characters, the name is truncated to

30 chamcters.

Comments:

The maximum length of the DOS filename is currently 30 characters.

This number may change in later versions of DOS.

Examples:

oldName

newBuffer

''Test''
"copy of Test"
"copy 2 of Test"
"copy 199 of Test"
"copy Test"
"copy 0 of Test"

"copy of Test"
"copy 2 of Test"

Pointer to the new buffer.

"copy 3 of Test"
"copy 200 of Test"
"copy of copy Test"
"copy 1 of Test"

IFindTOOIType
Syntax:

Searches for ToolType entryl

Value
DO

FindToolType(toolTypeArray,Name)
-96

AO

Al

UBYTE *Value;
UBYTE **toolTypeArray,*Name;

Description:

372

This function searches the To 0 1 Type array for a certain entry. The
Tool Type array consists of pointers to strings which are constructed
in the following way:

ABACUS

6.5 THE ICON LIBRARY

VARIABLE=value

You get a pointer to the value of the string back, rather than a copy of
the value string.
Parameters:

toolTypeArray:
Pointer to the Tool Type array.
Pointer to the variable name that should be searched in
the array. This is found in the region outside of the
array and is not a part of it.

Name:

Result:

Value:

Exceptions:

When the variable could not be found, you get a zero back.

Comments:

Tool Types are assigned files (programs) and can be set from the
Workbench with the menu point "Info".

Example:

The Tool Type array contains the following strings:

Pointer to the value string.

UBYTE *tTA[] =
(

"FlLETYPE=text",
"TEMPDIR=:t"

Then the following function calls result

FindToolType(tTA,"FlLETYPE") => pointer to "text"
FindToolType (tTA, "TEMPDIR") => pointer to ":t"
FindToolType(tTA,"MAXSIZE") => Null

See Also:

MatchToolType

IMatchToOIValue
Syntax:

Checks for ToolType value(s)l

OK = MatchToolValue(typeString,Value)

DO
BOOL

-102

AD

Al

OK;

UBYTE *typeString,*Value;

Description:

This function determines whether a Tool Type variable contains one

or more variables. Multiple values can be separated by I characters.

Parameters:

typeString:
Value:

Pointer to the variable type (see example) below.

Pointer to the value of a Tool Type variable (e.g., a
variable found by the FindTool Type function).

Result:

OK:

Returns FALSE if the variable does not contain the

value being searched for.

See Also:

FindToolType

373

6. THE AMIGA LIBRARIES

6.6

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The graphics library

The graphics library makes graphic commands available for almost any
graphic application. In addition to simple lines, pixel setting and circle
drawings, this library contains functions for controlling sprites, bobs
and vsprites. You'll also find some functions in this library that are
located in the layers library as well. The graphics library is opened as
follows:
"GfxBase = (struct GfxBase) OpenLibrary("graphics.library",O)"

The GfxBase structure looks like the following:

Offset
struct GfxBase <graphics/gfxbase.h>
{

374

Oxoo
Ox22

0
34

Ox26
Ox2a

38
42

struct Library LibNode;

struct View *ActiView;
/* view currently presented */
struct copinit *copinit;
long *cia;

Ox2e

46

long *blitter;

Ox32
Ox36
Ox3a
Ox3e

50
54
58
62

Ox42
Ox46

66
70

Ox4a

74

Ox60

96

Ox76

118

Ox8c

140

Ox9a
Oxge
OxaO
Oxa1
Oxa2
Oxa4
Oxa6

154
158
160
161
162
164
166

Oxa7
Oxa8
Oxaa
Oxac
Oxae

167
168
170
172
174

Oxbc

188

UWORD *LOFlist;
UWORD *SHFlist;
struct bltnode *blthd,
*blttl;
1* List for QBlit () *1
struct bltnode *bsblthd,
*bsblttl;
/* List for QBSBlit () */
struct Interrupt vbsrv,
1* vertical blank server */
timsrv,
1* time server */
bltsrv;
/* blitter server */
struct List TextFonts;
/* System font list */
struct TextFont *DefaultFont;
UWORD Modes;
BYTE VBlank;
BYTE Debug;
SHORT Beamsync;
SHORT system_bplconO;
UBYTE SpriteReserved;
/* reserved Sprites */
UBYTE bytereserved;
USHORT Flags;
SHORT BlitLock;
short BlitNest;
struct List Bli tWai tQ;
/* Blitter Wait Queue */
struct Task *BltOwner;

6.6 THE GRAPHICS LIBRARY

ABACUS

OxcO

192

Oxce

206

OxdO
Oxd4
Oxd6
OxdB
Oxda
Oxdc
Oxde
OxeO

20B
212
214
216
21B
220
222
224

Oxe4 22B
OxeB 232
Oxea 234
Oxf2 242

/* who's calling OWnBlitter()? */

struct List TOF WaitQ;
/* Top Of Frame Wait Queue */
UWORD Disp1ayF1ags;
/* NTSC, PAL, GENLOCK, etc. */
struct SimpleSprite **SimpleSprites;
UWORD MaxDisplayRow;
UWORD MaxDisplayColumn;
UWORD NormalDisplayRows;
UWORD NormalDisplayColumns;
UWORD NormalDPMX;
UWORD NormalDPMY;
struct Signal Semaphore
*LastChanceMemory;
UWORD *LCMPtr;
UWORD MicrosPerLine;
ULONG reserved[2];

Graphics library functions

6.6.1

Raster initialization and processing

AllocRaster
FreeRaster
InitBitMap
InitRastPort
SetAPen
SetBPen
SetDrMd
SetDrPt
SetRast
SetWrMsk

6.6.2

378
378
379
379
380
380
381
381
382
382

RastPort drawing functions

QearEOL

ClearScreen
Draw
DrawEllipse
DrawCircle
PolyDraw
ReadPixel
ScrollRaster
Text
TextLength
WritePixel

385
385
385
386
386
386
387
387
388
388
389

375

6.

THE AMIGA LIBRARIES

6.6.3

RastPort fill functions

AreaCircle
An-&>raw

AreaEllipse
AreaEnd
AreaMove
BNDRYOFF
Hood

InitArea
InitTmpRas
RectFill
SetAtPt
SetOPen

6.6.4

391
391
391
392
392
393
394

394
395

397
397
397
398
399
399

401
403
403
404

405
406

407
407
407
408
408
409

Copper functions

CBump
CEND
CMove
CWait
FreeCopList
FreeCprList

376

390

Blitter functions
BltBitMap
BltBitMapRastPort
BltClear
BltMaskBitMapRastPort
BltPattem
BltTemp1ate
ClipBlit
DisownBlitter
OwnBlitter
QBlit
QBSBlit
WaitBlit

6.6.6

389
390

ColorMap functions
FreeColorMap
GetColorMap
GetRGB4
LoodRGB4
SetRGB4
SetRGB4CM

6.6.5

ADVANCED SYSTEM PROGRAMMER'S GUIDE

411
411

412
412
413

413

6.6

ABACUS

FreeVPortCopLists
InitView
InitVPort
lradView
MakeVPort
MrgCop
ScrollVPort
UCopperListlnit
VBeamPos
WaitBOVP
WaitTOF

6.6.7

420
420
420
421
421
421
421
422
422
422
423
423
424
424
424

Character display
AddFont
AskFont
AskSoftStyle
CloseFont
OpenFont
RemFont
SetFont
SetSoftStyle

6.6.9

413
414
414
414
415
415
416
416
416
417
417

Layer functions
AndRectRegion
AndRegionRegion
AuemptLockLayerRom
OearRectRegion
ClearRegion
CopySBitMap
DisposeRegion
LockLayerRom
NewRegion
OrRectRegion
OrRegionRegion
SyncSBitMap
UnlockLayerRom
XorRectRegion
XorRegionRegion

6.6.8

THE GRAPHICS LIBRARY

427
427
427
428
428
429
429
430

GELs and sprites

AddAnimOb
AddBOO

AddVSprite
Animate

432
432
432
433
377

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

433

ChangeSprite
DoCollision
DrawGList
FreeGBuffers
FreeSprite
GetGBuffers
GetSprite
InitAnimate
InitGels
InitGMasks

434
434

435
435
436
436
437
437
438
438
439
439

InitMasks

MoveSprite
RemBob
Remmob
RemVSprite
SetCollision
SortGList

6.6.1

440
440
440
441

Raster initialization and processing

IAllocRaster
Syntax:

Allocates memory for bit-planel

Memory = AllocRaster (Width,Height)
DO

-492

DO

01

PlANEPTR Memory;
SHORT
Width,Height;

Description:

This function allocates as much memory as needed to accommodate a

bit-plane width * Height pixels in size.

Parameters:

Width:
Height:

Bit-plane width in pixels.

Bit-plane height in pixels.

Result:

Memory:

Returns the starting address of the memory to be

allocated. When the requested number of bytes is
reserved. this function returns a value of zero.

See AlSO:

FreeRaster ()

IFreeRaster
Syntax:

378

Frees allocated bit-plane memoryl

FreeRaster (Memory, Width, Height)
-498
AD
DO
01
PlANEPTR BitPlane;
SHORT
Width, Height;

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This function releases the memory previously allocated for a bit-plane

using AllocRaster (). This makes the memory available to any
part of the system.

Parameters:

Memory:
Width:
Height:

Comments:

You must give the same values for Height and width as you did in
AllocRaster. If these values are different than the ones used to
allocate memory, too little or too much memory is freed.

See Also:

AllocRaster ()

Address of the memory to be freed.

Bit-plane width in pixels.
Bit~plane height in pixels.

IInitBitMap

Initializes BitMap structurel

Syntax:

InitBitMap (BitMap, Depth, Width, Height)

-390
AD
DO
D1
D2
struct BitMap *BitMap;
BYTE
Depth,
SHORT
Width,

Description:

This function initializes a Bi tMap structure.

Parameters:

Bit-map:
Depth:
Width:
Height:

Comments:

After the initialization of the bit-map structure using

Ini tBi tMap () , you must assign the address of the bit-planes in the
structure (BitMap.Planes[i] = memory;). The size of each
bit-plane corresponds to that of the bit-map.

See Also:

AllocRaster ()

Address of the Bi tMa p structure to be initialized.

Number of bit-planes the bit-map should contain.
Bit-map width in pixels.
Bit-map height in lines.

InitRastPort
Syntax:

Initializes RastPort structure

InitRastPort (RastPort)

-198

A1

struct RastPort *RastPort;

Description:

This function initializes a RastPort structure.

Parameter:

RastPort:

Comments:

The Ra s t P 0 r t structure contains the actual character colors, the

actual drawing mode, and more.

Address of the RastPort structure to be initialized.

379

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

After initialization the drawing mode defaults to JAM2, and the

variables Mask, FgPen, A01Pen and LinePtrn contain a value of
-1. All of the other variables of the RastPort structure are set to
zero. So you must make the bit-map the RastPort's "easel"
(RastPort. BitMap = BitMap). After that the RastPort is ready
for the graphic commands.

ISetAPen
Syntax:

Sets foreground penl

SetAPen (RastPort, ColorPen)

-342

Al

DO

struct RastPort *RastPort;

SHORT
ColorPen;

Description:

This function specifies the foreground pen color.

Parameters:

RastPort:

Address of the RastPort whose foreground pen should

be changed.
Number of the color register used when drawing with
the foreground pen.

ColorPen:

Comments:

Although only 32 color registers normally exist, the Color Pen

parameter can accept a value higher than 32. This occurs mainly when
the RastPort is the RastPort of an EXTRA HALFWIDTH or HAM
ViewPort.

See Also:

SetBPen(),SetOPen()

\SetBPen
Syntax:

determination of the background pen\

SetBPen (RastPort, ColorPen)

-348

Al

DO

struct RastPort *RastPort;

SHORT
ColorPen;

Description:

This function specifies the background pen color.

Parameters:

RastPort:
ColorPen:

Address of the RastPort whose background pen should

be changed.
Number of the color register used when drawing with
the background pen.

Comments:

The background pen can be found in JAM2 mode and any combinations
using JAM2 mode (JAM2 I COMPLEMENT and JAM2 I INVERSVID)
in conjunction with text or area fills. The points not actually set in
JAMl mode are the color of the background pen in JAM2 drawing mode
(JAM2 I INVERSVID).

See Also:

SetDrMd(),SetAPen()

380

6.6 THE GRAPHICS LIBRARY

ABACUS

ISetDrMd

Sets drawing model

Syntax:

SetDrMd (RastPort, DrawMode)

-354
Al
DO
struct RastPort *RastPort;
SHORT
DrawMode;

Description:

This function sets the drawing mode of a RastPort. The drawing mode
dictates the behavior of a pixel, line, etc., in conjunction with pixels
already placed in the RastPort. In JAM! mode the point appears directly
in the RastPort. Text output requires special attention. For example,
free areas inside of the letter 0 show through the rest of the letter.
The JAM2 mode is different. There the color of the BPen is assigned to
all of the points not set by letters (e.g., the inside of the letter 0). In
addition, the BPen color covers any 0 bits (e.g., a single color fill

pattern). This means that the Blitter can only copy rectangular areas,
which can contain these areas. The empty area can be made any color
you want.
The following drawing modes function only in conjunction with the
JAM! or JAM2 mode:
COMPLEMENT

mode pixels are run through XOR before you set them.

If you use JAM2 mode in conjunction with COMPLEMENT mode, the

APen and BPen exchange roles.

The INVERSVID mode often occurs in conjunction with the Text ( )

function. This mode allows the display of inverse video characters or
graphics. When you use JAM2 mode along with INVERSVID, the
system behaves as if you are using JAM2 mode only, except that the
APen and BPen switch roles.
Parameters:

RastPort:
DmwMode:

Comments:

DrawMode can have the values JAM!, JAM2, COMPLEMENT,

INVERSVID. These symbols are defined in the include
graphics/rastport.h.

RastPort in which the drawing mode should be changed.

Selected drawing mode.
and
file

Sets drawing patternl

ISetDrPt
Syntax:

SetDrPt (RastPort, Pattern)

(Macro)
struct RastPort *RastPort;
UWORD
Pattern;

Description:

This function determines the line pattern.

381

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Parameters:

RastPort:
Pattern:

Comments:

This line pattern is only 16 points wide. Any lines wider than 16
pixels repeat the pattern.

RastPort in which the line pattern should be changed.

New line pattern. Each set bit in this word represents a
set pixel in the line.

/SetRast

Sets RastPort colorsl

Syntax:

SetRast (RastPort, ColorPen)

-234
A1
DO
struct RastPort *RastPort;
UBYTE
ColorPen;

Description:

This function assigns one color to all the pixels in the RastPort.

Parameters:

RastPort:
ColorPen:

See Also:

SetAPen(),SetBPen()

Address of the RastPort to be colored in.

Number of the color register in whose color the
RastPort should be colored.

ISetWrMsk

Sets bit-planes for writingl

Syntax:

SetWrMsk (RastPort, Mask)

(Macro)
struct RastPort *RastPort;
UBYTE
Mask;

Description:

This function determines which bit-planes of a bit-map can be written

to (e.g., pixel ge\tting).

Parameters:

RastPort:
Mask:

RastPort whose write mask should be changed.

Bit mask of the bit-planes that can be addressed. Bit 0
represents the bit-plane BitMap. Planes [0], bit 1
BitMap.Planes[l],e~.

Structures:

Offset

Structures
struct BitMap <graphics/gfx.h>
(

382

OxOO

Ox02

Ox04
OxOS

4
S

Ox06
OxOB

6
B

Ox10

16

UWORD BytesPerRow;
1* Width in bytes *1
UWORD Rows;
1* Height in lines */
UBYTE Flags;
UBYTE Depth;
1* Number of bit-planes *1
UWORD pad;
PLANEPTR Planes[B);
1* Address of bit-plane *1

6.6

ABACUS

THE GRAPHICS LIBRARY

struct RastPort <graphics/rastport.h>

{

OxOO

Ox04

OxOB

OxOc

12

Ox10

16

Ox14

20

Ox1B

24

Ox19

25

Ox1a

26

Ox1b

27

Ox1c

2B

Ox1d

29

Ox1e
Oxlf
Ox20
Ox22

30
31
32
34

Ox24
Ox26

36
3B

Ox2B
Ox30
Ox32
Ox34

40
4B
50
52

Ox3B

56

Ox39
Ox3a
Ox3c
Ox3e
Ox40
Ox42

57
5B
60
62
64
66

Ox46

70

Ox4e
Ox5c

7B
92

Ox64

100

struct Layer *Layer;

/* Address of layer */
struct BitMap *BitMap;
/* Address of bit-map;
USHORT *AreaPtrn;
/* Address of fill pattern */
struct TmpRas *TmpRas;
/* Address of temporary raster */
struct Arealnfo *Arealnfo;
/* Address of Arealnfo structure */
struct Gelslnfo *Gelslnfo;
/* Address of Gelslnfo structure */
UBYTE Mask;
/* Write mask */
BYTE FgPen;
/* APen */
BYTE BgPen;
/* BPen */
BYTE AOlPen;
/* OPen */
BYTE DrawMode;
/* Drawing mode */
BYTE AreaPtSz;
/* Height of fill pattern */
BYTE linpatcnt;
BYTE dummy;
USHORT Flags;
USHORT Lineptrn;
/* Line pattern */
SHORT cp_x,
cpy;
/* Graphic cursor position */
UBYTE minterms[B];
SHORT PenWidth;
SHORT PenHeight;
struct TextFont *Font;
/* Actual Font */
UBYTE AlgoStyle;
/* SoftStyle * /
UBYTE TxFlags;
UWORD TxHeight;
UWORD TxHeight;
UWORD TxBaseline;
WORD TxSpacing;
APTR *RP User;
/* U~er extension */
ULONG longreserved[2];
iifndef GFX RASTPORT 1 2
UWORD wordreserved[7];
UBYTE reserved[B];
iendif;

383

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct RastPort
struct Layer:
*Layer

....
,....
struct BitMap

struct BitMap:
*BitMap
UBY1E:
Mask
BYIE:
FgPen
BYIE:
BgPen
BY1E:
AOlPen

BY1E:
DrawMode
USHORT:
LinePtrn
SHORT:
cp_x
cp-y

384

........

UWORD:
BytesPerRow
UWORD:
Rows
UBY1E:
Flags
UBY1E:
Depth
PLANEPTR:
Planes [8]

.....
...

6.6 THE GRAPHICS LIBRARY

ABACUS

6.6.2

RastPort drawing functions

ClearEOL
Syntax:

Clears line u

to current cursor

ClearEOL (RastPort)

-42

Al

struct RastPort *RastPort;

Description:

This function clears a text line displayed using the RastPort character
set, up to the current graphic cursor position. This position can be
determined using the Move () function. The clearing occurs in such a
way that all of the points that lie outside the graphic cursor position are
erased, or (in JAM2 drawing mode) changed to the color of the BPen.

Parameter:

RastPort:

See Also:

ClearScreen(),Move()

RastPort in which the line should be deleted.

Clear Screen
Syntax:

Clears screen at current cursor

ClearScreen (RastPort)

-48

Al

struct RastPort *RastPort;

Description:

This function clears the entire screen starting at the current graphic
cursor position. The clearing occurs in such a way that all of the points
that lie outside the graphic cursor position are erased, or (in J AM2
drawing mode) changed to the color of the BPen.

Parameter:

RastPort:

See Also:

ClearEOL ()

RastPort that should be erased from the graphic cursor

position to the end of the screen.

IDraw
Syntax:

Draws line to given coordinatesl

Draw (RastPort, x, y)

-246

Al,

DO, Dl

struct RastPort *RastPort;

SHORT
x,y;

Description:

This function draws a line in the given RastPort, from the current
graphic cursor position to the specified coordinates. These coordinates
become the new graphic cursor position.

Parameters:

RastPort:
x, y:

RastPort in which the line should be drawn.

Coordinates of the line's end point

385

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Comments:

This function uses the line pattern set using SetDrPt () .

See Also:

Move ()

IDrawElIipse

Draws ellipsel

Syntax:

OrawEllipse (RastPort, XM, YM, Xr, Yr)

-180
A1
DO 01 02 03
struct RastPort *RastPort;
SHORT
XM,YM;
SHORT
Xr,Yr;

Description:

This function draws the outline of an ellipse in the specified RastPort.

Parameters:

RastPort:
XM, YM:
Xr, Yr:

See Also:

AreaEllipse ( )

RastPort in which the ellipse should be drawn.

Coordinates of the ellipse's midpoint.
X and Y radii of the ellipse.

!DrawCircle

Draws circlel

Syntax:

OrawCircle (RastPort, XM, YM, Radius)

(Macro)
struct RastPort *RastPort;
SHORT
XM, YM;

Description:

This function draws a circle in the specified RastPort.

Parameters:

RastPort:
XM,YM:

Radius:
See Also:

RastPort in which the circle should be drawn.

Coordinates of the circle's midpoint
Radius of the circle.

AreaEllipse ()

!PolyDraw

Draws polygonl

Syntax:

PolyOraw (RastPort, Number, PointArray)

-336
A1
DO
AO
struct RastPort RastPort;
SHORT
Number;
struct tPoint
PointArray[MaxNumber];

Description:

This function draws polygons in the specified RastPort.

Parameters:

RastPort:
Number:
PointArray:

RastPort in which the polygon should be drawn.

Number of comer points in the polygon.
Coordinates of each comer point that should be
connected. The X coordinate is saved in PointArray
[i) . x and the Y coordinate is saved in PointArray
[i).y.

386

6.6 THE GRAPmCS LIBRARY

ABACUS

See Also:

Move () ,Draw ()

IReadPixel

Reads pixel colorl

Syntax:

ColorPen = ReadPixel (RastPort, x, y)

DO
-31B
A1
DO 01
LONG
ColorPen;
struct RastPort *RastPort;
SHORT
x,y;

Description:

This function determines the color of the pixel at the given X/Y
COOIdinates.

Parameters:

RastPort:
x, y:

Address of the RastPort in which a pixel's color should

be tested.
Coordinates of the pixel to be tested.

Result:

ColorPen:

See Also:

WritePixel ()

ScrollRaster

Returns the number of the color register whose color is

used by the pixel. or the value -1 if x and y are outside
the limits of the RastPort's bit-map.

Moves rectan Ie within RastPort

Syntax:

ScrollRaster (RastPort, OeltaX, OeltaY, xl, y1, x2, y2)

-396
A1
DO
01
02 03 04 05
struct RastPort *RastPort;
SHORT
OeltaX, DeltaY;
SHORT
xl,yl,y2,x2;

Comments:

This function scrolls the contents of a rectangle within the given

RastPort.

Parameters:

RastPort:
RastPort in which a rectangle should be scrolled.
DeltaX. DeltaY:
Coordinates to which the rectangle should be moved.
Positive Delta values move the rectangle toward the
upper left comer of the RastPort; negative Delta values
move the rectangle in the opposite direction.
Upper left comer of the rectangle to be moved.
xl, yI:
Lower right comer of the rectangle to be moved.
x2. y2:

Comments:

ScrollRaster () is not especially fast to avoid screen flickering.

387

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

String output!
Syntax:

Text (RastPort, String, NurnCharactersl

-54

Al

AO

DO

struct RastPort *RastPort;

char
*String;
SHORT
NumCharacters;

Description:

This function displays character strings at the current graphic cursor

position (see Move ( ) ).

Parameters:

RastPort:

Comments:

The Strlen (String) function easily calculates the number of

characters in the string to be displayed.

See Also:

Move () SetDrMd ()

Address of the RastPort in which the string should be

displayed
String:
Address of the string to be written in the RastPort.
NumCharacters:
Number of characters that the string to be displayed
contains.

ITextLength
Syntax:

Calculates number of pixelsl

Length = TextLength (RastPort, String, NumCharactersl
DO

-54

A1

AO

DO

SHORT
Length;
struct RastPort *RastPort;
char
*String;
SHORT
NumCharacters;

Description:

This function computes the horizontal resolution of the string to be

displayed. This resolution is in pixels, not in characters. The
TextLength function is useful for drawing a rectangle around a text,
or for centering a rectangle around a text.

Parameters:

RastPort:
RastPort into which the string should be written.
String:
Address of the string whose width should be tested.
NumCharacters:
Number of characters in the string.

Result:

Length:

Comments:

TextLength calculates only the width of the string in pixels-the

string itself is not displayed. You must display the string using the
Text () function.

String wi<tth in pixels.

The number of characters of the string to be selected can be computed

using the Strlen (String) function.

388

6.6 THE GRAPHICS LIBRARY

ABACUS

See Also:

Text (),SetFont()

IWritePixel

Draws single pixelsl

Syntax:

Status = WritePixel (RastPort, x, y)

-324
Al
DO Dl
ULONG
Status;
struct RastPort *RastPort;
SHORT
x,y;

Description:

This function draws one pixel in the current drawing color (Apen) at
the specified X/Y coordinates oCthe current RastPort.

Parameters:

RastPort:
x,

Address of the RastPort in which the pixel should be

drawn.
Coordinates of the pixel to be drawn.

y:

Result:

Status:

See Also:

ReadP ixel ( )

Structure:

Offset

Returns 0 if the procedure was successful, and -1 if the

given coordinates are outside of the RastPort.

Structure
struct tPoint <graphics/gfx.h>
{

OxOO
Ox02
Ox04

6.6.3

2
4

WORD x,
y;

RastPort fill functions

AreaCircie

Defines circle in Arealnfo structure

Syntax:

Status = AreaCircle (RastPort, Xm,Ym, Radius)

(Macro)
LONG
Status;
struct RastPort *RastPort;
SHORT
Xm,Ym;
SHORT
Radius;

Description:

This function dermes a circle for filling in the AreaInfo structure of

the given RastPort.

Parameters:

RastPort:

Address of the RastPort in which the filled circle should

be drawn.

Xm, Ym:
Radius:

Coordinates of the circle's midpoinL

Radius of the circle to be drawn.

389

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Returns 0 if the data for the circle was accepted by the

Arealnfo structure, or -1 if the data was rejected.

Result:

Status:

Comments:

AreaCircle () is a macro (graphics/gfxmacros. h) that

AreaEllipse () calls with the same X and Y radius.

See Also:

AreaEnd() ,InitArea ()

AreaDraw
Syntax:

ixel in AreaInfo

Defines
Status = AreaDraw (RastPort, x, y)
DO

-258

A1

00 D1

LONG
Status;
struct RastPort *RastPort;
SHORT
x,y;

Description:

This function defmes a pixel for a filled polygon.

Parameters:

RastPort:
x, y:

Address of the RastPort in whose Arealnfo structure

the new polygon pixel should be placed.
Coordinates of the pixel.

Result:

Status:

See Also:

AreaEnd(),AreaEllipse(),AreaMove(),InitArea()

Returns 0 if the data for the polygon was accepted by

the Arealnfo sttucture, or -1 if insufficient memory
existed for the new pixel.

\AreaEllipse
Syntax:

Defines ellipse in AreaInfo structure\

Status = AreaEllipse (RastPort, Xm, Ym, Xr, Yr)
DO

-186

Al

00

01

02

03

LONG
Status;
struct RastPort *RastPort;
SHORT
Xm,Ym;
SHORT
Xr,Yr;

Description:

This function defines the data for a filled ellipse in the Arealnfo
structure of the given RastPort.

Parameters:

RastPort:
Xm, Ym:
Xr, Yr:

Result:

Status:

Address of the RastPort in which the filled ellipse

should be drawn.
Coordinates of the ellipse's midpoint.
X and Y radii of the ellipse to be drawn.
Returns 0 if the data for the ellipse was accepted by the
Arealnfo structure, or -1 if the data was rejected.

See Also:

390

AreaEnd() ,InitArea ()

6.6 THE GRAPHICS LIBRARY

ABACUS

IAreaEnd
Syntax:

Draws polygons, circles or ellipsesl

Status = AreaEnd (RastPort)
DO

-264

Al

struct RastPort *RastPort;

Description:

This function draws and fills a polygon created using AreaMove ()

and AreaDraw ()'. Or it draws the determined ellipse with the help of
AreaEllipse () and fills the surface with the current fill pattern.

Parameter:

RastPort:

Address of the RastPort whose AreaInfo structure

was created using AreaMove () ,AreaDraw () ,
AreaCircle() ,orAreaEllipse () .

Result:

Status:

Returns status of the AreaEnd () function, or -1 if

insufficient memory is available for filling the area.

Comments:

Because AreaEnd () draws and fills the polygon/circle/ellipse, the

TmpRas structure must be initialized in addition to the AreaInfo
structure.

See Also:

AreaDraw(),AreaMove(),AreaEllipse(),InitArea(),
InitTmpRas ()

AreaMove
Syntax:

Defines start of

01

on in AreaInfo

Status = AreaMove (RastPort, x, y)

DO

-252

Al

DO 01

struct RastPort *RastPort;

SHORT
x,y;

Description:

This function defines the starting point of a new polygon. Previously

created polygons are ended using AreaMove ( ) .

Parameters:

RastPort:

Address of the RastPort in which a new polygon should

be drawn.

x, y:

Starting coordinates of the new polygon.

Result:

Status:

Returns -1 if insufficient memory exists for the

operation.

See Also:

AreaDraw(),AreaEllipse(),AreaEnd(),InitArea()

Disa bles borderl

IBNDRYOFF

Syntax:

BNDRYOFF (RastPort)
(Macro)
struct *RastPort;

391

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This macro clears the AREAOUTLINE flag in the given RastPort,

suppressing the drawing of borders.

Parameter:

RastPort:

Comments:

If you want to draw border lines, set the AREAOUTLINE bit in the
Flags variables of the RastPort (AREAOUTLINE is defined in

Address of the RastPort in which the AREAOUTLINE

bit should be cleared.

graphics/rastport.h).

Flood

IFlood
Syntax:

Flood (RastPort, Mode, x, y)

-330
A I , D2
DO,DI
struct RastPort *RastPort;
ULONG
Mode;
SHORT
x,y;

Description:

This function fills enclosed areas.

Parameters:

RastPort:

Mode:

x, y:

Comments:

filii

Address of the RastPort in which a continuous surface

should be filled.
Test for the enclosed area. If Mode=O, the surface fills
with the current fill pattern in the current color, which
is bordered by a border line in the color of AOlPen
(SetOPen). When mode is 1 the continuous surface
receives a new color that has the color of the pixel in
the given coordinate.
Starting coordinates for fill within the RastPort. The
pixel color of this coordinate corresponds to the one
when Mode == 1.

The RastPort in which a surface should be filled by means of

Flood () must contain a completely initialized TmpRas structure.
Because the Area commands also use the Flood command, a
TmpRas structure must be present when you use it

See Also:

InitArea

InitTmpRas(),SetOPen()

Initializes AreaInfo structure

Syntax:

InitArea (Arealnfo, Buffer, NumPixels)

-282
AO
Al
DO
struct Arealnfo *Arealnfo;
APTR
Buffer;
SHORT
NumPixels;

Description:

This function initializes an Arealnfo structure and makes a RastPort

available. This must be done before you can use the Area functions.

392

ABACUS

6.6 THE GRAPHICS LDRARY

When this structure is initialized through this function. you specify the
address of the coordinates buffer. which must be NumPoints * 5
bytes. so that it will accommodate a UBYTE array consisting of the
number of comer points used in the polygon. For example. at least 25
bytes must be allocated in the coordinates buffer for a four-point
polygon 4+1*) 5 bytes).
The AreaEllipse () function needs two coordinates. One ellipse
requires a buffer of at least 15 bytes (2*5 bytes for the ellipse itself
plus 1*5 bytes for AreaEnd
When you have initialized the
Arealnfo structure using InitArea (). you must add this with
RastPort .Arealnfo = Arealnfo in the RastPort.

(.

Parameters:

AreaInfo:

Buffer:

Address of the Arealnfo structure to be initialized.

Address of the buffer for storing polygon/ellipse/circle
data.

NumPixels:
See Also:

Number of pixels required in the Arealnfo structure.

AreaDraw().AreaEnd().AreaEllipse().AreaMove()

hnitTmpRas
Syntax:

Initializes TmpRas structurel

ITmpRas = InitTmpRas (TmpRas, Buffer, BufferSize)
DO

-468

AD

Al

DO

struct TmpRas *ITmpRas;

struct TmpRas *TmpRas;
APTR
Buffer;
LONG
BufferSize;

Description:

This function initializes a TmpRas structure. Flood () and Area

functions all use the TmpRas structure. This operates in conjunction
with the recursive fIll algorithm. also used by Flood ( ) .
This recursive fIll algorithm checks the size of the buffer allocated for
the operation. This must contain as many bytes as are found in a
rectangular area covering the largest area to be fIlled. Creating a buffer
the size of the RastPort's bit-plane or bit-map.
After invoking I ni t TmpRa s () the initialized structure must be added
to the RastPort (RastPort . TmpRas = TmpRas). Unfortunately.
each RastPort must have its own completely initialized TmpRa s
structure. Multiple RastPorts cannot share a single TmpRas structure.

Parameters:

TmpRas:
Buffer:

BufferSize:

TmpRa s structure to be initialized.

Address of the memory to be assigned to the TmpRas
structure.
Buffer size in bytes.

393

6.

THE AMIGA LIBRARIES

Result:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ITmpRas:

Returns the address of the initialized TmpRa s structure.

This address is identical to the address of the structure
(ITmpRas = TmpRas). The TmpRas structure can
also be given in the RastPort: RastPort. TmpRas

InitTmpRas

( ).

Fills a rectanglel

IRectFiII
Syntax:

RectFill (RastPort, xl, yl, x2, y2)

-306

Al

DO

D1

D2

D3

struct RastPort *RastPort;

SHORT
x1,y1,x2,y2:

Description:

This function fills a rectangle using the current drawing mode, color
pen and fill pattern. As soon as the AREAOUTLINE bit is set in the
RastPort . F 1 a g variables a border line appears around the filled
rectangle in the color of the OPen.

Parameters:

RastPort:

Address of the RastPort in which the rectangle should

be drawn.

xl, yI, x2, y2:

Upper left (xl, yI) and lower right (x2, y2) coordinates
of the rectangle. Make sure that the upper left corner
coordinates are above and to the left of the lower right
coordinates, or a system crash will occur.
Comments:

When working in COMP LEMENT mode, all of the bit-planes are rotated
in the rectangle, as well as those selected using the APen.

See Also:

BNDRYOFF ()

ISetAfPt

Sets fill patternl

Syntax:

SetAfPt (RastPort, Pattern, NumLines)

(Macro)
struct RastPort *RastPort
UWORD
Pattern[];
SHORT
NumLines:

Description:

This function defines a fill pattern accessed by the RectFill () ,

Flood () and Area () functions. You can specify either a single
color fill pattern drawn in the APen color in the current drawing mode,
or a multicolor fill pattern.

Parameters:

RastPort:
Pattern:
NumLines:

394

Address of the RastPort structure to be given a new fill

pattern.
Bit pattern of the fill pattern.
Height of the fill pattern. Only heights that are powers
of 2 (0, 1, 2, 4, 8, ... ) are allowed. Instead of absolute

6.6 THE GRAPHICS LIBRARY

ABACUS

height, you give the power in base 2 that corresponds

to the heighL Multicolor fill patterns use an exponent
preceded by a minus sign. The fill array must then
make a bit pattern available for each bit-plane.
Example:

The following call assigns a multicolor fIJI pattern with a height of 16

pixels to the RastPort
WORD Pattern[NumBitPlanes] [16];
SetAfPt (&RastPort, Pattern, -4);

ISetOPen

Defines border color pen

Syntax:

SetOPen (RastPort, Co1orPen)

(Macro)
struct RastPort *RastPort;
SHORT
ColorPen;

Description:

This macro specifies the border pen color.

Parameters:

RastPort:

Address of the RastPort whose border pen should be

changed.
Number of the color register used when drawing with
the border pen.

ColorPen:

Comments:

This macro (found in graphics/gfxmacros. h) is used in

conjunction with RectFill (), Flood (), and the Area ()
functions. While it takes an active part in R e c t Fill () and
Area ... () , the OPen (or AOIPen) tests the perimeter of the area to
be filled.

See Also:

BNDRYOFF ()

Structures:

Offset

Structures
struct Arealnfo <graphics/gfx.h>
{

OxOO 0
Ox04 4
Ox08 8
OxOc 12
Ox10 16
Ox12 18

SHORT *VctrTbl;
/* Vector table */
SHORT *VctrPtr;
/* Next free vector */
BYTE *FlagTbl;
BYTE *FlagPtr;
SHORT Count;
/* Number of vectors to count */
SHORT MaxCount;
/* Maximum numbere of vectors */
SHORT FirstX,
FirstY;/* First coordinate {AreaMove( */

Ox14 20
Ox16 22
Ox18 24

struct TmpRas <graphics/rastport.h>

{

OxOO
Ox04
Ox08

0
4
8

BYTE *RasPtr;
LONG Size;

/* Pointer to raster */
/* Size of raster */

395

6.

THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct RastPort
slroct Layer:
*Layer

f+

sttuct BitMap:
*BitMap

~
struct TmpRas

USHORT:
*AreaPtrn
struct TmpRas:
*TmpRas
Slroct AreaInfo:
*AreaInfo

struct AreaInfo

......

SHORT:
*Vctr'Ibl

UBYIE:
Mask

SHORT:
*VctrPtr

BITE:
FgPen

BYJE:
*F1agTbl

BITE:
BgPen

BYIE:
*F1agPtr

BITE:
AOIPen

SHORT:
Count

BYIE:
DrnwMode

SHORT:
MaxCount

BY1E:
AreaPtSz

SHORT:
FirstX
Firsty

USHORT:
LinePtm
SHORT:
cP_x

CPJ

396

BYlE:
*RasPtr
LONG:
Size

6.6 THE GRAPHICS LmRARY

ABACUS

6.6.4

Colormap functions

FreeColorMa

Frees memor

from ColorMa

Syntax:

FreeColorMap (ColorMap)
-576
AD
struct ColorMap *ColorMap;

Description:

This function releases the memory allocated for the Colo rMa p
structure. When you allocate memory for a color table using
GetColorMap () , you must free this memory before ending the
program using the FreeColorMap () function. This ensures that
other applications have access to as much memory as possible.

Parameter:

ColorMap:

See Also:

GetColorMap ()

Pointer to the ColorMap structure to be freed.

IGetColorMap

Allocates memory for ColorMap structure!

Syntax:

ColorMap = GetColorMap (NunColors)

DO
-570
DO
struct ColorMap *ColorMap;
LONG
NunColors;

Description:

This function allocates memory for a ColorMap structure, which can

then accept NumColors color entries.

Parameter:

NumColors:

The number of color entries actually contained in the

ColorMap structure.

Result:

ColorMap:

Returns a pointer to the newly initialized ColorMap

structure, given by (ViewPort. ColorMap
ColorMap) in the ViewPort. This allows the
computation of the Copper lists used by this
ColorMap.

See Also:

!GetRGB4
Syntax:

FreeColorMap ()

Reads color entry from ColorMap!

Color = GetRGB4 (ColorMap, ColorRegister)
DO
-582
AD
DO
ULONG
Color;
struct ColorMap *ColorMap;
LONG
Col orRegi ster;

397

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This function determines the color combinations used in a single color

displayed in the ViewPort. For this you give the number of the color
register whose color palette entry you want to read (0-31) in the color
register.

Parameters:

ColorMap:

Address of the ColorMap structure from which you

want to read the color entry.

ColorRegister:
Number of the color register that you want to read
(values range from 0 to 31).
Result:

Color:

Word corresponding to the color of the color register

being searched. The value in the Color variable is
coded as follows:
Red components = (Color8) & Oxf
Green components = (Color4) & Oxf
Blue components = (ColorO) & Oxf

Color returns a value of -1 (Oxffff) if the color register

number is less than or greater than the 0--31 range.

Comments:

You must give the address of a ColorMap structure in GetRGB4 () .

If you have not added this to a ViewPort and created the Copper list, the
colors of the ColorMap are not returned.

See Also:

GetColorMap(), LoadRGB4(),GetRGB4(),SetRGB4CM(),
MrgCop () , LoadView ()

ILoadRGB4

Syntax:

Initializes ColorMapl
LoadRGB4 (ViewPort, ColorPalette, ColorEntries)
-192

AD

A1

DO

struct ViewPort *ViewPort;

awORD
ColorPalette[ColorEntries);
SHORT
ColorEntries;

Description:

This function creates a color palette with different color entries in the
ColorMap of the specified ViewPort. This adds the colors to the
ColorMap only; they are not visible in the ViewPort. The sequences
MakeVPort (), MrgCop () and LoadView () must first be called

to display the colors in the ViewPort.

Parameters:

398

ViewPort:

Address of the ViewPort whose colors should be

changed.
ColorPalette: Color entries written in the corresponding color register
after creating the Copper list.
ColorEntries: The number of color entries that should be placed in the
ViewPort's color palette.

6.6 THE GRAPHICS LIBRARY

ABACUS

See Also:

GetRGB4 (),SetRGB4 ()

ISetRGB4
Syntax:

Changes color entries/color registersl

SetRGB4 (ViewPort, ColorRegister, Red, Green, Blue)
-288

AO

DO

D1

D2

D3

struct ViewPort *ViewPort;

SHORT
n;
UBYTE
Red, Green, Blue;

Description:

This functicn assigns a new cclor value to a cclcr register ccntained in

a ViewPcrt. SetRGB4 () transfers this cclcr value intc the
ColorMap .of the ViewPcrt, recalculates the Ccpper list and makes
the colcr change visible immediately.

Parameters:

ViewPcrt:
Address .of the ViewPcrt to be changed.
CclcrRegister:
Number .of the colcr register to be changed.
Red, Green, Blue:
Cclcr ccmpcnents. The Amiga creates cclcrs by
ccmbining the basic cclcrs red, green and blue in
different prcporticns. Values for each colcr component
range frcm 0 to 15, resulting in 16"3, .or 4096, possible
cclcr combinaticns.

See Also:

LoadRGB4 () , GetRGB4 () , SetRGB4CM ( )

ISetRGB4CM
Syntax:

Changes color entry in a COlorMapl

SetRGB4CM (ColorMap, ColorRegister, Red, Green, Blue)
-630

AO

DO

D1

D2

D3

struct ColorMap *ColorMap;

SHORT
ColorRegister;
UBYTE
Red, Green, Blue;

Descripticn:

This functicn assigns a new cclor value to a cclcr register ccntained in

a ColorMap. Unlike SetRGB4 () , the Copper list recalculation does
nct occur, nor does the cclcr change immediately appear .on the screen
since the new value is nct added to the ViewPort. This functicn is best
applied in creating ColorMaps that dc nct need tc be displayed
immediately.

Parameters:

CclcrMap:
Address .of the ColorMap to be changed.
CclcrRegister:
Number .of the cclcr register tc be changed.
Red, Green, Blue:
Cclcr ccmponents. The Amiga creates cclcrs by
combining the basic cclors red, green and blue in
different proporticns. Values fcr each cclor component

399

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

range from 0 to 15. resulting in 161'3. or 4096. possible

color combinations.
See Also:

SetRGB4 ()

Structures:

Offset

Structures
struct ColorMap <graphics/view.h>
{

OxOO
OxOl
Ox02

0
1
2

Ox04

Ox08

UBYTE Flags;
UBYTE Type;
{)WORD Count;
/* number of the color entry */
APTR colorTable;
/* Address of the color table */

SIrUtt VOPm:

r'

*Nat
stnII:IOhMap:
*Cci1lMap

*Ncxt

SlrUttCopI.isl:

SprIns

sInEI CopliI:
*(]rIlE

SlnllSUCoplil:
*UCopIns:
SHORT:

UBYl'E:
UBYl'E:

SlnldCoklMap:
~

....
Copliat ....

SInId

T~

SprlDs

UWoo.

SInIIS Coplist:

*OrIns:

....

Am:
CdllTaIK

llUctuo.,lii:
*UCopIns:

....

...

SHORT:
!1NiII

SHORT:
DxOlkt

SHORT:

DxOfkt

MIkt

UWORD:
Modal

Mla

*RasInfo

...

*~Im

Cowl

DIfjgbI

SIrUQ RBnfo:

....

SlnldOJpUat

...

I1!V1dIh

400

sInEI CDIlMap

...... Hap
Copliat ....

*~
SIIUCt

Ib1II% VoM

UW<iD:

r+

IIII1ia RasIDfo:

*Raslnfo

f.+

6.6

ABACUS

6.6.5.

THE GRAPHICS LIBRARY

Blitter functions
BUts rectangle between bit-mapsl

IBItBitMap
Syntax:

BitPlanes
DO

BltBitMap (SourceBitMap, xl, yl, DestBitMap,

AD
DO Dl
Al
x2, y2, Width, Height, Minterm, Mask, Buffer)
D2 D3
D4
D5
D6
D7
A2
ULONG
BitPlanes;
struct BitMap *SourceBitMap;
SHORT
xl,yl;
struct BitMap *DestBitMap;
SHORT
x2,y2;
SHORT
Width, Height;
UBYTE
Minterm, Mask;
PLANEPTR
Buffer;

Description:

This function blits a rectangle from a source bit-map to a rectangle of

the same size, either in the same bit-map or a different bit-map.
Blitting is more than copying; it can also logically combine the source
and destination rectangles.

Parameters:

SourceBitMap:

xl, yl:
DestBitMap:
x2, y2:

Pointer to the bit-map from which the data should be

read.
Upper left comer coordinates of SourceBi tMap's
rectangle.
Pointer to the bit-map to which the data should be read
or combined.
Upper left comer coordinates of DestBi tMap's
rectangle.

Width, Height:

Minterm:

Size of the rectangle being bUtted.

Variable which specifies the operation performed by the
bUtter when creating the destination rectangle. Because
B1 tBi tMap () can only join two bit-maps together,
only the top four bits of this parameter are used:
BC (B and C)

Ox80
Ox40

!C)

(B and Not (C) )

BC (!B and C)

(Not (B) and C)

= Ox20

Bp (!B and

(Not (B) and (Not(C

BC (B and

!C)

OxlO

401

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

B represents Sou rceBi trnap and C represents

DestBi trnap. Using each of these four Minterrns
you can copy data or combine the data with information

already in the destination rectangle through an AND

operator. For example, if you assign OxCO to
Minterrn, the function copies the data from the source
rectangle of the source bit-map to the destination
rectangle of the destination bit-map. The equation for
this operation is (B and C) or (B and ! C) . You
can replace the and with a multiplication symbol (*)
and the 0 r with an addition sign (+):
(B * C)+(B * !C) (don't forget parenthesis!)

After substitution the equation looks like this:

B * (C + !C)
(C + ! C) can be replaced by the number 1 so that
only B remains. That's how you can calculate the
connection table for all 16 Minterrns.

Mask:

Buffer:

Result:

BitPlanes:

Parameter mask which specifies the accessible

bit-planes of the two bit-maps. Only the bit-planes for
which the corresponding bit is set are included in the
blit (bit O=Bi tMap. Planes [0] (ftrst bit-plane), bit
I=Bi tMap. Planes [2] (second bit-plane), etc.).
Points to a memory location the size of one line of a
bit-plane within a bit-map. If the destination and source
bit-maps are identical, the two bit-maps may overlap in
some places. The data for the blit is temporarily stored
in Buffer. If Buffer is too small, the BitPlanes
variable (see Result below) returns -1.
Returns the number of bit-planes accessed by the blit.
or -1 if Bu f fer is too small to accommodate the data

inserted.

See Also:

402

ClipBit ()

6.6 THE GRAPHICS LIBRARY

ABACUS

IBItBitMapRastPort

Blits rectangle from bit-map I

Syntax:

BltBitMapRastPort (SourceBitMap, xl, yl, DestRastPort,

-606
AO
DO Dl
Al
x2, y2, Width, Height, Minterm)
D2 D3
D4
DS
D6
struct BitMap
*SourceBitMap;
SHORT
x1tyl;
struct RastPort *DestRastPort;
SHORT
x2,y2;
SHORT
Width, Height;
UBYTE
Minterm;

Description:

This function blits a rectangle from a source bit-map in a RastPort.

Blitting is more than copying; it can also logically combine the source
and destination rectangles. The RastPort specifies which bit-planes
should be blitted (see also RastPort . Mask).

Parameters:

SourceBitMap:
Pointer to the bit-map from which the data should be
read.
xl, yl:
Upper left corner coordinates of SourceBi tMap's
rectangle.
DestRastPort: Pointer to the RastPort to which the data should be read
or combined.
Upper left corner coordinates of DestRastPort's
x2, y2:
rectangle.
Width, Height:
Size of the rectangle being blitted.
Minterm:
Variable which specifies the operation performed by the
Blitter when creating the destination rectangle (see
B 1 t Bit Map () for more information about
Minterm).
Mask::
Parameter mask which specifies the accessible
bit-planes of the two areas. Only the bit-planes for
which the corresponding bit is set are included in the
blit (bit O=Bi tMap. Plane s [0] (first bit-plane), bit
l=BitMap. Planes [2] (second bit-plane), etc.).

See Also:

IBItClear
Syntax:

BltBitMap ()

Clears specified memory range/

BltClear (MemBlk, NumBytes, Flags)
-300
Al
DO
Dl
APTR Memblk;
ULONG NumBytes;
ULONG Flags;

403

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This function clears memory up to the given absolute address using the
APTR (Absolute memory PoinTeR, compatible with PLANEPTR
[pLANE PoinTeR]). The memory range must be Chip accessible and
located in less than 512K.

Parameters:

Memblk:
NumBytes:
Flags:

Address of the memory region to clear.

Number of bytes to be cleared.
Flags which indicate the number of bytes to clear. If bit
I (=2) of the Flags parameter is set, the function reads
the top 16 bits of NumBytes as the number of rows to
be cleared, and the bottom 16 bits as the number of
bytes per row of a rectangle to be cleared. If bit I of the
Flags parameter is cleared, NumBytes gives the
number of bytes to be cleared. Bit 0 of Flags indicates
whether the program should pause until the Blitter is
done clearing memory.

IBItMaskBitMapRastPort

Blits through a maskl

Syntax:

BltMaskBitMapRastPort (SourceBitMap, Xl, Yl, DestRastPort,

-636
AO
DO Dl
Al
X2, Y2, Width, Height, Minterm, BltMask)
D2 D3
D4
D5
D6
A2
struct BitMap
*DestBitMap;
SHORT
XI,YI;
struct RastPort *RastPort;
SHORT
X2,Y2;
SHORT
Width, Height;
UBYTE
Minterm;
APTR
BltMask;

Description:

This function blits a rectangle from a bit-map into a RastPort, using a

mask. This mask is actually a bit-plane, which acts as a pattern for
controlling the Blitter operation: Any set pixels in the Bl tMask are
allowed through the mask for the blit, while any clear pixels will not
penetrate the mask.

Parameters:

SourceBitMap:
Pointer to the bit-map from which the data should be

read.
xl, yl:

Upper left comer coordinates of SourceBi tMap's

rectangle.
DestRastPort: Pointer to the RastPort to which the data should be read
or combined.
x2, y2:
Upper left comer coordinates of DestRastPort's
rectangle.
Width, Height:
Size of the rectangle being blitted.

404

6.6 THE GRAPHICS LIBRARY

ABACUS

Minterm:

Variable which specifies the operation performed by the

Blitter when creating the destination rectangle. The
Minterm variable for this function can have only two
values: OxeO for a true copy and Ox20 for an inverted

source.
BltMask:
See Also:

Address of the single-plane mask.

B1 tBi tMap ( )

IBItPattern
Syntax:

Fills rectangle using maskl

BltPattern (RastPort, Mask, xl, y1, x2, y2, NumBytes)
-312
A1
AD
DO D1 D2 D3
D4
struct RastPort *RastPort;
APTR
Mask;
SHORT
xl, y1,

x2, y2;
SHORT

NumBytes;

Description:

This function fills a rectangle using the current drawing mode, color
pen and fill pattern. The fIll pattern is transferred through a mask. This
mask is actually a bit-plane, which acts as a template for controlling
the fill operation. This mask is the same size as the rectangle being
blitted.

Parameters:

RastPort:
Mask:
xl, yl, x2, y2:

NumBytes:

See Also:

Address of the RastPort in which the B1tPattern ()

should occur.
Address of the single-plane mask.
Upper left (xl, yl) and lower right (x2, y2) coordinates
of the rectangle to be filled. Make sure that the upper
left comer coordinates are above and to the left of the
lower right coordinates, or a system crash will occur.
Mask width in bytes. For example, if you want to fill a
two-pixel-wide rectangle, enter a 1 here, which indicates
that each line of the mask is one byte (eight pixels)
wide. Mask width can only be a multiple of 8 (i.e., 8,
16, 24, 32, etc.).

B1tMaskBitMapRastport()

405

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

IBItTemplate

Reads data from packed arrayl

BltTemplate (Source, BitPosition, Modulo, RastPort, x,

Syntax:

-36

AO

DO

DI

Al

D2,

y, Width, Height)
D3

D4

DS

APTR
*Source;
SHORT
Bi tPosition;
SHORT
Modulo;
struct RastPort *RastPort;
SHORT
x,y;
SHORT
Width,Height;

Description:

This function reads a packed segment of data from a rectangular area

(Amiga developers call this area a cookie cur). Amiga fonts are packed
so that they can occupy any width, based on the height assigned to
them. The characters are packed bit by bit, without spacing, to
optimize memory. With Bl t Template () , it allows you to load this
data.

Parameters:

Source:
BitPosition:

Pointer to the start address of the packed data array.

The starting location of the characters within the data
array. When the bit pattern begins in the second byte,
Bi tPosi tion contains a value of 16.
The number of bytes that must be added to the current
bit position to execute the next line of the data.
RastPort to which the read data should be blitted.
Upper left coordinates of the rectangle to which the read
data should be written.

Modulo:
RastPort:
x, y:
Width, Height:

Character sizes that should be read from the data array.

Organization of a packed data aWl!
Sourc<:

Modulo = 6 Bytes
Byte 1

Byle 0

Byle 2

Byle 7
Byle 14

Byte 21

Byte 3

Byte 4

Appearance

x
I

406

---.t
..
I
I

I
I

...

Byle 6

Height = 9 Rows

+ +

Bit Position =2Dth Bit

Byle S

Width - 10 Bits

'n

IMPort

Byle 62

6.6 THE GRAPHICS LIBRARY

ABACUS

IclipBit

Blits rectangle between RastPortsl

Syntax:

ClipBit (SourceRastPort, xl, yl, DestRastPort, x2, y2,

-552
AO
DO Dl
Al
D2, D3,
Width, Height, Minterm)
D4
D5
D6
struct RastPort *SourceRastPort;
SHORT
xI,yI;
struct RastPort *DestRastPort;
SHORT
x2,y2;
SHORT
Width, Height;
UBYTE
Minterm;

Description:

This function blits a rectangle from a source RastPort to a rectangle of

the same size, either in the same RastPort or a different RastPort. The
clipping functions only when you use layers and ClipRects, or
when you use the function within an Intuition screen or window.

Parameters:

SourceRastPort:
Pointer to the RastPort from which the data should be
read.
xl, yl:
Upper left comer coordinates of SourceRastPort's
rectangle.
DestRastPort: Pointer to the RastPort to which the data should be read
or combined.
x2, y2:
Upper left comer coordinates of DestRastPort's
rectangle.
Width, Height:
Size of the rectangle being blitted.
Minterm:
Variable which specifies the operation performed by the
Blitter when creating the destination rectangle (see
BIt Bit Map () for more information about
Minterm).

See Also:

BltBi tMap ( )

DisownBlitter

Releases exclusive Blitter access

Syntax:

DisownBlitter ()

Description:

This function releases the Blitter from exclusive access, allowing other
programs or tasks to use the Blitter.

See Also:

ownBli t ter ()

OwnBlitter
Syntax:

Reserves Blitter for exclusive use

OwnBli t ter ()
-456

407

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

Description:

This function locks the Blitter into exclusive access mode (only one
task can use the Blitter, excluding all other tasks). WaitBlit ()
should be invoked before Blitter use. This forces the Blitter to wait on
executing OwnBli t ter () until any task currently running through
the Blitter is done.

See Also:

DisownBlitter(),WaitBlit()

Inserts BlitNode in Blitter queuel

IQBHt
Syntax:

QBlit (BlitNode)

-276
struct blitnode *BlitNode;

Description:

This function allows Blitter control through routines contained in the

Bli tNode structure of the Blitter job queue.

Parameter:

BlitNode:

Comments:

The assembly language routine placed in the queue should be written so

that it runs in user mode as well as supervisor mode. This type of
Blitter control has advantages over Own/DisownBlitter ()
method. When the program/task has executed OwnBlitter (), the
routine contained in the Bl i tN ode structure of the Blitter job queue is
executed.

See Also:

QBSBlit ()

Bli tNode structure inserted in the Blitter job queue.

When your job reaches the head of the queue, you have
exclusive access rights to the Blitter.

IQBSBlit

Inserts BlitNode in Blitter queuel

Syntax:

QBSBlit (BlitNode)
-294
struct blitnode *BlitNode;

Description:

This function allows Blitter control through routines contained in the

Bl i tNode structure of the Blitter job queue. The routine given in the
Bli tNode structure is called like the QBl it () function, except it
waits for the electron beam to reach a certain position before executing
the job.
This allows screen memory manipulation while the electron beam lies
outside of the visible screen area (e.g., the top of the bottom of the
screen). The routines are also beam synchronized, or synchronized with
the electron beam. Because all of these jobs are in a list which is
available for all programs and tasks, running problems can occur within
one or more tasks.

408

6.6 THE GRAPHICS LIBRARY

ABACUS

Parameter:

BlitNode:

See Also:

Qblit ()

Bli tNode structure to be inserted.

IWaitBlit

Waits until end

or

Blitter access I

Syntax:

WaitBlit ()

Description:

This command returns to your program or task when the blit, the
current blit operation, is completely done. Unfortunately you cannot
always get out of Wa i t B1 it ( ) . This is because a processor error
occurs in Agnus so that Wai tBli t () comes back although the blit
has actually not begun. This can happen especially when the Amiga is
running in HIRES with 4 bit-planes.

Structures:

Offset

Structures
struct bltnode <hardware/blit.h>
{

OxOO

Ox04

OxOB

OxOa 10
OxOc 12
OxOe 14

struct bltnode *n;

/* For chaining */
int (*function) ();
/* Pointer to executing function */
char stat;
/* Call cleanup routine */
/* ? stat = CLEANUP
*/
short blitsize;
short beamsync;
/* Position of the electron beam */
/* for synchronization.
*/
int (*cleanup) ();
/* Cleanup routine */

Ox12 IB

409

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct GfxBase
struct Library:
LibNode
struct View:
*ActiView
UWORD:

*WFList
UWORD:

*SHFList
struct bltnode:
*blthd
*blttl
struct bltnode:
*bsblthd
*bsblttl
struct List
*TextFonts
struct TextFont:
*DefaultFont

struct bltnode
struct bltnode:
*n
int:
(*function) 0
char:
stat

short:
bltsize
short:
beamsync

UBYfE:

SpriteReserved
struct List:
BlitWaitQ
struct Task:
*BlitOwner
struct SimpleSprite:
**SimpleSPrites

410

int:
(*cleanup) 0

6.6 THE GRAPmCS LIBRARY

ABACUS

6.6.6

Copper functions

ICBump
Syntax:

Increments user Copper list command pointer I

CBump (UCopList)

-366
Al
struct UCopList *UCopList;

Description:

This function increments the Copper command pointer to the next

Copper command's memory location. The programmer usually has
little need for this function because the macros CMove () , Cwai t ()
and CEnd () do everything necessary to place the desired command in
the user Copper list.

Parameter:

UcopList:

See Also:

CMove(),CWait,UCopListInit

User Copper list into which a command should be

entered.

ICEND

Indicates end or user Copper list!

Syntax:

CEND (UCopList)
(Macro)
struct UCopList *UCopList;

Description:

This macro from graphics/gfxmacros. h marks the end of the

user Copper list. Copper lists are saved in the lower 512K of the
Amiga, just like most applications that can be processed by the 68000
The CEnd () macro informs the Copper that no memory above the
Copper list should be executed.
CEnd () invokes CWait (UCopList, 10000, 255), which
means that before the Copper program can process again it must wait
for the electron beam to move to position 255, 10000. This ends the
Copper program, since the electron beam cannot move to position
255,10000.

Parameter:

UCopList:

See Also:

CMove(),CWait(),UCOpListInit()

User Copper list whose end should be marked.

411

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Writes value in hardware register

ICMove
Syntax:

CMove (UCopList, Register, Value)

-372
Al
DO
01
struct UCopList *UCopList;
APTR
Register;
SHORT
Value;

Description:

This function places a command in the user Copper list to write a

specific value to a specific hardware register. After this command is
placed in the user Copper list, you must increase the Copper list
program counter using CBump ( ) .

Parameters:

UCopList:

User Copper list in which the command should be

Register:
Value:

Hardware register to which Val ue should be written.

Value that should be placed in Register.

placed.

Comments:

Instead of using CMove () and CBump () you can use the macro
CMOVE () (graphics/gfxmacros. h). This macro is called using
the same parameters as CMove ( ) .
You can also invoke CWa i t () to wait for a certain electron beam
position, and then change a register (e.g., color register). You may not
fill all of the hardware registers with the Copper.

See Also:

UCopListlnit(),CWait

ICWait

Waits for electron beam positionl

Syntax:

CWait (UCopList, Y, X)
-378
Al
DO, 01
struct UCopList *UCopList;
SHORT
Y,X;

Description:

This function places a command in the user Copper list to ensure that
the Copper program waits on the processing until the electron beam
reaches the specified position. If the electron beam has already passed
the specified position, the program continues with the Copper program.

Parameter:

UCopList:

User Copper list in which the command should be

placed.
Y,X
Comments:

412

Y and X coordinates which the electron beam must

reach before the Copper commands may continue.

The x parameter should be no greater than 222. Also, instead of the

combination Cwai t () , CBump () you can use the macro CWAI T ()
(graphics/gfxmacros. h). This is called using the same
parameters as Cwai t () .

6.6 THE GRAPHICS LIBRARY

ABACUS

See Also:

CMove(),CWait(),UCOpListlnit()

Frees memor

ia intermediate Co

Syntax:

FreeCopList (CopList)
-546
AO
struct coplist *CopList;

Description:

This function frees the memory location of a single intermediate

Copper list that was created by MakeVPort () . The user does not
normally need to call this function because FreeVPortCopList ()
ensures that all of intermediate Copper lists of a ViewPort are freed.

Parameter:

CopList:

See Also:

FreeVPortCopLists()

Pointer to the intermediate Copper list the user wants

released.

Frees memor

or hardware Co

Syntax:

FreeCprList (CprList)
-564
AO
struct cprlist *CprList;

Description:

This function frees memory that was allocated by the executed Copper
list (View. LOFCprList, View. SHFCCprList).

Parameter:

CprList:

See Also:

MrgCop ()

Hardware Copper list to be freed.

IFree VPortCopLists

Frees ViewPort Copper listsl

Syntax:

FreeVPortCopLists (ViewPort)
-540
AO
struct ViewPort *ViewPort;

Description:

This function frees all of the intermediate Copper lists of a ViewPort

The ViewPort can accommodate multiple intermediate lists. One of
these lists handles color display, one handles sprite display, etc.
FreeVPortCopLists () also frees user Copper lists.

Parameter:

ViewPort:

ViewPort whose intermediate Copper lists should be

freed.

See Also:

MakeVPort (),FreeCopList ()

413

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

I&.; I;.; n;.; i.;.tV.. ;. .;.ie;;.w,;.;. . _________________I;; .;n; ;.;i;.; h;.;a;.;;l;.;;iz;.;;e..;;,s_View

structurel
Syntax:

InitView (View)
-360
Al
struct View *View;

Description:

This routine clears all variables and initializes a View structure. Then
the variables DxOffset and DyOffset, which control the position
of the View on the screen, initialize so that the View's position moves
1/2" from the upper left comer of the screen when the monitor and
Preferences are correctly set
The starting address of the current Copper lists is saved in this View
structure. One list is always in use (View. LOFCprList) and another
comes into service only when interlace mode is invoked
(View. SHFCprList). When using a resolution mode (HIRES or
LACE) remember that a ViewPort arranged within a View can only use
the resolution mode that is set in the View.

Parameter:

View:

See Also:

MrgCop ()

View structure to be initialized.

InitVPort

Initializes ViewPort structure

Syntax:

InitVPort (ViewPort)
-204
AD
struct ViewPort *ViewPort;

Description:

This function clears all variables and initializes a ViewPort structure.

The ViewPort iS,a section of the graphic interface used for actual
display. It acts as 'an interface to the bit-map in which the graphics are
saved, and to the ColorMap in which the colors are saved.
Intermediate Copper lists must be set (MakeVPort () ) before the
presentation can begin. After that each list must be merged with one
another (M r g Cop ( ) , after which they can be displayed
(LoadView ( ) ).

Parameter

ViewPort:

See Also:

MakeVPort(),MrgCop(),LoadView()

ViewPort structure to be initialized.

ILoadView
Syntax:

414

Starts View displayl

LoadView (View)
-222
Al
struct View *View;

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This function loads and executes hardware Copper lists. The

MakeVPort () and MrgCop () functions calculate these lists before
execution. Most modes, use one list, while interlace mode uses two
hardware Copper lists. The starting addresses of these lists appears in
the hardware register copllc (and cop21c if the system is running
in interlace mode).

Parameter:

View:

See Also:

InitView(), InitVPort (),MakeVPort(),MrgCop()

Address of the View structure for which the hardware

list(s) are calculated.

IMakeVPort

Calculates Copper lists of a ViewPort!

Syntax:

MakeVPort (View, ViewPort)

-216
AD
A1
struct View
*View;
struct ViewPort *ViewPort;

Description:

This function calculates the intermediate Copper lists for a ViewPort

The ViewPort can accommodate multiple intermediate lists. One of
these lists handles color display, one handles sprite display, etc. The
individual Copper lists must be merged together using the MrgCop ( )
function, after which they are executable using the LoadView ()
function. If you want to display multiple ViewPorts in a View, you
must call MakeVPort () for each ViewPort.

Parameters:

View:
ViewPort:

See Also:

MrgCop(),LoadView()

View to which the ViewPort is secondary.

Address of the ViewPort structure from which the
intermediate Copper lists should be calculated, based on
the DxOffset and DyOffset values of the View.

Calculates hardware Copper list!

IMrgCop
Syntax:

MrgCop (View)
-210
A1
struct View *View;

Comments:

This function calculates the hardware Copper list based on the

intermediate Copper lists of the ViewPort. This ViewPort information
is drawn from View.

Parameter:

View:

See Also:

MakeVPort(),LoadView()

Address of the View structure from which the hardware

Copper list should be calculated.

415

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Recalculates Copper listsl

IScrollVPort
ScrollVPort (ViewPort)

Syntax:

-588

AD

struct ViewPort *ViewPort;

Description:

This function recalculates the Copper list for the ViewPort and adds the
result to the hardware Copper list. After you change some variables in
the ViewPort structure or in the Ra sIn f 0 structure, the
Scroll VP 0 rt () function offers a simple method of making the

changes.
Parameter:

ViewPort:

Address of the ViewPort for which the Copper list

should be recalculated.

IUCopperListlnit
Syntax:

Initializes a user Copper list\

UCopList = UCopperListlnit (CopperList, NumberCommands)
-594

AD

DO

struct UCopList *UCopList;

struct UCopList *CopperList;
SHORT
NumberCommands;

Description:

This function re-initializes a previous user Copper list (Copperlist

! =0) or inserts a new one (Copperlist == 0).

Parameters:

CopperList:
Pointer to the user Copper list to be re-intialized.
NumberCommands:
The number of commands to be placed in the user
Copper list.

Result:

UCopList:

Comments:

This function can also be called using the CINIT () macro (found in
graphics/ gfxmacros . h) . The syntax remains the same.

Returns an initialized U Cop Lis t

CopperList equals zero.

structure if

When accessing the user Copper lists you must remember that these are
given in the ViewPort in which they should be presented
(ViewPort.UCoplns = UCopListorViewPort.UCoplns =
CopperLi st). Then you must only calculate the Copper lists
(MakeVPort () ,MrgCop () ).
See AlSO:

CBump (), CMove (), CWait ()

IVBeamPos
Syntax:

Reads electron beam position\

Position

VBeamPos()
-384

ULONG Position;

416

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This function returns the current position of the electron beam that is
responsible for drawing the video image. Unfortunately you cannot be
100% certain about the result from this function during multitasking.
because multitasking returns slightly inaccurate results. The most
accurate result (up to one line) is returned if you run your task at the
highest priority.

Result:

Position:

Vertical position of the electron beam.

!WaitBOVP

Waits until ViewPort is displayed!

Syntax:

WaitBOVP (ViewPort)
-402
AO
struct ViewPort *ViewPort;

Description:

This function returns to your program or tasks when the electron beam
displayed the last raster line of the given ViewPort (Bottom Of
ViewPort).

Parameter:

ViewPort:

Address of the ViewPort waiting for display.

!WaitTOF

Waits at top of frame!

Syntax:

WaitTOFO
270

Description:

This function waits at the Top Of Frame (TOF) for the electron beam
to return. The electron beam travels between the bottom of the screen
and the top. displaying nothing. The ViewPort display begins at the
frrst line after the TOF. You can direcdy change the bottom line of the
screen after wai t TOF () without an immediately visible change. The
task with the highest priority executes immediately after Wa it TOF ( ) .

Structures:

Offset

Structures

---------struct UCopList

<graphics/copper.h>

OxOO

Ox04
Ox08
OxOc

4
8

struct
/*
struct
struct

UCopList *Next;
For linking */
CopList *FirstCopList;
CopList *CopList;

12
struct CopList

<graphics/copper.h>

OxOO

Ox04
Ox08

OxOc

12

struct
/*
struct
struct
/*
struct

CopList *Next;
For linking */
CopList *_CopList;
ViewPort * ViewPort;
Interface to ViewPort *1
CopIns *CopIns;
1* Copper instructions *1
1* Linked list *1

417

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

OxlO
Ox14

16
20

Ox18

24

Oxlc

28

Oxle

30

Ox20

32

Ox22

34

struct CopIns *CopPtr;

UWORD *CopLStart;
/* Long frame start */
UWORD *CopSStart;
/* Short frame start */
/* Interlace * /
SHORT Count;
/* Number of Copper ins taken */
SHORT MaxCount;
/* Max. number of Copper ins */
SHORT DyOffset;
/* Starting electron beam position */
/* of the Copper list.
*/
struct cprlist <graphics/copper.h>
{

OxOO

Ox04

Ox08

OxOa

10

struct cprlist *Next;

/* for linking */
UWORD *start;
/* Start of the Copper list */
SHORT MaxCount;
/* number of commands */
struct ViewPort <graphics/niew.h>
{

OxOO

Ox04

Ox08

OxOc

12

OxlO

16

Ox14

20

Ox18
Oxla

24
26

OxIc
Oxle

28
30

Ox20

32

Ox22
Ox23
Ox24

34
35
36

Ox28

40

struct
/*
struct
/*
struct
/*
struct

ViewPort *Next;
For linking */
ColorMap *ColorMap;
Address of the ColorMap */
CopList *DspIns;
Display instructions */
CopList *SprIns;
1* Sprite instructions */
struct CopList *ClrIns;
/* Color instructions */
struct UCopList *UCopIns;
/* User instructions */
SHORT DWidth,
DHeight;
/* Size of the ViewPort */
SHORT DxOffset,
DyOffset;
/* Position of the ViewPorts */
UWORD Modes;
/* Display mode */
UBYTE SpritePriorities;
UBYTE reserved;
struct RasInfo *RasInfo;
/* Interface to the bit-map */
struct RasInfo <graphics/view.h>
{

418

OxOO

Ox04

Ox08
OxOa

8
10

struct RasInfo *Next;

/* For DUALPF */
struct BitMap *BitMap;
/* Address of the bit-map */
SHORT RxOffset,
RyOffset;
/* Bitmap position, */

6.6 THE GRAPHICS LIBRARY

ABACUS

1* relative to ViewPort *1
OxOc 12
struct View
{

OxOO

Ox04

Ox08

OxOc
OxOe

12

Ox10

16

Ox14

20

struct ViewPort *ViewPort;

1* Address of the first ViewPort *1
struct cprlist *LOFCprList;
1* Long frame Copper list *1
struct cprlist *SHFCprList;
1* Short frame Copper list *1
short DxOffset,
DyOff!'et;
1* View position on the monitor *1
UWORD Modes;
1* Display mode *1

14

IInJCt VicwPat

tVnPut
IInJCt qlliit

r1

~
-S

=
mt

UWORD:
Mocb

..

IInJCt VnPut
IInJCtVnl'cJrt
~

f+

IInJCt CdorMIp:

"Co\mMIp
IInJCt Co!i.iII:

"DIp"
IInJCt Co!i.iII:

Sp'D

IInJCt Co!i.iII:

tClrlDl:

IInJCt Cqi.iIt

IInJCt Co!i.iII:
~

r+

IInJCt CopIDI:

r+

UWatD:

~1IIt

IInII:I UCcd.iII
*U~IDI:

1InII:I~

Li

IInJCt qlliit

*NcJd

UWORD:
*SWt

SmRT:
MuCamt

-capIDI

UWORD:
*CopSSIIn

SHOKI':
DWidIh

SmRT:

c-

DIJciaI'

SmRT:
MaCama

SHOKr:
IhOIIic:t
o,oDiI:t

SmRT:
D,OIfIat

UWORD:
Mocb
IInICI RaIDfo:

*Ra1Dfo

......IInJCt RaInfo

IIr1Ic:IRaInfo:

*Nm
IInJCt BWap:

IInII:I UCqi.iIt

IIInII:IUCopLiII:
*Next
IInICI CopLiII:

*FinICopLiIt
I1nICt CopLiII:

tCopLiIt

-..
-..

-+

-..

SHORT:
RxOffIct
R)Oftic:t

r+
419

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

6.6.7

Layer functions

!AndRectRegion

ANDs clipping rectanglesl

Syntax:

AndRectRegion (Region, Rectangle)

-504
AO
Al
struct Region
*Region;
struct Rectangle *Rectangle;

Description:

This function combines clipping rectangles in a region into one region.

After accessing AndRectRegion () only the remaining rectangle in
the region is available for drawing.

Parameters:

Region:
Rectangle:

See Also:

OrRectRegion(),XorRectRegion(),OrRegionRegion()

Region in which the rectangles should be ANDed.

Clipping rectangle that should be ANDed.

!AndRegionRegion

ANDs two regions!

Syntax:

Status = AndRegionRegion (Regionl, Region2)

DO
-624
AD
Al

Description:

This function removes a section from Region2 not contained in

Regionl (Region2 == Region2 AND Regionl).

Parameter:

Regionl, Region2:
Regions to be ANDed.

!AttemptLockLayerROm

Obtaining access to layer!

Syntax:

Status = AttemptLockLayerRom (Layer)

DO
-654
AS

Description:

This function tries to gain exclusive access right to a layer. If the layer
is unlocked, At temptLoclLayerRom obtains exclusive access.

Parameter:

Layer:

Address of the layer to be accessed.

Result:

Status:

Returns FALSE if the layer is locked, and TRUE if the

layer is unlocked.

420

6.6 THE GRAPHICS LIBRARY

ABACUS

IClearRectRegion
Syntax:

Clears a clipping rectanglel

Status

ClearRectRegion (Region, Rectangle)

DO

-522

AD

Al

BOOL
Status;
struct Region
*Region;
struct Rectangle *Rectangle;

Description:

This function clears a clipping rectangle from the specified region.

Parameters:

Region:
Rectangle:

See Also:

Address of the region from which the rectangle should

be cleared.
Address of the rectangle to be cleared.

ClearRegion ()

IClearRegion
Syntax:

Clears a region I
ClearRegion (Region)
-528

AD

struct Region *Region;

Description:

This function clears all of the clipping rectangles in the specified

region, disabling any drawing functions that may follow in a layer.

Parameter:

Region:

See Also:

AndRectRegion () , OrRectRegion ()

Region from which the rectangles should be cleared.

!copySBitMap
Syntax:

Copies superbitmap to layer bit-mapl

CopySBitMap (Layer)
-450

AO

struct Layer *Layer;

Description:

This function copies a section of the superbitmap of a LAYERSUPER

layer into the bit-map presented by the layer. After calling
Sync SBi tMap ( ) , you can use the superbitmap graphic operations
without worrying about the ClipRects of the layer. After that you
should call CopySBitMap ().

Parameter:

Layer:

See Also:

SyncSBitMap ()

Address of the LAYERSUPER layer.

IDisposeRegion
Syntax:

Frees region memoryl

DisposeRegion (Region)

-534

AD

struct Region *Region;

421

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Description:

This function frees the memory for all of the rectangles of the specified
region and frees the region memory itself. It also frees the region that
was previously allocated using NewRegion () .

Parameter:

Region:

See Also:

NewRegion ()

Address of the region to be freed.

ILockLayerRom
Syntax:

Secures access rights to layerl

LockLayerRom (Layer)

-432

AS

struct Layer *Layer;

Description:

This function prevents another program or task from making changes

to the specified layer.

Parameter:

Layer:

Comments:

This routine is identical to the LockLayer () function found in the

layers library.

See Also:

UnLockLayerRom()

Address of the layer that should be locked.

INewRegion

Allocates new regionl

Region = NewRegion ()

Syntax:

DO

-516

struct Region *Region;

Description:

This function allocates and initializes a new region, returning a pointer

to the region. The OrRectRegion function ensures that clipping
rects are accepted in this region.
Only drawing is allowed in these clipping reets. This operates only in
conjunction with the layers that use BeginUpdate () and
EndUpdate ().

Result:

Region:

See Also:

OrRectRegion ( ) , DisposeRegion ()

Pointer to an initialized Region structure.

ion
Syntax:

Inserts cli
Status = OrRectRegion (Region, Rectangle)
-510

AO

BOOL
Status;
struct Region
*Region;
struct Rectangle *Rectangle;

422

Al

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This function adds a clipping rectangle to the specified region. After the
RectRegion function inserts the rectangle, it can be manipulated
using AndRectRegion () and XorRectRegion () .

Parameters:

Region:
Rectangle:

Address of the region in which a rectangle should be

inserted.
Rectangle structure to be inserted.

Result:

Status:

See Also:

AndRectRegion(),XorRectRegion()

Returns lRUE if enough memory was present for this

operation and FALSE if insufficient memory existed.

IOrRegionRegion

ORs two regions togetherl

Syntax:

Status = OrRegionRegion (Region1, Region2)

DO
-612
BOOL Status;
struct Region *Region1, *Region2;

Description:

This function transfers screen sections of Regionl not contained in

Region2 into Region2 (Region2 = Regionl I Region2).

Parameter:

Region!, Region2:
Regions to be ORed.

Result:

Status:

See Also:

NewRegion () , Di sposeRegion ()

Returns lRUE if enough memory was present for this

operation and FALSE if insufficient memory existed.

ISYDCSBitMap
Syntax:

Copies bit-map to superbitmapl

SyncSBitMap (Layer)
-444

AO

struct Layer *Layer;

Description:

This function copies the presented bit-map to the corresponding

location of the superbitmap specified by the LAYERSUPER layer.
Graphic operations can then be executed in the superbitmap without
having to worry about the ClipRects.

Parameter:

Layer:

See Also:

CopySBi tMap ( )

Address of the LAYERSUPER layer.

423

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

IUnloekLayerRom

Free layerl

UnlockLayerRom (Layer)

Syntax:

-438

AS

struct Layer *Layer;

Description:

This function unlocks a layer previously locked into exclusive access

by the LockLayerRom () function. When the layer locks an
Intuition window, UnLockLayerRom () frees it so that Intuition
can manage window sizing again.

Parameter:

Layer.

Warning:

The number of LockLayerRom () calls must equal the number of

UnLockLayerRom () calls.

Comments:

LockLayerRom () and UnLockLayerRom () are identical to the

layers library functions LockLayer () and UnLockLayer () .

See Also:

LockLayerRom ( )

Address of the layer you want freed.

XorReetRe ion
Syntax:

ORs eli
Status

XorRectRegion (Region, Rectangle)

DO

-558

AD

Al

Status;
struct Region
*Region;
struct Rectangle *Rectangle;

BOOL

Description:

This function removes a clipping rectangle if contained in a region, and

inserts a clipping rectangle if absent from a region.

Parameters:

Region:
Rectangle:

Address of the region in which the rectangle should be

inserted.
Address of the rectangle that should be inserted.
Returns lRUE if enough memory was present for this
operation and FALSE if insufficient memory existed.

Result:

Status:

See Also:

OrRectRegion(),AndRectRegion()

ion
Syntax:

Exclusive ORs two re

XorRegionRegion (Regionl, Region2)

AD

Description:

424

Al

This function inserts data from Regionl into Region2 if the data
differs between the two regions, and clears the data from Region2 if
the data in Regionl is identical to the data in Region2.

6.6 THE GRAPHICS LIBRARY

ABACUS

Parameter:

Region I, Region2:
Addresses of the two regions that should be exclusive
oRedo

Result:

Status:

See Also:

OrRegionRegion()

Structures:

Offset

Returns TRUE if enough memory was present for this

operation and FALSE if insufficient memory existed.

Structure
struct Rectangle <graphics/gfx.h>
{

OxOO
Ox02

0
2

OxOIl
Ox06

II
6

Ox08

SHORT MinX,
MinY;
/* Upper left corner * /
SHORT MaxX,
MaxY;
/* Lower right corner */
struct RegionRectangle <graphics/regions.h>
{

OxOO
OxOIl

0
II

Ox08

OxlO

16

struct RegionRectangle *Next,

*Prev;
/* For linking */
struct Rectangle bounds;
/* size */
struct Region <graphics/region.h>
{

OxOO

Ox08
OxOc

8
12

struct Rectangle bounds;

/* Size */
struct RegionRectangle *RegionRectangle;

425

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct Region
struct Rectangle:
bounds

struct Rectangle
SHORT:
MinX
MinY

struct RegionRectangle:
*RegionRectangle

SHORT:
MaxX
MaxY

struct RegionRectangle

....
... struct RegionRectangle:
*Next
*Prev

struct Rectangle:
bounds

426

6.6 THE GRAPHICS LIBRAJty

ABACUS

6.6.8

Character display

IAddFont

Adds font to system font

.~

Syntax:

AddFont (TextFont)
-480
Al
struct TextFont *TextFont;

Description:

This function makes a font opened by OpenDiskFont () the system

font This font can then be opened using the OpenFont () functions.
Other programs or tasks can access this font without opening the
DiskFont library.

Parameter:

TextFont:

See Also:

RemFont(),OpenFont(),OpenDiskFont()

AskFont

TextFont structure of the font that should be added to

the system list.

Describes current font in RastPort

Syntax:

AskFont (RastPort, TextAttr)

-474
Al
AD
struct RastPort *RastPort;
struct TextAttr *TextAttr;

Description:

This function detennines the text attributes currently in use by the

given RastPort's font.

Parameters:

RastPort:
TextAttr:

See Also:

Set Font ()

Address of the RastPort that should be examined.

Address of the TextAttr structure that should be
filled with the text attributes of the actual font in the
RastPott.

IASkSoftStyle

Reads current font stylesl

Syntax:

FontStyle = AskSoftStyle (RastPort)

DO
-84
Al
ULONG
FontStyle;
struct RastPort *RastPort;

Description:

This function retmns the style(s) in use in the current font. Two style
types exist:

1.

Bit patterns of each character are set in their stylistic fonn

(italic. underlined. etc.).

427

6. THE AMIGA LIBRARIES

2.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Bit patterns of each character are set for normal display (no
italic, etc.).

The AskSoftStyle () function tells you the bit pattern as well as

reading the font's SoftStyles, which precede the specified RastPort.
The following styles exist:
FSF UNDERLINED = 1 (Underlined)
FSF-BOLD
= 2 (bold)
FSF ITALIC
= 4 (italics)
FSF NORMAL
= 0 (Normal characters)

The font style flags

graphics/text.h.

are defined

in

the include file

Parameter:

RastPort:

Address of the RastPort structure whose font styles

should be read.

Result:

FontStyle:

Font style flags set by SetSoftStyle () .

See Also:

SetSoftStyle ()

ICloseFont

Closes font!

Syntax:

CloseFont (TextFont)
-78
Al
struct TextFont *TextFont:

Description:

This function closes a font previously opened by the OpenFont () or

OpenDiskFont () functions. If the font is not entered in the system
font list, the function releases the memory allocated for the font.

Parameter:

TextFont:

See Also:

OpenFont ( ) ,AddFont ( )

Pointer to the TextFont structure of the font to be

closed.

IOpenFont
Syntax:

Opens fontl
TextFont = OpenFont (TextAttr)
DO

-72

AO

struct TextFont *TextFont:

struct TextAttr *TextAttr;

Description:

428

This function opens a font in the system font list. The TextA t t r
structure describes the desired font as closely as possible. This structure
contains the font names (e.g., TextAttr.ta_Name
" Top a z . Fan t "), the size or height (e.g., 9 lines,
TextAttr. ta_YSize = 9) and the text type that the font should
havee.g.,TextAttr.ta_Style = Underlined).

6.6 THE GRAPHICS LIBRARY

ABACUS

When a font with the given name is found but the height and text type
differ from all of the available fonts, the function opens the font that
most closely matches the description given.
Parameter:

TextAttr:

TextAttr structure which describes the font

Result:

TextFont:

Pointer to a completely initialized TextFont structure.

See Also:

CloseFont(),AddFont(),RemFont()

IRemFont
Syntax:

Removes font from system font list!

RemFont (TextFont)

-486

Al

struct TextFont *TextFont;

Description:

This function removes a font from the system font list. All programs
or tasks that currently have access to the font release their access. If a
task tries to access this font using OpenFont () , the system denies
access.When all tasks indicate that they no longer need the font (using
CloseFont () ), the system frees the memory used by the font.

Parameter:

TextFont:

See Also:

AddFont ()

Address of the TextFont structure that should be

removed from the system font list.

ISetFont
Syntax:

Set font in RastPort!

Set Font (RastPort, TextFont)

-66

Al

AD

struct RastPort *RastPort;

struct TextFont *TextFont;

Description:

This function controls text output after you have opened a font using
OpenFont () or OpenDiskFont () by assigning the new font to

the current RastPort

Parameters:

RastPort:
TextFont:

Address of the RastPort that should receive the new

output font.
Address of the TextFont structure that tests the new
output font.

Comments:

Mter initializing the RastPort, the system defaults to the Topaz.font

which is also used in the CLI window.

See Also:

OpenFont(),CloseFont()

429

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ISetSoftStyle

Sets a new text typel

Syntax:

NewTextType = SetSoftStyle (RastPort, Text Type, DTextType)

DO
-90
A1,
DO,
D1
ULONG
NewTextType;
struct RastPort *RastPort;
ULONG
Text Type;
ULONG
DTextType;

Description:

This function assigns a new text style to the font used by Text () .
Only the text styles whose bits are set in DTextTypes can be
algorithmically generated.

Parameters:

RastPort:
TextType:
DTextType:

Address of the RastPort whose font should be displayed

in a new text style.
Mask of possible text types (see AskSoftStyle).
Desired text style in which the given characters should
appear through Text ( ) . The font style flags (see
AskSoftStyle ( specify the desired text style.

Result:

NewTextType:
Text types set by SetSoftStyle () .

See Also:

AskSoftStyle ()

Structures:

Offsets

Structures
struct TextAttr <graphics/text.h>
(

OxOO

Ox04

Ox06

Ox07

Ox08

STRPTR ta Narre;
/* Font narre * /
UWORD ta YSize;
/* Height */
UBYTE ta Style;
/* Text style */
UBYTE ta Flags;
/* Font preference flags */
struct TextFont <graphics/text.h>
(

430

OxOO
Ox14

0
20

Ox16

22

Ox17

23

Ox18
Ox1a
Ox1c
Ox1e

24
26
28
30

Ox20
Ox21

32
33

struct Message tf_Message;

UWORD tf YSize;
/* H;ight */
UBYTE tf_Style;
/* Bit pattern text style */
UBYTE tf_Flags;
/* Font preference flags */
UWORD tf_XSize;
UWORD tf_Baseline;
UWORD tf_BoldSmear;
UWORD tf Accessors;
/* number of OpenFont() calls */
UBYTE tf LoChar; /* Smallest defined ASCII Code */
UBYTE tf_HiChar; /* Largest defined ASCII Code */

6.6 THE GRAPHICS LIBRARY

ABACUS

Code Ox22
Ox26
Ox28

38
40

Ox2c

44

Ox30

48

Ox34

52

34

APTR tf CharData;/* Packed bit pattern

address*/
UWORD tf Modulo; /* Packed data array module */
APTR tf ChatLoc;
/* Bit pos. addresses of each character */
APTR tf CharSpace;
/* Character container size */
APTR tf CharKern;
/* Starting character inside character
container */

struct GfxBase
sttuct Ubrary:
UbNode
IIIrUct View:

SlIUct TextAtlr

*ActiView

UWORD:
*LOFLi.st

UWORD:
*SHFList

IIIrUct bItnode:

*b1thd
*bsblttl
struct b1tnode:

*bsblthd
*bsblttl

*SimpIeSPrites

UBYfE:
ta_Flags

SIIUct TextFont

...

UWORD:
tCYSize
UBYIE:
tCStyle
UBYIE:
tCFlags

struct List:
BlitWaitQ

SIl'Ilct SimpIeSprite:

UBYIE:
ty_Style

~
~

UWORD:
ta_YSize

...

UBYIE:
SpiteReserved

struct Tilt:
*BlitOwncr

ta_Name

struct List
*TextForu
sttuct TextFont:
*DefaultFom

S'mPl'R;

APIR:
OaData

~
~

f+

UWORD:
tCModulo
APIR:

tCOta-Loc

AP1R:

tCQwSpace

f.+

APIR:
tCOuI-Kern

r+
431

6. THE AMIGA LIBRARIES

6.6.9

ADVANCED SYSTEM PROGRAMMER'S GUIDE

GELs and sprites

Inserts AnimOb in GEL list!

\AddAnimOb
Syntax:

AddAnimOb (AnimOb, AnimKey, RastPort)

-156
AO
Al
A2
struct AnimOb
*AnimOb;
struct AnimOb
*AnimKey;
struct RastPort *RastPort;

Description:

This function inserts all bobs of an animation object in the previously

initialized GEL (Graphic ELement) list of the RastPort. The object can
then be drawn using the DrawGList () function.

Parameters:

AnimOb:
AnimKey:

RastPort:
See Also:

Pointer to the user-defmed animation object

Internal pointer to animation objects. It must be zero
on the first call. When using multiple animation
objects, AnimKey points to the animation object
inserted last
Address of the RastPort containing the Gelslnfo
structure.

Animate(),DrawGList()

IAddBob

Inserts bob in GEL list!

Syntax:

AddBob (Bob,RastPort)
-96
AO,
Al
struct Bob
*Bob;
struct RastPort *RastPort;

Description:

This function adds a bob (Bliller OBject) to the GEL list of a RastPort.

Parameters:

Bob:
RastPort:

See Also:

Address of the bob to be inserted.

Address of the RastPort containing the Ge 15 I n f
structure needed for the creation of the GEL list

AddVSprite(),DrawGList()

\AddVSprite
Syntax:

432

Inserts vsprite in GEL list!

AddVSprite (VSprite, RastPort)
-102
AO
Al
struct VSprite *VSprite;
struct RastPort *RastPort;

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This function inserts an initialized vsprite (virtual sprite) in the GEL

list of the given RastPort for later drawing.
You cannot display more than eight vsprites at a vertical position. Two
of these vsprites must be identical colors. This means that if you wish
to display sprites of different colors. you can only present a maximum
of four vsprites per raster line.

Parameters:

Vsprite:
RastPort:

See Also:

DrawGList ()

Address of the vsprites to be inserted into the GEL list.

Address of the RastPort in which the GEL list is
defined.

IAnimate

Animates animation objectsl

Syntax:

Animate (AnimKey, RastPort)

-162
AO
A1
struct AnimOb
*AnimKey;
struct RastPort *RastPort;

Description:

This function animates the animation object previously inserted using

the AnimOb () function. Variables used by AnimObs must be defined
before using animate. These variables specify data for the X and Y
positions of the AnimOb. speed of movement. different versions of the
AnimOb to simulate animation and more (see the Abacus book
Amiga Graphics Inside & Out for additional information on
AnimOb variables. as well as C language implementation of these
objects).

Parameters:

AnimKey:
RastPort:

See Also:
!changeSprite

Pointer to the AnimKey that may not be changed after

the last AddAnimOb () function.
Address of the RastPort which dermes the GEL list.

AddAnimOb ( )

Changes sprite's appearancel

Syntax:

ChangeSprite (ViewPort, Sprite, SpriteData)

-420
AO
A1
A2
struct ViewPort
*ViewPort;
struct Simple Sprite *Sprite;
struct SpriteDaten *SpriteData;

Description:

This function changes the appearance of a hardware sprite. The

Simp 1 e S p r i t e structure which contains the number of the
corresponding hardware sprite specifies which sprite should be changed.

433

ADVANCED SYSTEM PROGRAMMER'S GUIDE

6. THE AMIGA LIBRARIES

Unfortunately the SpriteData structure cannot be based in an

include file so that the user must deal with it himself through
programming. Look at the following structure:
struct SpriteData
{

UWORD posctl[2];
UWORD Daten [Height] [2];
UWORD Reserved[2]; 1* = 0,0 */

The data array in this structure which contains the actual twodimensional bit pattern of the sprite has other dimensions
corresponding to the bit pattern. This must be determined by the user.
Parameters:

ViewPort:

Sprite:
SpriteData:
See Also:

Address of the ViewPort if the sprite should be

positioned relative to the View or to the ViewPort, or a
value of zero.
Address of the SimpleSpri te structure which is
initialized by the GetSprite () function.
Address of the Spri teData structure that contains
the sprite's bit pattern.

GetSprite(),FreeSprite(),MoveSprite()

Tests GELs on collisions!

!DOCollision
Syntax:

DoCollision (RastPort)
-108
A1
struct RastPort *RastPort;

Description:

This function tests for GEL/GEL collisions that automatically call the
respective collision routine. The function should be called following
each gel movement.
GELs (bobs and sprites) must be sorted according to X and Y
coordinates in increasing order (SortGLi st () ).

Parameter:

RastPort:

See Also:

SortGList(),SetCollision()

Address of the RastPort that contains the Gelslnfo

structure containing the GELs.

!DrawGList
Syntax:

Displays GELs!
DrawGList (RastPort, ViewPort)
-114

Al

AO

struct RastPort *RastPort;

struct ViewPort *ViewPort;

434

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This routine draws all of the bobs of the given RastPort's GEL list and
creates the Copper lists for vsprite display. The vsprites do not appear
on the screen immediately after DrawGList () ; MakeVPort () ,
MrgCop () and LoadView () must be called after DrawGList () to
display the vsprites. MakeScreen () and RethinkDisplay () are
called for Intuition screens.

Parameters:

RastPort:
ViewPort:

See Also:

Pointer to the RastPort that contains the Ge 1 sIn f 0

structure.
Address of the ViewPort in which the vsprites should
appear, and for which the vsprite Copper lists should be
calculated.

MakeVPo rt ( ) , MrgCop ( ) , LoadView ()

IFreeGBurrers

Frees GEL buffersl

Syntax:

FreeC,13uffers (AnimObject, RastPort, DoubleBuffer)

-600
AO
A1
DO
struct AnimOb
*AnimObject;
struct RastPort *RastPort;
BOOL
DoubleBuffer;

Description:

This function frees all of the buffers of an animation object previously

allocated using GetGBuffers () .

Parameters:

AnimObject:

Address of the animation object for which the GEL

buffer was allocated using GetGBuffers () .
RastPort:
Address of the RastPort which defmes the Gel sIn f 0
structure.
DoubleBuffer: Indicates status of additional buffers used for storing
bobs. 1RUE indicates that a double buffer allocated by
GetGBuffers () has been freed.

See AlSO:

GetGBuffers(),InitGBuffers()

Returns sprite to systeml

IFreeSprite
Syntax:

FreeSprite (SpriteNumber)
-414
DO
SHORT SpriteNumber;

Description:

This function returns a sprite to the system from a program or task.

Parameter:

SpriteNumber:
Number of the sprite to be freed, as declared in
GetSprite ().

435

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Warning:

Do not attempt to free sprites that were not previously declared by you
using GetSprite ().

See Also:

GetSprite (),ChangeSprite (),MoveSprite()

Gets GEL buffers\

\ GetGBuffers
Syntax:

Status = GetGBuffers (AnimObject, RastPort, DoubleBuffer)

DO
-168
AO
A1,
DO
BOOL
Status;
struct AnimOh
*AnimObject;
struct RastPort *RastPort;
OOOL
DoubleBuffer;

Description:

This function allocates all of the buffers needed for the bobs of an
animation object. In addition to the SaveBuffer, the BorderLine
and the CollMask (
ImageShadow) functions,
DoubleBuffer == TRUE allocates, double buffering used by the
animation objects.

Parameters:

AnimObject:

Address of the animation object for whose bobs the

buffer should be allocated.
RastPort:
Address of the RastPort which defmes the GelSlnfo
structure containing the AnimObs and bobs.
DoubleBuffer: Indicates status of additional buffers used for storing
bobs. TRUE indicates that a double buffer allocated by
GetGBuffers () has been allocated in addition to
other buffers.

Result:

Status:

Comments:

You cannot guarantee that memory locations can be freed from all of
the previously allocated buffers. GetGBuffers() can also be used to
"refresh" memory.

See Also:

FreeGBuffers(),InitGBuffers()

Returns TRUE if enough memory could be allocated

from GetGBuffers () to provide memory for all of
the buffers.

IGetSprite

Allocates spritel

Syntax:

SpriteNumber = GetSprite (Sprite, DesSprite)

DO
-408
AO
DO
SHORT
SpriteNumber;
struct SimpleSprite *Sprite;
SHORT
DesSprite;

Description:

This function enables a hardware sprite, which can then be added to

your own applications.

436

6.6 THE GRAPHICS LIBRARY

ABACUS

Parameters:

Sprite:

Address of the Simp 1 e S p r i t e structure to be

allocated. This can be processed further using
ChangeSprite () and MoveSprite ().
Number of the sprite that you want used (0-7), or -1 if
the sprite number makes no difference to you.

DesSprite:
Result:

SpriteNumber:
Returns the number of the assigned sprite or the value
-1 if the desired sprite or no sprite at all could be

allocated.
Comments:

The Amiga reads the GfxBase. Spri teReserved variable to find

which sprites are allocated. GfxBase. SpriteReserved == 3
means that sprites 1 and 2 are already in use by other tasks. If you have
received an assigned sprite, pay attention to the sprite number because
FreeSprite () will need this number for freeing the sprite when the
program ends.

See Also:

FreeSprite(),ChangeSprite()

IInitAnimate

Initializes AnimKeyl

Syntax:

InitAnimate (AnimKey)
(Macro)
struct AnirrOb *AnimKey;

Description:

This macro assigns a value to the AnimKey parameter, which is on

the first call of AddAnimOb (). InitAnimate () can be found in
the include file graphics / gels. h.

Parameter:

AnimKey:

See Also:

AddAnimOb ( )

Address of the AnimKey that must be given with each

callofAddAnimOb() .

hnitGels
Syntax:

Initializes GEL list!

InitGe1s (ListStart, ListEnd, Ge1sInfo)
-120

AO

Al

A2

struct VSprite

*ListStart,
*ListEnd;
struct Gelslnfo *Gelslnfo;

Description:

This function initializes a Ge lsI n f 0 structure, which manages

vsprites and bobs in a user-defined v s p r i t e structure. All of the
Vsprite structures, including those from bobs and vsprites alike, are
organized into a linked list (GEL list).

437

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The v s p r it e structures are placed in a linked list to allow sorting

through SortGList () by Y and X coordinates. After initialization of
the Ge 1 sIn f 0 structure this must be added to the RastPort
(RastPort. Gelslnfo = Gelslnfo).
The AddBob () and AddVSpri te () fWlctions can be assigned the
RastPort structure instead of the Gelslnfo structure.
Parameters:

ListStart, ListEnd:
Addresses of the two Vspri te structures that represent
the start and the end of the GEL list These vspri te
structures cannot be used for bobs or vsprites.
GelsInfo:
the Gelslnfo structure to be initialized.

See Also:

SortGList ()

hnitGMasks

Initializes all GEL buffersl

Syntax:

InitGMasks (AnimationObject)
-174
AD
struct AnimOb *AnimationObject;

Description:

This function initializes all of the buffers previously allocated for the
bobs of an animation object. A double buffer parameter does not need
to be given here as with GetGBuffers () and FreeGBuffers () ,
because In i t GMa s k s () knows if the animation object or its bobs
require double buffer operation.

Parameter:

AnimOb:

See Also:

InitMasks(),GetGBuffers(),FreeGBuffers()

Address of the animation object whose buffer

(ImageShadow,CollMask,Borderline,ekJ
should be initialized.

InitMasks

Initializes bob or vs rite buffers

Syntax:

InitMasks (Vsprite)
-126
AD
struct VSprite *Vsprite;

Description:

This function initializes the different buffers of a bob or vsprite. The

border line of a bob/vsprite is confIgured so that all of the bit pattern
lines oCthe bob/vsprite are joined by OR and saved in BorderLine.
When a bob is used in the DoubleBuffer operation, all of the other
bobs must be supported by the Ge 1 sIn f 0 structure as well as the
DoubleBuffer operation.

438

6.6 THE GRAPHICS LIBRARY

ABACUS

The use of the bob in the DoubleBuffer operation is realized so

that each bob has a DBUfPacket allocated. This later contains the
saved background of the second bit-map, while SaveBuffer, like in
the normal operation, contains the background of the ftrst bit-map.
See Also:

InitGels ()

IMoveSprite

Moves a spritel

Syntax:

MoveSprite (ViewPort, Sprite, x, y)

-426
AO
Al DO Dl
struct ViewPort
*ViewPort;
struct SimpleSprite *Sprite;
SHORT
x,y;

Description:

This function places a sprite at the given position in the ViewPort,

when specifted. If the ViewPort is not specifted, the sprite is positioned
relative to the View. Unlike vsprites, the Copper lists do not have to
be recalculated for normal hardware sprites. This is done by the
MoveSpri te () and ChangeSpri te () functions. All sprites,
including vsprites, can only be moved around pixels the size of a lowresolution screen. Sprite resolution is the same as low resolution. If
you enable HIRES or LACE mode in your ViewPort, the size and
resolution of the sprites remains unchanged. To move a sprite away
you must give a minimum position change of two pixels.

Parameters:

ViewPort:

Sprite:
x,y:
See Also:

Address of the ViewPort in which the sprite should be

presented. Should the sprite be presented relative to the
View, enter a value of zero for the ViewPort.
Address of the SimpleSpri te structure that should
be written in closer to the moved sprite.
X and Y coordinates of the new sprite position.

ChangeSprite(),GetSprite()

IRemBob

Removes bob from screen I

Syntax:

RemBob (Bob)
(Macro)
struct Bob *Bob;

Description:

This macro suppresses display of the specified bob. The next

DrawGList () function call ignores the bob. This macro is defmed in
the include ftlegraphics / gels. h and ensures that the BOBSAWAY
flag is set in the bob.

Parameter:

Bob:

Address of the bob that should be ignored on the next

DrawGList () call.

439

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Comments:

Clearing the BOBSAWAY flag (Bob. flags

again displays the bob.

See Also:

AddBob()

&=-

BOBSAWAY;)

Removes bobs from screen and GEL list!

IRemIBob
Syntax:

RemIBob (Bob, RastPort, ViewPort)

-132
AO
Al
A2
struct Bob
*Bob;
struct RastPort +RastPort;
struct ViewPort *ViewPort;

Description:

This function removes a bob from the GEL list and the screen.
Removal from the screen is synchronized with the electron beam
location given by the ViewPort.

Parameters:

Bob:
RastPort:

ViewPort:
See Also:

Address of the bob to be removed.

Address of the RastPort in which the Ge 1 sIn f 0
structure is deflned.
Address of the ViewPort in which the bob is presented.

RemBob ()

IRem VSprite
Syntax:

Removes vspritesl
RemVSprite (VSprite)
-138

AD

struct VSprite *VSprite;

Description:

This function removes a vsprite from the GEL list and from the screen.
This happens immediately. as with RemIBob () but here you do not
have to give a ViewPort for electron beam synchronization. After
RemVSpri te () the corresponding Copper list is recalculated and the
electron beam synchronization compensates automatically.

Parameter:

VSprite:

See Also:

AddVSpri te ( )

SetCollision
Syntax:

440

Address of the vsprite that should be removed from the

GEL list. Because the GEL list consists of V s p rite
structures. no RastPort containing the address of the
Gelslnfo structure is needed.

Determines collision routine

SetCollision (Number, Routine, Gelslnfo)
-144
DO
AO
Al
ULONG
Number;
VOOID
(*Routine(
struct Gelslnfo *Gelslnfo;

6.6 THE GRAPHICS LIBRARY

ABACUS

Description:

This function inserts a routine that should be called when two GELs
collide, in the corresponding memory Gel sIn f 0 structure
(Gelslnfo. collHandler). After two GELs collide, an AND
combination joins the Hi tMask of one GEL and the MeMask of the
other GEL. The resulting bit indicates the number of the routine (0-15)
to which the program should jump. Routine 0 is always called when a
GEL collides with the border, determined by the variables
Gelslnfo.leftmost/rightmost/topmost/bottommost.
The remaining routines (1-15) specify the addresses of the v s p r i t e
structures in the collided GELs. Only routine 0 (GEUborder collision)
contains a pointer to the vsprite of the GEL, and a flag that designates
with which border the GEL has collided (LEFfHIT, RIGHTHIT,
TOPHIT, BOTIOMHIT-see graphics/collide .h).

Parameters:

Number:
Routine:
GelsInfo:

Number of the collision routine.

Pointer to the collision routine.
Pointer to the Gelslnfo structure of the GEL.

ISortGList
Syntax:

Sorts GEL list!

SortGList (RastPort)

-150

Al

struct RastPort *RastPort;

Description:

This function sorts the entries in the GEL list of the given RastPort.
The GELs are sorted so that those with the smallest Y coordinates are
at the beginning of the list and those with the largest Y coordinates are
at the end of the list If some GELS have matching Y coordinates, the
X coordinate is the deciding factor, and the X coordinates are also sorted
in increasing order. This sorting maintains optimum speed in accessing
hardware sprites for vsprite generation. The advantage to bobs is that
fewer bobs can be drawn before the electron beam, minimizing
flickering. The drawing is done from DrawGList () .

Parameter:

RastPort:

See Also:

DrawGList ()

Structures:

Offset

Address of the RastPort containing the GelSlnfo

structure storing bob and vsprite data.

Structures

struct VSprite <graphics/gels.h>

{

Oxoo
Ox04

0
4

Ox08

struct VSprite *NextVSprite;

struct VSprite *PrevVsprite;
/* For linking to the GEL List */
struct VSprite *DrawPath;
/* Presentation path */

441

6.

THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Ox1c

12

OxiO
Ox12

16
18

Ox14
Ox16
Ox18

20
22
24

Ox1a

26

Ox1c

28

Ox1e

30

Ox20
Ox22

32
34

Ox26

38

Ox2a
Ox2e

42
46

Ox32
Ox36

50
54

Ox37
Ox38

56
57

Ox3a

58

struct VSprite *ClearPach;

/* Clearing path */
WORD OldY,
OldX;
/* Old position */
WORD Flags;
WORD Y,
X;
/* Current position */
WORD Height;
/* Height */
WORD width;
/* width */
WORD Depth;
/* Depth (VSprite
1) */
WORD MeMask;
WORD Hi tMask;
/* Collision bits */
WORD *ImageData;
/* Address of bit pattern */
WORD *BorderLine;
WORD *CollMask;
/* Collision mask */
WORD *SVSprite */
struct Bob *VSBob;
/* Bob address */
BYTE PlanePick;
BYTE PlaneOnOff;
/* Which bit-planes are related */
VUserStuff VUserExt;
/* User-defined */
struct Bob <graphics/gels.h>
{

OxOO
Ox02

0
2

Ox06

OxOa
OxOe

10
14

Ox12

18

Ox16

22

Ox1a

26

Ox1e

30

WORD Flags;
WORD *SaveBuffer;
/* Address of background memory * /
WORD *ImageShadow;
/* OR all of the planes */
struct Bob *Before;
struct Bob *After;
/* Previously set character order */
struct VSprite *BobVSprite;
/* Address of the BobVSprite */
struct AnirrComp *BobComp;
/* Animation component addresses of Bob
sequence in an AnirrComp* /
struct DBuffPacket *DBuffer;
/* For use in DoubleBuffer BitMaps */
BUserStuff BUserExt;
/* User-defined */
struct DBufpacket <graphics/gels.h>
{

442

OxOO
Ox02

Ox04
Ox08

WORD BufY,
BufX;
/* Background position in second bit-map */
struct VSprite *Bufpath;
WORD *BufBuffer;
/* Address of background memory * /

6.6 THE GRAPHICS LIBRARY

ABACUS

OxOc

12
struct AnimComp <graphics/ge1s.h>

OxOO
Ox02
Ox04
Ox06
OxOa

0
2
4
6
10

OxOe
Ox12

14
18

Ox14

22

Ox1a
Ox1c

26
28

Ox1e

30

Ox22

34

Ox26

38

WORD Flags;
WORD Timer;
WORD TimeSet;
struct AnimComp *NextComp;
struct AnimComp *PrevComp;
/* For component linking */
struct AnimComp *NextSeq;
struct AnimComp *PrevSeq;
/* For linking sequences */
WORD (*AnimCRoutine) ();
/* Routine to be called */
WORD XTrans;
WORD YTrans;
/* Speed */
struct AnimOb *HeadOb;
/* Interface to AnimObject */
struct Bob *AnimBob;
/* Bob address */
struct AnimOb <graphics/gels.h>
{

OxOO
Ox04

0
4

Ox08
OxOc
OxOe

8
12
14

Ox10
Ox12

16
18

Ox14
Ox16

20
22

Ox18
Ox1a

24
26

Ox1c
Ox1e

28
30

Ox20

32

Ox24

36

Ox28

40

struct AnimOb *NextOb,

*PrevOb;
/* For linking */
LONG Clock;
WORD AnOldY,
AnOldX;
/* Old position */
WORD AnY,
AnX;
/* Current position */
WORD YVel,
XVel;
/* Speed */
WORD YAccel,
XAccel;
/* Acceleration */
WORD RingYTrans,
RingXTrans;
/* Ringtrigger speed */
WORD (*AnimORoutine) ();
/* Routine to be called */
struct AnimComp *HeadComp;
/* Address of first component */
AUserStuff AUserExt;
/* User-defined */
struct SimpleSprite <graphics/sprite.h>

OxOO

Ox04

Ox06
Ox08

6
8

UWORD *posctldata;
/* Address of the sprite data */
UWORD height;
/* Height */
UWORD x,
y;

/* Position */

443

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

OxOa

10

OxOc

12

UWORD num;
/* Number of the sprite */
struct Geslslnfo <graphics/rastport.h>
(

OxOO

Ox01
Ox02
Ox06

1
2
6

OxOa
OxOe

10
14

Ox12

18

Ox16
Ox18
Oxla
OxIc

22
24
26
28

OxIc
Ox22
Ox26

30
34
38

UBYTE SprRsrvd;
/* Reserved sprites */
UBYTE Flags;
struct VSprite *geIHead,
*geITail;
/* Beginning and end of GEL List */
WORD *nextLine;
WORD **lastColor;
/* VSprite colors presented last */
struct collTable *coIIHandler;
/* Collision Handler */
short leftmost,
rightmost,
topmost,
bottommost;
/* Rectangle for border collision */
APTR firstBlissObj,
lastBlissObj;
struct ColI Table <graphics/gels.h>
(

444

OxOO

Ox40

64

int (*coIIPtrs[16]) ();

/* 16 collision routine addresses */

6.6 THE GRAPHICS LIBRARY

ABACUS

SlIuct VSpite

SlIuct AnimComp

s1IuctBob

sIruct VSPrite:
*NextVS{rite

.. ...

WORD:
Flags

SInJct VSprite:
*PrevVSprite

WORD:
*SaveBuffer

WORD:
Tuner

WORD:
*ImageShadow

WORD:
TimeSet

SlructBob:
*Before

struct AnimComp:
*NextComp

struct AnimComp:
*PrevComp

WORD:
adY
0IdX

WORD:
Flags

slructBob:
*After

...

struct VSprite:
*BobVS{rite

struct AnimComp:
*NextSeq

SInJct AnimComp:
*BobComp

.......

struct AnimComp:
*PrevSeq

struct DBufPacket:
*DBuffer

WORD:
(*AnimCRoutine) (

WORD:
Y

X
WORD:
Heigbl
WORD:
WidIh
WORD:

WORD:
Flags

Deph

WORD:
XTrans

WORD:
MeMask
sIJuct AnimOb

WORD:

HitMask

WORD:
*ImageData
WORD:
*BorderLine
WORD:
CoIIMa*
WORD:
*SprColors

structBob:
*VSBob
BYl'E:
PlaDePick
BYl'E:
PIaneOnOff

...
....

..

struct AnimOb:
*NextOb

struct AnimOb:
*PrevQb

...
...

WORD:
YTrans
SIIUcl AnimOb:
*HeadQb

....

sIJuct Bob:
*AnimBob

-~

LONG:
Clock

... j
j

WORD:

WORD:
BufY
BufX

AnY

AnX
WORD:
YVel
XVel

struct VSprite:
*BufPath

WORD:
YAluJ

XAa:eI
WORD:
(*AnimORoutine) (
struct AnimComp:
*HeadComp

struct DBufPacket

...

WORD:
*BufBuffer

. . .1

....

..

445

6. THE AMIGA LIBRARIES

6.7

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The DiskFont library

The DiskFont library makes it possible to quickly and easily load
additional fonts from disk. There are two functions for this, to which
Kickstart1.3 adds two more functions.

DiskFont library functions

446
447
447
448

AvailFonts
DisposeFontContents
NewFontContents
OpenDiskFont

IAvailFonts
Syntax:

Creates list of available fontsl

Error = AvailFonts(Buffer,Length,Type)

DO

-36

AO

DO

01

LONG Error;
UBYTE *Buffer;
LONG Length;
LONG Type;

Description:

This function fills a data buffer with information about the fonts
available on disk or in memory. Disk fonts must be loaded using the
OpenDiskFont function, while fonts in memory can be opened with
the OpenFont function (graphics library).

Parameters:

Buffer:
Length:
Type:

Result:

446

Error:

Pointer to the data buffer. This fills with the

AvailFontsHeader structure.
Length of the data buffer in bytes.
Indicates the location of the fonts about which you
want information. The Type parameter can contain
AFF_MEMORY, AFF_DISK, or both. This system then
returns the fonts available in memory, on disk or in
both media.
Returns 0 if the function executes without an error, or
the number of bytes by which the data buffer fell short
in trying to load the information. This invalidates the
contents of the data buffer.

6.7 THE DISKFoNT LIBRARY

ABACUS

Comments:

If you give (AFF_MEMORY I AFF_ DISK) for the Type parameter,

the system examines fonts on disk as well as in memory. Some fonts
may be duplicated between memory and disk; the Type array indicates
this (see the TextAttr structure).
The AvailFonts function checks the FontContents file for the
font name, but it doesn't check the disk for the font file itself. If the
font is missing, opening the non-existent font using the
OpenDiskFont function returns an error message.

See Also:

FontsContents structure

IDisposeFontContents
Syntax:

Frees FontsContentsHeaderl

DisposeFontContents (FontContentsHeader)
-48

Description:

Al

This function frees the memory that was allocated by the

NewFontContents function.

Parameter:

FontContentsHeader:
Pointer to the FontContentsHeader structure
returned by the NewFontsContents function.

Warning:

If you state the address of a FontContentsHeader that is not

employed by the NewFontContents function, the system may

crash.
See Also:

NewFontContents

INewFontContents
Syntax:

Reads font datal

FontContentsHeader = NewFontContents(FontsLock,FontName)
DO

-42

AD

Al

Description:

This function adds a FontsContentsHeader structure in memory.

All data found in the directory passed by FontsLock, and whose
name reads FontName is saved in this structure.

Parameters:

FontsLock:

FontName:

Directory lock on the FontContents file and the

subdirectory containing the current font (usually the
FONTS directory).
Font filename plus a file extension of font, the
name of the FontContents file.

Result:

FontContentsHeader:
Pointer to the FontContentsHeader structure.

Exceptions:

If an error occurs (file not found, etc.), a value of zero is returned.

447

6. TIlE AMIGA LIBRARIES

See Also:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

DisposeFontContents

IOpeaDiskFont

Loads font from diskl

Syntax:

CharSet = OpenDiskFont (t.extAttr)

DO
-30
AO
struct Font *CharSet;
struct TextAttr *textAttr;

Description:

This function loads the font described by the TextAt t r structure from
disk and returns a pointer to this font. When the font is no longer
needed, call the CloseFont function to save memory. If the font
already exists in memory, the system returns a pointer without loading
the font a second time.

Parameter:

TextAttr:

TextAttr structure describing the font to be loaded.

Result:

CharSet:

Pointer to the font.

Exceptions:

If the font is not on disk or in memory, a value of zero is returned.

See Also:

CloseFont,SetFont

Structures:

struct FontContentsHeader <libraries/diskfont.h>

OxOO 0
Ox02 2
Ox04 4

1*

UWORD fch_FileID;
UWORD fch_NumEntries;

1* FCH_ID *1
1* Number of entries *1

struct FontContents fch_FC[); *1

};

struct FontContents <libraries/diskfont.h>

(

OxOOO
OxlOO
Ox102
Ox103
Ox104

0
256
258
259
260

char
UWORD
UBYTE
UBYTE

fc_FileName[MAXFONTPATH);
fc YSize; 1* Font height *1
fc=Style; 1* Text type *1
fc_Flags; 1* Font type *1

};

MAXFONTPATH 256
1* Inclusive null byte *1
FCH ID
OxOfOO
struct AvailFontsHeader <libraries/diskfont.h>
{

OxOO 0
Ox022

1*

UWORD afh_NumEntries;l* Number of entries *1

struct

AvailFonts afh_AF[); *1

};

struct AvailFonts <libraries/diskfont.h>

(

OxOO 0
Ox02 2
OxOA 10
};

448

UWORD af_Type;
1* MEMORY or DISK *1
struct
TextAttr af_Attr;

6.7 THE DISKFoNT LIBRARY

ABACUS

Type (af_Type):
AFF MEMORY 1
AFF DISK
2
struct TextAttr <graphics/text.h>
{

OxOO
Ox04
Ox06
Ox07
Ox08

0
4
6
7
8

STRPTR
{)WORD
UBYTE
UBYTE

ta_Name;
ta YSize;
ta::::Style;
ta_Flags;

/* Font height */
/* Text style */
/* Font type */

};

Text styles (ta_Style):

FS NORMAL
FSF EXTENDED
FSF ITALIC
FSF BOLD
FSF UNDERLINED

(13)
(12)
(11)
(10)

Character set-Typen (ta_Flags):

FPF ROMFONT (10) /* Font found in the ROM */
FPF DISKFONT (11) /* Font found on disk */
FPF REVPATH (12)
FPF TALLDOT (13) /* 640x200 resolution */
FPF_WIDEDOT (14) /* 320x400 resolution */
FPF PROPORTIONAL (15) /* Proportional font */
FPF::::DESIGNED (16)
FPF REMOVED (17) /* Font removed */
struct TextFont <graphics/text.h>
{

OxOO
Ox14
Ox16
Ox17
Ox18
Ox1A
Ox1C
OxlE
Ox20
Ox21
Ox22
Ox26
Ox28
Ox2C
Ox30
Ox34

o
20
22
23
24
26
28
30
32
33
34
38
40
44
48
52

struct Message tf Message;

tf YSize;
/* Character height */
UWORD
tf-Style;
UBYTE
tCFlags;
UBYTE
tf-XSize;
{)WORD
/* Character width */
tf-Baseline;
UWORD
UWORD
tf::::Bo1dSmear;
UWORD
tf Accessors;
tf-LoChar;
UBYTE
/* First character */
tf-HiChar;
UBYTE
/* Last character */
APTR
tf::::CharData;
UWORD
tf Modulo;
APTR
t f::::CharLoc;
APTR
tf_CharSpace;
tf_ CharKern;
APTR

};

449

6. THE AMIGA LIBRARIES

6.8

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The math libraries

The operating system of the Amiga gives you four different math
libraries: Two for single precision (FFP) numbers, and two for double
precision (IEEE) numbers. One contains the basic calculations needed,
and the other contains trigonometric functions.

6.8.1

The math library

This library offers two different floating-point numeric formats: FFP
and IEEE. The functions for FFP floating-point numbers are in the
math library and are the computing basics. When you program in C
you usually don't need to worry about special floating-point
calculations, because most C compilers include these functions in an
onboard math library.
Changing formats poses some problems. For example, the Aztec C
compiler allows global formatting for one module, while the earlier
versions of the Lattice C compilers didn't include this option (this was
corrected with Version 4.0 of Lattice C).
What do you do when you want to use both single precision and double
precision numbers in your program? You must use the libraries and
separate the elements of the equation. Amiga assembly language
accepts floating-point math much more easily than other computers,
where the programmer must program the functions on his/her own.
About the layout of these functions. Each function states a syntax, a
description of the function, the assembler condition code and any
additional data as needed.

450

6.8

ABACUS

THE MATH LIBRARIES

Math library functions

451
451
452
452
452
453
453
453
454
454
454

SPAbs
SPAdd
SPCmp
SPDiv
SPFix
SPFlt
SPMul
SPNeg
SPSub
SPTst
FFP

Absolute valuel

ISPAbs
Syntax:

result = SPAbs(value)
DO

-54

DO

FLOAT result;
FLOAT value;

Description:

Calculates an absolute value from value.

Assembler condition code:

N = 0

Z
V
C
X

= 1, if result = 0
= 0
= not defined
= not defined

Additionl

ISPAdd
Syntax:

result = SPAdd(value1,value2)
DO

-66

01

DO

FLOAT result;
FLOAT value1,value2;

Description:

Adds valuel and value2.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

451

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Compares two numbersl

ISPcmp
Syntax:

result = SPCmp(valuel,value2)
DO
-42
01
DO
LONG result;
FLOAT value1,value2;

Description:

Compares valuel with value2. The result is:

+1 if value1 < value2
o if value1 = value2
-1 if valuel > value2

Assembler condition code:

GT, i f
GE, if
EQ, if
NE, if
LT, if
LE, if

value2
value2
value2
value2
value2
value2

> value1
>= value1
= value1
<> value1
< value1
<= value1

ISPDiv

Divisionl

Syntax:

result = SPDiv(value1,value2)
DO
-84
01
DO
FLOAT result;
FLOAT value1,value2;

Description:

Divides value2 by value1.

Assembler condition code:

N
Z
V
C
X

=
=
=
=
=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

ISPFix

Converts FFP to integer formatl

Syntax:

result = SPFix(value)
DO
-30
DO
LONG result;
FLOAT value;

Description:

Converts an FFP number to an integer (two's complement).

Assembler condition code:

N
Z
V
C
X

452

<0
= if result = 0

= 1 if result

= if overflow

= not defined
= not defined

6.8 THE MATH LIBRARIES

ABACUS

ISPFIt

Converts integer to FFP formatl

Syntax:
result = SPFlt(value)
DO

-36

DO

FLOAT result;
LONG value;

Description:

Converts an integer (two's complement) to FFP format.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
0
not defined
not defined

!SPMul
Syntax:

Multiplication!
result = SPMul(valuel,value2)
DO

-78

Dl

DO

FLOAT result;
FLOAT valuel,value2;

Description:

Multiplies val uel by value2.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
if result = 0
if overflow
not defined
not defined

Swaps Dumber sign!

!SPNeg
Syntax:

result = SPNeg(value)
DO

-60

DO

FLOAT result;
FLOAT value;

Description:

Swaps the sign from

value:~

result

-value.

Assembler condition code:

N=
Z =
V=
C=
X=

1 if result < 0
if result = 0
0
not defined
not defined

453

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Subtractionl

ISPSub

Syntax:

result = SPSub(valuel,value2)
00
-72
01
DO
FLOAT result;
FLOAT valuel,value2;

Description:

Subtracts valuel from value2:---+

result

value2 -

valuel.

Assembler condition code:

N = 1 if result < 0
Z = if result = 0
V = if overflDw
C = not defined
X = not defined

Compares number with zerol

ISPTst

Syntax:

result = SPTst(value)
00
-48
01
LONG result;
FLOAT value:

Description:

Tests if val ue is zero. The result is:

+1 if value> 0
o if value = 0
-1 i f value < 0

Assembler condition code:

N = 1 if result < 0
Z = if result = 0
V

C = not defined
X = not defined

Formatl

Syntax:

MMMMMMMM MMMMMMMM MMMMMMMM SEEEEEEE

31 23 15 7

Meaning:

M = 24-bit mantissa
S = sign
E = 7-bit exponent

Value range (decimal):

9.22337177
-9.22337177

454

10~lB

10~IB

> +value > 5.42101070 * 10~-20

< -value < -2.71050535 * 10A-20

6.8 THE MATH UBRARIES

ABACUS

Value range (binary):

O.FFFFFF
-O.FFFFFF

6.8.2

2"'3F > +value > 0.800000 * 2"'-3F

< -value < -0.800000 * 2"-40

* 2"'3F

The MathTrans library

The MathTrans library gives you the transcendental functions needed for
single precision. Everything concerning format in the math library
applies here. Single precision floating-point numbers are usually in
FFP format.

MathTrans library functions

455
456
456
456
457
457
457
458
458
458
459
459
459

SPAcos
SPAsin
SPAtan
speos
SPCosh
SPExp
SPFieee
SPLog
SPLoglO
SPPow
SPSin
SPSincos
SPSinh
SPSqrt
SPTan
SPTanh
SPTieee
FFP

460
460
460

461
461
Calculates arccosinel

ISPACOS
Syntax:

result = SPAcos(value)
-120
DO
DO
FLOAT result;
FLOAT value;

Description:

Calculates the arccosine of value.

Assembler condition code:

N

Z = if result
V= 0

=0

455

6.

THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

C = not defined
X = not defined

ISPAsin

Calculates arcsinel

Syntax:

result = SPAsin(value)
DO
-114
DO
FLOAT result;
FLOAT value;

Description:

Calculates the arcsine of val ue.

Assembler condition code:

= 0
Z = if result = 0

N
V

C = not defined
X = not defined

ISPAtan

Calculates arctangent!

Syntax:

result = SPAtan(value)
DO
-30
DO
FLOAT result;
FLOAT value;

Description:

Calculates the arctangent of val ue.

Assembler condition code:

N = 0
z = i f result = 0
V= 0
C = not defined
X = not defined

IsPCos

Calculates cosinel

Syntax:

result = SPCos(value)
DO
-42
DO
FLOAT result;
FLOAT value;

Description:

Calculates the cosine of value.

Assembler condition code:

N

1 if result < 0

Z = 1 i f result
0
V = 1 if value is too large
C =

not defined

X = not defined

456

6.8 THE MATH LIBRARIES

ABACUS

Calculates hyperbolic cosinel

ISPCOSh
Syntax:

result = SPCosh(value)
DO
-66
DO
FLOAT result;
FLOAT value;

Description:

Calculates the hyperbolic cosine of val ue.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

Calculates e to the x power!

\SPExp
Syntax:

result = SPExp(value)
DO
-78
DO
FLOAT result;
FLOAT value;

Description:

Calculatese raised to the power of value.

Assembler condition code:

N = 0

Z = 1 if result = 0
V = 1 if overflow
C = not defined
X = not defined

Converts IEEE format to FFP\

\SpFieee
Syntax:

result = SPFieee(value)
DO
-108
DO
FLOAT result;
FLOAT value; /* IEEE standard format */

Description:

Converts simple precision IEEE standard format into FFP format.

Assembler condition code:

N
Z
V
C
X

=
=
=
=
=

not defined
1 if result = 0
1 if overflow
not defined
not defined

457

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Calculates natural logarithml

ISPLog
Syntax:

result = SPLog(value)
DO
-84
DO
FLOAT result;
FLOAT value;

Description:

Calculates the natural logarithm of value.

Assembler condition code:

N
Z
V
C
X

= 1 if result < 0
= 1 if result = 0
= 1 if value <= 0
= not defined

= not defined

ISPLogI0

Calculates base 10 logarithml

Syntax:

result = SPLog10(value)
DO
-126
DO
FLOAT result;
FLOAT value;

Description:

Calculates the base 10 logarithm of val ue.

Assembler condition code:

N = 1 if result < 0
Z = 1 if result = 0
V = 1 if value <= 0
C = not defined
X = not defined

Isppow

Calculates x to the y power

Syntax:

result = SPPow(value1,value2)
DO
-90
DO
D1
FLOAT result;
FLOAT value1,value2;

Description:

Calculates value! "value2.

Assembler condition code:

N = 0
Z = 1 if result = 0

V = 1 if overflow or value1 < 0

C = not defined
X = not defined

458

6.8 THE MATH LIBRARIES

ABACUS

ISPSin

Calculates sinel

Syntax:

result = SPSin(value)
DO
-36
DO
FLOAT result;
FLOAT value;

Description:

Calculates the sine of value.

Assembler condition code:

N=
Z=
V =
C=
X=

1 if result < 0
1 if result = 0
1 if value is too large
not defined
not defined

ISPSincos

Calculates sine and cosine I

Syntax:

result = SPSincos(value,adr_c)
DO
-54
DO
D1
FLOAT result;
FLOAT value,*adr_c;

Description:

Calculates the sine and cosine of val ue. Returns the sine immediately
and saves the cosine in the variable to which adr_ c points.

Assembler condition code:

N
Z
V
C
X

= 1 if result < 0

= 1 if result = 0
= 1 if value is too large

= not defined
= not defined

ISPSinh

Calculates hyperbolic sinel

Syntax:

result = SPSinh(value)
DO
-60
DO
FLOAT result;
FLOAT value;

Description:

Calculates the hyperbolic sine of val ue.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

459

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Calculates square root!

!SPSqrt
Syntax:

result = SPSqrt(value)
DO
-96
DO
FLOAT result;
FLOAT value;

Description:

Calculates the root of value.

Assembler condition code:

N = 0

Z
V
C
X

= 1 if result = 0
=

1 if value < 0

= not defined
= not defined

!SPTan

Tangent!

Syntax:

result = SPTan(value)
DO
-48
DO
FLOAT result;
FLOAT value;

Description:

Calculates the tangent of val ue.

Assembler condition code:

N
Z
V
C
X

=
=
=
=
=

1 if result < 0
1 if result = 0
1 if cos (value)
not defined
not defined

!SPTanh

Calculates hyperbolic tangent!

Syntax:

result = SPTanh(value)
DO
-72
DO
FLOAT result;
FLOAT value;

Description:

Calculates the hyperbolic tangent of value.

Assembler condition code:

N
Z
V
C
X

460

=
=
=
=
=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

6.8 THE MATH LIBRARIES

ABACUS

Converts FFP into IEEE format

ISPTieee

Syntax:

result = SPTieee(value)
DO
-102
DO
FLOAT result; /* Standard IEEE format */
FLOAT value;

Description:

Converts FFP format into simple precision standard IEEE format.

Assembler condition code:

N = 1 if result < 0

Z = 1 if result
V = not defined
C = not defined
X = not defined

=0

Format!

Syntax:

MMMMMMMM MMMMMMMM MMMMMMMM SEEEEEEE

31 23 15 7

Meaning:

M = 24 bit mantissa
S - sign
E = 7 bit exponent

Value range (decimal):

9.22337177
-9.22337177

* 10 A1B
* 10 A1B

> +value > 5.42101070 * 10A_20

< -value < -2.71050535 * 10A-20

Value range (binary):

O.FFFFFF * 2A3F > +value > O.BOOOOO * 2A-3F
-O.FFFFFF * 2A3F < -value < -0.800000 * 2A_40

461

6. THE AMIGA LIBRARIES

6.8.3

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The MathleeeDoubBas library

The MathIeeeDoubBas library gives you double precision math
functions. Double precision floating-point numbers are usually
expected in IEEE fonnat
Operating system Version 1.3 runs the functions of this library seven
times faster than before. In addition, this library then automatically
supports a 68881 coprocessor once such a processor is installed in the
system. A 68881 in conjunction with a 68020 is automatically
recognized (under Kickstart 1.2 as well). When you find the 68881
alone in the computer, it must be accessed through the
MathIEEE. resource of the operating system.

MathIeeeDoubBas library functions

IEEEDPAbs
IEEEDPAdd
IEEEDPCeil
IEEEDPCmp
IEEEDPDiv
IEEEDPFix
IEEEDPFloor
IEEEDPFlt
IEEEDPMul
IEEEDPNeg
IEEEDPSub
IEEEDPTst

hEEEDPAbS

463
463
464
464
464
464

465
465
465
466

Absolute valuel

Syntax:

result = IEEEDPAbs(value)
DO/Dl
-54
DO/Dl
DOUBLE result;
DOUBLE value;

Description:

Calculates the absolute value of value.

Assembler condition code:

N = 0

1 if result = 0
=0
C = not defined
X = not defined
Z

462

462
463

6.8 THE MATH LIBRARIES

ABACUS

IIEEEDPAdd

Additionl

Syntax:

result = IEEEDPAdd(value1,value2)
00/01
-66
00/01
02/03

Description:

Adds valuel and value2.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

IIEEEDPCeil

Smallest integer equivalent!

Syntax:

result = IEEEDPCeil(value)
00/01
-96
00/01
DOUBLE result;
DOUBLE value;

Description:

Finds the smallest integer greater than or equal to val ue.

Assembler condition code:

Unknown.

IIEEEDPCmp

Comparisonl

Syntax:

result = IEEEOPCmp(value1,value2)
DO
-42
00/01 02/03
LONG result;
DOUBLE value1,value2;

Description:

Compares valuel with value2. The result is:

+1 if value1 > value2
o if value1 = value2
-1 if value1 < value2

Assembler condition code:

GT
GE
EO
NE
LT
LE

if
if
if
if
if
if

value > value2

value! >= value2
value! = value2
value! <> value2
value! < value2
valuel <= value2

463

6.

THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Divisionl

hEEEDPDiv
Syntax:

result = lEEEOPOiv(value1,value2)
00/01
-84
00/01 02/03
DOUBLE result;
DOUBLE value1,value2;

Description:

Divides valuel by value2.

Assembler condition code:

N = 1 if result < 0

Z
V
C
X

= 1 if result = 0
= 1 if overflow

= not defined
= not defined

Converts IEEE to integer formad

hEEEDPFix
Syntax:

result = IEEEOPFix(value)
DO
-30
00/01
LONG result;
DOUBLE value;

Description:

Converts an IEEE number into integer format

Assembler condition code:

=
=
V =
C =

1 if result < 0
1 if result = 0
1 if overflow
not defined
X = not defined

N
Z

hEEEDPFloor

Largest whole numberl

Syntax:

result = IEEEOPFloor (value)

00/01
-90
00/01
DOUBLE result;
DOUBLE value;

Description:

Finds the largest whole number less than or equal to value.

Assembler condition code:

Unknown.
IEEEDPFIt
Syntax:

464

Converts integer to IEEE formad

result = IEEEDPFlt(value)
DO/D1
-36
DO
DOUBLE result;
LONG value;

6.8 THE MATH LIBRARIES

ABACUS

Description:

Converts an integer into IEEE format.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
0
not defined
not defined

hEEEDPMul

Multiplicationl

Syntax:

result = lEEEOPMul(value1,value2)
00/01
-78
00/01 02/03
DOUBLE result;
DOUBLE value1,value2;

Description:

Multiplies valuel and value2.

Assembler condition code:

N=
Z=
VC=
X=

1 if result < 0
1 if result = 0
1 if overflow
not defined
not defined

IIEEEDPNeg

Swaps number signl

Syntax:

result = IEEEOPNeg(value)
00/01
-60
DO/D1
DOUBLE result;
OOUBLE value;

Description:

Sign cbange:-+ result

-value.

Assembler condition code:

N=
Z=
V=
C=
X=

1 if result < 0
1 if result = 0
0
not defined
not defined

hEEEDPSub

Subtractionl

Syntax:

result = lEEEOPSub(value1,value2)
00/01
-72
00/01 02/03
DOUBLE result;
DOUBLE value1,va1ue2;

Description:

Subtracts val ue2 from val uel:-+ result

value2.

valuel

465

6. THE AMiOA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Assembler condition code:

N = 1 if result <
Z = 1 if result =
v = 1 if overflow
C = not defined
X = not defined

a
a

hEEEDPTst

Tests for zerol

Syntax:

result = IEEEOPTst(value)
DO
-48
00/01
LONG result;
DOUBLE value;

Description:

Tests if val ue is zero. The result is:

+1 if value>

if value = a
-1 i f value < a

Assembler condition code:

N = 1 if result <
Z = 1 if result =

v= a

a
a

C = not defined
X = not defined

Sb'Uctures:

MathlEEE.resource:
struct MathlEEE =
{

OxOO
OxOE
Ox10
Ox14
Ox18
OxIC
Ox20
Ox24
}

466

a
14
16
20
24
28
32
36

struct
UWORD
ULONG
ULONG
ULONG
ULONG
ULONG

Node MathIEEE node;

MathlEEE Flag;
MathlEEE-BaseAddr
;fUr 68881-Coprozessor
MathIEEE-OblBaslnit ;fUr andere
MathlEEE-OblTranslnit
MathlEEE SnglBaslnit
MathIEEE=SnglTranslnit

6.8

ABACUS

6.8.4

THE MATH LIBRARIES

The MathleeeDoubTrans library

The MathleeeDoubTrans library gives you the transcendental functions
needed for double precision math (lEEEDP = IEEE Double Precision).
Overall the double precision floating-point numbers are expected in
IEEE formal
This library supports a 68881 processor once installed in the system,
just like the MathleeeDoubBas library. If just the 68881 is found in the
computer, this must be accessed through the MathIEEE. resource
in the operating system.

MathTrans library
IEEEDPAcos
IEEEDPAsin
IEEEDPAtan
IEEEDPCos
IEEEDPCosh
IEEEDPExp
IEEEDPFieee
IEEEDPLog
IEEEDPLoglO
IEEEDPPow
IEEEDPSin
IEEEDPSincos
IEEEDPSinh
IEEEDPSqrt
IEEEDPTan
IEEEDPTanh
IEEEDPTieee

467
468
468
468
468
468
468
469
469
469
469
469
470
470
470
470
471
Arccosinel

IIEEEDPACOS

Syntax:

result = IEEEDPAcos(value)
00/01
-120
00/01
DOUBIE resul t;
DOUBIE value;

Description:

Calculates the arccosine of val ue.

467

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Arcsinel

hEEEDPAsin
Syntax:

result = IEEEOPAsin(value)
00/01
-114
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates the arcsine of value.

hEEEDPAtan

Arctangent!

Syntax:

result = IEEEOPAtan(value)
00/01
-30
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates the arctangent of val ue.

hEEEDPCOS

Cosinel

Syntax:

result = IEEEDPCos(value)
00/01
-42
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates the cosine of val ue.

hEEEDPCOSh

Hyperbolic cosinel

Syntax:

result = IEEEOPCosh(value)
00/01
-66
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates the hyperbolic cosine of val ue.

IIEEEDPExp

e raised to the x power

Syntax:

result = IEEEOPExp(value)
00/01
-78
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates e raised to the power of val ue.

hEEEDPFieee
Syntax:

468

Converts IEEESP format to IEEEDPI

result = IEEEDPFieee (value)
00/01
-108
DO
DOUBLE result;
FLOAT value; /* Single precision IEEE format */

6.8 THE MATH LIBRARIES

ABACUS

Description:

Converts a single precision IEEE number to double precision IEEE

formaL

hEEEDPLog

Natural logarithml

Syntax:

result = IEEEDPLog(value)
00/01
-84
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates the natural logarithm of val ue.

hEEEDPLoglO

Base 10 logarithm

Syntax:

result = IEEEDPLog10 (value)

00/01
-126
00/01
DOUBLE result;
DOUBLE value;

Description:

Calculates the base 10 logarithm of value.

hEEEDPPow

x to the y power!

Syntax:

result = IEEEDPPow(value2,value1)
00/01
-90
02/03 00/01
DOUBLE result;
DOUBLE value1,value2;

Description:

Calculates valuel "value2.

!IEEEDPSin

Sine!

Syntax:

result = IEEEDPSin(value)
00/01
-36
DO/D1
DOUBLE result:
DOUBLE value;

Description:

Calculates the sine of value.

hEEEDPSincos

Sine and cosine!

Syntax:

result = IEEEDPSincos(adr_c,value)
00/01
-54
AD 00/01
DOUBLE result;
DOUBLE value,*adr_c;

Description:

Calculates the sine and cosine of val ue. The sine returns immediately
and the cosine is saved in the variable to which adr_ c points.

469

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Hyperbolic sinel

hEEEDPSinb
Syntax:

result = IEEEOPSinh(value)
00/01

-60

00/01

DOUBLE result;
DOUBLE value;

Description:

Calculates the hyperbolic sine of value.

hEEEDPSqrt
Syntax:

Square root!
result = IEEEOPSqrt(value)
00/01

-96

00/01

DOUBLE re suI t;
DOUBLE value;

Description:

Calculates the square root of value.

hEEEDPTan
Syntax:

Tangent!
result = IEEEOPTan(value)
00/01

-48

00/01

DOUBLE result;
DOUBLE value;

Description:

Calculates the tangent of val ue.

IIEEEDPTanh
Syntax:

Hyperbolic tangent!
result = IEEEOPTanh(value)
00/01

-72

00/01

DOUBLE result;
DOUBLE value;

Description:

470

Calculates the hyperbolic tangent of value.

6.8

ABACUS

hEEEDPTieee

THE MATH LIBRARIES

Converts IEEEDP into IEEESP format!

Syntax:

result = IEEEOPTieee(value)
DO
-102
00/01
FLOAT result; 1* Single precision IEEE format *1
DOUBLE value;

Description:

Converts a double precision IEEE number into single precision IEEE

formal

Structures:

MathIEEE.resource:
struct MathIEEE =
(

OxOO
OxOE
Ox10
Ox14
Ox18
Ox1C
Ox20

0
14
16
20
24
28
32

struct
UWORD
ULONG
ULONG
ULONG
ULONG
ULONG

Node MathIEEE node;

MathIEEE Flags
MathIEEE-BaseAddr
;fUr 68881-Coprozessor
MathIEEE-OblBasInit ;fUr andere
MathIEEE-OblTransInit
MathIEEE-SnglBasInit
MathIEEE=SnglTransInit

471

6. THE AMIGA LIBRARIES

6.9

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The Potgo library

The Potgo library isn't really a library. It's a resource that makes
library-like calls available. The Potgo library controls the two
gameports, into which you can plug mice, joysticks or paddles.

PotKo library functions

472
473
473

AlIocPotBits
FreePotBits
WritePotgo

IAlIocPotBits
Syntax:

Allocates Potgo register bitsl

Reserved = AllocPotBits(Bits)
DO

-6

DO

LONG Reserved;
LONG Bits;

Description:

This function reserves bits in the Potgo register. You must request
access to this register ($DFF034) before accessing the register because
of the Amiga's multitasking capability. You can reserve any bits, but
after the function call you must examine the bits to see if you can
reserve them at that time.

Parameters:

Bits:
START

DAlLX
OUlLX
DAlLY:
OUlLY:
DATRX:
OUTRX:
DA1RY:
OUI'RY:
Result:

472

Reserved:

Bitmask that indicates which bits you want reserved.

The following bits have the following meanings:
(Bit 0) Starts the counter for analog entries. You must
set all of the entries that you want started in the same
call where the OUTxx bits must be cleared.
(Bit 8) Left port, pin 5.
(Bit 9) Output flag for left port, pin 5. If another task
calls later with a set START bit, this port is unaffected.
(Bit 10) Left port, pin 9.
(Bit 11) Output flag for left port, pin 9.
(Bit 12) Right port, pin 5.
(Bit 13) Output flag for right port, pin 5.
(Bit 14) Right port, pin 9.
(Bit 15) Output flag for right port, pin 9.
Sets reservable bits. This affects only the START and
DATxx bits because the OUTxx bits have nothing to
do with the reservation.

ABACUS

6.9 THE POTGO LIBRARY

Comments:

When you have reserved bits of the Potgo register with this function,
you must free these again with FreePotBits once you no longer
need them, or the bits will be suppressed until the next reset

See Also:

FreePotBits

IFreepotBits

Frees Potgo register bitsl

Syntax:

FreePotBits (Reserved)
-12
DO
LONG Reserved;

Description:

This function frees the bits previously reserved by AllocPotBits.

Parameter:

Reserved:

See Also:

AllocPotBits

The result received from AllocPotBits.

IWritePotGo

Writes to Potgo registerl

Syntax:

WritePotGo (Word, Mask)

-18
DO
Dl
LONG Word, Mask;

Description:

This function writes the specified bits in the Potgo register. It only
changes the bits that are set in the mask. You should only specify bits
which are actually reserved.

Parameters:

wont:
Mask:

New data for the Potgo register.

Bits whose values are overwritten by the bits from
Word.

473

6. THE AMIGA LIBRARIES

6.10

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The Translator library

The Translator library converts an English sentence into a phoneme
string which can then be output using the Narrator device.

Translate
Syntax:

Error = Translate(Sentence,Length,Buffer,BufLength)
DO

-30

AO

DO

Al

Dl

LONG Error;
UBYTE *Sentence;
LONG Length;
UBYTE *Buffer;
LONG BufLength;

Description:

This function converts an English sentence into phonemes. which the

Narrator device converts into sound.

Parameters:

Sentence:
Length:

Buffer:
buflength:
Result:

474

Pointer to the sentence.

Length of the sentence.
Pointer to the buffer in which the phoneme codes are
stored.
Length of Buffer.

Returns a zero if no error is encountered. or a negative value which

represents a negative offset in the sentence and designates the character
that cannot be translated. The only error that can occur is insufficient
memory in the buffer.

6.11

ABACUS

6.11

THE EXPANSION LIBRARY

The Expansion library

The Expansion library makes hardware expansions available from the
operating system. The following include files (Version 1.2 and up)
contain additional Expansion library data:
<libraries/expansion.h>
<libraries/configregs.h>
<libraries/configvars.h>
<libraries/filehandler.h>

Some include files may not contain comments, since the manufacturer
may have stripped the comments to save memory. Only non-stripped
include files will contain commentary.

Expansion library functions

AddConfigDev
AddDosNode
AllocBoardMem
AllocConfigDev
AllocExpansionMem
ConfigBoard
ConfigChain
FindConfigDev
FreeBoardMem
FreeConfigDev
FreeExpansionMem
GetCurrentBinding
MakeDosNode
ObtainConfigBinding
ReadExpansionByte
ReadExpansionRom
ReleaseConfigBinding
RemConfigDev
SetCurrentBinding
WriteExpansionByte

476
476
477
477

478
478
479
479
480
480
481
481
481
482
483
483
484
484
484
485

475

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

IAdd ConfigDev

Adds new ConfigDev structurel

Syntax:

AddConfigDev(configDev)
-30
AO
struct ConfigDev *configDev;

Description:

This function inserts the ConfidDev structure in the system's

Configuration device list

Parameter:

configDev:

See Also:

RemConfigDev

Pointer to the ConfigDev structure to be inserted.

IAddDosNode

Adds drive to systeml

Syntax:

ok = AddDosNode(bootPri,flags,deviceNode)
DO
-150
DO
D1
AO
BOOL ok;
BYTE bootPri;
LONG flags;
struct DeviceNode *deviceNode;

Description:

This function adds a disk drive driver to the system. If DOS was already
initialized, the function adds the driver immediately. Otherwise, the
system initializes DOS then adds the driver.

Parameter:

bootpri:

deviceNode:

Priority of the BOOT operation. It is possible to boot

from any drive. The system attempts to boot from the
drive assigned the highest priority. This continues until
a boo table drive can be found. This allows booting
from a hard disk (Kickstart 1.3 up). The following
priorities are possible:
Drive DFO (usually default booting priority).
Hard disk.
Drive in a network.
Non-bootable drive.
Flags to indicate driver status. If bit 0
(ADNF _STARTPROC) of this flag is set, the driver
starts immediately; otherwise it starts the frrst time the
driver can be accessed. If the dn_Taks array in the
DeviceNode structure is unequal to zero, this bit has
no meaning.
Pointer to the device node.

Result:

ok:

Returns FALSE if an error occurs.

Comments:

If dn_Seglist, dn_Handler and dn_Taks of the DeviceNode

structure contain a value of zero, the standard disk driver is used for the
drive.

+5

-5
-128
flags:

476

6.11

ABACUS

Warning:

THE EXPANSION LIBRARY

Because the Aztec C compiler expects long values on the stack, you
must convert bootpri to a long value.
The task to which the device node belongs is a DOS task and not an
Exec task. A DOS task is similar to a process, like it can create from
the DOS functions.

Example:

The following lines connect a bootable drive in the system and start the
driver process immediately:
AddDosNode(O,ADNF_STARTPROC,MakeDosNode(paramPacket;

See Also:

MakeDosNode

!AllocBoardMem

Allocates expansion memory!

Syntax:

startSlot = AllocBoardMem (slotSpec)

DO
-42
DO
LONG startSlot;
LONG slot Spec;

Description:

This function allocates sufficient expansion memory for the expansion.

Parameter:

slotSpec:

Expansion card memory array of type byte.

Result:

startSlot:

Number of the fIrst usable slot.

Exceptions:

Returns a value of -1 if no memory could be allocated.

Comments:

Assembly language programmers should use the EC_MEMADDR macro

to specify the memory address of the startS lot parameter.

Example:

struct ExpansionRom *er;

slot = AllocBoardMem(er->er_Type & ERT_MEMMASK);

See Also:

AllocExpansiOnMem, FreeExpansionMem, FreeBoardMem

!AllocConfigDev

Allocates ConfigDev structure!

Syntax:

configDev = AllocConfigDev ()
DO
-48
struct ConfigDev *configDev;

Description:

This function allocates a cleared ConfigDev structure.

Result:

configDev:

See Also:

FreeConfigDev

Pointer to a ConfigDev structure, or a value of zero

of an error occurs

477

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

IAllocExpansionMem
Syntax:

Allocates memory for expansionl

startSlot = AllocExpansionMem(numSlots,slotOffset)
DO

-!l4

DO

01

APTR ptr;
LONG startSlot;
LONG numSlots,slotOffset;

Description:

This function allocates memory for specific slots in expansion

memory. Each slot is E_SLOTSIZE bytes long. After the call the
following equation is fulfilled:
(startSlot - slotOffset) MOD slotAlign

Pammeters:

numSlots:
slotOffset.:

Number of slots that should be allocated.

Offset of the starting slot

Result:

startS lot:

Returns the number of the starting slot. or a value of -1

if the slots could not be allocated.

Comments:

Assembly language programmers should use the EC_ MEMADDR macro

to specify the memory address of the startS lot parameter.

Example:

AllocExpansionMem(2,0);

Gets two slots, where the number of the startS lot parameter must be an
even address.
AllocExpansionMem(64,32);

This is the standard call for 4 megabyte memory expansion. It uses 4

megabytes of expansion memory, which ends at an odd 2 megabyte

limit.
See Also:

FreeExpansionMem, AllocBoardMem, FreeBoardMem

IConfigBoard
Syntax:

Configures expansionl
Error

ConfigBoard(board,configDev)
-60
AD
A1
LONG Error;
LONG board;
struct ConfigDev *configDev;
=

DO

Description:

478

This function configures the expansion card. This card is usually at the
address E_EXPANSIONBASE, which can be changed on later model
Amigas so that the address can be given as a parameter.
ConfigBoard uses expansion memory, places the card there, and
moves the ConfidDev structure to the newest location.

6.11

ABACUS

Parameters:

board:

Cwrent card address.

Pointer to ConfigDev structure of the card.

configDev:

Returns a value other than zero if an error occurs.

Result:
See Also:

FreeConfigDev

IConfigChain
Syntax:

THE EXPANSION LIBRARY

Configures entire systeml

Error

ConfigChain(baseAdr)

DO

-66

AD

LONG Error;
LONG baseAdr;

Description:

This function configures the entire system by linking all of the

expansions found at the address E _ EX PAN S I 0 NB AS E in the
configuration list, and calling all the necessary functions.

Parameter:

hlseAdr:

Base address at which the expansion card should search

Result:

error:

Returns a value other than zero if an error occurs

See Also:

FreeConfigDev

IFindConfigDev
Syntax:

Searches for ConfigDevl

configDev

FindConfigDev(oldConfigDev,manufacturer,product)

DO

-72

AD

DO

01

struct ConfigDev *configDev;

struct ConfigDev *oldConfigDev;
LONG manufacturer,product;

Description:

This function searches for a ConfigDev structure that meets the

given specifications.

Parameters:

oldConfigDev:
ConfigDev search process. If this parameter equals
zero, the ConfigDev structure should be searched for
from the beginning; otherwise it should search from the
element following oldConfigDev structure in the
list.
manufacturer: Manufacturer ID that should be searched for, or -1 if no
particular manufacturer should be searched for.
pnxluct
Product ID that should be searched for, or -1 if no
particular product should be searched for.

Result:

configDev:

Returns the pointer to the ConfigDev that fulfllis the

requirements, or a value of 0 if no Con f i gD e v
structure can meet the given requirements.

479

6. THE AMIGA LIBRARIES

Example:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The following program section searches for all of the ConfigDevs of

the list that fulfills a certain requirement:
struct ConfigDev *cd = Null;
while (cd = FindConfigDev(cd,MANUFACTURER,PRODUCT)
(

/* Here you can experiment somewhat with

/* the ConfigDev */

!FreeBoardMem
Syntax:

*/

Frees expansion memory!

FreeBoardMem(startSlot, slotSpec)
-78

DO

Dl

LONG startSlot,slotSpec;

Description:

This function frees the memory from the expansion board previously
allocated using the AllocBoardMem function.

Parameters:

startS lot:
slotSpec:

Warning:

The system crashes if you attempt to free an already-free slot.

Example:

struct ExpansionRom *er;

LONG startSlot,slotSpec;
slotSpec = er->er Type & ERT MEMMASK;
startSlot = AllocBoardMem(slotSpec);
if (startSlot != -1)

Number of the slot.

Expansion card memory array of type byte.

FreeBoardMem(startSlot,slotSpec);

See Also:

AllocExpansionMem, FreeExpansionMem,
AllocBoardMem

!FreeConfigDev
Syntax:

Frees ConfigDev structure!

FreeConfigDev (configDev)
-84

AO

struct ConfigDev *configDev;

Description:

This function frees the ConfigDev structure previously allocated

using the AllocConfigDev function.

Parameters:

congifDev:

See Also:

AllocConfigDev

480

Pointer to ConfigDev structure.

6.11

ABACUS

ansionMem
Syntax:

THE EXPANSION LIBRARY

Frees ex ansion memor

FreeExpansionMem (startSlot,numSlots)
-90

DO

01

LONG startSlot,numS1ots;

Description:

This function frees expansion memory previously allocated using the

AllocExpansionMem function.

Parameters:

startS lot:
numSlots:

Warning:

The system crashes if you attempt to free an already-free slot.

See Also:

AllocExpansiOnMem

Starting slot.
Number of slots.

GetCurren tBindin
Syntax:

number = GetCurrentBinding(currentBinding, size)

DO

-138

AD

DO

UWORD number;
struct CurrentBinding *currentBinding;
UWORD size;

Description:

This function gets the current parameters of the configuration.

Parameters:

currentBinding:
size:

Pointer to the CurrentBinding structure.

Size of the CurrentBinding structure (this size can
vary).

Result:

number:

Returns the number of bytes copied.

See Also:

SetCurrentBinding

IMakeDosNode
Syntax:

Creates DOS data structures for diskl

deviceNode = MakeDosNode (parameterPkt)
DO

-144

AO

struct DeviceNode *deviceNode;

LONG *parameterPkt;

Description:

This function creates all of the data structures necessary to add a drive to
the system. These structures consist of a DeviceNode, a disk
environment vector, a FileSysStartupMsg and up to two BCPL
strings. The include files <libraries/dosextens. h> and
<libraries/filehandler. h> contain further information.
MakesDosNode allocates the necessary memory and links the
different SbUctures together.

481

6. THE AMIGA LIBRARIES

Parameters:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

parameterPkt:
Parameter block containing the information needed for
creating structures. The parameter block consists of
long words of variable length:
0= Pointer to string with the name of the DOS driver.
4 = Pointer to string with the name of the Exec driver.
8 = Number of the unit for OpenDevice.
12 =Flags for OpenDevice.
16 = Number of long words that follow.
20 =Additional information.
Returns a pointer to the DeviceNode structure, or a
value of zero if insufficient memory exists.

Result:

deviceNode:

Example:

The following program section adds a 3.5" disk drive to the system as
DF1:
char execName[] = "trackdisk.device";
char dosName[] = "dfl";
ULONG parmPkt [ ]
{

(ULONG) dosName,
(ULONG) execNarne,
1,

f* Drive number *f
f* Flags for OpenDevice *f
f* now the additional information follows *f
f* 11 additional long words *f
11,
512 2,
f* long words per block *f
0,
f* Sector Start, unused *f
0,

2,

/* Number of sides */

1,
11,

f* Sectors per log. block, unused */

f* Sectors per track *f
f* Reserved (boot-) blocks *f
f* Unused */
f* Interleave factor *f
f* First cylinder *f
f* Last cylinder *f

2,
0,
0,
0,
79,
5

/* Number of the buffer */

};

struct DeviceNode *dnode,*MakeDosNode();

dnode = MakeDosNode(parmPkt};

See Also:

AddDosNode

IObtainConfigBinding

Gets ConfigDev access rightsl

Syntax:

ObtainConfigBinding ()
-120

Description:

This function must be called before adding a driver to the Con f igDev
structure, if you wish to add the driver using means other than the CLI
BindDrivers command. The ObtainConfigBinding function
ensures that no other programs want to add drivers at the same time.

482

6.11 THE EXPANSION LIBRARY

ABACUS

See Also:

ReleaseConfigBinding

IReadExpansionByte
Syntax:

Reads byte nibble by nibblel

Byte = ReadExpansionByte(Board,Offset)
DO

-96

AO

DO

BYTE Byte;
LONG Board,Offset;

Description:

This function reads a byte from a new expansion card. New expansion
card data is read from memory nibble by nibble.

Parameters:

B<ml:
Offset

Pointer to base address of an expansion card.

Offset of expansion ROM structure, calculated using
the EROFFSET and ECOFFSET macros.

Result:

Byte:

Returns the byte that was read, or a value of -1 if the

byte could not be read.

Comments:

The ReadExpansionRam function usually calls this function.

Example:

type = ReadExpansionByte(od->BoardAddr,EROFFSET(er_Type:
ints =
ReadExpansionByte(cd->BoardAddr,ECOFFSET(ec_Interrupt;

See Also:

ReadExpansionRom,WriteExpansionByte

IReadExpansionRom
Syntax:

Read configuration datal

Error = ReadExpansionRom(board,configDev)
DO

-102

AD

A1

LONG Error:
LONG board;
struct ConfigDev *configDev;

Description:

This function reads the configuration data of an expansion card in the

ConfigDev structure (cd Rom). The function determines whether a
card exists in the given address, as well as whether the card is a new
expansion card or an old expansion card

Parameters:

board:
coofigDev:

Pointer to base address of an expansion card

Pointer to ConfigDev structure.

Result:

error:

Returns a value other than zero if an error occurs.

483

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

configDev = AllocConfigDev():
if (!configDev) Error();
Error = ReaJExpansionRom(board,configDev);
if (!Error)

Example:

configDev->cd BoardAddr = board;

ConfigBoard(configDev):

See AlSO:

ReadExpansionByte, WriteExpansionByte

ReleaseConfi

Frees access ri hts

Syntax:

ReleaseConfigBinding ()
-126

Description:

Releases access rights established by the ObtainConfigBinding

function, so that other programs can add their drivers.

See Also:

ObtainConfigBinding

Dev

Removes Confi Dev structure

Syntax:
RemConfigDev(configDev)
-108
AD
struct ConfigDev *configDev:

Description:

This function removes the given ConfigDev structure from the list
of all of the Conf igDev structures.

Parameter:

configDev:

See Also:

AddConfigDev

Pointer to Conf igDev structure.

SetCurrentBindin

Sets conti

Syntax:

SetCurrentBinding (currentBinding, number)

-132
AO
DO
struct Current Binding *currentBinding;
UWORD number:

Description:

This function specifies the current configuration parameters, allowing

the option of adding parameters to an existing device.

Parameters:

cunentBinding:
number:

See Also:

484

Pointer to CurrentBinding structure.

Number of bytes that should be given.

GetCurrentBinding

6.11

ABACUS

IWriteExpansionB yte

THE EXPANSION LIBRARY

Writes a byte by nibblesl

Syntax:

Error = WriteExpansionByte(board,offset,byte)
DO
-114
AD
DO
D1
LONG Error;
LONG board, offset;
BYTE byte;

Description:

This function writes a byte to a new expansion card. New expansion

card data is written to memory nibble by nibble.

Parameters:

Boa:d:

Offset:

Pointer to base address of an expansion card.

Offset of expansion ROM structure, calculated using
the EROFFSET and ECOFFSET macros.

Result:

Byte:

Warning:

Because the Aztec C compiler requires long values on the stack, you
must convert the byte to a long word.

Example:

Error = WriteExpansionByt
(cd->BoardAddr,ECOFFSET(ec Shutup), (LONG)O);
Error = WriteExpansionByte
(cd->BoardAddr,ECOFFSET(ec_Interrupt),lL);

See AlSO:

ReadExpansionByte,ReadExpansionRom

Returns the byte that was read, or a value of -1 if the

byte could not be read.

Structures:
Global sizes:
E SLOTSIZE
E_EXPANSIONBASE
E EXPANSIONSIZE
E EXPANSIONSLOTS
E MEMORYBASE
E MEMORYSIZE
E MEMORYSLOTS

Ox10000
Oxe80000
Ox080000
8

Ox200000
Ox800000
128

struct ExpansionRorn <libraries/configregs.h>

{

OxOO
Ox01
Ox02
Ox03
Ox04
Ox06
OxOA
OxOC
OxOD
OxOE
Ox OF
Ox10
I;

0 UBYTE
1 UBYTE
2 UBYTE
3 UBYTE
4 UWORD
6 ULONG
10 awORD
12 UBYTE
13 UBYTE
14 UBYTE
15 UBYTE
16

er_Type;
er Product;
er::::Flags;
er_Reserved03;
er_Manufacturer;
er SerialNumber;
er::::lnitDiagVec;
er ReservedOc;
er::::ReservedOd;
er ReservedOe;
er::::ReservedOf;

485

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

Types (er_Type):
ERT TYFEMASK
ERT NEWBOARD
ERT MEMMASK
ERTF CHAINEDCONFIG
ERTF DIAGVALID
ERTF MEMLIST
Flags (er_Flags):
ERFF MEMSPACE
ERFF NOSHUTUP

OxeO
OxeO
Ox07
(13)
(14)
(15)
(17)
(16)

struet ExpansionControl <libraries/eonfigregs.h>

{

OxOO
Ox01
Ox02
Ox03
Ox04
Ox05
Ox06
Ox07
Ox08
Ox09
OxOA
OxOB
OxOC
OxOD
OxOE
OxOF
Ox10

o
1
2
3
4

6
7
8

9
10
11
12
13

14
15
16

UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE

ee Interrupt;
ee-Reserved11;
ee=BaseAddress;
ec Shut up;
ec=ReservedI4;
ec Reservedl5;
ec-Reserved16;
ec- Reserved1 7;
ec=ReservedI8;
ec Reservedl9;
ec-Reservedla;
ec-Reserved1b;
ee-Reserved1c;
ec-Reservedld;
ec-Reservedle;
ec=Reserved1f;

);

Interrupt Control register (ec_Interrupt):

ECIF INTENA
ECIF RESET
ECIF-INT2PEND
ECIF-INT6PEND
ECIF-INT7PEND
ECIF INTERRUPTING

(11)
(13)
(14)
(15)
(16)
(17)

struct ConfigDev <libraries/configvars.h>

{

OxOO
OxOE
OxOF
Ox10
Ox20
Ox24
Ox28
Ox2A
Ox2C
Ox30
Ox34
Ox44
);

486

0
14
15
16
32
36
40
42
44
48
52
68

struet Node
UBYTE
UBYTE
struct ExpansionRom
APTR
APTR
UWORD
UWORD
APTR
struct ConfigDev *
ULONG

cd Node;

cd~)lags;

cd Pad;
cd=Rom;
cd BoardAddr;
cd=BoardSize;
cd_SlotAddr;
cd_Slot Size;
cd_Driver;
cd_NextCD;
cd_Unused [ 4];

6.11 THE EXPANSION LIBRARY

ABACUS

Flags (cd_Flags):
COF SHUTUP
COF CONFIGME

Ox01
Ox02

struct CurrentBinding <libraries/configvars.h>

{

OxOO 0
Ox04 4
Ox08 8
OxOC 12
Ox10 16

struct ConfigDev *cb ConfigOev;

UBYTE
* cb::::FileNarre;
UBYTE
*cb ProductString;
UBYTE
**cb::::Tool Types;

};

struct FileSysStartupMsg <libraries/filehandler.h>

{

OxOO 0 ULONG
Ox04 4 BSTR
Ox08 8 BPTR
OxOC 12 ULONG
Ox10 16

fssm_Unit;
fssm Device;
fssm::::Environ;
fssm_Flags;

};

struct DeviceNode <libraries/filehandler.h>

{

OxOO
Ox04
Ox08
OxOC
Ox10
Ox14
Ox18
Ox1e
Ox20
Ox24
Ox28
Ox2e

0 BPTR
dn Next;
4 ULONG
dn::::Type;
8 struct MsgPort *dn Task;
12 BPTR
dn::::Lock;
16 BSTR
dn Handler;
20 ULONG
dn::::StackSize;
dn Priority;
24 LONG
28 BPTR
dn::::Startup;
32 BPTR
dn SegList;
36 BPTR
dn::::GlobaIVec;
40 BSTR
dn_Name;
44

};

487

6. THE AMIGA LIBRARIES

6.12

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The Rom Boot library

The RomBoot library allows Kickstart 1.3 to boot from drive DFO:, or
from any expansion card added to the Amiga. The expansion card must
be bootable and have a ROM which contains the necessary
initialization routine.
When booting, the operating system tries to boot as usual from DFO:.
If no disk is in this drive, or if the disk is non-bootable, the system
checks all of the expansion cards to see if they are bootable and then
boots the card with the highest priority (see Expansion library:
AddDosNode). If no bootable expansion cards exist, the icon appears
on the screen requesting that you insert a Workbench disk.
Expansion cards could be bootable from the hard disk driver, and
networked Amigas can also boot from the network.
The RomBoot library contains only functions that are currently
undocumented by Commodore-Amiga. Because this function should
only be used within the operating system when booting, the average
user or programmer may not find this information useful.

Structures:

struct RomBootBase
{

Oxoo
Ox22
Ox26
Ox34
Ox3B

0
34
3B
52
56

struct Library
LibNode;
struct Execbase *ExecBase;
struct List
BootList;
ULONG
Reserved [4] ;

);

struct BootNode
{

OxOO 0
OxOE 14
Ox10 16
Ox14 20
};

488

struct Node bn Node;

UWORD
bn=Flags;
CPTR
bn_DeviceNode;

ABACUS

6.13

6.13

THE CONSOLE LIBRARY

The Console library

The Console library isn't really a library. but it only handles two
console device functions which are called as library functions. A pointer
to the console library is needed, such as this:
if (OpenDevioe (nconsole.device",-IL, IOStdReq, OL) == 0)
ConsoleDevice = IOStdReq->io Device;
else
/* error */

Console library functions

CDInputHandler
RawKeyConvert

ICDlnputHandler

489
489

Sends input to Console devicel

Syntax:

CDInputHandler (events,ConsoleDevice)
-42
AO
Al
struct Events *events;
struct Device *ConsoleDevice;

Description:

This function receives input (nonnally from the input. task ROM)
and sends this information to the console device.

Parameters:

events:
Pointer to list of events.
ConsoleDevice:
Pointer to console device.

Comments:

This function is listed here for historical purposes only. and should not
be used. Input in the system is handled by the WriteEvent function
of the input device.

IRawKeyCOnvert

Converts RA WKEY to ASCIII

Syntax:

number = RawKeyConvert (event, buffer, length,keyMap)

DO
-48
AO
Al
Dl
A2
SHORT number;
struct InputEvent *event;
UBYTE *buffer;
LONG length;
struct KeyMap *keyMap;

Description:

This function converts RAWKEY events into ASCII characters. or into

an ANSI character string. This happens in conjunction with the
KeyMap. if one exists.

489

6. THE AMIGA LIBRARIES

Parameters:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

event
buffer:

Pointer to input event.

Pointer to data buffer containing the ANSI character
smng.
Data buffer size in bytes.
Pointer to KeyMap which converts the RAWKEYs
into ANSI character smngs. If keyMap equals zero the
default KeyMap is used.

length:

keyMap:

Result:

number:

Exceptions:

If the n umbe r parameter equals -1, the contents of the data buffer are
dedared invalid

Structures:

struct InputEvent <devices/inputevent.h>

Returns the number of characters written in the data

buffer, or a value of -1 if insufficient buffer memory
existed.

Oxoo 0
Ox04 4
Ox05 5
Ox06 6
OxOS S
OxOA 10

struct
UBYTE
UBYTE
UWORD
UWORD
union

InputEvent *ie_NextEvent;
ie_Class;
/* Type */
ie SubClass;
1* Sub type *1
ie-Code;
ie:=Oualifie r;

struct
{

OxOA 10
OxOC 12
OxOA 10
OxOE 14
Ox16 22

1* Mouse position */

WORD
WORD

ie_xy;
APTR
ie addr;
ieyosition;
struct timeval ie_TimeStamp;/* System time */

};

Event classes (ie_Class):

IEClASS Null
IEClASS RAWKEY
IEClASS RAWMOUSE
IEClASS EVENT
IEClASS POINTERPOS
IEClASS_TlMER
IEClASS_GADGETDOWN
IEClASS_GADGETUP
IEClASS_REQUESTER
IEClASS_MENULIST
IEClASS_CLOSEWINDOW
IEClASS SIZEWINDOW
IEClASS_REFRESHWINDOW
IEClASS_NEWPREFS
IEClASS DISKREMOVED
IEClASS:=DISKINSERTED
IEClASS_ACTIVEWINDOW
IEClASS_INACTlVEWINDOW

490

OxOO
Ox01
Ox02
Ox03
Ox04
Ox06
OxO?
OxOS
Ox09
OxOA
OxOB
OxOC
OxOD
OxOE
OxOF
Ox10
Oxll
Ox12

6.13 THE CONSOLE

ABACUS

LIBRARY

Event Codes (ie_Code):

RAWKEY-Codes:
IECODE UP PREFIX
IECODE KEY CODE FIRST
IECODE KEY CODE LAST
IECODE=COMM_CODE_FIRST
IECODE- COMM- CODE- LAST

Ox80
OxOO
Ox11
Ox18
Ox1F

IECODE co FIRST
IECODE-CO-LAST
IECODE ASCII FIRST
IECODE-ASCII-LAST
IECODE ASCII DEL
IECODE-CI FIRST
IECODE CI LAST
IECODE-LATINI FIRST
IECODE LATINI LAST

OxOO
OxlF
Ox20
Ox1E
Ox7F
Ox80
Ox9F
OxAO
OxFF

ANSI Codes:

RA WMOUSE Codes:
IECODE
IECODE
IECODE
IECODE

LBUTTON
RBUTTON
MBUTTON
NOBUTTON

Ox68
Ox69
Ox6A
OxFF

WINDOW Codes:
IECODE NEWACTIVE

OxOl

REQUESTER Codes:
IECODE_REQSET
IECODE_REQCLEAR

OxOI
OxOO

Event Qualifier (ie _Qualifier):

IEQUALIFIER_LSHIFT
IEQUALIFIER_RSHIFT
IEQUALIFIER CAPSLOCK
IEQUALIFIER=CONTROL
IEQUALIFIER_LALT
IEQUALIFIER_RALT
IEQUALIFIER_LCOMMAND
IEQUALIFIER_RCOMMAND
IEQUALIFIER_NUMERICPAD
IEQUALIFIER_REPEAT
IEQUALIFIER INTERRUPT
IEQUALIFIER=MULTIBROADCAST
IEQUALIFIER_MIDBUTTON
IEQUALIFIER_RBUTTON
IEQUALIFIER LEFTBUTTON
IEQUALIFIER=RELATIVEMOUSE

OxOOOl
Ox0002
Ox0004
Ox0008
OxOOIO
Ox0020
Ox0040
Ox0080
OxOIOO
Ox0200
Ox0400
Ox0800
OxlOOO
Ox2000
Ox4000
Ox8000

491

6.

ADVANCED SYSTEM PROGRAMMER'S GUIDE

THE AMIGA LIBRARIES

struct KeyMap <devices/keymap.h>

{

OxOO
Ox04
Ox08
OxOC
OxlO
Ox14
Ox18
OxlC
Ox20

0
4
8
12
16
20
24
28
32

UBYTE
ULONG
UBYTE
UBYTE
UBYTE
ULONG
UBYTE
UBYTE

*km_LoKeyMapTypes;
*km_LoKeyMap;
*km_LoCapsable;
*km_LoRepeatable;
*km_HiKeyMapTypes;
*km_HiKeyMap;
*~HiCapsable;
*km_HiRepeatable;

};

Keymap Types:
KC_NOQUAL
KC VANILLA
KCF SHIFT
KCF ALT
KCF CONTROL
KCF DOWNUP
KCF DEAD
KCF STRING
KCF NOP

0
7

OxOl
Ox02
Ox04
Ox08
Ox20
Ox40
Ox80

Prefix Codes for DEAD Keys:

DPF MOD
DPF DEAD
DP 2DINDEXMASK
DP-2DFACSHIFT

492

OxOl
Ox08
OxOf
4

Key was modified by dead key

Dead Key

6.14 THE TIMER LIBRARY

ABACUS

6.14

The Timer library

The Timer library makes three library-like fWlctions available for time
control. This is helpful when your program involves operations
requiring time.

Timer library functions

AddTune

493
493
494

CmpTime
SubTime

IAddTime

Adds two timesl

Syntax:

AddTime (Dest,Source)
-42
AD
Al
struct timeval *Dest,*Source;

Description:

This function adds the two times specified by the timeval structures.
The result is placed in the Dest timeval structure.

Parameters:

Dest:
Source:

Comments:

Pointer to timeval structure which contains the

result after the call.
Pointer to timeval structure.

Registers AO and Al remain Wlchanged.

!cmpTime

Compares two timesl

Syntax:

result = CmpTime(Dest,Source)
DO
-54
AD
Al
LONG result;
struct timeval *Dest,*Source;

Description:

This function compares two times.

Parameters:

Dest:
Source:

Pointer to timeval structure.

Pointer to timeval structure.

Result:

result:

Returns a value of zero if both times are identical, a

value of +1 ifDest has more time than Source and a
value of -1 if Dest has less time than Source

Comments:

Registers AO and A 1 remain Wlchanged.

493

6. THE AMIGA LIBRARIES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Subtracts two timesl

ISubTime
Syntax:

SubTime (Dest,Source)
-48
AO
Al
timeval *Dest,*Source;

Description:

This function subtracts the two times specified by the time val
structures. The result is saved in the Dest timeval structure:
dest = dest - source

Parameters:

Dest:
Source:

Pointer to timeval structure which contains the

result after the call.
Pointer to timeval structure.

Comments:

Registers AO and Al remain unchanged.

Structures:

struct timeval <devices/timer.h>

OxOO 0
Ox04 4
Ox08 8
}

494

ULONG tv secs; /* Seconds */

ULONG tv=micro; /* Microseconds [0,999999] */

ABACUS

7.

7.1

PREFERENCES AS A DATA STRUCTURE

Basic and System

Structures
Many kinds of computer data exist There's data which you use very
seldom, data you almost always use, and most often, data that you
couldn't operate your computer without For example, you don't access
fonts directly very often, but the system uses fonts constantly. Without
fonts of some kind, you wouldn't be able to display any text using the
Amiga.
This chapter examines the basic structures of the Amiga operating
system, right down to the system structures. How does the keyboard
check operate without keymaps? Or how do you print something
without a printer driver? It doesn't, and you don't, without these system
structures, set by the operating system or by applications.
Remember that the Amiga is an ever expanding system and therefore
the system structures will change. Never count on the addresses of
system structures to remain constant between versions of the operating
system and never modify private system structures.

7.1

Preferences as a data structure

Every computer includes basic settings that define its "character." In the
early days of home computing. the manufacturer dictated these settings.
For example, you could be sure that when you turned on a Commodore
64, the screen and text would appear in different shades of blue.
With the accent on user-friendliness, you can now change these settings
to suit your own needs. This makes it much more enjoyable to work
with your machine.
The Amiga has so many settings that it includes an extra structure for
storing these settings. If a boot disk doesn't contain ibis information,
the Amiga keeps a default Preferences structure in Kickstart
ROM.

495

7. BASIC SYSTEM STRUCTURES

7.1.1

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The data managed by Preferences

The Preferences structure, which is managed from Intuition,
contains all of the data that can be set using the Preferences program.
The Preferences structure looks like this:
struct Preferences
{

OxOOO
Ox001
Ox002
Ox004
Ox004
OxOOB
OxOOC
OxOOC
Ox010
Ox014
Ox014
Ox01B
Ox01C
Ox064
Ox065
Ox066
Ox06B
Ox06A
Ox06C
Ox06E
OxO?O
Ox072
OxO?4
OxO?6
OxO??
OxO?B
OxO?A
OxO?C
OxO?D
OxOBO
Ox09E
OxOAO
OxOA2
OxOM
OxOA6
OxOAB
OxOM
OxOAC
OxOAE
OxOBO
OxOB2
OxOB4
OxOB6
OxOB?
OxOB8
OxOB9
OxOBA
OxOBB

496

000
001
002
004
004
OOB
012
012
016
020
020
024
02B
100
101
102
104
106
lOB
110
112
114
116
11B
119
120
122
124
126
12B
15B
160
162
164
166
16B
1?0
172
1?4
176
17B
1BO
182
183
184
185
186
18?

BYTE
UBYTE
USHORT
struct
ULONG
ULONG
struct
ULONG
ULONG
struct
ULONG
ULONG
USHORT
BYTE
BYTE
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
USHORT
BYTE
BYTE
WORD
WORD
BOOL
USHORT
UBYTE
USHORT
USHORT
USHORT
UWORD
UWORD
USHORT
USHORT
USHORT
WORD
USHORT
UWORD
USHORT
UBYTE
UBYTE
UBYTE
UBYTE
UBYTE
BYTE

FontHeight;
PrinterPort;
BaudRate;
timeva1 KeyRptSpeed;
tv_secs;
tv micro;
ti~val KeyRptDelay;
tv secs;
tv-micro;
ti~val DoubleClick;
tv_secs;
tv micro;
pointerMatrix[36];
XOffset;
YOffset;
color1?;
color1B;
color19;
PointerTicks;
col orO;
color1;
color2;
color3;
ViewXOffset;
ViewYOffset;
ViewlnitX;
ViewlnitY;
EnableCLI;
PrinterType;
PrinterFilename[FlLENAME_SIZEj;
PrintPi tch;
PrintQuality;
PrintSpacing;
PrintLeftMargin;
PrintRightMargin;
Printlmage;
P rintAspect;
PrintShade;
Print Threshold;
PaperSize;
PaperLength;
PaperType;
/* End Ver. 1.1 */
SerRWBits;
SerStopBuf;
SerParShk;
LaceWB;
WorkName[30];
RowSizeChange;

7.1

ABACUS

OxOBC
OxOBE
OxOcO
OxOC2
OxOC4
OxOCS
OxOC6
OxOCS
OxOCA
OxOCB
OxOCD

1S8
190
192
194
196
197
198
200
202
203
204

BYTE
UWORO
UWORD
UWORD
UBYTE
UBYTE
UWORD
UWORD
UBYTE
UBYTE

PREFERENCES AS A DATA STRUCTURE

ColumnSizeChange;
PrintFlags;
PrintMaxWidth;
PrintMaxHeight;
PrintDensity;
PrintXOffset;
wb_Width;
wb_Height;
wb_Depth;
ext_size;

1* End Ver. 1. 2 *1

1* Ver. 1. 3 * 1

};

The structure can be divided into the subject groups listed below.

Time intervals
All of the system time intervals applying to the keyboard and the
mouse can be set. This means that the timeval structures are
integrated into the Preferences structure. They use components
made of seconds and microseconds. The keyRptSpeed field specifies
the frequency at which the key repeats. The smaller this time value, the
more characters are repeated on the screen at a time.
Before a key repeats, the keyboard driver delays repetition until a certain
interval elapses. This interval is called the repetition threshold, which
is defined by the KeyRptDelay structure. The larger the value, the
longer the system waits until beginning key repeat.
The DoubleClick structure specifies the time interval that elapses
between the two clicks of a double-click. This structure indicates the
maximum amount of time between two single clicks before they may
be read as a double-click. If you set the DoubleClick value too
high, the Workbench may read closely spaced single clicks as doubleclicks.

Mouse pointer
The Preferences structure includes a Pointermatrix field,
which describes the mouse pointer graphic data. It is stored in an array
of 36 words, which gives us a possible 16x16 pixel, four color pointer.
This array remains constant-we cannot expand the pointer to a larger
size.
XOf f set and YOf f set variables contain the coordinate values of the
mouse's hot spot (the pixel of the mouse pointer where the actual
activation occurs).

The colorl 7, color18 and color19 fields control three colors of

the mouse pointer sprite, based on color registers 17 through 19.

497

7.

BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The PointerTicks value defines the number of ticks needed to

move the mouse by one increment Normal settings are limited to I, 2
and 4. The higher the number, the farther you would have to move the
mouse to move the pointer one increment.

Workbench
Our basic structures also store some values which control the
Workbench's appearance.
The colorO, colorl, color2 and color3 fields specify the
Workbench colors.
The ViewXOffset and ViewYOffset fields place the upper left
comer of the Workbench screen (the View) at its proper location of the
monitor screen (you adjust this parameter from the center screen of
Preferences).
The ViewIni tX and viewIni t Y fields contain the initial View
values.
The FontHeight entry specifies the height of the default Topaz font
(8/9).
Version 1.3 includes additional fields: wb_Depth, wb_Height and
wb_width. They contain the dimensions and depth of the Workbench
screen. They can be read from any programs that open a window on the
screen.
The EnableCLI field (Versions 1.1-1.2) determined whether the eLI
icon appeared on the Workbench screen. Versions 1.3 and up ignore
this setting.

Printer settings
Almost half the P references structure lists printer parameters. This
is understandable when you consider how many settings many printers
offer.
The first and most elementary setting is the PrinterPort field,
which indicates the port through which the printer is driven. This is set
to PARALLEL PRINTER or SERIAL PRINTER.
Commodore-Amiga provides its own printer types that are then
supported through a printer driver. The PrinterType field reads
available printer types. If the printer cannot be found,
CustomP rinter is chosen and the name of the printer or printer

498

7.1

ABACUS

PREFERENCES AS A DATA STRUCTURE

driver is placed in the PrinterFileName field. The system can be

expanded at any time.
The Printpitch field specifies the pitch (characters per line).
Normal (pica) type prints 10 CPI (characters per inch). Elite pitch
prints 12 CPI, and Fine (also called condensed) pitch prints 15 CPI.
The PrintQuali ty field controls the printed quality of the text.
Many modem printers support the Near Letter Quality (NLQ) or LQ in
addition to draft quality.
The PrintSpacing field indicates the number of printed lines per
inch on a page. Here you can choose between 6 LPI (lines per inch) and
8 LPI.
Now the printer needs to know the dimensions of the printed page. The
PrintLeftmargin and PrintRightMargin fields give the right
and left margins of the paper.
The PaperSize field indicates the size of a sheet of paper. If you're
using some unusual paper size, you can insert the total number of lines
that will fit on a printed page in the PaperLength field instead.
The PaperType field can indicate either single sheets of paper or
fanfold (continuous) paper.

Graphic printout settings

The Amiga as a graphic computer offers many different settings for
graphic printing. The P r i n t I ma ge field allows the option of
generating a positive or negative printout. This is especially practical if
a picture has many dark surfaces that will appear black with a positive
print. Inverting the color causes less wear and tear on the printer
ribbon, and may yield a better printout.
The PrintAspect field specifies the aspect (direction) of the print.
The PrintShade field controls the intensity of shading. Here you
can specify whether the printout should be in black and white, in gray
scales or in color. The Print Threshold field controls the degree of
gray scaling as dictated by PrintShade.
The expansions that came with the new operating system for setting
the graphic printout are also important in the Preferences
structure. Version l.3 includes additional values that apply to the
Preferences program.
PrintFlags contains various settings for fme-tuning graphic printed
output. The settings for Smoothing (ON, OFF), ColorCorrect

499

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

(R, G, B), Dithering (Ordered, Halftone, F-S) and Scaling

(Fraction, Integer) are stored in PrintFlags.

The PrintMaxWidth and PrintMaxHeight fields contain the

topmost limits of a graphic's printed height and width.
Density is saved in an extra byte because this value will probably be
improved in later versions.

The P r i n t X0 f f set field specifies the left offset of the graphic

printout.

Serial data transfer

Since Version 1.3 of the operating system, additional settings for the
serial interface are now saved in the Preferences structure. These

are:
SerRWBit, one byte in whose top section the number of bits to be
read is saved and in whose bottom section the number of bits to be
written is saved. A setting of either 7 or 8 is possible.

The number of stop bits (1 or 2) as well as the size of the data buffer
are saved in SerStopBuf.
SerParShk acts as a flag for two settings. You can choose between
three handshake methods (xOn/xOff), RTS/CTS and None) and
between three parities (none, even and odd), using the top and
bottom bits as described above.

7.1.2

Preferences access through Intuition

After this information about the individual values of the data structure
we now come to some examples about the practicality. The
Preferences structure can be accessed through the Preferences
program. However, we'd like to draw up a short scenario for you to
show how impractica!.)this can be.
An early Amiga word processor relied completely on Preferences
settings, prohibiting the user from making small changes before a
printout It was incompatible with other programs.

The single advantage is the amount of memory saved by not using

memory for input and modifications. Let's assume that you type in a
text and would like to print this out twice: Once with normal type and

500

7.1 PREFERENCES AS A DATA STRUCTURE

ABACUS

once with NLQ type. The Preferences program must be loaded, which
mayor may not fit into available memory.
Today we know that the Preferences structure can be changed
without actually loading Preferences, and without conflicting with the
system or other programs. This is because Intuition supports three
functions. The first function offers the option of transferring the
contents of the current structure into buffer memory. We supply the
pointer to our buffer and the number of bytes that should be copied.
This GetPrefs () function has the following general format:
GetDefPrefs(PrefBuffer, Size):
-132

AD

DO

If we allocate a memory region and then copy the values there, we can
read the current values first The following program does just that:
1***************************************

*
*

* Program: Read Preferences Data

===================================

* Author: Date:
*
---------* Wgb
07/03/1988
* cc preLc
* In preLo -lc32

Comments:

---------printer data

*
*
*
*
*

***************************************/

'include <exec/memory.h>
'include <intuition/intuition.h>
'define SIZE sizeof(struct Preferences)
struct IntuitionBase *IntuitionBase:
struct Preferences
*PrefsBuffer;
main 0
{

Open_All () :
GetPrefs(PrefsBuffer, SIZE);
printf ("Printer settings: \n"):
printf ("Pitch
$%4x\n", PrefsBuffer->PrintPitch);
printf("Quality: $%4x\n", PrefsBuffer->PrintQuality):
printf ("Spacing: $%4x\nn, PrefsBuffer->PrintSpacing);
printf("Right Margin: %d\n", PrefsBuffer->PrintRightMargin);
printf ("Left Margin: %d\nn, PrefsBuffer->PrintLeftMargin);
Close All () ;
}
1***************************************
* Function: Open Library & Memory
*

===================================

* Author:

* Wgb

Date:

Comments:

07/03/1988

*
*
*
*

***************************************/

Open_All 0
{

void

*OpenLibrary();

501

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

UBYTE *AllocMem();
if (! (IntuitionBase = (struct IntuitionBase *)
OpenLibrary ("intuition. library" , OL)
(

printf ("No Intuition Library found! \n") ;

Close All () ;
exi t (FALSE) ;
}

PrefsBuffer = (struct Preferences *)AllocMem(SIZE,

MEMF CLEAR I MEMF FAST);
i f (!PrefsBuffer)
(

printf("No more memory!\nll);

Close All () ;
exi t (FALSE) ;
}

1***************************************
* Function: Close anything now open

* =================================== *
* Author: Date:
Comments:
*
* -----*
10.16/1987 Intuition and
* Wgb
*
memory only
*
*

***************************************/
Close All ()
{ if (PrefsBuffer)
if (IntuitionBase)

FreeMem(PrefsBuffer, SIZE);
CloseLibrary(IntuitionBase);

Program description
The program opens the Intuition.Library and allocates a memory range
in which the main program places the data of the current
Preferences structure. The chosen values are displayed and the
program closes the fIles.
This alone may be all that's needed for your program. Let's assume that
your program runs only on an Interlace Workbench. Then at the
beginning of your program you check to see if the Preferences
structure has an entry under LaceWB. Ifnot, the program stops with an
error message.
Another alternative is a short-term change to the Preferences
structure. Many programs load the structure into the buffer twice. The
frrst copy acts as the pattern for returning to default values later. Many
entries are changed in the second copy, and then the entire structure is
sent as a new setting10 the operating system. This is done using the
SetPrefs () function:
SetPrefs(PrefBuffer, Size, Flag)
-324

502

AD

DO

D1

7.1

ABACUS

PREFERENCES AS A DATA STRUCTURE

We assign a pointer to the structure, our buffer range and the size of the
buffer, because it may not be necessary to copy the entire structure and
then return it We include a flag value which determines whether other
programs should change the structure. If this flag value is set to TRUE.
all of the programs containing a NEWPREFS message are informed. A
value of FALSE ignores this message.
The following program uses the Preferences structure exactly like
the fust program. changes some of the values and returns them.
Because the changes are rather trivial (some colors were changed) there
is no NEWPREFS message as for the other program.
/***************************************

* Program: Change color data

* =================================== *
* Author: Date:
* ------ ---------07/03/1988
* Wgb
*
preLc
* In preLo -lc32

Comments:

---------Color data

*
*
*
*
*

***************************************/

iinclude <exec/memory.h>
iinclude <intuition/intuition.h>
idefine SIZE sizeof(struct Preferences)
struct IntuitionBase *IntuitionBase;
struct Preferences
*PrefsBuffer;
main 0
(

Open All 0;
GetPrefs(PrefsBuffer,
PrefsBuffer->colorO
PrefsBuffer->color1 =
PrefsBuffer->color2 =
SetPrefs(PrefsBuffer,
Close All 0 ;
}
-

SIZE);
1*15 + 256* 15;
1;
16*15;
SIZE, FALSE);

1***************************************

* Function: Open Library & Memory

* =================================== *

* Author:

* ------

Date:

Comments:

----------

07/03/1988
* Wgb
*
***************************************/
Open All ()
(void *OpenLibrary();
UBYTE *AllocMem () ;
if (! (IntuitionBase = (struct IntuitionBase *)
OpenLibrary ("intuition. library", OL)
{

printf ("No Intuition Library found! \n");

Close_All () ;
exit(FALSE);
}

PrefsBuffer = (struct Preferences *)AllocMem(SIZE,

MEMF CLEARIMEMF FAST);

i f (!PrefsBuffer)
{

503

7.

BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

printf(nNo more memory!\nn);

Close All () ;
exit (FALSE);
}

/***************************************

*
*
*
*
*

Function: Close anything now open

===================================

Author:

*
*
*
*
*

Wgb

Date:

Comments:

----------

----------

10/16/1987

Intuition and
memory only

***************************************/

Close_All ()
(

if (PrefsBuffer)
if (IntuitionBase)
)

504

FreeMem(PrefsBuffer, SIZE);
CloseLibrary(IntuitionBase);

7 ~ PRINTER DRIVERS

ABACUS

7.2

Printer drivers
What do yOu do when you have purchased a printer that is not
supported by the Amiga? This can be solved in most cases by
developing your own printer driver. The printer driver mediates between
the printer device and the printer.
What does a printer driver look like? First of all it needs a header,
similar to the fonts. So that a printer driver doesn't disrupt the
computer with a false start, the ftrst four bytes of the driver contain the
assembly language instructions:
moveq 1I0,dO
rts

Next follow two words that give the version and revision number of the
printer driver. The following is the PrinterExtended data
structure:
offset

Structure
struct PrinterExtendedData
(

o
4

OxOO
Ox04

Ox08

12 OxOc
16 Ox10
20 Ox14
21 Ox1S
22 Ox16
23 Ox17
24 Ox18
26 Ox1a
30 Ox1e
34 Ox22
36 Ox24
38 Ox26
42 Ox2a
46 Ox2e

char
VOID

/* Printer name */
/* Initialization
routine */
VOID (*ped_Expunge) (); /* De-Initialization
routine */
VOID (*ped_Open) (); /* called by OpenDevice() */
VOID (*ped_Close) ();
/* called by
CloseDevice() */
UBYTE ped PrinterC1ass;
UBYTE ped-ColorClass;
/* number of printer
UBYTE ped=MaxColumns;
columns (e.g., 80 or
136 ) */
UBYTE ped_NumCharSets;
/* number of printer
fonts */
UWORD ped_NumRows;
/* number of printer
lines */
ULONG ped_MaxXDots;
/* Maximum horiz.
resolution */
ULONG ped_MaxYDots;
/* Maximum vert.
resolution */
UWORD ped_XDotslnch;
/* Dots per inch
(horiz.) */
UWORD ped_YDotslnch;
/* Dots per inch
(vert.) */
char ***ped Commands;
/* Command strings */
VOID (*ped_DoSpecial) ();/* Special command
handler */
VOID (*ped_Render) ();
/* Hardcopy routine */
*ped PrinterName;
(*pe<tlnit) ();

505

7. BASIC SYSTEM STRUCTURES

50 Ox32
54 Ox36
58 Ox3a

ADVANCED SYSTEM PROGRAMMER'S GUIDE

LONG ped_TimeoutSecs;
char **ped 8BitChars;
); /* defined in "devices/prtbase.h" */

The arrays and functions defined in this structure follow.

7.2.1

The PrinterExtendedData structure

This routine is called after the printer driver is loaded from the printer
device. This routine gives a pointer to a PrinterData structure:
VOID Init (PrinterDatal
struct PrinterData
*PrinterData;
{

.. )

The PrinterData structure has the following appearance:

Offset

Structure
struct PrinterData
{

o
52
86

OxOO
Ox34
Ox56

90
92
96
100

Ox5a
Ox5c
Ox60
Ox64

104
108
108

Ox68
Ox6c
Ox6c

struct DeviceData
pd_Device;
struct MsgPort
pd_Unit;
BPTR
pd_PrinterSegment; /* For
UnLoadSeg (I
UWORD
pd PrinterType;
struct PrinterSegment *pd-SegmentData;
UBYTE
*pd-PrintBuf; /* Buffer
int
(*pd PWritel (I; /* Write
function
int
(*pd PBothReadyl (I; union
struct IOExtPar pd-pO; /* Parallel */
struct IOExtSer pd_sO; /* Serial */

*/
*/
*/
{

union
190
190

Oxbe
Oxbe

272
312
346
438
2486

Ox110
Ox138
Ox15a
Ox1b6
Ox9b6

2487
2488
2720
2721
2722

Ox9b7
Ox9b8
OxaaO
Oxaa1
Oxaa2

struct IOExtPar
struct IOExtSer

pd_p1; /* Parallel */
pd_s1; /* Serial */

struct time request

struct MsgPort
struct Task
UBYTE
UBYTE

pd_TIOR;
pd_IORPort;
pd TC;
pd=Stk[Ox800]; /* Stack */
pd_Flags;
/* OpenDevice() */
UBYTE
pd pad;
struct Preferences
pd=Preferences;
UBYTE
pd WaitEnabled;
/* here a pad byte is ndssing */
); /* defined in "devices/prtbase.h" */

This structure contains two additional undocumented structures. One is

the DeviceData structure that makes printer device information
available to the printer driver, and the other is a P rinterSegment

506

7.2 PRINTER DRIVERS

ABACUS

structure that is necessary to remove the printer driver from memory

using UnloadSeg ( ) .
The printer driver is loaded from the printer device with LoadSeg () .
The segment is not started through CreateProc (). This is because
the printer driver is actually comparable to a library that offers printer
specific routines. Now back to the two structures mentioned above:
Offset

Structure
struct DeviceData
{

0
32
36
40

Oxoo
Ox20
Ox24
Ox28

44
48

Ox2c
Ox30

52

Ox32

Offset

struct Library dd_Device;

APTR
dd_Segment;
APTR
dd ExecBase;
APTR
dd::::CmdVectors;

/* Segment list */
/* Jump table for

device commands */
/* Command string */
dd_CrndBytes;
dd_NUlTCommands; /* Number of
supported
commands */
/* defined in "devices/prtbase.h" */
APTR
APTR

Structure
struct PrinterSegment
{

OxOO

Ox04

8
10
12
70

Ox08
OxOa
OxOc
Ox46

ps_NextSegment; /* Attention! this

variable is a
BPTR */
ULONG
ps_runAlert;
/* contains moveq
itO,dO:rts */
UWORD
ps Version;
/* Version number */
UWORD
ps::::Revision;
/* Revision number * /
struct PrinterExtendedData ps PED;
/* defined in "devices/prtbase:-h" * /
ULONG

As you can see, the PrinterSegment structure, up to the pointer

ps_NextSegment, which is declared as a ULONG variable but is
really a BPTR, states the header of the printer driver. Now back to the
PrintData structure. Beside some internal variables, some important
variables are also made available to the user:
pd_ P ri n t Bu f contains the address of the memory range needed to
print a line of hardcopy. By a hardcopy line we mean the section of a
hardcopy that the printer can print in a single printhead movement from
left to right An eight-pin printer produces eight lines of pixels in one
pass.
pd_ PWri te is the main function of the entire printer device. This
sends the data through the serial or parallel interface. The SendIO ()
command is used for data transmission. That is why we use the double
buffer printout

507

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

The pd_PBothReady executes hardcopy printout (a hardcopy line is

printed out while the next is calculated). Both print operations must be
closed before execution because it may result in a system crash.
Look at the PrinterData structure, and notice that two unions exist
there. They contain a device block, either for parallel or serial devices
(double buffering).
An important structure in the PrinterData structure is the timer
device block pd_TIOR. This device block lets you send a
TR_ADDREQUEST command very easily. This is especially important
after a printer reset before the hardcopy routine, because you should let
at least a second elapse before you begin the hardcopy execution.
You can get all of the important Preferences structure data from
the P rintData structure. You have set the data with the Preferences
(e.g., line feed, etc.). Now back to the PrinterExtendedData
structure:
ped _Expunge:

This routine executes before the UnLoadSeg () function of the printer

device. You have the option of closing the libraries opened by
ped_Init, etc.

ped_Open:

This routine executes after every OpenDevice () function. The

difference between ped_Open and ped_Init is that ped_Init is
executed after the printer driver is loaded. This is not removed from
memory after it is used. For this an extra Expunge () must be called.
If the printer device is already in memory the ped_Open routine is
called after each OpenDevice () . This routine is given to the device
block from the printer device:
Open (IOStdReq)
struct IOStdReq
*IOStdReq;
{ } /* usually moveq #O,dO: rts */

This routine is called after each CloseDevice () . This routine is

also given to the device block of the printer device.

S08

7.2 PRINTER DRIVERS

ABACUS

7.2.1.1

Additional variables

ped PrinterClass:
This UBYTE contains the class of the printer supported by the driver.
The following values exist:
- black and white printer (only text)
- black and white graphic printer
- color graphic printer

'define PPC BWALPHA 0

'define PPC-BWGFX
1
'define PPC-COLORGFX 3

ped ColorClass:
This UBYTE specifies the color class of the supported printer:
'define
'define
'define
'define
'define
'define
'define
'define

PCC BW
PCC- YMC
PCC-YMC BW
PCC-YMCB
PCC-WE
PCC-BGR
PCC-BGR WE
PCC=BGRN

1
2
3
4
9
10
11
12

black and white

Yellow, Magenta, Cyan
Yellow, Magenta, Cyan or black/white
Yellow, Magenta, Cyan, Black
Black/White (inverted)
Blue, Green, Red
Blue, Green, Red or Black/White
Blue, Green, Red and White

ped _MaxColumns:
This variable specifies the number of printed columns that the printer
can print If you can print 80 characters per line, for example, you must
specify the value 80 here.

ped_NumCharStes:
This variable contains the number of different text types that your
printer can use (e.g., pica, condensed, elite, sans, serif).

ped _NumRows:
This variable contains the number of lines that you can print per pass
of the printhead. With an eight-pin dot-matrix printer this variable
contains the value 8.

ped MaxXDots:
This variable contains the number of points that fit in a print line.
With 80 characters per line, and characters eight pixels wide, the value
here is 8*80 =640. If your printer supports different character widths,
this value can vary.

509

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ped _ MaxYDots:
This variable contains the number of lines that fit on one page of text
This variable is only for page-oriented printers (e.g., laser printer). For
dot-matrix printers with fanfold paper, the value 0 can be entered here.

ped_XDotslnch:
This variable contains the number of pixels that the printer can print
horizontally per inch.

ped_YDotslnch:
This variable contains the number of pixels that the printer can print
vertically per inch.

7.2.1.2

DoSpecial and command array

The command strings are contained in this array. These command

strings are converted into Amiga command strings by the CMD_WRITE
function. If, for example, the sequence "<ESC>c" appears in the data
that should be sent to the printer, this is converted into the necessary
sequence ("<ESC>c" resets the printer). The array has the following
appearance:
char *CommandTable[] =
{

"\375\033\015P\275", /* Reset for Diablo printer * /

);

"

The address of this array is in ped_ComrnandTable. In case one of

the Amiga sequences cannot be substituted, you can give the value
'''377'' = 255 for this sequence in the ComrnandTable array. When
this sequence emerges somewhere with the output, the Amiga knows
that the translation of this sequence is possible in DoSpecial. When
your printer does not support some of these sequences you can give the
value '''377'' where no processing of the sequence in DoSpecial
occurs.

510

7.2 PRINTER DRIVERS

ABACUS

ped_DoSpecial:
This variable contains the address of the DoSpecial function:
DoSpecial (Command,OutPutBuffer,Line,LineSpace,CRLF,Params)
UWORD
*Command;
char
OutPutBuffer [] ;
BYTE
*Line;
BYTE
*LineSpace;
BYTE
*CRLF;
BYTE
Params[];
{

... )

Command returns the address of the command number.

OutPutBuffer is the memory range to which the new command
string is written. To realize the paper feed and transport back, Li ne

contains the address of a variable that can have the values -I, 0, 1. This
variable is added to an internal variable of the printer device that
contains the current print line on the paper.
When you, for example, want to paper feed one line, you must set this
variable to 1 in addition to the print command for the linefeed so that
the internal variable remains correct. With a paper transport back a line
you must give the value -1 in *Line. If no paper transport should take
place, the value 0 is given in *Line, or it is ignored.
LineSpace contains the address of the control character responsible
for the size of the linefeed. If, for example, the sequences "<ESC>O"
and "<ESC> I" establish the linefeed at 1/8 and 1/6 of an inch,
LineSpace contains the value "0" or "I".

CRLF specifies whether a linefeed should be sent after a CR or not

(*CRLF == TRUE => send linefeed). The parameters that you have
given the DoSpecial function through the printer device command
PRD_PRTCOMMAND are given in Params. When the DoSpecial ()
routine is called through the CMD_WRITE, no parameters are given in
Params.

ped_Render:

This routine takes over the hardcopy function. The following

parameters are given:
Render (ct,x,y,Status)
UBYTE
ct;
UWORD
x,y;
UBYTE
Status;
{

.. }

Because this routine must assume many tasks, these variables have
different interpretations. The Render function consists of six partial
functions. It is easiest to check these six partial functions through a
SWI TCH construct:

Sl1

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

switch (Status)
{

case 0:
/* Master Initialization */
/* x = width of the Hardcopy */
/* y = height of the Hardcopy */
break;
case 1:
/* transfer point into printer buffer */
/* ct = color of the point (Black = 0, Yellow = 1,
/*
Magenta = 2, Cyan = 3) */
/* x = X position */
/* y = Y Position */
break;
case 2:
/* send print buffer to the printer */
/* (* (pd PWrite (Buffer, Len); */
break;
case 3:
/* initialize printer buffer */
break;
case 4:
/* Close Down *1
/* ct = Error Code */
1* x = Special Flags *1
break;
case 5:
1* Pre Master initialization */
/* x = Special Flags *1
break;

What must happen in the partial functions?

case 0:

This partial function reserves the necessary print buffer in which the
individual pixels to be printed for the hardcopy are written. A printer
reset should also be executed. followed by a one-second delay.
The size of the print buffer is determined by the number of pins of the
printer. An eight-pin printer needs an 8*x byte print buffer. This print
buffer must also contain the control characters for "graphic mode on"
and "graphic mode off' so that the hardcopy can be sent immediately
after printing the text. With double buffering this print buffer is twice
as large.

case 1:

This partial function transfers the pixels given by X and Y into the
print buffer. You must calculate the Y coordinate of a hardcopy line so
that it fits in the print buffer described above.

case 2:

Here the print buffer sends graphic control characters to the printer. For
this the PWri te () function from the P rinterData structure is
used. This routine gives the address of the print buffer as well as the
number of bytes to be output. With double buffering you must also
determine the other print buffer for the transfer of the points in this
section function (case 1).

512

ABACUS

7.2 PRINTER DRIVERS

case 3:

After printing the buffer it must be re-initialized. This partial function

writes the control codes for "graphic on" and "graphic off' at the
beginning and end of the print buffers, and deletes the previously
entered pixels from the print buffer. This slows partial function 1 as
little as possible, and pixels still in the print buffer are ORed. Unset
pixels do not change the print buffer.

case 4:

This routine waits with (* (pd_PBothReady) ) () until both print

buffers (double buffering) are printed out, and then releases these and
returns the error code given in ct.

case 5:

This partial function is the ftrst called (even before case 0). In it you
can set the Render internal variables to inform case 1: that the
picture should be centered or variables for the print width is set. In x
you get the special flags that are given with DUMPRPORT.

7.2.1.3

The rest of the variables

ped _ Timeou tSecs:

This variable contains the number of seconds that the Amiga should
wait until the printer is turned on or set to ONLINE. When this time
elapses, the printer trouble requester appears. If you click on CANCEL
in this requester the PDERR_CANCEL error is sent.

ped_8BitChars:
This pointer contains the address of a 2S6-byte array that contains the
ASCII codes to be printed when using the extended fonts.

513

7. BASIC SYSTEM STRUCTURES

7.2.2

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Tips for programming a printer driver

These tips apply if you use the Lattice C compiler for developing your
printer drivers. All of the parameters given in Lattice use the long word
fonnat. That means that a four-byte UBYTE memory is needed to
access the bottom byte of this long word. The Lattice compiler reserves
registers a2-aS and registers d2-d6 from the call. Should you develop a
driver, you should be aware of this and adapt any byte access to
Lattice's quirks.
Although many of the functions described above are of type VOID
(they have no return value) you must return a zero in dO to the routine,
if it executed without an error. If an error occurs, you should return the
printer device error. Usually the routines Open and Close are
unnecessary. That is why these should have the following appearance
when they are not used:
return(Oll;

or
moveq IIO,dO
rts

514

7.3

ABACUS

7.3

FONTS AND TEXT OUTPUT

Fonts and text output

You probably have toyed with the thought of creating your own fonts.
Creating a font is as easy as booting a font editor, but you should
know what lies behind the Amiga fonts.
A font is available in different point sizes. Take the Opal font, for
example. This font comes in 12 and 9 sizes. If you look in the Fonts
directory of the SYS: diskette using the CLI dir command, you'l find
the following entry:
Opal (dir)
Opal. font

The file Opal. font is the font header. It contains the Opal font data
for the 12-pixel and 9-pixel sizes. The Opal directory contains the files
Opal. 12 and Opal. 9, which contain the character definitions.

7.3.1

The font header

The font header has the following structure:
FontContentsHeader
FontContents (for example for font size 12)
FontContents (for example for font size 9)

The FontContentsHeader structure informs the Amiga that it

handles this file as a font header, and how many fonts it manages. This
structure looks like this:
offset

Structure
struct FontHeader
{

o OxOO
2 OxOO
4 OxOO

UWORD fch FileID;

UWORD fch=NumEntries;
1* defined in "libraries/diskfont. h" *1

fch_FileIO contains the value OxOfOO and signals the Amiga that it
handles this fIle as a font header.
fch_NumEntries contains the total number of fonts the Amiga has
available. It only lists as many fonts that exist under a certain name,
e.g., Opal. Because the Opal font is present in two point sizes (9 and

515

ADVANCED SYSTEM PROGRAMMER'S GUIDE

7. BASIC SYSTEM STRUCTURES

12), this enlIy has the value 2 for the Opal font. The FontContents
structure supplies the exact information about each font:
Offset

Structure
struct FontContents

o OxOOO
256 OxlOO
258 Oxl02
259 Oxl03

char
UWORD
UBYTE
UBYTE

fc_FileName[256];
fc YSize;
fc-Style;
fc=Flags; 260 Oxl04 ) 1* defined in
libraries/diskfont.h *1

fc_FileName contains the filenames for the font types (e.g.,

Opal/12). Through these filenames the Amiga can load and use the
fonts. A FontContents structure must be stored for each font type.
The rest of the bytes are filled with zeros.
f c YS i z e contains the size of the font. This variable can be found
very quickly when opening the font if the required font is present.

fc_Style contains the text style of the font. Normally the value zero
is here, which says that the font is saved in normal style. You can, for
example, define the individual characters so that they appear as italics.
Then you should set the FSF_ITALIC flag (4) so that the Amiga
knows that an italic font in the size Y S i z e is found in the
fc _F ileName file. If you want to open a font that is eight lines high
and should be italic, the Amiga can recognize the header to see if such a
font exists.

If this is not the case, the Amiga tries to load the font that comes the
closest to the given size. If this font only contains normal characters,
the font can be italicized through software if needed. The following text
types are recognized by the Amiga, or can be created with the software:

FSF ITALIC (4):

The top half of the character is pushed a bit to the right.

FSF BOLD (2):

The characters are displayed normally and pushed to the right with
tf_BoldSmear pixels.

FSF _UNDERLINED (1):

Here a line is drawn in the baseline.

FC FLAGS:
Contains the flags that inform the Amiga in the fonfs status.

516

7.3 FONTS AND TEXT OUTPUT

ABACUS

FPF _ROMFONT (1):

The font is stored in ROM. This flag does not apply to us because we
are only concerned with disk supported fonts. The single font in ROM
is the Topaz font.

FPF _DISKFONT (2):

The font is stored on disk. This flag must be set in the
FontContents structure of the flags variable.

FPF _PROPROTIONAL (32):

The font supports proportional text (variable character widths).

FPF _REMOVED (128):

This flag announces that the font of the system is not ready. Because
that is not encountered for the disk fonts that are not opened, this flag
must also be set.
The following is a short C program that initializes the necessary
structures for a font header and saves this to disk.
1***************************************************************
Font.c
*
*
August 1988
*
*
(c) Bruno Jennrich
*
*

*
* Function: Create Font-Header

*
*

***************************************************************/
1***************************************************** **********

* Compile-Info:
*
* cc Font.c
* In Font.o -Ic

*
*
*
*

****************************************************** *********1
lIinclude
lIinclude
llinclude
#include
#include

"exec/types.h"
"exec/memory.h"
"libraries/dos.h"
"libraries/diskfont.h"
"graphics/text.h"

IIdefine NUMFONTS 1
VOID

*Open () ;

IIdefine FONCON LEN (ULONG) sizeof (struct FontContents)

#define FONHED LEN (ULONG) sizeof (struct FontContentsHeader)
BYTE

*FontHeaderName

"OwnFont. font";

517

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct FontContentsHeader
FontContentsHeader[NUMFONTSj

{OxOfOO,
/* File is Font-Header */
OxOOOl /* Single Font */
}:

struct FontContents
FontContents[ANZFONTSj
{"OwnFont/9" ,
Ox0009,
OxOO,
FPF_REMOVEDIFPF_DISKFONT
}

};
/***************************************************************

main

*
***************************************************************/
*

rrain ()
{

UWORD *FileHandle
UWORD i,j;

01;

FileHandle = Open (FontHeaderName, (ULONG)MODE NEWFlLE);

if (FileHandle == OL)
{

printf ("No File !!! \n");

exit (0);
for (j=O;j<ANZFONTS;j++)
if

(j==O)
Write (FileHandle,&FontContentsHeader[Oj,FONHED_LEN);

i = strlen (FontContents[j).fc FileName);

for (;i<256;i++)
1* fill with null bytes */
FontContents[j) . fc_FileName[ij = OxOO;
Write (FileHandle,&FontContents[jj,FONCON_LEN):
Close (FileHandle);

Note:

518

You must store your own FontContents structure for each size of
the font (e.g., Opal-12, Opal-9). The font header created from the above
program must be copied into the Font directory, and then the header
determines the appearance of each character.

7.3 FONTS AND TEXT OUTPUT

ABACUS

7.3.2

The actual character data

The actual character data is saved in files. When you look at the Opal
subdirectory for instance, there you find files named 12 and 9. These
flIes contain the actual data. Let's create a file like this.
The Amiga handles these ftles as nonnal programs. You can call a font
flIe like a nonnal program-{)nly nothing happens. The fIrst four bytes
of these programs contain the commands:
moveq 110, dO
rts

You have stored the fonts as program files to be able to load and
remove these simply with LoadSeg () and UnLoadSeg ( ) . This
makes the two above commands necessary. so that a system interrupt
does not happen when starting. A FontData fIle has the following

appearance:
moveq fO, dO
rts
DiskFontHeader
FontData

Let's examine the disk font header. This structure has the following

appearance:
Offset

Structure
struct DiskFontHeader
{

o
14
16
18
22
52

OxOO
OxOe
Oxl0
Ox12
Ox16
Ox34

struct Node
dfh Node;
UWORD
dfh=:FileID;
UWORD
dfh Revision;
LONG
dfh-Segment;
char
dfh-Name [32] ;
struct TextFont dfh-TF;
/* defined in "libraries/diskfont.h" */

dfh_Node adds the font to the system font list after it is loaded.
Mter that the Amiga no longer needs to access the disk, but the user
can still access the font
dfh_FileID contains a label that informs the Amiga to handle the
ftle as a font file. This label has the value Ox0f80.
dfh_Revision can be used to assign your own private font version
number. The value is usually here.

519

ADVANCED SYSTEM PROGRAMMER'S GUIDE

7. BASIC SYSTEM STRUCTURES

dfh Segment contains the address of the segment list that is returned
after-LoadSeg ( ) . It is necessary to be able to remove the font from
the system after it is used with UnLoadSeg ( ) . This value must be
set to zero by you. The Atniga does the rest.
dfh Name contains the name of the fonts so that the OpenFont ()
command can recognize that the font to be opened is found in the
memory.
dfh TF is a TextFont structure which returns a pointer after
OpenFont () or OpenDiskFont (). The font can then use this
pointer.
This TextFont structure (dfh_TF) must be initialized by the user. It
looks like this:
Offset

Structure
struct TextFont
{

o Oxoo
20
22
23
24
26
28
30
32
33
34
36
40
44
48

Ox14
Ox16
Ox17
Ox18
Oxla
Oxle
Oxle
Ox20
Ox2l
Ox22
Ox24
Ox28
Ox2c

Ox30

struct Message tf_Message; /* important for

UnLoadSeg * /
UWORD
tf YSize;
tf-Style;
UBYTE
UBYTE
t(~Flags;
UWORD
tf XSize;
tf-Baseline;
UWORD
tf-BoldSmear;
UWORD
t()ccessors;
UWORD
tf LoChar;
UBYTE
UBYTE
tCHiChar;
UWORD
tf Modulo;
tf-CharLoc;
APTR
tf-CharSpace;
APTR
APTR
t(:CharKern;
/* defined in "graphics/text.h" */

tf_YSize, tf_Style and tf_Flags contain the same values as

the variables in the FontContents structure of the same names.
t f _ XS i ze contains the width of a character in pixels. When you use
proportional fonts, this value changes from character to character. For
example, the "!" in a proportional font may be only three pixels wide,
while the "A" in the same font may be nine pixels wide. You should
specify the maximum width ofa character in tf_xSize when using
proportional fonts. Many word processors use this value to write the
characters in a matrix, which cannot be done with proportional fonts.
tf_Baseline contains the line on which the character is positioned.
This baseline is given in lines from the top line of the character. When
you determine the position of a character to be given with Move
(RastPort, 0 ,10), for example, the baseline of the character is

520

7.3

ABACUS

FONTS AND TEXT OUTPUT

at line 10 of the RastPort. The baseline must also act as an underline

for software reasons.
tf_BoldSmear gives the smear factor for bold type.
tf_Acceaaora contains the number of the user currently accessing
the font. If this variable contains a value of zero, the memory allocated
for the font can be freed.
tf LoChar contains the ASCII code of the frrst defmed character.
tf_HiChar contains the ASCII code of the last character generated.
tf_Module supplies the width of the character array.
tf_CharSpace points to the UWORD array that determines the
width of each character.
tf_CharKern points to a WORD array that determines the position
at which the character data should be displayed.

Say you want to create a font that consists of capital letters only. The
tf_ LoChar and tf_ HiChar variables would then contain the values
65 decimal (A) and 91 (Z) respectively. Your new characters are then

saved in an array that looks like this:

Byte
Byte
Byte

1, 2, 3, 4, 5, 6, 7, 8

9, 10, 11, 12, 13, 14, 15, 16

56, 57, 58, 59, 60, 61, 62, 63

Bytes 1-8 contain the top lines of all of the characters. Bytes 9-16
contain the second lines of all the characters, and so on. You see, the
character array is organized like a bit-map. The Blitter chip must know
the size of the array so that the Blitter can correctly read the data for a
character from this array. In this case the width would be eight bytes.
You must then give the value 8 for t f _Module.
Because the individual characters in the character array are saved without
any spaces in between (to save memory), the CharSpace array allows
display of each character. This array contains the width of each
character, as well as the width of the character container into which the
characters from the CharLoc array are copied.
The CharKern array contains the column to which the characters in
this container are copied. The following diagram shows this
connection:

521

ADVANCED SYSTEM PROGRAMMER'S GUIDE

7. BASIC SYSTEM STRUCTURES

CharLot:

CharPos:

'J

L-------'--

'}

t
16

30

37

Character on the screen:

Now you have the elements needed to create your own font. The
following assembly language program contains a font that redefines the
capital letters A through F. Remember that you must always defme one
character more than needed, that always appears when an ASCII code
not included in the font is encountered (see LoChar and HiChar
above). Undefined characters on the keyboard are presented as rectangles.

522

7.3 FONTS AND TEXT OUTPUT

ABACUS

****************************************************************

9.asm
August 1988
(c) Bruno Jennrich

*
*

*
*

*
*

****************************************************************
****************************************************************

Info:

*
* as 9
* ln 9.0

*
*

****************************************************************

moveq to,dO ; fir versehentlichen Start

rts

; Node-Structure for oner binding in System font list

dc.l
;In Succ
dc.l
1n=P red
dc.b 12
;In Type (NT_FONT)
dc.b
;In=Pri
dc.l Name ;In_Name
dc.w $Of80 ;DiskFontHeader-ID (DFH_ID)
dc.w 1
; Revision
; Segment
dc.l
Name:
dc.b
"OwnFont/9",0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

FONT:
dc.l
;In_Succ
;Message-Structure
dc.l
;In Pred
dc.b 12
;In-Type (NT]ONT)
dc.b
;In-Pri
dc.l Name
;In=Name
dc.l
;mn ReplyPort
dc.w Ende-FONT ;Length
dc.w 9
;YSize
dc.b
;tf Style (before defined?)
dc.b 128+32+2
;tf-Flags
(FPF REMOVED+FPF_PROPORTIONAL+FPF_ROMFONT)
dc.w 11
;tf XSize
dc.w 7
; t ()aseline
dc.w 1
itf_BoldSmear
dc.w
;tf_Accessors
dc.b 65
;tf LoChar 'A'
dc.b 70
;tCHiChar 'F'
dc.l CharData
;tf CharData
;tf-Modulo
dc.w 8
dc.l CharLoc
;tf=CharLoc
dc.l CharSpace ;tf_CharSpace
dc.l CharKern
;tf_CharKern

CharData:
de. w
de. w
de. w
de. w
de. w
de. w
de. w
de. w
de. w

: 0123456789012345 6789012345678901 2345678901234567 8901234567890123

'0000110000111111, '0000111111111111, '1100111111111111, tl111111111111111
'0001111000110001, U001100 000110000, '011011000000011 0, '000000 1000000001
'0001111000110001,U011 000000110000, '001111 000000011 0, '0000001000000001
'0011 001100111111, '0011000000110000, \0011110000000110, '0000001000000001
'0011 001100110001, UOll000000110000, \0011111111000111, '1111001000000001
\0111111110110000, '1111000000110000, \0011110000000110, \000000100000000 1
'0110000110110000, U111000000110000, '0011110000000110, \0000001000000001
'1100000011110001, UO 01100000110000, '011011 0000000110, \0000001000000001
\ 1100000011111111, \0000111111111111, \110011111111111 0, \0000001111111111
A

...

...

...

...

undefined

523

ADVANCED SYSTEM PROGRAMMER'S GUIDE

7. BASIC SYSTEM STRUCTURES

CharLoc:

dc.w
dc.w
dc.w
dc.w
dc.w
dc.w
dc.w

0,10
10,8
18,8
26,10
36,9
45,9
54,10

CharSpace:
dc.w 11
dc.w 9

dc.w
dc.w
dc.w
dc.w
dc.w

;A
;B
;C
;D

;E
;F
; undefined

;A

;B
;C

11

;D

10
10

;E

11

;F
; undefined

CharKern:

dc.w
dc.w
dc.w
dc.w
dc.w
dc.w
dc.w

1
1
1
1
1
1

Ende:
end

Because font files must be stored as program fIles, the following steps
must be taken:
as 9.asm
In 9.0

The linking is necessary to store the file as a program file (including all
of the hunks) so that it can be loaded using LoadSeg () . Then we
must copy the finished program file to a subdirectory of the F 0 n t
directory (you must create a subdirectory within the Font directory
using the CLI makedir command). Then you can use the font.
The C program printed in this chapter (Font. c) creates a header file
for the font Ow n F 0 n t. To use this font you must place the
subdirectory OwnFont in the Fonts directory and copy the assembled
version of the font created above (9). The font header also must be
copied to the Font directory.

524

7.4 KEYMAPS

ABACUS

7.4

Keymaps
It is important that the keyboard of a computer be adaptable to fit other
languages, because some countries use different keyboard arrangements.
Some of the keys must be transposed (e.g., Y becomes Z and Z
becomes Y). This alone is not enough. The Amiga keyboard, which
includes a small microprocessor, tells the Amiga that a certain key was
pressed, rather than a certain character. The Amiga does not know
which character is represented by this key. The number of the key sent
to the Amiga is called the RAWKEY number.
The following diagram of the International Amiga 500 and Amiga 2000
keyboard, includes the RAWKEY numbers in hexadecimal notation.
The Amiga International keyboard has two extra keys, one by the
<Return> key and one by the <Left Shift> key. The operating system
converts these RAWKEY numbers into key characters. The system
uses a table called a key map as a reference, into which the character
representing each RAWKEY number is entered. The Amiga includes
key maps for a number of different countries. A keymap is usually
loaded during the boot operation, or by the CLI SetMap command. If
no keymap is found the Amiga defaults to an American (USA) keymap.
In addition to regular characters, the keymap indicates whether a key
reacts to the <Caps Lock> key. An active <Caps Lock> key usually
has the same effect as continually pressing a <Shift> key. This means
that you get upper case letters instead of lower case letters when you
press the letter keys. If you press number keys you may also get the
corresponding special characters (!,",#,$, ...). Since most people want
access to upper case letters and numbers, but not the shifted numbers,
you can exclude any keys from the <Caps Lock> function, including
number and cursor keys.
The keymap also assigns key repeating for individual keys. For
example, if you press a cursor key, the key continues to repeat until
you release the key. This lets you move the cursor easily in a word
processor. The <Return> key has no repeat function since it is used
mainly for input, and shouldn't have a repeat function assigned to it.

S2S

7. BASIC SYSTEM STRUCTURES

526

ADVANCED SYSTEM PROGRAMMER'S GUIDE

ABACUS

7.4 KEYMAPS

All of these parameters are present in the keymap for each key. A
keymap has the following structure:
struct KeyMap
{

Oxoo
Ox04
Ox08
OxOC
Ox10
Ox14
Ox18
Ox1C
Ox20

0
4
8
12
16
20
24
28
32

UBYTE
ULONG
UBYTE
UBYTE
UBYTE
ULONG
UBYTE
UBYTE

*km LoKeyMapTypes:
*km-LoKeyMap;
*km=LoCapsable:
*km LoRepeatable:
*km=HiKeyMapTypes:
*km HiKeyMap:
*km-HiCapsable;
*km=HiRepeatable;

The parameters of the keys containing a RAWKEY number from 0 to

Ox3f are in LowKeyMap, while the rest belong to the HighKeyMap.
The keymap points to the table which contains an entry for each key.
The KeyMapTypes pointer includes a byte for each key from which is
detennined which character the key delivers in conjunction with
<Shift>, <Alt> and <Clll>. These characters are stored in the second
table and occupy one long word per key. One bit is reserved for each
key in the third table. This bit is set to 1 if the key should react to
<Caps Lock>. The fourth and final table includes a bit to indicate if the
key has a repeat function.
The bit assignment of the last two tables to the RAWKEY numbers is
intuitive: Bit 0 of byte 0 of the table belongs to the RAWKEY number
o (km_Lo; with km_Hi you must add Ox40 to the RAWKEY
number), bit 1 of byte 0 belongs to RAWKEY number 1, bit 0 of byte
1 to RAWKEY number 8 and so on. The RAWKEY number divided by
eight results in the byte number, and the bit number is the remainder
(modulo eight).
The KeyMapTypes includes the following, which tell if the
corresponding key reacts to a qualifier Shift>, <Alt> or <Clll:
KC_NOQUAL
KC VANILLA
KCF SHIFT
KCF ALT
KCF-CONTROL
KCF DOWNUP
KCF DEAD
KCF STRING
KCF-NOP

0
7
Ox01
Ox02
Ox04
Ox08
Ox20
Ox40
Ox80

Reacts to no other key

Reacts to Shift, Alt and Ctrl
Reacts to Shift
Reacts to Alt
Reacts Ctrl
Reacts first after key release
Special key for special characters
Displays string instead of character
No reaction

Depending on which flags are set, the corresponding character is in the

long word of the second table, km_ LoKeyMap or km_ HiKeyMap.

527

ADV ANCED SYSTEM PROGRAMMER'S GUIDE

7. BASIC SYSTEM STRUCTURES

O. Byte

Qualifier
KC_NOQUAL
KCF SHIFT
KCF ALT
KCF CONTROL
KCF ALT+KCF SHIFT
KCF CONTROL+KCF ALT
KCF CONTROL+KCF SHIFT
KC VANILLA

Shift+Alt
Ctrl+Alt
Ctrl+Shift
Shift+Alt

1. Byte

2. Byte

Alt
Alt
Ctrl
Alt

Shift
Alt
Ctrl
Shift
Ctrl
Shift
Shift

3. Byte
alone
alone
alone
alone
alone
alone
alone
alone

KC_VANILLA, which is only a combination KFC_SHIFT, KCF_ALT

and KCF_CONTROL, adds a special effect to the letter keys and a few
other keys. When the <Ctr1> key is pressed, bits 5 and 6 are cleared
from the character code.

If the KCF_ S TRI NG flag is set, the long word is handled as a pointer
to a string descriptor (more on this later) instead of four individual
bytes. The following are a few examples from a German keymap:
RAWKEY-Nummer: OxOE
Ox80

KeyMapType:

This means that this RA WKEY number is not allocated because there
is no key that sends this number.
RAWKEY Number: Ox30
Ox01
0,0, '>','<'

KeyMapType:
KeyMap:
Capsable:
Repeatable:

Reacts only to the shift key.

0
1

This key usually sends the < character. If the <Shift> key is pressed in
addition, the result of the key is the> character. The <Caps Lock> key
does not react with this key, and for that reason it has a repeat function.
RAWKEY-Nummer: Ox45
Ox02
Reacts to the Alt key.
0,0, Ox9B, OxlB

KeyMapType:
KeyMap
Capsable:
Repeatable:

o
o

This key (ESCAPE key) usually delivers Oxlb (27). When <Alt> is
pressed at the same time, you get Ox9B. This key does not react to the
<Caps Lock> key and does not have a repeat function.
RAWKEY-Nummer: Ox01
Ox03
Reacts to the Shift and Alt keys.
, ! I, OxB9, 1 ! ., 111

KeyMapType:
KeyMap:
Capsable:
Repeatable:

o
1

This key without a qualifier results in a 1. When you press <Shift>

with it, you get the !, with the <Alt> you get the character with the
code OxB9 and when you press the <Shift> and <Alt> key at the same

528

7.4 KEYMAPS

ABACUS

time, you get the ! again. The key reacts to the <Caps Lock> key and
has a repeat function for this.
RAWKEY-Nurrmer:
KeyMapType:
KeyMap:
Capsable:
Repeatable:

Ox10
Reacts to Shift, A1t, Ctrl.
Ox07
OxC5,OxE5, IQI, 'q'
1
1

This key is a normal letter key. Without a qualifier you get a small
letter and with a qualifier you get a capital letter. When you press
<A1t>, you get a special character, OxC5 and with <Shift> (or with the
activated <Caps Lock> key) 0xE5. When you press <Ctrl> you get the
code of the character without a qualifier, but with the 5th and 6th bits
cleared, q = Ox71 => Ox71 & Ox9F = Oxll = IIQ. You always get this
code when you have pressed <Ctcl> at the same time, regardless of
whether you have also pressed <Shift> or <Alt>. This key reacts to
<Caps Lock> and has a repeat function.
The following keys supply strings, so that we should look at the
construction of a string descriptor. Just as each key can send different
characters, this can also send different strings. For each combination
with one allowable qualifier there is an entry in the string descriptor
made up of two bytes, just like normal keys. The first byte gives the
length of the string and the second gives the distance of the string from
the beginning of the string descriptor. Unlike normal keys, the order
here is exchanged, which means the string for the key without the
qualifier is described first, then for the key with <Shift>, then with
<A1t>, <Shift> plus <A1t>, etc.
RAWKEY-Nummer:
KeyMapType:
KeYMaP:
Stringdescr.:
Capsable:
Repeatable:

Ox5F
Ox40
String.
Pointer to string descriptor
Ox03,Ox02
Ox9B, Ox3F, Ox7E

o
o

This key Help supplies a string of length three: Ox9B Ox3F Ox7E.
RAWKEY-Nummer:
KeyMapType:
KeyMap:
Stringdescr.:

Capsable:
Repeatable:

Ox42
String, reacts to Shift.
Ox41
Pointer to String descriptor.
OxOl,Ox04
without shift (length: 1)
Ox02,Ox05
with Shift (Length: 2)
Ox09
String without Shift (distance: 4)
Ox9B,Ox5A
String with shift (distance: 5)
0
1

This key, the <Tab> key, usually sends a character with code 9. When
pressed with the <Shift> key, the <Tab> key sends the string Ox9B
Ox5A.

529

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Complicated strings are not offered by the keymap. For these we must
access the dead keys. The following example does not work with the
USA keymaps, use SETMAP d to enable the German keymap. These
are especially interesting when used in conjunction with the equals key
(RAWKEY number OxOC, the apostrophe key in the German keymap).
If you press this key, nothing happens. If you press a vowel key
<e>, <i>, <0>, <U, <Space>, <y> or <n>, the system displays the
corresponding character with an accent (try this from the CLI).

a>,

Ail of these keys '>, vowels, <Space>, <y> and <n are marked as
dead keys in the KeyMapTypes. When a key is a dead key, the
key map long word contains a pointer that points to a dead key
descriptor. This consists of a row of 2 byte entries from which the first
byte gives how the second is handled:

The second byte is the character code that sends this key with
the corresponding qualifiers.

This key (DFP _MOD) is modified through a dead key. The

second byte is an offset from the beginning of the dead key
descriptor field to a field of 18 bytes (this number varies from
key map to keymap), that the codes the characters contain.
These keys can send the codes depending on which dead keys
were pressed.

This key (DPF_DEAD) is the actual dead key. The second byte
contains an offset that designates which character is used from
the I8-byte field. This offset is noted in the operating system
until another key is pressed. When this key is handled as a
dead key, this offset is ignored. The offset itself is actually
divided into two nibbles. When the high nibble (bits 7
through 4) is unequal to zero, the value of this nibble is
multiplied by the low byte, and both are added together with
the previous offset. When the previous offset of the high
nibble was unequal to zero, only the low nibble is added. If no
previous offset exists, zero is added and only the product is
used.

Here are a few examples that hopefully will make it clearer:

RAWKEY Number:
KeyMapType:
KeyMap:
Dead-Key-Des. :

530

Ox23
Ox27
Dead and Vanilla
pointer to dead key descriptor
O,'f'
without qualifier
0, 'F'
with Shift
8,Ox61
Alt (dead key)
8,Ox61
Alt+Shift (dead key)
0,Ox06
Ctrl
0,Ox06
Ctrl+Shift
0,Ox86
Ctrl+Alt

7.4 KEYMAPS

ABACUS

O,OxB6
Capsable:
Repeatable:

Ctrl+Alt+Shift

1
1

This key supplies either a normal character or an offset as a dead key

when you press it together with the <Alt> key. The same goes for the
next key:
RAWKEY Number:
KeyMapType:
KeyMap:
Dead-Key-Des.:

Ox24
Ox27
Dead and Vanilla
Pointer to dead key descriptor
O,'g'
without qualifier
0, 'G'
with Shift
B,Ox62
Alt (dead key)
Alt+shift (dead key)
B,Ox62
O,OxO?
Ctrl
O,Ox07
Ctrl+Shift
O,OxB?
Ctrl+A1t
O,OxB7
Ctrl+Alt+Shift

Capsable:
Repeatable:

1
1

This key reacts the same way as mentioned before. but it has a different
offset than the dead key (and also sends a different character). Let's take
a third dead key:
RAWKEY Number:
KeyMapType:
KeyMap:
Dead-Key-Des. :

Ox25
Ox27
Dead and Vanilla
Pointer to dead key descriptor
without qualifier
0, 'h'
with Shift
0, 'H'
8,Ox03
Al t (dead key)
B,Ox03
Alt+Shift (dead key)
O,OxOB
Ctrl
O,OxOB
Ctrl+Shift
O,Ox88
Ctrl+Alt
O,OxBB
Ctrl+Alt+Shift

Capsable:
Repeatable:

1
1

This key has a dead key offset where the high byte nibble is zero. Now
here is a key modified through the dead keys:
RAWKEY Number: Ox20
KeyMapType:
Ox2?
Dead and vanilla
KeyMap:
Pointer to dead key descriptor
Dead-Key-Des. :
l,OxlO
without qualifier (dead modified)
l,Ox22
Shift (dead modified)
O,OxE6
Alt
O,OxC6
Alt+Shift
O,OxOl
Ctrl
O,OxOl
Ctrl+Shift
O,OxBl
Ctrl+Alt
Ctrl+Alt+Shift
O,OxBl

531

7.

BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Field for key without qualifier:

'a', OxEO,OxEl,OxE2,OxE3,OxE4
OxEO,OxEO,OxE2,OxEO,OxEO,OxEO
OxEl,OxE2,OxEl,OxEl,OxEl,OxEl
Field for key with Shift:
'A', OxCO,OxCl,OxC2,OxC3,OxC4
OxCO,OxCO,OxC2,OxCO,OxCO,OxCO
OxCl,OxC2,OxCl,OxCl,OxCl,OxCl
Capsable:
Repeatable:

1
1

Now let's look at a few options offered by different field entries, and
which keys you must press:
A
Alt-F
A
Alt-G
Shift-A
Alt-H
Shift-A
Alt-F
Alt-G
A
Alt-G
Alt-F
A
Alt-G
Alt-H
A
Alt-H
Alt-F
A
Alt-H
Alt-G
Shift-A

No offset => 'a' (character in position zero)

Offset = Ox6l
Low nibble of offset, you get OxEO
Offset = Ox62
Low nibble of offset = 2, result => Oxcl
Offset = 3
Offset = 3, result => OxC2
Offset = Ox6l
Offset = Offset & OxOF + (6 * 2)
13
Character in position 13 OxE2
Offset = Ox62
Offset = Offset & OxOF + (6 * 1)
8
Character in position 8 OxE2
Offset = Ox62
Offset = 3
Character in position 3 OxE2
Offset = 3
Offset = Offset & OxOF + (6 * 1)
9
Character in position 9 OxEO
Offset = 3
Offset = Offset & OxOF + (6 * 2)
15
Character in position 15 Oxel

Now let's show you an example of a keymap in source form. The

following assembler source code is a disassembly of a German keymap
used on the Amiga:
German Keymap
(disassembled)
;Node:
dc.l 0,0
dc.w 0
dc.l name
: Keymap:
dc.l lotypes
dc.l lokeymap
dc.l locaps
dc.l lorepeat
dc.l hitypes
dc.l hikeymap
dc.l hi caps
dc.l hirepeat
locaps:
dc.b O,O,$FF,7,$FF,7,$FE,O

532

7.4 KEYMAPS

ABACUS

hicaps:
de.b 0,0,0,0,0,0,0,0
lorepeat:
de.b $FF,$BF,$FF,$EF,$FF,$EF,$FF,$F7
hirepeat:
de.b $47,$F4,$FF,$7F,0,0,0,0
lotypes:
de.b $07,$03,$03,$03,$03,$03,$03,$03
de.b $03,$03,$03,$03,$03,$07,$80,$00
de.b $07,$07,$27,$07,$07,$07,$27,$27
de.b $27,$07,$07,$03,$80,$00,$00,$00
de.b $27,$07,$07,$27,$27,$27,$27,$27
de.b $07,$07,$07,$05,$80,$00,$00,$00
de.b $01,$27,$07,$07,$07,$07,$27,$07
de.b $03,$03,$07,$80,$00,$00,$00,$00
hitypes:
de.b $22,$00,$41,$00,$04,$02,$00,$80
de.b $80,$80,$00,$80,$41,$41,$41,$41
de.b $41,$41,$41,$41,$41,$41,$41,$41
de.b $41,$41,$05,$05,$00,$00,$00,$40
de.b $80,$80,$80,$80,$80,$80,$80,$80
de.b $80,$80,$80,$80,$80,$80,$80,$80
de.b $80,$80,$80,$80,$80,$80,$80,$80
lokeymap:
de. b

de.b
de.b
de.b
de.b
de.b
de.b
de.b
de.b
de.b
de.b
de. b
de.l
de.b
de.b
de.b
de.b
de.b
de.l
de.b
de.b
de.b
de.l
de.l
de.l
de.b
de.b
de.b
de.b
de.b
de.b
de.b
de.l
de.b
de.b
de.l
de.l
de.l

1 -' ,

.. , - ' I

.. I

'!', $B9, , ! " '1'

$B2,'@','n','2'
'i',$B3,$A7, '3'
$A2,$BO,'$', '4'
'%',$Be,'%', '5'
'A',$BD,'&', '6'
'&',$BE, 'I', '7'
'*', $B7, , (' , '8'
'(', $AB, ') " '9'
')',$00,'=','0'
' ',' -' , , ? ' , $DF
deadapostroph
'I',' \', , I " '\'
$00,$00,$00,$00
$00,$00,$00, '0'
$C5,$E5,'Q','q'
$BO,$BO,'W', 'w'
deade
$AE,$AE, 'R', 'r'
$DE,$FE,'T', 't'
$A5,$A4, 'Z', 'z'
deadu
deadi
deado
$B6,$B6, 'P', 'p'
'{',' [' , $DC, $FC

'}',']','*','+'
$00,$00,$00,$00
$00,$00,$00, '1'
$00,$00,$00, '2'
$00,$00,$00, '3'
deada
$A7,$DF,'S', 's'
$DO,$FO, 'D', 'd'
deadf
deadg
deadh

533

7. BASIC SYSTEM STRUCTURES

dc.l
dc.l
dc.b
dc.b
dc.b

deadj
deadk
$A3,$A3, 'L', '1'
':',';', $D6, $F6
'''',$27,$C4,$E4

de. b ." 1 I

dc.b
dc.b
dc.b
dc.b
dc.b
dc.l
dc.b
dc.b
dc.b
dc.b
dc.l
dc.b
dc.h
dc.b

ADVANCED SYSTEM PROGRAMMER'S GUIDE

't I ,

,A I ,

1:# I

$00,$00,$00,$00
$00,$00,$00, '4'
$00,$00,$00, '5'
$00,$00,$00, '6'
$00,$00,'>','<'
deadz
$F7,$D7,'X', 'x'
$C7,$E7,'C', 'c'
$AA,$AA,'V', 'v'
$BA,$BA, 'B', 'b'
deadn
$BF,$BS, 'M', 'm'
'<' I ' I I I';

1, . ,

'>',$2E, ':',$2E

de. b .?,. /. ,. "

1_ 1

dc.b $00,$00,$00,$00
dc.b $00,$00,$00,$2E
dc.b $00,$00,$00, '7'
dc.b $00,$00,$00, 'S'
dc.b $00,$00,$00, '9'
hikeymap:
dc.l deadspace
dc.b $OO,$OO,$OO,$OS
dc.l strtab
dc.b $OO,$OO,$OO,$OD
dc.b $OO,$OO,$OA,$OD
dc.b $00,$00,$9B,$lB
dc.b $00,$00,$00,$7F
dc.l $00000000
dc.1 $00000000
dc.l $00000000
dc.b $00,$00,$00, '-'
dc.l $00000000
dc.l strcdown
dc.l strcup
dc.l strcright
dc.l strcleft
dc.l strfl
dc.l strf2
dc.l strf3
dc.l strf4
dc.l strf5
dc.l strf6
dc.l strf7
dc.l strfa
dc.l strf9
dc.l strflO
dc.b $OO,$OO,'{','['
dc.b $00,$00,' I', ']'
dc.b $00,$00,$00, 'I'
dc.b $00,$00,$00, '*'
dc.b $00,$00,$00, '+'
dc.l strhelp
dcb.l 24,0
;Strings and Dead-Keys
deadapostroph:

534

7.4

ABACUS

I{EVMAPS

dc.b $08,$62,$08,$61,$00, '=',$00, ,+,

deadf:
dc.b $00,'f',$00,'F',$08,$61,$08,$61
dc.b $00,$06,$00,$06,$00,$86,$00,$86
deadg:
dc.b $00, 'g',$00,'G',$08,$62,$08,$62
dc.b $00,$07,$00,$07,$00,$87,$00,$87
deadh:
dc.b $00,'h',$00,'H',$08,$03,$08,$03
dc.b $00,$08,$00,$08,$00,$88,$00,$88
deadj:
dc.b $OO,'j',$OO, 'J',$08,$04,$08,$04
dc.b $00,$OA,$00,$OA,$00,$8A,$00,$8A
deadk:
dc.b $00,'k',$00,'K',$08,$05,$08,$05
dc.b $00,$OB,$00,$OB,$00,$8B,$00,$8B
deada:
dc.b $01,$10,$01,$22,$00,$E6,$00,$C6
dc.b $00,$01,$00,$01,$00,$81,$00,$81
dc.b 'a',$EO,$El,$E2,$E3,$E4,$EO,$EO,$E2
dc.b $EO,$EO,$EO,$E1,$E2,$E1,$E1,$E1,$E1
dc.b 'A',$CO,$C1,$C2,$C3,$C4,$CO,$CO,$C2
dc.b $CO,$CO,$CO,$C1,$C2,$C1,$C1,$C1,$C1
deade:
dc.b $01,$10,$01,$22,$00,$A9,$00,$A9
dc.b $00,$05,$00,$05,$00,$85,$00,$85
dc.b 'e',$E8,$E9,$EA, 'e',$EB,$E8,$E8,$EA
dc.b $E8,$E8,$E8,$E9,$EA,$E9,$E9,$E9,$E9
dc.b 'E',$C8,$C9,$CA, 'E',$CB,$C8,$C8,$CA
dc.b $C8,$C8,$C8,$C9,$CA,$C9,$C9,$C9,$C9
deadi:
dc.b $01,$10,$01,$22,$00,$A1,$00,$A6
dc.b $00,$09,$00,$09,$00,$89,$00,$89
dc.b 'i',$EC,$ED,$EE, 'i',$EF,$EC,$EC,$EE
dc.b $EC,$EC,$EC,$ED,$EE,$ED,$ED,$ED,$ED
dc.b 'I',$CC,$CD,$CE, 'I',$CF,$CC,$CC,$CE
dc.b $CC,$CC,$CC,$CD,$CE,$CD,$CD,$CD,$CD
deadn:
dc.b $01,$10,$01,$22,$00,$AD,$00,$AF
dc.b $00,$OE,$00,$OE,$00,$8E,$00,$8E
de. b . n' , 'n' , n I , 'n ' , $Fl, 'n' , n' , n' ,In'
de. b . n' , 'n I , 'n' , 'n I , In' , 'n' , 'n' , 'n' ,In'
dc.b IN', 'N', 'N', 'N', $01, 'N', 'N', 'N', 'N'
de. b N' ,IN 1 ,

N I ,IN' I

N1 ,

N' , I N I

NI

N'

deado:
dc.b $01,$10,$01,$22,$00,$F8,$00,$D8
dc.b $00,$OF,$00,$OF,$00,$8F,$00,$8F
dc.b 'o',$F2,$F3,$F4,$F5,$F6,$F2,$F2,$F4
dc.b $F2,$F2,$F2,$F3,$F4,$F3,$F3,$F3,$F3
dc.b 'O',$D2,$D3,$D4,$D5,$D6,$D2,$D2,$D4
dc.b $D2,$D2,$D2,$D3,$D4,$D3,$D3,$D3,$D3
deadu:
dc.b $01,$10,$01,$22,$00,$B5,$00,$B5
dc.b $00,$15,$00,$15,$00,$95,$00,$95
dc.b 'u',$F9,$FA,$FB, 'u',$FC,$F9,$F9,$FB
dc.b $F9,$F9,$F9,$FA,$FB,$FA,$FA,$FA,$FA
dc.b 'U',$D9,$DA,$DB, 'U',$DC,$D9,$D9,$DB
dc.b $D9,$D9,$D9,$DA,$DB,$DA,$DA,$DA,$DA
deadz:
dc.b $01,$10,$01,$22,$00,$B1,$00,$AC
dc.b $00,$19,$00,$19,$00,$99,$00,$99
dc.b 'y', 'y', $FD, 'y', 'y', $FF, 'y', 'y', 'y'

535

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

dc.b 'y', 'y','y',$FO,$FO,$FO,$FO,$FO,$FO

dc.b 'Y', 'Y' ,$00, 'Y', 'Y', 'Y', 'Y', 'Y', 'Y'
dc.b 'Y', 'Y', 'Y',$OO,$OO, $00, $00,$00,$00
deadspace:
dc.b $01,$04,$00,$AO
dc.b $20,$60,$B4,$5E,$7E,$A8,$60,$60,$5E
dc.b $60,$60, $60, $B4, $5E, $B4, $B4, $B4,$B4
strtab:
dc.b $01,$04,$02,$05
dc.b $09,$9B,$5A
strcdown:
dc.b $02,$04,$02,$06
dc.b $9B,$41,$9B, $54
strcup:
dc.b $02,$04,$02,$06
dc.b $9B,$42,$9B,$53
strcright:
dc.b $02,$04,$03,$06
dc.b $9B,$43,$9B,$20,$40
strcleft:
dc.b $02,$04,$03,$06
dc.b $9B,$44,$9B,$20,$41
strfl :
dc.b $03,$04,$04,$07
dc.b $9B,$30,$7E,$9B,$31,$30,$7E
strf2:
dc.b $03,$04,$04,$07
dc.b $9B,$31,$7E,$9B,$31,$31,$7E
strf3:
dc.b $03,$04,$04,$07
dc.b $9B,$32,$7E,$9B,$31,$32,$7E
strf4:
dc.b $03,$04,$04,$07
dc.b $9B,$33,$7E,$9B,$31,$33,$7E
strf5:
dc.b $03,$04,$04,$07
dc.b $9B, $34, $7E,$9B,$31,$34,$7E
strf6:
dc.b $03,$04,$04,$07
dc.b $9B,$35,$7E,$9B,$31,$35,$7E
strf7:
dc.b $03,$04,$04,$07
dc.b $9B,$36,$7E,$9B,$31,$36,$7E
strf8:
dc.b $03,$04,$04,$07
dc.b $9B,$37,$7E,$9B,$31,$37,$7E
strf9:
dc.b $03,$04,$04,$07
dc.b $9B,$38,$7E,$9B,$31,$38,$7E
strflO:
dc.b $03,$04,$04,$07
dc.b $9B,$39,$7E,$9B,$31,$39,$7E
strhelp:
dc.b $03,$02
dc.b $9B,$3F,$7E
name:dc.b "d",O

536

7.4 KEYMAPS

ABACUS

You can write your own keymap as a data block and assemble it. After
linking you have a keymap file which can be installed using the CLI
SetMap command. You define an Exec node in the assembler source
of the keymap, which is used later to link the keymap to the
keymap. resource structure. The KeyMap structure follows with
all of the tables. Remember to provide the names of the Exec nodes,
otherwise you cannot find the keymap after you have added it to the
system.
Here are two more structures. The flI'St comprises the entire structure of
the keymap fde, only you don't see the tables for the actual conversion
because these belong to the KeyMap structure. The second states the
structure of the keymap. resource. You can get this from the list
of all of the resources using the FindName function (execBase),
then search for a keymap of the same name with the same function.
struct

KeyMapNode

Oxoo 0
OxOE 14

struct Node kn Node;

struct KeyMap kn_KeyMap;

};

struct

KeyMapResource

OxOO 0
OxOE 14
OxIC 28

struct Node kr Node;

struct List kr=List;

};

When you want to change your keymap, use the disassembled keymap
listed above. Enter the listing, change the arrangement of the keys that
you want to change and save this keymap under an unusual name
(include an . asm extension if possible). For example, say you named
the file demo. a sm. You can assemble this file with:
as demo

And then link it

In demo

These calls are for the Aztec assembler. They should work on other
assemblers. Above all, no library is linked to the keymap. The
following CLI entries copies this keymap to a boot disk:
copy demo to Devs:Keymaps
SetMap demo

If you want to access this keymap, you must add it to the startup
sequence of your boot disk. or from the tool (application program) that
should use this keymap. This could l()()k like the following example:

537

7. BASIC SYSTEM STRUCTURES

ADVANCED SYSTEM PROGRAMMER'S GUIDE

struct KeyMapResource *FindName();

struct KeyMapResource *kmRes;
struct KeyMap *km = Null;
if (kmRes = FindName(&(SysBase>ResourceLi st) , "keymap. resource") )
km = FindName(&(kmRes->kr_List),ndemo");

This keymap (km) can be given either at the call of the

RawKeyConvert function or in the Stringlnfo structure of a
gadget (AI tKeyMap). This enables you to access the new keyboard
arrangement

If you don't want to reassemble and relink the keymap every time you
want to change a key arrangement, use programs that let you change
the keyboard arrangement during program execution. This is helpful if
you want to change the arrangement more than once. You can find
many such programs available commercially as well as in the public
domain and shareware world.
If you want to know the current arrangement of your keyboard, use the
KeyToy tool usually located in the Tools directory of your Extras
diskette (your Key Toy may be in another directory--check with your
dealer). The Amiga 2000 KeyToy is called KeyToy2000, while the
Amiga 500 KeyToy is called KeyToySOO. When you start this tool,
it displays an image of a keyboard on the screen, and shows which
characters you get when you press the corresponding key on the real
keyboard.
By clicking on the <Shifl>, <All> or <Ctrl> keys you can see what
function the corresponding key has. While this tool cannot display
strings that are modified through a dead key, it shows your letters in
italics. The actual dead keys are displayed in orange, and the accent
indicates that this dead key was created using other keys.
To conclude, the console device functions are ready to get a pointer to
the current keymap, set the current key map and convert a RAWKEY
number into an ASCII string. The last function (RawKeyConvert) is
the most interesting of all for the programs that wait for RAWKEY
input and must convert these themselves.

538

ABACUS

Appendix A:
AbortIO ...................................... 269
Activate<Jadget ............................. 309
ActivateWindow ........................... 302
AddAnimOb ................................. 432
AddBob ............ 432
AddConfigDev .............................. 476
AddDevice ......................... 265
AddDosN"ode ....... 476
AddFont. .................................... 427
AddFreeList ................................. 370
AddGadget ....... 310
AddGList. .................................... 313
AddHeal ................................... 251
AddIntServer ................................ 245
AddLibrary ................................... 261
AddMemList ...................... 274
AddPort....................................... 258
AddResource ................................ 269
AddSemaphore .............................. 273
AddTail .................................. 251
AddTask ................................... 253
AddTime ..................................... 493
AddVSprite ................................. 432
Alert ........................................... 241
AllocAbs ..................................... 247
Allocate ...................................... 246
AllocBoardMem ............................ 477
AllocConfigDev ........................... 477
AllocEntry .................................. 248
AllocExpansionMem ..................... 478
AllocMem ................................... 247
AllocPotBits ................................ 472
AllocRaster.................................. 378
AllocRemember............................ 335
AllocSignai ................................. 257
AllocTrap .................................... 258
AllocWBObject ............................ 365
AndRectRegion ............................ 420
AndRegionRegion ........................ 420
Animate ...................................... 433
AreaCircle ................................... 389
AJeaI)raw .................................... 390
AreaEllipse .................................. 390
AreaEnd ...................................... 390

ApPENDIX A: FUNCTION LIST

Function List
AreaMove ................................... .391
AskFont ......................................427
AskSoftStyle ................................427
AttemptLockLayerRom ..................420
AttemptSemaphore ........................272
AutoRequest. ............................... .321
AvailFonts ...................................446
AvailMem ....................................248

BeginRefresh ................................336
BeginUpdate ................................ .353
BehindLayer................................. .355
BltBitMap ................................... .401
BltBitMapRastPort ....................... .403
BltClear ...................................... .403
BltMaskBitMapRastPort ................ .404
BltPattern.....................................405
BltTemplate ................................. .406
BNDRYOFF ............................... .391
BuildS ysRequest. .......................... .322
BumpRevision ............................. .372
Cause ..........................................245
CBump ....................................... .411
CDInputlIand1er ........................... .489
CEND ........................................ .411
ChangeSprite ............................... .433
ChecldO ......................................268
ClearDMRequest .......................... .322
ClearEOL ..................................... 385
ClearMenuStrip ............................. 318
ClearPointer ................................ .332
ClearRectRegion ...........................421
ClearRegion' .................................421
ClearSa-een .................................. 385
ClipBlit. ......................................407
Close ..........................................278
CloseDevice ................................. 266
CloseFont ....................................428
CloseLibrary .................................262
CloseScreen ................................. .326
CloseWindow ............................... 302
CloseWorlcBench .......................... .326
CMove ........................................412

539

ApPENDIX A: FUNCTION LIST

CmpTime .................................... 493

ConfigBoard ................................. 478
ConfigChain ................................ 479
CopyMem ................................... 275
CopyMemQuick ........................... 275
CopySBitMap .............................. 421
CreateBehindLayer ......................... 348
CreateDir ..................................... 282
CreateProc ................................... 291
CreateUpfrontLayer ....................... 349
CurrentDir ................................... 282
CurrentTime ................................ 337
CWait. ........................................ 412
DateStamp ................................... 292
Deallocate .................................... 246
Debug ......................................... 242
Delay .......................................... 292
DeleteFile .................................... 283
DeleteLayer .................................. 361
DeviceProc .................................. 293
Disable ....................................... 242
DisownBlitter ............................... 407
Display Alert ................................ 323
DisplayBeep ................................. 327
DisposeFontContents .................... 447
DisposeLayerInfo .......................... 361
DisposeRegion ............................. 421
DoCollision ................................. 434
I>oI0 .......................................... 267
I>oubleClick ................................ 338
Draw ... :...................................... 385
I>rawBorder .................................. 332
DrawCircle .................................. 386
DrawEIlipse ................................. 386
DrawGList ................................... 435
DrawlInage .................................. 333
DupLOck ..................................... 287
Enable ........................................ 242
EndRefresh .................................. 336
EndRequest. ................................. 323
EndUpdate ................................... 355
Enqueue ...................................... 252
Examine ...................................... 283
Execute ....................................... 295
Exit ............................................ 293
ExNext ....................................... 283

540

ADVANCED SYSTEM PROGRAMMER'S GUIDE

FauenLayerInfo ............................ .3 51
FFP ........................................... .454
FFP ........................................... .461
FindConfigDev ............................ .479
FindNaIDe ....................................253
FindPort ......................................261
FindResiden t. ................................241
FindSemaphore .............................273
FindTask ......................................255
FindTooIType .............................. .372
Flood .......................................... 392
Forbid .........................................243
FreeBoardMem ............................. .480
FreeColorMap ............................... 397
FreeConfigDev ............................. .480
FreeCopList ................................ .413
FreeCprList. ................................ .413
FreeDiskObject ............... , ............ .368
FreeEntry .....................................249
FreeExpansionMem ...................... .481
FreeFreeList ................................ .371
FreeGBuffers ................................ .435
FreeMem .....................................248
FreePotBits ................................. .473
FreeRaster .................................... 378
FreeRemember .............................. 336
FreeSignal. ...................................257
FreeSprite ................................... .435
FreeSysRequest ............................ .324
FreeTrap ......................................258
FreeVPortCopLists ....................... .413
FreeWBObject. .............................. 365
GetCC .........................................276
GetColorMap ............................... .397
GetCurrentBinding ........................ .481
GetI>efPrefs ................................. 338
GetDiskObject ............................. .369
GetGBuffers ................................. .436
GetIcon ....................................... .367
GetMsg .......................................260
GetPacket. ....................................296
GetPrefs ...................................... .338
GetRGB4 .................................... .397
GetScreenData .............................. .327
GetSprite .................................... .436
GetWBObject. .............................. .365

ABACUS

IEEEDPAbs ................................. 462

IEEEDPAcos ............................... 467
IEEEDPAdd ................................. 462
IEEEDPAsin ............................. 468
IEEEDP Atan ................................ 468
IEEEDPCeil ................................ 463
IEEEDPCmp ............................... 463
IEEEDPCos ................................. 468
IEEEDPCosh ............................... 468
IEEEDPDiv ............................. 464
IEEEDPExp ............................... 468
IEEEDPFieee ............................. 468
IEEEDPFix ................................. 464
IEEEDPFloor ............................... 464
IEEEDPFlt. ................................. 464
IEEEDPLog ................................. 469
IEEEDPLogI0 ............................. 469
IEEEDPMul ................................ 465
IEEEDPNeg ................................. 465
IEEEDPPow ................................ 469
IEEEDPSin ................................. 470
IEEEDPSincos ............................. 469
IEEEDPSinh ................................ 469
IEEEDPSqrt. ................................ 470
IEEEDPSub ................................. 465
IEEEDPTan ................................. 470
IEEEDPTanh ............................... 470
IEEEDPTieee ............................... 471
IEEEDPTst.. ................................ 465
Info ............................................ 284
InitAnimate ................................ 437
InitArea ....................................... 392
InitBitMap ................................... 379
InitCode ...................................... 240
Ini tGels ....................................... 437
InitGMasks .................................. 438
lnitLayers .................................... 351
InitMasks .................................... 438
InitRastPort ................................. 379
InitRequester ................................ 324
InitResident ................................. 241
InitSemaphore .............................. 270
InitStruct ..................................... 240
InitTmpRas ................................. 393
InitView ...................................... 414
InitVPort ..................................... 414
Input .......................................... 288
Insert .......................................... 250
InstallClipRegion ......................... 356
IntuiTextLength ............................ 333
loErr ........................................... 288

ApPENDIX A: FuNCTION LIST

IsInteractive ..................................289

1teInAddress ................................. .318

LoadRGB4 .................................. .398
LoadSeg .......................................295
LoadView .................................... .414
Lock ...........................................289
LockIBase ................................... .342
LockLayer ................................... .356
LockLayerInfo .............................. .357
LockLayerRom ............................ .422
LockLayers .................................. .357
MakeDosNode .............................. .481
MakeFunctions .............................262
MakeLibrary .................................263
MakeScIren ................................. .327
Make VPort. ................................. .415
MatchTooIValue ........................... .373
Modify IDCMP ............................. .303
ModifyProp ................................. .314
MoveLayer ................................... 357
MoveLayerInFrontOf.. ................... .358
MoveScreen ..................................328
MoveSprite ................................. .439
MoveWindow ............................... 303
MrgCop ...................................... .415
New FontContents ..........................44 7
NewLayerInfoO ............................ .351
NewModifyProp ........................... .314
NewRegion ................................. .422
ObtainConfigBinding .................... .482
ObtainSemaphore .......................... 271
ObtainSemaphoreList .....................272
OffGadget ..................................... 315
OftMenu ..................................... .319
OldOpenLibrary .............................264
()n(jadget .................................... .315
()nMenu ...................................... 319
()pen ...........................................279
OpenDevice ..................................266
OpenDiskFont ..............................448
OpenFont .................................... .428
()penLibrary .................................264
()peoResource ...............................270
()penSCIren .................................. 328
()penWindow ............................... .304
OpenWorkBench ........................... .330
OrRectRegion ...............................422

541

ApPENDIX A: FUNCTION LIST

OrRegionRegion ........................... 423

Output ........................................ 290
OwnBli tter ................................... 407
ParentDir ..................................... 285
Permit ........................................ 243
PolyDraw .................................... 386
PrintlText.................................... 334
PutDiskObjeet.............................. 369
Pulleon ....................................... 368
PutMsg ....................................... 259
PutWBObject ............................... 366
QBlit. ......................................... 408
QBSBlit ...................................... 408
QueuePacket ................................ 297
RawDoFmt .................................. 275
RawKeyConvert ........................... 489
Read ........................................... 279
ReadExpansionByte ....................... 483
ReadExpansionRom ...................... 483
ReadPixel .................................... 387
RectFill ...................................... 394
RefreshGadgets ............................. 316
RefreshGList. ............................... 316
RefreshWindowFrame .................... 306
ReleaseConfigBinding .................... 484
ReleaseSemaphore ......................... 271
ReleaseSemaphoreList ................... 273
RemakeDisplay ............................ 337
RemBob ...................................... 439
RemConfigDev ............................ 484
RemDevice .................................. 266
RemFont. .................................... 429
RemHead ..................................... 252
RemIBob ..................................... 440
RemlntServer ............................... 245
RemLibrary ................................. 263
Remove ...................................... 252
RemoveGadget ............................. 317
RemoveGList ............................... 317
RemPort ..................................... 259
RemResource ............................... 270
RemSemaphore ............................ 274
RemTail. ............. ~ ........................ 252
Rem Task ..................... _ .............. 255
Rem YSprite ................................. 440
Rename ....................................... 285
ReplyMsg ................................... 260
ReportMouse ............................... 343
542

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Request........................................325
RethinkDisplay ............................. 337
ScreenToBack .............................. .330
ScreenToFront ............................. .330
SerollLayer...................................358
SerollRaster................................. .388
SerollVPort ................................. .416
Seek ............................................280
SendIO ........................................268
SetAfPt ...................................... .394
SetAPen ......................................380
SetBPen ...................................... .380
SetCollision .................................440
SetComment ................................285
SetCurrentBinding ........................ .484
SetDMRequest ............................. .325
SetI>rMd ..................................... .381
SetDrPt ....................................... 381
SetExeept.....................................256
SetFont ...................................... .429
SetFunetion ..................................264
SetIntYector .................................244
SetMenuStrip .............................. .319
SetOPen ..................................... .395
SetPointer .................................... 334
SetPrefs ....................................... 343
SetProtection ................................286
SetRast....................................... .382
SetRGB4 .................................... .399
SetRGB4CM ............................... .399
SetSignal .....................................256
SetSoftS tyle ................................ .430
SetSR ......................................... 243
SetTaskPri .................................. .255
SetWindowTitles .......................... .307
SetWrMsk ................................... .382
ShowTitle ................................... .331
Signal .........................................257
SizeLayer .................................... .359
SizeWindow ................................ .307
SortGList. ....................................441
SPAbs ........................................ .451
SPAeos .......................................455
SPAdd ........................................ .451
SPAsin ....................................... .456
SPAtan ....................................... .456
SPCmp ...................................... .452
SPCos ........................................ .456
SPCosh ...................................... .457
SPDiv ........................................ .452

ABACUS

SPExp ........................................ 451

SPFieee ...................................... 451
SPFix ......................................... 452
SPFlt ......................................... 453
SPLog ........................................ 458
SPLogI0..................................... 458
SPMul. ....................................... 453
SPNeg ........................................ 453
SPPow ....................................... 458
SPSin ......................................... 459
SPSincos .................................... 459
SPSinh ....................................... 459
SPSqrt ........................................ 460
SPSub ........................................ 454
SPTan ........................................ 460
SPTanh ....................................... 460
SPTieee ...................................... 461
SPTst ......................................... 454
SubTime ..................................... 494
SumKickData ............................... 214
SumLibrary ................................. 265
SuperState ................................... 243
SwapBitsRastPortClipRect ............. 359
SyncSBitMap ............................... 423

ApPENDIX A: FuNCTION LIST

WaitlOF .................................... .411

WBenchToBack .............................331
WBenchToFront ............................331
WbichLayer .................................. 360
WindowLimits ..............................308
WindowToBack ............................. 308
WindowToFront ........................... .309
Write ...........................................281
WriteExpansionByte .......................485
WritePixel. ...................................389
WritePotgo .................................. .413
XorRectRegion ............................ .424
XorRegionRegion ......................... .424

Text ........................................... 381

TextLength .................................. 388
ThinLayerInfo .............................. 362
Type(>fMem ................................ 276
UCopperListInit ........................... 416
UnLoadSeg .................................. 296
UnLock ....................................... 290
UnlockIBase ................................. 343
UnlockLayer ................................ 362
UnloclcLayerInfo ........................... 363
UnlockLayerRom .......................... 424
UnlockLayers ............................... 362
UpfrontLayer ................................ 360
UserS tate ..................................... 244
VBeamPos ................................... 416
ViewAddress ................................ 344
ViewPortAddress ........................... 344
Wait. .......................................... 256
WaitBlit. ..................................... 409
WaitBOVP .................................. 417
WaitForChar ................................ 293
WaitIO ........................................ 269
WaitPort ..................................... 260

543

ApPENDIX B: BIBLIOGRAPHY

Appendix B:

ADVANCED SYSTEM PROGRAMMER'S GUIDE

Bibliography

ROM Kernel Reference Manual: Libraries and Devices

Commodore-Amiga, Inc.
Addison Wesley Publish~ng Company, Inc.
Source for: Library functions version 1.1
Device functions 1.1
ROM Kernel Reference Manual: Exec
Commodore-Amiga, Inc.
Addison Wesley Publishing Company, Inc.
Source for: Library functions version 1.1
Structure documentation 1.1
Amiga Intuition Reference Manual
Commodore-Amiga, Inc.
Addison Wesley Publishing Company, Inc.
Source for: Library functions, Version 1.1
Structure documentation, Version 1.1
The AmigaDOS Manual (2nd Edition)
Commodore Amiga, Inc.
The Bantam Amiga Library
Source for: Library functions, Version 1.2
Structure documentation, Version 1.2
Amiga System Programmer's Guide
Abacus
Source for: Library functions Version 1.2
Structure documentation, Version 1.2
Amiga Graphics Inside and Out
Abacus
Source for: Library functions Version 1.2
Structure documentation, Version 1.2
Commodore Amiga Developers Conference Documentation
Commodore-Amiga, Inc.
Source for: Operating system information, Version 1.3

544

INDEX

ABACUS

Index
8SVXchunk
8SVX IFF fonnat

233
233

AbortIO
ActivateGadget
ActivateWindow
Actual
actual character data
AddAnimOb
hkIBob
AddConfigDev
AddDevice
AddDa;Node
AddFont
AddFreeList
AddGadget
AddGList
MlHeal
AddIntServer
Additions lines
AddLibrary
AddMemList
AddPoct:
AddResource
AddSemaphore
AddTail

269
309
302
139
518
432
432
476
265
476
427
370
310
313
251
245
7
261
274
258
269
273
251
253
493
186
432
241
247
246
477
477
248
478
150
247
472

Addfask

Addfime
Addfime()
AddVSprite
Alert
AllocAbs
Allocate
AllocBoardMem
AllocConfigDev
AllocEntry
AllocExpansionMem
AllocKey
AllocMem
AllocPotBits

AllocRaster
AllocRemember
AllocSignal
AllocTrap
AllocWBObject
AndRectRegion
AndRegiooRegion
Animate
ANNO chunk
AreaCircle
ArelDraw
AreaEllipse
AreaEnd
AreaMove
ArgC (Argument Counter)
argument template
ArgV (Argument Vector)
AskFont
AskSoftStyle
Assembly language
Assign command
ATAKchunk
atoiO function
AttemptLockLayerRom
AttemptSemaphore
Audio channel allocation
audio device
AUTHchunk
AutoRequest
AvaiIFonts
AvailMem
Aztec C compiler
base address register

basic settings
basic structures
beam synchronized
BeginlO
BeginRefresh
BeginUpdate

378
335
257
258
365
420
420
433
231,234
389
390
390
390
391
22
23
22
427
427
12
14
234
34
420
272
146, 148
145
230,234
321
446
248
453
12
495
495
412
46
336
353

545

INDEX

BehindLayer
355
block movement operations
141
BltBitMap
401
BltBitMapRastPort
403
BltClear
403
BltMaskBitMapRastPort
404
BltPattem
405
BltTemplate
406
BMHD
216
BMHDreader
227
BNDRYOFF
391
BODY chunk
220, 222
Buffer parameter
139
BuildSysRequest
322
BumpRevision
372
Cdirectory
15
C handler routine
100
CAMG
221
Cause
245
CBump
411
CCRTchunk
219
CDInputHandler
489
CEND
411
ChangeSprite
433
channel allocation map
146
ChecklO
268
CHRS chunk
229
Chunks
216, 230,234
CIA timer
179
ClearDMRequest
322
OearEOL
385
ClearMenuStrip
318
ClearPointer
332
ClearRectRegion
421
ClearRegion
421
OearScreen
385
CLI commands
20
ClipBlit
407
clipboard device
141
clipping rectangles
347
Close
46
Close
278
Close_AlIO
9, 10
CloseDevice
266
CloseDeviceQ
44
CloseFont
428

546

ADVANCED SYSTEM PROGRAMMER'S GUIDE

45,226
OoseltO
262
OoseLibrary
326
OoseScreen
302
OoseWindow
326
CloseWorltBench
218
CMAP
228
CMAPchunk
CMD_READ
49,58,166,191
CMD_RESET
49
49, 58, 192
CMD_WRITE
412
CMove
493
CmpTime
186
CmpTimeO
228
Color cycling
218
color register
218
colormap
511
Command
commercial software developers
215
communication channels
8
Complicated strings
530
compression
218
ConfigBoard
478
479
ConfigChain
491
Console library
console device
111
113
control strings
85
controller types
ConUnit structure
138
cookie cut
409
CopyMem
275
275
CopyMemQuick
421
CopySBitMap
348
CreateBehindLayer
282
CreateDir
291
CreateProc
CreateUpfrontLayer
349
CRLF
511
CRNGchunk
219
CurrentDir
282
CurrentTime
337
CustomPrinter
498
412
CWait
Cycles
154

INDEX

ABACUS

data pointer
48
222
data report
DateS tamp
292
dead keys
530
Deallocate
246
242
Debug
decimal string
119
Delay
292
DeleteFile
283
DeleteLayer
361
Density
500
221
depth
234
dest
DestCols
73
DestRows
73
device
37
device block
191
device command
47
device request structures
39
device specific support routines
49
DeviceData
506
293
DeviceProc
16
devs directa:y
dfh_FileID
519
dfh_Name
519
dth_Node
519
dfh_Revision
519
dfh_Segment
519
dfh_TF
519
direction
220
242
Disable
203
disk editor
DiskFont library
449
407
DisownBlitter
227
Display screen size
DisplayAlert
323
DisplayBeep
327
447
DisposeFontContents
361
DisposeLayerInfo
421
DisposeRegion
DoCollision
434
267
DolO
47
DolOO
13,277
DOS library
double precision (IEEE) numbers
453
DoubleOick
338

DoubleOick structure
Draw
DrawBooJer
DrawCircle
DrawEllipse
DrawGList
DrawImage
DupLock
duration

497
385
332
386
386
435
333
287
234

emergency exit
Enable
EndRefresh
EndRequest
Enqueue
Error handling
enorcheck
EID_READ command
EID_WRI'IE
Examine
Exec functions
Exec support function
exec library
Execute
Execute command
Exit
ExNext
Expansion library
Expunge
extended commands
Extfunc

45
242
336
323
355
252
201
8
191
192
283
37
38
236
295
15
293
283
477
46
49
46

FattenLayerInfo
fc_FileName
FC_FLAGS
fc_Style
fc_YSize
fch_FileID
fch_NumEntries
FFP
FFP
File menu
File menu title
File standards
files
FindConfigDev

351
516
516
516
516
515
515
454
461
17
17
215
25
479

EndUtxJate

547

INDEX

FindName
FindPon
FindResident
FindSemaphore
FindTask
FindToolType
fIre button
Flags
floating-point numeric formats
Flood
FONS chunk
FontContentsHeader
Forbid
forbidden register
Forgotten chunks
formatting
FPF_DISKFONT (2)
FPF_PROPROTIONAL (32)
FPF_REMOVED (128)
FPF_ROMFONT (1)
FreeBoon1Mem
FreeColorMap
FreeConfigDev
FreeCopList
FreeCprList
FreeDiskObject
FreeEntry
FreeExpansionMem
FreeFreeList
FreeGBuffers
FreeMem
FreePotBits
FreeRaster
FreeRemember
FreeSignal
FreeSprite
FreeSysRequest
FreeTrap
FreeVPortCopLists
FreeWBObject
freq parameter
FSF_UNDERLINED (1)
FSF_BOLD (2)
FSF_ITALIC (4)
FTXTformat
Function headers

548

ADVANCED SYSTEM PROGRAMMER'S GUIDE

253
261
241
273
255
372
89
30
453
392
229
515
243
12
228
196
517
517
517
517
480
397
480
413
413

gamepondevice
85
OCR (Group Code Recording)
194
generic device support routines
49
GetCC
276
GetColorMap
397
481
GetCurrentBinding
GetDefPrefs
338
GetDiskObject
369
GetGBuffers
436
GetIeon
367
GetMsg
260
GetPacket
296
GetPrefs
338
GetRGB4
397
327
GetScreenData
GetSprite
436
GetWBObject
365
GPCT_ABSJOYSTICK
89
GPCT_MOUSE
88
GPCT_REUOYSTICK
89
GRAB chunk
220
Graphic printout settings
499
Graphics library
299, 376
greeting entry
5

368

hardcopy line
Irakr
Hikeymap

507
216
124

icon library
IEEEDPAbs
IEEEDPAcos
IEEEDPAdd
IEEEDPAsin
IEEEDPAtan
IEEEDPCeil
IEEEDPCmp
IEEEDPCos
IEEEDPCosh
IEEEDPDiv
IEEEDPExp
IEEEDPFieee
IEEEDPFix
IEEEDPFloor
IEEEDPFlt
IEEEDPLog
IEEEDPLoglO

364
462
467
462
468
468
463
463
468
468
464
468
468
464
464
464
469
469

249
481
371
435
248
473
378
336
257
435
324
258
413
365
172
516
516
516
229
6

ABACUS
IEEEDPMul
IEEEDPNeg
IEEEDPPow
IEEEDPSin
IEEEDPSincos
IEEEDPSinh
IEEEDPSqrt
IEEEDPSub
IEEEDPTan
IEEEDPTanh
IEEEDPTieee
IEEEDPTst
IFF (Interchange File Format)
ll...BMFORM
Info
InitAnimate
InitArea
InitBitMap
InitCode
InitGels
InitGMasks
InitLayers
InitMasks
InitRastPort
InitRequester
InitResident
InitSemaphore
InitStruct
InitTmpRas
InitView
InitVPort
Input
input device
input handler
input parameters
Input_Handler
INS 1
INSI chunk
Insert
InstallClipRegion
InterLeaved BitMap
interrupt
interrupt structure
IntuiTextLength
Intuition
Intuition library

INDEX

465
465
469
470
469
469
470
465
470
470
471
465
215
227
284
437
392
379
240
437
438
351
438
379
324
241
270
240
393
414
414
288
93
94
7
100
231
231
250
356
216
199
199
333
17
299

IOAudio SbUcture
IoErr
IOF_QUICK flag
IOReplyPort
IORequest Structure
iouCCount variable
IRevchunk
IsInteractive
ItemA~

39
288
48
39
37
190
230
289
318
528
528
18
107
81

KC_VANILLA
KCF_STRING
Key response
key repeat speed
keyboard device
keyboard shortcuts
keymap
keymap structure
KeyMapTypes
Keypresses
keyRptSpeed field
Keys element
Keys parameter
KeyToy
Keywords
Kickstart

527
124
527, 528
90
497
90
109
538
29
6

Ldirectory
label buffer
Lattice C compiler
Layexs
layers library
Length
library version
library version number
libs directory
Line
LineSpace
Lokeymap
LoadRGB4
LoadSeg
LoadView
Lock
LockIBase
LockLayer
LockLayerInfo
LockLayerRom

15
191
453,513
347
299, 347
139
6
6
16
511
511
124
398
295
414
289
342
356
357
422

17

549

ADVANCED SYSTEM PROGRAMMER'S GUIDE

INDEX

LockLayers
locks
loop
machine language routine
macro recorder

MainO
major version
MakeDosNode
MakeFunctions
MakeLibrary
MakeScreen
MakeVPort
Management systems
Masking
MatchTooIValue
math library
MathleeeDoubBas library
MathleeeDoubTrans library
MathTrans library
Maxima
menu line
menu titles
Menus
Message ports
MFM
minor version
mode parameter
ModifyIDCMP
ModifyProp
Mouse pointer
mouse port
mouse speed
mouth
Mouth_ExpungeO
Mouth_initO
Mouth_RoutineO
MoveLayer
MoveLayerInFrontOf
MoveScreen
MoveSprite
MoveWindow
MrgCop
multitasking operating system
NAME chunk
narrata device

550

357
25
21
100
101
11,20
5
481
262
263
327
415
8
217
373
453
464
469
458
75
17
17
17
40
194
5
171
303
314
497
109
108
169
172
172
172
357
358
328
439
303
415
8
230,234
168

NewFontContents
NewLayednfo()
NewModifyProp
NewRegion
Notepad flags
nPlanes

447
351
314
422
35
217

ObtainConfigBinding
ObtainSemaphore
ObtainSemaphoreList

482
271
272
315
319
264
315
319
46
279
9
266
37
448
428
264
37
270
328
304
330
5
30
422
423
290
511
227
407

0ftGadget

OtlMenu
OldOpenLibrary
OnGadget

OnMenu
Open
Open
Open_AlIO
OpenDevice
0penDevice()

OpenDiskFont
OpenFont
OpenLibrary
OpenLibraryO
OpeoResource
OpenScreen
OpenWindow
OpenWorlcBench
operating system version
Or charocter
OrRectRegion
OrRegiooRegioo
Output
OutPutBuffer
OverScan
OwnBlitter
Pal
Padl
pageHeight
pageWidth
PaperLength
PaperSize
Papetrype
parallel device
PARB_SHARED flag (32)
ParentDir

220
218,219
218
218
499
499
499
50
50
285

INDEX

ABACUS

partial functions
512
508
IXCPBothReady
507
IXCPrintBuf
507
IXCPWrite
pe(C8BitChars
513
508
pe(COose
pe<CColorClass
509
pe(CCommands
510
pecCCommandTable
510
ped,- DoSpeeial
511
ped_Expunge
508
ped_Init
506, 508
ped_MaxColwnns
509
ped_MaxXDots
509
ped_MaxYDots
510
IJe'CNwnCharStes
509
ped_NwnRows
509
508
ped-Open
ped_PrinterClass
509
ped_Reodel'
511
ped_TimeoutSecs
513
ped_XDotsInch
510
ped_YDotsInch
510
period calculation
152
Permit
243
phoneme codes
168
pitch parameter
171
planeMask
221
planePick
221
Pointennatrix field
497
PolyDraw
386
Potgo library
474
PRD_DUMPRPORT command
73
precedence nwnber
147
Preferences program
90
Preferences sttucture
496
PrintAspect
499
Printer settings
498
printer commands
72
printer device
68
printer driver
505
printer escape sequences
69
PrinterData
506
PrinterExtendedData structure
506
PrinterSegment
506
PrintFlags
499

PrintImage
PrintIText
PrintLeftmargin
PrintMaxHeight
PrintMaxWidth
PrintPitch
PrintQuality
PrintRightMargin
PrintShade
PrintSpacing
PrintThreshold
PrintXOffset
Program header
Project
PutDiskObject
PutIcon
PutMsg
PutWBObject

499
334
499
500
500
499
499
499
499
499
499
500
4
30
369
368
259
366

QBlit
QBSBlit
QueuePacket
Quotation marks

408
408
297
22

Rate
Raw data
RawDoFmt
RAWKEY number
RawKeyConvert
Real
Read ToolTypes
ReadEvent
ReadExpansionByte
ReadExpansionRom
Readlt()
ReadPixel
RectFill
RefreshGadgets
RefreshGList
RefreshWindowFrame
register
ReleaseConfigBinding
ReleaseSemaphore
ReleaseSemaphoreList
RemakeDisplay
RemBob
RemConfigDev

171,219
194
275
525
489
279
26
89
483
483
226
387
394
316
316
306
12,231
484
271
273
337
439
484

551

INDEX

ADVANCED SYSTEM PROGRAMMER'S GUIDE

RemDevice
RemFont
RernHead
Remffiob
RemIntServer
RernLibrary
Remove
RemoveGadget
RemoveGList
RemPort
RemResource
RemSemaphore
RemTail
RemTask
RemVSprite
Rename
Render
repeat threshold
repetition threshold
ReplyMsg
ReportMouse
Request
Requesters
reserved keyboard codes
reset routines
RethinkDisplay
return parameters
RLSE chunk
Rom Boot library

266
429
252
440
245
263
252
317
317
259
270
274
252
255
440
285
511
108
497
260
343
325
17
140
83
337
7
234
490

S directory
ScreenToBack
ScreenToFront
ScrollLayer
ScrollRaster
ScrollVPort
sector
SectorBuffer
Seek
SendIO
SendIOO
separator characters
Serial data transfer
Serial device errors
serial device
serial interfaces

15
330
330
358
388
416
190
191
280
268
47
21
500
64
57
60

552

SerParShk
SerRWBit
SerStopBuf
SetAfPt
SetAPen
SetBPen
SetCollision
SetComment
SetCurrentBinding
SetDMRequest
SetDrMd
SetDrPt
SetExcept
SetFont
SetFunction
SetIntVector
SetMenuStrip
SetOPen
SetPointer
SetPrefs
SetPrefsO
SetProtection
SetRast
SetRGB4
SetRGB4CM
SetSignal
SetS oftS tyle
SetSR
SetTaskPri
SetWindowTitles
SetWrMsk
sex parameter
SHDR chunk
ShowTitle
SID's SEvents
Signal
single precision (FFP) numbers
SizeLayer
SizeWindow
SMUS music format
SortGList
SPAbs
SPAcos
SPAdd
SPAsin
SPAtan

500
500
500
394
380
380
440
285
484
325
381
381
256
429
264
244
319
395
334
343
502
286
382
399
399
256
430
243
255
307
382
171
230
331
231
257
453
359
307
230
441
451
455
451
456
456

ABACUS

SPCmp
452
456
SPCos
SPCosh
457
SPDiv
452
SPECIAL_lRUSTME flag
80
SPExp
457
SPFieee
457
SPFix
452
SPFIt
453
SPLog
458
SPLoglO
458
SPMul
453
SPNeg
453
SPPow
458
Sprites
221
SPRT
221
SPSin
459
SPSincos
459
SPSinh
459
SPSqrt
460
SPSub
454
SPTan
460
SPTanh
460
SPTieee
461
SPTst
454
stack pointer (SP)
12
Standard device blocks
39
startup-sequence
15
status
197
Stealing
147
string descriptor
134,529
string packet
203
SubTime
494
186
SubTimeO
SumKickData
274
SumLibrary
265
243
SuperState
supervisor stack pointer (SSP)
12
SwapBitsRastPortClipRect
359
511
SWITCH construct
423
SyncSBitMap
SYS
16
14
system directories
system libraries
9
system structures
495
system support
14

INDEX

Tdirectory
tempo
terminators
Text
TextLength
tCAccessors
tCBaseline
tCBoldSmear
tCCharKem
tCCharSpace
tf_Flags
tCHiChar
tCLoChar
tf_Module
tf_Style
tCYSize
ThinLayerlnfo
time intervals
Timeout
Timeout parameter
Timer library
timer device
timeval
Tool
ToolTypes
trackdisk device
tracks
1RAKchunk
Transfer protocols
Transferring data
translate() routine
Translator library
TYPE
TypeOfMem
UCopperListInit
undefined keyboard codes
Unit parameter
UnLoadSeg
UnLock
UnlockIBase
UnlockLayer
UnlockLayerlnfo
UnlockLayerRom
UnlockLayers
UpfrontLayer

16
230
52
387
388
520
520
520
521
520
520
520,521
520,521
520
520
520
362
497
90

109
495
179
181
30
34
189
194
231
60
51
168
476
29,231
276
416
140
85, 179, 190
296
290
343
362
363
424
362
360

553

INDEX

user interaction
user stack pointer (USP)
User_Routine
UserState

VBeamPos
Version
version number
vertical blank
YHDRchunk
ViewAddress
ViewMode
ViewPortAddress
Wait
WaitBlit
WaitBOVP
WaitForChar
WaitIO
WaitPort
WaitTOF
WaveForm
WaveLength
WBtn:hToBock
WBenchToFront
WhichLayer
WindowLimits
WindowToBack
WindowToFront
wordperlod
Workbench
Workbench messages
Write
WriteExpansionByte
WritePixel
WritePotgo

ADVANCED SYSTEM PROGRAMMER'S GUIDE

19
12
100
244

416
8
5
179
234
344
221,228
344

256
409
417
293
269
260
417
154
154
331
331
360
308
308
309
152
6,498
34
281
485
389
473

xAspect
XDelta
XorRectRegion
XorRegionRegion

218
90, 109
424
424

yAspect
YDelta

218
90, 109

554

Companion Diskette

AMIGA
Advanced System
Programming
CompanIon dIskette

For your convenience, the program listings contained in this book are
available on an Amiga formatted floppy disk. You should order the
diskette if you want to use the programs, but don't want to type them
in from the listings in the book.
All programs on the diskette have been fully tested. You can change the
programs for your particular needs. The diskette is available for $14.95
plus $2.00 ($5.00 foreign) for postage and handling.
When ordering, please give your name and shipping address. Enclose a
check, money order or credit card information. Mail your order to:
Abacus Software
5370 52nd Street SE
Grand Rapids, MI49512
For fast service, call 616/698-0330
Credit Card orders only 1-800-451-4319

Products for Amiga Computers

Books for the AMIGA

liHiHIHll1

Amiga for Beginners

Amlga For Beglnners- the first volume in our Amiga series,
introduces you to Intuition (Amiga's graphic interface), the mouse,
windows, the CLI, and Amiga BASIC and explains every practical aspect
of the Amiga in plain English.The glossary, "first-aid" appendix, icon
appendix and technical appendix are invaluable to the beginner.
Topics include:
Unpacking and connecting the Amiga components
Starting up your Amiga
Customizing the Workbench
Exploring the Extras Disk
Taking your first steps in the AmigaBASIC programming
language
AmlgaDOS functions
Using the CLI to perform 'housekeeping' chores
First Aid, Keyword, Technical appendixes
Complete set-up instructions
Backing up important diskettes
Setting Preferences
Creating your own icons
Volume 1 Suggested retail price

No Optional Disk
Available

$16.95 ISBN 1-55755-021-2

AmigaBASIC: Inside & Out

AmlgaBASIC- Inside and Out- THE definitive step-by-step
guide to programming the Amiga in BASIC. Every AmigaBASIC
command is fully described and detailed. Topics include charts,
windows, pull down menus, files, mouse and speech commands.
Features:

Loaded with real working programs

Video titling for high quality object animation
Windows
Pull-down menus
Moused commands
Statistics
Sequential and random files
Exciting graphics demonstrations
Powerful database
Charting application for creating detailed pie charts and bar graphs
Speech utility for remarkable human voice syntheses demonstrations
Synthesizer program to create custom sound effects and music.

Volume 2 Suggested retail price

IOptlonal Diskette

$14.95

$24.95 ISBN 0-916439-87-9

1612

Save Time and Money!-Optional program disks are available for all our Amiga reference
books (except Amiga for Beginners and AmigasDOS Quick Reference) . Programs listed in
the book are on each respective disk and saves countless hours of typing! $14.95

Books for the AMIGA

Amiga

3-~

IliiiliHIHI

Graphics Programming in BASIC

Shows you how to use the powerful graphics capabilities of the

Amiga. Details the techniques and algorithm for writing threedimensional graphics programs: ray tracing in all resolutions, light
sources and shading, saving graphics in IFF format and more.
Topics include:
Basics of ray tracing
Using an object editor to enter three-dimensional objects
Material editor for setting up materials
Automatic computation in different resolutions
Using any Amiga resolution (low-res, high-res, interface,
HAM)
Different light sources and any active pixel
Save graphics in IFF format for later recall Into any IFF
compatible drawing program
Mathematical basics for the non-mathematician

Volume 3 Suggested retail prl~

IOptlonal Diskette

$14.95

$19.95 ISBN 1-55755-044-1

116n

Amiga Machine Language

Amlga Machine Language introduces you to 68000 machine
language programming presented in clear, easy to understand terms. If
you're a beginner, the introduction eases you into programming right
away. " you're an advance programmer, you'll discover the hidden
powers Of your Amiga. Le&rn how to access the hardware registers, use
the Amiga libraries, create gadgets, work with Intuition and much more.

68000 address modes and instruction set

Accessing RAM, operating system and multitasking
capabilities
Details the powerful Amiga libraries for using AmigaDOS
Speech and sound facilities from machine language
Simple number base conversions
Text Input and output
Checking for special keys
Opening CON: RAW: SER: and PRT: devices
New directory program that doesn't access the CLI
Menu programming explained
Complete Intuition demonstration program including
Proportional, Boolean and String gadgets.
Volume 4 Suggestea retail price $19.95 ISR.N 1-55755-025-5

IOptional Diskette

$14.95

11662

Save Time and Moneyl-Optional program disks are available for all our Amiga reference
books (except Amiga for Beginners and AmigasDOS Quick Reference). Programs listed in
the book are on each respective disk and saves collntless hours of typing! $14.95

Books for the AMIGA

Amiga Tricks & Tips
Amlga Tricks & Tips follows our tradition of other Tricks and Tips
books for CBM users. Presents dozens of tips on accessing libraries
from BASIC, custom character sets, AmigaDOS, sound, important
68000 memory locations, and much more!
Topics include:

Diverse and useful programming techniques

Displaying 64 colors on screen simultaneously
Accessing libraries from BASIC
Creating custom character sets
Using Amiga DOS and graphics
Dozens of tips on windows
Programming aids
Covers important 68000 memory locations

Volume 5 Suggested retail price

IOptional Diskette

$14.95

$19.95 ISBN 0-916439-88-7

#617

Amiga System Programmer's Guide

Amlga System Programmer's Guide is a comprehensive guide to
what goes on inside the Amiga in a single volume. Explains in detail the
Amiga chips (68000, CIA, Agnus, Denise, Paula) and how to access
them. All the Amiga's powerful interfaces and features are explained
and documented in a clear precise manner.
Topics include:
EXEC Structure
Multitasking functions
110 management through devices and 110 request
Interrupts and resource management
RESET and its operation
DOS libraries
Disk Management
Detailed information about the eLi and its commands

Volume 6 Suggested retail price

IOptional Diskette

$14.95

$34.95 ISBN 1-55755-034-4

#607

Save Time and Money!-Optional program disks are available for all our Amiga reference
books (except Amiga for Beginners and AmigasDOS Quick Reference). Programs listed in
the book are on each respective disk and saves countless hours of typing! $14.95

Books for the AMIGA

Advanced System Programmer's Guide
A follow up volume to the internals of the Amiga covering even more topics
including Kickstart and covering Wor1<bench 1.3. Presents the conventions for
systems programming. Very thorough explainations of accessing the facilities
provided by the Libraries, input and output using the Devices, using and
changindg the preferences. Describes the various standard IFF formatsgraphics, text music.
Topics include:
Using the new AmigaD
1.3 and the
Do

~~a\\a\)\e 89

t-'

...

t1\bet

NO"~M4rH:::~=

:::::~::;:::.::

""Md:NewCon, PIPE and using the Mount command

Volume 7 Suggested retail price

IOptional Diskette

$14.95

$34.95 ISBN 1-55755-047-6

1697

AmigaDOS: Inside & Out

AmlgaDOS: Inside & Out-covers the insides of AmigaDOS from
the internal design up to practical applications . Includes detailed
reference section, tasks and handling, DOS editors ED and EDIT, how
to create and use batch files, multitasking. and much more.
Topics include:

68000 microprocessor architecture

AmigaDOS - Tasks and handling
Detailed explanations of CLI commands and their functions
DOS editors ED and EDIT .
Operating notes about the CLI
(Wildcards, shortening input and output)
Amiga devices and how the eLi uses them
Batch files - what they are and how to write them
Changing the startup sequence
AmigaDOS and multitasking
Writing your own CLI commands
Reference to the CLI, ED and EDIT commands
Resetting priorities - the TaskPri command
Protecting your Amiga from unauthorized use

Volume 8 Suggested retail price

IOptlonal Diskette

$14.95

$19.95 ISBN 1-55755-041-7

1667

Save Time and Money!-Optional program disks are available for all our Amiga reference
books (except Amiga for Beginners and AmigasDOS Quick Reference). Programs listed in
the book are on each respective disk and saves countless hours of typing! $14.95

Books for the AMIGA

Amiga Disk Drives: Inside & Out
Amlga Disk Drives: Inside & Out is the most in-depth reference
available covering the Amiga's disk drives. Learn how to speed up data
transfer, how copy protection works, computer viruses, Workbench
and the CLI DOS functions, loading, saving sequential, relative file
organization, more.
Topics Include:

Floppy disk operation from the Workbench and CLI

BASIC: Loading, saving, sequential and relative files DOS
functions
File managemen!: Block types, boot blocks, checksums, file
headers, hashmarks and protection methods
Viruses: Protecting your boot block
Trackdisk.device: Commands, structures
Trackdisk-task: Function and design
Diskette access with DOS
MFM, GCR, Track design, blockheader, data blocks,
checksums, coding and decoding data, hardware registers,
SYNC, and interrupts
Volume 9 Suggested retail price $29.95 ISBN 155755-042-5

IOptlonal Diskette

$14.95

1672

Amiga C for Beginners

An introduction to learning the popular C language. Explains the
language elements using examples specifically geared to the Amiga.
Describes C library routines, how the compiler works and more.
Topics include:
Particulars of C
How a compiler works
Writing your first program
The scope of the language (loops, conditions, functions,
structures)
Special features of C
Important routines in the C libraries
Input/Output
Tricks and Tips for finding errors
Introduction to direct programming of the operating system
(windows, screens, direct text output, DOS functions)
Using the LATIICE and AZTEC C compilers
Volume 10 Suggested retail price $19.95 ISBN 155755-045X

IOptlonal Diskette

$14.95

1682

Save Time and Money!-Optional program disks are available for all our Amiga reference
books (except Amiga for Beginners and AmigasDOS Quick Reference). Programs listed in
the book are on each respective disk and saves countless hours of typing! $14.95

Books for the AMIGA

Amiga C for Advanced Programmers
Amlga C for Advanced Programmers- contains a wealth of
information from the pros: how compilers, assemblers and linkers work,
designing and programming user friendly interfaces using Intuition,
managing large programming projects, using jump tables and dynamic
arrays, coming assembly language and C codes, and more. Includes
complete source code for text editor.
Topics include:
USing INCLUDE, DEFINE and CASTS
Debugging and optimizing assembler sources
All about Intuition programming (windows, screens, pulldown
menus, requesters, gadgets)
Programming the console devices
A professional editor's view of problems with developing
larger programs
Using MAKE correctly
Debugging C programs with different utilities
Folding (formaHing text lines and functions for readability)
Volume 11 Suggested retail price $24.95 ISBN 1-55755-046-8
IOptional DlskeHe

$14.95

1687

More Tricks & Tips for the Am iga

Offers you even more hints, tips, suggestions, software tools and shortcuts to
help make your Amiga sessions shorter, more efficient and more fun!.
Whether you program in AmigaBASIC or C, More Amiga Tricks & Tips is for
you. More Amiga Tricks & Tips will help sharpen your programming skills by
learning, until now, little known facts about your Amiga.
Topics include:
Using the new AmigaDOS 1.3, WorkBench 1.3 and Preferences
1.3 and the Extras 1.3 disk
Dozens of hints and tips for streamlining and improving your
programming skills with the CLI and AmigaBASIC
How to find a few of the "secret messages" built into your
Amiga's operating system
More information on HAM, halfbrite, and overscan Amiga
video modes
Accessing assembler and C programs from AmigaBASIC
Disabling FASTRAM and disk drives, Hardware hacking
New devices explained : NewCon, PIPE and using the Mount command
Volume 12 Suggested retail price $16.95 ISBN 1-55755-051-4
IOptional DlskeHe

$14.95

1620

Save Time and Money!-Optional program disks are available for all our Amiga reference
books (except Amiga for Beginners and AmigasDOS Quick Reference). Programs listed in
the book are on each respective disk and saves countless hours of typing! $14.95

Books for the AMIGA

Amiga Graphics Inside & Out
The Amiga Graphics Inside & Out book will show you simply and in plain English the super graphic features and functions of the Amiga in detail. You will
learn the graphic features that can be accessed from AmigaBASIC or C.
The advanced user will learn graphic programming in C with examples of
points, lines, rectangles, polygons, colors and more. Amiga Graphics
Inside & Out contains a complete description of the Amiga graphic
system - View, ViewPort, RastPort, bitmap mapping, screens, and
windows.
Topics include:
Accessing fonts and type styles in AmigaBASIC
CAD on a 1024 x 1024 super bitmap, Using graphic
library routines
New ways to access libraries and chips from BASIC - 4096
colors at once, color patterns, screen and window dumps to printer
Graphic programming in C - points, lines, rectangles, polygons,colors
Amiga animation explained including sprites, bobs and AnimObs, Copper and blitter programming
Volume 13 SUggested retail price $34.95 ISR" 1-55755-052-2
IOptional Diskette

$14.95

'727

Amiga Desktop Video Guide

The Amlga Desktop Video Guide is the most complete and useful guide to desktop video on the Amiga.
Amlga Desktop Video Guide covers all the basics - defining video terms,
selecting genlocks, digitizers, scanners, VCRs, camera and connecting
them to the Amiga.
Just a few of the topics you'll find described in this excellent book:
The BaSics of Video
Genlocks
Digitizers and Scanners
Frame Grabbers/Frame Buffers
How to connect VCRs, VTRs, and Cameras to the Amlga
Animation
Video Titling
Music and Videos
Home Video
Advanced Techniques
Using the Amiga to add or incorporate Special Effects to a video
Tips on Paint, Ray Tracing, and 3-D Rendering in Commercial Applications
Volume 14 Suggested Retail Price $19.95 ISBN 1-55755-057-3
Save Time and Money!-Optional program disks are available for all our Amiga reference
books (except Amiga lor Beginners and AmigasDOS Quick Reference). Programs listed in
the book are on each respective disk and saves countless hours of typing! $14.95

Books for the AMIGA

AmigaDOS Quick Reference Guide
AmigaDos Quick Reference Guide is an easy-to-use reference tool for
beginners and advanced programmers alike. You can quickly find commands
for your Amiga by using the three handy indexes designed wHh the user in
mind. All commands are in alphabetical order for easy reference. The most
useful information you need fast can be found- including:

All AmigaDOS commands described, including Workbench 1.3

Command syntax and arguments described with examples
CLI shortcuts
CTRL sequences
ESCape sequences
Amiga ASCII table
Guru Meditation Codes
Error messages with their corresponding numbers

:rtlmii indexes for quick information at your fingertips! The AmigaDOS

Quick Reference Guide is an indispensable tool you'll want to keep close
to your Amiga.

Suggested retail price US $9.95

ISBN 155755-049-2

Abacus Amiga Books

Vol. 1

Amlaa for Bealnners

1-55755-021-2

$16.95

Vol. 2

AmlgaBASIC Inside & Out

0-916439-87-9

$24.95

Vol. 3

Amlaa 3D Graphic Proarammlna In BASIC

1-55755-044-1

$19.95

Vol. 4

Amlaa Machine Lanauaae

1-55755-025-5

$19.95

Vol. 5

Amlga Tricks & Tips

0-916439-88-7

$19.95

Vol. 6

Amlaa System Proarammers Guide

1-55755-034-4

$34.95

Vol. 7

Advanced System Proarammers GUide

1-55755-047-6

$34.95

Vol. 8

AmlgaDOS Inside & Out

1-55755-041-7

$19.95

Vol. 9

Amlaa Disk Drives Inside & Out

1-55755-042-5

$29.95

Vol. 10 Amlaa C for Bealnners

1-55755-045-X

$19.95

Vol. 11 Amlga C for Advanced Programmers

1-55755-046-8

$34.95

Vol. 12 More Tricks & Tips for the Amlga

1-55755-051-4

$19.95

Vol. 13 Amlga Graphics Inside & Out

1-55755-052-2

$34.95

Vol. 14 Amlga Desktop Video Guide

1-55755-057-3

$19.95

AmlgaDOS Quick Reference Guide

1-55755-049-2

9.95



Now

Presenting...

'A

.
'
,
All
.n
n
.. -r,. ,fa
rJrus rrotecfIon: ,DO.
Shipping

.. :' l

..

...,

'I~G : : : : : .. . ..... ~

m
'
,

' . _

Protect your Amiga computer

system with this collection of
essential and valuable tools/

.:Irna 160
Includes
page
I !!:.I~ guide to

Computer

I . Viruses!

The Virus Protection Toolbox

describes how computer viruses
work; what problems viruses
cause; how viruses invade the
Libraries, Handler and Devices
of the operating system;
preventive maintenance; how to
cure infected programs and disks.
Works with Workbench 1.2 and 1.3!

AbacusllBl
5370 52nd Street S. E.

Grand Rapids, MI49512

Available at your local dealer or

Order Toll Free 1-800-451-4319

Amlga Is a registered trademark of Commodore-Amlga Inc.

Some of our best tools included are:

Boot Checkto prevent startup viruses.

Recoverto restore the system information
to disk.
Change Control Checkerto record modifications to
important files.
Check Newto identify new program and data files.
Order now or call for your Free
pamphlet "What you should know
about Computer Viruses"
(while supplies last)

New Software
The Ideal AMiGA wordprocessor

TextPro

BeckerText

TextPro AMIGA upholds the true spirit of the AMiGA:

it's powerful, it has a surprising number of "extra"
features, but it's also very easy to use. TextPro
AMIGA-the Ideal AMiOA word processor that proves
just how easy word processing can be. You can write
your ftrst documents immediately, with a minimum of
learning-without even reading the manual. But
TextPro AMIGA is much more than a begiMer's
package. ffitra-fast onscreen formatting, graphic merge
capabilities, automatic hyphenation and many mci'~
features make TextPro AMIGA ideal for the
professional user as well. TextPro AMIGA features:

High-speed text input and editing

Functions accessible through menus or shortcut keys
Fast onscreen formatting
Automatic hyphenation
Versatile function key assignment
Save any section of an AMiOA screen & print as text
Loading and saving through the RS-232 interface
Multiple tab settings
Accepts IFF format graphics in texts
Extremely flexible printer adaptations. Printer drivers
for most popular dot-matrix printers included
Includes thorough manual
Not copy protected

Suggested retail price:

L -_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~

More than word processing ...

AMIGA

TextPro AMIGA
sets a new standard
for word processing
packages in its price
range. So easy to
use and modestly
priced that any
AMiOA owner can
use it-so packed
with advanced
features, you can't
pass it up.

All Abacus software runs on the Amiga 500. Amiga

1000 or Amiga 2000. Each package is fully compatible
with our other products in the Amiga line

TextPro
ANIIGA

AMIGA
This is one program for ~ AMiOA owners.
BeckerText Amiga is more than a word processor. It
has alI the features of TextPro AMIGA, but it also has
features that you might not expect:
Fast WYSIWYG formatting
Calculations within a text-like having a spreadsheet
program anytime you want it
Templates for calculations in columns
Line spacing options
Auto-hyphenation and Auto-indexing
Multiple-coluIM printing, up to 5 coluIMS on a single
page
Online dictionary checks spelling in text as it's written
Spell checker for interactive proofmg of documents
Up to 999 characters per line (with scrolling)
Many more features for the professional
BeckerText AMIGA
is a vital addition for
C programmers-it's
an extremely flexible
C editor. Whether
you're deleting,
adding or duplicating
a block of C sourcecode, BeckerText
AMIGA does it alI,
automaticalIy.~d

---

Bec:lferText
AMIGA

---

Tho-...

the online dictionary

acts as a C syntax
checker and ftnds
syntax errors in a
flash.
BeckerText AMIGA. When you need more from your
word processor than just word processing.

$ 79.95

Suggested retail price:

$150.00

Abacus Products for

Amiga

computers

Professional DataRetrieve
The Proressional Level
Database Management System
Professional DataRetrieve, for the Amiga 500/1000/2000,
is a friendly easy-to-operate professional level data management package with the features most wanted in a relational
data base system.
Professional DataRetrleve has complete relational data
mangagement capabilities. Define relationships between
different files (one to one, one to many, many to many).
Change relations without file reorganization.
Professional Data Retrieve includes an extensive programming laguage which includes more I1mn 200 BASIC-like
commands and functions and integrated program editor.
Design custom user interfaces with pulldown menus, icon
selection, window activation and more.
Professional DataRetrien can perform calculations and
searches using complex mathematical comparisons using
over 80 functions and consttmts.
Professional DatllRelrine is a friendly, easy to opera Ie
programmable RELATIONAL data base system. I'DR includes PROFIL, a programm ing language similar to BASIC.
You can open and edit up to 8 liIes simullancously and the
size of your data fields , records and files are limited only by
your memory and disk storage. You have complete interrelalion betwecn files which can include IFF graphics. NOT
COpy PROTECTED. ISBN 1-55755-048-4
MORE features of Professional DataRetrieve
Easily imporl daL.1 from other daL.1bases .... fiIe compatible
wilh standard Data Retrieve ....supports multitasking...design
your own custom forms with the completely integrated
printer mask editor....includes PROFIL programming language that allows the programmer to custom tailor his database requirements ...
MORE features of PROFIL include:
Open Amiga devices including the console, printer,
serial and the CLI.
Create your own programmable requestors
Complete error trapping.
Built-in compiler and much, much more.

Suggested retail price:

$295.00

Th.

I'm/mi111
Iml

DnlnMu ...

Features
up to 8 files can be edited sirooltaneously
Maximum size 01 a data field 32,000 characters
(textlields only)
Maximum number 01 data fields limited by RAM
Maximum record size 01 64,000 characters
Maximum number 01 records disk dependent
(2,000,000,000 maximum)
Up to 80 index fields per file
Up to 6 field types - Text, Date, Time, Numeric,
IFF, Choice
Unlimited number of searches and subrange
criteria
Integrated list editor and lull-page printer mask
editor
Index accuracy selectable from 1-999 characters
Multiple file masks on-screen
Easily create/edit on-screen masks for one or
many files
User-programmable pulldown menus
Operate the program from the mouse or the key
board
Calculation fields, Data Fields
IFF Graphics supported
Mass-storage-oriented file organization
Not Copy Protected, NO DONGLE; can be in
stalled on your hard drive

ISBN 1-55755-047-6

90000