dfadd-add a logical record to a subfile

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_xxxacc);

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_xxxacc, 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_xxxacc, 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_xxxacc,
        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_xxxacc,
        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_xxxacc,
        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_xxxacc,
        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_xxxacc,
        dft_rec *sub, dft_nbr nbr, dft_pky pky);

Options Parameter Values

Rec_Type Parameter Values

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 4-byte file address for the acc parameter. A file address is in integer format. The acc parameter is of type dft_fad.

DFADD_FADDR8

specifies that you are providing a pointer to an 8-byte file address for the acc parameter. The acc parameter is of type * dft_fad8.

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 file that you want to access and is returned by the dfifb or dfopn function. Use the acc parameter to specify a particular subfile to access. If you do not specify the acc parameter, the last subfile accessed with this SW00SR slot will be accessed.

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

Note:

• 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_BAM

adds the new LREC using buffered access mode (BAM). If you use BAM, before you call this function you must have defined the BAM parameters previously by using the dfsetbam function. The field buf_siz in the data structure dft_bam is not used and must be set to NULL.

DFADD_BEFORE

adds the new LREC immediately before the current LREC.

DFADD_FAST

used for migration purposes only; use the 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_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 TPFDF Messages (System Error, Online, Offline) 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.

Note:

• 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 LREC that you are adding. If you specify the DFADD_BAM option, rec must be set to NULL and the pointer to the LREC being added must be specified by using the dfsetbam function.

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.

Note: If you modify any fields in an LREC that was added with the DFADD_NULLREC record type, you must issue a dfmod function to indicate that the LREC was modified.

sub

is a pointer to the subLREC that you are adding.

usr

is a pointer to the userLREC that you are adding.

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

One of the following:

• A pointer to the LREC that was added (if the LREC being added is an LLR, the pointer points to the portion of the LLR that is in the first 4-K block)
• A pointer to the extended LREC that was added
• A pointer to the extended LREC to which a subLREC was added.

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

• 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 and DFADD_FADDR is coded, 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.
• To add an LREC when no subfile is defined and DFADD_FADDR8 is coded, the TPFDF product obtains a prime block from pool and inserts the LREC into it. The address of this prime block in the SW00FAD8 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.
• If a current LREC does not exist because a previous read operation with keys did not find an LREC matching the search criteria, and the subfile does not have default keys, specifying the DFADD_AFTER or DFADD_BEFORE value adds the new LREC to the target position of the unsuccessful read operation.
• If you are adding an LLR, the first 3 bytes of the new LREC must contain the standard TPFDF header information (halfword length and primary key byte) and must be included in the length. The halfword of length information is ignored for an LLR; the length is obtained from the parameter list defined by the dfsetbam function. If a non-LLR is being added using buffered access mode (BAM), both the halfword length in the header and the BAM parameter list value must be valid.
• Do not use the following values with an add current file or a pushdown chaining file:
  • DFADD_AFTER
  • DFADD_BEFORE
  • DFADD_LRECNBR.

• dfdel-Delete One or More Logical Records
• dfmod-Perform or Indicate Logical Record Modifications
• dfopn-Open a Subfile
• dfred-Read a logical record
• dfsetbam-Set buffered access mode (BAM) parameters.