|
|
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:
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:
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:
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:
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:
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:
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
|
|
IBM-REXX Related Tutorials |
|
---|---|
IBM DB2 Tutorial | COBOL Tutorial |
IBM-JCL Tutorial | IBM Mainframe Tutorial |
Unix/Linux Tutorial |
All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd
Wisdomjobs.com is one of the best job search sites in India.