Sequential File Access

In addition to accessing Reality items and attributes using the various file I/O commands, DataBasic allows you to open host files and individual Reality items for sequential access. Data is read starting from the beginning, making it unnecessary to read the entire file or item into memory.

When used with host files, this feature provides an alternative to directory view.

Once you have opened a file or item for sequential access, you can read and write lines or blocks of data.

Opening a File for Sequential Access

You open a host file or Reality item for sequential access using the OPENSEQ statement. For a host file, you must specify the full path of the file you wish to open and the name of a variable in which a reference to the opened file can be returned. For example, the following statement opens the file /usr/pauls/qa4 and returns a reference to the opened file in the variable SF1:

OPENSEQ "/usr/pauls/qa4" TO SF1 THEN NULL

To open a Reality item for sequential access, specify the required Reality file and item instead of a host file path. For example, the following statement opens the item 1991 in the file SALES:

OPENSEQ 'SALES','1991' TO SF1 THEN NULL

The opened item is locked to prevent access by other Reality users, and the current position (for reading and writing) is set to the beginning of the item.

If you wish, you can specify a record size to be used when reading and writing blocks of data. The following is the same as the previous example, except that a block size of 32 bytes is specified:

OPENSEQ "/usr/pauls/qa4",,32 TO SF1 THEN NULL

If the opened file does not exist, it will be created automatically. To prevent this, use the EXISTING keyword. For example:

OPENSEQ EXISTING "/usr/pauls/qa4" TO SF1 SETTING ERR ON ERROR
    IF ERR # 2420 THEN STOP
END THEN NULL

The file will then not be created until you write to it. Note that if the file does not exist, the ON ERROR clause, if any, is executed with the SETTING variable (ERR in this case) set to error 2420. If there is no ON ERROR clause, the DataBasic Debugger will be entered.

If you want to add data to an existing file, you can use the APPENDING keyword. For example:

OPENSEQ APPENDING "/usr/pauls/qa4" TO SF1 THEN NULL

This sets the current file position to the end of the file, ready to write the appended data. See also Writing to a Sequential File below.

When you have finished with a sequential file or item you must close it with the CLOSESEQ statement to ensure that the locks are released. For example:

CLOSESEQ SF1

Reading from a Sequential File

To read from a file or item that has been opened for sequential access, use the READSEQ and READBLK statements.

• READSEQ reads a line of text from the file or item, and moves the current file pointer to the start of the next line. In host files, lines are delimited by line feeds (UNIX) or carriage return/line feed (Windows), while in Reality items, they are delimited by attribute marks. For example, the following statement reads one line from the file referenced by the variable SF1 and assigns the data to the variable LINE:

  READSEQ LINE FROM SF1 ELSE PRINT "End of file"

  Note that the line delimiter is not included in the returned data.

• READBLK reads a block of data from the file or item (that is, a specified number of bytes), and moves the current file pointer to the start of the next block. You can specify the block size either when you open the file (with the OPENSEQ statement) or when you read the data. For example, the following statement reads 20 bytes from the file referenced by the variable SF1 and assigns the data to the variable DATA:

  READBLK DATA FROM SF1,20 ELSE PRINT "End of file"

  The next example is similar, but the number of bytes to be read was specified in the OPENSEQ statement:

  READBLK DATA FROM SF1 ELSE PRINT "End of file"

With both statements, the ELSE clause is executed if the end of the file is encountered. Under these circumstances, the data variable will contain any partial line or block from the end of the file.

Both READSEQ and READBLK can be used in LOOP constructs. The following example reads lines from the file or item referenced by the variable SF1 until the end of the file is reached; each line read is displayed on the screen:

LOOP WHILE READSEQ LINE FROM SF1 DO
    PRINT LINE
REPEAT
IF LINE # "" THEN PRINT LINE

In this case, exiting the loop at the end of the file is equivalent to executing an ELSE clause - the data variable will contain any partial line or block from the end of the file. The final line of the example ensures that this data is correctly processed.

Writing to a Sequential File

To write to a file or item that has been opened for sequential access, use the WRITESEQ and WRITEBLK statements.

• WRITESEQ writes a line of text to the file or item. A line delimiter (line feed, carriage return/line feed or an attribute mark as appropriate) is appended to the data. The following example writes a line of text contained in the variable LINE to the file referenced by the variable SF1:

  WRITESEQ LINE TO SF1 THEN NULL

• WRITEBLK writes a block of data to the file or item without appending a line delimiter. For example:

  WRITEBLK DATA TO SF1 THEN NULL

If you want to write fixed size records, specify a block size when you open the file. Then, if your data is shorter than this, it will be padded with spaces to a multiple of the specified length. If you are using WRITESEQ, the line delimiter will be appended to the padded data.

You can only write to a file or item that has been opened for sequential access if the current position is at the end of the file. This can be achieved as follows:

• Specify the APPENDING keyword when opening the file or item.

• Use the SEEK statement to move to the end of the file. For example:

  SEEK SF1,0,E

• Truncate the file or item at the current position using the WEOFSEQ statement.

Deleting a Sequential File

You can delete a file or item that has been opened for sequential access with the DELETESEQ statement.

Overwriting a Sequential File

If you want to completely replace the contents of a file or item that has been opened for sequential access, there are two methods you can use:

• The preferred method is to truncate at the start of the file or item before writing. For example:

  OPENSEQ "/usr/pauls/qa4" TO SF1 THEN
      WEOFSEQ SF1
  END
  WRITEBLK DATA TO SF1 THEN NULL
  CLOSESEQ SF1

• Alternatively, you can delete the file or item with the DELETESEQ statement and then write your new data to the same file. A new file will be automatically created. For example:

  OPENSEQ "/usr/pauls/qa4" TO SF1 THEN
      DELETESEQ SF1 THEN NULL
  END
  WRITEBLK DATA TO SF1 THEN NULL
  CLOSESEQ SF1

  Note that you do not need to close and reopen the file or item concerned.