223cc6685e
git-svn-id: svn://svn.compuextreme.de/Viitor/V963/Viitor_cc65@5933 504e572c-2e33-0410-9681-be2bf7408885
1042 lines
50 KiB
HTML
1042 lines
50 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.20">
|
|
<TITLE>GEOSLib docs: Library Functions</TITLE>
|
|
<LINK HREF="geos-4.html" REL=next>
|
|
<LINK HREF="geos-2.html" REL=previous>
|
|
<LINK HREF="geos.html#toc3" REL=contents>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="geos-4.html">Next</A>
|
|
<A HREF="geos-2.html">Previous</A>
|
|
<A HREF="geos.html#toc3">Contents</A>
|
|
<HR>
|
|
<H2><A NAME="s3">3.</A> <A HREF="geos.html#toc3">Library Functions</A></H2>
|
|
|
|
<P>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 <CODE>geosSym</CODE> file provided with GeoProgrammer package. Only my extensions to <CODE>geosSym</CODE>
|
|
are covered by new names, but I tried to keep them in the naming convention.</P>
|
|
|
|
<H2><A NAME="ss3.1">3.1</A> <A HREF="geos.html#toc3.1">Graphics</A>
|
|
</H2>
|
|
|
|
<P>This section covers drawing package of GEOS along with text output routines.</P>
|
|
|
|
<H3>SetPattern</H3>
|
|
|
|
<P><CODE>void SetPattern (char pattern)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>GraphicsString</H3>
|
|
|
|
<P><CODE>void GraphicsString (char *myGString)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>Rectangle functions</H3>
|
|
|
|
<P>Parameters to those functions are grouped in <CODE>struct window drawWindow</CODE>. 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. <CODE>drawWindow.top=10</CODE>) or via
|
|
<CODE>InitDrawWindow</CODE> function. Contents of <CODE>drawWindow</CODE> are guaranteed not to change only when
|
|
using graphics functions. In other case you should keep your data in separate <CODE>struct window</CODE>
|
|
and use <CODE>InitDrawWindow</CODE> before first call to rectangle functions.</P>
|
|
|
|
<H3>InitDrawWindow</H3>
|
|
|
|
<P><CODE>void InitDrawWindow (struct window *myWindow)</CODE></P>
|
|
<P>This function only copies contents of <CODE>myWindow</CODE> into system area of <CODE>drawWindow</CODE>. Use it
|
|
if for some reason you have to keep window data out of zero page space.</P>
|
|
|
|
<H3>Rectangle</H3>
|
|
|
|
<P><CODE>void Rectangle (void)</CODE></P>
|
|
<P>This draws on screen rectangle filled with current pattern.</P>
|
|
|
|
<H3>FrameRectangle</H3>
|
|
|
|
<P><CODE>void FrameRectangle (char pattern)</CODE></P>
|
|
<P>This one draws frame with given bit pattern (not a pattern from GEOS palette).</P>
|
|
|
|
<H3>InvertRectangle</H3>
|
|
|
|
<P><CODE>void InvertRectangle (void)</CODE></P>
|
|
<P>Just as the name says...</P>
|
|
|
|
<H3>ImprintRectangle and RecoverRectangle</H3>
|
|
|
|
<P><CODE>void ImprintRectangle (void)</CODE></P>
|
|
<P><CODE>void RecoverRectangle (void)</CODE></P>
|
|
<P>These two functions are for copying parts of the screen to (<CODE>Imprint</CODE>) and from (<CODE>Recover</CODE>)
|
|
backbuffer of the screen. For example when drawing new menu box GEOS first uses
|
|
<CODE>ImprintRectangle</CODE> to save the area under the box, and restores it by <CODE>RecoverRectangle</CODE> upon
|
|
destroying the menu.</P>
|
|
|
|
<H3>Line Functions</H3>
|
|
|
|
<P>GEOS drawing package is optimized so there are different functions for drawing vertical and
|
|
horizontal lines.</P>
|
|
|
|
<H3>HorizontalLine</H3>
|
|
|
|
<P><CODE>void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)</CODE></P>
|
|
<P>This function draws horizontal line using given pattern - here it is a true bit pattern, not
|
|
pattern set by <CODE>SetPattern</CODE>.</P>
|
|
|
|
<H3>InvertLine</H3>
|
|
|
|
<P><CODE>void InvertLine (char y, unsigned xStart, unsigned xEnd)</CODE></P>
|
|
<P>There is only horizontal version.</P>
|
|
|
|
<H3>RecoverLine</H3>
|
|
|
|
<P><CODE>void RecoverLine (char y, unsigned xStart, unsigned xEnd)</CODE></P>
|
|
<P>This function recovers only one line. It is utilized by <CODE>RecoverRectangle</CODE>. See its description
|
|
for more details.</P>
|
|
|
|
<H3>VerticalLine</H3>
|
|
|
|
<P><CODE>void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)</CODE></P>
|
|
<P>This function draws vertical line using given pattern. Note that <CODE>pattern</CODE> is not a pattern
|
|
number as set in <CODE>SetPattern</CODE> but a true bit pattern.</P>
|
|
|
|
<H3>DrawLine</H3>
|
|
|
|
<P><CODE>void DrawLine (char mode, struct window *myWindow)</CODE></P>
|
|
<P><CODE>top</CODE> parameters of <CODE>struct window</CODE> describe the starting point of the line, while
|
|
<CODE>bottom</CODE> are for the ending point. If <CODE>mode</CODE> is <CODE>DRAW_DRAW</CODE> then current pattern from
|
|
<CODE>SetPattern</CODE> is used for drawing. If <CODE>mode</CODE> is <CODE>DRAW_ERASE</CODE> then line is erased from the
|
|
screen. If <CODE>mode</CODE> is <CODE>DRAW_COPY</CODE> then line is copied from/to back/frontbuffer, according to
|
|
<CODE>dispBufferOn</CODE> setting.</P>
|
|
|
|
<H3>Point Functions</H3>
|
|
|
|
<P>Parameters to these two functions are passed by a pointer to own <CODE>struct pixel</CODE> filled with
|
|
proper values.</P>
|
|
|
|
<H3>DrawPoint</H3>
|
|
|
|
<P><CODE>void DrawPoint (char mode, struct pixel *myPixel)</CODE></P>
|
|
<P>Depending on <CODE>mode</CODE> (see <CODE>DrawLine</CODE>) draws/erases/copies a single point
|
|
on the screen.</P>
|
|
|
|
<H3>TestPoint</H3>
|
|
|
|
<P><CODE>char TestPoint (struct pixel *myPixel)</CODE></P>
|
|
<P>This function tests if given pixel is set and returns <CODE>true</CODE> (non-zero) or <CODE>false</CODE> (zero).</P>
|
|
|
|
<H3>Character and string output</H3>
|
|
|
|
<H3>cpputs</H3>
|
|
|
|
<P><CODE>cpputsxy (char x, char y, char *myString)</CODE></P>
|
|
<P><CODE>cpputs (char *myString)</CODE></P>
|
|
<P>Actually this is a part of <CODE>conio</CODE>, but this function is non-standard. It is
|
|
a variety of <CODE>cputs</CODE> that will output string with proportional spacing, not
|
|
fixed like <CODE>cputs</CODE>.</P>
|
|
|
|
<H3>PutChar</H3>
|
|
|
|
<P><CODE>void PutChar (char character, char y, unsigned x)</CODE></P>
|
|
<P>This function outputs single character using current style and font to screen.</P>
|
|
|
|
<H3>PutString</H3>
|
|
|
|
<P><CODE>void PutString (char *myString, char y, unsigned x)</CODE></P>
|
|
<P>Same as <CODE>PutChar</CODE> except the fact that you can output whole <CODE>NULL</CODE>-terminated string.
|
|
See <CODE>ggraph.h</CODE> for list of tokens that you can also place in the string - like <CODE>CBOLDON</CODE> or
|
|
<CODE>COUTLINEON</CODE>.</P>
|
|
|
|
<H3>PutDecimal</H3>
|
|
|
|
<P><CODE>void PutDecimal (char parameter, unsigned value, char y, unsigned x)</CODE></P>
|
|
<P>This function converts <CODE>value</CODE> to its decimal representation and outputs it to the screen.
|
|
The <CODE>parameter</CODE> 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 <CODE>ggraph.h</CODE> for predefined values for <CODE>parameter</CODE>.</P>
|
|
|
|
<H3>Font Handling</H3>
|
|
|
|
<H3>GetCharWidth</H3>
|
|
|
|
<P><CODE>char GetCharWidth (char character)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>LoadCharSet</H3>
|
|
|
|
<P><CODE>void LoadCharSet (struct fontdesc *myFont)</CODE></P>
|
|
<P>This function forces GEOS to use given font instead of own. <CODE>myFont</CODE> should be casted from
|
|
pointer to the start of area where was loaded record from font file (VLIR structure).</P>
|
|
|
|
<H3>UseSystemFont</H3>
|
|
|
|
<P><CODE>void UseSystemFont (void)</CODE></P>
|
|
<P>This function forces GEOS to use built-in BSW font.</P>
|
|
|
|
<H3>Bitmap handling</H3>
|
|
|
|
<P>I'm not quite sure how are these functions working (except <CODE>BitmapUp</CODE>) so you should
|
|
probably look into library sources and compare it with your knowledge. Please let me know
|
|
if something is wrong or broken.</P>
|
|
|
|
<H3>BitmapUp</H3>
|
|
|
|
<P><CODE>void BitmapUp (struct iconpic *myPic)</CODE></P>
|
|
<P>This function unpacks the bitmap and places it on the screen - just as you set it in the
|
|
<CODE>struct iconpic</CODE> pointer to which you pass. See <CODE>gstruct.h</CODE> for description of this
|
|
structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.</P>
|
|
|
|
<H3>BitmapClip</H3>
|
|
|
|
<P><CODE>void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)</CODE></P>
|
|
<P>This function acts similar to <CODE>BitmapUp</CODE> 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.</P>
|
|
|
|
<H3>BitOtherClip</H3>
|
|
|
|
<P><CODE>void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop,
|
|
struct iconpic *myPic)</CODE></P>
|
|
<P>Similar to the previous one with some extension. <CODE>proc1</CODE> is called before reading a byte (it
|
|
returns in .A next value), and <CODE>proc2</CODE> 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 <CODE>__fastcall__</CODE> returning char.</P>
|
|
|
|
<H2><A NAME="ss3.2">3.2</A> <A HREF="geos.html#toc3.2">Menus and Icons</A>
|
|
</H2>
|
|
|
|
<P>Here you will find information about functions related with menus and icons.</P>
|
|
|
|
<H3>Menus</H3>
|
|
|
|
<P>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.</P>
|
|
<P>Menus are initialized with <CODE>DoMenu</CODE> and then Kernal takes care for everything. Your code
|
|
(called from event handler) should be a function without parameters, returning void. You should
|
|
use <CODE>DoPreviousMenu</CODE> or <CODE>GotoFirstMenu</CODE> at least once in its code to have the screen clean.</P>
|
|
|
|
<H3>DoMenu</H3>
|
|
|
|
<P><CODE>void DoMenu (struct menu *myMenu)</CODE></P>
|
|
<P>This function initializes GEOS menu processor and exits. See <CODE>DoMenu structure</CODE> 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 <CODE>DoMenu</CODE>.</P>
|
|
|
|
<H3>ReDoMenu</H3>
|
|
|
|
<P><CODE>void ReDoMenu (void)</CODE></P>
|
|
<P>This simply redraws the menu at lowest level. It works like calling <CODE>DoMenu</CODE> again with
|
|
the same parameters.</P>
|
|
|
|
<H3>RecoverMenu</H3>
|
|
|
|
<P><CODE>void RecoverMenu (void)</CODE></P>
|
|
<P>This function erases current menu from the screen. It doesn't change the menu level.</P>
|
|
|
|
<H3>RecoverAllMenus</H3>
|
|
|
|
<P><CODE>void RecoverAllMenus (void)</CODE></P>
|
|
<P>This calls <CODE>RecoverMenu</CODE> and erases all menus from the screen. Then the menu level is
|
|
set to 0 (topmost).</P>
|
|
|
|
<H3>DoPreviousMenu</H3>
|
|
|
|
<P><CODE>void DoPreviousMenu (void)</CODE></P>
|
|
<P>This functions causes menu processor to go back one menu level. You should use it in menu
|
|
handler code to have the screen clean.</P>
|
|
|
|
<H3>GotoFirstMenu</H3>
|
|
|
|
<P><CODE>void GotoFirstMenu (void)</CODE></P>
|
|
<P>This one jumps back to the topmost menu. If there is only menu and submenu it works the
|
|
same as <CODE>DoPreviousMenu</CODE>.</P>
|
|
|
|
<H3>Icon Functions</H3>
|
|
|
|
<P>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 <CODE>ClearMouseMode</CODE>
|
|
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.</P>
|
|
|
|
<H3>DoIcons</H3>
|
|
|
|
<P><CODE>void DoIcons (struct icontab *myIconTab)</CODE></P>
|
|
<P>This function initializes all icons that are present on the screen at once. For more information
|
|
look at <CODE>Icons</CODE> chapter in this manual.</P>
|
|
|
|
<H2><A NAME="ss3.3">3.3</A> <A HREF="geos.html#toc3.3">DialogBoxes</A>
|
|
</H2>
|
|
|
|
<P>This chapter covers the most powerful GEOS user interface function - <CODE>DoDlgBox</CODE>.</P>
|
|
|
|
<H3>GEOS standard</H3>
|
|
|
|
<H3>DoDlgBox</H3>
|
|
|
|
<P><CODE>char DoDlgBox (char *dialogString)</CODE></P>
|
|
<P>DialogBox returns one byte. It can be the value of one of six standard icons (see <CODE>gdlgbox.h</CODE>)
|
|
or whatever closing routine passes. Register <CODE>r0L</CODE> also contains this value.</P>
|
|
<P>Read structures chapter for the specs of the <CODE>dialogString</CODE>.</P>
|
|
|
|
<H3>RstrFrmDialogue</H3>
|
|
|
|
<P><CODE>char RstrFrmDialogue</CODE></P>
|
|
<P>This function called from within DialogBox event immediately closes the DialogBox and returns
|
|
the owner ID (or whatever caller has in the .A register).</P>
|
|
|
|
<H3>GEOSLib extensions</H3>
|
|
|
|
<P>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.</P>
|
|
|
|
<H3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk</H3>
|
|
|
|
<P><CODE>char DlgBoxYesNo (char *line1, char *line2)</CODE></P>
|
|
<P><CODE>char DlgBoxOkCancel (char *line1, char *line2)</CODE></P>
|
|
<P><CODE>void DlgBoxOk (char *line1, char *line2)</CODE></P>
|
|
<P>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 <CODE>DlgBoxYesNo</CODE> it can only be <CODE>YES</CODE> or <CODE>NO</CODE>.
|
|
You can pass an empty string or NULL to get a blank line.</P>
|
|
|
|
<H3>DlgBoxGetString</H3>
|
|
|
|
<P><CODE>char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)</CODE></P>
|
|
<P>This function prompts user for entering a string of at most <CODE>strlen</CODE> characters. It is returned
|
|
in <CODE>string</CODE>. The two given lines of text are shown above the input line. Please remember
|
|
that there is also <CODE>CANCEL</CODE> icon in the DialogBox and you should test if user confirmed his
|
|
input or gave up. The <CODE>string</CODE> is also shown so you can place default input there or remember
|
|
to place <CODE>NULL</CODE> at start.</P>
|
|
|
|
<H3>DlgBoxFileSelect</H3>
|
|
|
|
<P><CODE>char DlgBoxFileSelect (char *class, char filetype, char *filename)</CODE></P>
|
|
<P>This routine is the standard file selector. It can return <CODE>OPEN</CODE>, <CODE>CANCEL</CODE> or disk error
|
|
on reading the directory or opening the disk.
|
|
There is also <CODE>DISK</CODE> icon shown, but it is handled internally. You pass as input parameters
|
|
<CODE>filetype</CODE> and pointer to string containing the first part of file's class. If this string is
|
|
empty (<CODE>NULL</CODE> at the start), then all files with given filetype will be shown.</P>
|
|
<P>At present this file selector handles only first 16 files of given type and supports only one
|
|
(current) drive.</P>
|
|
|
|
<H3>MessageBox</H3>
|
|
|
|
<P><CODE>char MessageBox (char mode, const char *format, ...)</CODE></P>
|
|
<P>This function is a more general one. It works very much like <CODE>printf</CODE> in a
|
|
box. The only difference is <CODE>mode</CODE> parameter which allows for placing
|
|
default icons (see <CODE>gdlgbox.h</CODE> for list of possible <CODE>MB_</CODE> values).
|
|
Any too wide text will be clipped to the size of the default window. If mode
|
|
parameter is invalid or equal to <CODE>MB_EMPTY</CODE> then the window will be closed
|
|
after a click. Otherwise the user must choose an icon.</P>
|
|
<P>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.</P>
|
|
<P>Note: the formatted text <EM>cannot exceed</EM> 255 bytes in length, there is no check
|
|
for that.</P>
|
|
|
|
<H2><A NAME="ss3.4">3.4</A> <A HREF="geos.html#toc3.4">Mouse, Sprites and Cursors</A>
|
|
</H2>
|
|
|
|
<P>You will find here functions related to sprite and mouse drawing and handling.</P>
|
|
|
|
<H3>Mouse related functions</H3>
|
|
|
|
<P>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).</P>
|
|
|
|
<H3>StartMouseMode</H3>
|
|
|
|
<P><CODE>void StartMouseMode (void)</CODE></P>
|
|
<P>This function initializes mouse vectors - <CODE>mouseVector</CODE> and <CODE>mouseFaultVec</CODE>, and then
|
|
calls <CODE>MouseUp</CODE>.</P>
|
|
|
|
<H3>ClearMouseMode</H3>
|
|
|
|
<P><CODE>void ClearMouseMode (void)</CODE></P>
|
|
<P>This function disables all mouse activities - icons and menus stop to respond to mouse events,
|
|
but they are not cleared from the screen.</P>
|
|
|
|
<H3>MouseUp and MouseOff</H3>
|
|
|
|
<P><CODE>void MouseUp (void)</CODE></P>
|
|
<P><CODE>void MouseOff (void)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>IsMseInRegion</H3>
|
|
|
|
<P><CODE>char IsMseInRegion (struct window *myWindow)</CODE></P>
|
|
<P>This function tests if mouse pointer is actually in given range of screen. See <CODE>gsprite.h</CODE> for
|
|
description of bits in return values - they describe the position in detail.</P>
|
|
|
|
<H3>Sprites</H3>
|
|
|
|
<P>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.</P>
|
|
|
|
<H3>DrawSprite</H3>
|
|
|
|
<P><CODE>void DrawSprite (char sprite, char *mySprite)</CODE></P>
|
|
<P>This function initializes the sprite data. <CODE>mySprite</CODE> is a 63-byte table with bitmap data, which
|
|
is copied to system sprite area (at <CODE>sprpic</CODE> - see <CODE>gsym.h</CODE>). Hardware sprite registers are
|
|
not initialized and sprite is not yet visible.</P>
|
|
|
|
<H3>PosSprite</H3>
|
|
|
|
<P><CODE>void PosSprite (char sprite, struct pixel *myPixel)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>EnablSprite and DisablSprite</H3>
|
|
|
|
<P><CODE>void EnablSprite (char sprite)</CODE></P>
|
|
<P><CODE>void DisablSprite (char sprite)</CODE></P>
|
|
<P>These two functions are responsible for making the sprite visible or not.</P>
|
|
|
|
<H3>Cursors and Console</H3>
|
|
|
|
<H3>InitTextPrompt</H3>
|
|
|
|
<P><CODE>void InitTextPrompt (char height)</CODE></P>
|
|
<P>This function initializes sprite 1 for text prompt with given <CODE>height</CODE>. This parameter can be in
|
|
range 1-48.</P>
|
|
|
|
<H3>PromptOn and PromptOff</H3>
|
|
|
|
<P><CODE>void PromptOn (struct pixel *myPixel)</CODE></P>
|
|
<P><CODE>void PromptOff (void)</CODE></P>
|
|
<P>The first function places text prompt in given place and enables blinking.
|
|
The second one is pretty self-explanatory.</P>
|
|
|
|
<H3>GetNextChar</H3>
|
|
|
|
<P><CODE>char GetNextChar (void)</CODE></P>
|
|
<P>This function gets next character from the keyboard queue. If the queue is empty it returns
|
|
<CODE>NULL</CODE>, otherwise you receive true ASCII code of a character or value of special (function)
|
|
key. See <CODE>gsprite.h</CODE> for list of them.</P>
|
|
|
|
<H2><A NAME="ss3.5">3.5</A> <A HREF="geos.html#toc3.5">Disk</A>
|
|
</H2>
|
|
|
|
<P>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.</P>
|
|
<P>For some purposes you might consider using <CODE>dio.h</CODE> interface to disk access. It is native.</P>
|
|
<P>All GEOS disk functions return error code in X register. In some cases this is returned by
|
|
GEOSLib function (if its type is <CODE>char</CODE>), but in all cases last error is saved in <CODE>__oserror</CODE>
|
|
location. If it is nonzero - an error occured. See <CODE>gdisk.h</CODE> for the list of possible errorcodes.
|
|
You need to include <CODE>errno.h</CODE> to get <CODE>__oserror</CODE>, together with standard <CODE>errno</CODE>. The
|
|
latter gives less verbose, but still usable information and can be used with <CODE>strerror</CODE>.
|
|
Probably you will get more information using <CODE>_stroserror</CODE> in similar way.</P>
|
|
<P>For passing parameters use almost always pointer to your data e.g. <CODE>ReadBuff (&myTrSe)</CODE>.</P>
|
|
|
|
<H3>Buffer functions</H3>
|
|
|
|
<P>These functions are taking single data sector (256 bytes) to read or write on a disk.</P>
|
|
|
|
<H3>ReadBuff and Writebuff</H3>
|
|
|
|
<P><CODE>char ReadBuff (struct tr_se *myTrSe)</CODE></P>
|
|
<P><CODE>char WriteBuff (struct tr_se *myTrSe)</CODE></P>
|
|
<P>These functions read and write sector placed at <CODE>diskBlkBuf</CODE>.</P>
|
|
|
|
<H3>GetBlock and ReadBlock</H3>
|
|
|
|
<P><CODE>char GetBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
|
|
<P><CODE>char ReadBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
|
|
<P>These two functions are reading a single block directly at 256 byte array placed at <CODE>buffer</CODE>.
|
|
The difference between them is that <CODE>GetBlock</CODE> will initialize TurboDos in drive if it was not
|
|
enabled. <CODE>ReadBlock</CODE> assumes that it is already enabled thus being slightly faster.</P>
|
|
|
|
<H3>PutBlock, WriteBlock, VerWriteBlock</H3>
|
|
|
|
<P><CODE>char PutBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
|
|
<P><CODE>char WriteBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
|
|
<P><CODE>char VerWriteBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
|
|
<P>Similar to previous but needed for writing the disk. <CODE>VerWriteBlock</CODE> verifies the data after
|
|
writing. In case of error five tries are attempted before error code is returned.</P>
|
|
|
|
<H3>Directory header</H3>
|
|
|
|
<P>Functions described here are operating on <CODE>curDirHeader</CODE> where current disk header is stored.
|
|
On larger capacity drives (than 1541) the second part of directory header in <CODE>dir2Head</CODE>.</P>
|
|
|
|
<H3>GetPtrCurDkNm</H3>
|
|
|
|
<P><CODE>void GetPtrCurDkNm (char *diskName)</CODE></P>
|
|
<P>This function fills given character string with the name of current disk. It is converted to C
|
|
standard - string is terminated with <CODE>NULL</CODE> character instead of code 160 as in Commodore DOS.
|
|
Note that passed pointer must point to an array of at least 17 bytes.</P>
|
|
|
|
<H3>GetDirHead and PutDirHead</H3>
|
|
|
|
<P><CODE>char GetDirHead (void)</CODE></P>
|
|
<P><CODE>char PutDirHead (void)</CODE></P>
|
|
<P>These functions are reading and writing the directory header. You should use <CODE>GetDirHead</CODE> before
|
|
using any functions described below, and you should use <CODE>PutDirHead</CODE> to save the changes on the
|
|
disk. Otherwise they will be lost. Operating area is the <CODE>curDirHead</CODE>.</P>
|
|
|
|
<H3>CalcBlksFree</H3>
|
|
|
|
<P><CODE>unsigned CalcBlksFree (void)</CODE></P>
|
|
<P>This function returns the number of free blocks on current disk. It is counted using data in
|
|
<CODE>curDirHead</CODE> so you must initialize the disk before calling it.</P>
|
|
|
|
<H3>ChkDskGEOS</H3>
|
|
|
|
<P><CODE>char ChkDskGEOS (void)</CODE></P>
|
|
<P>This functions checks <CODE>curDirHead</CODE> for GEOS Format identifier. It returns either true or false,
|
|
and also sets <CODE>isGEOS</CODE> properly. You must initialize the disk before using this.</P>
|
|
|
|
<H3>SetGEOSDisk</H3>
|
|
|
|
<P><CODE>char SetGEOSDisk (void)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>FindBAMBit</H3>
|
|
|
|
<P><CODE>char FindBAMBit (struct tr_se *myTrSe)</CODE></P>
|
|
<P>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:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
#define BlockInUse FindBAMBit
|
|
...
|
|
if (!BlockInUse(&myTrSe)) {
|
|
... block not allocated ...
|
|
}
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>Anyway, I feel that this function is too low-level.</P>
|
|
|
|
<H3>BlkAlloc and NxtBlkAlloc</H3>
|
|
|
|
<P><CODE>char BlkAlloc (struct tr_se output[], unsigned length)</CODE></P>
|
|
<P><CODE>char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[], unsigned length)</CODE></P>
|
|
<P>Both functions are allocating enough disk sectors to fit the number of <CODE>length</CODE> in them. You
|
|
will find output in <CODE>output</CODE> which is table of <CODE>struct tr_se</CODE>. 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 <CODE>fileTrScTab</CODE>, which is a predefined table.</P>
|
|
<P>The difference between those two is that <CODE>NextBlkAlloc</CODE> will start allocating from given sector,
|
|
and <CODE>BlkAlloc</CODE> starts from the first nonused sector.</P>
|
|
<P>You need to use <CODE>PutDirHead</CODE> later to save any changes in BAM.</P>
|
|
|
|
<H3>FreeBlock</H3>
|
|
|
|
<P><CODE>char FreeBlock (struct tr_se *myTrSe)</CODE></P>
|
|
<P>Simply deallocates a block in BAM. You need to update BAM with <CODE>PutDirHead</CODE>.</P>
|
|
|
|
<H3>SetNextFree</H3>
|
|
|
|
<P><CODE>struct tr_se SetNextFree (struct tr_se *myTrSe)</CODE></P>
|
|
<P>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 <CODE>struct tr_se</CODE> you have to
|
|
cast both variables to <CODE>unsigned</CODE>. E.g.
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
struct tr_se myTrSe;
|
|
...
|
|
(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe);
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>In this example <CODE>otherTrSe</CODE> can be replaced by <CODE>myTrSe</CODE>.</P>
|
|
<P>Note: you <EM>must</EM> use casting to have correct values.</P>
|
|
|
|
<H3>Low-level disk IO</H3>
|
|
|
|
<P>Functions described here are more usable in kernal or drivers code, less common in applications,
|
|
but who knows, maybe someone will need them.</P>
|
|
|
|
<H3>EnterTurbo, ExitTurbo, PurgeTurbo</H3>
|
|
|
|
<P><CODE>void EnterTurbo (void)</CODE></P>
|
|
<P><CODE>void ExitTurbo (void)</CODE></P>
|
|
<P><CODE>void PurgeTurbo (void)</CODE></P>
|
|
<P>These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit
|
|
more usable. <CODE>EnterTurbo</CODE> 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. <CODE>ExitTurbo</CODE> 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 <CODE>InitForIO</CODE>. You don't have to worry about speed.
|
|
<CODE>EnterTurbo</CODE> will only enable TurboDos (no code transfer) if TurboDos was disabled with
|
|
<CODE>ExitTurbo</CODE>. <CODE>PurgeTurbo</CODE> acts different from <CODE>ExitTurbo</CODE> - it not only disables TurboDos,
|
|
but also removes it from drive RAM (not quite true, but it works like that). After using
|
|
<CODE>PurgeTurbo</CODE> the next call to <CODE>EnterTurbo</CODE> will reload drive RAM.</P>
|
|
|
|
<H3>ChangeDiskDevice</H3>
|
|
|
|
<P><CODE>char ChangeDiskDevice (char newDevice)</CODE></P>
|
|
<P>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 <CODE>newDevice</CODE> 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.</P>
|
|
|
|
<H3>Disk Initialization</H3>
|
|
|
|
<P>GEOS has two functions for initialization ('logging in' as they say on CP\M) the disk.</P>
|
|
<H3>OpenDisk</H3>
|
|
|
|
<P><CODE>char OpenDisk (void)</CODE></P>
|
|
<P>This function initializes everything for a new disk. It loads and enables TurboDos if needed.
|
|
Then the disk is initialized with <CODE>NewDisk</CODE>. Next, <CODE>GetDirHead</CODE> initializes <CODE>curDirHead</CODE>.
|
|
Disk names are compared and if they differ then disk cache on REU is cleared. Finally format is
|
|
checked with <CODE>ChkDkGEOS</CODE> and disk name is updated in internal tables.</P>
|
|
|
|
<H3>NewDisk</H3>
|
|
|
|
<P><CODE>char NewDisk (void)</CODE></P>
|
|
<P>This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.</P>
|
|
|
|
<H2><A NAME="ss3.6">3.6</A> <A HREF="geos.html#toc3.6">Files</A>
|
|
</H2>
|
|
|
|
<P>This section cover GEOS file interface.</P>
|
|
|
|
<H3>Directory handling</H3>
|
|
|
|
<P>Functions described here are common for SEQ and VLIR structures.</P>
|
|
|
|
<H3>Get1stDirEntry and GetNxtDirEntry</H3>
|
|
|
|
<P><CODE>struct filehandle *Get1stDirEntry (void)</CODE></P>
|
|
<P><CODE>struct filehandle *GetNxtDirEntry (void)</CODE></P>
|
|
<P>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 <CODE>unsigned</CODE> - as in <CODE>SetNextFree</CODE>
|
|
function or read directly after call to those two functions from <CODE>r5</CODE>. Current sector number
|
|
is in <CODE>r1</CODE> and sector data itself is in <CODE>diskBlkBuf</CODE>.</P>
|
|
|
|
<H3>FindFile</H3>
|
|
|
|
<P><CODE>char FindFile (char *fName)</CODE></P>
|
|
<P>This function scans whole directory for the given filename. It returns either 0 (success) or 5
|
|
(FILE_NOT_FOUND, defined in <CODE>gdisk.h</CODE>) or any other fatal disk read error. After successful
|
|
<CODE>FindFile</CODE> you will have <CODE>struct filehandle</CODE> at <CODE>dirEntryBuf</CODE> filled with file's data and
|
|
other registers set as described in <CODE>GetNxtDirEntry</CODE>.</P>
|
|
|
|
<H3>FindFTypes</H3>
|
|
|
|
<P><CODE>char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)</CODE></P>
|
|
<P>This function scans directory and fills a table at <CODE>buffer</CODE> with <CODE>char [17]</CODE> entries.
|
|
<CODE>fType</CODE> is GEOS type of searched files and <CODE>classTxt</CODE> 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 <CODE>NULL</CODE> as
|
|
<CODE>classTxt</CODE>. Be warned that for searching <CODE>NON_GEOS</CODE> files must pass <CODE>NULL</CODE> as <CODE>classTxt</CODE>.
|
|
<CODE>fMaxNum</CODE> is the maximal number of found files, thus the <CODE>buffer</CODE> must
|
|
provide area of size equal to <CODE>17 * fMaxNum</CODE>.
|
|
This function returns the number of found files, ranging from 0 to number passed as <CODE>fMaxNum</CODE>.
|
|
Return value can be also restored from <CODE>r7H</CODE>.</P>
|
|
|
|
<H3>DeleteFile</H3>
|
|
|
|
<P><CODE>char DeleteFile (char *fName)</CODE></P>
|
|
<P>This function deletes a file by its name. It works for SEQ and VLIR files.</P>
|
|
|
|
<H3>RenameFile</H3>
|
|
|
|
<P><CODE>char RenameFile (char *oldName, char *newName)</CODE></P>
|
|
<P>I think it is obvious...</P>
|
|
|
|
<H3>GetFHdrInfo</H3>
|
|
|
|
<P><CODE>char GetFHdrInfo (struct filehandle *myFile)</CODE></P>
|
|
<P>This function loads the file header into <CODE>fileHeader</CODE> buffer. Using after e.g. <CODE>FindFile</CODE>
|
|
you can pass address of <CODE>dirEntryBuf</CODE>.</P>
|
|
|
|
<H3>Common and SEQ structure</H3>
|
|
|
|
<P>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.</P>
|
|
|
|
<H3>GetFile</H3>
|
|
|
|
<P><CODE>char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)</CODE></P>
|
|
<P>This routine loads and runs a given file <CODE>fname</CODE>. The file must be one of following types:
|
|
<CODE>SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,</CODE> or <CODE>INPUT_DEVICE</CODE>. 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 <CODE>flag</CODE> has bit 0 set then load address is taken from <CODE>loadaddr</CODE>
|
|
and not from file header. In this case <CODE>APPLICATION</CODE> files will be only loaded, not executed.
|
|
This does not apply to <CODE>DESK_ACC</CODE>. If either bit 6 or 7 of <CODE>flag</CODE> are set, then 16 bytes from
|
|
<CODE>datadname</CODE> is copied to <CODE>dataDiskName</CODE> and 16 bytes from <CODE>datafname</CODE> goes to <CODE>dataFileName</CODE>
|
|
thus becoming parameters for the new application. Pass <CODE>NULL</CODE> as any unused parameter.</P>
|
|
|
|
<H3>ReadFile</H3>
|
|
|
|
<P><CODE>char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)</CODE></P>
|
|
<P>This function reads at most <CODE>fLength</CODE> bytes into <CODE>buffer</CODE> from chained sectors starting at
|
|
<CODE>myTrSe</CODE>.</P>
|
|
|
|
<H3>ReadByte</H3>
|
|
|
|
<P><CODE>char ReadByte (void)</CODE></P>
|
|
<P>This function returns next byte from a file. Before the first call to it you must load <CODE>r5</CODE>
|
|
with <CODE>NULL</CODE>, <CODE>r4</CODE> with sector buffer address and <CODE>r1</CODE> with track and sector of the
|
|
first block of a file.
|
|
Remember to not modify <CODE>r1</CODE>, <CODE>r4</CODE> and <CODE>r5</CODE>. These registers must be preserved between
|
|
calls to <CODE>ReadByte</CODE>.</P>
|
|
<P>Returned value is valid only if there was no error. End of file is marked as <CODE>BFR_OVERFLOW</CODE>
|
|
in <CODE>__oserror</CODE>, this is set when trying to read one byte after the end of file, in this case
|
|
returned value is invalid.</P>
|
|
|
|
<H3>SaveFile</H3>
|
|
|
|
<P><CODE>char SaveFile (char skip, struct fileheader *myHeader)</CODE></P>
|
|
<P><CODE>SaveFile</CODE> 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 <CODE>skip</CODE> 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
|
|
<CODE>0</CODE> there.</P>
|
|
<P>You have to declare a <CODE>struct fileheader</CODE> 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.</P>
|
|
<P>When saving sequential files two most important fields in <CODE>struct fileheader</CODE> are <CODE>fileheader.load_address</CODE>
|
|
and <CODE>fileheader.end_address</CODE>.</P>
|
|
|
|
<H3>FreeFile</H3>
|
|
|
|
<P><CODE>char FreeFile (struct tr_se myTable[])</CODE></P>
|
|
<P>This function deallocates all sectors contained in passed table.</P>
|
|
|
|
<H3>FollowChain</H3>
|
|
|
|
<P><CODE>char FollowChain(struct tr_se *myTrSe, char *buffer)</CODE></P>
|
|
<P>This function fills a <CODE>struct tr_se</CODE> table at <CODE>buffer</CODE> with sector numbers for chain of
|
|
sectors starting with <CODE>myTrSe</CODE>. You can pass such data (<CODE>buffer</CODE>) to e.g. <CODE>FreeFile</CODE>.</P>
|
|
|
|
<H3>VLIR structure</H3>
|
|
|
|
<P>Here are informations about VLIR files (called later as RecordFile) and functions.</P>
|
|
<P>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 (<CODE>tr_se</CODE> of such record is equal to <CODE>{NULL,$ff}</CODE>),
|
|
or even non-exist (<CODE>{NULL,NULL}</CODE>). Any other numbers represent starting track and sector of
|
|
particular file.</P>
|
|
<P>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 <CODE>fileTrScTab</CODE> (table of
|
|
128 <CODE>struct tr_se</CODE>) and from <CODE>VLIRInfo</CODE> (<CODE>struct VLIR_info</CODE>.
|
|
E.g. size of whole VLIR file can be retrieved by reading <CODE>VLIRInfo.fileSize</CODE>.</P>
|
|
|
|
<H3>OpenRecordFile</H3>
|
|
|
|
<P><CODE>char OpenRecordFile (char *fName)</CODE></P>
|
|
<P>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 <CODE>VLIRInfo</CODE> is initialized. VLIR track and sector table is
|
|
loaded at <CODE>fileTrScTab</CODE> and will be valid until call to <CODE>CloseRecordFile</CODE> so don't modify it.
|
|
You should <CODE>PointRecord</CODE> before trying to do something with file.</P>
|
|
|
|
<H3>CloseRecordFile</H3>
|
|
|
|
<P><CODE>char CloseRecordFile (void)</CODE></P>
|
|
<P>This function calls <CODE>UpdateRecordFile</CODE> and clears internal GEOS variables.</P>
|
|
|
|
<H3>UpdateRecordFile</H3>
|
|
|
|
<P><CODE>char UpdateRecordFile (void)</CODE></P>
|
|
<P>This function will check <CODE>VLIRInfo.fileWritten</CODE> flag and if it is set, then <CODE>curDirHead</CODE> is
|
|
updated along with size and date stamps in directory entry.</P>
|
|
|
|
<H3>PointRecord</H3>
|
|
|
|
<P><CODE>char PointRecord (char recordNumber)</CODE></P>
|
|
<P>This function will setup internal variables (and <CODE>VLIRInfo.curRecord</CODE>) and return the track and
|
|
sector of given record in <CODE>r1</CODE>. 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).</P>
|
|
|
|
<H3>NextRecord and PreviousRecord</H3>
|
|
|
|
<P><CODE>char NextRecord (void)</CODE></P>
|
|
<P><CODE>char PreviousRecord (void)</CODE></P>
|
|
<P>These two work like <CODE>PointRecord</CODE>. Names are self-explanatory.</P>
|
|
|
|
<H3>AppendRecord</H3>
|
|
|
|
<P><CODE>char AppendRecord (void)</CODE></P>
|
|
<P>This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector
|
|
table. It will also set <CODE>VLIRInfo.curRecord</CODE> to its number.</P>
|
|
|
|
<H3>DeleteRecord</H3>
|
|
|
|
<P><CODE>char DeleteRecord (void)</CODE></P>
|
|
<P>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 <CODE>UpdateRecordFile</CODE> to
|
|
commit changes.</P>
|
|
|
|
<H3>InsertRecord</H3>
|
|
|
|
<P><CODE>char InsertRecord (void)</CODE></P>
|
|
<P>This function will insert an empty record in place of <CODE>VLIRInfo.curRecord</CODE> and move all following
|
|
records in table one place forward (contents of <CODE>VLIRInfo.curRecord</CODE> after call to <CODE>InsertRecord</CODE>
|
|
can be found in <CODE>VLIRInfo.curRecord + 1</CODE>).</P>
|
|
|
|
<H3>ReadRecord and WriteRecord</H3>
|
|
|
|
<P><CODE>char ReadRecord (char *buffer, unsigned fLength)</CODE></P>
|
|
<P><CODE>char WriteRecord (char *buffer, unsigned fLength)</CODE></P>
|
|
<P>This function will load or save at most <CODE>fLength</CODE> bytes from currently pointed record into or from
|
|
<CODE>buffer</CODE>.</P>
|
|
|
|
<H2><A NAME="ss3.7">3.7</A> <A HREF="geos.html#toc3.7">Memory and Strings</A>
|
|
</H2>
|
|
|
|
<P>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 <CODE>memset, memcpy, strcpy</CODE> 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. <CODE>CopyString</CODE> instead of <CODE>strcpy</CODE>. It will work faster.</P>
|
|
<P>However some of them have slightly different calling convention (order of arguments to be specific),
|
|
so please check their syntax here before direct replacing.</P>
|
|
<P>Please note that the memory areas described here as <EM>strings</EM> are up to 255 characters (without
|
|
counting the terminating <CODE>NULL</CODE>), and <EM>regions</EM> can cover whole 64K of memory.</P>
|
|
|
|
<H3>CopyString</H3>
|
|
|
|
<P><CODE>void CopyString (char *dest, char *src)</CODE></P>
|
|
<P>This function copies string from <CODE>src</CODE> to <CODE>dest</CODE>, until it reaches <CODE>NULL</CODE>. <CODE>NULL</CODE>
|
|
is also copied.</P>
|
|
|
|
<H3>CmpString</H3>
|
|
|
|
<P><CODE>char CmpString (char *s1, char *s2)</CODE></P>
|
|
<P>This function compares string <CODE>s1</CODE> to <CODE>s2</CODE> for equality - this is case sensitive, and both
|
|
strings have to have the same length. It returns either <CODE>true</CODE> (non-zero) or <CODE>false</CODE> (zero).</P>
|
|
|
|
<H3>CopyFString and CmpFString</H3>
|
|
|
|
<P><CODE>void CopyFString (char length, char *dest, char *src)</CODE></P>
|
|
<P><CODE>char CmpFString (char length, char *s1, char *s2)</CODE></P>
|
|
<P>These two are similar to <CODE>CopyString</CODE> and <CODE>CmpString</CODE> except the fact, that you provide
|
|
the length of copied or compared strings. The strings can also contain several <CODE>NULL</CODE>
|
|
characters - they are not treated as delimiters.</P>
|
|
|
|
<H3>CRC</H3>
|
|
|
|
<P><CODE>unsigned CRC (char *src, unsigned length)</CODE></P>
|
|
<P>This function calculates the CRC checksum for given memory range. I don't know if it is
|
|
compatible with standard CRC routines.</P>
|
|
|
|
<H3>FillRam and ClearRam</H3>
|
|
|
|
<P><CODE>void *FillRam (char *dest, char value, unsigned length)</CODE></P>
|
|
<P><CODE>void *ClearRam (char *dest, unsigned length)</CODE></P>
|
|
<P>Both functions are filling given memory range. <CODE>ClearRam</CODE> fills with <CODE>0s</CODE>, while
|
|
<CODE>FillRam</CODE> uses given <CODE>value</CODE>. Be warned that these functions destroy <CODE>r0, r1 and
|
|
r2L</CODE> registers. These are aliases for <CODE>memset</CODE> and <CODE>bzero</CODE>, respectively.</P>
|
|
|
|
<H3>MoveData</H3>
|
|
|
|
<P><CODE>void *MoveData (char *dest, char *src, unsigned length)</CODE></P>
|
|
<P>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
|
|
<CODE>r0, r1 and r2</CODE> registers. This is also alias for <CODE>memcpy</CODE></P>
|
|
|
|
<H3>InitRam</H3>
|
|
|
|
<P><CODE>void InitRam (char *table)</CODE></P>
|
|
<P>This function allows to initialize multiple memory locations with single bytes or strings.
|
|
This is done with <CODE>table</CODE> where everything is defined. See structures chapter for description of
|
|
<CODE>InitRam's</CODE> command string.</P>
|
|
|
|
<H3>Stash, Fetch, Swap, and VerifyRAM</H3>
|
|
|
|
<P><CODE>void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
|
|
<P><CODE>void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
|
|
<P><CODE>void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
|
|
<P><CODE> char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)</CODE></P>
|
|
<P>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 <CODE>ramExpSize</CODE>. You have to do it before
|
|
using any of these functions.</P>
|
|
|
|
<H2><A NAME="ss3.8">3.8</A> <A HREF="geos.html#toc3.8">Processes and Multitasking</A>
|
|
</H2>
|
|
|
|
<P>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.</P>
|
|
|
|
<H3>InitProcesses</H3>
|
|
|
|
<P><CODE>void InitProcesses (char number, struct process *processTab)</CODE></P>
|
|
<P>This is the main initialization routine. After calling it processes are set up, but not
|
|
enabled. The parameters for <CODE>InitProcesses</CODE> are:
|
|
<UL>
|
|
<LI><CODE>number</CODE> - number of processes</LI>
|
|
<LI><CODE>processTab</CODE> - table of <CODE>struct process</CODE>, with size equal to <CODE>number</CODE></LI>
|
|
</UL>
|
|
</P>
|
|
<P>Single task is described by entry in <CODE>processTab</CODE>, it contains two values - <CODE>pointer</CODE> to
|
|
task function and number of <CODE>jiffies</CODE> which describe the delay between calls to task. On PAL
|
|
systems there are 50 jiffies per second, while on NTSC there are 60.</P>
|
|
<P>The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
|
|
if <CODE>processTab</CODE> would be too large it would overwrite existing data in GEOS space.</P>
|
|
<P>There's one important thing - the last entry in <CODE>processTab</CODE> has to be <CODE>NULL,NULL</CODE>, so the
|
|
maximum size of <CODE>processTab</CODE> is equal to 21.</P>
|
|
<P>See description of <CODE>process</CODE> structure for more detailed discussion on this.</P>
|
|
|
|
<H3>RestartProcess and EnableProcess</H3>
|
|
|
|
<P><CODE>void RestartProcess (char processNumber)</CODE></P>
|
|
<P><CODE>void EnableProcess (char processNumber)</CODE></P>
|
|
<P>These two functions start the task counter. <CODE>RestartProcess</CODE> for each process should be called
|
|
after <CODE>InitProcesses</CODE>, because it resets all flags and counters and it starts the counters.</P>
|
|
<P><CODE>RestartProcess</CODE> enables counters and sets their initial value to that given in <CODE>processTab</CODE>.</P>
|
|
<P><CODE>EnableProcess</CODE> forces given process to execute by simulating the timer running out of time.</P>
|
|
|
|
<H3>BlockProcess and UnBlockProcess</H3>
|
|
|
|
<P><CODE>void BlockProcess (char processNumber)</CODE></P>
|
|
<P><CODE>void UnBlockProcess (char processNumber)</CODE></P>
|
|
<P><CODE>BlockProcess</CODE> disables the execution of given process, but this does not disable the timers.
|
|
It means that if you call <CODE>UnBlockProcess</CODE> before timer runs out, the process will be executed.</P>
|
|
<P><CODE>UnBlockProcess</CODE> does the opposite.</P>
|
|
|
|
<H3>FreezeProcess and UnFreezeProcess</H3>
|
|
|
|
<P><CODE>void FreezeProcess (char processNumber)</CODE></P>
|
|
<P><CODE>void UnFreezeProcess (char processNumber)</CODE></P>
|
|
<P><CODE>FreezeProcess</CODE> disables timer for given process. <CODE>UnFreezeProcess</CODE> does the opposite.
|
|
This is not equal to <CODE>RestartProcess</CODE> as timers are not reloaded with initial value.</P>
|
|
|
|
<H3>Sleep</H3>
|
|
|
|
<P><CODE>void Sleep (unsigned jiffies)</CODE></P>
|
|
<P>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
|
|
<CODE>sleep</CODE> function from <CODE>unistd.h</CODE>.</P>
|
|
|
|
<H2><A NAME="ss3.9">3.9</A> <A HREF="geos.html#toc3.9">System Functions</A>
|
|
</H2>
|
|
|
|
<H3>FirstInit</H3>
|
|
|
|
<P><CODE>void FirstInit (void)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>InitForIO and DoneWithIO</H3>
|
|
|
|
<P><CODE>void InitForIO (void)</CODE></P>
|
|
<P><CODE>void DoneWithIO (void)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>MainLoop</H3>
|
|
|
|
<P><CODE>void MainLoop (void)</CODE></P>
|
|
<P>Returns control to the system. Any code between call to <CODE>MainLoop</CODE> and the end of current
|
|
function will never be executed. When in <CODE>MainLoop</CODE> 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.</P>
|
|
|
|
<H3>EnterDeskTop</H3>
|
|
|
|
<P><CODE>void EnterDeskTop (void)</CODE></P>
|
|
<P>This is an alias for <CODE>exit(0)</CODE> so you will never burn yourself. Anyway, you should not
|
|
use it. Always use <CODE>exit()</CODE> instead. Library destructors and functions registered with
|
|
<CODE>atexit()</CODE> are called.</P>
|
|
|
|
<H3>ToBASIC</H3>
|
|
|
|
<P><CODE>void ToBASIC (void)</CODE></P>
|
|
<P>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.</P>
|
|
<P><EM>WARNING:</EM> library destructors and functions registered with <CODE>atexit()</CODE> will not be called
|
|
so it is quite unsafe way to finish your program.</P>
|
|
|
|
<H3>Panic</H3>
|
|
|
|
<P><CODE>void Panic (void)</CODE></P>
|
|
<P>This calls system's <CODE>Panic</CODE> handler - it shows dialog box with message
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
System error at:xxxx
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
where <CODE>xxxx</CODE> is last known execution address (caller). By default this is bound to <CODE>BRK</CODE>
|
|
instruction, but it might be usable in debugging as kind of <CODE>assert</CODE>. (Note that <CODE>assert</CODE>
|
|
is available as a separate function and will give you more information than that).</P>
|
|
<P>System is halted after call to <CODE>Panic</CODE> which means that library destructors will not be
|
|
called and some data may be lost (no wonder you're panicking).</P>
|
|
|
|
<H3>CallRoutine</H3>
|
|
|
|
<P><CODE>void CallRoutine (void *myFunct)</CODE></P>
|
|
<P>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 <CODE>NULL</CODE>. This is the main functionality of this function -
|
|
you don't need to check if the pointer is valid.</P>
|
|
|
|
<H3>GetSerialNumber</H3>
|
|
|
|
<P><CODE>unsigned GetSerialNumber (void)</CODE></P>
|
|
<P>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.</P>
|
|
|
|
<H3>GetRandom</H3>
|
|
|
|
<P><CODE>char GetRandom (void)</CODE></P>
|
|
<P>This function returns a random number. It can be also read from <CODE>random</CODE> e.g.
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
a=random;
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
but by calling this function you are sure that the results will be always different.
|
|
<CODE>random</CODE> is updated once a frame (50Hz PAL) and on every call to <CODE>GetRandom</CODE>.</P>
|
|
<P>Note that it is not the same as <CODE>rand</CODE> function from the standard library. <CODE>GetRandom</CODE>
|
|
will give you unpredictable results (if IRQs would occur between calls to it) while
|
|
<CODE>rand</CODE> conforms to the standard and for given seed (<CODE>srand</CODE>) it always returns with the
|
|
same sequence of values.</P>
|
|
|
|
<H3>SetDevice</H3>
|
|
|
|
<P><CODE>void SetDevice (char device)</CODE></P>
|
|
<P>This function sets current device to given. It might be used together with <CODE>InitForIO</CODE>,
|
|
<CODE>DoneWithIO</CODE> and some Kernal routines. Unless new device is a disk drive this only sets
|
|
new value in <CODE>curDevice</CODE>, in other case new disk driver is loaded from REU or internal RAM.</P>
|
|
|
|
<H3>get_ostype</H3>
|
|
|
|
<P><CODE>char get_ostype (void)</CODE></P>
|
|
<P>This function returns GEOS Kernal version combined (by logical OR) with machine type. Read
|
|
<CODE>gsys.h</CODE> for definitions of returned values.</P>
|
|
|
|
<H3>get_tv</H3>
|
|
|
|
<P><CODE>char get_tv (void)</CODE></P>
|
|
<P>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 <CODE>graphMode & 0x80</CODE> which returns <CODE>0</CODE> for
|
|
40 columns and <CODE>0x80</CODE> 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 <CODE>get_ostype</CODE> to check it. Read <CODE>gsys.h</CODE> for
|
|
definitions of returned values.</P>
|
|
|
|
<HR>
|
|
<A HREF="geos-4.html">Next</A>
|
|
<A HREF="geos-2.html">Previous</A>
|
|
<A HREF="geos.html#toc3">Contents</A>
|
|
</BODY>
|
|
</HTML>
|