bdfp1m2d | Programming Concepts and Reference |
Use this macro to merge two subfiles into one subfile.
Format
Notes:
- See Specifying File Organization with Keyn Parameters for information about the rules for using the
KEYn parameters and file organization parameters together.
- INPUTREF=irefname
- specifies the reference name of the input subfile, where irefname
is one of the following:
- The DSECT name
- A label that references the DSECT name in one of the following
formats:
- irefname
- is the label of an 8-byte field containing the DSECT name.
- A/irefname
- is the label of a 4-byte field that contains the storage address of an
8-byte field containing the DSECT name.
- INPUT=inputaddr
- specifies the base address of the SW00SR slot of the input file.
- Note:
- This parameter is supported for migration purposes only; where possible,
always use the INPUTREF parameter to identify the input subfile.
- 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.
- 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.
- 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.
- FULLFILE
- merges LRECs from the entire input file to the output subfile specified
with the REF parameter.
- 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:
- R
- specifies a field in the LREC to be used for placing the LRECs in the
output file.
- T
- specifies a field in the subLREC of an extended LREC to be used for
placing the LRECs in the output file.
- fldname
- is the name of a field defined in the DSECT for the LREC; for
example:
... KEY1=(R=GR00FLD)
- label1
- is a 2-byte field containing the displacement into the LREC; for
example:
... KEY1=(R=EBX010,L==H'4')
- D/absval
- specifies the displacement into the LREC of the field, where
absval is an absolute value; for example:
... KEY1=(R=D/2,L=L'GR00NAM,UP)
You can also specify the absolute value implicitly; for example:
... KEY1=(R=D/GR00NAM-GR00REC,L=L'GR00NAM,UP)
- literal
- is a halfword literal containing the displacement into the LREC; for
example:
... KEY1=(R==H'2',L==H'4')
- flddisp
- is the displacement off the field of the LREC; for example:
... KEY1=(R=GR00FLD+2,L==H'4')
or
... KEY1=(R=GR00FLD+L'GR00FLD,L==H'4')
- L=length
- specifies the length of the field to be used in placing the LRECs in the
output file, where length is one of the following:
- The label of a 2-byte field containing the length of the field
- 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.
- 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.
- NOPGM
- specifies not to change the program stamp in a block when filing
it.
- RELEASE
- releases the SW00SR slot for the input subfile after the macro has
completed processing.
- RELFC
- releases the input subfile and deletes it from DASD. All overflow
blocks are released. If the file is a pool file, the prime block is
also released. If the file is a fixed file, the prime block is
initialized to empty.
- SUFFIX=char
- allows you to use the same DSECT to map two different areas of storage,
where char is the suffix character.
Entry Requirements
You must open both subfiles before calling DBMRG.
Normal Return
None.
Error Return
See Identifying Return Indicators and Errors for information about how to check the error
indicators.
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.
- After opening a file, if you use fullfile processing to access or
update records, you must continue to use fullfile processing on any subsequent
macros when available until the file is closed. Accessing or updating
subfiles using fullfile processing cannot be mixed with macros that access or
update records without using fullfile processing.
- Make sure the input file contains LRECs that are in the same order as the
output file. If the input file is not in the same order as the output
file, do not merge the files until they are in the same order. Use the
DBSRT macro to arrange the input file in the same order as the output
file.
- If the output subfile is not a B+Tree subfile, you
must specify keys using KEYn parameters or the KEYLIST
parameter when you call this macro. The keys specify how the TPFDF
product sorts the LRECs in the output subfile.
The KEYn and KEYLIST parameters are ignored for
B+Tree files. The output file is organized according default
keys defined on the DBDEF macro for the file. See TPFDF Database Administration for more information about
default keys.
- The output file cannot be in detac mode when you use the DBMRG
macro.
- You cannot issue additional TPFDF macros to the input file until the file
is closed if the following conditions are true:
- You specify the FULLFILE parameter
- You do not specify the RELEASE parameter
- The end-of-file indicator is set.
However, you can specify the REUSE parameter on the DBCLS macro.
See Identifying Return Indicators and Errors for information about the end-of-file indicator.
- When this macro has completed processing, the output subfile is left
open and must be closed using the DBCLS macro before the ECB exits. If
you specify the RELEASE parameter, this macro closes the input
subfile.
- You cannot use this macro with P-type files.
- Figure 20 shows how the DBMRG macro merges LRECs from two
subfiles.
Figure 20. Merging LRECs from Two Subfiles. The input file is defined by the INPUTREF parameter and the output file is defined by the REF parameter.
This macro does not modify the input subfile that you specify with the
INPUTREF parameter. The TPFDF product leaves the ECB data level for the
input subfile free after use.
- If you use the DBMRG macro in a commit scope, the files or subfiles that
are being merged must be opened in the same commit scope. See Commit Scopes for more information about commit scopes.
Examples
The following example merges files GR26DF and GR25DF.
DBMRG REF=GR26DF,INPUTREF=GR25DF, *
KEY1=(R=GR25KEY,L==AL2(L'GR25KEY)) *
Related Macros
DBSRT-Sort a Subfile.