bdfp1m2c | Programming Concepts and Reference |
Use this 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.
Format
- REF=dsectvv
- specifies the file or subfile that you want to access, where
dsectvv is the DSECT name and an optional 2-character version.
- REF=refname
- specifies the file or subfile that you want to access, where
refname is a label that references the DSECT name in one of the
following formats:
- refname
- is the label of an 8-byte field that contains the 6-byte DSECT name and an
optional 2-character version.
- A/refname
- is the label of a 4-byte field that contains the storage address of the
DSECT name and an optional 2-character version.
- FILE=dsect
- specifies the file or subfile that you want to access, where
dsect is the 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.
- 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 only modifies the LRECs that match these keys.
- Note:
- In an ALCS environment, TPFDF C language support must be enabled if you
specify this parameter when KEYCHECK=YES is defined on the DBDEF macro.
See TPFDF Installation and Customization for more
information about enabling TPFDF C language support in an ALCS
environment.
- 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 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.
- 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.
- 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 TPFDF product to issue any of the
following system errors while processing this macro:
- 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 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.
- REG=register
- specifies a register in which to return the address of the current LREC
(this address is contained in SW00SR field SW00REC). You must specify
this parameter for T-type files.
- REGD=register
- specifies a register in which to return the base address of the userLREC
part of an extended LREC.
Entry Requirements
None.
Normal Return
- 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.
Error Return
None.
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.
- 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 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 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.
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
Related Macros