dfcre: Create a subfile

Use this group of functions to create a new subfile, an empty pool subfile, or an empty indexed pool subfile with its corresponding index file. You can subsequently add logical records (LRECs) to the empty detail subfile as required.

Last updated

Changed for PUT11.
Changed for PUT10.
Changed for PUT00.

Format

dft_hdr *dfcre(dft_fil *file, dft_opt options);

dft_hdr *dfcre_chka(dft_fil *file, dft_opt options, dft_rcc rcc

dft_hdr *dfcre_alg(dft_fil *file, dft_opt options, dft_alg *alg);

dft_hdr *dfcre_alg_chka(dft_fil *file, dft_opt options, dft_alg *alg,
        dft_rcc rcc);

dft_hdr *dfcre_alg_pth_all(dft_fil *file, dft_opt options, dft_alg *alg);

dft_hdr *dfcre_alg_pth_all_chka(dft_fil *file, dft_opt options, dft_alg *alg,
        dft_rcc rcc);

dft_hdr *dfcre_alg_pth(dft_fil *file, dft_opt options, dft_alg *alg,
        dft_pth pth);

dft_hdr *dfcre_alg_pth_chka(dft_fil *file, dft_opt options, dft_alg *alg
        dft_pth pth, dft_rcc rcc);

Options Parameter Values

alg

A pointer to an algorithm argument that identifies the subfile.

The z/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 z/TPFDF product uses the algorithm argument to locate the subfile. For more information about how the z/TPFDF product uses the algorithm argument to locate the subfile, see z/TPFDF Database Administration.

Note: The area of storage that contains the algorithm argument must not be modified and must be accessible to the z/TPFDF product until the subfile is closed and the SW00SR is released.

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.

rcc

is the user-defined record check (RCC) used in the created subfile, where rcc is a 1-byte field that contains the RCC value.

options

are the processing options for this function. Use one of the following values:

DFCRE_INDEX

creates an indexed subfile and inserts an index LREC referencing this subfile into the related index file (or files) defined by the database administrator.

If you have supplied an algorithm argument when you opened the subfile (using a dfopn function), you can use DFCRE_INDEX with the dfcre function. If not, you must use the dfcre_alg function and supply an algorithm argument in the alg parameter.

If you specify this value, the algorithm defined for the new subfile must be #TPFDBFF.

0

Specifies that you do not want to use any processing options.

pth

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.

For more information about path indexes, see z/TPFDF Database Administration.

Entry requirements

None.

Return conditions

A pointer to the main storage address of the header of the prime block of the created subfile.

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.
If any of the following parameters contain addresses above 2 GB, performance may be affected. The alg parameter (pointer to an algorithm) can affect performance if passed above the 2 GB bar.
Set the options parameter to zero if you do not require any processing options.
A dfadd function creates a subfile, if one does not exist, before it adds the LREC. (If you are adding an LREC to an indexed detail file, you must use the DFADD_INDEX value of the options parameter or use a dfidx function to index the subfile.)
Alternatively, you can call dfcre before you add an LREC to a subfile to create the subfile if it does not already exist.
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 creates a new indexed subfile using the algorithm argument member_number.

dft_fil *file_ptr;
char member_number[10];
⋮
(void)dfcre_alg(file_ptr, 0, member_number);

Related information

See the following functions for more information:
See z/TPFDF Database Administration for more information about path indexes and how the z/TPFDF product uses the algorithm argument to locate the subfile.