bdfp1m1lProgramming Concepts and Reference

dfrst-Restore a Subfile

Use this group of functions to restore a subfile (previously copied by a dfcpy function) to a file address that you specify.

Format

void dfrst(dft_fil *file, dft_opt options, dft_fad rstaddr);
void dfrst_acc(dft_fil *file, dft_opt access, dft_opt options,
     dft_fad rstaddr, dft_xxx acc);
void dfrst_seq(dft_fil *file, dft_opt options, dft_fad rstaddr,
     dft_seq seq);
void dfrst_acc_seq(dft_fil *file, dft_opt access, dft_opt options,
      dft_fad rstaddr, dft_xxx acc, dft_seq seq);



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:

DFRST_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.

DFRST_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.

DFRST_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.

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.

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

DFRST_FLIP
specifies to flip the subfiles specified in the rstaddr and file parameters.

DFRST_FROMCHAIN
restores only the prime block of the subfile. Any overflow blocks in the subfile are chained to this new prime block without copying the overflow blocks to new pool blocks.

DFRST_HELD
restores a subfile that is already held (for example, if you have opened the subfile with a DFOPN_HOLD value).

DFRST_SEQ
specifies that you want to check the sequence number when it restores the subfile. This ensures that if there are several copies of a subfile, you restore the correct one.

If you use this value, you must have supplied a sequence number when you copied the subfile using a dfcpy function.

rstaddr
is the file address to which you want to restore the subfile.

seq
is an update sequence number. The number you provide must match the sequence number contained in the subfile that is specified by the rstaddr parameter.

If the numbers do not match, the dfrst function does not proceed and issues an error return. If the numbers match, the dfrst function restores the subfile and increases the sequence number by 1. This sequence number is placed in the prime block of the restored subfile.

Entry Requirements

Before you can use the dfrst function, you must make a copy of a subfile using the dfcpy function. You can modify this copy using other TPFDF functions.

Normal Return

The restored file (with any modifications you have made to the copy) becomes the currently open subfile. You can continue processing it using other TPFDF functions. The copy is released unless you use the DFRST_FLIP value.

Error Return

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

Programming Considerations

Examples

Related Functions

dfcpy-Copy a Subfile.