File Input & Output library

All channels have a default timeout associated with them. The default timeout is shared by all the jobs which use the channel. When the Channel was passed as command line parameter, it is adviceable to set the default timeout to a suitable value (as this will not be done if the channel was opened without using syslib). When a channel is opened with one of the IOOpen routines, the default timeout is set to FOREVER.

The IOOpenPath is a bit special. It can use paths which give a list of directories where the file should be searched. Such a path is a list of directories, separated by semicolons (';'). For example "win1_test_;flp1_" will first search the given filename as if it includes the device, then win1_test_ and then flp1_.

Both IOOpen and IOOpenPath allow you to use special escape symbols at the start of the filename. The default directories can be indicated with "$D" for the data, and "$P" for the program directory (both case dependent). Directory name can also start with the name of a "Global Variable", by preceding the name of the variable with a dollar character ('$'). If the name of the global variable includes underscores ('_'), then it should be given in quotes (the name should then not include quotes). When replacing "Global Variables" with their value, any ending underscore is always removed. The underscore after the name is copied though.

The io library is mostly oriented at file handling, but not with inquiries about directories (see dir library), and it also not concerned with windowing (see win library and ProWesS).

channel allocation
IOOpen
Stupid, back to the basics open routine.
IOOpenFor
IOOpenPath
Intelligent open, which uses a searchpath.
IOOpenPathFor
IOClose
Close a channel.
IODelete
Delete the file associated with the channel.
IOFormat
Format a device.
channel operators
IOGet
Get a byte from the channel.
IOPut
Send a byte to the channel.
IOGetBytes
Get multiple bytes from the channel.
IOPutBytes
Send multiple bytes to the channel.
IOPutRawBytes
Send multiple bytes to the channel. This function is similar to IOPutBytes, except that no translation is used on the bytes, independent of the flags which where used when the device/file was opened. It is only relevant for serial and parallel devices. If the device driver does not recognize this command, then it is identical to IOPutBytes. It is strongly recommended that this command is used to send binary data to printers.
IOPutString
Send a line to the channel ('\n' added). Returns number of bytes which are successfuly sent.
IOGetString
Get a line ('\0' or '\n' terminated) from the channel. A buffersize has to be given. If buffersize==N, and the first N-1 characters read are not '\0' or '\n', then a '\0' is appended to the string and ERR_BFFL returned.
IOTest
Check for pending input or eof on file.
IODone
See if all operations done (as files are buffered).
IOFlush
Make sure all write operations on a file are done.
IOTruncate
Truncate the file at the current position.
IOTimeOutGet
Get the current timeout value for the given channel.
IOTimeOutSet
Set the timeout value to use for the given channel.
IOPositionGet
Get current file position.
IOPositionSet
Set file position.
IOPositionMove
Move file position.
Take care !! first byte in file is at position zero ! These return ERR_EOF when at end of file, or when setting/moving being start or end of file. To move to the end of the file, you should use TO_END_OF_FILE as fileposition. Files are limited by the OS to 1GB.

The following calls are for directory device drivers only, they will return an error (ERR_NIMP) when used on ordinary device drivers (unless the driver handles them specially).

IOName
Get name and directory of channel.
IOLength
Get length of the file.
IOUpdateDateGet
Get update date.
IOUpdateDateSet
Set update date.
IOBackupDateGet
Get backup date.
IOBackupDateSet
Setbackup date.
IOVersionGet
Get file version, ERR_IPAR on directories.
IOVersionSet
Set file version, ERR_IPAR on directories.
IOFileTypeGet
Get file type.
IOFileTypeSet
Set file type.
IODataSpaceGet
Get dataspace for file.
IODataSpaceSet
Set dataspace for file.
IOFileInfoGet
Get all the file information at once.
IOFileInfoSet
Set the type, version, dataspace, update and backup time of a file all at once. The structure which is passed also contains entries for file name and size but these are not used by this function (they are only used to query using IOFileInfoGet.
IOMedium
Get medium information.
IOFileLoad
Load an entire file at once.
IOFileSave
Save an entire file at once.
IORenameFile
Rename a file.
IOMakeDirectory
Create a new directory.

PROGS, Professional & Graphical Software
last edited April 18, 1996