DBMOD: Perform or indicate logical record modifications

Use this general macro to do the following:
  • Indicate that the current logical record (LREC) has been modified
  • Modify all LRECs in a file or subfile that match previously established keys.
Note: The DBMOD macro cannot be used for large logical records (LLRs). Consider using the DBREP macro instead.

Last updated

  • Changed in 2020 (information only; no code change).
  • Changed for PUT12.
  • Changed for PUT11.
  • Changed for PUT10.
  • Changed for PUT07.
  • Changed for PUT06.
  • Changed for PUT05.
  • Changed for PUT04.
  • Changed for PUT03.
  • Changed for PUT02.
  • Changed for PUT00.

Format

Read syntax diagramSkip visual syntax diagramDBMOD REF= dsectvvREF= refname,FILE= dsectFILE= dsect,R3= address,AMODE= amodedef,AMODE=3164,ERROR= spmlbl,ERRORA= asmlbl,ALL,MODLIST= modreg,ALG= algarg,FADDR= faddr,FADDR8= faddr8,ORD= ordnum,BEGIN,FULLFILE,NOKEY,NODUMP,NOPGM,REG= register,REGD= register,SUFFIX= char
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 z/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
The label of an 8-byte field that contains the reference name.
A⁄refname
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 z/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 (R3) will be loaded with this address. If R3 already contains the address of the SW00SR slot before this macro is called, you do not need to specify the R3 parameter.
Note: Do not use this and the FILE parameter; they are provided only for migration purposes. Use the REF parameter to specify the file that you want to access.
AMODE
Specifies the addressing mode that is being used when the macro is called. Specify one of the following values:
amodedef
The value that is specified by the AMODE parameter on the BEGIN macro. If the AMODE parameter is not specified on the BEGIN macro, the default value is 31.
31
Indicates that 31-bit addressing mode is in use.
64
Indicates that 64-bit addressing mode is in use.
ERROR=spmlbl
Branches to the specified location if a serious error is detected when processing the macro, where spmlbl is a z/TPFDF structured program macro (SPM) label defined with the #LOCA macro. For more information about serious errors, see Identifying return indicators and errors. For more information about the #LOCA macro, see z/TPF and z/TPFDF Structured Programming Macros.
ERRORA=asmlbl
Branches to the specified location if a serious error is detected when processing the macro, where asmlbl is an assembler label. For more information about serious errors, see Identifying return indicators and errors.
ALL
modifies every LREC in the open subfile specified by the REF parameter, beginning with the current LREC. If selection keys are currently active, the DBMOD macro modifies only the LRECs that match these keys.
MODLIST=modreg
specifies the base register of the modification key list, where modreg is a register. See Setting up and using a key list for more information about defining a modification key list.
ALG=algarg
Identifies the subfile that you want to access, where algarg specifies an algorithm argument.

The z/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 z/TPFDF product uses the algorithm argument to locate the subfile. For more information about how the z/TPFDF product uses the algorithm argument to locate the subfile, see z/TPFDF Database Administration.

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
    The label of a field that contains the algorithm argument.
    A⁄algarg
    The label of a 4-byte field that contains the storage address of the algorithm argument.
Note: The area of storage that contains the algorithm argument must not be modified and must be accessible to the z/TPFDF product until the subfile is closed and the SW00SR is released.
FADDR=faddr
Identifies the subfile that you want to access, where faddr is one of the following:
faddr
The label of a 4-byte field that contains the file address of the prime block of the subfile.
A⁄faddr
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
The label of an 8-byte field that contains the file address of the prime block of the subfile.
A⁄faddr8
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
The label of a 4-byte field that contains the ordinal number of the subfile.
A⁄ordnum
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.

BEGIN
searches from the beginning of the subfile for LRECs to modify.
FULLFILE
modifies LRECs in all subfiles of the file, not just the current subfile.
NOKEY
Deactivates any currently active keys.
NODUMP
Specifies that you do not want the z/TPFDF product to issue system errors with return while the z/TPFDF product is processing this macro.
Note: Use the NODUMP parameter with caution because it can prevent the z/TPFDF system errors that indicate a critical problem from being issued.
NOPGM
Specifies not to change the program stamp in a block when filing it.
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.

Entry requirements

None.

Return conditions

  • If you are using the DBMOD macro to indicate that you have modified a record in storage, the address of the current LREC is loaded in the SW00REC field of the SW00SR slot.
  • If a global modification is being done, the SW00REC field of the SW00SR slot contains 0 and SW00RTN contains a record not found (#BIT1) or end-of-file (#BIT5) indication. This is a normal return condition.

Programming considerations

  • For information about macro register conventions, see Assembler program register conventions.
  • The contents of R3, which contains the storage address of the SW00SR slot, are used by z/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.
  • If register R8 is not used as a base register, its contents are unknown upon return from this macro. If R8 is used as a base register, its contents are unchanged.
  • All data, address reference fields, and storage areas that are passed to the z/TPFDF product assembler macros must reside below 2 GB in storage unless otherwise noted.
  • If a literal value is specified as a parameter, the program must have a base register.
  • 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.
  • If you locate an LREC or header in a subfile using the DBRED macro and modify the LREC data using assembler instructions, you must ensure that the changes are recorded on DASD. Use the DBMOD macro without the ALL parameter to do this.

    The DBMOD macro sets an indicator in the block to say that it has been changed. The z/TPFDF product writes this block to DASD when you close or checkpoint the subfile. You must call the DBMOD macro while the LREC you modified is still current. If you allow the program to read other LRECs in the subfile before you call the DBMOD macro, some modifications to LRECs can be lost.

    Attention: Do not use the DBMOD macro if you have changed:
    • The size of the existing LREC
    • Any key fields
    • Any fields in the LREC that are also used as index key fields.
    Instead, delete the old LREC with a DBDEL macro and add a new LREC with a DBADD macro.
  • Use the ALL parameter to perform global modifications. Global modification allows you to update multiple LRECs with a single DBMOD call. You must provide the base register of a modification key list with the MODLIST parameter. The modification key list contains the rules for updating the LRECs. See Setting up and using a key list for more information about defining a modification key list.
  • If you use global modification when KEYCHECK=YES is defined on the DBDEF macro, and any of the fields being modified overlap any default key fields for that primary key in the file, the z/TPFDF product issues a system error and processing ends. All records that were changed before processing ended remain changed.
  • The DBMOD macro does not have a KEYLIST parameter. If necessary, activate the selection key list using the DBKEY macro before calling the DBMOD macro with the ALL parameter to perform global modifications of LRECs.
  • If you call the DBMOD macro and the current LREC is an LLR, a system error is issued and the program exits.
  • For programming considerations when you use this macro with data event processing, see z/TPFDF API programming considerations for data event processing.

Examples

The following is an example of how to do a global modification of LRECs from an application written in assembler. In this example, a selection key list is first established using 3 keys as the selection criteria. Then a modification key list is defined. The modification key list indicates that for each LREC that meets the selection criteria, field zzzzFL1 will have the halfword value at EBX020 added to it and the byte at zzzzFL2 will be set to X'00'. Processing will begin with the first LREC in the subfile and end with the last LREC in the subfile. 
SW01SR REG=R5
LA     R5,EBW000
*
MVC    SW01NKY,=H'3'
DBSETK BASE=R5,KEYNUM=1,DIS=I/zzzzPKY-zzzzREC,LEN=L'zzzzPKY,   *
      CON=#DF_EQ,MSK=I/X'80',ID1=#DF_UP+#DF_CONST
DBSETK BASE=R5,KEYNUM=2,DIS=I/zzzzKY1-zzzzREC,LEN=L'zzzzKY1,   *
      CON=#DF_EQ,SEA=EBX000,ID1=#DF_UP
DBSETK BASE=R5,KEYNUM=3,DIS=I/zzzzKY2-zzzzREC,LEN=L'zzzzKY2,   *
      CON=#DF_NE,SEA=EBX010,ID1=#DF_UP
DBKEY REF=zzzzzz,KEYLIST=EBW000,NOPGM
*
MVC    SW01NKY,=H'2'
DBSETK BASE=R5,KEYNUM=1,DIS=I/zzzzFL1-zzzzREC,LEN=L'zzzzFL1,   *
      SEA=EBX020,ID2=#DF_AH
DBSETK BASE=R5,KEYNUM=2,DIS=I/zzzzFL2-zzzzREC,LEN=L'zzzzFL2,   *
      MSK=I/X'00',ID2=#DF_MVI
*
DBMOD REF=zzzzzz,ALL,BEGIN,MODLIST=R5,REG=R6
The following example modifies all LRECs that match the selection criteria in the subfile that is specified by the 8-byte prime file address. 
FA4X4C ACTION=4TO8,FA4=(R5),FA8=MYFADDR
LA     R5,EBW000
MVC    SW01NKY,2
DBSETK BASE=R5,KEYNUM=1,DIS=4,LEN=2,SEA=EBX020,ID2=#DF_AH
DBSETK BASE=R5,KEYNUM=2,DIS=7,LEN=1,MSK=I/X'08',ID2=#DF_MVI

DBMOD  ALL,REF=ILLRDF,ERROR=ERRLOC,FADDR8=MYFADDR,                     *
       KEY1=(PKY=#ILLRK80),BEGIN,MODLIST=R5,REG=R6
#IF    CLI,SW00RTN,EQ,#TPFDBOK           If no error...
*                                        LRECs are sucessfully modified