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.

Last updated

  • Changed in 2021.
  • Changed in 2020.
  • Changed for PUT13.
  • Changed for PUT11.
  • Changed for PUT10.
  • Changed for PUT08.
  • Changed for PUT06.
  • Changed for PUT05.
  • Changed for PUT04.
  • Changed for PUT03.
  • Changed for PUT01.
  • Changed for PUT00.

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);
List_Type Parameter Values
Read syntax diagramSkip visual syntax diagramDFCLS_INCLUDEDFCLS_EXCLUDE
Options Parameter Values
Read syntax diagramSkip visual syntax diagram|DFCLS_ALLDFCLS_ALWAYSDFCLS_TAPECommit Scope OptionsDetac Mode Disposition OptionsPacking OptionsSW00SR Disposition Options0
Commit Scope Options
Read syntax diagramSkip visual syntax diagramDFCLS_TMDFCLS_NO_TM
Detac Mode Disposition Options
Read syntax diagramSkip visual syntax diagramDFCLS_COMMITDFCLS_ABORTDFCLS_RELFC
Packing Options
Read syntax diagramSkip visual syntax diagramDFCLS_PACKDFCLS_NOPACK
SW00SR Disposition Options
Read syntax diagramSkip visual syntax diagramDFCLS_RELEASEDFCLS_NORELEASEDFCLS_REUSE
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 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
A pointer to a structure that contains a list of files.
new
A pointer to a new reference name (up to 8 bytes). If less than 8 bytes are specified, it must be null-terminated. The z/TPFDF product will pad it with blanks (X'40') to build an 8-byte reference name. Specify this parameter only if you specify the DFCLS_REUSE or DFCLS_NORELEASE values for the options parameter.
options
The processing options for this function. Use the following values:
DFCLS_ABORT
Discards all database updates that were made since the subfile was opened or since the last dfckp function. The updates are not written to DASD.
Notes:
  • The DFCLS_ABORT value is valid only if the subfile was opened in detac mode. If the subfile was not opened in detac mode, some updates might be already written to DASD by previous z/TPFDF functions, and only the updates that are still pending are skipped during close processing.
  • If you specify DFCLS_ABORT for this parameter for a detail subfile that was created in the current open through close sequence, the following conditions occur:
    • The index reference to the created subfile is cleared. If there are no other references in the index LREC, the index LREC is deleted.
    • The system releases the created detail subfile by issuing the z/TPF relfc function.
DFCLS_COMMIT
Writes all blocks that have been modified since the last dfopn or dfckp function to DASD.
Note: The DFCLS_COMMIT value is ignored if the subfile is not opened in detac mode because all updates have been written to DASD by previous z/TPFDF functions.
DFCLS_RELFC
Deletes the subfile. All overflow blocks are released.

If the subfile is a remote subfile, the document that corresponds to the subfile is deleted from the remote data store.

If the file is a pool file, the following conditions occur:

  • The prime block is also released.
  • If the subfile is indexed, one of the following conditions occurs:
    • If an algorithm was specified on the dfcls function or on a previous API that manages this subfile, the subfile is deindexed from the specified path.
    • If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the subfile will be deindexed from all its indexes.
    Note: In both cases, the application cannot open the indexes with the DFOPN_HOLD option specified in the same ECB.

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

Because W-type files are automatically released, you do not need to specify the DFCLS_RELFC option to release W-type files unless they have been sorted, merged, or checkpointed.

Note: Except for indexing errors, if an error occurs before the subfile is closed, the DFCLS_RELFC option is ignored.
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 z/TPFDF Database Administration for more information about the packing threshold.
DFCLS_ALL
Closes all open files except for subfiles defined as always open (ALWAYS=YES coded on the DBDEF macro), which are not closed unless the DFCLS_ALWAYS value is also coded on the dfcls function.nd see

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_ALWAYS
Indicates that the file is to be closed even if it is defined as always open when ALWAYS=YES is coded on the DBDEF macro.

If DFCLS_ALWAYS is not coded and the subfile is defined as always open, dfcls processing returns to the application and the subfile remains open until the ECB exits.

DFCLS_TAPE
Closes the tape or sequential data set at the same time that any subfiles are closed. The tape name is obtained from when you specified the tpn parameter previously on a dfopn, dftlg, or dftrd function call.
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.

If this file uses recoup optimized chain chasing, z/TPFDF might use commit scopes during checkpoint and close processing when the recoup optimized chain chase information is updated for the subfile.

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

Entry requirements

None.

Return conditions

None.

Error return

None.

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 following parameters can affect performance if passed above the 2 GB bar:
    • alg (pointer to an algorithm)
    • new (pointer to a new reference name).
  • Do not check the error indicators in the SW00RTN field of the SW00SR slot. When you close a subfile, the dfcls function releases the SW00SR slot for the file (unless you specify the DFCLS_NORELEASE or DFCLS_REUSE values), so the error indicators are not available for you to check. When you specify the DFCLS_NORELEASE or DFCLS_REUSE values the SW00SR slot is not released, but the error indicators are not valid.
  • Deleting LRECs from a subfile leaves empty space in the blocks. If you do not specify the DFCLS_PACK or DFCLS_NOPACK value and the file is not a B+Tree file, the subfile is packed if the amount of space occupied by LRECs in any block falls below the threshold defined in the database definition (DBDEF).

    B+Tree files are not packed during close processing unless the DFCLS_PACK value is specified or there are no nodes in the B+Tree index.

  • It is not necessary to close W-type files containing T-type LRECs (T-type DSECTs). In addition, it is not necessary to close W-type file that are open in detac mode. See z/TPFDF Database Administration for more information about T-type DSECTs and W-type files.
  • If you open a file that is defined as always open (ALWAYS=YES is coded on the DBDEF macro) with the DFOPN_HOLD value specified, you must explicitly close the file with the DFCLS_ALWAYS value coded. It is not necessary to close files that are defined as always open if the subfile was opened with the DFOPN_NOHOLD value specified.
  • The dfcls functions do an internal dfdix function when you specify a DFCLS_RELFC value in the options parameter and the file is indexed.
  • If you do not specify the DFCLS_INCLUDE value with the dfcls_lst function and an attempt is made to close a subfile that is not open, the z/TPFDF product issues a DB0115 system error.
  • If you specify DFCLS_ALL with the DFCLS_TM value and more than one file is open, the files in a commit scope are processed individually.
  • If the AUTODEINDEX=YES parameter is specified on the DBDEF macro and an indexed subfile is empty when the subfile is closed, the 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.
  • 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 closes all open subfiles. 
    dfcls(NULL, DFCLS_ALL);
  • The following example closes a specific subfile and commits all changes. The alternative is to use DFCLS_ABORT. 
    dft_fil *file_ptr;
⋮
dfcls(file_ptr, DFCLS_COMMIT);
  • The following example closes a list of subfiles. If any of the listed subfiles are not open, the subfiles that are not open are ignored. 
    struct
{
  dft_rfl rl;
  char more_refs[5][8];  /* allows a total of 6 references */
  char ch;               /* room for zero byte             */
} close_list;

short int count = 3;

memcpy(&close_list,"  GR95SR  GR91SR  GR93SR  ",26);
memcpy(&close_list,&count,2);
dfcls_lst(NULL,DFCLS_INCLUDE,0,&close_list);

For more information about the DBDEF macro and also about the packing threshold and how the z/TPFDF product uses the algorithm argument to locate the subfile, see z/TPFDF Database Administration.