Input/Output Routine - IBM-REXX

The input/output (I/O) replaceable routine is also called the read input/write output data routine. The system calls the I/O routine to:

• Read a record from a specified DD
• Write a record to a specified DD
• Open a DD

The DD must be allocated to either a sequential data set or a single member of a partitioned data set. The name of the system-supplied I/O routine is IRXINOUT.

Notes:

1. The system supplied I/O routine does not support I/O on files allocated to data sets with spanned, track overflow, or undefined record formats.
2. To permit FORTRAN programs to call IRXINOUT, TSO/E provides an alternate entry point for the IRXINOUT routine. The alternate entry point name is IRXIO.

If a read is requested, the routine returns a pointer to the record that was read and the length of the record. If a write is requested, the caller provides a pointer to the record to be written and the length of the record. If an open is requested, the routine opens the file if the file is not yet open. The routine also returns a pointer to an area in storage containing information about the file. You can use the IRXDSIB mapping macro to map this area. The mapping macro is in SYS1.MACLIB.

You specify the name of the I/O routine in the IOROUT field in the module name table.

I/O processing is based on the QSAM access method. The I/O routine is called for:

• Initialization. When IRXINIT initializes a language processor environment, the system calls the I/O replaceable routine to initialize I/O processing.
• Open, when:
  • You use the LINESIZE built-in function in an exec
  • Before the language processor does any output
• For input, when:
  • A PULL or a PARSE PULL instruction is processed, and the data stack is empty, and the language processor environment is not integrated into TSO/E
  • A PARSE EXTERNAL instruction is processed in a language processor
    environment that is not integrated into TSO/E
  • The EXECIO command is processed.
  • A program outside of REXX calls the I/O replaceable routine for input of a record.
• For output, when:
  • A SAY instruction is processed in a language processor environment that is not integrated into TSO/E
  • Error messages must be written.
  • Trace (interactive debug facility) messages must be written.
  • A program outside of REXX calls the I/O replaceable routine for output of a record. Termination. When the system terminates a language processor environment, the I/O replaceable routine is called to cleanup I/O.

Entry Specifications

For the I/O replaceable routine, the contents of the registers on entry are described below. The address of the environment block can be specified in either register 0 or in the environment block address parameter in the parameter list.

Register 0 Address of the current environment block

Register 1 Address of the parameter list

Registers 2-12 Unpredictable

Register 13 Address of a register save area

Register 14 Return address

Register 15 Entry point address

Parameters

Register 1 contains the address of a parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter. The high-order bit of the last address in the parameter list must be set to 1 to indicate the end of the parameter list. Table below describes the parameters for the I/O routine.

Input Parameters for the I/O Replaceable Routine

Functions Supported for the I/O Routine

The function to be performed by the I/O routine is specified in parameter 1. The valid functions are described below.

INIT
The routine performs any initialization that is required. During the initialization of a language processor environment, the I/O routine is called to initialize I/O processing.

OPENR
The routine opens the specified DD for a read operation if the DD is not already open. The ddname is specified in parameter 4.

The I/O routine returns the address of the data set information block in parameter 2. It returns the length of the data set information block (DSIB) in parameter 3.

The routine opens the specified DD for a write operation if the DD is not already open.The ddname is specified in parameter 4.

The I/O routine returns the address of the data set information block in parameter 2. It returns the length of the data set information block (DSIB) in parameter 3.

OPENX
The routine opens the specified DD for an update operation if the DD is not already open. The ddname is specified in parameter 4.

The I/O routine returns the address of the data set information block in parameter 2. It returns the length of the data set information block (DSIB) in parameter 3. “Data

READ
The routine reads data from the DD specified in parameter 4. It returns the data in the buffer pointed to by the address in parameter 2. It also returns the number of the record that was read in the line number parameter (parameter 5).

The READ and READX functions are equivalent, except that the data set is opened differently. Subsequent read operations to the same data set can be done using either the READ or READX function because they do not reopen the data set.If the data set to be read is closed, the routine opens it for input and then performs the read.

READX
The routine reads data from the DD specified in parameter 4. It returns the data in the buffer pointed to by the address in parameter 2. It also returns the number of the record that was read in the line number parameter (parameter 5).

The READ and READX functions are equivalent, except that the data set is opened differently. Subsequent read operations to the same data set can be done using either the READ or READX function because they do not reopen the data set.

If the data set to be read is closed, the routine opens it for update and then performs the read.

WRITE
The routine writes data from the specified buffer to the specified DD. The buffer is pointed to by the address in parameter 2 and the ddname is specified in parameter 4.

If the data set is closed, the routine first opens it for output and then writes the record. For sequential data sets, if the data set is allocated as OLD, the first record that is written after the data set is opened is written as record number 1. If a sequential data set is allocated as MOD, the record is added at the end of the data set.

Rule: MOD cannot be used to append data to a member of a PDS. You can use MOD only when appending information to a sequential data set. To append information to a member of a PDS, rewrite the member with the additional records added.

When a data set is opened for update, the WRITE function is used to rewrite the last record that was retrieved by the READ or READX function. You can optionally use the line number parameter (parameter 5) to ensure that the number of the record being updated agrees with the number of the last record that was read.

TERM The routine performs cleanup and closes any opened data sets.

CLOSE
The routine closes the DD specified in parameter 4. The CLOSE function permits data sets to be freed and reallocated.

The CLOSE function is allowed only from the task under which the data set was opened. If CLOSE is requested from a different task, the request is ignored and a return code of 20 is returned.

Buffer and Buffer Length Parameters

Parameter 2 specifies the address of a buffer and parameter 3 specifies the buffer length. These two parameters are not used for the INIT, TERM, and CLOSE functions.

On input for a WRITE function, the buffer address points to a buffer that contains the record to be written. The buffer length parameter specifies the length of the data to be written from the buffer. The caller must provide the buffer address and length.

For the WRITE function, if data is truncated during the write operation, the I/O routine returns the length of the data that was actually written in the buffer length parameter. A return code of 16 is also returned.

On output for a READ or READX function, the buffer address points to a buffer that contains the record that was read. The buffer length parameter specifies the length of the data being returned in the buffer.

For a READ or READX function, the I/O routine obtains the buffer needed to store the record. The caller must copy the data that is returned into its own storage before calling the I/O routine again for another request. The buffers are reused for subsequent I/O requests.

On output for an OPENR, OPENW, or OPENX function, the buffer address points to the data set information block, which is an area in storage that contains information about the file. The buffer length parameter returns the length of the data set information block (DSIB) whose address is being returned. TSO/E provides a mapping macro, IRXDSIB, that you can use to map the buffer area returned for an open request.

For an OPENR, OPENW, or OPENX function, all of the information in the data set information block does not have to be returned. The buffer length must be large enough for all of the information being returned about the file or unpredictable results can occur. The data set information block buffer must be large enough to contain the flags field and any fields that have been set, as indicated by the flags field.

REXX does not check the content of the buffer for valid or printable characters. Any hexadecimal characters may be passed.

The buffers that the I/O routine returns are reserved for use by the environment block (ENVBLOCK) under which the original I/O request was made. The buffer should not be used again until:

• A subsequent I/O request is made for the same environment block, or
• The I/O routine is called to terminate the environment represented by the environment block (TERM function), in which case, the I/O buffers are freed and the storage is made available to the system.

Any replaceable I/O routine must conform to this procedure to ensure that the exec that is currently running accesses valid data.

If you provide your own replaceable I/O routines, your routine must support all of the functions that the system-supplied I/O routine performs. All open requests must open the specified file. However, for an open request, your replaceable I/O routine need only fill in the data set information block fields for the logical record length (LRECL) and its corresponding flag bit. These fields are DSIB_LRECL and DSIB_LRECL_FLAG. The language processor needs these two fields to determine the line length being used for its write operations. The language processor will format all of its output lines to the width that is specified by the LRECL field. Your routine can specify a LRECL (DSIB_LRECL field) of 0, which means that the language processor will format its output using a width of 80 characters, which is the default.

When the I/O routine is called with the TERM function, all buffers are freed.

Line Number Parameter

The line number parameter (parameter 5) is not used for the INIT, OPENR, OPENW, OPENX, TERM, or CLOSE functions. The parameter is used as an input parameter for the WRITE function and as an output parameter for the READ and READX functions.

If you are writing to a DD that is opened for update, you can use this parameter to verify the record being updated. The parameter must be either:

• A non-zero number that is checked against the record number of the last record that was read for update. This ensures that the correct record is updated. If the record numbers are identical, the record is updated. If not, the record is not written and a return code of 20 is returned.
• 0 - No record verification is done. The last record that was read is unconditionally updated.

If you are writing to a DD that is opened for output, the line number parameter is ignored.

On output for the READ or READX functions, the parameter returns the absolute record number of the last logical record that was read.

Data Set Information Block

The data set information block is a control block that contains information about a file that the I/O replaceable routine opens. For an OPENR, OPENW, or OPENX function request, the I/O routine returns the address of the data set information block (DSIB) in parameter 2, and the length of the DSIB in parameter 3.TSO/E provides a mapping macro IRXDSIB you can use to map the block. The mapping macro is in SYS1.MACLIB. This shows the format of the control block.

Format of the Data Set Information Block

At offset +20 in the data set information block, there is a fullword of bits that are used as flags. Only the first nine bits are used. The remaining bits are reserved. The bits are used to indicate whether information is returned in each field in the control block starting at offset +24. A bit must be set on if its corresponding field is returning a value. If the bit is set off, its corresponding field is ignored.

The flag bits are:

• The LRECL flag. This bit must be on and the logical record length must be returned at offset +24. The logical record length is the only data set attribute that is required. The remaining eight attributes starting at offset +26 in the control block are optional.
• The BLKSIZE flag. This bit must be set on if you are returning the block size at offset +26.
• The DSORG flag. This bit must be set on if you are returning the data set organization at offset +28.
• The RECFM flag. This bit must be set on if you are returning the record format at offset +30.
• The GET flag. This bit must be set on if you are returning the total number of records read at offset +32.
• The PUT flag. This bit must be set on if you are returning the total number of records written at offset +36.
• The MODE flag. This bit must be set on if you are returning the mode in which the DCB was opened at offset +40.
• The CC flag. This bit must be set on if you are returning carriage control information at offset +41.
• The TRC flag. This bit must be set on if you are returning IBM 3800 Printing Subsystem character set control information at offset +42.

Return Specifications

For the I/O routine, the contents of the registers on return are:

Registers 0-14 Same as on entry

Register 15 Return code

Return Codes

This shows the return codes for the I/O routine. The routine returns the return code in register 15. If you specify the return code parameter (parameter 7), the I/O routine also returns the return code in the parameter.

Return Codes for the I/O Replaceable Routine