Text File I/O from a Macro

The macro language provides the ability to read from and write to external text files. These files are connected to and disconnected from the macro processor using OPEN and CLOSE commands. Input and output to external files is done using the READ and WRITE commands.

When a file is opened, it must be assigned a “unit” number. This is a number that for historical purposes must range from 20 through 29. This unit number will then be used in subsequent READ, WRITE and CLOSE statements to identify the particular file opened. In this way more than one file can be processed simultaneously.

If an error occurs during text file I/O, the error return code will be stored in the $ERRNO macro system variable. Macros must test for I/O errors and act accordingly since a diagnostic will not be output to indicate an I/O failure.

Text file I/O processing can optionally be monitored in the GENER and CERUN Console trace window for debugging purposes. Tracing of I/O is off by default. Tracing is controlled from the GENER and CERUN full display Tools»Preferences»Trace menu “Macro IO commands” check box.

Opening a Text File (OPEN)

The OPEN command opens a text file with a given name on a given unit. The file name is optional if the unit is pre-connected. If FRONT is specified, the unit is rewound. If REAR is specified, the unit is positioned at the end-of-file. FRONT is the default. The OPEN command has the following syntax:

$\textbf{OPEN}\;\textbf{/}\;\mathit{unit}\begin{bmatrix},\!\begin{array}{l}\textbf{FRONT}\\\textbf{REAR}\end{array}\!\end{bmatrix}\,\bigl[,\mathtt{\char39}\mathit{filename}\,\mathtt{\char39}\,\bigr]$

Two special file names are predefined to permit input and output to the console; they are STDIN and STDOUT.

Closing a Text File (CLOSE)

The CLOSE command closes a text file. It has the following syntax:

$\textbf{CLOSE}\;\textbf{/}\;\mathit{unit}$

It is good programming practice to close files when finished using them.

Writing to a Text File (WRITE)

The WRITE command writes a string into a text file. The syntax of the WRITE command is:

$\textbf{WRITE}\;\textbf{/}\;\mathit{unit},\,\mathtt{\char39}\mathit{format}\,\mathtt{\char39}\,\;\icamrange{0.66}{0}\,\bigl[,\mathit{parameter}\,\bigr]$

See “Output String Format” for a description of how the string to be written is constructed using the format string argument and optional list of parameters.

Reading from a Text File (READ)

The READ command can be used to read a line from a text file into one or more macro variables. The text file must be open when the READ is executed. The syntax of the READ from text file command is:

$\textbf{READ}\;\textbf{/}\;\mathit{unit}\,\!\begin{bmatrix},\!\begin{array}{l}\textbf{INCR}\\\textbf{DECR}\end{array}\!\end{bmatrix}\,,\mathtt{\char39}\mathit{format}\,\mathtt{\char39}\,\;\icamrange{0.66}{1}\,\bigl(,\mathit{variable\text{-}name}\,\bigr)$

If INCR is specified, the next line is read. This is the default. A READ using INCR should only be performed if a call to “$FEOF(unit)” returns false. If DECR is specified, the last line is read again. If no lines have been read yet, the first line is read.

See “Input String Format” for a description of how the variables in the input list are assigned values from the input text using the format string.

Reading from a String Value (READ)

The READ command can also be used to do an “internal read” from a string value. The syntax of the internal READ command is:

$\textbf{READ}\;\textbf{/}\;\mathtt{\char39}\mathit{source}\,\mathtt{\char39},\,\mathtt{\char39}\mathit{format}\,\mathtt{\char39}\,\;\icamrange{0.66}{1}\,\bigl(,\mathit{variable\text{-}name}\,\bigr)$

See “Input String Format” for a description of how the variables in the input list are assigned values from the input source string using the format string.