Amiga ISO Collection/AmigaUtilCD2.iso/Programming/Basic/MAXONB32.DMS/in.adf/docs.lha/Operating_System

Text File | 1994-10-31 | 99.8 KB | 3,373 lines

Operating System Support




The Amiga header files

MaxonBASIC is supplied with a number of .bmap,
.bh and .bc specific to the Amiga which give
access to the machine´s operating system.
Whilst it is outside the scope of this manual
to give a complete description of the system
software, this section does give an overview of
the facilities available and within which
subsystem and files you can find them.
Many of the example programs supplied with
MaxonBASIC 3 make use of these files and as
such, serve as an excellent starting point for
writing your own Amiga programs. For a complete
guide to system you should refer to the Amiga
ROM Kernel Manuals or one of the many books
available on programming the Amiga (see the
Bibliography).
The operating system itself consists of a
hierarchical system of disk loaded and ROM
resident function libraries, device drivers and
shared hardware resources all working under the
management of the system executive, responsible
for the multitasking and message passing
facilities of the machine. We will use the term
library to refer not just to true libraries but
also to devices, datatypes and resources.

In order for your program to use the facilities
of a given library, your program must first
inform the compiler which functions the library
contains and the machine register conventions
for each call. This information is stored in
.bmap files. Our standard installation will
have copied these for you into the BMAP:
directory. The LIBRARY DECLARE statement is
used to tell the compiler to read the
appropriate .bmap file.
For example,


 LIBRARY DECLARE "graphics.library"
 LIBRARY DECLARE "audio.device"
 LIBRARY DECLARE "gadgets/colorwheel.gadget"


These statements will access the graphics.bmap,
audio.bmap and gadgets/colorwheel.bmap files.
The facilities provided by the operating system
have been expanded over the years considerably
but in a way that you can still write programs
for older systems using the newer .bmap files.
To actually call a library you must first
´open´ the relevant library. For true libraries
you can use the LIBRARY OPEN statement, for
example:


 LIBRARY OPEN "graphics.library"


If you are going to write a program that uses a
facility of the library that wasn´t available
in earlier versions you can specify a minimum
version when you open the library. For example,
if you program will require the LoadRGB32
function that was introduced in version 39 of
the graphics library you can use:


 LIBRARY OPEN "graphics.library",39


The versions of the operating system that were
currently in use at the time of writing are:

34  Workbench 1.3 (A500 owners)
37  Workbench 2.04/2.05(e.g. shipped with
A3000 )
38  Workbench 2.1 (e.g. A600 owners who have
upgraded)
39  Workbench 3.0 (e.g. A1200 and A4000
owners)
40  Workbench 3.1 (e.g. CD32 owners)

Note that early A500 may only have version 33
Kickstart (1.2) but they now generally have
Workbench 1.3.
For devices and resources you will need to use
the OpenDevice and OpenResource functions of
exec.library together with the LIBRARY VARPTR
statement.
The library statement is not enough - the .bmap
files make no distinction between functions and
sub-programs, because they are converted from
the C equivalent .fd files. This is because C
makes no real distinction between functions and
sub-programs - if you aren´t interested in the
result of a function you can call it without
doing anything with the result.
We use the DECLARE statement to do indicate
which routines are functions and which are
subroutines after the LIBRARY statement. Here
is an example of the ASL library:

LIBRARY DECLARE "asl.library"
DECLARE FUNCTION AllocAslRequest& LIBRARY ´
reqType&, tagList&
DECLARE SUB FreeAslRequest LIBRARY
´requester&
DECLARE FUNCTION AslRequest& LIBRARY   ´
requester&, tagList&

The first DECLARE statement indicates that
AllocAslRequest& is a function and the comment
indicates that it has two parameters, reqType&
and tagList&. On the other hand, FreeAslRequest
is a sub-program, i.e. it doesn´t return a
value. It has one parameter, requester&. Note
that all the operating system functions that
are true functions return a long value and that
all the parameters are passed as long integers
too.
Taglists are the method used by most of the
parts of the operating system that have been
added in Workbench 2 and above. The file
requester has 31 different possible options (at
the time of writing!). The operating system
could have a function call for the File
Requester that has 31 parameters, or an area of
memory containing all those parameters but this
would be unwieldy and would be out of date if
Commodore decided to add one more option in a
later release.
So instead you pass a list of tags (which
indicate the value that you are setting and
values that you are setting the flags to). If
you leave out a tag the operating system will
usually provide a sensible default for you.
Commodore have given the tags names, so that
you don´t have to remember the right numbers
for the tags. We supply those names in include
files with MaxonBASIC 3. These constants are in
the files with extension .bc. Continuing our
ASL File Requester example, there´s a tag
called ASLFR_TitleText& ; this specifies the
string to be placed in the top line of the
requester. Taglists are terminated by a value
of 0 (TAG_DONE& and TAG_END& are the
identifiers that are normally used).


DIM frtags&(20)
TAGLIST VARPTR(frtags&(0)), _
 ASLFR_TitleText&, "MaxonBASIC File Requester",
_
 TAG_DONE&


Here the taglist is stored in the array
frtags&(). Notice that we have dimensioned it
with 21 elements (0..20). This is enough for 10
pairs of tags and the terminator. Note that the
address where the tag list is stored is passed,
hence the VARPTR(frtags&(0)). This gives total
flexibility in that you can modify the middle
of a tag list or store it in some memory that
you have allocated yourself. However the
compiler can´t check that you haven´t specified
too many tags. If you specify a string in a tag
list the BASIC will automatically turn it into
a null-terminated C-style string for you and
use the address of the string.
Note that the string values will become invalid
if a garbage collect occurs so you should
ensure that there is sufficient space left on
the heap for any strings you need before
setting up your taglist. Let us assume that you
are setting up a taglist that needs strings
that are x bytes long, you can to this as
follows:


IF FRE(0)< x*2 THEN junk&=FRE("")


Library sub-programs and functions are called
in the same way as BASIC sub-programs and
functions. Here is a complete example of
displaying the File Requester and then freeing
it again.


REM $include asl.bh
LIBRARY OPEN Òasl.libraryÓ

CONST TAG_DONE&=0

DIM frtags&(20)

TAGLIST VARPTR(frtags&(0)), _
 ASLFR_TitleText&,"MaxonBASIC File Requester",
_
 ASLFR_InitialFile&,"", _
 ASLFR_InitialDrawer&, CURDIR$, _

 TAG_DONE&

fr&=AllocAslRequest&(ASL_FileRequest&,VARPTR(fr
tags&(0)))

IF fr& THEN
 IF AslRequest&(fr&,0) THEN
     PRINT "OK!Ó
 ELSE
     PRINT "Cancelled"
 END IF

 FreeASlRequest fr&

END IF


The REM $include statement will make the BASIC
read the asl.bh file. This contains the LIBRARY
DECLARE statement for the ASL library and the
appropriate DECLARE statements for all its
functions and libraries. It also includes
asl.bc itself -this contains the constants for
the tags.
There´s an additional constant here that isn´t
a tag, ASL_FileRequest&. It indicates to the
ASL library that a File Requester (rather than
a Font or Screen requester) is required.
Constants like this are in the asl.bc file too.
All these constants are defined as long
integers even if their values would fit easily
into an ordinary 16 bit integer. This is for
consistency; you shouldn´t need to know the
actual values of these constants.
The example above should really include
utility.bc which contains the definition of
TAG_DONE& rather than defining it itself. This
example is all very well but it doesn´t
actually know which file you have selected. To
do this we need to look at the area of memory
pointed to by the value returned by the
AllocAslRequest& function. This is a data
structure which is described in the asl.bc file
like this:


´FileRequester fields
CONST fr_Reserved0% = 0
CONST fr_File% = 4
CONST fr_Drawer% = 8
CONST fr_Reserved1% = 12
CONST fr_LeftEdge% = 22
CONST fr_TopEdge% = 24
CONST fr_Width% = 26
CONST fr_Height% = 28
CONST fr_Reserved2% = 30
CONST fr_NumArgs% = 32
CONST fr_ArgList% = 36
CONST fr_UserData% = 40
CONST fr_Reserved3% = 44
CONST fr_Pattern% = 52
CONST FileRequester_sizeof%=56


This means that the FileRequester structure
takes 56 bytes - but you should use the
FileRequester_sizeof% constant instead if you
needed it in your programs. The first field is
fr_Reserved and this is 4 bytes long we know
this because the next offset is 4 and the
offset for fr_Reserved is 0. Fields that are
called reserved should be left alone by your
programs.
The next field fr_File, is 4 bytes long (8-4)
and is a pointer to the filename that the user
has entered as a C-string. We can print this
out using:


 PRINT PEEK$(PEEKL(fr&+fr_File%))


fr&+fr_File% gives the address of the fr_File
field and the PEEKL retrieves the value stored
there. PEEK$ will then convert this into a
BASIC string.
The operating system data structures are listed
in detail in the ROM Kernel Manual: Includes
and Autodocs and are supplied on disk in the
Native Developer Update Kit, available from
Commodore. The newer parts of the operating
system generally don´t require you to modify
system data structures, they provide ways of
setting the fields via tags, however the older
facilities need to be accessed directly.
One data structure that is often used is the
TextAttr. Here is its definition from
graphics.bc:


´TextAttr fields
CONST ta_Name% = 0
CONST ta_YSize% = 4
CONST ta_Style% = 6
CONST ta_Flags% = 7
CONST TextAttr_sizeof%=8


To define a text attr we can use an array of
integers like this:


DIM ta%(TextAttr_sizeof%\2)


The division by 2 is needed because the sizes
of structures are specified in bytes and each
element of an integer array uses 2 bytes.
The following sub-program can be used to set up
such an array:


DEFINT a-z

SUB InitTextAttr(T(1),FontName$,BYVAL Height, _
     BYVAL style,BYVAL flags)
POKEL
VARPTR(T(0))+ta_Name%,SADD(FontName$+CHR$(0))
t(ta_YSize\2)=Height
POKEB VARPTR(T(0))+ta_Style,style
POKEB VARPTR(T(0))+ta_Flags,flags
END SUB


Note that SADD(FontName$+CHR$(0)) is used to
produce a pointer to a C string and POKEL is
used to store this as a long within the integer
array. To store integer elements of arrays you
can use a normal BASIC array assignment but
note again the division by 2 which converts
from a byte offset to an integer array index.
To store the byte members of this structure we
use the POKEB instruction.
When working with the operating system you´ll
save a lot of time if you use pre-tokenised
files for the include files. See the end of
Chapter 4: The Compiler for a description of
this.
In our examples we normally include the .bh
file for a library or device that we are using
but occasionally we will include the .bc file
instead. We use this when we aren´t calling the
library directly but still want to use its
constants or data structures; this saves
opening the library unnecessarily at runtime
and speeds up compilation a little.


Additional functions

As well as the data structure and constant
definitions, the C header files also contain
some C macros. We´ve included versions of the
most useful of these as sub-programs in files
in the Blib drawer within the BH drawer.
As well as the functions that are actually in
the true Amiga libraries, you will also see C
examples using functions from the C linkable
Amiga.lib library. This includes code for
calling devices directly, task and port
creation and BOOPSI support routines. Again we
have also provided these in the Blib drawer.
The Blib drawer also has routines that we hope
you will find useful for things such as busy
pointers and gadtools menus. These have no
equivalents in C.


Name conflicts

In some cases, the conventional names used
operating system routines and record fields
conflict with BASIC reserved words or other
operating system field names.
The following reserved words are prefaced with
an x; this is a hangover from AmigaBASIC and
HiSoft BASIC 1:

ABS       CLOSE      EXIT       INPUT
OPEN      OUTPUT     READ       TAN
TRANSLATE WAIT       WRITE

So the DOS library Open routine is named xOpen.
Clashes with other reserved words are resolved
by adding an underscore (_) to the end of a
name. For example the window field of the Layer
data structure in the graphics library is
called window_%.
 Clashes between structure fields and constant
names are resolved by prefixing the structure
name with the name of a structure, hence the
priority field from the Layer data structure in
the graphics library has been renamed
LayerPriority%.
The best way to check the name of a field is to
view the .bc file itself in the editor - you
can also check the size of the field at the
same time; this may not be obvious if you are
converting an example written in C.
We also strongly recommend that you keep your
code that calls the operating system in sub-
programs and use the Variable Checks
(VARCHECKS) option; this way the compiler can
often tell you if you mistype a field or
constant name; if you don´t use this option the
compiler won´t warn you but your program will
either crash or not work quite correctly when
you run it.



Libraries

The following documentation gives for each
library, the version of the operating system in
which it first appeared, the corresponding
Commodore C header files and a description of
the library´s function. Note that we only
include here versions of the operating system
that are currently in use.
A general overview of the library is then
given. For a full description, please refer to
the Amiga ROM Kernel Manuals: Libraries and the
Native Developer Update Kit.


Amigaguide                                2.1


Headers:     libraries/amigaguide.h
The amigaguide library provides the progammer´s
interface to the AmigaGuide help system. It
lets you add context sensitive help to the
program that you are writing. Typically you
would use the OpenAmigaGuideAsyncA& function to
open AmigaGuide and use the SendAmigaGuideCmdA&
function to send it commands (for example to
give help on a particular topic) and then
CloseAmigaGuide when finished. This library can
also be used to set up nodes that change
dynamically.


ASL 2.04





Headers:     libraries/asl.h
From Workbench 2.0, the asl.library contains
File and Font Requesters and Workbench 2.1
added the Screen Mode Requester. Typically you
allocate a requester with AllocAslRequest&,
activate it with AslRequest&, read the values
returned and then call FreeAslRequest.


Bullet                                    2.1


Headers:     diskfont/glyph.h,oterrors.h
The Bullet library is the Compugraphic outline
font engine that has been supplied as part of
the operating system from Workench 2.1. You can
use this if you need fine control over the font
rendering for example arbitrary rotation of
characters and access to kerning tables.


Commodities                              2.04


Headers:     libraries/commodities.h
The Commodoties library is used if your are
writing your own Commodities like the screen
blanker.


Datatypes                                 3.0


Headers:     datatypes/datatypes.h
This library lets you use the data types that
were added as part of Workbench 3.0; you´ll
need this library regardless of which datatype
class you are using and you will need to use
the include file for the particular datatype
classes that are used. These are described
later.


DiskFont                                  1.3


Headers:     diskfont/diskfont.h,
             diskfonttag.h
The DiskFont library is a disk-loaded library
responsible for loading new fonts into the
system. Using the OpenDiskFont function rather
than the Graphics library´s OpenFont function
will automatically load a font from the current
FONTS: directory if necessary.
Note that any number of programs may be using
the same font in memory and even once each of
these has called CloseFont, the data may still
remain in memory. However, all unused fonts,
libraries and devices will be flushed from
memory once the system requires the memory for
something else.


DOS 1.3



Headers:     dos/datetime.h, dos.h, dosasl.h
             dosextens.h, doshunks.h,
             dostags.h, exall.h,
             filehandler.h, notify.h,
             rdargs.h, record.h, var.h,
             stdio.h

The DOS library contains functions to examine
and manipulate files as well as some utility
routines and new process handling.
Note that you need to use LIBRARY OPEN
"dos.library" to call the exec functions; C
examples don´t do this.


Files


Some of the key routines in the DOS library are
xOpen, xInput and xOutput which return file
handles for subsequent xRead, xWrite and
possible Seek calls. You must xClose any file
handles which belong to you before your program
terminates. If a DOS call fails, you may obtain
an AmigaDOS error code from the IoErr function.
Opening a DOS device such as PRT: or SER: is
allowed and a specification such as
CON:0/0/640/200/Title can be used to open a new
console window. Input and Output return the
default file handles provided by DOS for your
program. These often refer to the Shell´s
console window but may be re-directed the user.
You should be aware that a program started from
Workbench has no default input or output
handles.
File Locks may be obtained from the Lock or
DupLock functions and may be used to uniquely
identify a volume, directory or file.
CurrentDir accepts a lock referring to a new
directory and returns the previous current
directory. Examine and ExamineNext provide
information on locked files. Remember to UnLock
file locks once you have finished with them.


BCPL


AmigaDOS uses some conventions of the BCPL
language in which it was originally written.
BCPL pointers (called BPTRs in the C include
files) are shifted right by 2 bits compared to
the actual machine address. This means that you
must first find the pointer address by
shifting. For example,

cli&=PEEKL(PEEKL(process&)+pr_CLI%)<<2
When passing memory to a DOS function, such as
a FileInfoBlock to Examine, it must lie on a 4
byte boundary. If a BPTR is required within a
structure you must shift it right twice before
storing it. This alignment is guaranteed by
both the MaxonBASIC safe_malloc routine and
Exec library memory allocation schemes.
Ideally, you should use the Workbench 2.0,
AllocDosObject function. BCPL strings are often
used within structures. These consist of a
single length byte followed by the data and
must also be aligned in this way.
For those interested in the structure of
AmigaDOS, many of the DOS library functions
simply form an interface to the underlying file
systems. Calling the Read function for example
will fill in a standard message packet with the
arguments you supply, send the message to the
appropriate filing system and wait for a reply.


Exec1.3


Headers:     exec/alerts.h, devices.h,
             errors.h, exec.h, execbase.h,
             interrupts.h, io.h, libraries.h,
             lists.h, memory.h, nodes.h,
             ports.h, resident.h,
             semaphores.h, tasks.h, types.h
The Exec library (also known as the system
executive) effectively coordinates the entire
system. It handles task switching, library and
device management, memory allocation, message
passing, inter-task communication and
interrupts as well as providing many low-level
utility routines for manipulating and sorting
linked lists, queues and stacks.
Note that you need to use LIBRARY OPEN
"exec.library" to call the exec functions; C
examples don´t do this.


Lists

In order to keep track of the entire system,
Exec makes extensive use of doubly linked lists
via the List and Node records. The List header
is slightly unusual in that it effectively
contains a dummy head and tail Node which do
not form part of the list. It also contains
some information concerning the nature of the
list. A list structure may be initialised with
the NewList function from Blib/ExecSupport.bas.
The Node record contains pointers to the
previous and next nodes along with optional
node type, priority and name. This record is
often the first member of a larger structure.
MinList and MinNodes provide the functionality
of Lists and Nodes without any type, priority
or name.
You may add and remove list nodes using Insert,
AddHead, AddTail, Remove, RemHead and RemTail.
Enqueue inserts a node according to its
priority. FindName searches a list for the
named node. In order to scan a list yourself,
you must remember to ignore the head and tail
nodes. Valid nodes always have successor and
predecessors, never NIL pointers.


Memory


Memory may be allocated via AllocMem and
FreeMem. Provision is made for allocating chip
memory (accessible by the Amiga custom chips).


Messages


In order to use message passing you must first
have a Port. This may be obtained from the
system, such as an Intuition window´s UserPort
or from the CreatePort function of
Blib/ExecSupport.bas. Wait, WaitPort, GetMsg,
PutMsg and ReplyMsg can then be used
communicate via this port. The device I/O
mechanism, Intuition´s IDCMP messages and
AmigaDOS´s packet sending are all built on top
of these basic functions.
To communicate with a device it is necessary to
allocate and initialise an IORequest record
using Blib/ExecSupport.bas´s CreateExtIO.
OpenDevice will then fill in the device
information and you must set up the io_Command
and possibly io_Data and io_Length before
calling DoIO (synchronous) or SendIO
(asynchronous). BeginIO, WaitIO, CheckIO and
AbortIO are also available for asynchronous
device I/O. CloseDevice and DeleteIOReq or
DeleteExtIOReq must be used before program
termination. BeginIO is actually a BASIC
keyword because of its unusual calling
conventions.



Expansion                                 1.3

Headers:     libraries/configregs.h,
             configvars.h, expansion.h,
             expansionbase.h
The Expansion library is the software that
interfaces to the Auto-Config mechanism of the
Amiga which allocates address space for
controller and memory cards. It is only of use
when writing new device drivers, which is
rather tricky from BASIC!


Gadtools                                  2.0


Headers:     libraries/gadtools.h
Gadtools was introduced with Workbench 2.0 and
provides a fairly easy to use scheme for
programming gadgets and menus. Some of the
latest features of the operating system can´t
be accessed via Gadtools however, you will need
to use BOOPSI for this. Having said that the
gadtools facilities have more immediate
functionality than the base BOOPSI facilities.


Graphics                                  1.3


Headers:     graphics/clip.h, collide.h,
             coerce.h, copper.h,
             display.h,displayinfo.h, gels.h,
             gfx.h, gfxbase.h, graphint.h,
             modeid.h, monitor.h, rastport.h,
             regions.h, rpattr.h, scale.h,
             sprite.h, text.h, videocontrol.h,
             view.h
There are basically three areas covered by the
Graphics library: display control, drawing and
animation. It is used by Intuition for all
rendering and is closely linked with the Layers
library.


Display

The graphics display primitives make use of
ViewPorts which describe a horizontal strip of
the display. ViewPorts are used by Intuition to
display draggable screens with different modes
and colour palettes. A number of ViewPorts may
be chained together in one View which describes
the complete display.
Display data is described in a BitMap and
consists of one or more ´bitplanes´ which
represent a rectangular array of pixels. In
order to represent different pen colours these
bitplanes are effectively stacked with the
corresponding pixel bits making up a pen
number. The actual colour in which each pen is
displayed is determined by the palette held in
a ColorMap record.
InitBitMap, AllocBitMap, AllocRaster,
GetColorMap, InitVPort and InitView initialise
the structures and MakeVPort, MrgCop and
LoadView generate the ´copper list´ which
coordinates the display hardware to produce the
correct image. These resources must later be
deallocated via FreeRaster, FreeColorMap,
FreeVPortCopLists and FreeCprList.
Note that generating a custom view which is
correct in all aspects on AGA machines is very
difficult.


Drawing

Drawing takes place via a RastPort. The
RastPort contains information concerning the
current co-ordinate positions, pen colours,
drawing mode, text font, line drawing pattern
and graphics layer (used for clipping). Some
commonly used drawing procedures are Move,
Draw, DrawCircle, DrawEllipse, Flood and Text.
SetAPen and SetBPen are used to select
foreground and background pen colours whilst
SetDrMd sets up a drawing mode.
Many graphics operations work on a whole block
of the display area. Examples of this are
scrolling, drawing rectangles, moving images
and clearing the display. The Amiga ´blitter´
(block image transfer) chip may be utilised via
the Graphics library; the calls ScrollRaster,
RectFill, SetRast and ClipBlit provide this.
More control over the blit operation is
provided by the wonderfully named BltBitMap,
BltPattern, BltTemplate, BltBitMapRastPort and
BltMaskBitMapRastPort!
All of the graphics drawing routines may be
used on the RastPort of an Intuition window.
The system will handle all clipping so that
only the visible parts of your window are drawn
into (although you must be careful not to draw
all over the window borders).


Animation

The animation routines provide facilities for
controlling ´sprites´ (images which move around
the display). Simple sprites correspond to
hardware sprites such as the one used for the
mouse pointer. These are used as the basis of
VSprites (virtual sprites) which make effective
use of the available hardware sprites. These
images are never actually drawn in the
RastPort, instead they are superimposed over it
by the graphics hardware.
Another form of movable image is the bob
(blitter object). These are drawn by software
and consequently are slower but give more
flexibility. Workbench attaches bobs to the
mouse pointer in order to provide draggable
icons.
Animated images are controlled via an AnimComp
(animation component) which are linked together
to provide an AnimOb (animation object). Any of
these structures may form a GEL (graphics
element) which may be moved around the display
at different velocities with acceleration
control.


Icon1.3


Headers:     workbench/icon.h
The Icon library provides application access to
the .info files used by the Workbench. The
GetDiskObject function loads the icon for a
specified file and returns a pointer to a
DiskObject record defined in Workbench.bc. In
general, programs should only add to or examine
an icons unit and not adjust the imagery or
default tool. The FindToolType and
MatchToolValue functions may be used for this
purpose.
To create or save an icon, PutDiskObject must
be called. The icon may be one previously
obtained from GetDiskObject or simply hard-
coded into the program. To dispose of a
DiskObject structure, call FreeDiskObject
although care must be taken to restore any
tooltypes which have been changed.


IFFParse                                 2.04


Headers:     libraries/iffparse.h
IFFParse is a new library added with Release 2
of the operating system but also available
under 1.3. It handles the reading and writing
of IFF (interchange file format) files.
IFFParse merely handles the job of
´understanding´ the file format, interpreting
or generating the file contents is completely
up to you. The library has support for DOS
files, the Amiga clipboard, user defined stream
types and IFF property chunks.
The general method of using IFFParse is to
first call AllocIFF to obtain the IFFHandle
used to refer to the file. You can then use the
AmigaDOS Open or IFFParse OpenClipboard
function to initialise an iff_Stream and call
InitIFFasDOS or InitIFFasClip. OpenIFF will
then begin reading or writing.
By default, the ParseIFF function will simply
read the entire file and tell you that it´s
done it. In order to do something useful you
must first call StopChunk to inform the parser
of which chunks you are interested in.
PropChunk may be used to record property chunks
which can be accessed via FindProp.
Writing IFF is performed through PushChunk and
PopChunk. To begin writing a chunk, specify the
name, ID and size (or IFFSIZE_UNKNOWN).
WriteChunkBytes or WriteChunkRecords will
actually output the data and PopChunk will
complete the chunk, adding the correct size and
pad byte if necessary.
For a full description of the use of IFFParse,
refer to the Amiga ROM Kernel Manuals:
Libraries. C language examples and the IFF
specification may also be found in the Devices
manual.


Intuition                                 1.3


Headers: intuition/cghooks.h, classes.h,
classusr.h, gadgetclass.h, icclass.h,
imageclass.h, intuition.h, intuitionbase.h,
preferences.h, screens.h, sghooks.h
Intuition is responsible for the windowing
interface of the Amiga. It handles screens,
windows, menus, gadgets and requesters and
provides a high level mechanism for programs to
receive mouse, keyboard and other system
events. It also supports BOOPSI (Basic Object-
Orientated Progamming System for Intuition)
which is the foundation on which many of recent
extensions to the operating system, such as
datatypes are built.
One thing which Intuition does not do is give
scrolling text windows. For this you must use
the console device.


Windows


Probably the most important object handled by
Intuition is the window. A window can be opened
by first creating and initialising a NewWindow
record and passing it to the OpenWindow
function. A pointer to a Window record will be
returned and the NewWindow may then be freed or
re-used. The NewWindow record contains
information such as the window size, default
title, system gadgets (close gadget, depth
gadgets, sizing gadget etc.) and refresh type
(simple, smart or superbitmap).
The RPort field of the Window points to a
Graphics library RastPort which may be used for
drawing into the window. The Window structure
should generally be treated as read-only with
adjustments to the window being carried out via
the appropriate Intuition library functions. A
program is responsible for closing each of its
windows with CloseWindow.



Screens

All windows exist on Intuition screens. By
default, the Workbench screen will be used but
programs may open as many screens as they wish
in a similar manner to opening windows. A
NewScreen record must be supplied to OpenScreen
which then returns a pointer to a Screen. This
pointer can then be used for subsequent new
windows and later closed with CloseScreen. The
Screen structure contains BitMap, ViewPort and
ColorMap records as used by Graphics.



Menus

A menu bar may be attached to a window once it
has been opened via the SetMenuStrip. The Menu
and MenuItem records are used to describe the
menu bar, items and sub-items. You must call
ClearMenuStrip before closing a window or
attaching a new menu strip.


Gadgets


Intuition gadgets are the buttons, scroll bars
and text input boxes used by the system. These
are created by setting up a linked list of
Gadget records each containing the position,
size and type of a single gadget. The BoolInfo,
StringInfo and PropInfo structures contain
further details for particular gadget types.
The actual appearance of a gadget is determined
by Image, Border and IntuiText records which
are once again attached to the Gadget
structure. These graphical objects are also
used for rendering menus and Intuition provides
support routines for using them from your own
code.
Once initialised, gadgets must be added to a
windows gadget list and refreshed before they
appear on the display. Further manipulation is
possible with AddGadget, RemGadget,
RefreshGList, GadgetOn and GadgetOff. In order
to determine the current state of a gadget you
may examine certain fields in the relevant data
structure.


IDCMP

In order to keep track of what the user is
doing, your program must monitor each window´s
IDCMP (Intuition Direct Communication Message
Port) for incoming IntuiMessages. When opening
a window or calling ModifyIDCMP you may specify
which events will be received for a given
window. Keypresses, menu selections, gadget
operations, mouse clicks or movements, disk
insertions, resizes and close events are all
reported in this way. Exec´s Wait, GetMsg and
ReplyMsg functions are the usual method of
handling these messages.
Your program may also be notified that its
window requires ´refreshing´, i.e. something
has obscured part of its display which now
needs redrawing. The system (through the Layers
library) does provide a facility for automatic
refreshing although it does involve some
overhead. To do your own refreshing, simply
call BeginRefresh, draw the entire window
contents and call EndRefresh. This will
optimise drawing so that only the damaged areas
are drawn into. Intuition takes care of drawing
the window gadgets itself.


BOOPSI


BOOPSI (or Basic Object Oriented Programming
System for Intuition) first appeared in
Workbench 2.0. It has provides the object
orientated foundation for many of the newer
facilities of intuition, such as the colorwheel
gadget and datatypes. It provides an easier way
to use Intuition gadgets although perhaps not
as easy as using the Gadtools library.
The real power of BOOPSI comes from writing
your own custom classes to extend the system.
It is only possible to give a brief overview of
Intuition here but it is the section of the
Amiga operating system which the applications
programmer will spend much of his or her time
working with. Indeed, large books have been
written on the subject. Take time to
familiarise yourself with its operation and try
to stick to the standard user interface where
possible.


Keymap                                    1.3

Headers:     devices/keymap.h

This file defines the Keymap structure type
which contains all the necessary information to
translate physical key presses into ASCII
sequences. This information is used by the
Console device and Intuition to translate raw
key codes from the hardware via Input device
into readable characters and cursor control
sequences.
Note that the Console device supports commands
to read and write the keymap associated with a
given console window and the system default
keymap.


Layers                                    1.3


Headers:     graphics/layers.h
Co-operates with the Graphics library in order
to provide overlapping ´layers´ with automatic
clipping and backup and restore of hidden
areas. To quote the ROM Kernel Manual; ÒThe
Layers Library takes care of the mundane
things, the low level, repetitive tasks that
are needed to keep track of where to put which
bitsÓ. When using Intuition, the operation of
layers is mainly transparent to the programmer.
Note that many layers functions actually form
part of the Graphics library.
Essentially, a layer is a list of clipping
rectangles associated with a BitMap. These
ClipRect records form a graphics Region.
Examples of Regions are the visible portion of
a window, or the areas exposed by scrolling
part of the display. Many utility routines for
adding rectangles and regions together exist in
the Graphics library.
Layers may be created, deleted, moved, resized,
depth arranged and scrolled. It can be seen
that these form the basis of Intuition´s
windowing system. Automatic backup of hidden
areas for refreshing is available as is manual
refreshing via BeginUpdate and EndUpdate. A
layer may also use its own private BitMap which
may be larger than the screen.


Locale                                    2.1


Headers:     libraries/locale.h
The Locale library was introduced in Workbench
2.1 so that programs can adapt to different
languages, date formats and currencies. To use
its catalog facilities you will need the
CatComp developers´ tool from Commodore.


Lowlevel                                  3.1


Headers:     libraries/lowlevel.h
Introduced in Workbench 3.1, the low level
library adds facilities for games programmers
in the hope that by using this their software
will work on future machines, whereas direct
hardware access might not.


Nonvolatile                               3.1


Headers:     libraries/nonvolatile.h
The non-volatile library is designed for CD32
games to provide a ´save game´ facility using
the NVRAM of the CD32 or another method if
running on a machine without NVRAM. This was
introduced in version 3.1 of the operating
system.


Realtime                                  3.1


Headers:     libraries/reatime.h
The realtime library is designed for ´playing´
events that happen in real time.


Rexx2.04



Headers:     rexx/errors.h, rexxio.h,
             rxslib.h, storage.h
The Rexx library provides facilities for
sending ARexx commands, checking errors etc.
Although we use the name Rexx.bh for the
include file the library is actually called
"rexxsyslib.library".


Translator                                1.3


Headers:     libraries/translator.h
Translator is a disk loaded library which used
to be supplied with the operating system. It
essentially exists for a single function call;
Translate&. This converts a string of English
language text into phonetics suitable for use
by the Narrator device. In general we do not
recommend the use of this as it is no longer
supplied as part of the operating system; if
you are still using it the BASIC TRANSLATE$
function is easier to use.


Utility                                  2.04


Headers:     utility/date.h, hooks.h,
             tagitem.h, name.h, pack.h,
             utility.h

The utility library provides a range of
facilities from tag list manipulation, date
conversions and taking advantage of the integer
math functions of the 68020 and above. You may
find it useful to use utility.bc on its own as
this will give definitions for such things as
TAG_DONE&.


Workbench                                2.04

Headers:     workbench/startup.h, workbench.h

The Workbench.bc file gives the definition of a
DiskObject as used for Workbench icons and
supported by the Icon library. For further
details refer to the Icon library description.
The Workbench library itself contains the
functions for installing AppIcons, AppWindows
and AppMenuItems.


Devices

i.devices;
Amiga devices are used by the system for I/O.
Each device must support a minimal set of
commands including read, write, stop, start and
flush. Whilst this is may be sufficient for a
simple stream type device such as a serial
driver, other devices require extensions to the
basic model. Hence, many devices support ´non-
standard´ commands which are specific to that
particular device.
Most devices exist as a separate task within
the system, i.e. they run simultaneously with
your program. Often, a device will support
multiple ´units´ such as a number of disk
drives or audio channels. I/O is achieved by
sending messages, I/O requests, to the device.
Programs may either wait for their completion
(synchronous I/O) or continue with other things
while the request is being carried out
(asynchronous I/O).
To use a device you must therefore have an
understanding of the Exec library´s message
passing system. Messages require a ´reply port´
which your program must provide although this
may be shared between several devices or used
for other purposes. I/O requests must also be
correctly initialised which is handled by the
Blib/ExecSupport.bas function, CreateExtIO.
Devices often use their own format of I/O
request with special fields tagged onto the
end.
Some devices, in addition to the message based
commands described above, also provide directly
callable functions, much like those given by
libraries. In fact, the internal representation
of a device is simply an extension of the Amiga
library mechanism. Such devices require a base
pointer to be initialised before their
functions can be used.
One example of such a device is the Timer
device; of course most of the time it is much
easier to use the BASIC ONÉTIMER statement
since this will handle ´talking´ to the timer
device for you.

´REM $INCLUDE Exec.bh
´REM $INCLUDE Timer.bh

REM $INCLUDE BLib/ExecSupport.bas
defint a-z
´ return a pointer to a timer request. if any
problem, return NULL
FUNCTION create_timer&(BYVAL unit&)
 STATIC r&, timerport&, timerIO&
 create_timer& = NULL&
 timerport& = CreatePort&(NULL&, 0)
 IF timerport& <> NULL& THEN
  timerIO& =
CreateExtIO&(timerport&,timerequest_sizeof)
  IF timerIO& <> NULL& THEN
    r& = OpenDevice&(SADD("timer.device" +
CHR$(0)), _
           unit&, timerIO&, 0)
    IF r& = 0 THEN
     create_timer& = timerIO&
    ELSE
     delete_timer timerIO&
    END IF
  ELSE
    DeletePort timerport& ´ Delete message port
  END IF
 END IF
END FUNCTION
SUB delete_timer(BYVAL tr&)
 STATIC tp&

 IF tr& <> NULL& THEN
  tp& = PEEKL(tr& + tr_node +
IORequestio_Message + _
               mn_ReplyPort)
  IF tp& <> 0 THEN DeletePort tp&
  CloseDevice tr&
  DeleteExtIO tr&
 END IF
END SUB

This illustrates the various setup required for
device I/O. The create_timer& function, creates
a message port called timerport&. A message
port is created. The I/O request block, in this
case a timerequest, is allocated and
initialised for use on that port. The correct
device unit is opened using the I/O request
block and returned as the result of the
function. The delete_timer sub-program ´un-
does´ this by deleting the port, closing the
device and deleting the I/O request block.
Note that, at each stage, the program checks
for errors and exits gracefully if
unsuccessful. It should be pointed out that the
OpenDevice call, unlike OpenLibrary, returns
zero for success or an appropriate error code.
In order to send an I/O request, the
appropriate fields for the device must first be
filled in. Often this is simply a matter of
setting io_Command to the command number,
io_Data to point to the data to be sent or
receive buffer and io_Length to its size. The
amount read or written will be returned in
io_Actual. Other devices have different
conventions. The following Exec functions are
available for device I/O: DoIO (synchronous,
waits for completion), SendIO (asynchronous),
CheckIO, WaitIO and AbortIO.
After successfully opening a device, the
io_Device and io_Unit fields may be copied into
another suitable I/O request block in order to
send multiple requests without having to reopen
the device.
The functions mentioned above are Exec
functions; normally these are all you will
need. Sometimes you will want to use device
specific functions. To do this for the timer
device with the function shown above you could
use:


tr& = create_timer&(UNIT_MICROHZ&)

LIBRARY VARPTR "timer.device", _
 PEEKL(tr& + tr_node + IORequestio_Device)


We can now call the AddTime, SubTime or CmpTime
functions as the above has set the TimerBase
variable for us. After using these you must
clean up with


LIBRARY VARPTR "timer.device", NULL&
delete_timer tr&


otherwise the BASIC runtimes will try to close
the device as if it was a true library.


Audio                                     1.3



Headers:     devices/audio.h

The Audio device handles sound output and
arbitration for the system. It should be used
even when writing to the hardware registers
directly in order to avoid conflicts with other
programs which may be running.
An IOAudio request block is used for audio
device I/O. When OpenDevice is called, you may
specify channels to be allocated via the
ioa_Request. The ioa_Length field in the
ioa_Request was as if you had send a
ADCMD_ALLOCATE command. An ioa_Length of zero
simply opens the device for later channel
allocation. Many commands work on multiple
audio channels determined by the io_Unit field.
The ADCMD_ALLOCATE command takes a sound
precedence in io_Message.mn_Node.ln_Pri to
determine whether it can override other sounds
which are in progress. Sounds may be started
with a CMD_WRITE after filling in the
appropriate fields of the IOAudio request
block.
Note that you must start i/o with BeginIO
rather than SendIO/DoIO.
The Amiga generates sounds from waveform or
sample data which must be located in Chip
memory. Even simple waveforms such as square,
sine or sawtooth waves must be represented by
an array of signed byte values.


CD                                       3.1



Headers:     devices/cd.h
The CD device first appeared with Workbench 3.1
and is used to control a CDROM drive as on the
CD32, although it can also be used with add-on
drives on other Amigas.


Clipboard                                 1.3



Headers:     devices/clipboard.h
The Amiga Clipboard provides a rendezvous for
applications that wish to ´cut´ and ´paste´
data. It supports multiple clip units, IFF
(interchange file format), disk spooling,
random access and delayed ´post´ write
requests. It is highly recommended that all
programs supporting block operations use the
Clipboard.
Clipboard I/O uses an IOClipReq which is
identical to a standard request with the
addition of the io_ClipID field. Although the
device supports 255 separate unit numbers
(requested through OpenDevice), the
PRIMARY_CLIP unit should be used unless
requested through user preferences. Note that
the clipboard.device file must be present in
DEVS: for use.
The sequence of events for cutting a block to
the clipboard is to CreateExtIO an IOClipReq,
OpenDevice the appropriate unit, CMD_WRITE with
io_Offset and io_ClipID set to zero. The
io_Data and io_Length fields indicate the
length of the data. Any number of CMD_WRITEs
may be used, terminated by a CMD_UPDATE to
complete the clip.
Pasting is achieved by sending CMD_READS
(io_Offset must again be initialised to zero)
until the returned io_Actual is zero,
indicating end of clip.
In order to support the clipboard, a program
must understand IFF. The most common IFF forms
used are FTXT (formatted text) and ILBM
(interleaved bitmap) for graphics. For a full
description of the IFF standard, please refer
to the ROM Kernel Manuals: Devices, Third
Edition.
Easier clipbaord support is available via the
Datatypes library; however this will only work
under Workbench 3 and above.


Console                                   1.3



Headers:     devices/console.h, conunit.h
The Console device provides ANSI terminal
capabilities within an Intuition window. ANSI
control sequences, line buffering and editing
(as used by the CLI and Shell) are supported.
The Console device may also be accessed in a
file-based manner via CON: under AmigaDOS.
Opening a Console device involves creating a
port, IOStdReq and Intuition window. An
OpenDevice of unit 0 with io_Data and io_Length
set up for the Window structure will fill in
io_Device with the device base pointer and
io_Unit as a pointer to a ConUnit record. Many
useful values such as the cursor position and
dimensions may be read from this data
structure.
Characters are output to the window and read
back using CMD_WRITE and CMD_READ in the usual
way. Control sequences to request special event
reporting or keyboard mapping information may
also be sent in this way. Note that the console
unit must be closed before the associated
Intuition window.
In addition to I/O operations, the console
device offers several library style functions
such as RawKeyConvert to translate raw keycodes
into text characters or control sequences. In
order to use these, the LIBRARY VARPTR  must be
initialised from a valid io_Device. Opening
unit -1 of the device may be used to obtain
this base pointer without opening a new console
window.


Gameport                                  1.3



Headers:     devices/gameport.h
Gameport is the device which handles mouse and
digital joystick input. There is no system
support for proportional joysticks. This
information is in turn passed on to the Input
device to form part of the event stream.
Two units are available, corresponding to the
Amiga´s two joystick ports. Unit 0 is normally
used for the mouse leaving unit 1 available for
other purposes. You may configure the Gameport
device to respond to specific events from a
particular type of controller. Each action is
returned in the form of an InputEvent.


Input                                     1.3



Headers:     devices/input.h, inputevent.h
The purpose of the Amiga Input device is to
collect and organise the stream of user input
events from the keyboard, mouse, disk drives
etc. into what is sometimes referred to as the
´food chain´. Intuition and the Console device
use this to react to user actions and programs
may add to or adjust input events as required.
The most common reason for directly opening the
Input device is to add ´hot keys´ (keypresses
which activate a program or operation
regardless of which application is running) to
the system by inserting a handler into the
input chain. However under workbench 2 and
above you should use the Commodities library
instead.
For other applications, it is usually
preferable to use Intuition´s IDCMP scheme or
access the Console, GamePort or Timer devices.


Keyboard                                  1.3



Headers:     devices/keyboard.h
The Keyboard device gives system access to the
Amiga keyboard and is usually only accessed by
the Input device. Commands to read the keyboard
matrix and to add reset handlers for emergency
processing upon user reset are also supported.
Warning: reading key events directly from the
Keyboard device will prevent them from reaching
the Input device and system event stream. Use
Intuition or the Console or Input device
instead.


Narrator                                  1.3




Headers:     devices/narrator.h
The Amiga Narrator is the device which used to
be used to produce recognisable human-like
speech from phonetic text. When used in
conjunction with the Translator library,
English language text to speech translation can
be achieved. Unfortunately, narrator is no
longer part of the newer versions of the
operating system. If you are still using the
speech facilities it is generally much easier
to use the BASIC SAY command. However if you
want additional control, then you will need to
use the Narrator device directly.


Parallel                                  1.3


Headers:     devices/parallel.h
The Parallel device is used for bi-directional
I/O via the Centronics compatible parallel
port. It is used by the Printer device which
should be employed for all printer output.
The IOExtPar request is used and is initialised
upon calling OpenDevice. Standard commands can
be used to read and write data. The device can
be programmed to accept a number of ´end of
transfer´ characters if required.


Printer                                   1.3



Headers:     devices/printer.h, prtbase.h,
             prtgfx.h
The Printer device is a disk loaded device
which via different printer drivers provides
translation of ANSI control sequences and full
colour or monochrome screen dumps. Output is
directed through SER: or PAR: according to
current user preferences.
Note that for many text applications it is
simpler to use the BASIC LPRINT or PRINT#
commands.
The Printer device uses 3 types of I/O
requests; IOStdReq for CMD_START and CMD_WRITE
etc., IOPrtCmdReq for sending printer commands
directly (PRD_PRTCOMMAND) and IODRPReq to
request a graphic dump of a RastPort
(PRD_DUMPRPORT). These may be allocated with
CreateExtIO.
The standard I/O commands all work as expected,
translating ANSI command sequences where
necessary. Note that if a printer driver does
not support a particular command, it will
simply be ignored. A common mistake is to send
escape codes suitable for your printer rather
than standard ANSI commands. See your system
documentation for a complete list of the
supported commands. The PRD_RAWWRITE I/O
command sends unprocessed data to the printer.
One of the main reasons for using the Printer
device directly is to utilise the graphic dump
facilities. A sub-rectangle of a RastPort may
be printed with the supplied ColourMap,
ViewModes (including HAM, Extra Half Bright
etc.), aspect ratio and page positioning. Note
that the printer device is not limited by Amiga
screen resolutions.


Ramdrive                                  1.3

The Ramdrive device has function calls to
remove the DOS RAD: device.


SCSI2.04



Headers:     devices/scsidisk.h, hardblocks.h
SCSI (small computer system interface) hardware
is used on the Amiga 3000 computer and
A2091/A590 hard drives to transfer data under
the control of the SCSI device. This device is
also used to control the IDE interfaces on the
A1200 and A4000. This device can cope with
standard I/O commands as well as some Trackdisk
commands and HD_SCSICMD to issue a SCSI-direct
command to any SCSI unit on the bus.
The RigidDiskBlock structure used to provide
automatic mounting of hard drive partitions
also forms part of the scsi.bc file. Note that
different hard drives use other driver software
and mount information. All file level access
must be done through AmigaDOS and not through
the device interface.


Serial                                    1.3



Headers:     devices/serial.h
The Serial device controls the Amiga´s built in
RS-232C compatible serial port. It supports a
variety of transfer protocols and baud rates.
Note that output intended for a printer should
instead be sent to the Amiga Printer device.
An IOExtSer request block contains the
parameters required for serial transfer. This
is achieved by use of standard device commands
with some extra commands providing control over
various parameters.
Some applications requiring high speed serial
transfer, notably MIDI programs, may ´miss´
data due to system software overhead. If it is
necessary to write to the hardware directly,
this should only be done after successfully
allocating the appropriate bits through the
Misc resource.


Timer                                     1.3



Headers:     devices/timer.h
Provides general purpose timing through an Exec
style device. Two timer resolutions are
supported, vertical blank (through UNIT_VBLANK)
for long duration requests and microhertz
(UNIT_MICROHZ) for short burst timing.
The Timer device can also be used to read or
set the system clock and for library routines
involving time calculations based upon I/O
requests.
The device is intended for interval timing and
does not support stopwatch or alarm clock style
functionality For general purpose application
´prods´ for updating scroll bars or list
displays, Intuition windows can provide
´intuitick´ events at a rate of around 10 per
second.
The Timer device uses a timerequest structure
for I/O which is simply an IORequest with
fields for seconds and microseconds added to
it. When sending timerequests to the timer
device via SendIO, you must be careful not to
re-use the request block until the device has
replied to it. Any number of requests may be
sent and they will be returned in the
appropriate order. Using DoIO will simply delay
your program for a period of time in a similar
way to the dos.library Delay sub-program.
One bug which exists in the Timer device under
Kickstart 1.3 and before is that asking for a
time delay of 0 or 1 microseconds can crash the
system.




Trackdisk                                 1.3

Headers:     devices/trackdisk.h
Trackdisk is the device used by the Amiga
filing system to read and write floppy disks.
It is intended for advanced users only. Some
standard commands are supported and in
addition, many device specific commands to
control the motor, seek to a specific track,
format the disk, check disk and drive status
and read/write raw MFM data are available.



Resources

In general, resources handle arbitration of
shared hardware. Since the Amiga multitasks,
different programs or devices may require
access to the hardware and to ensure they do
not conflict, this is done through the
appropriate resource.
Important note: resources are just one step
above direct hardware manipulation. There is
usually a higher level device or library
interface that is easier to use, maintain and
upgrade and which shares the hardware more
efficiently between applications.
You must open a resource before calling its
functions. An example of this is:


rem $include exec.bh
rem $include disk.bh

DiskBase& = OpenResource&(SADD("disk.resource"
+ CHR$(0)))



To call the functions in a resource you need to
´tell´ the BASIC runtimes that this is the base
pointer of the resource:



 LIBRARY VARPTR "disk.resource", DiskBase&


You can now call the resource´s functions.
You may notice that there is no CloseResource
call; unlike the closing calls for libraries
and devices. However you must reset the library
base pointer to 0 like this:


 LIBRARY VARPTR "disk.resource", 0


 otherwise the BASIC runtimes will try and
close the resource as if it was a library.


BattClock                                 2.0



Headers:     resources/battclock.h
This resource accesses the Amiga´s battery
backed clock; normally you should not access
this directly; use the timer device if you need
to set the date/time.


BattMem                                   2.0



Headers:     resources/battclock.h,
             battmembitsamiga.h,
             battmembitsamix.h,
             battmembitsshared.h
This resource accesses the Amiga´s battery
backed up configuration RAM; normally you
should not access this.


CardRes                                  2.05




Headers:     resources/card.h
The Card Resource is used to control the PCMCIA
credit card slot of the Amiga 600 and 1200.


CIA 1.3

Headers:     resources/cia.h


This resource grants access to the interrupts
and timer bits of the 8520 CIA (complex
interface adaptor) chips. Some applications
such as MIDI and time coding programs require
such extreme accuracy and low overhead timing.
However, the vast majority of programs should
use the Timer device.
The CIA resource is unique in that it actually
is actually two resources: "ciaa.resource" and
"ciab.resource" corresponding to the two CIA
chips. You should use the LIBRARY VARPTR
statement to switch between using the two
 The BASIC calling of the CIA resource
functions differs from the C convention in that
the BASIC doesn´t include the resource base as
the first parameter.
There are only four interval timers available
and some of these will already be in use by the
system. The correct method of allocating a
timer is to add a timer interrupt using
AddICRVector. There are two CIA chips with
resource names of "ciaa.resource" and
"ciab.resource". Normally, you should open
ciab.resource and attempt to allocate timer B,
or timer A if it was already in use.


Disk1.3



Headers:     resources/disk.h
The Amiga supports up to 4 floppy disk units
which may be reserved through use of the Disk
resource. Routines exist to permanently
allocate or temporarily ´borrow´ a disk unit
although you should be aware that the Trackdisk
device normally allocates all units for its own
use.


FileSystem                                1.3


Headers:     devices/hardblocks.h,
             devices/bootblock.h,
             resources/filesysres.h
As has been mentioned, the AmigaDOS filing
system is built upon a number of ´file
handlers´ which communicate via a standard
packet based interface. The two most common
file handlers used by floppy and hard disks are
the Fast File System (FFS) and Old File System
(OFS).
FileSystem.bc contains a number of structures
and definitions which are used by the system to
determine and update the current configuration.
A list of available file systems may be
obtained by opening the FileSystem resource.


Misc1.3

Headers:     resources/misc.h
The Misc resource is used to arbitrate the use
of several important registers which control
the serial and parallel hardware. It should be
used when a program wishes to drive such
hardware directly rather than through the
standard device interface.
The correct way to allocate these bits is to
call MR_ALLOCMISCRESOURCE with the appropriate
constant and an identification name. If the
call returns NULL&, you now have exclusive
access until MR_FREEMISCRESOURCE is called.
Note that all versions of the Serial device up
to and including 1.3 contain a bug which
prevents them from correctly freeing the serial
bits when closed but still resident in memory.
The workaround for this is to Forbid, FindName
the serial device on the ExecBase device list,
RemDevice it and Permit.


Potgo                                     1.3


Headers:     resources/potgo.h
The Potgo resource allows control of the
hardware POTGO register connected to some I/O
pins on the joystick ports. The Gameport device
and Intuition provide other methods of reading
joysticks and mouse buttons. The functions
AllocPotBits, FreePotBits and WritePotgo should
be used to access these bits.


Gadgets


With Workbench 3.0, Commodore extended the
range of System gadgets available by using
BOOPSI gadgets. These BOOPSI gadgets are really
libraries that are normally stored in the
gadgets drawer inside the classes drawer of you
system disk. These are true libraries and we
have placed the corresponding .bh and .bc files
in a separate gadgets draw, so you can open
them with,


´REM $INCLUDE Gadgets/ColorWheel.bh
LIBRARY OPEN "gadgets/colorwheel.gadget", 39




Gadgets/ColorWheel                        3.0


Headers:     gadgets/colorwheel.h
This BOOPSI class provides the ColorWheel
gadget, as used by the Palette preferences. It
also has a couple of sub-programs of its own
for converting RGB to HSB colours.


Gadgets/GradientSlider                    3.0


Headers:     gadgets/gradientslider.h
This BOOPSI class provides the Gradient Slider
gadget, as used in conjunction with the
ColorWheel gadget. Note that the GradientSlider
gadget doesn´t have any of its own functions,
but we provide a dummy .bmap file so that it
can still be opened.


Gadgets/Tapedeck                          3.1


Headers:     gadgets/tapedeck.h
With Workbench 3.1, Commodore introduced this
BOOPSI class to provide a consistent way of
controlling animation and sound play back. We
provide a dummy .bmap file so that this gadget
can be opened even though it doesn´t provide
any of its own functions.


Datatypes


Workbench 3 introduced a very powerful way of
extending the data that can be handled by
programs without the need for them to
´understand´ the file formats involved. Like
gadgets, datatypes are built on to the BOOPSI
facilities of intuition and are stored in the
datatypes drawer of your classes drawer;
however you don´t need open the datatypes
themselves. You will need to use the
corresponding .bc or .bh file for their
constants and data structures.


Datatypes/AmigaguideClass                 3.0


Headers:     datatypes/amigaguideclass.h
The Amigaguide datatype can be used to ´drive´
Amigaguide. The datatypes/amigaguide.bc class
contains the IDs and constants for accessing
this.


Datatypes/AnimationClass                  3.1


Headers:     datatypes/animationclass.h
The AnimationClass datatype was introduced with
Workbench 3.1 for playing animations. The
datatypes/animationclass.bc file contains the
IFF ids and constants for using the animation
datatype.


Datatypes/DatatypesClass                  3.0


Headers:     datatypes/datatypesclass.h
The datatypes class is the base class on which
all other datatypes are built. This header
files also contains the structures and
constants that are used when writing datatypes.


Datatypes/PictureClass                    3.0


Headers:     datatypes/pictureclass.h
The PictureClass data type is used for
manipulating graphics images. The
datatypes/pictureclass.bc file contains the IFF
IDs and constants for using the picture
datatype.


Datatypes/SoundClass                      3.0


Headers:     datatypes/soundclass.h
The SoundClass is used for playing sounds. The
datatypes/soundclass.bc file contains the IFF
IDs and constants for using the sound datatype.


Datatypes/TextClass                       3.0


Headers:     datatypes/textclass.h
The TextClass is used for formatted and un-
formatted text. The datatypes/textclass.bc file
contains the IFF IDs, constants and structures
for using the text datatype.


BLib

The files in the Blib drawer fall into the
following classes:

·  Routines  that  are  in  the  C   library
   Amiga.lib
·  Sub-programs and functions that implement C
   macros from the Commodore include files,
·  Extra  utility routines that we  hope  you
   will  find useful but have no C counterpart.
   These  we  won´t  document here  because  we
   hope   they   will  evolve  with  subsequent
   releases.


ExecSupport.bas


This corresponds to the amiga.lib functions
that deal with Exec features, such as
CreatePort, DeletePort, CreateExtIo,
DeleteExtIO and NewList. It also contains
CreateTask and DeleteTask, but these may only
be used if the task is written in C or
assembler.


HookEntryTask.bas


This contains a single routine
CreateHookEntryTask which is similar to
CreateTask but can be used to create a task
written in BASIC. The assembly language code
used by this is shown in TaskHookEntry.s. Note
that a garbage collection may be disastrous to
either the parent or created task.


BoopsiSupport.bas


Boopsi.bas contains implementations of the
macros in intuition/classes.h and the
CoerceMethodA&, DoMethodA& and DoSuperMethodA&
routines from Amiga.lib.


Gfxmacros.bas


This contains implementations of the macros in
graphics/gfxmacros.h. This includes the
SafeSetOutlinePen and SafeSetWriteMask sub-
programs which call the corresponding Workbench
3.0 calls but fall back to a method which will
work under older versions of the operating
system.


Other

Some of the Amiga MaxonBASIC include files do
not fall under the category of libraries,
devices, resources, or BOOPSI classes, they are
merely definitions that you may find useful.
In order to use these units you simply include
them with rem $include at the start of your
program. No other preparation is required.


Hardware


Headers:     hardware/adkbits.h, blit.h,
             cia.h, custom.h, dmabits.h,
             intbits.h
The hardware.bc file contains a collection of
definitions necessary when directly reading and
writing the Amiga hardware registers. Whilst
the operating system is running you should
never do this unless you have gained exclusive
access to the hardware through the correct
system functions. Failure to do so can result
in unexpected crashes, loss of data, hard disks
etc. You have been warned!
You should be aware that some hardware
registers trigger actions upon read or write
accesses. Great care must be taken with these
registers to ensure the correct behaviour.



Prefs


Headers:     prefs/font.h, icontrol.h,
             input.h, locale.h, overscan.h,
             palette.h, pointer.h, prefhdr.h,
             printergfx.h, printerps.h,
             printertxt.h, screenmode.h,
             serial.h, sound.h, wbpattern.h
The prefs.bc file contains the structures and
constants used to define the IFF file formats
used by the various Preferences editors.
Normally you will only need these if writing an
alternative preferences editor.


Obsolete names

Over the lifetime of the Amiga´s operating
system Commodore have changed some of the names
that are used for constants. They recommend
that the old names are no longer used. As this
is the first release of MaxonBASIC to come with
constant files, we do not provide the old
names. Unfortunately though, you may see
programs in other languages that use the old
names. In particular the ROM Kernel Manuals
that were current at the time of writing still
use some of the old names. So you can convert
these to the modern names we have listed them
here.


IFFParse library





Old Name             New Name
IFFSCC_INIT          IFFCMD_INIT
IFFSCC_CLEANUP       IFFCMD_CLEANUP
IFFSCC_READ          IFFCMD_READ
IFFSCC_WRITE         IFFCMD_WRITE
IFFSCC_SEEK          IFFCMD_SEEK






ASL library

Originally the ASL library used a single tag
name for both the File and Font Requesters.
Where they are used for both, there are now
separate names starting with ASLFR for the file
requester and ASLFO for the font requester as
shown in the table below:

Old Name      New Name(s)
rf_File       fr_File
rf_Dir        fr_Drawer
rf_LeftEdge   fr_LeftEdge
rf_TopEdge    fr_TopEdge
rf_Width      fr_Width
rf_Height     fr_Height
rf_NumArgs    fr_NumArgs
rf_ArgList    fr_ArgList
rf_UserData   fr_UserData
rf_Pat        fr_Pattern
ASL_Hail      ASLFR_TitleTe ASLFO_TitleTe
              xt            xt
ASL_Window    ASLFR_Window  ASLFO_Window
ASL_LeftEdge  ASLFR_InitalL ASLFO_InitalL
              eftEdge       eftEdge
ASL_TopEdge   ASLFR_Initial ASLFO_Initial
              TopEdge       TopEdge
ASL_Width     ASLFR_Initial ASLFO_Initial
              Width         Width
ASL_Height    ASLFR_Initial ASLFO_Initial
              Height        Height
ASL_HookFunc  ASLFR_HookFun ASLFO_HookFun
              c             c
ASL_File      ASL_InitialFi
              le
ASL_Dir       ASL_InitialDr
              awer
ASL_FontName  ASLFO_Initial
              Name
ASL_FontHeigh ASLFO_Initial
t             Size
ASL_FontStyle ASLFO_Initial
s             Style
ASL_FontFlags ASLFO_Initial
              Flags
ASL_FrontPen  ASLFO_InitialF
              rontPen
ASL_BackPen   ASLFO_Initial
              BackPen
ASL_MinHeight ASLFO_MinHeig
              ht
ASL_MaxHeight ASLFO_MaxHeig
              ht
ASL_OKText    ASLFR_Positiv ASLFO_Positiv
              eText         eText
ASL_CancelTex ASLFR_Negativ ASLFO_Negativ
t             eText         eText
ASL_FuncFlags ASLFR_Flags1  ASLFO_Flags
ASL_ModeList  ASLFO_ModeLis
              t
ASL_ExtFlags1 ASLFR_Flags2
ASL_Pattern   ASLFR_InitalP
              attern
FILB_DOWILDFU FRB_FILTERFUN
NC            C
FILB_DOMSGFUN FRB_INTUIFUNC
C
FILB_SAVE     FRB_DOSAVEMOD
              E
FILB_NEWIDCMP FRB_PRIVATEID
              CMP
FILB_MULTISEL FRB_FOMULTISE
ECT           LECT
FILB_PATGAD   FRB_DOPATTERN
              S
FILF_DOWILDFU FRF_FILTERFUN
NC            C
FILF_DOMSGFUN FRF_INTUIFUNC
C
FILF_SAVE     FRF_DOSAVEMOD
              E
FILF_NEWIDCMP FRF_PRIVATEID
              CMP
FILF_MULTISEL FRF_DOMULTISE
ECT           LECT
FILF_PATGAD   FRF_DOPATTERN
              S
FIL1B_NOFILES FRB_DRAWERSON
              LY
FIL1B_MATCHDI FRB_FILETERDR
RS            AWERS
FIL1F_NOFILES FRF_DRAWERSON
              LY
FIL1F_MATCHDI FRF_FILTERDRA
RS            WERS
FONB_FRONTCOL FOB_DOFRONTPE
OR            N
FONB_BACKCOLO FOB_DOBACKPEN
R
FONB_STYLES   FOB_DOSTYLE
FONB_DRAWMODE FOB_DODRAWMOD
              E
FONB_FIXEDWID FOB_FIXEDWIDT
TH            HONLY
FONB_NEWIDCMP FOB_PRIVATEID
              CMP
FONB_DOMSGFUN FOB_INTUIFUNC
C
FONB_DOWILDFU FOB_FILTERFUN
NC            C
FONF_FRONTCOL FOF_DOFRONTPE
OR            N
FONF_BACKCOLO FOF_DOBACKPEN
R
FONF_STYLES   FOF_DOSTYLE
FONF_DRAWMODE FOF_DODRAWMOD
              E
FONF_FIXEDWID FOF_FIXEDWIDT
TH            HONLY
FONF_NEWIDCMP FOF_PRIVATEID
              CMP
FONF_DOMSGFUN FOF_INTUIFUNC
C
FONF_DOWILDFU FOF_FILTERFUN
NC            C






Intuition

The obsolete names in Intuition were obsolete
as of version 2.0 so only very old code should
use them. Sadly they still appear in some of
the ROM Kernel Manual Examples. Some of these
are merely different casings of the modern
usage which would make no difference in BASIC
in any case, so they haven´t been listed here.

Old Name             New Name
GADGHIGHBITS         GFLG_GADGHIGHBITS
GADGHCOMP            GFLG_GADGHCOMP
GADGHBOX             GFLG_GADGHBOX
GADGHIMAGE           GFLG_GADGHIMAGE
GADGHNONE            GFLG_GADGHNONE
GADGIMAGE            GFLG_GADGIMAGE
GRELBOTTOM           GFLG_RELBOTTOM
GRELRIGHT            GFLG_RELRIGHT
GRELWIDTH            GFLG_RELWIDTH
GRELHEIGHT           GFLG_RELHEIGHT
SELECTED             GFLG_SELECTED
GADGDISABLED         GFLG_DISABLED
LABELMASK            GFLG_LABELMASK
LABELITEXT           GFLG_LABELITEXT
LABELSTRING          GFLG_LABELSTRING
LABELIMAGE           GFLG_LABELIMAGE
RELVERIFY            GACT_RELVERIFY
GADGIMMEDIATE        GACT_IMMEDIATE
ENDGADGET            GACT_ENDGADGET
FOLLOWMOUSE          GACT_FOLLOWMOUSE
RIGHTBORDER          GACT_RIGHTBORDER
LEFTBORDER           GACT_LEFTBORDER
TOPBORDER            GACT_TOPBORDER
BOTTOMBORDER         GACT_BOTTOMBORDER
BORDERSNIFF          GACT_BORDERSNIFF
TOGGLESELECT         GACT_TOGGLESELECT
BOOLEXTEND           GACT_BOOLEXTEND
STRINGLEFT           GACT_STRINGLEFT
STRINGCENTER         GACT_STRINGCENTER
STRINGRIGHT          GACT_STRINGRIGHT
LONGINT              GACT_LONGINT
ALTKEYMAP            GACT_ALTKEYMAP
STRINGEXTEND         GACT_STRINGEXTEND
ACTIVEGADGET         GACT_ACTIVEGADGET
GADGETTYPE           GTYP_GADGETTYPE
SYSGADGET            GTYP_SYSGADGET
SCRGADGET            GTYP_SCRGADGET
GZZGADGET            GTYP_GZZGADGET
REQGADGET            GTYP_REQGADGET
SIZING               GTYP_SIZING
WDRAGGING            GTYP_WDRAGGING
SDRAGGING            GTYP_SDRAGGING
WUPFRONT             GTYP_WUPFRONT
SUPFRONT             GTYP_SUPFRONT
WDOWNBACK            GTYP_WDOWNBACK
SDOWNBACK            GTYP_SDOWNBACK
CLOSE                GTYP_CLOSE
BOOLGADGET           GTYP_BOOLGADGET
GADGET0002           GTYP_GADGET0002
PROPGADGET           GTYP_PROPGADGET
STRGADGET            GTYP_STRGADGET
CUSTOMGADGET         GTYP_CUSTOMGADGET
GTYPEMASK            GTYP_GTYPEMASK
SIZEVERIFY           IDCMP_SIZEVERIFY
NEWSIZE              IDCMP_NEWSIZE
REFRESHWINDOW        IDCMP_REFRESHWINDOW
MOUSEBUTTONS         IDCMP_MOUSEBUTTONS
MOUSEMOVE            IDCMP_MOUSEMOVE
GADGETDOWN           IDCMP_GADGETDOWN
GADGETUP             IDCMP_GADGETUP
REQSET               IDCMP_REQSET
MENUPICK             IDCMP_MENUPICK
CLOSEWINDOW          IDCMP_CLOSEWINDOW
RAWKEY               IDCMP_RAWKEY
REQVERIFY            IDCMP_REQVERIFY
REQCLEAR             IDCMP_REQCLEAR
MENUVERIFY           IDCMP_MENUVERIFY
NEWPREFS             IDCMP_NEWPREFS
DISKINSERTED         IDCMP_DISKINSERTED
DISKREMOVED          IDCMP_DISKREMOVED
WBENCHMESSAGE        IDCMP_WBENCHMESSAGE
ACTIVEWINDOW         IDCMP_ACTIVEWINDOW
INACTIVEWINDOW       IDCMP_INACTIVEWINDOW
DELTAMOVE            IDCMP_DELTAMOVE
VANILLAKEY           IDCMP_VANILLAKEY
INTUITICKS           IDCMP_INTUITICKS
IDCMPUPDATE          IDCMP_IDCMPUPDATE
MENUHELP             IDCMP_MENUHELP
CHANGEWINDOW         IDCMP_CHANGEWINDOW
LONELYMESSAGE        IDCMP_LONELYMESSAGE
WINDOWSIZING         WFLG_SIZEGADGET
WINDOWDRAG           WFLG_DRAGBAR
WINDOWDEPTH          WFLG_DEPTHGADGET
WINDOWCLOSE          WFLG_CLOSEGADGET
SIZEBRIGHT           WFLG_SIZEBRIGHT
SIZEBBOTTOM          WFLG_SIZEBBOTTOM
REFRESHBITS          WFLG_REFRESHBITS
SMART_REFRESH        WFLG_SMART_REFRESH
SIMPLE_REFRESH       WFLG_SIMPLE_REFRESH
SUPER_BITMAP         WFLG_SUPER_BITMAP
OTHER_REFRESH        WFLG_OTHER_REFRESH
BACKDROP             WFLG_BACKDROP
REPORTMOUSE          WFLG_REPORTMOUSE
GIMMEZEROZERO        WFLG_GIMMEZEROZERO
BORDERLESS           WFLG_BORDERLESS
ACTIVATE             WFLG_ACTIVATE
WINDOWACTIVE         WFLG_WINDOWACTIVE
INREQUEST            WFLG_INREQUEST
MENUSTATE            WFLG_MENUSTATE
RMBTRAP              WFLG_RMBTRAP
NOCAREREFRESH        WFLG_NOCAREREFRESH
WINDOWREFRESH        WFLG_WINDOWREFRESH
WBENCHWINDOW         WFLG_WBENCHWINDOW
WINDOWTICKED         WFLG_WINDOWTICKED
NW_EXTENDED          WFLG_NW_EXTENDED
VISITOR              WFLG_VISITOR
ZOOMED               WFLG_ZOOMED
HASZOOM              WFLG_HASZOOM






C for BASIC programmers


Users programming the Amiga in any computer
language will discover that most of the
documentation, books and example programs which
exist are based around the C language. This is
partly because much of the machine´s operating
system was originally written in C and partly
because of the language´s current popularity
and the early availability of an Amiga C
compiler.
We have gone to a great deal of effort to
ensure that MaxonBASIC supports the Amiga in a
comprehensive manner; you aren´t tidied to just
the set of OS routines that we have built into
the BASIC. However, whether you are using BASIC
because it is the language which you are used
to or simply because you find it easier to use,
you will find a basic knowledge of C most
useful when trying to use the Amiga to its
full.
In the following section we will attempt to
furnish the reader with a basic working
knowledge of C, enough to understand the system
documentation and example programs. We would
like to stress that it is by no means intended
to teach C to BASIC programmers (why would we
want to do such a thing?), merely to provide
enough information to allow you to figure it
out for yourself.


Data structures



Basic types


Like  most  languages, C provides a  number  of
basic  types  which  represent  characters  and
numbers;  these may be employed for  variables,
constants,  structured types etc. You  can  use
this section for converting C types to BASIC.


Here  is  a  list of them and their  MaxonBASIC
equivalents:




 C type         BASIC type    byte size
 char           see below     1
 int            % (integer)   2/4
 short          % (integer)   2
 long           &       (long 4
                intger)
 unsigned char  see below     1
 unsigned int   see below     2/4
 unsigned       see below     2
 short
 unsigned long  no equivalent 4

The first thing to notice is that int can have
two sizes. This is because the type int is used
to specify the natural integer type. It may be
either a long or a short integer. In practice,
most Amiga programs are written for long
integers only but you cannot always assume that
this is the case.
BASIC´s types are always signed, but C also has
unsigned types like unsigned short; this has a
range of 0 to 65535 rather than -32768 to
32767. If you need to perform arithmetic on
such a value then you should convert it to a
long integer first.
The char type in C stores a single byte;
there´s no exact equivalent of this in BASIC
but they can be stored as one element of a
string or in an integer variable ignoring the
top byte.
Another point of confusion is that both signed
and unsigned character types exist. Each of
these can be used for storing numbers or ASCII
characters. Although char is supposed to mean a
signed quantity, C compilers often give the
option of making it default to unsigned to
avoid bizarre problems when converting to other
types. Because of this confusion Commodore use
the following named types in their header
files:

 Commodore      Range      of byte size
 type           values
 BYTE           -128 to 127   1
 UBYTE          0 to 255      1
 WORD           -32768     to 2
                32767
 UWORD          0 to 65535    2
 LONG           -2147483648   4
                to 2147483647
 ULONG          0          to 4
                4294967295
 BOOL           0-1           2

MaxonBASIC does not provide an unsigned long
type. Instead, you will have to make do with
longer integers. In practice, this does not
present too much of a problem as you may
specify hex numbers to allow use of the full 32
bits. Unsigned long is often used for bit
flags.


Constants


In  general, constant values look much the same
in both languages. One important distinction is
between  character and string  constants  which
use   different  delimiters.  These  and  other
constants are illustrated below.




 type of constant      example
 decimal               123
 signed number         -287
 decimal long          96L
 hex                   0x1800
 octal                 0375
 character             ´a´
 string                ÒhelloÓ




In  addition  to this, there are  some  special
rules for character constants and strings.  The
backslash  character  (\)  is  used  to  denote
certain special control sequences.


You  should also be aware that strings  may  be
split  over  several lines  without  using  any
special concatenation character.




 character sequence    represents
 \n                    end of line
 \r                    carriage return
 \l                    line feed
 \t                    tab
 \f                    form feed
 \0                    end of string
 \D                    decimal
                       character code
 \xDD                  hex     character
                       code

Although C has a const keyword to define
constants, most programs make use of the
#define directive of the preprocessor. The
preprocessor acts like an extra pass of the
compiler which goes around substituting defined
values or names and including other files.
Although #define is capable of great
sophistication, you will often see it used to
specify a numeric or string constant as in


#define VANILLAKEY 0x00200000


Commodore often use the convention of defining
a flag bit number and value with B and F, e.g.
MEMB_CLEAR refers to the bit number whilst
MEMF_CLEAR is the actual value you would use in
expressions.
Another method of defining a list of related
constants in C is an enumeration. For example


 enum Colours { Red, Green, Blue };


is equivalent to the BASIC


CONST Red%=0, Green%-1, Blue%=2


This type may be referred to as enum Colours
and is equivalent to int.


Pointers

Now we are getting to more interesting things.
C supports typed and untyped pointers. A
pointer of unknown type is known as a ´void´
pointer. Essentially a pointer contains the
address of the data that it points to, so you
can store a pointer with POKEL and read it with
PEEKL. pointers are always stored as long
integers (with the & sign on the end in BASIC).
Pointers are denoted by the * character. For
example,


 void *something;
 char *name;


In the second example, the star means that it
is a character pointer; these tend to be used
where you would use a string in BASIC but they
are stored differently, rather than storing the
length of the string and its address the string
ends when a 0 character (like CHR$(0)) is
found. That is why you use
SADD(strname$+CHR$(0)) to pass a string to the
operating and why we provide the PEEK$ function
to convert a C string to BASIC.
.A pointer to a pointer is declared as


 int **table;


The star character is also used as a
´dereferencing´ operator, i.e. it gives you
what the pointer is actually pointing at. This
corresponds to PEEKB/PEEKW/PEEKL depending on
the size of the data. For example,


 initial = *name;


would put the character pointed to by name into
the variable initial. Thus the BASIC equivalent
would be


 initial=PEEKB(name)


 Note that the equals sign in C represents an
assignment rather than equivalence as it does
in Pascal.
The opposite of the * operator is & or ´address
of´. It gives you a pointer to the object
rather than its value and is used in much the
same way as BASIC´s VARPTR operator. The symbol
NULL is often used to specify a pointer that is
not pointing anywhere. Its actual value is
zero.

The  Amiga  header files from Commodore  define
several pointer types used by the system.




 pointer type       purpose
 APTR               a void pointer
 BPTR               an    AmigaDOS   BCPL
                    pointer,      shifted
                    right by 2 bits
 CPTR               general       purpose
                    pointer
 STRPTR             pointer to a C  null-
                    terminated string

An unusual feature of C pointers is that adding
and subtracting numbers from them gives you a
pointer to the next or previous object, i.e.
adding one to a long pointer makes it point to
the next longword in much the same way as
adding one to a character pointer causes it to
point to the next character. If you are
converting such pointer arithmetic to BASIC you
will need to multiply the offsets by the size
of the data. This is how arrays are
implemented.


Arrays

Pointers and arrays in C are very closely
linked. Defining an array of 10 integers is a
matter of saying


 int array[10];


C always starts array numbering at zero but the
10 doesn´t give the index of the last element
in the array, it gives the size of the array.
The expression array[9] would thus give the
last element in the array. Because of the way
arrays work, just saying array actually yields
a pointer to the start of the array and array+3
is a pointer to the fourth (numbering starts
from zero, remember) element of it! Note that C
uses square brackets rather than parentheses
for arrays.
It is possible to miss out the number of
elements in an array declaration. This can be
very dangerous as the compiler can no longer
warn you if you are writing to array elements
that don´t actually exist but it is a powerful
technique. It allows you to have arrays of no
fixed size, dynamic arrays, or to determine the
array dimensions at run time.
It is this laxness of type checking that
permits C programmers to miss out the []
characters on many occasions, use a simple
character pointer to point to a string and to
say ´pointer´ when they really mean ´array´.
Beware.
Multi-dimensional arrays are used in the
following way.


 short minutes[24][60];
 minutes[12][0] = minutes[23][59];


In other words, a 24-deep array where each
element is itself an array of 60 short
integers.

Pointers  and  arrays  are  one  of  C´s   most
powerful features. Although confusing at first,
they  are very useful. The following comparison
table may help to clear up a few points.




 C           BASIC            comment
 expression  equivalent
 *name       PEEKL(name&)     value
                              which  name
                              is
                              pointing
                              to
 grid[8][12  grid[8,12]       using     a
 ]                            multi-
                              dimensiona
                              l array
 *messages[  PEEKL(messages&  extracting
 2]          +2*4)            value   via
                              a  table of
                              pointers






Structures and Unions


Structures are very important part of C and are
something  that have to be converted  to  PEEKs
and  POKEs  in BASICs. A structure may  contain
simple  types, pointers, arrays and have  other
structures  embedded within it. To  demonstrate
this, here is the C declaration o a structure.





struct student {
 struct Tutor *next;
 struct History
info;
 char name [32];
 short int age,
stay;
};

The  first  element is called  next  and  is  a
pointer to another structure called Tutor.  The
*  indicates  that it is a pointer.  This  will
take  up  4 bytes and so would be accessed  via
PEEKL and POKEL in BASIC.
The  next  field, info is actually a  structure
called  History embedded within this structure,
so  it  would  take  up as many  bytes  as  the
History structure, lets say that is 10 bytes.
Next  comes  an  array of 32 characters  called
name.  To  access the individual characters  we
would  use  PEEKB. Finally there are two  short
integers which as we have seen before will take
up  2  bytes and so could be accessed via PEEKW
and  POKEW. To use a similar definition to  the
MaxonBASIC Amiga include files for this  record
we would have:


´ Fields of student
CONST next_offset%=0
CONST info_offset%=4
CONST name_offset%=14
CONST age_offset%=46
CONST stay_offset%=48
CONST student_sizeof%=50


So where

 st.name[i]=c
was used in C you would use

 POKEB st&+name_offset%+i,c
in BASIC and given

 i= stp->stay
you would have

 i=PEEKW(PEEKL(stp&)+stay_offset%)


Notice the difference here between the C .  and
->  operators. The first accesses the structure
directly  whereas  the second  uses  a  pointer
deference (hence the PEEKL call in the BASIC).
Unions   follow  a  very  similar   syntax   to
structures  although  instead  of  each  member
being  placed sequentially in memory  they  are
overlaid on top of one another.
These  are used to represent data which may  be
accessed  in  a number of ways or  a  structure
which  may  contain different  sets  of  values
depending upon the circumstances.


Type checking

Because   C  has  the  concept  of  types,   on
occasions  where you need to convert  from  one
type  to  another  (often caused  by  functions
which   use  generic  pointers  and   types   -
allocating memory for example) C allows you  to
specify  a ´coercion´. Simply placing the  type
name  in  brackets  before the  value  performs
this.


 button = (struct Gadget *)
     AllocMem(sizeof(struct Gadget),
     MEMF_CLEAR | MEMF_PUBLIC);


Here, the void pointer returned by AllocMem  is
being  explicitly  typed to  a  gadget  pointer
before  assignment to button. By  contrast,  in
BASIC  you  must  make sure that  you  use  the
correct structure offsets yourself.


Programs



Functions

The  declaration of a function in C looks  very
much  like  a  modern BASIC  version.  Function
prototypes  are often used which  look  like  a
function  definition without any code following
it,  just like a DECLARE statement. Here is  an
example which demonstrates the layout  of  a  C
function:


 int main(int argc, char *argv[])
 {
     int counter;
     char digits[] = {1, 2, 3};
     return 5;
 }


The   function  return  type  is  given   first
followed  by  the name and bracketed  parameter
list.  The } or ´close curly bracket´ is the  C
equivalent  of  the  END  keyword  followed  by
whatever   you   are  ending.   The{   has   no
counterpart in BASIC but marks the beginning of
a set of statements.
You  will  see  a lot of these curly  brackets.
It´s  often easier just to ignore them all when
trying to understand a C program!
Any  local variables associated with a function
come immediately after the opening bracket  and
may  be  initialised after an equals sign.  The
previous  example  shows initialisation  of  an
array using more curly brackets, structures can
be   initialised  in  the  same  way.  This  is
initialisation  is  a bit like  having  a  DATA
statement for the values and then reading  them
into the variable.
Unlike   BASIC,  C  makes  little   distinction
between a sub-program and a function. In  C,  a
sub-program is known as a void function, i.e. a
function  with  no return value.  Similarly,  a
function which takes no parameters is  said  to
have a void parameter list. A simple example of
this is:


 void simple_function(void);


instead of


SUB simple_function


For  functions  which do return  a  value,  the
return  statement  may  be  used  to  exit  the
function  with the given number. This  is  like
assigning  a  value  to the function  name  and
doing  an EXIT FUNCTION. Any number of  returns
may  appear in a single function and no  return
value  is  necessary  for void  functions.  The
exit() function will leave the entire program.
There´s   no  main  program  in  C,   all   the
executable  code  is in functions.  Main  is  a
special  function which is run when the program
starts   up.  By  convention,  it   takes   two
parameters: argc, the argument count and  argv,
an  array  of string pointers for each  command
line argument passed to the program ending with
a  null  pointer.  These  can  be  obtained  in
MaxonBASIC via COMMAND$ function. Main  returns
an  int  which  is an error code  or  zero  for
success.
C  also allows functions with a variable number
of  arguments. This is denoted in  the  command
declaration by three dots. Suffice  it  to  say
that  subsequent  parameters are  accessed  via
pointers  and that no type checking is  carried
out.  The  most  used command of  this  ilk  is
printf()  detailed  towards  the  end  of  this
section.
If a C programmer decides that he or she is not
interested  in the return value of a  function,
they  can  call  it just as if it  was  a  void
function or procedure call. This is often  used
by  lazy  people who don´t check to see  if  an
error has occurred.


Macros

As  has  been  mentioned, C uses a preprocessor
which  can be used for simple text substitution
or defining constants. However, it does have  a
facility  for parameter substitution.  This  is
usually  used  for  short sequences  which  are
tedious to enter time and time again but  which
do   not  warrant  a  function  definition.  An
example of this might be


#define   RECSIZE(n)  (n  *  sizeof(Record)   +
sizeof(Header))


When   referred   to   via   RECSIZE(10),   the
preprocessor  will substitute  the  calculation
with  n equal to the value 10. In effect,  such
macros  are  mini functions and you  may  treat
them as such.
Advanced  macro programming is something  of  a
black  art with additional operators and  rules
applying.  However, in general if you implement
a macro as a BASIC function or procedure (as is
done  in  the MaxonBASIC Blib operating  system
files) you will get along fine.


Expressions


The  diversity  of operators  in  C  and  their
precedence is a source of great confusion, even
(or  especially, depending upon your  point  of
view) for C programmers. Let´s start off with a
list  of  all  the  operators and  their  BASIC
equivalents. The following table is  in  the  C
order  of precedence, i.e. the ones at the  top
are  done first. Don´t worry about the gaps  on
the BASIC side; we´ll come to that later.




  C operators         BASIC operators
  () [] -> .          () () PEEKL +
  ! ~ ++ -- + - * &   NOT INCR DECR PEEKL
                      VARPTR
  * / %               * / \ MOD
  + -                 + -
  << >>               << >>
  < <= > >=           < <= > >=
  == !=               = <>
  &                   AND
  ^                   XOR
  |                   OR
  &&
  ||
  ?:
  =  += -= *= /=  %=  = (not an operator)
  &= ^= |= <<= >>=
  ,

As you can see, many of these are simply a
matter of using different symbols. However,
there are some major differences. Taking it
from the top, -> means use the pointer before
this operator add on the offset for the field
afterwards and use this instead. So
The ++ and -- operators are a way of changing a
value by one. They correspond to the INCR and
DECR statements in BASIC but in C they are
operators and can be used in expressions. They
have the unusual property of returning a
different value depending upon the order. For
example, a++ gives the value of a before
incrementing it whereas ++a increments a and
then gives its value.
When combined with pointers, ++ and -- can be
used as follows:


 nextchar = *name_ptr++;
 sameagain = *--name_ptr;


These statements return a character via the
pointer, updating it to point to the next or
previous characters. This implements post-
increment and pre-decrement stacks.
Note that C has a single divide operator rather
than different ones for integers and floating
point.
The bitwise operators (&, |, ^) are identical
to AND, OR, XOR in BASIC but C also gives
logical operators. These guarantee a certain
sequence of execution which must be simulated
with nested IF statements in BASIC. Logical
´and´ (&&) says that the second part will only
be executed if the first part is non-zero.
Logical ´or´ (||) doesn´t bother with the right
hand expression if it has already found that
the first part is false.
The logical operators can be used to great
effect (in traditionally cryptic style) if
function calls form part of the expressions. In
the following example, no data will be written
if ReadData returned FALSE.


 if (ReadData(source, buffer) != FALSE &&
     WriteData(dest, buffer) != FALSE)
         printf(ÒOK\nÓ);


The entry shown as ?: in the table is in fact
two parts of a single construct sometimes known
as the tertiary operator. In fact, it is a
short circuit form of the ´if´ statement which
takes three parts; a condition, a true part and
a false part. To clarify, the statement


 value = (inputch < 10) ? inputch : 10;
is equivalent to the BASIC

 if inputch < 10 then value = inputch else
value = 10


It may surprise you to see = (assignment)
listed as an operator (remember, this is
different from the BASIC = which tests for
equality like == does in C). Equals is an
operator because it returns a value, the value
assigned. This means you can string them
together as in a = b = c = 99. You can even
start putting them inside expressions and
conditional expressions, e.g.


 if ((mem = malloc(100)) == NULL) panic();


which calls malloc with the number 100, assigns
the return value to the variable mem and tests
if equal to NULL. If used sensibly, this
practice can condense several lines of code but
taken to extremes it makes many complex
expressions difficult to read at a glance.
There are a number of flavours of the
assignment operator which add a number to a
variable and suchlike. In C you may say value
+= 10 rather than value = value + 10 or
inc(value,10).
Finally, the comma operator is used to separate
multiple expressions in much the same way as
the semicolon separates statements. In effect,
it returns the value of the rightmost
expression.


Control structures

Let´s start with the if statement in both
languages.


if (a < b)           if a < b then
 do_something();      do_something
else                 else
                      do_something_else
do_something_else(); end if

Note the parentheses round the if expression,
the lack of then and the extra semicolons.
Don´t go typing this into your BASIC program
because it will get confused!
A more complex if statement would use more than
one statement in each case (shown by more curly
brackets) and possible a number of ifs strung
together, as in


 if (opened)
 {
     LoadPicture(file, buffer);
     Display(picture);
     count += 1;
 }
 else if (error != NOT_FOUND)
     ErrorRequester();
 else
 {
     printf(ÒWhat picture?\nÓ);
     return 20;
 }


Very similar looping structures exist in both
BASIC and C. While loops are almost identical
to WHILEÉWEND loops (without the curly
brackets, course.
do..while loops can be translated into DO..LOOP
while such as


do
{                    DO
 c = getch(stream);   c = getch(stream)
 counter++;           INCR c
} while (c == ´ ´);  LOOP WHILE c = Ò Ò%

The break statement corresponds to EXIT LOOP
etc. where as the continue statement jumps to
the end of the loop and tests again.
The goto statement is just like in BASIC
although label names are always identifiers
rather than numbers.
One C control construct which you may find more
difficult to understand is the for loop. Whilst
the BASIC version is restricted to stepping
through a number range, the C version is much
more general. It can be used to step through
linked lists, maintain two counters etc. To
understand C for loops you must keep in mind
the general structure of the statement which
is:


 for (initialisation; condition; continuation)
     loop_body;


The initialisation part is always performed
before the loop begins, typically this is used
to set up start values. The loop body will be
executed while the condition expression is non-
zero. After the loop body, the continuation
statement is carried out. This usually updates
the loop counters. Any of these sections may be
missed out by simply specifying a semicolon.
This may become clear with the aid of a few
short examples. The C is first, followed by the
BASIC equivalent.


C:       for (n = 1; n < 10; n++)
BASIC:   FOR N = 1 TO 10



C:       for (a = 256; a; a -= 8)
BASIC:   FOR A = 256 TO 0 STEP -8



C:       for (node = &first; node; node =
node.next)
BASIC:     node& = VARPTR(first&)
     WHILE node&
         node& = PEEKL(node&+next_offset)
     WEND


For a more complex example (you will see much
worse):


for (ptr = &start, i = 0; i != 11; i += *ptr,
ptr++)


assuming ptr is pointing to 2 byte integers, is
equivalent to


 ptr& = VARPTR(start)
 i = 0

 WHILE i <> 11
     i = i + PEEKW(ptr&)
     ptr&=ptr&+2
 WEND


Enough of loops. One final control construct is
the select case statement. In C these look
like:


 select (action)
 {
     case 1:
         error = SaveFile(buffer);
         break;

     case 2:
         CloseBuffer(buffer);
         break;


     default:
         break;
 }


An important pitfall which you should watch out
for is that omitting the break statement at the
end of a case causes control flow to
unconditionally fall through to the next case.
This is often used in ´cunning´ ways by
advanced C programmers.


The standard C library

We will not attempt to describe the standard C
library although there are a few functions
singled out for special attention. The first of
these is printf().
Printf is to C what PRINT USING is to BASIC.
Most formatted output is performed via this
single command; there´s no equivalent to
ordinary PRINT. Rather than using # etc.,
printf() uses the percent character as a
special marker.
When printf() sees a percent sign, it then
picks up the next argument in the list and
applies formatting to it according to
additional characters following the percent
sign. It can be used to print strings and
numbers in various ways.


printf('Hello\n');         Hello
printf('Number = %d\n',    Number = 10
10);                       In hex: 2A...
printf('In hex: %X...',    Name: Bob,
42};                       Age: 67
printf('Name: %s, Age:
%d',
   &person, age);

Some other functions of note are the ´str´
family. These include strcpy (copy a string,
note that the destination comes first), strncpy
(length limited copy), strcmp (compare two
strings, returns zero if the same), stricmp
(case insensitive comparison) and strcat (add a
string to the end of another). There are many
more.
This concludes our introduction to reading C
programmers; we hope that this section helps
the examples in the ROM Kernel manuals and
other books seem less frightening!