DBADD-add a logical record to a subfile

Edit online

Use this macro to do the following:

  • 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.
  • Add an LREC to a subfile in buffered access mode (BAM). You must use this form of the DBADD macro if you are adding a large logical record (LLR) to a subfile.

Format

Read syntax diagramSkip visual syntax diagramDBADDREF= dsectvvREF= refname,FILE= dsectFILE= dsect,R3= address,NEWLREC= newlrecNULLREC= nullrecSUBLREC= sublrecUSRLREC= usrlrecSUBLREC= sublrec,USRLREC= usrlrecRECADDR= recaddr,RECLEN= reclen,AFTER,BEFORE,ALG= algarg,FADDR= faddr,FADDR8= faddr8,ORD= ordnum,ERROR= spmlbl,ERRORA= asmlbl,FAST,INDEX,INDEX=NOHOLD,INDEX=HOLD,INTERLV= intrlvnum,PARTITN= partitnum,,KEY n=(Key Subparameters),KEYLIST= keyloc,NOKEY,LRECNBR= lrecnum,NODUMP,NOPGM,PATH= pathnum,PKY=x'C0',PKY= primarykey,REG= register,REGD= register,SUFFIX= char,UNIQUE,USEBTREE,UP,DOWN,NOORG
Note: See Specifying File Organization with Keyn Parameters for information about the rules for using the KEYn parameters and file organization parameters together.

Key Subparameters

Read syntax diagramSkip visual syntax diagramPKY= primarykey,C= conditionRT=fldname,D= dynmask,C= condition,M= mask,C= condition,S= searcharg,L= length,C= conditionRT=label1D/ absvalliteralflddisp,D= dynmask,C= condition,M= mask,C= condition,S= searcharg,L= length,C= condition,UP,DOWN,NOORG
REF=dsectvv
specifies the file that you want to access, where dsectvv is the 6-character DSECT name and an optional 1- or 2-character suffix. If a suffix is omitted, the DSECT name will be padded with blanks (X'40') to build an 8-byte character string.

The reference name can be any 8-byte value that is unique for the current ECB. If you specify the same reference name more than once, a DB0170 system error may occur on any subsequent command if the TPFDF product needs to search for the SW00SR slot with this duplicate reference name.

REF=refname
specifies the name associated with the file that you want to access, where refname is a label that references the name in one of the following formats:
refname
is the label of an 8-byte field that contains the reference name.
A/refname
is the label of a 4-byte field that contains the storage address of an 8-byte field that contains the reference name.

The reference name can be any 8-byte value that is unique for the current ECB. If you specify the same reference name more than once, a DB0170 system error may occur on any subsequent command if the TPFDF product needs to search for the SW00SR slot with this duplicate reference name.

FILE=dsect
specifies the file or subfile that you want to access, where dsect is the 6-character DSECT name.
R3=address
specifies the location of the SW00SR slot for this subfile, where address is the label of a field that contains the address of the SW00SR slot. Register 3 will be loaded with this address.
Note: Do not use this parameter; it is provided only for migration purposes. Use the REF parameter to specify the file that you want to access.
NEWLREC=newlrec
adds a new fixed-length or variable-length LREC, where newlrec is one of the following:
  • A register that contains the address of the LREC to add
  • A label in one of the following formats:
    newlrec
    is the label of a field that contains the LREC.
    A/newlrec
    is the label of a 4-byte field that contains the storage location of the LREC.
NULLREC=nullrec
adds an empty LREC to a subfile, where nullrec is one of the following:
  • A register that contains the address of a 2-byte field that contains the length of the LREC
  • A label in one of the following formats:
    nullrec
    is the label of a 2-byte field that contains the length of the LREC.
    A/nullrec
    is the label of a 4-byte field that contains the storage location of the 2-byte length of the LREC.

If you specify this parameter, you must also specify the primary key (LREC ID) of the empty LREC with the PKY parameter.

Note:
  • Do not use the NULLREC parameter on files that are UP or DOWN organized because it can destroy the organization of the file.
  • NULLREC is most suitable for W-type files.
  • NULLREC is not allowed for B+Tree files.
  • If you modify any fields in an LREC that was added with the NULLREC parameter specified, you must issue a DFMOD macro to indicate that the LREC was modified.
SUBLREC=sublrec
adds a subLREC to the current extended LREC or to the extended LREC specified by the USRLREC parameter, where sublrec is one of the following:
  • A register that contains the address of the subLREC
  • A label in one of the following formats:
    sublrec
    is the label of a field that contains the subLREC.
    A/sublrec
    is the label of a 4-byte field that contains the storage location of the subLREC.

    If you specify this parameter for an LREC that contains existing subLRECs, the subLREC is added immediately before the existing subLRECs. See Using Extended Logical Records for more information about how subLRECs are added to an extended LREC.

USRLREC=usrlrec
adds an extended LREC to the subfile, where usrlrec is one of the following:
  • A register that contains the address of the userLREC
  • A label in one of the following formats:
    usrlrec
    is the label of a field that contains the userLREC.
    A/usrlrec
    is the label of a 4-byte field that contains the storage location of the userLREC.
RECADDR=recaddr
adds an LREC to an open subfile using buffered access mode (BAM), where recaddr is one of the following:
  • A register that contains the address of the buffer with the LREC
  • A label in one of the following formats:
    recaddr
    the label of the buffer containing the LREC.
    A/recaddr
    the label of a 4-byte field that contains the storage address of buffer containing the LREC.

If you are adding an LLR to the subfile, you must specify this parameter and the RECLEN parameter.

RECLEN=reclen
specifies the length of the LREC being added to the subfile using BAM, where reclen is one of the following:
  • A register that contains the length of the LREC
  • A label of a fullword field containing the length of the LREC.

If you are adding an LLR to the subfile, you must specify this parameter and the RECADDR parameter. If a fixed-length LREC is being added, the value specified by the RECLEN parameter is ignored.

AFTER
adds the new LREC immediately after the current LREC.
BEFORE
adds the new LREC immediately before the current LREC.
ALG=algarg
identifies the subfile that you want to access, where algarg specifies an algorithm argument.

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.

Specify algarg as one of the following:

  • A register that contains the address of the algorithm argument
  • A literal value that specifies the algorithm argument (for example, ALG==C'SMITH')
  • A label in one of the following formats:
    algarg
    is the label of a field that contains the algorithm argument.
    A/algarg
    is the label of a 4-byte field that contains the storage address of the algorithm argument.
Note: Do not modify the area of storage containing the algorithm argument until the subfile is closed.
FADDR=faddr
identifies the subfile that you want to access, where faddr is one of the following:
faddr
is the label of a 4-byte field that contains the file address of the prime block of the subfile.
A/faddr
is the label of a 4-byte field that contains the storage address of the file address of the prime block of the subfile.
FADDR8=faddr8
identifies the subfile that you want to access, where faddr8 is one of the following:
faddr8
is the label of an 8-byte field that contains the file address of the prime block of the subfile.
A/faddr8
is the label of a 4-byte field that contains the storage address of the 8-byte file address of the prime block of the subfile.
ORD=ordnum
identifies the subfile that you want to access, where ordnum is one of the following:
ordnum
is the label of a 4-byte field that contains the ordinal number of the subfile.
A/ordnum
is the label of a 4-byte field that contains the storage address of the ordinal number of the subfile.

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.

ERROR=spmlbl
branches to the specified location if a serious error is detected when processing the macro, where spmlbl is a TPFDF structured program macro (SPM) label defined with the #LOCA macro. See TPFDF and TPF Structured Programming Macros for more information about the #LOCA macro. See Identifying Return Indicators and Errors for more information about serious errors.
ERRORA=asmlbl
branches to the specified location if a serious error is detected when processing the macro, where asmlbl is an assembler label. See Identifying Return Indicators and Errors for more information about serious errors.
FAST
used for migration purposes only; use the NOKEY parameter instead. If you specify this parameter, the NOKEY parameter is implemented; that is, any currently active keys are deactivated.
INDEX
adds an LREC to a detail subfile or intermediate index subfile where the index structure does not yet exist. If you specify this parameter, 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.

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 parameter 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 macro, or the OP2= parameter in the DBDEF macro, affect hold processing.

INDEX=NOHOLD
does not hold the index files that reference the subfiles you are accessing.
INTERLV=intrlvnum
specifies the number of the interleave that you want to use, where interlvnum is one of the following:
  • A register that contains the address of the interleave number
  • An absolute value representing the interleave number
  • The label of a 2-byte field that contains the interleave number.

If you specify this parameter, the maximum interleave number must be defined in the DSECT or DBDEF macro. See TPFDF Database Administration for more information about interleaves.

PARTITN=partitnum
specifies the number of the partition that you want to use, where partitnum is one of the following:
  • A register that contains the partition number
  • An absolute value representing the partition number
  • The label of a 2-byte field that contains the partition number.

If you specify this parameter, the number of partitions and the end ordinal must be defined in the DSECT or DBDEF macro. See TPFDF Database Administration for more information about partitions.

Note: Do not use this parameter with the #TPFDB0F algorithm. This algorithm calculates the partition used from the algorithm argument. See TPFDF Database Administration for more information about algorithms.
KEYn
specifies the key parameters that you want to use with this macro, where n is a number from 1-6. You can specify as many as six KEYn parameters and they must be specified in sequential order beginning with 1. That is, you cannot code a KEY2 parameter without a KEY1 parameter, a KEY3 parameter without the KEY1 and KEY2 parameters, and so on.

If you use these parameters, you must also specify the file organization of the keys. See Specifying File Organization with Keyn Parameters for more information about how to do this. Use one or more of the following subparameters with the KEYn parameter:

PKY=primarykey
specifies a value that will be compared against the primary key of an LREC, where primarykey is a 1-byte immediate value; for example: ... KEY1=(PKY=#RR00K80) This has the same effect as: ... KEY1=(R=RR00KEY,S=#RR00K80)
R
specifies a field in the LREC to be compared with the search argument specified with the S subparameter or to be tested against the mask specified with the M or D subparameter.
T
specifies a field in the subLREC of an extended LREC to be compared with the search argument specified with the S subparameter or to be tested against the mask specified with the M or D subparameter.
fldname
is the name of a field defined in the DSECT for the LREC; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,S=EBW000)
label1
is a 2-byte field containing the displacement into the LREC; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R=EBX010,S=EBW000,L==H'4')
D/absval
specifies the displacement into the LREC of the field, where absval is an absolute value; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R=D/2,S=EBW000,L=L'GR00NAM,UP)

You can also specify the absolute value implicitly; for example:

... KEY1=(PKY=#GR00K80),KEY2=(R=D/GR00NAM-GR00REC,S=EBW000,L=L'GR00NAM,UP)
literal
is a halfword literal containing the displacement into the LREC; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R==H'2',S=EBW000,L==H'4')
flddisp
is the displacement off the field of the LREC; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD+2,S=EBW000,L==H'4') or ... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD+L'GR00FLD,S=EBW000,L==H'4')
C=condition
specifies the condition to be used when comparing fields in the logical record (specified with the R subparameter) with the search argument (specified with the S or PKY subparameter) or with the bit mask (specified with the M or D subparameter).

If you specify the S or PKY subparameter, use one of the following values:

Value
Condition
EQ
Equal (this is the default)
E
Equal
NE
Not equal
GE
Greater than or equal
LE
Less than or equal
GT
Greater than
LT
Less than
H
High
L
Low
NH
Not high
NL
Not low.

If you specify the M or D subparameter, use one of the following values:

Value
Condition
Z
Zeros
O
Ones
M
Mixed
NZ
Not zeros
NO
Not ones
NM
Not mixed.
D=dynmask
specifies the label of a 1-byte field containing a mask to be tested against the LREC field specified with the R or T subparameter; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,D=EBW000,C=Z)
M=mask
specifies a mask to be tested against the LREC field specified with the R or T subparameter; for example: ... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,M=X'80',C=Z)
S=searcharg
specifies the search argument to be compared with the LREC field specified with the R or T subparameter, where searcharg is one of the following:
  • A register that contains the address of the search argument
  • A literal that represents the search argument
  • A label in one of the following formats:
    searcharg
    is the label of the search argument.
    A/searcharg
    is the label of a 4-byte field that contains the storage address of the search argument.
    P/searcharg
    is the label of a field that contains the search argument in packed decimal format.

    If you specify P/searcharg or a literal in the form of =P"...", the LREC field and search argument are compared as decimal numbers in packed format. Otherwise, the LREC field and search argument are compared as character data.

Note: When you use this parameter, you cannot specify the core block reference word (CBRW) or file address reference word (FARW) fields in an ECB.
L=length
specifies the length of the search argument, where length is one of the following:
  • The address of a 2-byte field containing the length of the search argument
  • A 2-byte literal
  • An absolute value in the form of L'fldname (for example, L=L'GR92FLD).

The default value is the length of the field specified with the R subparameter.

UP
specifies that the key field is in ascending order in the subfile.
DOWN
specifies that the key field is in descending order in the subfile.
NOORG
specifies that the key field is in no particular order in the subfile.
KEYLIST=keyloc
specifies a key list that you want to use with this macro, where keyloc is one of the following:
  • A register that contains the address of the key list
  • A label in one of the following formats:
    keyloc
    is a label indicating the address of the key list.
    A/keyloc
    is the label of a 4-byte field that contains the storage address of the key list.

See Setting Up and Using a Key List for information about how to set up a key list.

NOKEY
deactivates any currently active keys.
LRECNBR=lrecnum
specifies the sequence number of an LREC that you want to add, where lrecnum is one of the following:
  • A register that contains the address of the LREC number
  • An immediate value that represents the LREC number
  • A label in one of the following formats:
    lrecnum
    is the label of a 4-byte field that contains the LREC number.
    A/lrecnum
    is the label of a 4-byte field that contains the storage address containing the LREC number.
Note:
  • Do not use this parameter with files for which default keys are defined.
  • 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.
NODUMP
specifies that you do not want the TPFDF product to issue any of the following system errors while processing this macro:
  • DB0100
  • DB0102
  • DB0117
  • DB0123
  • DB0138
  • DB0140.

See TPFDF Messages (System Error, Online, Offline) for more information about these system errors.

Note: Using the NODUMP parameter is not recommended because it can prevent system errors from being issued that indicate a critical problem.
NOPGM
specifies not to change the program stamp in a block when filing it.
PATH=pathnum
specifies the path number for a detail subfile using index support, where pathnum is the path number or the label of a 2-byte field that contains the path number. The number of index paths used is defined by your database administrator. If there is only one index path, do not specify this parameter.

See TPFDF Database Administration for more information about path numbers.

PKY=primarykey
specifies the primary key (LREC ID) of the LREC that you are adding, where primarykey is one of the following:
  • An equate that represents the primary key (for example, PKY=#GR00K80)
  • An explicit term that represents the primary key (for example X'80')
  • A label in one of the following formats:
    primarykey
    is the label of a field that contains the primary key (for example, PKY=EBW000)
    A/primarykey
    is the label of a 4-byte field that contains the storage address of the primary key.

You must specify this parameter if the default value is not acceptable and you are:

  • Adding an empty LREC using the NULLREC parameter
  • Adding an extended LREC using the USRLREC parameter. This primary key is placed in the zzzzKEY field in the control area of the extended LREC.
REG=register
specifies a register in which to return the address of the current LREC, which is also contained in SW00SR field SW00REC.
REGD=register
specifies a register in which to return the base address of the userLREC part of an extended LREC.
SUFFIX=char
allows you to use the same DSECT to map two different areas of storage, where char is the suffix character.
UNIQUE
specifies that the TPFDF product should not add the LREC to the subfile if an LREC exists with the same key fields.
Note:
  • If UNIQUE=YES was specified in the DBDEF macro for a file, all DBADD statements for that file default to 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
    • Specify an organization using the UP or DOWN parameter
    • Ensure the KEYn or KEYLIST parameter was specified with a previous macro; if not, specify the KEYn or KEYLIST parameter with this macro call.

    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.

USEBTREE
specifies that the B+Tree index is used when adding an LREC to a subfile. You can use this parameter only on a B+Tree file. Otherwise, this parameter is ignored by the TPFDF product.
UP
specifies that the LRECs are organized in the subfile in ascending order of key fields.
DOWN
specifies that LRECs in the subfile are organized in descending order of key fields.
NOORG
specifies that the LRECs are organized in the subfile in no particular order. (NOORG is the default if subfile organization has not been defined in the DBDEF).

Entry requirements

  • Before you use the AFTER or BEFORE parameter, you must first establish a current LREC (for example, using the DBRED macro). You can then specify whether you want to add the new LREC before or after this current LREC by using the BEFORE or AFTER parameter with the DBADD macro. You can add any number of LRECs at this point in a subfile without having to reestablish the current LREC. The last LREC added becomes the current LREC.
  • Before using the SUBLREC parameter without the USRLREC parameter, you must first establish the extended LREC to which you want to add the subLREC as the current LREC.

Normal return

The address of the new LREC is placed in the SW00REC field of the SW00SR slot. If you specify the REG parameter, the address of the new LREC is placed in the specified register and SW00REC. If the LREC is an LLR, SW00REC contains the address of the portion of the LLR in the first 4K block. You can check that an LLR was added with the LLRFOUND,YES SPM parameters.

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 DBADD macro with an LREC ID that has not been defined as a default key, a system error is issued.
  • If bufferec access mode (BAM) is used to add an LREC and RECADDR is 0 or the length specified in RECLEN is not valid, a system error is issued.

Programming Considerations

  • The optional 2-character version on the REF parameter allows you to access more than one subfile in the same file at the same time. For example, you can code REF=IR71DF01,ALG==C"A" to access subfile A and REF=IR71DF02,ALG==C"B" to access subfile B.
  • If you specify a label, the label must be more than 3 characters long.
  • The contents of register 14 (R14) and R15 cannot be predicted across a TPFDF macro call.
  • The contents of R3, which contains the storage address of the SW00SR slot, are used by TPFDF macro calls. Do not change the value of R3 between macro calls unless you save the value after each macro call and restore the value before each macro call.
  • You cannot specify six KEYn parameters (KEY1-KEY6) when both of the following conditions are true:
    • The S subparameter is used on all six keys
    • The length of all keys is greater than 1 (either with an explicit length using the L subparameter or an implied length from the field used in the R or T subparameter).

    If you need this type of key definition, you must use a key list.

  • Any active keys are ignored when you use the #TPFDB0D algorithm.
  • Do not use the following parameters for B+Tree files:
    • AFTER
    • BEFORE
    • FAST
    • KEYn
    • KEYLIST
    • LRECNBR
    • NULLREC.
  • Do not use the FAST parameter with extended LRECs. That is, do not specify this parameter with the SUBLREC or USRLREC parameters.
  • Do not use the following parameters with the SUBLREC parameter:
    • AFTER
    • BEFORE
    • UNIQUE.
  • If a file is UP or DOWN organized and does not have default keys defined in the DBDEF macro, include the KEYn or KEYLIST parameters to preserve the organization of the LRECs.
  • If a file has default keys defined in the DBDEF, do not specify the KEYn or KEYLIST parameters with the DBADD macro; the TPFDF product inserts the LREC in the correct place in the subfile. Also, any keys that are active from a previous TPFDF macro will no longer be active after the DBADD macro call.
  • When DBADD is coded for an add current file, the following considerations apply:
    • KEYn and KEYLIST parameters cannot be specified on the DBADD macro.
    • If keys are active, they 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 macros.

    See TPFDF Database Administration for more information about add current files.

  • To add an LREC when no subfile is defined and 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 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 AFTER or BEFORE parameter, 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 NEWLREC parameter with a P-type file to specify the data contents of the new block.
  • You can use the NULLREC 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 DBMOD macro.
  • Use the DBADD macro with the NULLREC parameter specified to create a work area for a T-type LREC (T-type DSECT) in the underlying W-type file. Use the DBDEL macro to delete the T-type LREC (T-type DSECT) from the underlying W-type file before exiting the application program.
  • If you use the #TPFDB0D algorithm, you must specify one of the following parameters:
    • AFTER
    • BEFORE
    • LRECNBR.
  • 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 AFTER or BEFORE parameter 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 RECLEN parameter. If a non-LLR is being added using BAM, both the halfword length in the header and the RECLEN value must be valid.
  • The following rules determine the value of the record code check (RCC) value used when the TPFDF product creates a new subfile:
    • If you do not specify the NOCHK parameter, the TPFDF product creates new subfiles with a random RCC value.
    • If you specify the NOCHK parameter without the CHKA parameter, the TPFDF product creates new subfiles without an RCC value.
    • If you specify both the NOCHK and CHKA parameters, the TPFDF product creates new subfiles with the RCC value specified with the CHKA parameter.
  • Do not use the following parameters with an add current file or a pushdown chaining file:
    • AFTER
    • BEFORE
    • LRECNBR.

Examples

  • The following example shows how to store the ECB work areas in two T-type DSECTs, RTEWSR and RTEXSR respectively. This frees the work areas for other uses.

    Each LREC contains 115 bytes made up of:

    • Size field (2 bytes)
    • LREC ID (1 byte)
    • File reference (8 bytes)
    • Data from work area (104 bytes).

    The LRECs are added last.

    The files are set up by coding:

    DBADD REF=RTEWSR,REG=R4,NULLREC==AL2(115)
MVC 11(104,R4),EBW000
DBADD REF=RTEXSR,REG=R4,NULLREC==AL2(115)
MVC 11(104,R4),EBX000
  • The following example shows how you can add an LREC to a subfile using an algorithm argument. In this example, EBW001 contains the algorithm argument and EBX000 points to the LREC that will be added. DBADD REF=GR45DF,ALG=EBW001,NEWLREC=EBX000
  • The following example adds an empty LREC that has the length of field GR23L80. The primary key is the value defined for #GR23K80. DBADD REF=GR23DF,NULLREC==AL2(L'GR23L80),PKY=#GR23K80
  • The following example adds a subLREC and a userLREC. DBADD REF=GR39DF,USRLREC=GR39REC,SUBLREC=A/EBW000,PKY=#GR39K80
  • The following example shows the use of the SUFFIX parameter. 
    GR25DF REG=R6,SUFFIX=X
DBOPN REF=GR25DF,REG=R6,SUFFIX=X
DBADD REF=GR25DF,SUFFIX=X,                *
      KEY1=(PKY=#GR25K80,UP),             *
      KEY2=(R=GR25ALCX,S=GR25ALC,DOWN)
  • The following example adds an LREC to a detail subfile. DBADD REF=GR23DF,INDEX,ALG=EBW044

    This has the same effect as the following sequence of macros:

    DBCRE REF=GR23DF
DBIDX REF=GR23DF,ALG=EBW0044
DBADD REF=GR23DF
  • The following example adds a NULL LREC to the subfile that is specified by the 8-byte prime file address. 
    FA4X4C ACTION=4TO8,FA4=(R5),FA8=MYFADDR
DBADD  REF=ILLRDF,ERROR=ERRLOC,FADDR8=MYFADDR,NULLREC
#IF    CLI,SW00RTN,#TPFDBOK,Z     IF NO ERROR ...               
*                                 LREC IS SUCCESSFULLY ADDED
  • The following example adds a normal LREC using BAM with register parameters. 
    L     R5,=F'3500'                       MALOC area size : 3.5K
LR    R6,R5                             Save buffer area length
MALOC SIZE=R5                           Get this area pointed to by R5
#IF   LTR,R5,R5,NZ                      If valid buffer returned
STH   R6,0(R5)                          Put LREC length in 1st halfword
MVI   2(R5),#LLRPKY                     .   Set up LLR Primary key
*       note : no need to set up the size header halfword
#PERF R15,BUILD-LLR-IN-AREA             .   Build the LLR into the buffer
DBADD REF=ILLRDF,ERROR=ERRLOC,RECADDR=R5,RECLEN=R6
#IF   CLI,SW00RTN,#TPFDBOK,Z            .   If no error ...
*       LLR is successfully added
#EIF                                    .   End If
FREEC BLOCK=R5                          .   release buffer
  • The following example adds an LLR using buffered access mode (BAM) with direct storage references. The address of the LLR is stored in the field named FIELDA and the length is stored in FIELDB. 
    L     R5,=F'16000'                      MALOC area size : 16K
ST    R5,FIELDB                         Store buffer area length
MALOC SIZE=R5                           Get this area pointed to by R5
#IF   LTR,R5,R5,NZ                      If valid buffer returned
ST    R5,FIELDA                         .   Save buffer area address
MVI   2(R5),#LLRPKY                     .   Set up LLR Primary key
*       note : no need to set up the size header halfword
#PERF R15,BUILD-LLR-IN-AREA             .   Build the LLR into the buffer
DBADD REF=ILLRDF,ERROR=ERRLOC,RECADDR=A/FIELDA,RECLEN=FIELDB
#IF   CLI,SW00RTN,#TPFDBOK,Z            .   If no error ...
*       LLR is successfully added
#EIF                                    .   End If
FREEC BLOCK=R5                          .   release buffer
    Note: If this was a normal LREC, the length of the LREC would have to be saved in the first halfword of the buffer.

Related Information