READ—Read a block (BPAM and BSAM)

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:

After issuing the CHECK, WAIT or EVENTS macro for the DECB for the READ request, obtain the status area address from the word that is 16 bytes from the start of the DECB.
Subtract 12 from the address of the status area to obtain the address of the length-read field.

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.

Data Conversion: For BSAM, you can request conversion by coding LABEL=(,AL) or (,AUL) in the DD statement, or by coding OPTCD=Q in the DCB macro or DCB subparameter of the DD statement. If conversion is requested, the check routine automatically converts BSAM records, as they are read, from one character representation to another if the record format is F, FB, D, DB, or U. Conversion occurs when the check routine determines that the input buffer is full. Conversion is performed according to one of the following techniques:

Coded Character Set Identifier (CCSID) Conversion
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.
Default Character Conversion
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
,{SF|SB|SF64|SF64P}
,dcb address
,area address
[,length|,'S']

decb name—symbol

specifies the name that is assigned to the data event control block (DECB) that is created as part of the macro expansion.

type—{SF|SB|SF64|SF64P}

is coded as shown to specify the type of read operation:

SF: specifies normal, sequential, forward retrieval.
SB: specifies a read-backward operation. This parameter can be specified only for magnetic tape with format-F or format-U records.
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.
SF64: for BSAM, indicates sequential forward retrieval and that area address is an 8-byte address and can point to an area above the 2-GB bar. The 8-byte pointer in the macro expansion must reside below the 2-GB bar. When the area address is in a register, it must be a 64-bit register.
The system supports this option only for extended format data sets. For other restrictions see z/OS DFSMS Using Data Sets.
SF64P: for BSAM, indicates sequential forward retrieval and that area address is a doubleword (eight bytes) containing the address of the area above the 2-GB bar. The 8-byte pointer must reside below the 2-GB bar. With SF64 you code the name or address of the data area. With SF64P you code the name or address of a doubleword that points to the area.

dcb address—A-Type Address or (2-12)

specifies the address of the data control block for the opened data set to be read. When READ is issued in 31-bit addressing mode, the input DCB address and area address must be clean 31-bit addresses.

area address—A-Type Address or (2-12)

specifies the address of the problem program area in which the block is placed if you do not code SF64P. Specifies an eight–byte pointer if you specify SF64P. If you specify SF64P, the specified doubleword contains an area pointer that can point above the 2 GB bar. The doubleword must reside below the 2 GB bar. If you specify the register form with SF64, it is a 64–bit register. If you specify SF64 or SF64P, your program must run in 24–bit or 31–bit mode.

length—symbol, decimal digit, absexp, (2-12), or 'S'

specifies the number of data bytes to be read. This parameter is meaningful only for format-U records and for format-D records when the DCB BUFOFF parameter is not L. If your program is not using large block interface (LBI), the maximum value is the BLKSIZE value in the DCB when it was opened. If your program is using LBI, the maximum value is the BLKSIZE value in the DCBE.

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.