OSREAD

The OSREAD statement reads an operating system file by pathname.

Format

OSREAD var FROM path {ON ERROR statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

where

var	is the variable to receive the data.

path	is the pathname of the file to be read.

At least one of the THEN and ELSE clauses must be present.

The OSREAD statement provides a simple way for a program to read the content of an operating system file by pathname rather than having to open the parent directory with OPENSEQ and then using READBLK to read the data.

The data read from the specified file is transferred to var with no modification. In particular, note that the translation of newlines to field marks that occurs when reading from directory files does not happen with this statement.

OSREAD takes no part in the locking system. It is up to the application developer to ensure that concurrency issues are handled appropriately.

The THEN clause is executed if the read is successful. Use of the SYSTEM() function with key 1071 (SYS$OSREAD.INFO) after a successful read will return a dynamic array similar to that returned by the STATUS statement for a directory file item.

The ELSE clause is executed if the read fails because, for example, the pathname does not reference an existing file. Attempting to read an item larger than 1Gb will take the ELSE clause. The STATUS() function will indicate the cause of the error and the OS.ERROR() function will provide further information for operating system level errors.

The ON ERROR clause is executed for serious fault conditions such as the inability to read the data from the file for reasons outside of QM. The STATUS() function will return an error number and the OS.ERROR() function will provide further information about the operating system level error. If no ON ERROR clause is present, an abort would occur at these types of error.

Example

OSREAD FAXDATA FROM 'C:\FAXLOG' THEN CALL PROCESS.FAX(FAXDATA)

This statement reads the content of an operating system file with pathname C:\FAXLOG and, if found, executes a subroutine to process this data.