The READ macro retrieves a block from a data set and places it in a designated area of storage (input area). Control might be returned to the problem program before the block is retrieved. The input operation must be tested for completion using a CHECK, WAIT or EVENTS macro. After completion, you can determine the length of the block by using a technique described in z/OS DFSMS Using Data Sets.
If you are using the large block interface (OPEN set DCBESLBI on) for fixed-length blocked or undefined-length records, the actual length of the record block that was read can be found in a 4-byte length-read field. Locate the length-read field by performing the following tasks:
A data event control block, shown in Status information following an input/output operation, is constructed as part of the macro expansion. If the OPEN macro specifies UPDAT, both the READ and WRITE macros must refer to the same data event control block. See the list form of the READ or WRITE macro for a description of how to construct a data event control block. See the execute form of the READ or WRITE macro for a description of how to modify an existing data event control block.
If CCSIDs are supplied from any source for ISO/ANSI V4 tapes, records are converted from the CCSID which represents the data on tape to the CCSID as seen by the problem program. You can also prevent conversion by supplying a special CCSID. CCSID may be supplied in the CCSID subparameter of a JOB, EXEC, or DD statement or the tape label.
If you are using non-ISO/ANSI V4 tapes or if CCSIDs are not supplied by any source, data management converts the records from ASCII code to EBCDIC code using specific tables defined for this default character conversion.
Refer to z/OS DFSMS Using Data Sets, for a complete description of CCSID conversion and Default Character conversion.
Reading a PDSE directory: When reading the PDSE directory, end-of-file is indicated after the last of the directory data is read. Empty directory blocks are not simulated.
UNIX files: For a UNIX file processed with RECFM=VB, each READ returns one record per block.
Extended format data sets: On READ requests for extended format data sets, that are not in the compressed format, you must provide a data area at least the size of DCBBLKSI or DCBEBLKSI unless you are reading format-U records and code a length on the READ macro. In that case, the data area must be at least the length coded.
Compressed format data sets: When processing a compressed format data set and NOTE/POINT is specified in the DCB (MACRF=P), a READ issued for a block whose user RBN value exceeds 16 777 215 will result in an I/O error. This is due to the fact that the NOTE/POINT interface is limited by a 3 byte token.
Addressing mode: When you issue the READ macro in 24-bit mode, provide only 24-bit addresses unless you code SF64 or SF64P. When you issue the READ macro in 31-bit addressing mode, provide only 31-bit addresses unless documentation says otherwise or you code SF64 or SF64P. With SF64 or SF64P, the data area can reside above the 2 GB bar but you cannot issue READ in 64-bit mode.
BSAM and BPAM allow data areas to be located above the 16MB line. This includes allowing the caller to issue some other BPAM and BSAM macros in 31-bit addressing mode regardless of whether the data area is above or below the 16MB line. Most types of data sets support 31-bit mode.
The standard form of READ must be issued from a program that resides below the 16MB line because the DECB must reside below the line.
To take advantage of providing data areas above the 16 MB line for BSAM macros, the issuer of the READ macro must execute in 31-bit addressing mode.
Syntax: The standard form of the READ macro is written as follows (the list and execute forms are shown following the descriptions of the standard form instructions):
[label] |
READ |
decb name |
---|
This parameter is intended to be used when the data set is open for RDBACK. Tape positioning, label processing, and volume mounting errors will occur during EOV and CLOSE if an OPEN option other than RDBACK is used.
The system supports this option only for extended format data sets. For other restrictions see z/OS DFSMS Using Data Sets.
For format-U records, 'S' or a valid length must be coded. If you code 'S', the number of bytes to be read is taken from the data control block BLKSIZE field (non-LBI) or the DCBE BLKSIZE field (LBI). For format-U records with LBI you must code 'S'.
For format-D records only, the length of the block just read is automatically inserted into the DCBLRECL field by the check routine if BUFOFF=L is not specified in the data control block.