bdfp1m16 | Programming Concepts and Reference |
Use this group of functions to delete:
- One or more logical records (LRECs) from an open subfile
- The LRECs in one or more subfiles of a file
- A complete extended LREC
- All of the LRECs in a file
- Some or all of the subfiles referenced from the LRECs that you delete
- One or more subLRECs in an extended LREC.
Format
dft_rec *dfdel(dft_fil *file, dft_opt options);
dft_rec *dfdel_acc(dft_fil *file, dft_opt access, dft_opt options, dft_xxx acc);
dft_rec *dfdel_lst(dft_fil *file, dft_opt list_type, dft_opt options,
dft_idl *lst);
dft_rec *dfdel_nbr(dft_fil *file, dft_opt nbr_type, dft_opt options,
dft_xxx nbr);
dft_rec *dfdel_acc_lst(dft_fil *file, dft_opt list_type, dft_opt access,
dft_opt options, dft_xxx acc, *dft_idl lst);
dft_rec *dfdel_acc_nbr(dft_fil *file, dft_opt nbr_type, dft_opt access,
dft_opt options, dft_xxx acc, dft_xxx nbr);
dft_rec *dfdel_lst_nbr(dft_fil *file, dft_opt list_type, dft_opt nbr_type,
dft_opt options, dft_idl *lst, dft_xxx nbr);
dft_rec *dfdel_acc_lst_nbr(dft_fil *file, dft_opt list_type,
dft_opt nbr_type, dft_opt access, dft_opt options,
dft_xxx acc, dft_idl *lst, dft_xxx nbr);
dft_rec *dfdel_sub(dft_fil *file, dft_opt options,
dft_sno sub, dft_qty qty);
- acc
- is an ordinal number, a file address, or a pointer to an algorithm string
that specifies the subfile you want to access. The type for this
parameter is determined by the value you specify for the access
parameter.
- access
- is the method you want to use to access the subfile. Use one of the
following values:
- DFDEL_ALG
- specifies that you are providing a pointer to an algorithm argument in the
acc parameter. The acc parameter is of type
dft_alg.
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.
- DFDEL_FADDR
- specifies that you are providing a file address in the acc
parameter. A file address is in integer format. The acc
parameter is of type dft_fad.
- DFDEL_ORD
- specifies that you are providing an ordinal number in the acc
parameter. Ordinal numbers in a file start at zero and are in integer
format. The acc parameter is of type
dft_ord.
If the file is partitioned or interleaved, specify the relative ordinal
number within the partition or interleave. If the file is not
partitioned or interleaved, specify the file address compute program (FACE)
ordinal number.
- 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.
- list_type
- specifies which files to delete. Use one of the following
values:
- DFDEL_INCLUDE
- deletes only the files listed in the structure pointed to by the
lst parameter. This is the default value.
- DFDEL_EXCLUDE
- deletes all files except those listed in the structure pointed to by the
lst parameter.
- lst
- is a pointer to a list of up to 10 subfiles to be included or excluded in
the delete action when the DFDEL_INCLUDE or DFDEL_EXCLUDE value of the
list_type parameter is specified.
The lst parameter is provided so that you can delete, or not
delete, subfiles that are referenced from the LREC that you are
deleting.
To delete LRECs in all the referenced subfiles, specify zero as the number
of file identifiers and provide one file identifier consisting of a string of
2 space characters. For example:
struct id_list ids = {0," "};
- nbr
- is an LREC number (type dft_nbr) or a pointer to a list (type
dft_rcl) of LRECs to be deleted. The following is deleted
based on the value of the nbr_type parameter:
- A single LREC specified by nbr if the nbr_type parameter
is set to DFDEL_LRECNBR.
- All the LRECs in a list pointed to by nbr if the
nbr_type parameter is set to DFDEL_LIST.
Specify the LRECs in this list as character array. For
example:
char nbrs[10] = "2/3-6/LAST";
The list contains one or more LREC sequence numbers separated by a slash
(/). You can also specify a range of sequence numbers by separating
the beginning and end of the range by a hyphen (-). You can use LAST to
mean the last LREC of the subfile and ALL to mean all the remaining
LRECs. You can also end the list with a nonnumeric character.
Notes:
- The ranges must be in ascending order; if one is found out of order,
that range and all subsequent ranges are ignored.
For example, if there are 41 LRECs in a subfile, the following lists all
have the same effect:
20/31/32/33/37/38/39/40/41
20/31/32/33/37-41
20/31-33/37-LAST
20/31-33/37/ALL
- You cannot specify the number zero in the list of LREC numbers,
even if you specify the ADJUST parameter with a value that would adjust the
number zero to a valid LREC number.
Notes:
- If you use the #TPFDB0D algorithm, you must specify a specific LREC number
for the value of nbr.
- LRECs are numbered in increasing order from the start of the subfile (the
first LREC in the prime block has sequence number 1).
- If you specify this parameter with active keys, only those LRECs that
match the key conditions are included in the sequence numbering; LRECs
that do not match are ignored.
- In functions that do not include the nbr_type parameter, the
value of nbr is a specific LREC number.
- nbr_type
- specifies the type of value that you are providing in the nbr
parameter. Use one of the following values:
- DFDEL_LIST
- specifies that you are providing a pointer to a list of LREC numbers (type
dft_rcl).
- DFDEL_LRECNBR
- specifies that you are providing the sequence number of a single LREC
(type dft_nbr).
- options
- are the processing options for this function. Use the following
values:
- DFDEL_ALL
- deletes every LREC in the open subfile that you have specified. If
you currently have keys active, the function deletes only the LRECs that match
the keys.
If you delete LRECs from a fixed file using the DFDEL_ALL value, the
function writes the empty prime block to DASD after deleting the LRECs (the
block header and optional trailer are not deleted). Any blocks
previously chained to the prime block are released. It releases any
blocks previously chained to the prime block.
If you delete all the LRECs from a pool subfile, the function releases both
prime and overflow blocks. However, if you delete all the LRECs from a
pool subfile and add an LREC before you close the subfile, the prime block is
not released.
For B+Tree files, if no keys are specified, DFDEL_ALL releases
the index blocks as well as the data blocks.
If the subfile was opened in detac mode, you cannot recover the subfile
using the dfcls function with DFCLS_ABORT.
If you combine this value with a lst parameter, the TPFDF product
deletes only the LRECs in the lst parameter.
If you specify keys in addition to DFDEL_ALL, this function deletes all the
LRECs in the open subfile that match these keys. If you also specify
the DFDEL_FULLFILE value, the dfdel function deletes all the LRECs
that match the keys in an entire file. In this case, the blocks are not
released, whether they are fixed or pool, because some LRECs can remain in a
file after deletion.
You can use the DFDEL_ALG value on the access parameter with the
DFDEL_ALL value to delete LRECs from an indexed detail file. The DBDEL
macro deletes the index entry for the subfile and releases the indexed subfile
if it is in pool.
- DFDEL_ALL_DOWNWARD
- deletes all LRECs from (and including) the current LREC to the last LREC
in the subfile. If you currently have keys active, the function deletes
only the LRECs that match the keys.
- DFDEL_ALL_UPWARD
- deletes all LRECs from (but not including) the current LREC to the first
LREC in the subfile. If you currently have keys active, the function
deletes only the LRECs that match the keys.
- DFDEL_BEGIN
- specifies that you want to start at the beginning of the file when
searching for LRECs to delete.
- DFDEL_FULLFILE
- deletes an LREC from every subfile of the file.
If you combine this value with the DFDEL_ALL value, the function deletes
every LREC in every subfile of the file. You can delete LRECs in
certain subfiles only by specifying the beg and end
parameters with the dfadr function.
- DFDEL_INITIALIZE
- empties the entire subfile apart from the standard TPFDF header in the
prime block. It releases any blocks previously chained to the prime
block.
- DFDEL_LAST
- deletes the last LREC of the subfile. (If you have set keys, the
function only deletes LRECs with matching keys.)
- DFDEL_NEXT
- deletes the next LREC in sequence from a file. (If you have set
keys, the function only deletes LRECs with matching keys.)
- DFDEL_NODUMP
- specifies that you do not want the TPFDF product to issue any of the
following system errors while processing this function:
- DB0100
- DB0102
- DB0117
- DB0123
- DB0138
- DB0140.
See Messages (System Error, Online, Offline) and
Master Glossary for more information about these system errors.
- Note:
- Using the DFDEL_NODUMP value is not recommended because it can prevent system
errors from being issued that indicate a critical problem.
- DFDEL_NOKEY
- deactivates any currently active keys.
Notes:
- If the file is not open when you specify the DFDEL_NOKEY value, the
dfdel function opens the file and deletes the first
LREC.
- If the file is open when you specify the DFDEL_NOKEY value, the
dfdel function deletes the current LREC.
- 0
- specifies that you do not want to use any processing options.
- qty
- is the number of subLRECs you want to delete.
- sub
- is the sequence number of the first subLREC in the extended LREC that you
want to delete.
Entry Requirements
Before using the dfdel_sub function, you must use a
dfred function to locate the extended LREC from which you want to
delete the subLREC.
Normal Return
- One of the following:
- Pointer to the next LREC in the subfile (after the last deleted LREC)
- Pointer to the current extended LREC from which the subLREC or subLRECs
were deleted.
- After you use the DFDEL_ALL_DOWNWARD or DFDEL_ALL_UPWARD value, the
SW00REC is set to zero and the SW00RTN is set to X'40'.
Error Return
- See Identifying Return Indicators and Errors for information about how to check the error
indicators.
- A pointer to protected main storage for all functions except the
dfdel_sub function.
- For the dfdel_sub function, there is no error return when
the subLRECs that you specify to be deleted do not exist. In all cases,
the return value is as if the function was processed successfully.
Programming Considerations
Examples
- The following example deletes all LRECs in a subfile.
dft_fil *file_ptr;
·
·
·
(void) dfdel(file_ptr, DFDEL_ALL);
- The following example deletes five subLRECs, starting at the first
(subLREC number 0):
dft_fil *file_ptr;
·
·
·
dfdel_sub(file_ptr, 0, 0, 5);
- You can delete a number of subLRECs without starting at the first.
To delete n subLRECs from the mth subLREC onward,
specify:
dft_fil *file_ptr;
·
·
·
dfdel_sub(file_ptr, 0, m-1, n);
(The first subLREC in an extended LREC is numbered zero so the mth
subLREC is numbered m-1.)
- To delete all the subLRECs from the mth to the last in the LREC,
specify:
dft_fil *file_ptr;
·
·
·
dfdel_sub(file_ptr, 0, m-1, 99);
(The previous example assumes there is a maximum of 99 subLRECs after the
mth subLREC.)
- Suppose an extended LREC contains six subLRECs. You could delete
the two middle subLRECs (numbers 2 and 3) by specifying:
dft_fil *file_ptr;
·
·
·
dfdel_sub(file_ptr, 0, 2, 2);
Related Functions