Device 3 Details

Device channel 3 is used to access a disk file. Opening, reading, writing, and closing device 3 is more complicated than the other devices. The usual operations are as follows:

1. Opening Files. The FOpen intrinsic opens files for input or output. Here is the intrinsic prototype:

Handle:= FOpen(Filename, Mode);

FOpen opens a file and returns a "handle," which is an integer used to refer to the file. FOpen has two arguments: the address of a string giving the name of the file; and the mode, which is either 0 for input or 1 for output. The file name can include the drive and subdirectory path names. If these are omitted, the current default drive and subdirectory are used. If you output to device 3 without opening a file, output information is sent to the screen, and no error is detected.

2. Selecting Files. The FSet intrinsic is used to select which previously opened file is used with device channel 3. Here is the intrinsic prototype:

FSet(handle, mode);

The arguments are the Handle and the Mode. The Handle is the handle for a file that was previously opened using the FOpen intrinsic. It represents the file that will be assigned to device channel 3. The Mode argument is a single ASCII character that controls whether the file is used for input to device 3 or output from device 3. The following modes can be selected:

^I = Input

^O = Output

In standard XPL, the case of the command character controlled whether the specified file's I/O was buffered or not. In EXPL all files are buffered, so the case of the mode character is irrelevant.

3. Resetting Files. Using the OpenI and OpenO intrinsics with device channel 3 reset the file pointers to the beginning of the files. The prototypes are:

OpenI(3);        OpenO(3);

OpenI resets the input file pointer; OpenO resets the output file pointer.

4. Flushing Buffers. Using the Close intrinsic with device channel 3 flushes any accumulated bytes in the output buffer. It does not actually close the file. Here is the intrinsic prototype:

Close(3);

5. Closing Files. The FClose intrinsic closes a file that was opened with the FOpen intrinsic. Here is the intrinsic prototype:

FClose(handle);

The intrinsic flushes any buffers and closes the file specified by the handle argument.

6. Locate the End of a File. There are several methods for locating the end of a file depending on the circumstances.

Text Files. Text files are sometimes terminated with a control-Z ($1A), which is the standard End Of File (EOF) character. XPL also returns a control-Z if you attempt to read beyond the end of a file. (If the program attempts this a second time, a runtime I/O error occurs.) As a result, programs that are reading text files can look for the EOF character to determine that they have reached the end of the file.

Binary Files. When reading binary files, the program must know when to stop. It can get the size of the file from the GetFileSize intrinsic. A simpler way is to use XPL's error trapping intrinsics. By setting the Trap intrinsic's value to 3, you can block the program from generating an error if you read past the end of a file:

       Trap(3);

Then you can check the GetErr intrinsic for an I/O error, indicating that the program has read past the end of the file:

       if GetErr=3 then DoSomething;

If you use this method, note that an extra control-Z is returned at the end, and it is not part of the file.

6. Opening Files From the Command Line. You can retrieve filenames from the program's command line and use the names to open files. This is done using the CommandLine Intrinsic. Retrieving the command line enables you to write utility programs that can process files from the command prompt. For example, the following command line might be used with a program that converts all characters in a file to lowercase:

       LowCase Test1.txt Text2.txt

The file Test1.txt would be the input file and Text2.txt would be the output file. Click here to view an actual program that reads the command line to convert files to lowercase.