GEOS CONVERT UTILITY FILE STRUCTURE

The GEOS convert program is used to convert GEOS VLIR and SEQ structure files
to Commodore SEQ structure files. Within the Commodore SEQ file which is
created, all of the GEOS-related information about the file is contained. This
includes the file's:

 - directory entry
 - header block
 - index table (if file is VLIR)
 - data blocks

Convert also will convert these "GEOS format in Commodore SEQ" files back to
their original form.

Whether Convert is processing a GEOS VLIR or SEQ file, the first two blocks of
the resulting Commodore SEQ file contain the same information:

block 1: bytes 0 and 1 contain standard next track and sector pointers(NTS)
         bytes 2 to 31 contain the file's directory entry, with the file's
         original name and time stamp.

block 2: bytes 0 and 1: NTS pointer
         bytes 2 to 255: bytes 2 to 255 of the file's header block.

When converting GEOS SEQ files, the rest of the blocks in the resulting
Commodore SEQ file are the data blocks from the GEOS SEQ file.

blocks 3, 4 etc:
         bytes 0 and 1: NTS pointer
         bytes 2 to 255: bytes 2 to 255 of block from original GEOS SEQ
         file.

last block:
         byte 0 = 0
         byte 1 = pointer to last byte used in this block (=$02 to $ff)

When converting GEOS VLIR files, the third block in the resulting Commodore SEQ
file contains an index table for the file:

block 3:  bytes 0 and 1: NTS pointer
          byte 2: number of blocks in VLIR record #0
          byte 3: number of bytes in last block of record #0
          bytes 4,5: # blocks/bytes in record #1
          ...and so on until:
          bytes 254 and 255: number of blocks/bytes for record#126


If one of the block/byte pairs is (0,0), then the record does not exist.  If a
pair is ($00,$ff) then the record is empty. The remaining blocks in the
Commodore SEQ file contain all of the VLIR records, appended end-to-end,
starting with the first existing record (usually record #0). Adding up all of
the "number of blocks" entries in the third block will give you the total
number of block which remain.

Thus if the VLIR file has two blocks in record #0, one block in record #4, and
null pointers (no blocks) for all other records, then the resulting Commodore
SEQ file will contain: 

Block 1:  directory entry
Block 2:  file header
Block 3:  blocks/bytes per record table
Block 4:  block #1 of record #0
Block 5:  block #2 of record #0
Block 6:  block #1 of record #4

Note that the conversion process does not create a new file, it simply modifies
the existing GEOS VLIR or SEQ file so that it conforms to the format of a
Commodore SEQ file. Using a GEOS VLIR file as an example, this process
involves:

1) Creating a new block to contain the file's directory entry, changing the
existing directory entry so that the pointer to the file's first block now
points to this new block. The NTS pointer in this new block will point to the
file's existing header block.

2) Changing the NTS pointer in the block containing the file header so that it
points to the file's index table block.

3) Changing the file's index table block so that it has accurate "number of
blocks/bytes" information for each record. Also, the NTS pointer in this block
is altered to point to the first block of the first record which exists.

4) Changing the NTS pointers in the first and last blocks of each record, so
that the records are appended into a string of blocks.

Also, think about the reverse process. Convert will take a Commodore SEQ file
which completely defines a GEOS VLIR or SEQ file and will convert it to the
correct structure. Software developers may find this useful; if you are using a
standard Commodore assembler which creates Commodore SEQ files, then if the
data is set up right, Convert can be used to turn the Commodore SEQ file into a
runnable GEOS VLIR or SEQ application! We will post a note in the future about
how to do this.