dfsrt: Sort a subfile

Use this function to sort logical records (LRECs) from a single input subfile or from multiple input subfiles into an open output subfile.

Last updated

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

Format

void dfsrt(dft_fil *file, dft_fil *input, dft_opt options, dft_kyl *key_list);
void dfsrt_pty(dft_fil *file, dft_fil *input, dft_opt options,
     dft_kyl *key_list, dft_pty pty);
Options Parameter Values
Read syntax diagramSkip visual syntax diagram|DFSRT_FULLFILEDFSRT_RELEASEDFSRT_RELFC0
file
A pointer to the base address of the SW00SR slot (defined in c_sw00sr.h) of the output subfile.
input
A pointer to the SW00SR slot of the input subfile, whose LRECs you chose to select and sort into the output file.
key_list
The address of the sort key list of the output subfile specifying the order into which you want to sort the LRECs. See Specifying logical records (LRECs) using keys for more information about key lists.
options
The processing options for this function. Use the following values:
DFSRT_FULLFILE
Sorts LRECs from the entire input file (specified in input), not from a single subfile. See dfopt: Set optional information for more information about specifying ordinal ranges, partitions, or interleaves.
Note: This parameter cannot be specified if the input file is a W-type file.
DFSRT_RELEASE
Releases the SW00SR slot of the input subfile (specified in input).
DFSRT_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 dfsrt 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 DFSRT_RELFC option is ignored.
0
Specifies that you do not want to use any processing options.
pty
The pool type of the overflow blocks, which can be one of the following:
0
Uses the pool type defined by the PF0 parameter of the DBDEF macro.
1
Uses the pool type defined by the PF1 parameter of the DBDEF macro.
2
Uses the pool type defined by the PF2 parameter of the DBDEF macro.

Entry requirements

  • Both subfiles must be opened before you call the dfsrt function.
  • 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.
  • Any keys that are active for the input file when you call this function are used to select records from the input file.
  • The keys that you specify with this function are used to sort the LRECs in the output subfile. The key list parameter is ignored for files with default add keys defined in the DBDEF macro. The default keys will override any keys provided with the dfsrt function. For more information about default keys, see z/TPFDF Database Administration.
  • If the output file is a W-type file, it will be checkpointed internally and will become and R-type file until the file is closed.
  • This function does not change the input subfile unless the DFSRT_RELFC option is specified.
  • The z/TPFDF product creates the output subfile for you when there is no file address associated with the output file (for example, if the output file was opened without access parameters DFOPN_ALG, DFOPN_FADDR, DFOPN_FADDR8, or DFOPN_ORD) before sort processing.
  • When you use this function to sort large input files, use detac mode for the output file to ensure optimum system performance.
  • The location of the input subfile and the output subfile is unchanged after the sort. 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.
  • If the output file was opened in detac mode or is stored in a remote data store:
    • If the number of blocks in the output file exceeds the maximum sort batch file size (as defined with #TPFDBSB in the ACPDBE macro), the dfsrt will put the sorted output in a newly created pool file. If the original output file is stored in a remote data store, the newly created file will be stored in the same remote data store. The output file originally associated with the SW00SR referenced by the file parameter is emptied (any blocks previously chained to the prime block are released). If the prime was a pool file address it is also released. Therefore, whenever the output file is in detac mode, if you need to reference the file address of the output file, you should reload the address from SW00FAD (or SW00FAD8).
    • Only the prime block will be in core after dfsrt processing has been completed.
  • When dfsrt processing has been completed, the output subfile remains open and must be closed by using the dfcls function before the ECB exits.
  • If the DFSRT_RELEASE parameter value is not specified, the input file is closed internally without releasing the SW00SR. You can enter subsequent APIs for the input file, but you must re-establish keys with the dfkey function and specify the DFxxx_FADDR (or DFxxx_FADDR8) option on the next function for the input file, where xxx specifies the operation to be performed. After sort processing has been completed, any new access of the input file will be with DFOPN_HOLD regardless of the parameter value specified originally on the dfopn function of the input file.
  • The output file must be the same LREC type as the input file. For example, if the input subfile contains variable-length LRECs, you can use standard sort output file SR05SR, which is provided with the z/TPFDF product, by specifying its FILE ID (FD0F) for the output file. If you do not use SR05SR, you must specify a subfile of the same LREC type as the input file.
  • You cannot issue additional z/TPFDF functions to the input file if the following conditions are true:
    • You specified the DFSRT_FULLFILE option.
    • The end-of-file indicator is set.

    See Identifying return indicators and errors for information about the end-of-file indicator.

  • You cannot use this function with P-type files, add current files, or pushdown chaining files.
  • If the output file contains data when the dfsrt function is called, that data must be in the correct sequence already according to the keys specified with the dfsrt function. Otherwise, the data that existed already in the output file will not be sorted correctly.
  • Figure 1 shows how the dfsrt function sorts LRECs from an input subfile into an output subfile.
    Figure 1. Sorting LRECs from One Subfile into Another. The input file is defined by the input parameter and the output file is defined by the file parameter.
  • If you use the dfsrt function in a commit scope, both input and output files must be opened 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 sorted, 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 selects LRECs from the subfile in_file_ptr using key list structure selectkeys and puts them into subfile out_file_ptr in the order described by the sortkeys key list structure.
dft_fil *in_file_ptr;
dft_fil *out_file_ptr;
dft_kyl sortkeys;
dft_kyl selectkeys;

/* set up the keys to use to sort the output file */

df_nbrkeys(&sortkeys, 1);

df_setkey(&sortkeys, 1, offsetof(struct gr95sr, gr95nam),
          member_size(struct gr95sr, gr95nam),
          0, NULL, 0, DF_UPORG, DF_CHAR);

/* set up the keys to use to select the LRECs in the input file */

df_nbrkeys(&selectkeys, 1);

df_setkey(&selectkeys, 1, offsetof(struct gr95sr, gr95key),
          1, DF_EQ, &pky, 0, DF_UPORG, DF_CHAR);

dfkey(in_file_ptr, &selectkeys);

/* sort the subfile after extracting matching LRECs */
/* release the input file after the sort */
/* (the key list in the command is the sort key specification) */

dfsrt(out_file_ptr, in_file_ptr, DFSRT_RELEASE, &sortkeys);
The following example sorts the LRECs from all subfiles in all partitions of a partitioned file using the z/TPFDF standard sort output file SR05SR.
/* dfsrt fullfile with partition
all */

#include <c_sr05sr.h>
dft_fil *in_file_ptr;
dft_fil *out_file_ptr;
dft_kyl sortkeys;

/* open the input file and specify ALL partitions              */

  in_file_ptr = dfopn("GR34SR  ",GR34SRI,0);
  dfopt1(in_file_ptr, DFOPT_PARTITION , DFOPT_ALL);
 
/* open the output file SR05SR and setup the sort keylist      */

  out_file_ptr = dfopn("SR05SR  ",DF_SR05SRI, DFOPN_HOLD);
 
df_setkey(&sortkeys,1,offsetof(GR34SR,GR34KEY),   
        1, DF_EQ, NULL, 0, DF_UPORG, DF_CONST);   
df_setkey(&sortkeys,2,offsetof(GR34SR,GR34FAD),        
   4, DF_EQ, NULL, 0, DF_DOWNORG, DF_CHAR);  
df_nbrkeys(&sortkeys, 2);

/* sort all subfiles of all partitions into SR05SR             */

/* the input file is closed by dfsrt                           */
  dfsrt(out_file_ptr, in_file_ptr, DFSRT_FULLFILE, &sortkeys);

  dfcls(0, DFCLS_ALL);
For more information about the DBDEF macro, see z/TPFDF Database Administration.

For more information about the ACPDBE macro, see z/TPF and z/TPFDF System Generation.