Reading from and writing to z/OS FBA devices
To read from or write to an z/OS FBA device or set of z/OS FBA devices, a z/OS FBA device I/O list (FBADIOL) entry for each device is created that contains, among other things, a device descriptor (returned by the ALLOCATE function), an I/O status block (mapped by the IOSDIOST), the storage buffers, and the blocks on the device that are to be read from or written to. The IOSFBA API will build the appropriate channel program and start the I/O. The read and write functions can be synchronous or asynchronous.
For asynchronous reading and writing, an ECB is passed to the IOSFBA service and control is returned to the invoking program once the I/O is started. The invoking program must wait, at some point, for the ECB to be posted. The ECB is posted once all I/Os are completed, either successfully or unsuccessfully, and the status of the I/O for the device is stored in the corresponding status block.
Input to IOSFBA READ and IOSFBA WRITE requests
When reading from or writing to an z/OS FBA device, a z/OS FBA device I/O list (FBADIOL) specifies the I/O to be performed. The FBADIOL contains a count of the devices that are involved with the READ or WRITE request and an address for each I/O entry represented by the FBADIOE. An FBADIOE is the representation of I/O to be performed to an FBA device (represented by the FBADDE). The FBADIOE contains pointers to extent entries (FBAEE) that indicate the starting location on the FBA device and length of data to be read or written. The data itself is represented as buffer entries (FBAEE_BUFENT) that contain the location and length of specific sections of data. For READ operations, it indicates the location and length of where data will be read from. For WRITE operations, it indicates the location and length of where data will be written to. These control blocks are found in the IOSDFBA mapping macro.
- Each buffer entry must be a multiple of the physical block size. Partial block sizes cannot be read or written.
- The number of target blocks on the device must not be exceeded by the number of blocks represented by the storage buffer entries.
The service also provides the capability of determining the completion status of each of the I/Os (FBADIOEs) through the use of the status block address. For each FBADIOE, IBM recommends that a status block be allocated and the address stored in the FBADIOE. The status block is mapped by the IOSDIOST mapping macro. It contains the I/O completion code, reason code detailing the completion code value, device and subchannel status, and sense data (when device status contains a unit check).
