dfmrg: Merge logical records from two subfiles

Use this function to merge two subfiles into one subfile.

Last updated

  • Changed in 2022 (information only; no code change).
  • Changed in 2021.
  • Changed in 2020.
  • Changed for PUT11.
  • Changed for PUT10.
  • Changed for PUT03.
  • Changed for PUT01.
  • Changed for PUT00.

Format

void dfmrg(dft_fil *file, dft_fil *input,
     dft_opt options, dft_kyl *key_list);
Options Parameter Values
Read syntax diagramSkip visual syntax diagram|DFMRG_FULLFILEDFMRG_RELEASEDFMRG_RELFC0
file
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.
input
A pointer to the SW00SR slot of the input subfile that will be merged into the subfile referenced by file.
key_list
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
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 subfile is indexed, one of the follow conditions occurs:
    • If an algorithm was specified either on the dfmrg function or on a previous API manipulating this subfile, the subfile is deindexed from the specified path.
    • If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the input subfile will be deindexed from all its indexes.
    Note: In both cases, the application cannot open the indexes with the DFOPN_HOLD option in the same entry control block (ECB).

If the file is a fixed file, the prime block is initialized to empty.

Note: Except for indexing errors, if an error occurs before the subfile is closed, the DFMRG_RELFC option is ignored.
0
Specifies that you do not want to use any processing options.

Entry requirements

  • You must open both subfiles before calling dfmrg.
  • If the input or output subfile contains large logical records (LLRs), the file address header format of the input and output subfiles must be the same.

Return conditions

None.

Error return

For information about how to check the error indicators, see Identifying return indicators and errors.

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. See dfsrt: Sort a subfile for more information about this function.
  • Any keys that are active for the input file when you call this macro will be ignored, but are preserved. If you want to select records from the input file, use the dfsrt function.
  • If the output subfile is not a B+Tree file, you must specify default keys on the DBDEF macro or specify the key_list parameter. If default keys are defined, they are used and the key_list parameter is ignored. The keys specify how the LRECs in the output subfile and input subfile are sorted already.

    If the file is a B+Tree file, default keys must be defined and the key_list parameter is ignored. The output file is sorted by using the default keys.

    See z/TPFDF Database Administration for more information about default keys.

  • The location of the input subfile and the output subfile is unchanged after the merge. If either subfile is stored in a remote data store before this function is called, the subfile is stored in the same data store after this function is called.
  • You cannot call additional z/TPFDF functions to the input file if the following conditions are true:
    • You specified the DFMRG_FULLFILE option.
    • The end-of-file indicator is set.

    However, you can issue the dfcls function with the DFCLS_REUSE parameter specified for the input file and then continue with additional z/TPFDF functions. See Identifying return indicators and errors for information about the end-of-file indicator. For more information about the macro, see DBCLS: Close a subfile .

  • 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 1 shows how the dfmrg function merges LRECs from two subfiles.
    Figure 1. Merging LRECs from two subfiles. The input file is defined by the input parameter and the output file is defined by the file parameter.
    Alternate text

    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.

  • 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.
  • If the AUTODEINDEX=YES parameter is specified on the DBDEF macro and an indexed subfile is empty when the input subfile is merged, the input subfile will be deindexed from all its indexes and all corresponding pool file addresses will be released. The application cannot open the indexes with the DFOPN_HOLD option in the same ECB in this case.
  • For programming considerations when you use this function with data event processing, see z/TPFDF API programming considerations for data event processing.

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);

For more information about the DBDEF macro, see z/TPFDF Database Administration.