bdfp1m0zProgramming Concepts and Reference

dfadd-Add a Logical Record to a Subfile

Use this group of functions to:

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:

  1. Do not use this parameter with files for which default keys are defined.

  2. If you use the #TPFDB0D algorithm, you must specify this parameter.

  3. LRECs are numbered in increasing order from the start of the subfile (the first LREC in the prime block has sequence number 1).

  4. 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.

  5. When you specify this parameter, the LREC is added immediately after the specified LREC.

  6. 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:

  1. If UNIQUE=YES was specified in the DBDEF macro for a file, all dfadd function calls for that file default to DFADD_UNIQUE.

  2. 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

Normal Return

One of the following:

Error Return

Programming Considerations

Examples

Related Functions