READ—Read a block (BDAM)

The READ macro retrieves a block from a data set and places it in a designated area of storage. Control might be returned to the problem program before the block is retrieved.The input operation must be tested for completion using a CHECK or WAIT macro. A data event control block, shown in Status information following an input/output operation, is constructed as part of the macro expansion.

Addressing mode: The READ macro may be issued in 24- or 31-bit addressing mode. When issued in 31-bit addressing mode, all addresses must be valid 31-bit addresses.

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):

decb name—symbol

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

type—{DI[F|X][R|RU]}

     {DK[F|X][R|RU]}

is coded in one of the combinations shown above to specify the type of read operation and the optional services performed by the system:

DI

specifies that the data and key, if any, are read from a specific device address. The device address, which can be designated by any of the three addressing methods, is supplied by the block address.

DK

specifies that the data (only) is read from a device address identified by a specific key. The key used as a search argument must be supplied in the area specified by the key address. The search for the key starts at the device address supplied in the area specified by the block address. The description of the DCB macro, LIMCT, contains a description of the search.

F

requests that the system provide block position feedback into the area specified by the block address. This character can be coded as a suffix to DI or DK as shown above.

X

requests exclusive control of the data block being read, and that the system provide block position feedback into the area specified by the block address. If OPTCD=F is not specified, the feedback is provided in the form of an 8-byte absolute address (MBBCCHHR). The descriptions of the WRITE and RELEX macros contain a description of releasing a data block under exclusive control. This character can be coded as a suffix to DI or DK as shown above.

R

requests that the the system provide next address feedback into the area specified by next address. When R is coded, the feedback is the relative track address of the next data record. This character can be coded as a suffix to DI, DK, DIF, DIX, DKF, or DKX as shown above, but can be coded only for use with variable-length spanned records.

RU

requests that the the system provide next address feedback into the area specified by the next address. When RU is coded, the feedback is the relative track address of the next capacity record (R0) or data record whichever occurs first. These characters can be coded as a suffix to DI, DK, DIF, DIX, DKF, or DKX, but it can be coded only for use with variable-length spanned records.

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

specifies the address of the data control block opened for the data set to be read.

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

specifies the address of the area in which the data block is to be placed. If 'S' is coded instead of an address, dynamic buffering is requested (dynamic buffering must also be specified in the MACRF parameter of the DCB macro). When dynamic buffering is used, the system acquires a buffer and places its address in the data event control block.

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

specifies the number of data bytes to be read up to a maximum of 32760. If 'S' is coded instead of a length, the number of bytes to be read is taken from the data control block. If neither length nor 'S' is specified, no error indication is given when your program is assembled, but your program must insert a length into the data event control block (DECB) before the READ is issued.

key address—A-Type Address, (2-12), 'S', or 0

specifies the address of the area for the key of the desired data block. If the search operation is made using a key, the area must contain the key. Otherwise, the key is read into the designated area. If the key is read and 'S' was coded for the area address, you can also code 'S' for the key address; the key and data are read sequentially into the buffer acquired by the system. If the key is not to be read, specify 0 instead of an address or 'S'.

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

specifies the address of the area containing the relative block address, relative track address, or actual device address of the data block to be retrieved. The device address of the data block retrieved is placed in this area if block position feedback is requested. The length of the area containing the address depends on whether the feedback option (OPTCD=F) is specified in the data control block and if the READ macro requested feedback.

If OPTCD=F is specified, feedback (if requested) is in the same form as originally presented by the READ macro, and the field can be either 3 or 8 bytes long, depending on the type of addressing.

If OPTCD=F is not specified, feedback (if requested) is as an actual device address, and the field must be 8 bytes long.

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

specifies the address of the storage area in which the system places the relative address of the next block. Length must be specified as 'S'. When next address is specified, an R or RU must be added to the type parameter (for example, DIR or DIRU). The R indicates that the next address returned is the next data record. RU indicates that the next address returned is for the next data or capacity record, whichever occurs first. The next address parameter can be coded only for use with variable-length spanned records.