dfcls-close a subfile

Format

void dfcls_lst(dft_fil *file, dft_opt list_type, dft_opt options,
        dft_rfl *lst);

List_Type Parameter Values:

Options Parameter Values:

Commit Scope Options:

Detac Mode Disposition Options:

Packing Options:

SW00SR Disposition Options:

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 (up to 8 bytes). If less than 8 bytes are provided, it must be null-terminated. The 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

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:

1. The prime block is also released.
2. If the subfile is indexed:
   • If an algorithm was specified either on the dfcls function or on a previous API manipulating this subfile, the subfile is de-indexed from the specified path.
   • If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the subfile will be de-indexed from all its indexes.
   Note:
   In both cases, the application cannot open the indexes with the HOLD option in the same entry control block (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.

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_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

Normal return

Error return

Programming considerations

• The type definitions (for example, dft_fil, dft_ref, and dft_kyl) are defined in the c$cdfapi.h header file.
• 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 TPFDF Database Administration for more information about T-type DSECTs and W-type files.
• 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 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 de-indexed from all its indexes and all corresponding pool file addresses will be released. The application cannot open the indexes with the HOLD option in the same ECB.

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

Related information

• dfopn-Open a Subfile
• dfckp-Checkpoint a Subfile
• See TPFDF Database Administration for more information about the DBDEF macro and also about the packing threshold and how the TPFDF product uses the algorithm argument to locate the subfile.