bdfp1m13Programming Concepts and Reference

dfcls-Close a Subfile

Use this group of functions to close one or more subfiles. You can also choose whether you want to write modified blocks that are in detac mode to DASD.

Format

void dfcls(dft_fil *file, dft_opt options);
void dfcls_lst(dft_fil *file, dft_opt list_type, dft_opt options,
        dft_rfl *lst);
void dfcls_alg(dft_fil *file, dft_opt options, dft_alg *alg);
void dfcls_new(dft_fil *file, dft_opt options, dft_ref new);



alg
is a pointer to an algorithm argument that identifies the subfile.

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.

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.

If you specify the DFCLS_ALL value for the options parameter, specify NULL for the file parameter.

list_type
specifies which files to close. Use one of the following values:

DFCLS_INCLUDE
closes only the files listed in the structure pointed to by the lst parameter. If any of the listed files are not open, they are ignored.

DFCLS_EXCLUDE
closes all files except those listed in the structure pointed to by the lst parameter.

Do not specify DFCLS_INCLUDE or DFCLS_EXCLUDE if you use the DFCLS_ALL value for the options parameter.

lst
is a pointer to a structure that contains a list of files.

new
is a pointer to a new reference name. Specify this parameter only if you specify the DFCLS_REUSE or DFCLS_NORELEASE values for the options parameter.

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

DFCLS_ABORT
causes all database updates since the file was opened, or since the last dfckp function, to be discarded. The updates are not written to DASD.
Note:
The DFCLS_ABORT option is ignored if the subfile is not opened in detac mode because all updates have been written to DASD by previous TPFDF functions.

DFCLS_COMMIT
writes all blocks that have been modified since the last dfopn or dfckp function to DASD.
Note:
The DFCLS_COMMIT option is ignored if the subfile is not opened in detac mode because all updates have been written to DASD by previous TPFDF functions.

DFCLS_RELFC
releases the 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.

W-type files are automatically released unless they have been sorted, merged, or checkpointed. In these cases, you must specify the DFCLS_RELFC value to release W-type files.

DFCLS_RELEASE
releases the SW00SR slot when the subfile is closed.

DFCLS_NORELEASE
prevents the SW00SR slot from being released when the file is closed. Any key parameters you have defined are also retained. Specify this parameter if you intend to process the same subfile at a later time.

DFCLS_REUSE
retains the SW00SR slot of the file. Any key parameters you have defined are also retained. Specify this parameter if you intend to retrieve another subfile in the same file at a later time.

DFCLS_PACK
packs the subfile.

DFCLS_NOPACK
specifies that you do not want to pack the subfile, even if a block has fallen below the packing threshold defined by the PIN parameter on the DBDEF macro. See TPFDF Database Administration for more information about the packing threshold.

DFCLS_ALL
closes all open files.

Do not specify DFCLS_ALL if you use the DFCLS_INCLUDE or DFCLS_EXCLUDE value for the list_type parameter.

Note:
When you use this parameter, all database interface blocks (DBIFBs), which contain SW00SR slots, are released. However, DBIFBs are not released if there are no files open or any of the following parameters have been specified:
  • EXCLUDE
  • INCLUDE
  • NORELEASE
  • REUSE.

DFCLS_TAPE
closes the tape or sequential data set. You must specify this value if you opened the subfile with a tape name (tpn parameter).
Note:
Do not use this value with the DFCLS_TM value because the integrity of the commit scope could be compromised, and files that are on tape cannot be rolled back.

DFCLS_TM
specifies that commit scopes are used during close processing, regardless of what the database definition (DBDEF) macro has set as the default. This option is valuable when many files are to be filed out during close processing (for example, detac mode, extensive B+Tree indexing updates, and requests that result in packing).

DFCLS_NO_TM
specifies that commit scopes are not used during close processing, regardless of what the DBDEF macro has set as the default.

0
specifies that you do not want to use any processing options.

Entry Requirements

None.

Normal Return

None.

Error Return

None.

Programming Considerations

Examples

Related Functions