bdfp1m0z | Programming Concepts and Reference |
Use this group of functions to:
- Add a fixed- or variable-length logical record (LREC) to a subfile
- Add an empty LREC to a subfile
- Add a subLREC to the current extended LREC
- Add an extended LREC to a subfile
- Add an extended LREC and a subLREC to a subfile.
Format
dft_rec *dfadd(dft_fil *file, dft_opt rec_type, dft_opt options,
dft_rec *rec);
dft_rec *dfadd_acc(dft_fil *file, dft_opt rec_type, dft_opt access,
dft_opt options, dft_rec *rec, dft_xxx acc);
dft_rec *dfadd_nbr(dft_fil *file, dft_opt rec_type, dft_opt options,
dft_rec *rec, dft_nbr nbr);
dft_rec *dfadd_pky(dft_fil *file, dft_opt rec_type, dft_opt options,
dft_rec *rec, dft_pky pky);
dft_rec *dfadd_acc_nbr(dft_fil *file, dft_opt rec_type, dft_opt access,
dft_opt options, dft_rec *rec, dft_xxx acc, dft_nbr nbr);
dft_rec *dfadd_acc_pky(dft_fil *file, dft_opt rec_type, dft_opt access,
dft_opt options, dft_rec *rec, dft_xxx acc, dft_pky pky);
dft_rec *dfadd_nbr_pky(dft_fil *file, dft_opt rec_type, dft_opt options,
dft_rec *rec, dft_nbr nbr, dft_pky pky);
dft_rec *dfadd_acc_nbr_pky(dft_fil *file, dft_opt rec_type,
dft_opt access, dft_opt options, dft_rec *rec, dft_xxx acc,
dft_nbr nbr, dft_pky pky);
dft_rec *dfadd_sub(dft_fil *file, dft_opt options,
dft_rec *sub);
dft_rec *dfadd_usr_pky(dft_fil *file, dft_opt options,
dft_rec usr, dft_pky pky);
dft_rec *dfadd_usr_acc_pky(dft_fil *file, dft_opt access,
dft_opt options, dft_rec usr, dft_xxx acc,
dft_pky pky);
dft_rec *dfadd_usr_nbr_pky(dft_fil *file, dft_opt options,
dft_rec usr, dft_nbr nbr, dft_pky pky);
dft_rec *dfadd_usr_acc_nbr_pky(dft_fil *file, dft_opt access,
dft_opt options, dft_rec usr, dft_xxx acc,
dft_nbr nbr, dft_pky pky);
dft_rec *dfadd_usr_sub_pky(dft_fil *file, dft_opt options,
dft_rec *usr, dft_rec *sub, dft_pky pky);
dft_rec *dfadd_usr_acc_sub_pky(dft_fil *file, dft_opt access,
dft_opt options, dft_rec *usr, dft_xxx acc,
dft_rec *sub, dft_pky pky);
dft_rec *dfadd_usr_sub_nbr_pky(dft_fil *file, dft_opt options,
dft_rec *usr, dft_rec *sub, dft_nbr nbr,
dft_pky pky);
dft_rec *dfadd_usr_acc_sub_nbr_pky(dft_fil *file, dft_opt access,
dft_opt options, dft_rec *usr, dft_xxx acc,
dft_rec *sub, dft_nbr nbr, dft_pky pky);
- 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:
- DFADD_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.
- DFADD_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.
- DFADD_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.
- nbr
- is a variable containing the LREC sequence number in the subfile.
(You can add an LREC or an extended LREC by providing a specific sequence
number.)
Notes:
- Do not use this parameter with files for which default keys are
defined.
- If you use the #TPFDB0D algorithm, you must specify this parameter.
- 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.
- When you specify this parameter, the LREC is added immediately
after the specified LREC.
- If you specify this parameter for an LREC number that does not exist, the
LREC is not added.
- options
- are the processing options for this function. Use the following
values:
- DFADD_AFTER
- adds the new LREC immediately after the current LREC.
- DFADD_BEFORE
- adds the new LREC immediately before the current LREC.
- DFADD_FAST
- used for migration purposes only; use the DFADD_INLINE or DFADD_NOKEY
value instead. If you specify this parameter, the DFADD_NOKEY parameter
is implemented; that is, any currently active keys are
deactivated.
- DFADD_INDEX
- adds an LREC to a detail subfile or intermediate index subfile where the
index structure does not yet exist. If you specify this value, the
algorithm defined for the new subfile must be #TPFDBFF.
When you specify this parameter, the subfile is created and indexed by
adding an index LREC in the index file referencing the subfile.
- DFADD_INDEX_HOLD
- potentially holds any index files that reference the subfiles you are
accessing and prevents two or more application programs from modifying the
index files at the same time. Holding occurs if bits 4 and 5 in the
&SW00OP2 global set symbol in the DSECT macro, or the OP2= parameter in
the DBDEF macro, have been set appropriately. Subsequent TPFDF calls by
other ECBs to modify the index file will not occur until the index file is no
longer held. If more than one application can update the same index
file, you must specify this value to ensure the updates are
synchronized.
See TPFDF Database Administration for information
about how bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT
marco, or the OP2= parameter in the DBDEF macro, affect hold
processing.
- DFADD_INLINE
- provides a faster method for adding LRECs to a subfile. You cannot
use this value with key parameters or with extended LRECs. Any keys
that are active from previous TPFDF functions are deactivated.
- DFADD_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 DFADD_NODUMP value is not recommended because it can prevent system
errors from being issued that indicate a critical problem.
- DFADD_NOKEY
- deactivates any currently active keys.
- DFADD_UNIQUE
- specifies that the TPFDF product should not add the LREC to the subfile if
an LREC exists with the same key fields. The key fields are those
specified by the currently active keys.
Notes:
- If UNIQUE=YES was specified in the DBDEF macro for a file, all
dfadd function calls for that file default to DFADD_UNIQUE.
- If you specify this option for a file that is not organized (that is,
defined as NOORG), you must do one of the following:
- Define default keys for the file being updated
- Ensure there are active keys from a previous dfkey
function.
If you do not have default keys defined or have active keys when adding a
unique LREC to a file that is not organized, the TPFDF product issues a system
error. Symbol &DB013E in the DBLCL macro controls whether the TPFDF
product returns control to the application program or exits the entry control
block (ECB) after issuing the error. If you set &DB013E to 0 (which
is the default setting) the ECB exits. If you set &DB013E to 1,
control is returned to the application program. See TPFDF Installation and Customization for more information
about the DBLCL macro.
- DFADD_USEBTREE
- specifies that the B+Tree index is used when adding an LREC to
a subfile. You can use this value only on a B+Tree
file. Otherwise, this value is ignored by the TPFDF product.
- 0
- specifies that you do not want to use any processing options.
- pky
- is the primary key of the LREC that you are adding. You must
specify this parameter when using the DFADD_NULLREC value of the
rec_type parameter.
When adding an extended LREC, this primary key is placed in the
zzzzKEY field in the control area of the extended LREC.
- rec
- is a pointer to the new LREC that you are adding.
- rec_type
- is the type of LREC that you are adding. Use one of the
following:
- DFADD_NEWLREC
- adds a new fixed-length or variable-length LREC.
- DFADD_NULLREC
- adds an empty LREC that can be used as a work area.
Do not use this value for any file that is UP or DOWN organized because it
can destroy the organization of the file.
- sub
- is a pointer to the subLREC that you are adding.
- usr
- is a pointer to the userLREC that you are adding.
Entry Requirements
- Before using the DFADD_AFTER or DFADD_BEFORE value, you must first
establish a current LREC (for example, using a dfred
function).
You can then specify whether you want to add the new LREC before or after this
current LREC by using the DFADD_BEFORE or DFADD_AFTER value for the
options parameter on the dfadd function. You can
add any number of LRECs at this point in a subfile without reestablishing the
current LREC. The last LREC added becomes the current LREC.
- Before using the dfadd_sub function, you must first
establish the extended LREC to which you want to add the subLREC as the
current LREC.
Normal Return
One of the following:
- Pointer to the LREC that was added
- Pointer to the extended LREC that was added
- Pointer to the extended LREC to which a subLREC was added.
Error Return
- See Identifying Return Indicators and Errors for information about how to check the error
indicators.
- If there are default keys defined in the database definition (DBDEF) and
you use the dfadd function with an LREC ID that has not been
defined as a default key, a system error is issued.
Programming Considerations
- The type definitions (for example, dft_fil,
dft_ref, and dft_kyl) are defined in the
c$cdfapi.h header file.
- Some parameters can be of different types based on the value you
specify for that parameter or a related parameter. In the function
format, the type of these parameters is shown as
dft_xxx. See the description of the specific
parameter for information about what type definition to use for that
parameter.
- Do not use the following values for B+Tree files:
- DFADD_AFTER
- DFADD_BEFORE
- DFADD_FAST
- DFADD_NOKEY
- DFADD_NULLREC.
- Do not use the DFADD_FAST value with extended LRECs; that is, do not
use this value with the dfadd_sub function or any of the
dfadd_usr_ functions.
- Do not use the following values with the dfadd_sub
function:
- DFADD_AFTER
- DFADD_BEFORE
- DFADD_UNIQUE.
- If keys are active for an add current file when you call a function from
the dfadd group, the keys will not be used to determine the
location of the record being added to the subfile. However, the keys
will remain active for any subsequent functions. See TPFDF Database Administration for information about add
current files.
- Any active keys are ignored when you use the #TPFDB0D
algorithm.
- To add an LREC when no subfile is defined, the TPFDF product obtains a
prime block from pool and inserts the LREC into it. It puts the address
of this prime block in the SW00FAD field of the SW00SR slot and the record
code check into the SW00WCC field.
- If adding an LREC to a subfile block causes the block to overflow, the
TPFDF product gets a new block and chains it to the old one.
- Note:
- How LRECs are added to a subfile depends on the following factors:
- For add current files, the LREC is added to the end of the
subfile. See TPFDF Database Administration for
more information about add current files.
- For pushdown chaining files, the LREC is added as the last LREC
in the prime block of the subfile. See TPFDF
Database Administration for more information about pushdown chaining
files.
- For P-type files, a new block is added after the current block or at the
end of the subfile.
- If you specify the DFADD_AFTER or DFADD_BEFORE value, the LREC is added
after or before the current LREC.
- If you have active keys (which can include default keys coded on the DBDEF
macro for the file), the LREC is added to the subfile at the specified
location.
- In all other cases, the LREC is added at the end of the subfile.
- You can use the DFADD_NEWLREC value for the rec_type parameter
with a P-type file to specify the data contents of a new block.
- You can use the DFADD_NULLREC value for the rec_type parameter
with a P-type file to add an empty block, chained to the current block.
You can then add data to this block using the dfmod
function.
- Use the dfadd function with the DFADD_NULLREC value for the
rec_type parameter to create a work area for a T-type LREC in the
underlying W-type file. Use the dfdel function to delete the
T-type LREC from the underlying W-type file before exiting the application
program.
Examples
- The following example adds LREC GR95SR to the current subfile. The
new LREC is in lrec.
dft_fil *file_ptr;
struct gr95sr lrec;
·
·
·
(void) dfadd(file_ptr, DFADD_NEWLREC, 0, &lrec);
- The following example adds LREC GR95SR to a subfile specified with an
algorithm. The new LREC is in lrec. The algorithm
argument is in alg_string.
dft_fil *file_ptr;
char alg_string[10] = "JONES";
struct gr95sr lrec;
·
·
·
(void) dfadd_acc(file_ptr, DFADD_NEWLREC, DFADD_ALG, 0, &lrec, alg_string);
- The following example adds a subLREC to the current extended LREC.
dft_fil *file_ptr;
·
·
·
dfadd_sub(file_ptr, 0, &sublrec);
- The following example adds an extended LREC to a subfile specified with an
algorithm. The userLREC is in userlrec and the algorithm
argument is in alg_string. The primary key of the extended
LREC is hexadecimal 80.
dft_fil *file_ptr;
char alg_string[10]="JONES";
dft_pky pky;
pky=0x80;
·
·
·
dfadd_usr_acc_pky(file_ptr, DFADD_ALG, 0, &userlrec, alg_string, pky);
- The following example shows how you can add new LRECs to a detail file by
specifying an index key as the algorithm argument. To add passenger
MCKAY to the passenger file, you can code:
dbptr=dfopn("GR45DF ","S0",DFOPN_HOLD);
alg_string="MCKAY";
dfadd_acc(dbptr,DFADD_NEWLREC, DFADD_ALG, DFADD_INDEX, newlrec, alg_string);
Related Functions