dfmbuf_read: Read a logical record in a z/TPFDF multiple LREC buffer

Use this function to read an LREC in an existing z/TPFDF multiple LREC buffer.

Last updated

Added for PUT11.

Format

#include <cdf.h>

dft_rec *dfmbuf_read(dft_buf *buf_ptr, dft_opt options);

dft_rec *dfmbuf_read_stack(dft_buf *buf_ptr, dft_srn stacknbr);

Options parameter values

buf_ptr

is a pointer to a z/TPFDF multiple LREC buffer or the pointer to a local copy of a z/TPFDF multiple LREC buffer header.

Note: If you specify a local copy of the header, this ECB can traverse the buffer by using its own keys while the ECB maintains its own buffer position. The multiple LREC buffer must be in read-only mode while it is being accessed by more than one ECB.

options

are the processing options for this function. Use the following values:

DFMBUF_NOKEY: deactivates any currently active keys. If this value is not specified, the dfmbuf_read function uses any active selection keys.
DFMBUF_BEGIN: reads LRECs from the start of the z/TPFDF multiple LREC buffer. If this value is not specified, the LREC search starts from the current position.
0: specifies that you do not want to use any processing options.

stacknbr

is a stack value in the range 1 - 6 that identifies an LREC which was previously retained on a dfmbuf_retain function.

Entry requirements

The z/TPFDF multiple LREC buffer that the buf_ptr parameter references must be allocated and previously initialized by using the dfmbuf_init_v2 function.

Return conditions

A pointer to the LREC that was read.

Error return

A NULL pointer, if an error occurred or an LREC was not located.

For more information about how to check the error indicators, Identifying return indicators and errors.

Programming considerations

To determine the size of the current LREC, use the dfmbuf_getinfo function. For example, if the buffer LREC has no size field.
When a dfmbuf function returns with a not-found condition (DF_MBUF_NOT_FOUND), a subsequent dfmbuf_read function reads from the beginning of the buffer.

Examples

The following example activates keys by using the dfmbuf_key function and then reads an LREC in the z/TPFDF multiple LREC buffer by using the currently active keys.

dfmbuf_setkey(&keys, 1, offsetof(struct gr3msr,GR3MKEY), 1, DF_EQ, 
   0, GR3MK80, DF_UPORG, DF_CONST);    
dfmbuf_setkey(&keys, 2, offsetof(struct gr3msr,GR3MNAM), 6, DF_EQ,            
   pnewlrec->GR3MNAM, 0, DF_UPORG, DF_CHAR);    
dfmbuf_key(buffer_ptr, &keys, 2);    
if (DFMBUF_OK(buffer_ptr)) {      
    lrec_ptr = dfmbuf_read(buffer_ptr, DFMBUF_BEGIN);      
    if (!DFMBUF_OK(buffer_ptr)) {      
        ⋮
    }    
}

The following example reads the retained LREC with stack value 5 in the z/TPFDF multiple LREC buffer.

lrec_ptr = dfmbuf_read_stack(buffer_ptr, 5);
if (DFMBUF_OK(buffer_ptr)) {
    ⋮
}