bdfp1m1l | Programming Concepts and Reference |
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
- 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. See the description of the specific
parameter for information about what type definition to use for that
parameter.
- The dfrst function rebuilds the B+Tree index for
B+Tree files.
Examples
- The following example restores a subfile that might be being held (by this
or another application).
dft_fad fad;
dft_fil *file_ptr;
·
·
·
dfrst(file_ptr, DFRST_HELD, fad);
- The following example restores a subfile from a specified file address
(contained in file_address).
dft_fil *file_ptr;
dft_fad file_address;
·
·
·
dfrst(file_ptr, 0, file_address);
Related Functions
dfcpy-Copy a Subfile.