geos-3.html

cc65 的编译器文档

<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 simpliest 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(&amp;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 nonexistant 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>