GEOS Programmer's Reference Guide

Errors:

See appendix I.

Description:

A hole is opened up in the VLIR sector immediately following the current chain. The hole is filled with $00,$FF. This represents a null chain. This hole becomes the current chain.

Function Name:

BASIC

Purpose:

Restart BASIC with optional program load.

Call address:

$C241

Input requirements:

$02-$03: Pointer to 40 characters of text.
$0C-$0D: Pointer to file's directory entry.
$10-$11: Load address.

Preparatory routines:

LOOKUP

Description:

The 40 characters pointed to by $02-$03 are saved in a buffer. If $0C-$0D is non-zero, the file is loaded into memory at the address specified by $10-$11. BASIC is restarted with an interrupt vector. This interrupt is set up to give BASIC a chance to start up. After the time has elapsed, the 40 characters in the buffer are copied to the screen and a CR is placed in the keyboard buffer. The interrupt vector is then removed, but the NMI vector is set up to reboot GEOS. The reboot code is at $C000-$C037.

Function Name:

BLKCMP

Purpose:

Compares two blocks of memory for a fixed length.

Call address:

$C26E

Input requirements:

A: Byte count.
X: Address of zero page source pointer.
Y: Address of zero page destination pointer.

Output:

Z flag: Set accordingly.

Description:

The X and Y registers point to zero page pointers. A has the number of bytes to be compared (1-255). If A is zero, this routine will compare up to and including a zero byte. The Z flag is set accordingly. See STRCMP.

Function Name:

BLKFIL

Purpose:

Fills a memory region with a specified byte.

Call address:

$C17B

Input requirements:

$02-$03: The length of the region.
$04-$05: The address of the region.
$06: The byte to fill the region with.

Description:

A simple loop fills memory with the specified byte.

Function Name:

BLKFL2

Purpose:

Identical to BLKFIL, but with inline data.

Call address:

$C1B4

Description:

This routine takes the inline data and sets everything up before calling BLKFIL. For example:

JSR BLKFL2
.WORD Length of region
.WORD Address of region
.BYTE Byte to fill memory with
;Control returns here upon completion.

Function Name:

BLKMOV

Purpose:

Copy a block of memory.

Call address:

$C268

Input requirements:

A: Byte count.
X: Address of zero page source pointer.
Y: Address of zero page destination pointer.

Description:

The X and Y registers point to zero page pointers. A has the number of bytes to be transferred (1-255). If A is zero, this routine will copy up to and including a zero byte. See STRCPY.

Function Name:

BLKSET

Purpose:

Uses a table to set various memory locations in a uniform manner.

Call address:

$C181

Input requirements:

$02-$03: Address of a data table.

Description:

This routine allows many memory locations to be specified and set in an orderly manner. The format of the data table is as follows:

#Bytes	Description
2	Address to store values at.
1	# of values that follow.
?	Values to be stored at the designated memory region.
...	More definitions.
2	An address of $0000 ends the table.

Function Name:

CBOX

Purpose:

Draws a click box on the screen.

Call address:

$C142

Input requirements:

$02-$03: Pointer to the graphic data.
$04: Column in characters.
$05: The row in pixels.
$06: The width in bytes.
$07: The height in pixels.

Description:

This routine draws a click box on the screen. A click box is a box like Ok, Open, etc. These boxes are generally part of a window description. The graphic data is in a coded format. This format consists of a code byte followed by 1 or more data bytes.

Code bytes less than 128 mean that the following byte is to be repeated that many times.
Code bytes ranging from 128 to 219 mean that if 128 is subtracted from the code byte, then the result is the number of data bytes that follow.
Code bytes ranging from 220 to 225 are special. First 219 is subtracted from the code byte, the result is the number of bytes in the pattern. Following this code byte is a repetition count for the pattern. Following this are the bytes that constitute the pattern. These could include either of the previous two code types.

Function Name:

CBOX2

Purpose:

Identical to CBOX, but with inline data.

Call address:

$C1AB

Description:

This routine takes a click box descriptor from inline data and draws it. The inline data does NOT include the processing vector, ie.

JSR CBOX2
.WORD address of graphic image
.BYTE start column in bytes
.BYTE start margin in pixels
.BYTE width of box in bytes
.BYTE height of box in pixels
; Control returns here after the box is drawn.

Function Name:

CBOXES

Purpose:

Draws all of the click boxes in a table.

Call address:

$C15A

Input requirements:

$02-$03: Pointer to a click box table (Usually $880C).

Preparatory routines:

WINDOW (optional).

Description:

This routine draws all of the click boxes by calling CBOX repeatedly until the table is exhausted. The INITMS is called to set the mouse's position. Click table format:

#Bytes	Description
1	# click boxes in table.
2	Column to place mouse in (0 will prevent placement).
1	Row to place mouse in.

This is followed by sets of 8 bytes, one for each click box:

#Bytes	Description
2	Address of graphic data.
1	Column position of box in characters.
1	Row position of box in pixels.
1	Width of box in bytes.
1	Height of box in pixels.
2	Address of routine to process this box.

Function Name:

CHARST

Purpose:

Get statistics for a character.

Call address:

$C1B1

Input requirements:

A: The character.

Output:

A: The position of the underline.
Y: The character's width.
X: The character's height.

Description:

Given the ASCII value of a character, this routine computes and returns the height and width, taking the style into account. The # pixels above the underline for the present font is also returned.

Function Name:

CHGDRV

Purpose:

Change the device number of a drive.

Call address:

$C2BC

Input requirements:

A: New device number for drive.
$8489: Current drive number.

Output:

$BA: New device number.
$8489: New device number.
$8492-$8495: Appropriate bytes are reset and set.

Errors:

See appendix I.

Description:

The current drive is made ready, then the new device number is sent to Turbodos which will change it. This results in the drive being set as the current drive but with a new device number, and with Turbodos up and running. The status bytes at $8492-$8495 are changed, the old one is reset and the new one has bits 6 and 7 set.

Function Name:

CKMOUS

Purpose:

Check if the mouse is in a box.

Call address:

$C2B3

Input requirements:

$06: Top margin.
$07: Bottom margin.
$08-$09: Left margin.
$0A-$0B: Right margin.

Output:

A: $00 - outside box, $FF - inside box.

Description:

This routine simply compares the present mouse location stored at locations $3A-$3C against the box's boundaries. A is set to $00 if the mouse is outside, $FF if it is inside.

Function Name:

CLRRDY

Purpose:

Turn off Turbodos.

Call address:

$C232

Input requirements:

$8489: Current drive number.

Description:

Turbodos is terminated in the current drive.

Function Name:

CLRSTS

Purpose:

Clear the drive ready status.

Call address:

$C235

Input requirements:

$8489: Current drive number.

Output:

Appropriate status byte is reset.

Description:

This routine terminates Turbodos in the current drive, and resets the drive status byte at $8492-$8495.

Function Name:: CLSMNU
Purpose:: Backs up a menu level.
Call address:: $C190
Description:: This routine erases the present menu, and pops back one level.

Function Name:: CLSSER
Purpose:: Close off serial communication.
Call address:: $C25F
Errors:: See appendix I.
Description:: This routine resets the I/O ports after serial communication is complete. This routine is called after calls to READ2, WRITE2 or CWRITE.

Function Name:

CLSWIN

Purpose:

Close a window.

Call address:

$C2BF

Output:

$02: Command byte from window processor.
$851D: Command byte from window processor.

Description:

The window is erased and the memory addresses that the window processor saved are restored. Control returns to the caller of WINDOW.

Function Name:

Purpose:

Sets up a table of recurring timed events.

Call address:

$C103

Input requirements:

A: The number of entries in the table.
$02-$03: A pointer to the table of counters and routine addresses.

Description:

This routine copies a table of subroutine addresses and counter values into GEOS's tables at $872D and $8755. The counters will be decremented on each call to IRQRTN. When they reach zero, they are reset and the associated routine is called by the GEOS main loop. The command bytes are initially set to disable the counters. Several calls to ENABLE are needed to start the counters running, one for each entry in the table. The table consists of pairs of words. The first is the address of the subroutine to be executed each time the counter reaches zero and the second is the counter value. This appears to be the rudiments of multitasking GEOS. The table of command bytes at $8719 are bit oriented and operate according to the following table:

Bit 7: Timer reached zero, call the subroutine.
Bit 6: Disable the execution of the routine. This does NOT affect the counter.
Bit 5: Initially set by CMDTBL, causes the counter to stop running.
Bit 4: Though not referenced anywhere in the GEOS Kernal, this bit also stops the counter. This bit is NOT touched by any of the GEOS routines, including ENABLE.

Function Name:: CMENUS
Purpose:: Closes all menu levels.
Call address:: $C1BD
Preparatory routines:: MENU
Description:: This routine is not the same ERAMNS. The menus are cleared one at a time and the previous levels are reprocessed in reverse order until all menus are closed.

Function Name:: CONVRT
Purpose:: Converts a disk to GEOS format.
Call address:: $C1EA
Errors:: See appendix
Description:: This routine modifies the directory header to include the GEOS format message. It also allocates a sector to be used for the border from DESKTOP.

Function Name:

COPYB

Purpose:

Copies a box from screen 2 to screen 1.

Call address:

$C12D

Input requirements:

$06: The top margin.
$07: The bottom margin.
$08-$09: The left margin.
$0A-$0B: The right margin.

Description:

This routine copies a box from screen 2 ($6000) to screen 1 ($A000). Location $2F is unaffected. This routine calls COPYL repeatedly to copy each line of the box.

Function Name:: COPYB2
Purpose:: Identical to COPYB, but with inline data.
Call address:: $C1A5
Description:: This routine copies a box from screen 2 ($6000) to screen 1 ($A000). The box descriptor is inline with the calling code. See PFILL2 for an example.

Function Name:

COPYB3

Purpose:

Copies a box from screen 2 to screen 1.

Call address:

$C250

Input requirements:

$06: The top margin.
$07: The bottom margin.
$08-$09: The left margin.
$0A-$0B: The right margin.

Description:

This routine copies a box from screen 1 ($A000) to screen 2 ($6000). Location $2F is unaffected. This routine calls COPYL repeatedly to copy each line of the box.

Function Name:: COPYB4
Purpose:: Identical to COPYB3, but with inline data.
Call address:: $C253
Description:: This routine copies a box from screen 1 ($A000) to screen 2 ($6000). The box descriptor is inline with the calling code. See PFILL2 for an example.

Function Name:

COPYL

Purpose:

Copies a horizontal line from screen 2 to screen 1.

Call address:

$C11E

Input requirements:

$08-$09: The left margin.
$0A-$0B: The right margin.
$18: The row number.

Description:

This routine copies a horizontal line from screen 2 ($6000) to screen 1 ($A000). Location $2F is unaffected.

Function Name:

COPYSP

Purpose:

Copies a sprite into GEOS's storage area.

Call address:

$C1C6

Input requirements:

$08: The sprite number (0-7).
$0A-$0B: Pointer to the sprite data.

Description:

This routine simply copies 63 bytes of data pointed to by $0A-$0B to the specified sprite block. GEOS uses sprite blocks 40 to 47.

Function Name:

CURSOF

Purpose:

Turn off text cursor.

Call address:

$C29E

Output:

$84B4: Bit 6 is cleared.

Preparatory routines:

CURSON

Description:

Sprite 1 (GEOS's text cursor) is turned off, bit 6 of location $84B4 is reset. The blink rate is set to 60 (once per second).

Function Name:

CURSON

Purpose:

Turn on text cursor.

Call address:

$C29B

Input requirements:

$84BE-$84BF: Column to place cursor in.
$84C0: Row to place cursor on.

Output:

$84B4: Bit 6 is set.

Description:

Turns on sprite 1 and positions it. It also sets bit 6 of location $84B4. The blink rate is set to 60, once per second. Sprite 1 is the text cursor for GEOS.

Function Name:

CWIDTH

Purpose:

Returns the width of a character.

Call address:

$C1C9

Input requirements:

A: The ASCII value of the character.

Output:

A: The width of the character.

Description:

This routine simply takes the difference of the bit stream indices to get the characters width. The delete character has its width loaded from $8807. This routine is called by CHARST.

Function Name:

CWRITE

Purpose:

Conditionally write a sector to disk.

Call address:

$C223

Input requirements:

$04: Track number.
$05: Sector number.
$0A-$0B: Pointer to data buffer.

Preparatory routines:

Errors:

See appendix I.

Description:

The first thing this routine does is try to read the desired sector. If the read succeeds, nothing happens. Three attempts are made at the read. After these read attempts, the sector is written to the disk, by calling WRITE2. If the write succeeded without any errors, then the routine restarts itself. It will make five attempts at this loop. If after five attempts, the sector can not be read reliably, an error 39 results. This routine is usually called after the sector has been written out with a call to WRITE2. WRITE calls this routine to verify the sector.

Function Name:

DEC16

Purpose:

Decrements a 16 bit value.

Call address:

$C175

Input requirements:

X: The address of the 16 bit integer.

Output:

X: The address of the 16 bit result.

Description:

This routine is one of the GEOS math routines. X points to a 16 bit value which is decremented by 1.

Function Name:

DECODE

Purpose:

Compute a checksum for a data region.

Call address:

$C20E

Input requirements:

$02-$03: Pointer to data region.
$04-$05: Length of region.

Output:

$06-$07: Checksum of region.

Description:

This routine is called by the boot-up routines to compute the checksum of GEOS BOOT. This checksum is used to create the interrupt vector address. The reason for this was to prevent piracy. This can be used to check the integrity of a memory region. This is actually more of a CRC computation then a checksum and the formula is a little too complex to explain here.

Function Name:

DELAY

Purpose:

Sets up a time delay.

Call address:

$C199

Input requirements:

$02-$03: Amount of time delay value in 60ths of a second.

Description:

The counter is saved on a stack, as well as the return address of the caller. Control is passed back a level higher than the caller. When the timer runs out, control will return where it left off. This allows programs to incorporate delays without halting GEOS's many independent processes. This and CMDTBL appear to be the beginnings of multitasking for GEOS.

Function Name:

DELET2

Purpose:

Delete a temporary file.

Call address:

$C244

Input requirements:

$08-$09: Pointer to table of tracks and sectors.
$0E-$0F: Pointer to file name.

Errors:

See appendix I.

Description:

This routine removes the file from the directory. It uses the table of tracks and sectors to free up the sectors used by the file. This routine is used to clean up a temporary file that was not completed.

Function Name:

DELETE

Purpose:

Delete a file from the disk.

Call address:

$C238

Input requirements:

$02-$03: Pointer to file name.

Errors:

See appendix I.

Description:

The specified file is deleted from the current drive.

Function Name:

DIRDSK

Purpose:

Creates a directory entry on the disk.

Call address:

$C1F0

Input requirements:

$14-$15: $8100, required.
$16: # of directory sectors to skip first.
$8100-$81FF: Information sector for file.
$8300-: Track and sector list for file.

Output:

$8400-$841D: Directory entry (written to the disk).

Preparatory routines:

Errors:

See appendix

Description:

This routine is used by SAVE and calls DIRMEM. Because of this, assumptions are made. The first is that the information sector is at $8100-$81FF and that $14-$15 point there. The first two bytes of the information sector are the address of the filename. These are reset by this routine to $00, $FF. Another assumption made by this routine is that $8300 is a list of usable tracks and sectors; specifically, $8300-$8301 are the track and sector for the information sector and $8302-$8303 are the track and sector of the first sector of the file.

Function Name:

DIRMEM

Purpose:

Create a directory entry in memory.

Call address:

$C1F3

Input requirements:

$14-$15: $8100, required.
$8100-$81FF: Information sector for file.
$8300-: Track and sector list for file.

Outputs:

$8400-$841D: Directory entry.

Preparatory routines:

Errors:

See appendix

Description:

See DIRDSK for a complete list of all the assumptions made by this routine.

Function Name:

DRAW

Purpose:

Draw a section of a coded graphic image.

Call address:

$C2AA

Input requirements:

$02-$03: Pointer to graphic image data.
$04: Column to start on, in bytes.
$05: Row to start drawing the image on.
$06: Image width in bytes.
$07: Image height in pixels
$18: # bytes to skip on the left side.
$19: # bytes on the right side.
$1A-$1B: # rows to skip down.

Description:

The coding of the image is the same as that of the click boxes, see CBOX for more information. This routine seems to be for drawing pieces of Photo Scraps. Photo Scraps have this coded format. The parameters for this routine allow a section of the image to be drawn by specifying how many rows to skip down,as well as how many bytes to skip on the left and the right of the desired section. This is not used by GEOpaint unless GEOpaint converts its files because they are in a different format; however, Photo Scraps are in this format.

Function Name:

DRAW2

Purpose:

Draw a section of a coded graphic image.

Call address:

$C2C5

Input requirements:

$02-$03: Pointer to graphic image data.
$04: Column to start on, in bytes.
$05: Row to start drawing the image on.
$06: Image width in bytes.
$07: Image height in pixels
$18: # bytes to skip on the left side.
$19: # bytes on the right side.
$1A-$1B: # rows to skip down.
$1C-$1D: First user vector.
$1E-$1F: Second user vector.

Description:

This routine is identical to DRAW, except that before each byte is read, the first user routine is called. The second user routine is called before reading each byte that is not part of a pattern (Command bytes greater than 219). These user routines might be for disk reading, in order to draw an image that is not memory resident.

Function Name:

DRAWCH

Purpose:

Draws a character.

Call address:

$C202

Input requirements:

A: The ASCII value of the character.
$05: Row to print on (1 above the underline).
$18-$19: Column to print in.
$33: The top margin (Usually 0).
$34: The bottom margin (Usually 199).

Description:

This routine is not exactly the same as DSPCHR. This routine does not process control characters at all. It also does not check left and right margins at all. It only checks top and bottom margins so that it stays on screen.

Function Name:

DRVNAM

Purpose:

Compute the address of the disk's name.

Call address:

$C298

Input requirements:

X: Address to place pointer in.
$8489: Current drive number.

Output:

Location in zero page pointed to by X has the address of the current drive's name.

Preparatory routines:

OPNDSK

Description:

This routine computes the address of the current drive's name by multiplying the drive number (minus 8) by 18, then the offset of $841E is added to that. The result of the computation is stored at the zero page address in X.

Function Name:

DRVSET

Purpose:

Set current drive.

Call address:

$C2B0

Input requirements:

A: Device number of drive (8-11).

Output:

$BA: Set to new device number.
$8489: Set to new drive number.

Description:

If the drive being specified is not the current drive then CLRRDY is called to clear the current drive. Then locations $BA and $8489 are set to the new drive number. No other locations are affected, nor is anything actually done with the drive.

Function Name:: DRWMNU
Purpose:: Redraws the present menu.
Call address:: $C193
Description:: This routine redraws the current menu.

Function Name:

Purpose:

Sets up a drive with Turbodos.

Call address:

$C214

Input requirements:

$8489: Current drive number.

Errors:

See Appendix I.

Description:

This routine initializes the current drive, sending Turbodos if necessary. It then causes the drive to run Turbodos. This routine is called by several of the disk I/O routines, most notably are READ and WRITE. Upon initializing the drive, the drive's status byte is set to the appropriate value. The status bytes are stored at $8492-$8495 and have the following bit definitions:

Bit 7: Turbodos is loaded.
Bit 6: Turbodos is running.

Function Name:

DSPCHR

Purpose:

Displays a character on the screen.

Call address:

$C145

Input requirements:

A: The character to be printed.
$02-$03: Pointer to extra data (Used by a few control characters, not needed otherwise).
$05: The row for printing (1 above the underline).
$18-$19: The column to start printing.
$33: The top margin (Usually 0).
$34: The bottom margin (Usually 199).
$35-$36: The left margin.
$37-$38: The right margin.

Preparatory routines:

SELBSW or FONT

Errors:

Branches through $84AB-$84AC if right margin is exceeded.

Description:

This routine displays a character in a given location in the current font and style. The style byte in location $2E is coded as follows:

Bit 7: Underline
Bit 6: Boldface
Bit 5: Reversed video
Bit 4: Italics
Bit 3: Outline

Either SELBSW or FONT must be called prior to using this routine, in order to set up the font pointers. SELBSW is called during GEOS's boot-up procedure, as well as by the menu processor. Several control characters have special properties. Those which require a data pointer are marked with an asterisk in the following table:

Ctrl-H: Delete previous character.
Ctrl-I: Tab.
Ctrl-J: Move straight down a line.
Ctrl-K: Set text cursor to 0,0.
Ctrl-L: Move straight up a line.
Ctrl-M: Move to the beginning of the next line.
Ctrl-N: Turn on underlining.
Ctrl-O: Turn off underlining.
Ctrl-P *: Followed by a table suitable for GRPHIC.
Ctrl-R: Turn on reverse video.
Ctrl-S: Turn off reverse video.
Ctrl-T *: Followed by 2 bytes which specify the new column.
Ctrl-U *: Followed by a byte which specifies the new row.
Ctrl-V *: Followed by 3 bytes which specify the new print position.
Ctrl-W *: Skips the next 3 bytes.
Ctrl-X: Turn on Boldface.
Ctrl-Y: Turn on Italics.
Ctrl-Z: Turn on Outline.
Ctrl-: Turn off all effects, return to plain text.

Those entries marked with an asterisk (*) should only be used from DSPTXT because they require $02-$03 to be a pointer to get extra data. As with GRPHIC, Ctrl-P must be the last command because the zero byte that terminates GRPHIC will terminate DSPTXT.

Function Name:

DSPNUM

Purpose:

Display an unsigned 16 bit integer.

Call address:

$C184

Input requirements:

A: Control value (See description).
$02-$03: The value to be displayed.

Description:

This routine converts the value at $02-$03 to decimal ASCII and displays it using DSPCHR. The control value in A is defined as follows:

Bit 7

0: right justify the number.
1: left justify the number, ie. no justify.

Bit 6

0: print leading zeroes.
1: skip leading zeroes.

Bits 0-5

The field width in pixels for right justification.

Function Name:

DSPTX2

Purpose:

Identical to DSPTXT, but with inline code.

Call address:

$C1AE

Input requirements:

$35-$36: The left margin.
$37-$38: The right margin.

Preparatory routines:

SELBSW or FONT

Errors:

Branches through $84AB-$84AC if right margin is exceeded.

Description:

This routine creates a pointer to the text, calls DSPTXT, then returns to the code immediately following the text.

JSR DSPTX2
.WORD The column to start printing in
.BYTE Row for line of print (1 above the underline)
.BYTE Text to be displayed
.BYTE 0
; Control returns here after text is printed.

Function Name:

DSPTXT

Purpose:

Displays an entire string of text.

Call address:

$C148

Input requirements:

$02-$03: Pointer to text string.
$05: The row for printing (1 above the underline).
$18-$19: The column in which to start printing.
$33: The top margin (Usually 0).
$34: The bottom margin (Usually 199).
$35-$36: The left margin.
$37-$38: The right margin.

Preparatory routines:

SELBSW or FONT

Errors:

Branches through $84AB-$84AC if right margin is exceeded.

Description:

This routine calls DSPCHR to display each character in a string. The string is terminated by a zero byte.

Function Name:

ENABLE

Purpose:

Enables a recurring timed event.

Call address:

$C106

Input requirements:

X: The index into the command table at $8719.

Preparatory routines:

Description:

This routine enables a specific timer in the table at $8719 by resetting bits 5 and 6 in the command table. It also copies the initial value into the timer table at $87F1. The command table must have been previously set up by a call to CMDTBL.

Function Name:: ERAMNS
Purpose:: Erases all open menus.
Call address:: $C157
Preparatory routines:: MENU
Description:: This routine erases all of the menus. It calls ERAMNU repeatedly to accomplish this. It then sets the menu level counter ($84B7) to $00.

Function Name:: ERAMNU
Purpose:: Erases the current menu from the screen.
Call address:: $C154
Preparatory routines:: MENU
Description:: This routine will erase the current menu. It does NOT pop up a level. It simply erases it from the screen. If the vector at $84B1 was set, then that is the routine called to erase the menu; otherwise, a blank pattern is selected with SETPAT and PFILL is called. The default setting for $84B1 is COPYB.

Function Name:

EXERTN

Purpose:

Forces a timed event to execute,regardless of its timer.

Call address:

$C109

Input requirements:

X: The index into the command byte table at $8719.

Preparatory routines:

Description:

This routine sets bit 7 of a specific command byte in the table at $8719. This simulates the timer having run out.

Function Name:

Purpose:

Allocate enough sectors for a file.

Call address:

$C1FC

Input requirements:

$06-$07: Number of bytes to be saved.
$0A-$0B: Address of buffer for track and sector list.

Output:

Buffer is filled with a set of tracks and sectors.

Errors:

See Appendix

Description:

Given a byte count and a pointer to a buffer, this routine attempts to allocate enough sectors. This routine is called prior to saving a file. The track and sector list is not limited in length, available disk space not withstanding. The list is terminated with a track number of zero and the appropriate byte count in the sector location. Note if an error occurs during the allocation, the sectors already allocated are not freed up. Either this must be done or the disk must be validated.

Function Name:

FALOC2

Purpose:

Allocate enough sectors for a file.

Call address:

$C24D

Input requirements:

$06-$07: Number of bytes to be saved.
$08: Track to start looking from.
$09: Sector to start looking from.
$0A-$0B: Address of buffer for track and sector list.

Output:

Buffer is filled with a set of tracks and sectors.

Errors:

See Appendix

Description:

This routine is almost identical to FALLOC. As a matter of fact, FALLOC falls into this routine after setting $08-$09 to point to track 1 sector 0. This routine allows the user to specify where on the disk to start looking for free sectors, possibly speeding things up.

Function Name:

FONT

Purpose:

Change the current font.

Call address:

$C1CC

Input requirements:

$02-$03: Pointer to font header in memory.

Output:

$26: # pixels above line of print.
$27-$28: The number of bytes in the bit stream.
$29: The point size.
$2A-$2B: Pointer to the table of the bit stream indices.
$2C-$2D: Pointer to the bit stream.

Description:

This routine simply copies the header block from the font to zero page. This makes the font the current font for all character output. (See DSPCHR, DSPTXT and DSPTX2).

Function Name:

FORBID

Purpose:

Disables the execution of a timed event.

Call address:

$C10C

Input requirements:

X: The index into the command table at $8719.

Preparatory routines:

Description:

This routine sets bit 6 of a specific command byte in the table at $8719. This prevents the associated routine from executing, regardless of its timer. This does NOT stop the timer from running. If the timer runs out while the routine is disabled, when the timer is reenabled, the associated routine will be executed. This routine is the complement to PERMIT.

Function Name:

FREE

Purpose:

Deallocates all of a file's sectors.

Call address:

$C226

Input requirements:

$14-$15: Pointer to directory entry.

Preparatory routines:

LOOKUP (Pointer must be copied).

Errors:

See Appendix I.

Description:

Given the directory entry of a file, all of its sectors are returned to the free pool. The directory pointer should be pointing to the directory entry at $8400 and not the pointer returned by LOOKUP. This is due to memory conflicts that will arise. This routine uses $8000-$82FF for its buffer areas.

Function Name:

GEOSCK

Purpose:

Checks if a disk is GEOS format or not.

Call address:

$C1DE

Input requirements:

$0C-$0D: Pointer to buffer with track 18 sector 0.

Output:

Z: Set if non-GEOS, reset if GEOS format.
A,$848B: $00 if non-GEOS, $FF if GEOS format.

Description:

This routine expects that track 18 sector 0 has already been read. It compares 11 bytes, starting with the 173rd, against 'GEOS format'. It sets $848B so that the current drive is kept track of.

Function Name:

GETBYT

Purpose:

Read a byte from a file.

Call address:

$C2B6

Input requirements:

$0C: Index of last byte in buffer.
$0D: Index to next character in buffer.
$0A-$0B: Pointer to disk buffer.

Output:

A: Character that was read.

Errors:

See Appendix I.

Description:

The initial sector must have been read because the first two bytes in the buffer are used to find the next track and sector. Bytes are read from the buffer until there are no more, then the next sector is read from the disk. This can continue until the last character of the last sector is read. After this an error 11 (End of file) will be returned.

Function Name:

GETIN

Purpose:

Get a key from the keyboard.

Call address:

$C2A7

Output:

A: Character or $00 if there are none.

Description:

This routine takes a key from the keyboard buffer, if there is one. If there are no characters in the buffer, then a zero is returned.

Function Name:

GOTO

Purpose:

Get a specific VLIR chain.

Call address:

$C280

Input requirements:

A: VLIR chain number.

Output:

Y: Track of VLIR chain.
$04: Track of VLIR chain.
$05: Sector of VLIR chain.
$8496: Set to A.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine gets the track and sector of a specific chain in the open VLIR file. It does not check to see if the chain exists (ie. track is zero). It does check if this chain is greater than zero and less than the number of VLIR chains (Location $8497). VLIR chains are numbered from 0 to N-1, where N is the number of chains.

Function Name:: GRPHC2
Purpose:: Identical to GRPHIC, but with inline data.
Call address:: $C1A8
Description:: This routine takes an inline data table, creates a pointer to it, then calls GRPHIC to process it. See PFILL2 for an example of inline data tables.

Function Name:

GRPHIC

Purpose:

Process several graphics commands designated by a table.

Call address:

$C136

Input requirements:

$02-$03: Pointer to the table of commands.

Description:

This routine executes the graphic commands present in a table. This routine is used by DSPCHR (Control-P), DSPTXT (By calling DSPCHR), and WINDOW (Command 15). The following table describes the available commands:

Graphic Command Table
Command	#Bytes	Description
0	1	Stop, end of table.
1	4	Set column and row variables.
2	4	Draw a line.
3	4	Pattern fill a region.
4	1	No operation.
5	2	Set fill pattern.
6	4+	Set position and display text. MUST BE last command because the zero byte that ends the text also ends this command table.
7	4	Draw a solid lined box.
8	3	Add an offset to column variable.
9	2	Add an offset to row variable.
10	4	Add offsets to both column and row variables.

Command 1 is used to set the column and row variables used by all of the other commands which require two points. The format of the commands is that all of the necessary data follows the command byte. For example, the commands to erase the entire screen would look like this:

.BYTE $05,$00
.BYTE $01
.WORD 0
.BYTE 0
.BYTE $03
.WORD 320
.BYTE 199
.BYTE $00

In the case of command 6, after the column and row bytes in the command comes the text that is to be displayed. For example:

.BYTE $06
.WORD 50
.BYTE 50
.BYTE 'Hello world!'
.BYTE $00

Function Name:

HLINE

Purpose:

Draws a horizontal line on the screen.

Call address:

$C118

Input requirements:

A: The actual bit pattern for the line.
$08-$09: The left margin.
$0A-$0B: The right margin.
$18: The row number.

Description:

This routine draws a horizontal line on the hires screen in a given pattern. See also ROWADR.

Function Name:

HOLE

Purpose:

Find a hole in the directory, or make one.

Call address:

$C1F6

Output:

Y: Index of hole in buffer.
$04: Directory track number (Should be 18).
$05: Directory sector number.
$16: # directory sectors to skip first.
$8000-$80FF: Buffer for directory sector.

Description:

This routine scans the disk's directory looking for a deleted file, by first skipping a certain number of sectors. This allows the user to find a hole in a given directory page. If one is not found in any of the available directory sectors, then a new sector is added to the directory.

Function Name:

INDJMP

Purpose:

Conditional jump.

Call address:

$C1D8

Input requirements:

A: The high byte of the jump vector.
X: The low byte of the jump vector.

Description:

If A and X are zero, the jump is not performed. If A and X are nonzero, the jump is performed.

Function Name:: INIT01
Purpose:: Part of GEOS's boot-up process.
Call address:: $C271
Description:: Initializes the VIC chip and the I/O chips. Some global memory is also initialized. It also resets the preferences and all the drives. The default drive is reset by a call to DSETUP.

Function Name:

INITDV

Purpose:

Initializes a drive.

Call address:

$C1E1

Input requirements:

$04: Track to position the disk drive head at.
$05: Sector to position the disk drive head at.

Errors:

See Appendix

Description:

Makes sure that current drive has Turbodos running. It also positions the head over a particular sector.

Function Name:

INITMS

Purpose:

Initializes the mouse.

Call address:

$C14E

Input requirements:

C: flag Clear if the mouse position should not be set.
C: flag Set if the mouse position should be set.
Y: The row position for the mouse (optional).
$18-$19: The column position for the mouse (optional).

Description:

This routine turns on the mouse and positions it if desired. If the column is set to 0, the mouse is not positioned even is the C flag is set. It also sets up the button pressed vector $84A1-$84A2 and the close menu vector $84A7-$84A8. It also clears the flag at $84B6. This routine does not actually turn on the mouse. It calls MOUSON to reset bit 7 of location $30; this will cause GEOS's interrupt routines to turn on the mouse.

Function Name:

INPUT

Purpose:

Input a line of text from the user.

Call address:

$C1BA

Input requirements:

$02-$03: Address of text and buffer.
$04: Flag byte ($87D3).
$05: Row to print text on (1 above the underline).
$06: Maximum length of input.
$0A-$0B: Vector for user routine for right margin exceeded (optional).
$18-$19: Column to start printing text at.
$84A3-$84A4: Address for CR entered.

Output:

$24-$25: Pointer to text buffer (copied from $02-$03). Buffer will be modified according to the user's input.
$84A3-$84A4: Cleared to $0000.

Description:

This routine is rather powerful. It displays a line of text, if there was any text to display. Then the text cursor is turned on. Several of the jump vectors are used. $84AB-$84AC is the vector for the right margin being exceeded. $84A9-$84AA is the vector for a character being typed. $84A3-$84A4 is the vector for CR entered. After everything is set up, control returns to the caller; however, the input is handled by the interrupt drivers. When a CR is entered, control goes through the vector at $84A3-$84A4. The flag byte at location $04 is copied to $87D3 and has the following property: If bit 7 is set, then use the user's routine whose address is stored at locations $0A-$0B for the right margin is exceeded routine.

Function Name:

INSERT

Purpose:

Insert a new chain in a VLIR file.

Call address:

$C286

Input requirements:

$8496: Current chain number.

Output:

$8497: Incremented by 1.

Preparatory routines:

Errors:

See Appendix I.

Description:

A hole is opened up in the VLIR sector starting with the current chain. The hole is filled with $00,$FF. This represents a null chain.

Function Name:

INTBM

Purpose:

Intelligent block move.

Call address:

$C17E

Input requirements:

$02-$03: The source address.
$04-$05: The destination address.
$06-$07: The length of the region to be moved.

Description:

This routine will perform an intelligent, ie. non-conflicting, block move of memory. If an attempt is made to move a block of memory to a destination that is within the block, the transfer is done from back to front so as to prevent the conflict, or 'ripple effect'.

Function Name:

INTBM2

Purpose:

Identical to INTBM, but with inline data.

Call address:

$C1B7

Description:

This routine uses the inline data to set everything up before calling INTBM. For example:

 JSR INTBM2
.WORD Source address
.WORD Destination address
.WORD Length of transfer
;Control returns here upon completion.

Function Name:

INUSE

Purpose:

Check if a disk sector is in use.

Call address:

$C2AD

Input requirements:

$0E: Track to be checked.
$0F: Sector to be checked.
$8200-$82FF: Track 18 sector 0, BAM buffer.

Output:

X: Index into BAM of the appropriate byte.
Z flag: Set if the sector is in use.
$11: Index to track's data in BAM.
$13: Bit mask for the desired sector.

Preparatory routines:

RD180

Description:

This routine is used by ALLOC to test if a sector is already in use.

Function Name:

INVBOX

Purpose:

Inverts the pixels in a box.

Call address:

$C12A

Input requirements:

$06: The top margin.
$07: The bottom margin.
$08-$09: The left margin.
$0A-$0B: The right margin.

Description:

This routine reverses the pixels in a given box by repeatedly calling INVLIN. See also ROWADR.

Function Name:

INVLIN

Purpose:

Inverts a horizontal line on the screen.

Call address:

$C11B

Input requirements:

$08-$09: The left margin.
$0A-$0B: The right margin.
$18: The row number.

Description:

This routine reverses the pixels on a horizontal line on the hires screen. If the pixel was on it will now be off; if it was off it will now be turned on. See also ROWADR.

Function Name:: IRQRTN
Purpose:: Handles several items that occur at regular timed intervals.
Call address:: $C100
Description:: GEOS sets up the raster interrupt on the VIC chip to cause an interrupt every sixtieth of a second. This routine is called by GEOS after each interrupt. First it reads the input device and updates the mouse's position, turning it on if necessary. It then scans the command table at $8719 to see if any of the command bytes have both bits 4 and 5 reset. If so, it then decrements the associated counter at $86F1. If the counter reaches zero, its value is reset and bit 7 of the associated command byte is set. This will cause the appropriate subroutine to be executed the next time the table is polled. The next part of this routine is to decrement all nonzero counters in the stack at $877F. The routine to blink the text cursor is called next. Finally, the random number generator at $850A is updated.

Function Name:

LCHAIN

Purpose:

Load memory from disk.

Call address:

$C1FF

Input requirements:

$04: Initial track number.
$05: Initial sector number.
$06-$07: Byte count of load.
$10-$11: Load address.

Output:

$0C: Index to last sector loaded.
$8300-: List of tracks and sectors track were loaded.

Preparatory routines:

LOADAD

Errors:

See Appendix I.

Description:

This routine assumes that the file has been located in the directory and that the initial track and sector are known.

Function Name:: LDSWAP
Purpose:: Reload the SWAPFILE.
Call address:: $C23E
Preparatory routines:: LOADSW
Errors:: See Appendix I.
Description:: This routine reloads the SWAPFILE, then deletes it. The last window description is reprocessed to restore the screen and control is returned to the original program that called LOADSW.

Function Name:

LINE

Purpose:

Draws, erases or copies a line on the hires screen.

Call address:

$C130

Input requirements:

N Flag	C Flag	Operation
1	X	Copy
0	1	Draw
0	0	Erase

$08-$09: The column for the first endpoint.
$0A-$0B: The column for the second endpoint.
$18: The row for the first endpoint.
$19: The row for the second endpoint.

Description:

This is a very versatile routine. It can copy an arbitrary line from one screen to another, as well as draw or erase lines. This routine places no restrictions on the relative positions of the endpoints. This routine calls PLOT to plot the points. See also ROWADR.

Function Name:

LOAD

Purpose:

Load and run a file.

Call address:

$C208

Input requirements:

$02: Flag byte (See description).
$06-$07: Optional data pointer.
$08-$09: Optional data pointer.
$0E-$0F: Pointer to filename.
$10-$11: Load address (optional).

Output:

$8100-$81FF: Info sector for file.
$8300-$83FF: Table of tracks and sectors that were loaded.

Errors:

See Appendix

Description:

This routine loads and runs a given file. The file must be one of the following GEOS types:

4: System file
5: Desk Accessory
6: Application
7: Application Data
9: Printer driver
10: Input driver

The execution address is taken from the information sector. If it is zero, the file is not executed, only loaded. VLIR files have only their first chain loaded. Desk Accessories swap out the memory that they use to the SWAPFILE. Upon completion, the SWAPFILE is reloaded. The flag byte at location $02 has two purposes. This first is if bit 0 is set and the file was an application, then it is not executed. Also if bit 0 is set, then locations $10-$11 have the load address; otherwise, the load address is taken from the information sector. This bit does not apply to Desk Accessories. If either bit 6 or 7 are set, then $06-$07 points to 16 bytes which are copied to $8453 (Disk name for drive 10), and $07-$08 point to 16 bytes which are copied to $8442 (Disk name for drive 11).

Function Name:

LOAD2

Purpose:

Load a file.

Call address:

$C211

Input requirements:

$14-$15: Pointer to directory entry.
$886B: Flag byte.
$886C-$886D: Load address.

Output:

$8100-$81FF: Info sector for file.
$8300-$83FF: Table of tracks and sectors that were loaded.

Preparatory routines:

LOOKUP (Pointer must be copied)

Errors:

See Appendix

Description:

This routine is called by LOAD to perform the load. This routine does not try to execute the file loaded, nor is it limited to the file types that LOAD is. However, this routine can not be used to load Non-GEOS files because the info sector must be present. If bit 0 of location $886B is set, then the load address is taken from locations $886C-$886D instead of the info sector. The directory entry pointer should point to $8400 and not the pointer returned by LOOKUP. This is due to memory conflicts that will arise.

Function Name:

LOAD3

Purpose:

Load and possibly run a file.

Call address:

$C21D

Input requirements:

$02: Flag byte (See description).
$06-$07: Optional data pointer.
$08-$09: Optional data pointer.
$0E-$0F: Pointer to filename.
$10-$11: Load address (optional).

Output:

$8100-$81FF: Info sector for file.
$8300-$83FF: Table of tracks and sectors that were loaded.

Errors:

See Appendix

Description:

This routine is called by LOAD to load Application files. Like LOAD2, this routine is not limited to any particular file type, except that it also can not load a Non-GEOS file. See LOAD for a description of the flag byte, data pointers and load address.

Function Name:

LOADAD

Purpose:

Get the load address of a file.

Call address:

$C229

Input requirements:

$14-$15: Pointer to directory entry.

Output:

$04: Track of file's first sector.
$05: Sector of file's first sector.
$10-$11: Load address for file.
$8100-$81FF: Info sector for file.
$8300-$8301: Track and sector of info sector.

Errors:

See Appendix I.

Description:

This routine loads the info sector for a file into the buffer at $8100. The load address is set from $8147-$8148. This routine is called by all the load routines.

Function Name:

LOADSW

Purpose:

Load and run a file using the SWAPFILE.

Call address:

$C217

Input requirements:

$14-$15: Pointer to directory entry.

Output:

$8100-$81FF: Info sector for file (Modified).
$8300-$83FF: List of tracks and sectors that were loaded.

Preparatory routines:

LOOKUP (Pointer must be copied).

Errors:

See Appendix I.

Description:

This routine is used to load Desk Accessories. The info sector is loaded to determine the necessary memory region. This region is saved to a file called 'SWAPFILE', whose info sector is the same as the file to be loaded. The difference is that the text field is cleared, and the file type is System file (Type 4). LDSWAP must be eventually called to reload the SWAPFILE and return to normal operation. The directory entry pointer should point to $8400, and the pointer returned by LOOKUP. This is due to memory conflicts that will arise.

Function Name:

LOOKUP

Purpose:

Lookup a filename in the directory.

Call address:

$C20B

Input requirements:

$0E-$0F: Pointer to filename.
$886E: Flag byte.

Output:

$04: Track for directory sector.
$05: Sector for directory sector.
$0C-$0D: Pointer to file name entry.
$8000-$80FF: Directory sector.
$8400-$841D: Copy of directory entry.

Errors:

See Appendix

Description:

This is a very useful routine. Given a text string of a filename, this routine will find it in the directory. If the flag byte at $886E is $00, then both drives 8 and 9 will be scanned if necessary. If the flag is $FF, then the lookup is only to the current drive. If there is only one drive, then this flag has no effect. The directory sector is loaded into a buffer at $8000, and the track and sector are in locations $04 and $05. The particular directory entry is copied to $8400 and the pointer to the entry in the buffer is stored at $0C-$0D.

Function Name:

MAIN

Purpose:

Enters GEOS's main loop.

Call address:

$C1C3

Input requirements:

$849B-$849c: Address of user's addition to GEOS's main loop (optional).

Description:

This loop does whatever polling is needed. First the button is checked, as well as the keyboard and the mouse's position. The command table at $8719 (See CMDTBL) is scanned for executable routines. Then the counters at $877F (See DELAY) are checked; those that have reached zero have their associated routines executed. The memory image of the clock is updated. Then the alarm clock is checked. Finally, the user's addition to the main loop, if there is one, is executed. This loop continues forever.

Function Name:

MAKCUR

Purpose:

Makes a vertical bar cursor sprite.

Call address:

$C1C0

Input requirements:

A: The height of the cursor minus 1 (0-41)

Output:

Sprite block #41 ($8A40-$8A7E) is made into a vertical bar of a given height.

Description:

Given the desired height, a vertical bar is created in the sprite block. If the height is greater than 21, then the height is halved and the sprite is Y-expanded. No check is performed on the height. If a height greater than 41 is used then the memory for next few sprites will be affected.

Function Name:

MASL

Purpose:

16 bit multiple arithmetic shift lefts.

Call address:

$C15D

Input requirements:

Y: The shift count.
X: The address of the 16 bit value to be shifted.

Output:

X: Result of shifts.

Description:

This routine is one of the GEOS math routines. X has the address of a 16 bit integer in zero page, which is to be shifted left by the count in Y.

Function Name:

Purpose:

Draws and sets everything up for pull down menus and submenus.

Call address:

$C151

Input requirements:

A: Menu option to position mouse on (0 to #options-1)
$02-$03: Pointer to the menu descriptor.

Description:

This is an extremely powerful routine. It does everything for menu processing. Once control returns to the program that created the menu, the program can return to the GEOS main line, or do anything else. It is important to note that menus only appear on screen 1. Location $2F is saved and restored during the drawing phase. The left and right margins are also left unaltered. The following is a description of a menu descriptor:

#Bytes	Description
1	Top margin of entire menu.
1	Bottom margin of entire menu.
2	Left margin of entire menu.
2	Right margin of entire menu.
1	Code byte: Bit 7 vertical menu. Bit 6 set secondary box descriptor to full screen; this allows the mouse to be moved outside of a menu without causing it to be closed. Bits 0-4 # entries in menu.

This is followed by sets of 5 bytes; as many as there are entries.

#Bytes	Description
2	Address of the text for this option.
1	Code byte which describes what to do with the address that follows: Bit 7 operand is the address of a submenu descriptor. Bit 6 call subroutine, it must return a result in $02-$03 which is either 0 or the address of the next submenu. If neither bit is set, then when this option is selected it will flash before the routine is executed. Control does not return to the menu processor.
2	Address of either a submenu descriptor or a routine to be executed.

Function Name:

MLSR

Purpose:

16 bit multiple logical shift rights.

Call address:

$C262

Input requirements:

Y: The shift count.
X: The address of the 16 bit value to be shifted.

Output:

X: Result of shifts.

Description:

This routine is one of the GEOS math routines. X has the address of a 16 bit integer in zero page, which is to be shifted right by the count in Y.

Function Name:: MOUSOF
Purpose:: Turns off the mouse.
Call address:: $C18D
Description:: This routine resets bit 7 of location $30, and actually turns off the mouse sprite.

Function Name:: MOUSON
Purpose:: Turns on the mouse.
Call address:: $C18A
Description:: This routine sets bit 7 of location $30. The interrupt routines will turn on the mouse when it tries to update its position.

Function Name:

NEG16

Purpose:

Negates a 16 bit value.

Call address:

$C172

Input requirements:

X: The address of the 16 bit integer

Output:

X: The address of the 16 bit result.

Description:

This routine is one of the GEOS math routines. X points to a 16 bit value which is negated. The value of X is not affected.

Function Name:

Purpose:

Move to next VLIR chain.

Call address:

$C27A

Output:

Y: Track of VLIR chain.
$04: Track of VLIR chain.
$05: Sector of VLIR chain.
$8496: Incremented by 1.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine gets the track and sector of the next chain in the open VLIR file. It does not check to see if the chain exists (ie. track is zero). It does check if this chain is in range (against $8497).

Function Name:

NUMBLK

Purpose:

Counts the number of free blocks in the BAM that is in RAM.

Call address:

$C1DB

Input requirements:

$0C-$0D: Pointer to buffer with track 18 sector 0.

Output:

$0A-$0B: The number of free blocks.

Preparatory routines:

RD180

Description:

This routine expects that the BAM has already been read into memory. All that it does is add up the number of free blocks in each track.

Function Name:

OPNDSK

Purpose:

Opens a disk to GEOS.

Call address:

$C2A1

Input requirements:

$8489: Current drive number.

Output:

$848B: $00/$FF Geos format or not.
$841E-$8465: Appropriate buffer will have disk's name.

Errors:

See Appendix I.

Description:

The current drive is initialized by calling INITDV. GEOS format is checked for, and the disk's name is copied into the appropriate buffer at $841E-$8465.

Function Name:: OPNSER
Purpose:: Open serial communication.
Call address:: $C25C
Errors:: See Appendix I.
Description:: This routine sets up the I/O ports for high speed serial communication with the disk drives. This routine is called prior to calling READ2, WRITE2 or CWRITE.

Function Name:

PBOX

Purpose:

Draws the outline of a rectangular box in a given pattern.

Call address:

$C127

Input requirements:

A: The actual bit pattern for the box.
$06: The top margin.
$07: The bottom margin.
$08-$09: The left margin.
$0A-$0B: The right margin.

Description:

This routine draws the outline of a rectangular box in a given pattern. This routine calls HLINE and VLINE to draw the outline. See also ROWADR.

Function Name:: PBOX2
Purpose:: Identical to PBOX, but with inline data.
Call address:: $C1A2
Description:: This routine draws a solid outline of a box, which is described by inline code. See PFILL2 for an example.

Function Name:

PERMIT

Purpose:

Enables the execution of a timed event.

Call address:

$C10F

Input requirements:

X: The index into the command table at $8719.

Preparatory routines:

Description:

This routine resets bit 6 of a specific command byte in the table at $8719. This allows the associated routine to be executed when its timer runs out. If the timer had run out while the routine was disabled, GEOS will execute the routine when it gets to it. This is the complement to FORBID.

Function Name:

PFILL

Purpose:

Fills a rectangular box with a selected design.

Call address:

$C124

Input requirements:

$06: The top margin.
$07: The bottom margin.
$08-$09: The left margin.
$0A-$0B: The right margin.

Preparatory routines:

SETPAT

Description:

This routine fills a rectangular box in a given design. This routine calls HLINE repeatedly. See also ROWADR.

Function Name:

PFILL2

Purpose:

Identical to PFILL, but with inline data.

Call address:

$C19F

Preparatory routines:

SETPAT

Description:

This routine is identical to PFILL except that data that describes the box is part of the inline code. For example:

JSR PFILL2
.BYTE Top margin
.BYTE Bottom margin
.WORD Left margin
.WORD Right margin
; Control returns here after box is filled.

Function Name:

PLOT

Purpose:

Draws, erases or copies a pixel on the hires screen.

Call address:

$C133

Input requirements:

N Flag	C Flag	Operation
1	X	Copy
0	1	Draw
0	0	Erase

$08-$09: The column number.
$18: The row number.

Description:

This is a very versatile routine. It can copy a point from one screen to another, as well as draw or erase it. This routine is called by LINE to draw lines. See also ROWADR.

Function Name:

POSSPR

Purpose:

Sets the position of a sprite.

Call address:

$C1CF

Input requirements:

$08: Sprite number (0-7).
$0A-$0B: Sprite X position.
$0C: Sprite Y position.

Preparatory routines:

COPYSP

Description:

This routine copies the sprite's position to the VIC chip, relieving the user of the burden of handling the crossover in the screen from column 255 to column 256.

Function Name:

Purpose:

Move to previous VLIR chain.

Call address:

$C27D

Output:

Y: Track of VLIR chain.
$04: Track of VLIR chain.
$05: Sector of VLIR chain.
$8496: Decremented by 1.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine gets the track and sector of the previous chain in the open VLIR file. It does not check to see if the chain exists (ie. track is zero). It does check if this chain is greater than zero.

Function Name:

RANDOM

Purpose:

Modifies the random number generator at $850A-$850B.

Call address:

$C187

Output:

$850A-$850B: New seed value.

Description:

This routine changes the 16 bit random number at $850A-$850B, using a simple yet elaborate formula.

Function Name:

RD180

Purpose:

Read track 18, sector 0 from the disk.

Call address:

$C247

Output:

$04: $12, track number.
$05: $00, sector number.
$0A-$0B: $8200, address of buffer area.
$8200-$82FF: Data from track 18 sector 0.

Errors:

See Appendix I.

Description:

This routine sets up the pointers for READ, then calls it to read the sector. This is generally used to get the BAM into memory.

Function Name:

READ

Purpose:

Read a given track and sector.

Call address:

$C1E4

Input requirements:

$04: Track of sector to be read.
$05: Sector number to be read.
$0A-$0B: Pointer to buffer.

Errors:

See Appendix

Description:

Loads and runs Turbodos if it is not already there. Then reads the desired block from the disk into the buffer.

Function Name:

Purpose:

Read a sector from the disk.

Call address:

$C21A

Input requirements:

$04: Track to be read.
$05: Sector to be read.
$0A-$0B: Pointer to buffer for data.

Output:

Data is read into the desired buffer.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine is called by READ to read a sector. The difference between this routine and READ is that READ calls DSETUP before trying to read the sector. This routine assumes that the drive is ready with Turbodos running.

Function Name:: REBOOT
Purpose:: Reboot GEOS.
Call address:: $C000
Errors:: If load fails, system resets to BASIC.
Description:: This routine is not part of the normal GEOS KERNAL jump table. This is the routine that is set up as the NMI interrupt (RESTORE key) by GEOS when GEOS returns to BASIC. It loads 'GEOS BOOT', and executes it.

Function Name:

REMOVE

Purpose:

Remove a VLIR chain.

Call address:

$C283

Input requirements:

$8496: VLIR chain number.

Output:

$8496: Decremented if greater than or equal to $8497.
$8497: Decremented by 1.

Preparatory routines:

Errors:

See Appendix I.

Description:

The current VLIR chain is removed from the VLIR sector, and all the following chains are moved down one. The sectors associated with that chain are freed up.

Function Name:

RENAME

Purpose:

Rename a file.

Call address:

$C259

Input requirements:

$02-$03: Pointer to new file name.
$0E-$0F: Pointer to old file name.

Output:

$04: Track of directory sector.
$05: Sector of directory sector.
$0C-$0D: Pointer to file name in directory entry.
$8400-$841D: Copy of old directory entry.

Errors:

See Appendix I.

Description:

This routine renames a file by calling LOOKUP, then copying the new name into the entry. Finally, the sector is rewritten to the disk.

Function Name:: RESETM
Purpose:: Reset the mouse.
Call address:: $C19C
Description:: The flag at location $30 is set to $00, and the mouse sprite is turned off. However, since bit 7 of location $30 is not set, the next interrupt will turn it back on.

Function Name:: RESTRT
Purpose:: Restart DESKTOP.
Call address:: $C22C
Description:: This routine loads DESKTOP and runs it. It is called as the last part of the boot-up procedure. This is where a program should terminate.

Function Name:

ROWADR

Purpose:

Computes the address of a given row on the hires screens.

Call address:

$C13C

Input requirements:

X: The row number.
$2F: See description.

Output:

$0C-$0D: Pointer to the row on the destination screen.
$0E-$0F: Pointer to the row on the source screen.

Description:

This routine computes the address of column 0 on a given row of the hires screens. All of the graphics routines rely on this routine to get the address of the hires screens. They all take the data pointed to by $0E-$0F and store their data to both $0C-$0D and $0E-$0F. Location $2F determines which screen is pointed to by which pointer. This is as follows:

Bit 7	Bit 6	$0C-$0D	$0E-$0F	Description
0	0	$AF00	$AF00		Approximately the middle of screen 1
0	1	Screen 2	Screen 2
1	0	Screen 1	Screen 1
1	1	Screen 1	Screen 2	(Default at reset)

Function Name:

RUN

Purpose:

Execute a program already in memory.

Call address:

$C22F

Input requirements:

$02: Flag byte.
$06-$07: Data pointer (optional).
$08-$09: Data pointer (optional).
$10-$11: Start address.

Output:

$06-$07: Pointer to drive name 2.
$08-$09: Pointer to drive name 3.

Description:

This routine performs some initializations before executing a loaded program. If either bit 6 or bit 7 of the flag byte at location $02 is set, then the data pointed to by $06-$07 and $08-$09 are copied into the buffers for the 3rd and 4th drive names. These data blocks are limited to 16 bytes each. The initialization process selects the BSW font and initializes all of GEOS's global variables.

Function Name:

SAVE

Purpose:

Save memory to a file.

Call address:

$C1ED

Input requirements:

$14-$15: Pointer to information sector data.
$16: # directory sectors to skip first.

Errors:

See Appendix

Description:

This routine will save memory to a file; each sector is verified after the write is finished. The info sector has all the necessary information. ie. start and stop addresses, file type and structure. It must also contain the address of the filename string somewhere in memory, in the first two bytes. If the file is a VLIR file, the memory is saved to chain 0. Location $16 specifies the number of directory sectors to skip for DIRDSK and HOLE.

Function Name:

SAVE2

Purpose:

Save memory to specified sectors on the disk.

Call address:

$C1F9

Input requirements:

$0E-$0F: Pointer to list of tracks and sectors to use.
$10-$11: Start address of memory to be saved.

Preparatory routines:

Errors:

See Appendix

Description:

This routine is called by SAVE to actually save the memory. All of the sectors should have already been allocated. This routine stops saving memory when track 0 is found in the list of tracks and sectors.

Function Name:

SD1616

Purpose:

Signed 16 bit by 16 bit division.

Call address:

$C16C

Input requirements:

Y: The address of the 16 bit divisor.
X: The address of the 16 bit dividend.

Output:

X: The address of the 16 bit quotient.
$12-$13: The 16 bit remainder.

Description:

This routine is one of the GEOS math routines. X and Y each have the address of a term in the division. Both terms are made positive with ABS16. UD1616 is then called; if the result of the division should be negative, NEG16 is called. The quotient is stored in place of the original dividend that X pointed to. The dividend is left untouched. The remainder is always a positive integer.

Function Name:

SELBSW

Purpose:

Selects the Berkeley Softworks font.

Call address:

$C14B

Output:

$26: # pixels above line of print.
$27-$28: The number of bytes in the bit stream.
$29: The point size.
$2A-$2B: The pointer to the table of indices into the bit stream.
$2C-$2D: The pointer to the bit stream.

Description:

This routine simply copies the font header data for the BSW font to zero page for use by DSPCHR and DSPTXT.

Function Name:

SETPAT

Purpose:

Sets the current fill pattern.

Call address:

$C139

Input requirements:

A: The pattern number (0-31).

Description:

This routine sets the fill pattern used by PFILL, PFILL2, PBOX and PBOX2.

Function Name:

SPROFF

Purpose:

Turns off a sprite.

Call address:

$C1D5

Input requirements:

$08: Sprite number (0-7).

Preparatory routines:

COPYSP, POSSPR, SPRON

Description:

This routine turns the sprite off, so that it is no longer visible.

Function Name:

SPRON

Purpose:

Turns on a sprite.

Call address:

$C1D2

Input requirements:

$08: Sprite number (0-7).

Preparatory routines:

COPYSP, POSSPR

Description:

This routine turns the sprite on, so that it is visible.

Function Name:

START

Purpose:

Restarts the timer on a timed event.

Call address:

$C115

Input requirements:

X: The index into the command table at $8719.

Preparatory routines:

Description:

This routine resets bit 5 of a specific command byte in the table at $8719. This enables the associated counter. This routine is the complement to STOP. This routine is NOT a replacement for ENABLE. This routine does not copy the timer's initial value as does ENABLE.

Function Name:

STOP

Purpose:

Stops the timer on a timed event.

Call address:

$C112

Input requirements:

X: The index into the command table at $8719.

Preparatory routines:

Description:

This routine sets bit 5 of a specific command byte in the table at $8719. This prevents the associated timer from running. This routine is the complement to START.

Function Name:

STRCMP

Purpose:

Compare two strings for equality.

Call address:

$C26B

Input requirements:

X: Address of a zero page pointer.
Y: Address of a zero page pointer.

Output:

Z flag: Set accordingly.

Description:

The X and Y registers point to zero page pointers. The two strings are compared up to a zero byte. The Z flag is set accordingly.

Function Name:

STRCPY

Purpose:

Copy a string.

Call address:

$C265

Input requirements:

X: Address of zero page source pointer.
Y: Address of zero page destination pointer.

Description:

The X and Y registers point to zero page pointers. Data is copied up to and including a zero byte. This routine is used to copy strings by setting A to zero and calling BLKMOV.

Function Name:: SYSERR
Purpose:: Draw a system error window, and halt system.
Call address:: $C2C2
Description:: A window is drawn with the message 'System error near $xxxx', where xxxx is the hex address of the JSR SYSERR instruction. Since the system error window has no way of being closed, GEOS simply sits in its main loop forever. The BRK vector at $84AF-$84B0 is initially set to this routine.

Function Name:

TABLE

Purpose:

Create a list of filenames.

Call address:

$C23B

Input requirements:

$0E-$0F: Pointer to buffer area for file names.
$10: GEOS file type.
$11: Maximum number of file names.
$16-$17: Pointer to class.

Output:

$11: Number of files not found. The table is filled with filenames.

Errors:

See Appendix I.

Description:

This is a very useful routine. Given a GEOS file type, a list of files with that type is created. If the class pointer is non-zero then each file's info sector is checked for proper class. This is how GEOpaint and GEOwrite can both create Application Data files and not see each others files. The filenames are text strings with zero byte terminators. Each entry is indexed with a multiple of 17 (16 byte filename max. plus zero byte). Location $11 has the number of table entries not filled. To get the number of files actually found, this value must be subtracted from the original maximum buffer length.

Function Name:

TBLJMP

Purpose:

Jump through a table.

Call address:

$C2A4

Input requirements:

A: Offset into table.
$3D-$3E: Table address.

Description:

This routine is called by all of the routines that have inline data. They all set $3D-$3E to the return address of the caller, index off of this pointer to get their data, then call the appropriate routine. When the routine finishes, A is loaded with the data table's length and this routine is called to return control to the caller after the data table.

Function Name:

TEST

Purpose:

Tests the value of a point on the hires screen.

Call address:

$C13F

Input requirements:

$08-$09: The column number.
$18: The row number.

Output:

C flag: Value of the pixel.

Description:

Tests whether or not a given pixel is on or not. The carry flag is set to the value of the pixel.

Function Name:

TRACE

Purpose:

Create a table of tracks and sectors.

Call address:

$C205

Input requirements:

$04: Initial track number.
$05: Initial sector number.
$08-$09: Address of table to be created.

Output:

Table pointed to by $08-$09 is filled with all the tracks and sectors linked to the initial sector.

Errors:

See Appendix

Description:

Given an initial track and sector, this routine traces a chain and returns a list of all the tracks and sectors encountered. This routine uses the buffer at $8000-$80FF to read the sectors.

Function Name:

UD1616

Purpose:

Unsigned 16 bit by 16 bit division.

Call address:

$C169

Input requirements:

Y: The address of the 16 bit divisor.
X: The address of the 16 bit dividend.

Output:

X: The address of the 16 bit quotient.
$12-$13: The 16 bit remainder.

Description:

This routine is one of the GEOS math routines. X and Y each have the address of a term in the division. The quotient is stored in place of the original dividend that X pointed to. The dividend is left untouched.

Function Name:

UM1616

Purpose:

Unsigned 16 bit by 16 bit multiply.

Call address:

$C166

Input requirements:

Y: The address of the 16 bit multiplier.
X: The address of the 16 bit multiplicand.

Output:

X: The address of the 16 bit result.

Description:

This routine is one of the GEOS math routines. X and Y each have the address of a term in the multiplication. The result is stored in place of the original multiplicand that X pointed to. The multiplier pointed to by Y is untouched.

Function Name:

UM168

Purpose:

Unsigned 8 bit by 16 bit multiply.

Call address:

$C163

Input requirements:

Y: The address of the 8 bit multiplier.
X: The address of the 16 bit multiplicand.

Output:

X: The address of the 16 bit product.

Description:

Function Name:

UMUL88

Purpose:

Unsigned 8 bit by 8 bit multiply.

Call address:

$C160

Input requirements:

Y: The address of the multiplier.
X: The address of the multiplicand.

Output:

X: The address of the 16 bit product.

Description:

Function Name:

UPDATE

Purpose:

Update a VLIR file.

Call address:

$C295

Output:

$8498: Cleared to $00.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine writes the open VLIR file's VLIR sector to disk and updates the file's directory entry on disk (Time, date and file size). This operation is not performed if location $8498 is zero to start with. That location is a flag that tells whether the file has been altered or not. This routine is called by VCLOSE.

Function Name:

VCLOSE

Purpose:

Close a VLIR file.

Call address:

$C277

Output:

$8873: Cleared to $00.

Preparatory routines:

Errors:

See Appendix I.

Description:

The VLIR sector is rewritten to the disk and the directory is updated with a new time, date and file size by calling UPDATE. Location $8873 is the track number of the VLIR sector. By clearing it, GEOS says that the file is no longer in memory.

Function Name:

VLINE

Purpose:

Draws a vertical line on the screen.

Call address:

$C121

Input requirements:

A: The actual bit pattern for the line.
$08: The top margin.
$09: The bottom margin.
$0A-$0B: The right margin.

Description:

This routine draws a vertical line on the hires screen in a given pattern. See also ROWADR.

Function Name:

VLOAD

Purpose:

Load a VLIR chain.

Call address:

$C28C

Input requirements:

$06-$07: Maximum byte count of load.
$10-$11: Load address.
$8496: Current chain number.

Output:

$8302-$83FF: Table of tracks and sectors that were loaded.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine loads the current chain by calling LCHAIN.

Function Name:

Purpose:

Opens a VLIR file.

Call address:

$C274

Input requirements:

$02-$03: Pointer to file name.

Output:

$04: Track of VLIR sector.
$05: Sector of VLIR sector.
$0C-$0D: Pointer to file's directory entry.
$8100-$81FF: File's VLIR sector.
$8496: Initial chain # (Should be 0).
$8497: Number of chains.
$8498: Cleared to $00. (VLIR file modified).
$8499-$849A: File size.
$886F: Track of file's directory entry.
$8870: Sector of file's directory entry.
$8871-$8872: Pointer to directory entry.
$8873: Track for VLIR sector.
$8874: Sector for VLIR sector.

Errors:

See Appendix I.

Description:

This routine opens a VLIR file, and sets up all the variables associated with it. Only one VLIR file can be open at a time due to the fact that these variables are global.

Function Name:

VSAVE

Purpose:

Save memory to a VLIR chain.

Call address:

$C28F

Input requirements:

$06-$07: Length of save.
$10-$11: Address of memory to be saved.
$8496: VLIR chain number.

Output:

$8300-$83FF: Table of tracks and sectors that were saved to.

Preparatory routines:

Errors:

See Appendix I.

Description:

This routine saves a block of memory to a VLIR chain. If the chain already existed, then it is deleted first. If the length of the save is 0, then no save is performed. This would allow this routine to be used as a delete chain function.

Function Name:

WHATIS

Purpose:

Who knows?

Call address:

$C196

Output:

$02-$03: Value from $9F27-$9F28 ($3E66).

Description:

This routine seems to have absolutely no purpose. It copies a vector from $9F27-$9F28 ($3E66) to $02-$03. Locations $9F27 and $9F28 are checked by another routine at boot-up. If it is zero then the first VLIR chain of the kernal ($9000-$9FFF) is rewritten to the disk. This may be a remnant of the GEOS development environment or it may be some kind of kernal version number. The code looks like this:

LDA $9F28
STA $03
LDA $9F27
STA $02
RTS

Function Name:

WINDOW

Purpose:

Process a window descriptor.

Call address:

$C256

Input requirements:

$02-$03: Pointer to window descriptor.

Output:

$02: Window command that closed the window.
$851D: Window command that closed the window.

Description:

Like MENU, this is another very powerful routine. Given a description of the window's commands, everything gets handled. The format of the window descriptor is as follows:

.BYTE

Window type.

Bit 7: Window size follows; otherwise, use standard window size rows 40 to 135, columns 72 to 263.
Bits 0-4: Fill pattern for shadow. If zero, then no shadow is drawn.

The following six bytes are only present if bit 7 of the window type is set.

.BYTE

Top margin.

.BYTE

Bottom margin.

.WORD

Left margin.

.WORD

Right margin.

.BYTE

Command bytes followed by whatever data is needed.

All the click box descriptors are stored in a table at $880C, for GEOS to process them. This limits the number of click boxes in a window to 8. Several memory locations are saved prior to processing the window; also the stack pointer and return address are saved. After the window is drawn, control passes back to MAIN. CLSWIN must be called to return to the caller. Therefore it is essential that some means of closing a window exists, otherwise a situation like SYSERR will occur (See the SYSERR routine for more info).

The command that closes the window is the value returned to the user. ie. if a click box closes the window then the command number that drew the click box is returned. However it is the user's routine's responsibility to set the value of location $851D if a user click box is to close the window. Command #13 is another one that can close the window. User routines do not have to close the window but they may if they so desire.

The following is a list of the memory addresses stored by the window processor:

$22-$38
$3F-$40
$849B-$84C0
$86C0-$87D3
$8FF8-$8FFF
$D000-$D010
$D015
$D01B-$D01D
$D025-$D026
$D028-$D02E

The Window processor commands are:

0

No data. This command ends the window descriptor.

1

The data for this command is the column offset in bytes and the row offset in pixels. Draw an 'OK' click box.

2

The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'Cancel' click box.

3

The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'Yes' click box.

4

The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'No' click box.

5

The data for this command is the column offset in bytes and the row offset in pixels. Draw an 'Open' click box.

6

The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'Disk' click box.

7-10

undefined commands

11

The data for this command is the column offset in pixels, the row offset in pixels, and the address of a text string. This command displays the text string at the specified offset in the window.

12

The data for this command is the column offset in pixels, the row offset in pixels and zero page address of the address of a text string. This command is similar to command 11, except for its method of addressing the string.

13

The data for this command is the column offset in pixels, the row offset in pixels, zero page address of the address of the text buffer to be used by INPUT and the maximum length of the input buffer. See INPUT for more information.

14

Set the vector at $84A9-$84AA to close the window. Generally used with command 13.

15

The data for this command is the address of a GRPHIC command table. See GRPHIC for further information.

16

The data for this command is the column offset in pixels and the row offset in pixels. This command opens a scrolling window of filenames. Locations $10 and $16-$17 must be set prior to calling WINDOW (See TABLE for more information). The filenames are stored at $8300-$83FF, to a maximum of 15 filenames. Location $885C will return the index of the selected file name. If more than 6 files are found, the sub-window will have a click box for scrolling the list.

17

The data for this command is the address of the routine for button pressed. This command sets the vector at $84A9-$84AA to a user specified routine.

18

The data for this command is the column offset in bytes, the row offset in pixels and the address of a user's 8 byte click box description, in the following format:

#Bytes	Description
2	Address of graphic data.
2	Not used.
1	Width of box in bytes.
1	Height of box in pixels.
2	Address of routine to process this box.

19

The data for this command is the address of a user subroutine. This command calls the user's subroutine.

Function Name:

WR180

Purpose:

Write track 18 sector 0 back to disk.

Call address:

$C24A

Input requirements:

$8200-$82FF: Data for track 18 sector 0.

Output:

$04: $12, track number.
$05: $00, sector number.
$0A-$0B: $8200, address of buffer area.

Errors:

See Appendix I.

Description:

This routine sets up the pointers for WRITE, then calls it to write the sector. This is generally used to update the BAM on the disk.

Function Name:

WRITE

Purpose:

Write a given track and sector.

Call address:

$C1E7

Input requirements:

$04: Track of sector to be written.
$05: Sector number to be written.
$0A-$0B: Pointer to buffer.

Errors:

See Appendix

Description:

Loads Turbodos if it is not already there by calling DSETUP. The desired block is then written to the disk by calling WRITE2. Finally CWRITE is called to verify the sector.

Function Name:

WRITE2

Purpose:

Write a sector to the disk.

Call address:

$C220

Input requirements:

$04: Track number.
$05: Sector number.
$0A-$0B: Pointer to data buffer.

Preparatory routines: