bdfp1m1e | Programming Concepts and Reference |
Use this function to merge two subfiles into one subfile.
Format
void dfmrg(dft_fil *file, dft_fil *input,
dft_opt options, dft_kyl *key_list);
- 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.
- input
- is a pointer to the SW00SR slot of the input subfile that will be merged
into the subfile referenced by file.
- key_list
- is a pointer to the key list of the merged output file. See Specifying Logical Records (LRECs) Using Keys for more information about key lists.
- options
- are the processing options for this function. Use the following
values:
- DFMRG_FULLFILE
- merges LRECs from the entire input file to the output subfile referenced
by file.
- DFMRG_RELEASE
- releases the SW00SR slot of the input file after processing the
merge.
- DFMRG_RELFC
- releases the input subfile and deletes it from DASD. All overflow
blocks are released. If the file is a pool file, the prime block is
also released. If the file is a fixed file, the prime block is
initialized to empty.
- 0
- specifies that you do not want to use any processing options.
Entry Requirements
You must open both subfiles before calling dfmrg.
Normal Return
None.
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.
- After opening a file, if you use fullfile processing to access or
update records, you must continue to use fullfile processing on any subsequent
functions when available until the file is closed. Accessing or
updating subfiles using fullfile processing cannot be mixed with functions
that access or update records without using fullfile processing.
- Make sure the input file contains LRECs that are in the same order as the
output file. If the input file is not in the same order as the output
file, do not merge the files until they are in the same order. Use the
dfsrt function to arrange the input file in the same order as the
output file.
- The keys that you specify with this function are used to sort the
LRECs in the output subfile unless the file is a B+Tree
file. The keylist parameter is ignored for B+Tree
files. The output file is organized according default keys defined on
the DBDEF macro for the file. See TPFDF Database
Administration for more information about default keys.
- The output file cannot be in detac mode when you use the dfmrg
function.
- You cannot call additional TPFDF functions to the input file until the
file is closed if the following conditions are true:
- You specify the DFMRG_FULLFILE option
- You do not specify the DFMRG_RELEASE option
- The end-of-file indicator is set.
However, you can specify the DFCLS_REUSE value on the dfcls
function. See Identifying Return Indicators and Errors for information about the end-of-file indicator.
- When the dfmrg function has completed processing, the output
subfile is left open and must be closed using the dfcls function
before the ECB exits. If you specify the DFMRG_RELEASE value, the
dfmrg function will close the input file.
- You cannot use this function with P-type files.
- Figure 18 shows how the dfmrg function merges LRECs from
two subfiles.
Figure 18. Merging LRECs from Two Subfiles. The input file is defined by the input parameter and the output file is defined by the file parameter.
The merged subfile is in the sequence you specify in the key list pointed
to in the key_list parameter. The function does not modify the
input subfile that you specify with the input parameter. The
TPFDF product leaves the entry control block (ECB) data level for the input
subfile free after use.
- If you use the dfmrg function in a commit scope, open the files
or subfiles to be merged in the same commit scope. See Commit Scopes for more information about commit scopes.
Examples
The following example merges the two open subfiles referenced by file_ptr
and input_ptr. All the LRECs go into the file_ptr subfile.
/* first set up keys */
dft_fil *input_ptr;
dft_kyl keys;
df_nbrkeys(&keys, 1);
df_setkey(&keys, 1, offsetoff(struct gr95sr, gr95nam),
member_size(struct gr95sr, gr95nam), 0, NULL, 0, DF_UPORG, DF_CHAR);
dfmrg(file_ptr, input_ptr, 0, &keys);
Related Functions
dfsrt-Sort a Subfile.