bdfp1m22Programming Concepts and Reference

DBCLS-Close a Subfile

Use this macro 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




REF=dsectvv
specifies the file or subfile that you want to access, where dsectvv is the DSECT name and an optional 2-character version.

REF=refname
specifies the file or subfile that you want to access, where refname is a label that references the DSECT name in one of the following formats:

refname
is the label of an 8-byte field that contains the 6-byte DSECT name and an optional 2-character version.

A/refname
is the label of a 4-byte field that contains the storage address of the DSECT name and an optional 2-character version.

REF=ALL
closes all open subfiles. If you specify REF=ALL, only those subfiles that you opened using the DBOPN macro without the R3 parameter specified are closed.
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.

EXCLUDE
closes all files except those specified with this parameter.

INCLUDE
closes only the files specified with this parameter. If any of the listed files are not open, they are ignored.

fname
is the reference name of the file or files that you want to exclude or include in the DBCLS macro processing.

LIST=loc
specifies a list of files to be included in or excluded from the DBCLS macro processing, where loc is one of the following:

For example:

DBCLS REF=ALL,EXCLUDE=(LIST=GR25LST)

The specified location must start with a halfword stating the number of files listed, followed by a list of 8-byte reference names.

For example, GR25LST can contain the following data:

DC   H'3'
DC   C'GR25DF  '
DC   C'GR25DA  '
DC   C'GR25DB  '

FILE=dsect
specifies the file or subfile that you want to access, where dsect is the DSECT name.

R3=address
specifies the location of the SW00SR slot for this subfile, where address is the label of a field that contains the address of the SW00SR slot. Register 3 will be loaded with this address.
Note:
Do not use this parameter; it is provided only for migration purposes. Use the REF parameter to specify the file that you want to access.

ABORT
causes all database updates since the file was opened, or since the last DBCKP macro, to be discarded. The updates are not written to DASD.
Note:
Use this option only if the subfile is in detac mode.

ALG=algarg
identifies the subfile that you want to access, where algarg specifies an algorithm argument.

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.

Specify algarg as one of the following:

Note:
Do not modify the area of storage containing the algorithm argument until the subfile is closed.

NOPGM
specifies not to change the program stamp in a block when filing it.

PACK
packs the subfile.

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.

PATH
specifies the path for a detail subfile using index support. If there is only one index path, do not specify this parameter. Specify one of the following:

pathnum
is the path number or the label of a 2-byte field that contains the path number. The number of index paths used is defined by your database administrator.

ALL
specifies all paths.

See TPFDF Database Administration for more information about path numbers.

RELEASE
releases the SW00SR slot for the subfile after the macro has completed processing.

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.

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.

NEWREF=newrefn
changes the reference name of the file specified with the REF parameter, where newrefn is one of the following:

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 RELFC parameter to release W-type files.

SUFFIX=char
allows you to use the same DSECT to map two different areas of storage, where char is the suffix character.

TAPE
closes the tape or sequential data set at the same time as any subfiles are closed. You must specify this parameter if you specified the TAPE parameter on a previous DBOPN macro.
Note:
Do not use the TAPE parameter with the TM parameter specified with a value of YES because the integrity of the commit scope could be compromised, and files that are on tape cannot be rolled back.

TM
specifies one of the following:

NO
specifies that commit scopes are not used during close processing, regardless of what the database definition (DBDEF) macro has set as the default.

YES
specifies that commit scopes are used during close processing, regardless of what the 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).

Entry Requirements

None.

Normal Return

None.

Error Return

None.

Programming Considerations

Examples

Related Macros