CBRIBUFL macro

The CBRIBUFL macro describes the area to which the BUFLIST keyword on the OSREQ macro points. The area contains a header and a list of buffer descriptors. Each buffer descriptor describes one data buffer, giving the address of the buffer, the length of the buffer, and the amount of data in the buffer. The data buffer contains the data for the object to be stored or provides the buffer space for the object to be retrieved.

The CBRIBUFL macro is a mapping macro consisting of three DSECTs. The first two DSECTs are used to describe the buffer list. The third DSECT maps the data buffer pointed to by the buffer list. Figure 1 and Figure 2 describe the contents of the DSECTs.

Figure 3. Fields Described by CBRIBUFL

Figure 1. Fields Described by CBRIBUFL

        OBL       DSECT      Data buffer list control block
                  DS   0F
    +0  OBLID     DS   CL4   Control block identifier ('OBL ')
    +4  OBLLSTL   DS   F     Length of buffer list cb in bytes
                             including buffer descriptors
    +8  OBLVERSN  DS   XL1   Buffer list version (X'02')
    +9            DS   XL3   Reserved, must be zero
    +12           DS   F     Reserved, must be zero
    +16 OBLNUMBF  DS   F     Number of data buffer descriptors that
                             follow
    +20 OBLBUFL   DS   0F    Beginning of data buffer descriptor list,
                             mapped by OBLBDESC

The following buffer descriptor is repeated for each data buffer:

        OBLBDESC  DSECT      Data buffer descriptor
    +0  OBLBUFP   DS   A     Address of buffer
    +4  OBLBBLTH  DS   F     Length of buffer
    +8  OBLBUSED  DS   F     Length of data in buffer
    +12           DS   F     Reserved, must be zero

Each data buffer is described as follows:

        OBLB      DSECT      Data buffer
                  DS   0F
    +0  OBLBDATA  DS   0X    Object data area

Figure 2 is a structure diagram of the data buffer list (CBRIBUFL) pointed to by the BUFLIST keyword on an OSREQ STORE or OSREQ RETRIEVE macro.

Figure 2. Data Buffer List Structure Diagram

The caller uses the buffer descriptor for each buffer to provide buffer location, buffer size, and data length to the system; it is then used by the system to return data length information to the caller. The OBLBBLTH field indicates the buffer length. The contents of this field must be set by the caller. The OBLBUSED field will indicate the number of bytes used in the buffer. For a STORE request, the value in this field is supplied by the caller; for a RETRIEVE request, this field is zeroed by OAM and updated when information is loaded in the data area.

Part of an object may occupy space in an individual buffer; therefore, an object may span several buffers. For a RETRIEVE request, the entire object (or requested portion) is stored in the buffer space provided. If an error occurs during a RETRIEVE request, the buffer data is invalid. Given adequate buffer space, RETRIEVE will fill the first buffer with data, then the second, and so forth until the total number of bytes filled in the buffers is equal to the size of the object (or the requested portion of the object). For a STORE request, if the object data is in a contiguous area of storage immediately following the last (or only) buffer descriptor, the object data is stored directly from the data buffers; otherwise, object data is reblocked from the data buffers into a temporary storage buffer and stored from the temporary buffer.