File Processing in Rexx

EXECIO:

SYNTAX: EXECIO lines

DISKW ddname   write parms DISKR ddname read parms DISKRU  linenum   read parms

WRITE Parms:

STEM varname OPEN|FINISH

READ Parms:

(FIFO | OPEN  FINISH SKIP ) LIFO |

STEM Varname

This command controls I/O of information to and from a dataset. Information can be read from a dataset to a data stack for serialized processing or to a list of variables for random processing. Information from the data stack or a list of variables can be written to a data set.

You can use the EXECIO command to do various types of

I/O tasks, such as copy information to and from a data set to add, delete, or update the information.

Restriction: The EXECIO command does not support I/O on files allocated to data sets with spanned, track overflow, or undefined record formats.

An I/O data set must be either sequential or a single member of a PDS.             Before the EXECIO command can perform I/O to or from the data set, the data set must be allocated to a file that is specified on the EXECIO

command. The EXECIO command does not perform the allocation.

When performing I/O with a system data set that is available to multiple users, allocate the data set as OLD, before issuing the EXECIO command, to have exclusive use

of the data set.

When you use EXECIO, you must ensure that you use quotation marks around any operands, such as DISKW, STEM, FINIS, or LIFO. Using quotation marks prevents the possibility of the operands being substituted as variables.

For example, if you assign the variable stem to a value in the exec and then issue EXECIO with the STEM option, if STEM is not enclosed in quotation marks, it will be substituted with its assigned value.

Lines:

The number of lines to be processed. This operand can be a specific decimal number or an arbitrary number indicated by *. When the operand is * and EXECIO is reading from a data set, input is read until EXECIO reaches the end of the data set.

If you specify a value of zero (0), no I/O operations are performed unless you also specify either OPEN, FINIS, or both OPEN and FINIS.

If you specify OPEN and the data set is closed, EXECIO opens the data set but does not read any lines. If you specify OPEN and the data set is open, EXECIO does not read any lines.

In either case, if you also specify a non-zero value for the linenum operand, EXECIO sets the current record number to the record number indicated by the linenum operand.

If you specify FINIS and the data set is open, EXECIO does not read any lines, but EXECIO closes the data set. If you specify FINIS and the data set

is not already opened, EXECIO does not open the data set and then close it.

If you specify both OPEN and FINIS, EXECIO processes the OPEN first as described above. EXECIO then processes the FINIS as described above.

DISKR

Opens a data set for input (if it is not already open) and reads the specified number of lines from the data set and places them on the data stack.                           If the STEM operand is specified, the lines are placed in a list of variables instead of on the data stack.

While a data set is open for input, you cannot write information back to the same data set.

DISKRU

Opens a data set for update (if it is not already open) and reads the specified number of lines from the data set and places them on the data stack.                           If the STEM operand is specified, the lines are placed in a list of variables instead of on the data stack.

While a data set is open for update, the last record read can be changed and then written back to the data

set with a corresponding EXECIO DISKW command.Typically, you open a data set for update when you want to modify information in the data set.

ddname

The name of the file to which the sequential data set or member of the PDS was allocated. You must allocate the file before you can issue EXECIO. For example, you can allocate a file using the ALLOCATE command in the TSO/E address space only or a JCL DD statement.

linenum

The line number in the data set at which EXECIO is to begin reading. When a data set is closed and reopened as a result of specifying a record number earlier than the current record number, the file is open for:

- input if DISKR is specified

- update if DISKRU is specified

When a data set is open for input or update, the current record number is the number of the next record to be read. When linenum specifies a record number earlier

than the current record number in an open data set, the data set must be closed and reopened to reposition the current record number at linenum. When this situation occurs and the data set was not opened at the same task level as that of the executing exec, attempting to close the data set at a different task level results in an EXECIO error. The linenum operand must not be used in this case.

FINIS:

Close the data set after the EXECIO command completes. A data set can be closed only if it was opened at the same task level as the exec issuing the EXECIO command.

You can use FINIS with a lines value of 0 to have EXECIO

close an open data set without first reading a record.

Because the EXEC command (when issued from TSO/E READY

mode) is attached by the TSO/E terminal monitor program

(TMP), data sets opened by a REXX exec are typically closed automatically when the top level exec ends. Good programming practice, however, would be to explicitly close all data sets when finished with them.

OPEN:

Opens the specified data set if it is not already open. You can use OPEN with a lines value of 0 to have EXECIO do one of the following:

Open a data set without reading any records

Set the current record number (that is, the number of the next record EXECIO will read) to the record number indicated by the linenum operand, if you specify a value for linenum.

STEM var-name

The stem of the set of variables into which information is to be placed.          To place information in compound variables, which allow for easy indexing, the var-name should end with a period. For example,

MYVAR.

When var-name does not end with a period, the variable names are appended with numbers and can be accessed in a loop such as:

"EXECIO * DISKR MYINDD (FINIS STEM MYVAR"

 DO i = 1 to MYVAR0

this_line = VALUE('MYVAR'¦¦i)

  END

In the first example above, the list of compound variables has the stem MYVAR. and lines of information (records)

from the data set are placed in variables MYVAR.1, MYVAR.2, MYVAR.3, and so forth.The number of variables in the list is placed in MYVAR.0.

Thus if 10 lines of information were read into the MYVAR

variables, MYVAR.0 contains the number 10, indicating that

10 records are read. Furthermore, MYVAR.1 contains record

1, MYVAR.2 contains record 2, and so forth up to MYVAR.10 which contains record 10. All stem variables beyond MYVAR.10 (i.e. MYVAR.11, MYVAR.12, etc.) are residual and contain the values that they held prior to entering the EXECIO command.

To avoid confusion as to whether a residual stem variable value is meaningful, you may want to clear the entire stem variable prior to entering the EXECIO command. To clear

all compound variables whose names begin with that stem, you can either:

- Use the DROP instruction as follows, to set all possible compound variables whose names begin with that stem to their uninitialized values:

DROP MYVAR.

- Set all possible compound variables whose names begin with that stem to nulls as follows:

MYVAR. = ''

LIFO

Places information on the data stack in LIFO (last in first out) order.

FIFO

Places information on the data stack in FIFO (first in first out) order.            FIFO is the default when neither LIFO or FIFO is specified.

SKIP

Reads the specified number of lines but does not place them on the data stack or in variables. When the number of lines is *, EXECIO skips to the end of the data set.