AN INTRODUCTION TO RELATIVE FILES

Edited By Steven C .  Peyrot

FROM :  MEMPHIS COMMODORE USERS CLUB

  Your Commodore 64 and 1541 disk drive provide you with the capability to program using random access files, or RELATIVE files, as Commodore calls them .  This lesson will present an introduction to relative files to help you get started using them .  They aren ' t very difficult to use, and provided with enough information, you will find they are a quick and efficient way of handling large amounts of information .  When we are talking about relative files  ( or sequential files ),  we are talking about DATA files, unlike PROGRAMfiles .  When you type in a BASIC program and type SAVE " filename ", 8, it is created on disk as a PROGRAMfile .  The file type will show up on the disk directory as PRG .  A program file contains BASIC program instructions that can be loaded into memory and executed by typing RUN .  Relative files, on the other hand, usually do not contain instructions to be executed by the computer, but rather INFORMATION like names, addresses, accounting records, etc .  that are meaningful to a human, and not to a computer .  Typically the operations we wish to perform on a data file are to retrieve data, add data, update data, or delete data .  All of these operations pertaining to relative files will be discussed . 

  Understanding relative files requires knowledge of the parts of a file in general :  A file is made up of RECORDS, which are made up of FIELDS, which are made up of CHARACTERS .  For example, we may wish to maintain a data file of customer addresses .  We might assign one record per customer .  Within each record, there would be several fields, each containg some piece of information about that customer, like name, address, telephone, etc .  Finally, each field would be made up of a fixed or variable number of characters ;  we may use 10 characters to contain the customer ' s last name, for example .  There are several reasons why relative files might be used .  The main reason is that they provide direct access .  This means that you can directly access the individual record desired, without having to read all of the records preceding it, as in a sequential file .  Another reason is that they require very little computer memory .  You can maintain a 160K relative file on disk easily with a 2K Basic program .  All of the data stays on disk, and you read and write individual records one at a time .  Thus, speed and low memory requirements make relative files a powerful, effective way to maintain large amounts of information . 

  NN HOW DO THEY WORK ? 

  Before you can use relative files, you have to understand how they are implemented on the Commodore 64 .  There are several rules you must be aware of to use them properly .  First, all records in a relative file must be the same length in bytes .  Since a character takes one byte of memory, you could also say that all the records in a relative file contain the same number of characters .  You specify the record length when you first create the file .  Once the record length has been set for a relative file, it cannot be changed .  For this reason, it is very important to plan your file record structures carefully before you create it .  The first character in the record is considered character number 1 . N It is possible to write starting at any point within a record, but it is important to realize that all the bytes from that point on to the end of the record will be re - written, or blanked out if the data you ' re writing is smaller than the area from the starting point to the end of the record .  Records can have a maximum size of 254 bytes .  If you need to use larger records, you can split the data into 2 or more records . 

  If you dividedN the data into 2 records, then all of the odd numbered records would represent the first half of the logical record and all of the even numbered records would be the second half of the logical record .  The largest number of records that you can have in a relative file is 65,535  ( 64K ),  although because of space limitations, each record in such a file would only be 2 characters long .  In order to understand how relative files are stored on disk, its helpful to understand how your disk is formatted .  When you first format a disk, the directory shows 664 free blocks, or sectors .  A sector is an area on disk 256 bytes long .  Each relative file record may use up to 254 bytes of a sector, explaining the limit on the record length .  Some of the sectors on a disk are used by the relative file as an index, basically a look - up table that shows what track and sector each record is on .  The index is what enables the disk drive to go directly to the correct location on disk for any particular record .  With the index using some of the disk space, it is still possible to fill a blank disk with 167,132 characters, the largest possible amount in a relative file .  The records in a relative file are numbered from 1 to n, where n is the highest record number in the file .  Read and write operations can occur in the same open file .  Only one relative file may be open at a time . 

  USING COMMAND / ERROR CHANNEL

  Channel 15 is the channel through which the commodore 64 and the 1541 disk drive communicate .  The 64 sends commands to the disk drive, and the disk drive sends back information or error codes to the 64, which can be read by the programmer to determine if a disk operation, like a read or a write, completed successfully .  The command channel is necessary for handling relative files, because when reading or writing records, the 64 sends a command to the disk drive to position the read / write head to the appropriate position on the disk surface to access the record .  If an error occurs, the familiar red blinking light will occur, and the channel can be read to determine what the error was and on which disk track and sector the error occurred .  The channel is read in the following manner : 

   INPUT # 15,E,E $, T,S

  E is the error code, E $  is the error description, T is the track where the error occurred, and S is the sector where the error occurred .  Reading the error channel clears it, and will cause the red light to stop blinking .  

  There are several common errors that occur when working with relative files .  When the disk operation has been performed successfully, a return code of 0 is returned by the disk drive to the 64 via channel 15 .  There are 2 other common codes . 

  The first is code 50, RECORD NOT PRESENT error, which occurs whenever you attempt to read or write a record that does not exist .  It is not necessarily always an error ;  in fact it will always occur when you first create a relative file, since at that point, no records exist .  Thus, this code can be ignored sometimes .  It will always inform you when a record with the record number specified could not found .  Another common error code is 51, OVERFLOW IN RECORD error .  This occurs when an attempt is made to write more data to a record than will fit, for example writing 21 characters to a file with a record length of 20 characters .  Its important to realize that you should always make the record size one byte larger than the data it is to hold, because a carriage return character is always added to a character string sent to the file . 

 N CREATING A RELATIVE FILE

  A relative file is usually created in the following manner :   A )  Open the file and establish its record length .   B )  Write the highest record to the file .  This will allocate all of the records in the file .  For example, writing record number 200 to a new relative file will automatically create records 1 - 200 .  It is best to create the entire file first, since it will save time, and it will also insure that all the records that will ever be needed have been created . 

C )  Close the file . 

  The OPEN command is used for opening relative files .  Before the file is opened, the command channel should be opened .  This is accomplished by the following :  OPEN15,8,15

  Next the file itself is opened .  Below is an example of opening a relative file with the name RELFILE . 1, with a record length of 50 bytes .  OPEN2,8,2 ," RELFILE . 1,L,CHR $( 50 )"  The format of the command is :  OPENfile number, device, channel number,  " filename, L, CHR $   ( record length )  

  Here the logical file number is 2, the device number is 8  ( the disk drive ),  and the channel number is 2 .  The channel number should be a number between 2 and 14, and its a good idea to use the same number as the file number, to make it easier to remember .  You need to remember the channel number because it will be used when reading and writing records to the file .  The L stands for LENGTH, and it tells the disk operating system that this is a relative file, and what follows as an argument to the CHR $  function will be the record length .  Here we have used CHR $( 50 )  to indicate that this file will have 50 - byte records .  When the file is opened subsequently after being created for normal read and write operations, specifying the record length is optional .  The file could be opened with the following sytax :  OPEN2,8,2 ," RELFILE . 1 " 

  Specifying the record length is absolutely necessary only when first creating the file . 

  The next thing to do is write the highest record in the file .  You dont have to do it this way, but it saves time and allocates all the space needed, as mentioned before .  When the records are created, their contents are initalized to CHR $( 255 ),  which displays as the PI symbol .  If you were to print out the contents of a relative file before storing any data, all of the records would print as PI symbols .  If you don ' t create all of the records in the beginning, then they are created as they are written, which can be a lot slower than simply allocating all of the records from the start .  Now that the command channel and the file are open, the POSITIONcommand is used to read or write the records . Its syntax is the following :   PRINT # 15 ," P "+ CHR $( 96 + channel number )   + CHR $( record high byte )+ CHR $( record low byte )+ CHR $( offset )  

  This sends a command to the disk drive to position the read / write head to the appropriate record .  The P stands for POSITION .  The channel number is the number we used when opening the file .   ( channel number 2 was used when opening this file ). 

  The next 2N numbersN represent the record number as a 2 byte number expressed in low byte / high byte format .  We will use RH %  to stand for the high byte and RL5 to stand for the low byte .  The low byte and high byte are calculated from record number RN by the following expression :   RH %= RN / 256 : RL %= RN -( 256 * RH %) 

  Finally, the offset term refers to the starting point, or offset, within the record from which the record is to be read or written .  Usually this value is 1 .  However, we could begin reading the data in a record at posion 8, for example, by using an offset of 8 .  This can be useful when working with fields .  An important point to be aware of is that when writing records, all of the bytes in the record from the starting point to the end of the record will be re - written or blanked out .  The way to avoid blanking out the remaining data in the record is to read in the whole record, update the field of interest in the string read in, then re - write the entire record .    Thus, the steps to follow when creating, reading, or writing to the file are the following : 

1 )  Open the command channel
2 )  Open the file
3 )  Read and write records as needed
4 )  Close the file
5 )  Close the command channel
 
TO CONTINUE THIS ARTICLE SEE RELATIVE FILES PART 2