Next Previous Contents

3. Library Functions

Functions here are sorted more or less in the way they appear in header files. This way I am able to keep functions covering similar task near each other. All function names are identical to those from geosSym file provided with GeoProgrammer package. Only my extensions to geosSym are covered by new names, but I tried to keep them in the naming convention.

3.1 Graphics

This section covers drawing package of GEOS along with text output routines.

SetPattern

void SetPattern (char pattern)

This function sets current pattern to given. There are 32 different patterns in GEOS. You can see them together in the filling box in GeoPaint.

GraphicsString

void GraphicsString (char *myGString)

One of the more powerfull routines of GEOS. This function calls other graphic functions depending on given command string. See structures chapter for more detailed description of the structure of it.

Rectangle functions

Parameters to those functions are grouped in struct window drawWindow. To speed up things and reduce overhead this structure is glued to zero page locations, where all rectangle functions expect their parameters. You can modify data directly (e.g. drawWindow.top=10) or via InitDrawWindow function. Contents of drawWindow are guaranteed not to change only when using graphics functions. In other case you should keep your data in separate struct window and use InitDrawWindow before first call to rectangle functions.

InitDrawWindow

void InitDrawWindow (struct window *myWindow)

This function only copies contents of myWindow into system area of drawWindow. Use it if for some reason you have to keep window data out of zero page space.

Rectangle

void Rectangle (void)

This draws on screen rectangle filled with current pattern.

FrameRectangle

void FrameRectangle (char pattern)

This one draws frame with given bit pattern (not a pattern from GEOS palette).

InvertRectangle

void InvertRectangle (void)

Just as the name says...

ImprintRectangle and RecoverRectangle

void ImprintRectangle (void)

void RecoverRectangle (void)

These two functions are for copying parts of the screen to (Imprint) and from (Recover) backbuffer of the screen. For example when drawing new menu box GEOS first uses ImprintRectangle to save the area under the box, and restores it by RecoverRectangle upon destroying the menu.

Line Functions

GEOS drawing package is optimized so there are different functions for drawing vertical and horizontal lines.

HorizontalLine

void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)

This function draws horizontal line using given pattern - here it is a true bit pattern, not pattern set by SetPattern.

InvertLine

void InvertLine (char y, unsigned xStart, unsigned xEnd)

There is only horizontal version.

RecoverLine

void RecoverLine (char y, unsigned xStart, unsigned xEnd)

This function recovers only one line. It is utilized by RecoverRectangle. See its description for more details.

VerticalLine

void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)

This function draws vertical line using given pattern. Note that pattern is not a pattern number as set in SetPattern but a true bit pattern.

DrawLine

void DrawLine (char mode, struct window *myWindow)

top parameters of struct window describe the starting point of the line, while bottom are for the ending point. If mode is DRAW_DRAW then current pattern from SetPattern is used for drawing. If mode is DRAW_ERASE then line is erased from the screen. If mode is DRAW_COPY then line is copied from/to back/frontbuffer, according to dispBufferOn setting.

Point Functions

Parameters to these two functions are passed by a pointer to own struct pixel filled with proper values.

DrawPoint

void DrawPoint (char mode, struct pixel *myPixel)

Depending on mode (see DrawLine) draws/erases/copies a single point on the screen.

TestPoint

char TestPoint (struct pixel *myPixel)

This function tests if given pixel is set and returns true (non-zero) or false (zero).

Character and string output

cpputs

cpputsxy (char x, char y, char *myString)

cpputs (char *myString)

Actually this is a part of conio, but this function is non-standard. It is a variety of cputs that will output string with proportional spacing, not fixed like cputs.

PutChar

void PutChar (char character, char y, unsigned x)

This function outputs single character using current style and font to screen.

PutString

void PutString (char *myString, char y, unsigned x)

Same as PutChar except the fact that you can output whole NULL-terminated string. See ggraph.h for list of tokens that you can also place in the string - like CBOLDON or COUTLINEON.

PutDecimal

void PutDecimal (char parameter, unsigned value, char y, unsigned x)

This function converts value to its decimal representation and outputs it to the screen. The parameter is the field width in pixels (range 1-31) and mode bits. Depending on them the string can be filled with zeroes (string always 5 characters long) or not and left or right justified to given pixel. See ggraph.h for predefined values for parameter.

Font Handling

GetCharWidth

char GetCharWidth (char character)

This function returns real width (in pixels) of given character with current font. It can be used for counting the length of string on screen, allowing for indentation or justification.

LoadCharSet

void LoadCharSet (struct fontdesc *myFont)

This function forces GEOS to use given font instead of own. myFont should be casted from pointer to the start of area where was loaded record from font file (VLIR structure).

UseSystemFont

void UseSystemFont (void)

This function forces GEOS to use built-in BSW font.

Bitmap handling

I'm not quite sure how are these functions working (except BitmapUp) so you should probably look into library sources and compare it with your knowledge. Please let me know if something is wrong or broken.

BitmapUp

void BitmapUp (struct iconpic *myPic)

This function unpacks the bitmap and places it on the screen - just as you set it in the struct iconpic pointer to which you pass. See gstruct.h for description of this structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.

BitmapClip

void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)

This function acts similar to BitmapUp but you can also define which parts of the bitmap are to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap, and the number of rows to skip from the top if it.

BitOtherClip

void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop, struct iconpic *myPic)

Similar to the previous one with some extension. proc1 is called before reading a byte (it returns in .A next value), and proc2 is called every time the parser reads a byte which is not a piece of pattern (byte of code greater than 219). Both procedures should be written separately in assembler and declared as __fastcall__ returning char.

3.2 Menus and Icons

Here you will find information about functions related with menus and icons.

Menus

Menus are essential for GUI. GEOS can handle only one menu at a time, but each menu can call another one, which results in submenu tree. There can be up to 8 menu levels, each one with up to 32 items.

Menus are initialized with DoMenu and then Kernal takes care for everything. Your code (called from event handler) should be a function without parameters, returning void. You should use DoPreviousMenu or GotoFirstMenu at least once in its code to have the screen clean.

DoMenu

void DoMenu (struct menu *myMenu)

This function initializes GEOS menu processor and exits. See DoMenu structure for more information about it. Know that many GEOS application just initializes the screen, menu and exits to main Kernal loop, this proves the power of DoMenu.

ReDoMenu

void ReDoMenu (void)

This simply redraws the menu at lowest level. It works like calling DoMenu again with the same parameters.

RecoverMenu

void RecoverMenu (void)

This function erases current menu from the screen. It doesn't change the menu level.

RecoverAllMenus

void RecoverAllMenus (void)

This calls RecoverMenu and erases all menus from the screen. Then the menu level is set to 0 (topmost).

DoPreviousMenu

void DoPreviousMenu (void)

This functions causes menu processor to go back one menu level. You should use it in menu handler code to have the screen clean.

GotoFirstMenu

void GotoFirstMenu (void)

This one jumps back to the topmost menu. If there is only menu and submenu it works the same as DoPreviousMenu.

Icon Functions

Icons are working similar to menus except the fact that there is only one level. Icons are defined as a screen area filled with a bitmap, but if you would setup icons and erase the screen they are still active and clicking in the place where formerly an icon was will cause an effect. Similarly if you would setup icons and then turn them off with ClearMouseMode the bitmap will be still on the screen but clicking on it would not cause any action. There is only one, but powerful icon function.

DoIcons

void DoIcons (struct icontab *myIconTab)

This function initializes all icons that are present on the screen at once. For more information look at Icons chapter in this manual.

3.3 DialogBoxes

This chapter covers the most powerful GEOS user interface function - DoDlgBox.

GEOS standard

DoDlgBox

char DoDlgBox (char *dialogString)

DialogBox returns one byte. It can be the value of one of six standard icons (see gdlgbox.h) or whatever closing routine passes. Register r0L also contains this value.

Read structures chapter for the specs of the dialogString.

RstrFrmDialogue

char RstrFrmDialogue

This function called from within DialogBox event immediately closes the DialogBox and returns the owner ID (or whatever caller has in the .A register).

GEOSLib extensions

To simplify usage of DoDlgBox from C I've wrote some help functions - wrappers for DoDlgBox, with predefined data. In one word - these are standard DialogBoxes you can see in almost every GEOS application.

DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk

char DlgBoxYesNo (char *line1, char *line2)

char DlgBoxOkCancel (char *line1, char *line2)

void DlgBoxOk (char *line1, char *line2)

These function show two lines of text in standard-sized DialogBox. You can read the code of pressed icon from return value. E.g. for DlgBoxYesNo it can only be YES or NO. You can pass an empty string or NULL to get a blank line.

DlgBoxGetString

char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)

This function prompts user for entering a string of at most strlen characters. It is returned in string. The two given lines of text are shown above the input line. Please remember that there is also CANCEL icon in the DialogBox and you should test if user confirmed his input or gave up. The string is also shown so you can place default input there or remember to place NULL at start.

DlgBoxFileSelect

char DlgBoxFileSelect (char *class, char filetype, char *filename)

This routine is the standard file selector. It can return OPEN, CANCEL or disk error on reading the directory or opening the disk. There is also DISK icon shown, but it is handled internally. You pass as input parameters filetype and pointer to string containing the first part of file's class. If this string is empty (NULL at the start), then all files with given filetype will be shown.

At present this file selector handles only first 16 files of given type and supports only one (current) drive.

MessageBox

char MessageBox (char mode, const char *format, ...)

This function is a more general one. It works very much like printf in a box. The only difference is mode parameter which allows for placing default icons (see gdlgbox.h for list of possible MB_ values). Any too wide text will be clipped to the size of the default window. If mode parameter is invalid or equal to MB_EMPTY then the window will be closed after a click. Otherwise the user must choose an icon.

Note: use it if you really need (or if you will use it in many places) as it adds quite amount of code to your program.

Note: the formatted text cannot exceed 255 bytes in length, there is no check for that.

3.4 Mouse, Sprites and Cursors

You will find here functions related to sprite and mouse drawing and handling.

Mouse related functions

These cover mouse - as a general pointing device, but expect user to utilize as different devices as digital or analog joystick, mouse, lightpen or koalapad (whatever it is).

StartMouseMode

void StartMouseMode (void)

This function initializes mouse vectors - mouseVector and mouseFaultVec, and then calls MouseUp.

ClearMouseMode

void ClearMouseMode (void)

This function disables all mouse activities - icons and menus stop to respond to mouse events, but they are not cleared from the screen.

MouseUp and MouseOff

void MouseUp (void)

void MouseOff (void)

The first function turns the mouse pointer on. It will appear on next IRQ. The second one does the opposite - it turns off the pointer, but its position is still updated by input driver.

IsMseInRegion

char IsMseInRegion (struct window *myWindow)

This function tests if mouse pointer is actually in given range of screen. See gsprite.h for description of bits in return values - they describe the position in detail.

Sprites

You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse pointer and sprite 1 can be overwritten when using text prompt. You don't have to worry about 40/80 column issues because GEOS128 has pretty good sprite emulator for VDC.

DrawSprite

void DrawSprite (char sprite, char *mySprite)

This function initializes the sprite data. mySprite is a 63-byte table with bitmap data, which is copied to system sprite area (at sprpic - see gsym.h). Hardware sprite registers are not initialized and sprite is not yet visible.

PosSprite

void PosSprite (char sprite, struct pixel *myPixel)

This function positions the sprite on the screen. Given coordinates are screen ones - they are converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your sprite off the left or top to the screen.

EnablSprite and DisablSprite

void EnablSprite (char sprite)

void DisablSprite (char sprite)

These two functions are responsible for making the sprite visible or not.

Cursors and Console

InitTextPrompt

void InitTextPrompt (char height)

This function initializes sprite 1 for text prompt with given height. This parameter can be in range 1-48.

PromptOn and PromptOff

void PromptOn (struct pixel *myPixel)

void PromptOff (void)

The first function places text prompt in given place and enables blinking. The second one is pretty self-explanatory.

GetNextChar

char GetNextChar (void)

This function gets next character from the keyboard queue. If the queue is empty it returns NULL, otherwise you receive true ASCII code of a character or value of special (function) key. See gsprite.h for list of them.

3.5 Disk

This chapter covers slightly low-level disk routines. You should use them with care, because you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be dangerous.

For some purposes you might consider using dio.h interface to disk access. It is native.

All GEOS disk functions return error code in X register. In some cases this is returned by GEOSLib function (if its type is char), but in all cases last error is saved in __oserror location. If it is nonzero - an error occured. See gdisk.h for the list of possible errorcodes. You need to include errno.h to get __oserror, together with standard errno. The latter gives less verbose, but still usable information and can be used with strerror. Probably you will get more information using _stroserror in similar way.

For passing parameters use almost always pointer to your data e.g. ReadBuff (&myTrSe).

Buffer functions

These functions are taking single data sector (256 bytes) to read or write on a disk.

ReadBuff and Writebuff

char ReadBuff (struct tr_se *myTrSe)

char WriteBuff (struct tr_se *myTrSe)

These functions read and write sector placed at diskBlkBuf.

GetBlock and ReadBlock

char GetBlock (struct tr_se *myTrSe, char *buffer)

char ReadBlock (struct tr_se *myTrSe, char *buffer)

These two functions are reading a single block directly at 256 byte array placed at buffer. The difference between them is that GetBlock will initialize TurboDos in drive if it was not enabled. ReadBlock assumes that it is already enabled thus being slightly faster.

PutBlock, WriteBlock, VerWriteBlock

char PutBlock (struct tr_se *myTrSe, char *buffer)

char WriteBlock (struct tr_se *myTrSe, char *buffer)

char VerWriteBlock (struct tr_se *myTrSe, char *buffer)

Similar to previous but needed for writing the disk. VerWriteBlock verifies the data after writing. In case of error five tries are attempted before error code is returned.

Directory header

Functions described here are operating on curDirHeader where current disk header is stored. On larger capacity drives (than 1541) the second part of directory header in dir2Head.

GetPtrCurDkNm

void GetPtrCurDkNm (char *diskName)

This function fills given character string with the name of current disk. It is converted to C standard - string is terminated with NULL character instead of code 160 as in Commodore DOS. Note that passed pointer must point to an array of at least 17 bytes.

GetDirHead and PutDirHead

char GetDirHead (void)

char PutDirHead (void)

These functions are reading and writing the directory header. You should use GetDirHead before using any functions described below, and you should use PutDirHead to save the changes on the disk. Otherwise they will be lost. Operating area is the curDirHead.

CalcBlksFree

unsigned CalcBlksFree (void)

This function returns the number of free blocks on current disk. It is counted using data in curDirHead so you must initialize the disk before calling it.

ChkDskGEOS

char ChkDskGEOS (void)

This functions checks curDirHead for GEOS Format identifier. It returns either true or false, and also sets isGEOS properly. You must initialize the disk before using this.

SetGEOSDisk

char SetGEOSDisk (void)

This function initializes disk for use with GEOS. It sets indicator in directory header and allocates a sector for the directory of border files. You don't need to initialize the disk before using.

FindBAMBit

char FindBAMBit (struct tr_se *myTrSe)

This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is set if the sector is free to use. Returned value is always zero if the sector is already allocated. In fact, this function could be used in a following way:

#define BlockInUse FindBAMBit
...
if (!BlockInUse(&myTrSe)) {
... block not allocated ...
}

Anyway, I feel that this function is too low-level.

BlkAlloc and NxtBlkAlloc

char BlkAlloc (struct tr_se output[], unsigned length)

char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[], unsigned length)

Both functions are allocating enough disk sectors to fit the number of length in them. You will find output in output which is table of struct tr_se. The last entry will have the number of track equal to 0 and sector equal to 255. The simplest way of using them is to use predefined space in GEOS data space and pass fileTrScTab, which is a predefined table.

The difference between those two is that NextBlkAlloc will start allocating from given sector, and BlkAlloc starts from the first nonused sector.

You need to use PutDirHead later to save any changes in BAM.

FreeBlock

char FreeBlock (struct tr_se *myTrSe)

Simply deallocates a block in BAM. You need to update BAM with PutDirHead.

SetNextFree

struct tr_se SetNextFree (struct tr_se *myTrSe)

This function finds the first free sector starting from given track and sector and allocates it. It might return the same argument if the given block is not allocated. I wanted it to be type clean, but it made usage a bit tricky. To assign a value to own struct tr_se you have to cast both variables to unsigned. E.g.

struct tr_se myTrSe;
...
(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe);

In this example otherTrSe can be replaced by myTrSe.

Note: you must use casting to have correct values.

Low-level disk IO

Functions described here are more usable in kernal or drivers code, less common in applications, but who knows, maybe someone will need them.

EnterTurbo, ExitTurbo, PurgeTurbo

void EnterTurbo (void)

void ExitTurbo (void)

void PurgeTurbo (void)

These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit more usable. EnterTurbo enables TurboDos unless it is already enabled. If not, then you will have to wait a bit to transfer TurboDos code into disk drive RAM. ExitTurbo disables TurboDos. This is useful for sending some DOS commands for drive e.g. for formatting. Note that before any interaction with Kernal in ROM you have to call InitForIO. You don't have to worry about speed. EnterTurbo will only enable TurboDos (no code transfer) if TurboDos was disabled with ExitTurbo. PurgeTurbo acts different from ExitTurbo - it not only disables TurboDos, but also removes it from drive RAM (not quite true, but it works like that). After using PurgeTurbo the next call to EnterTurbo will reload drive RAM.

ChangeDiskDevice

char ChangeDiskDevice (char newDevice)

This function changes logical number of current device (in fact drives only) with given one. It is usable for swapping drives. There's no check if given newDevice already exist, so if you want to change the logical number of drive 8 to 9 and you have drive number 9 then GEOS will probably hang on disk access. Use safe, large numbers. Note that safe IEC range is 8-31.

Disk Initialization

GEOS has two functions for initialization ('logging in' as they say on CP\M) the disk.

OpenDisk

char OpenDisk (void)

This function initializes everything for a new disk. It loads and enables TurboDos if needed. Then the disk is initialized with NewDisk. Next, GetDirHead initializes curDirHead. Disk names are compared and if they differ then disk cache on REU is cleared. Finally format is checked with ChkDkGEOS and disk name is updated in internal tables.

NewDisk

char NewDisk (void)

This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.

3.6 Files

This section cover GEOS file interface.

Directory handling

Functions described here are common for SEQ and VLIR structures.

Get1stDirEntry and GetNxtDirEntry

struct filehandle *Get1stDirEntry (void)

struct filehandle *GetNxtDirEntry (void)

These two functions are best suited for scanning whole directory for particular files. Note that returned filehandles describes all file slots in the directory - even those with deleted files. The return value can be obtained by casting both sides to unsigned - as in SetNextFree function or read directly after call to those two functions from r5. Current sector number is in r1 and sector data itself is in diskBlkBuf.

FindFile

char FindFile (char *fName)

This function scans whole directory for the given filename. It returns either 0 (success) or 5 (FILE_NOT_FOUND, defined in gdisk.h) or any other fatal disk read error. After successful FindFile you will have struct filehandle at dirEntryBuf filled with file's data and other registers set as described in GetNxtDirEntry.

FindFTypes

char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)

This function scans directory and fills a table at buffer with char [17] entries. fType is GEOS type of searched files and classTxt is a string for Class field in file header. Class will match if given will be equal or shorter than that found in file's header block. If you want just to find all files with given GEOS type you should pass empty string or NULL as classTxt. Be warned that for searching NON_GEOS files must pass NULL as classTxt. fMaxNum is the maximal number of found files, thus the buffer must provide area of size equal to 17 * fMaxNum. This function returns the number of found files, ranging from 0 to number passed as fMaxNum. Return value can be also restored from r7H.

DeleteFile

char DeleteFile (char *fName)

This function deletes a file by its name. It works for SEQ and VLIR files.

RenameFile

char RenameFile (char *oldName, char *newName)

I think it is obvious...

GetFHdrInfo

char GetFHdrInfo (struct filehandle *myFile)

This function loads the file header into fileHeader buffer. Using after e.g. FindFile you can pass address of dirEntryBuf.

Common and SEQ structure

Functions described here are common for SEQ and VLIR structures because arguments passed are starting track and sector which may point either to start of a chain for VLIR or data for SEQ.

GetFile

char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)

This routine loads and runs a given file fname. The file must be one of following types: SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER, or INPUT_DEVICE. The execution address is taken from file header. If it is zero, then file is only loaded. Only the first chain from VLIR files is loaded. If flag has bit 0 set then load address is taken from loadaddr and not from file header. In this case APPLICATION files will be only loaded, not executed. This does not apply to DESK_ACC. If either bit 6 or 7 of flag are set, then 16 bytes from datadname is copied to dataDiskName and 16 bytes from datafname goes to dataFileName thus becoming parameters for the new application. Pass NULL as any unused parameter.

ReadFile

char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)

This function reads at most fLength bytes into buffer from chained sectors starting at myTrSe.

ReadByte

char ReadByte (void)

This function returns next byte from a file. Before the first call to it you must load r5 with NULL, r4 with sector buffer address and r1 with track and sector of the first block of a file. Remember to not modify r1, r4 and r5. These registers must be preserved between calls to ReadByte.

Returned value is valid only if there was no error. End of file is marked as BFR_OVERFLOW in __oserror, this is set when trying to read one byte after the end of file, in this case returned value is invalid.

SaveFile

char SaveFile (char skip, struct fileheader *myHeader)

SaveFile will take care of everything needed to create a GEOS file, no matter VLIR of SEQ structure. All you need to do is to place data in proper place and prepare a header which will contain all information about a file. The skip parameter says how many directory pages you want to skip before searching for a free slot for directory entry. In most cases you will put 0 there.

You have to declare a struct fileheader and fill it with proper values. There is only one difference - the first two bytes which are link to nonexistent next sector are replaced by a pointer to the DOS filename of the file.

When saving sequential files two most important fields in struct fileheader are fileheader.load_address and fileheader.end_address.

FreeFile

char FreeFile (struct tr_se myTable[])

This function deallocates all sectors contained in passed table.

FollowChain

char FollowChain(struct tr_se *myTrSe, char *buffer)

This function fills a struct tr_se table at buffer with sector numbers for chain of sectors starting with myTrSe. You can pass such data (buffer) to e.g. FreeFile.

VLIR structure

Here are informations about VLIR files (called later as RecordFile) and functions.

VLIR is a file which consists of up to 127 SEQ-like files called records. Each record is like one SEQ structure file. Records are grouped together, described by common name - VLIR file name and own number. Each record pointed by its number is described by starting track and sector numbers. VLIR structures allow records to be empty (tr_se of such record is equal to {NULL,$ff}), or even non-exist ({NULL,NULL}). Any other numbers represent starting track and sector of particular file.

In GEOS there can be only one file opened at a time. Upon opening VLIR file some information about it are copied into memory. You can retrieve records table at fileTrScTab (table of 128 struct tr_se) and from VLIRInfo (struct VLIR_info. E.g. size of whole VLIR file can be retrieved by reading VLIRInfo.fileSize.

OpenRecordFile

char OpenRecordFile (char *fName)

This function finds and opens given file. An error is returned if file is not found or if it is not in VLIR format. Information in VLIRInfo is initialized. VLIR track and sector table is loaded at fileTrScTab and will be valid until call to CloseRecordFile so don't modify it. You should PointRecord before trying to do something with file.

CloseRecordFile

char CloseRecordFile (void)

This function calls UpdateRecordFile and clears internal GEOS variables.

UpdateRecordFile

char UpdateRecordFile (void)

This function will check VLIRInfo.fileWritten flag and if it is set, then curDirHead is updated along with size and date stamps in directory entry.

PointRecord

char PointRecord (char recordNumber)

This function will setup internal variables (and VLIRInfo.curRecord) and return the track and sector of given record in r1. Note that the data may not be valid (if record is non-existing you will get 0,0 and if it is empty - 255, 0).

NextRecord and PreviousRecord

char NextRecord (void)

char PreviousRecord (void)

These two work like PointRecord. Names are self-explanatory.

AppendRecord

char AppendRecord (void)

This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector table. It will also set VLIRInfo.curRecord to its number.

DeleteRecord

char DeleteRecord (void)

This function will remove current record from the table, and move all current+1 records one place back (in the table). Note that there's no BAM update and you must call UpdateRecordFile to commit changes.

InsertRecord

char InsertRecord (void)

This function will insert an empty record in place of VLIRInfo.curRecord and move all following records in table one place forward (contents of VLIRInfo.curRecord after call to InsertRecord can be found in VLIRInfo.curRecord + 1).

ReadRecord and WriteRecord

char ReadRecord (char *buffer, unsigned fLength)

char WriteRecord (char *buffer, unsigned fLength)

This function will load or save at most fLength bytes from currently pointed record into or from buffer.

3.7 Memory and Strings

Functions covered in this section are common for whole C world - copying memory parts and strings is one of the main computer tasks. GEOS also has interface to do this. These functions are replacement for those like memset, memcpy, strcpy etc. from standard libraries. If you are dealing with short strings (up to 255 characters) you should use these functions instead of standard ones. E.g. CopyString instead of strcpy. It will work faster.

However some of them have slightly different calling convention (order of arguments to be specific), so please check their syntax here before direct replacing.

Please note that the memory areas described here as strings are up to 255 characters (without counting the terminating NULL), and regions can cover whole 64K of memory.

CopyString

void CopyString (char *dest, char *src)

This function copies string from src to dest, until it reaches NULL. NULL is also copied.

CmpString

char CmpString (char *s1, char *s2)

This function compares string s1 to s2 for equality - this is case sensitive, and both strings have to have the same length. It returns either true (non-zero) or false (zero).

CopyFString and CmpFString

void CopyFString (char length, char *dest, char *src)

char CmpFString (char length, char *s1, char *s2)

These two are similar to CopyString and CmpString except the fact, that you provide the length of copied or compared strings. The strings can also contain several NULL characters - they are not treated as delimiters.

CRC

unsigned CRC (char *src, unsigned length)

This function calculates the CRC checksum for given memory range. I don't know if it is compatible with standard CRC routines.

FillRam and ClearRam

void *FillRam (char *dest, char value, unsigned length)

void *ClearRam (char *dest, unsigned length)

Both functions are filling given memory range. ClearRam fills with 0s, while FillRam uses given value. Be warned that these functions destroy r0, r1 and r2L registers. These are aliases for memset and bzero, respectively.

MoveData

void *MoveData (char *dest, char *src, unsigned length)

This functions copies one memory region to another. There are checks for overlap and the non-destructive method is chosen. Be warned that this function destroys contents of r0, r1 and r2 registers. This is also alias for memcpy

InitRam

void InitRam (char *table)

This function allows to initialize multiple memory locations with single bytes or strings. This is done with table where everything is defined. See structures chapter for description of InitRam's command string.

Stash, Fetch, Swap, and VerifyRAM

void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)

void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)

void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)

char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)

These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory. You can check for REU presence by taking value of ramExpSize. You have to do it before using any of these functions.

3.8 Processes and Multitasking

Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions called in specified intervals and you can put the main program to sleep without disturbing other tasks and making user interface unresponsive.

InitProcesses

void InitProcesses (char number, struct process *processTab)

This is the main initialization routine. After calling it processes are set up, but not enabled. The parameters for InitProcesses are:

Single task is described by entry in processTab, it contains two values - pointer to task function and number of jiffies which describe the delay between calls to task. On PAL systems there are 50 jiffies per second, while on NTSC there are 60.

The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and if processTab would be too large it would overwrite existing data in GEOS space.

There's one important thing - the last entry in processTab has to be NULL,NULL, so the maximum size of processTab is equal to 21.

See description of process structure for more detailed discussion on this.

RestartProcess and EnableProcess

void RestartProcess (char processNumber)

void EnableProcess (char processNumber)

These two functions start the task counter. RestartProcess for each process should be called after InitProcesses, because it resets all flags and counters and it starts the counters.

RestartProcess enables counters and sets their initial value to that given in processTab.

EnableProcess forces given process to execute by simulating the timer running out of time.

BlockProcess and UnBlockProcess

void BlockProcess (char processNumber)

void UnBlockProcess (char processNumber)

BlockProcess disables the execution of given process, but this does not disable the timers. It means that if you call UnBlockProcess before timer runs out, the process will be executed.

UnBlockProcess does the opposite.

FreezeProcess and UnFreezeProcess

void FreezeProcess (char processNumber)

void UnFreezeProcess (char processNumber)

FreezeProcess disables timer for given process. UnFreezeProcess does the opposite. This is not equal to RestartProcess as timers are not reloaded with initial value.

Sleep

void Sleep (unsigned jiffies)

This function is multitasking sleep - the program is halted, but it doesn't block other functions e.g. callbacks from menus and icons. The only argument here is the number of jiffies to wait until app will wake up. It depends on video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively). If you don't want to worry about it and need only full second resolution, call standard sleep function from unistd.h.

3.9 System Functions

FirstInit

void FirstInit (void)

This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot up. You shouldn't use this unless you know what you are doing.

InitForIO and DoneWithIO

void InitForIO (void)

void DoneWithIO (void)

These functions are called by some disk routines. You should call them only if you want to do something with IO registers or call one of Kernal ROM routines. Note that this is rather an expensive way of turning off IRQs and enabling IO.

MainLoop

void MainLoop (void)

Returns control to the system. Any code between call to MainLoop and the end of current function will never be executed. When in MainLoop systems waits for your action - using icons, keyboard or menus to force some specific action from program. You have to define proper handlers before that.

EnterDeskTop

void EnterDeskTop (void)

This is an alias for exit(0) so you will never burn yourself. Anyway, you should not use it. Always use exit() instead. Library destructors and functions registered with atexit() are called.

ToBASIC

void ToBASIC (void)

This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC. I was considering whether to include it or not, but maybe someone will need it. Which is I doubt.

WARNING: library destructors and functions registered with atexit() will not be called so it is quite unsafe way to finish your program.

Panic

void Panic (void)

This calls system's Panic handler - it shows dialog box with message

System error at:xxxx
where xxxx is last known execution address (caller). By default this is bound to BRK instruction, but it might be usable in debugging as kind of assert. (Note that assert is available as a separate function and will give you more information than that).

System is halted after call to Panic which means that library destructors will not be called and some data may be lost (no wonder you're panicking).

CallRoutine

void CallRoutine (void *myFunct)

This is system caller routine. You need to provide pointer to a function and it will be immediately called, unless the pointer is equal to NULL. This is the main functionality of this function - you don't need to check if the pointer is valid.

GetSerialNumber

unsigned GetSerialNumber (void)

This function returns the serial number of system. It might be used for copy-protection. However, please remember that the Free Software is a true power and you are using it right now.

GetRandom

char GetRandom (void)

This function returns a random number. It can be also read from random e.g.

a=random;
but by calling this function you are sure that the results will be always different. random is updated once a frame (50Hz PAL) and on every call to GetRandom.

Note that it is not the same as rand function from the standard library. GetRandom will give you unpredictable results (if IRQs would occur between calls to it) while rand conforms to the standard and for given seed (srand) it always returns with the same sequence of values.

SetDevice

void SetDevice (char device)

This function sets current device to given. It might be used together with InitForIO, DoneWithIO and some Kernal routines. Unless new device is a disk drive this only sets new value in curDevice, in other case new disk driver is loaded from REU or internal RAM.

get_ostype

char get_ostype (void)

This function returns GEOS Kernal version combined (by logical OR) with machine type. Read gsys.h for definitions of returned values.

get_tv

char get_tv (void)

This function returns PAL/NTSC flag combined (by logical OR) with 40/80 columns flag. This is not the best way to check if screen has 40 or 80 columns since PAL/NTSC check is always performed and it can take as long as full raster frame. If you just want to know if screen has 40 or 80 columns use expression graphMode & 0x80 which returns 0 for 40 columns and 0x80 for 80 columns. Remember that this parameter can be changed during runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test anything if not running under GEOS128. Use get_ostype to check it. Read gsys.h for definitions of returned values.


Next Previous Contents