bdfp1m1iProgramming Concepts and Reference

dfred-Read a Logical Record

Use this group of functions to read a logical record (LREC) or block header and get the address where the record is stored. You can read the next LREC in sequence or specify details of the LREC you require.

You can also use these functions to read a sequence of LRECs. In this case, you perform a sequence of dfred calls and get a different LREC each time.

Format

dft_rec *dfred(dft_fil *file, dft_opt options);
dft_rec *dfred_acc(dft_fil *file, dft_opt access, dft_opt options,
        dft_xxx acc);
dft_rec *dfred_nbr(dft_fil *file, dft_opt nbr_type,
        dft_opt options, dft_xxx nbr);
dft_rec *dfred_are(dft_fil *file, dft_opt options, dft_are *are);
dft_rec *dfred_pth(dft_fil *file, dft_opt options, dft_pth pth);
dft_rec *dfred_acc_nbr(dft_fil *file, dft_opt nbr_type, dft_opt access,
        dft_opt options, dft_xxx acc, dft_xxx nbr);
dft_rec *dfred_acc_are(dft_fil *file, dft_opt access, dft_opt options,
        dft_xxx acc, dft_are *are);
dft_rec *dfred_acc_pth(dft_fil *file, dft_opt access, dft_opt options,
        dft_xxx acc, dft_pth pth);
dft_rec *dfred_nbr_are(dft_fil *file, dft_opt nbr_type, dft_opt options,
        dft_nbr nbr, dft_are *are);
dft_rec *dfred_nbr_pth(dft_fil *file, dft_opt nbr_type, dft_opt options,
        dft_xxx nbr, dft_pth pth);
dft_rec *dfred_are_pth(dft_fil *file, dft_opt options, dft_are *are,
        dft_pth pth);
dft_rec *dfred_acc_nbr_are(dft_fil *file, dft_opt nbr_type, dft_opt access,
        dft_opt options, dft_xxx acc, dft_xxx nbr, dft_are *are);
dft_rec *dfred_acc_nbr_pth(dft_fil *file, dft_opt nbr_type, dft_opt access,
        dft_opt options, dft_xxx acc, dft_xxx nbr, dft_pth pth);
dft_rec *dfred_acc_are_pth(dft_fil *file, dft_opt access, dft_opt options,
        dft_xxx acc, dft_are *are, dft_pth pth);
dft_rec *dfred_nbr_are_pth(dft_fil *file, dft_opt nbr_type, dft_opt options,
        dft_xxx nbr, dft_are *are, dft_pth pth);
dft_rec *dfred_acc_nbr_are_pth(dft_fil *file, dft_opt nbr_type,
        dft_opt access, dft_opt options, dft_xxx acc, dft_xxx nbr,
        dft_are *are, dft_pth pth);



acc
is an ordinal number, a file address, or a pointer to an algorithm string that specifies the subfile you want to access. The type for this parameter is determined by the value you specify for the access parameter.

access
is the method you want to use to access the subfile. Use one of the following values:

DFRED_ALG
specifies that you are providing a pointer to an algorithm argument in the acc parameter. The acc parameter is of type dft_alg.

The TPFDF product uses the algorithm argument to determine the subfile (ordinal number) that is to be accessed. Specify the algorithm argument based on the type of algorithm that is defined in the DSECT or DBDEF macro for the file. If the DSECT or DBDEF macro defines the #TPFDB04 or the #TPFDB0D algorithm, do not use this parameter.

If the subfile you are accessing is contained in a detail file or intermediate index file defined with the #TPFDBFF algorithm, the TPFDF product uses the algorithm argument to locate the subfile. See TPFDF Database Administration for more information about how the TPFDF product uses the algorithm argument to locate the subfile.

DFRED_FADDR
specifies that you are providing a file address in the acc parameter. A file address is in integer format. The acc parameter is of type dft_fad.

DFRED_ORD
specifies that you are providing an ordinal number in the acc parameter. Ordinal numbers in a file start at zero and are in integer format. The acc parameter is of type dft_ord.

If the file is partitioned or interleaved, specify the relative ordinal number within the partition or interleave. If the file is not partitioned or interleaved, specify the file address compute program (FACE) ordinal number.

are
is a pointer to an area to which the TPFDF product copies user data from the index LREC referencing the detail subfile you are accessing. This user data is defined in the DBDEF macro of the detail subfile. See TPFDF Database Administration for more information about defining this user data.

file
is a pointer to the base address of the SW00SR slot (defined in c$sw00sr.h) of the subfile that you want to access and is returned by the dfopn function.

nbr
is a variable containing one of the following based on the value of the nbr_type parameter:

Notes:

  1. If you use the #TPFDB0D algorithm, you must specify a specific LREC number for the value of nbr.

  2. LRECs are numbered in increasing order from the start of the subfile (the first LREC in the prime block has sequence number 1).

  3. If you specify this parameter with active keys, only those LRECs that match the key conditions are included in the sequence numbering; LRECs that do not match are ignored.

  4. In functions that do not include the nbr_type parameter, the value of nbr is a specific LREC number.

nbr_type
is one of the following:

DFRED_LIST
specifies that you are supplying a pointer to a list of LREC numbers (type dft_rcl) in the nbr parameter. The TPFDF product reads these LRECs in sequence on subsequent dfred function calls (unless you change the dfred parameters).

DFRED_LRECNBR
specifies that you are supplying the sequence number of a single LREC (type dft_nbr) in the nbr parameter. The TPFDF product reads the LREC with this sequence number.

DFRED_STACK
specifies that you are supplying a pointer to a stack area (type dft_stk) in the nbr parameter.

DFRED_STACKREF
specifies that you are supplying a stack reference number (type dft_srn) in the nbr parameter.

The DFRED_STACK and DFRED_STACKREF values allow you to read an LREC that you have retained with an earlier dfret function.

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

DFRED_BACKWARD
reads backward through the subfile; that is, the TPFDF product reads the LREC immediately before the current LREC position.

Notes:

  1. If you use DFRED_BACKWARD and also use the dfret function, you must specify DFRET_STACK or DFRET_STACKREF with the dfret function. See dfret-Retain a Logical Record Position for more information about these values and the dfret function.

  2. If you use DFRED_BACKWARD, the default and recommended setting for symbol &DB013A in the DBLCL macro is 0. This setting requires files to use full backward chaining (bit 0 of &SW00OP1 is set) to read backward. See TPFDF Database Administration for more information about defining full backward chaining. See TPFDF Installation and Customization for more information about the DBLCL macro.
Exception:
If the file uses add current processing (bit 2 of &SW00OP1 is set) with no chains (&SW00NOC = 0), you can specify DFRED_BACKWARD regardless of how bit 0 of &SW00OP1 is set.

DFRED_BEGIN
reads LRECs from the start of the subfile.

DFRED_LAST
reads the last LREC from the subfile. If you have specified keys with the read, the TPFDF product reads the last LREC that matches the keys.

DFRED_PREVIOUS
reads the LREC saved with the last dfret function that used a DFRET_CURRENT value for the ret_type parameter.

DFRED_FAST
used for migration purposes only; use the DFRED_INLINE or DFRED_NOKEY values instead. If you specify this value, the DFRED_NOKEY value is implemented; that is, keys that are currently active are deactivated.

DFRED_HEADER
locates the subfile header in the prime block and returns the address in field SW00RC rather than the address of an LREC.

If you specify the DFRED_HEADER and DFRED_FULLFILE values on an open subfile, the dfred function retrieves the header of the next subfile.

DFRED_INLINE
provides inline processing for this function. You can only use this value if you are reading LRECs sequentially, without any key parameters. This option also deactivates any keys that are currently active; that is, any previous key arguments are set to zero.

DFRED_FULLFILE
reads an LREC from any of the subfiles in the file. If you do not specify this value, you can only read an LREC in the current subfile.

DFRED_INDEX_HOLD
potentially holds any index files that reference the subfiles you are accessing and prevents two or more application programs from modifying the index files at the same time. Holding occurs if bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2= parameter in the DBDEF macro, have been set appropriately. Subsequent TPFDF calls by other ECBs to modify the index file will not occur until the index file is no longer held. If more than one application can update the same index file, or the file is processed in fullfile mode, you must specify this value to ensure the updates are synchronized.

See TPFDF Database Administration for information about how bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2= parameter in the DBDEF macro, affect hold processing.

DFRED_NODUMP
specifies that you do not want the TPFDF product to issue any of the following system errors while processing this function:
  • DB0100
  • DB0102
  • DB0117
  • DB0123
  • DB0138
  • DB0140.

See Messages (System Error, Online, Offline) and Master Glossary for more information about these system errors.

Note:
Using the DFRED_NODUMP value is not recommended because it can prevent system errors from being issued that indicate a critical problem.

DFRED_NOKEY
deactivates any currently active keys.

DFRED_USR
returns a pointer to the userLREC. Use this option when working with extended LRECs. See Using Extended Logical Records for more information about extended LRECs.

0
specifies that you do not want to use any processing options.

pth
is the path number for a detail subfile using index support. The value is defined in the DBDEF macro and is a decimal number (0, 1, 2, and so on). The default path number is 0.

See TPFDF Database Administration for more information about path indexes.

Entry Requirements

If you specify the DFRED_PREVIOUS, DFRED_STACK, or DFRED_STACKREF values, you must first open the subfile using the DFOPN_DETAC or DFOPN_HOLD values for the options parameter on the dfopn function.

Normal Return

Error Return

 See Identifying Return Indicators and Errors for information about how to check the error indicators. 

Programming Considerations

Examples

Related Functions