dfret: Retain a logical record position

Use this group of functions to retain the file address and displacement in a block of the current logical record (LREC). You can read the LREC later in your application program by using a dfred function with the appropriate option parameter value.

Last updated

  • Changed for PUT13.
  • Changed for PUT10.
  • Changed for PUT07.
  • Changed for PUT01.
  • Changed for PUT00.

Format

void dfret(dft_fil *file, dft_opt options);
void dfret_stk(dft_fil *file, dft_opt stk_type,
     dft_opt options, dft_xxx stk);
Options Parameter Values
Read syntax diagramSkip visual syntax diagramDFRET_CURRENT0
Stk_Type Parameter Values
Read syntax diagramSkip visual syntax diagramDFRET_STACKDFRET_STACKREF
file
A pointer to the base address of the SW00SR slot (defined in c_sw00sr.h) of the file that you want to access and is returned by the dfifb or dfopn function. Use the acc parameter to specify a particular subfile to access. If you do not specify the acc parameter, the last subfile accessed with this SW00SR slot will be accessed.
options
The processing options for this function. Use the following values:
DFRET_CURRENT
Specifies that you want to retain the current LREC.
0
Specifies that you do not want to use any processing options.
stk
One of the following based on the value you specify for the stk_typ parameter:
  • A stack reference number (specify dft_srn) if the stk_typ parameter is set to the DFRET_STACKREF option.
    Note: If the reference number assigned to stk_typ is not unique, the current LREC information will replace the LREC information previously associated with that reference number.
  • A pointer to a stack area (specify dft_stk) if the stk_typ parameter is set to the DFRET_STACK option.
    Note: Do not access any of the fields in the dft_stk structure. This structure is for use by the z/TPFDF product.
stk_typ
One of the following values:
DFRET_STACK
Specifies that you are supplying a pointer to a 10-byte stack area in the stk parameter.
Note: Where possible, use the DFRET_STACKREF option.
DFRET_STACKREF
Specifies that you are supplying a stack reference number in the stk parameter.

Both values let you retain a number of LRECs and identify them so that you can later read them with dfred functions.

Entry requirements

Before using this function, you must open the subfile using the DFOPN_DETAC or DFOPN_HOLD options for the options parameter of the dfopn function.

Return conditions

None.

Error return

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

Programming considerations

  • The type definitions (for example, dft_fil, dft_ref, and dft_kyl) are defined in the c_cdfapi.h header file.
  • Some parameters can be of different types based on the value you specify for that parameter or a related parameter. In the function format, the type of these parameters is shown as dft_xxx. For more information, see the description of the specific parameter for information about what type definition to use for that parameter.
  • To ensure that a retained LREC is retrieved correctly when you use the dfred or dfret function, you must use only one of the following methods while a file is open:
    • Specify the DFRED_STACK or DFRET_STACK parameter value
    • Specify the DFRED_STACKREF or DFRET_STACKREF parameter value
    • Do not specify the DFRED_STACK, DFRET_STACK, DFRED_STACKREF, or DFRET_STACKREF parameter value
    For example, if you specify the DFRET_STACK value on the dfret function, you can use only the DFRED_STACK and DFRET_STACK values on subsequent dfred and dfret function calls, respectively, while the file is open.

    If you want to change the method to work with retained LRECs, you must close and reopen the file.

  • If you specify the DFRET_STACK parameter value, the z/TPFDF product does not maintain the LREC's displacement in the block. Therefore, if after the dfret function call with the DFRET_STACK parameter value specified, you call the dfadd, dfdel, or dfrep function on the same open file, you cannot subsequently call the dfred function with the DFRED_PREVIOUS and DFRED_STACK parameter values specified on that same open file.
  • If you specify the DFRET_STACK or DFRET_STACKREF parameter value, you can retain the details of multiple LRECs. If you do not specify the DFRET_STACK or DFRET_STACKREF parameter value, only the details of the current LREC are retained.
  • Each ECB can retain a maximum of 250 unique DFRET_STACKREF parameter values that contain position information in one or more files.
  • When a file is closed, all retained positions for that file are deleted.

Examples

  • The following example retains the current LREC. 
    dft_fil *file_ptr;
⋮
dfret(file_ptr, DFRET_CURRENT);
  • The following example retains the current LREC with a reference number of 100. 
    dft_fil *file_ptr;
⋮
dfret_stk(file_ptr, DFRET_STACKREF, DFRET_CURRENT, 100);