bdfp1m13 | Programming Concepts and Reference |
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
- 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 Functions