&F_READ(TYPE  VAR)

and command

     &FILE, ACTION, DATA, -OPTIONS

The string function &F_READ is used to read a file and the command &FILE is used for a variety of tasks. When reading or writing, files are referred by type and TYPE is this type. A TYPE is associated with a file when the file is opened. The string function will read a record from the file and store it in the variable VAR. The value returned by the function is .TRUE. if there is no more data to read and .FALSE. if there is more to read. To check to see if a file exists, you can use the string function:

     &INFO(FILE_EXISTS filename)

which returns TRUE if the file exists or FALSE if it does not.

With &FILE the DATA and -OPTIONS depend on the value of ACTION, and the valid values of ACTION are: MKDIR, RM, MV, CP, USE, ANS_DIRECTORY, OPEN, CLOSE, and WRITE. The first four ACTIONS do not have any options:

     &FILE MKDIR, A
     &FILE RM, A
     &FILE MV, A, B
     &FILE CP, A, B

where the MKDIR ACTION creates the directory A, the RM ACTION deletes the file A, the MV ACTION renames file A to B, and the CP ACTION copies file A to B.

The USE action is used to alter the default association of files and file TYPES. The syntax here is:

     &FILE, USE, TYPE, FILE_NAME

and TYPE is the type of file which will be altered. It is a either a user defined file type or type "PREFIX" of a channel. Also, FILE_NAME is the new file name which will be associated with the file type. When this option is exercised, the old file will be closed and the new one used until further notice.

The ANS_DIRECTORY action is used to alter the default association of files and file TYPES. The syntax here is:

     &FILE, ANS_DIRECTORY, DIR

where DIR is a directory in which the "answers" will be stored.

Before one can write to a file, it must be opened with the command:

     &FILE, OPEN, -TYPE, TYPE, -NAME, FILE_NAME

Here, TYPE is a handle you can associate with the file and FILE_NAME is the name of the file. The handle can be any name of up to eight characters and is used to read, write and close the file. Once a file has been opened, you can write to it with the command:

     &FILE, WRITE, TYPE, STRING

which writes the line STRING to the file with type of TYPE. After writing a file, you should close it with

     &FILE, CLOSE, TYPE, -OPTIONS

If you specify -DELETE then the file will be deleted.

You cannot read and write to a file at the same time. Instead it must be written, closed, reopened, and then read. As an example, consider

     &FILE OPEN -TYPE COW -NAME MILK_COWS
     &FILE WRITE COW Brown
     &FILE WRITE COW Black and White
     &FILE WRITE COW Holstein
     &FILE CLOSE COW
     &FILE OPEN -TYPE COW -NAME MILK_COWS
     &LOOP
     &EXIT &F_READ(COW VAR)
     &TYPE %VAR
     &ENDLOOP
     &FILE CLOSE COW

which writes three lines to a file named MILK_COWS and then reads them.