dfcpy-copy a subfile
Use this group of functions to copy a subfile to a target file address (if specified) or to a new pool file. After processing the function, the TPFDF product closes the original subfile and performs all subsequent actions on the copy.
Format
dft_hdr *dfcpy(dft_fil *file, dft_opt options);
dft_hdr *dfcpy_acc(dft_fil *file, dft_opt access, dft_opt options,
dft_xxxacc);dft_hdr *dfcpy_toa(dft_fil *file, dft_opt options, dft_fad toa);
dft_hdr *dfcpy_toa8(dft_fil *file, dft_opt options, dft_fad8 *toa8);
dft_hdr *dfcpy_acc_toa(dft_fil *file, dft_opt access, dft_opt options,
dft_xxxacc, dft_fad toa);dft_hdr *dfcpy_acc_toa8(dft_fil *file, dft_opt access, dft_opt options,
dft_xxxacc, dft_fad8 *toa8);dft_hdr *dfcpy_acc_pth(dft_fil *file, dft_opt access, dft_opt options,
dft_xxxacc, dft_pth pth);dft_hdr *dfcpy_acc_toa_pth(dft_fil *file, dft_opt access, dft_opt options,
dft_xxxacc, dft_fad toa, dft_pth pth);dft_hdr *dfcpy_acc_toa8_pth(dft_fil *file, dft_opt access, dft_opt options,
dft_xxxacc, dft_fad8 *toa8, dft_pth pth);Access Parameter Values:
|--+-DFCPY_ALG----+---------------------------------------------|
+-DFCPY_FADDR--+
+-DFCPY_FADDR8-+
'-DFCPY_ORD----'
Options Parameter Values:
.-|----------------.
V |
|--+---+-DFCPY_CREATE-+-+-+-------------------------------------|
| '-DFCPY_HELD---' |
'-0--------------------'
- 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:
- DFCPY_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.
- DFCPY_FADDR
- specifies that you are providing a 4-byte file address forthe acc parameter. A file address is in integer format. The acc parameter is of type dft_fad.
- DFCPY_FADDR8
- specifies that you are providing a pointer to an 8-byte file address for the acc parameter. The acc parameter is of type * dft_fad8.
- DFCPY_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 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
- are the processing options for this function. Use the following values:
- DFCPY_CREATE
- creates an empty subfile by using pool blocks instead of copying the original subfile.
- DFCPY_HELD
- specifies that the entry control block (ECB) is already holding the file address specified by the toa or toa8 parameter. You can use this value only if you specify a toa or toa8 parameter.
- 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.
- toa
- is a 4-byte target prime block file address.
If used in a commit scope, the prime block specified by the toa parameter must be opened in the same commit scope as the subfile that is being copied. See Commit Scopes for more information about commit scopes.
- toa8
- is a pointer to an 8-byte target prime block file address.
If used in a commit scope, the prime block specified by the toa8 parameter must be opened in the same commit scope as the subfile that is being copied.
Entry requirements
None.
Normal return
A pointer to the main storage address of the header of the prime block of the copy of the subfile.
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.
- This function sets up a 2-byte sequence number in the SW00SEQ field in the SW00SR slot. You can specify this sequence number to restore the same subfile with a subsequent dfrst function.
- When a B+Tree file is copied, the dfcpy function builds the B+Tree index for the new file.
- If the source and destination subfiles do not have the same header and file address format types, an error is returned. If a new pool is allocated, it is created using the same header and file address format as the source.
Examples
dft_fil *file_ptr;
dft_hdr *block_ptr;
·
·
·
block_ptr = dfcpy(file_ptr, 0);