DBMRG-merge logical records from two subfiles

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 that you want to access, where dsectvv is the 6-character DSECT name and an optional 1- or 2-character suffix.

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.

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.

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 subfile and deletes it from DASD. All overflow blocks are released. If the file is a pool file:

1. The prime block is also released.
2. If the subfile is indexed:
   1. If an algorithm was specified either on the DBMRG macro or on a previous API managing this subfile, the subfile is de-indexed from the specified path.
   2. If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the subfile will be de-indexed from all its indexes.
   Note: In both cases, the application cannot open the indexes with the HOLD option in the same entry control block (ECB).

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.

You must open both subfiles before calling DBMRG.

None.

See Identifying Return Indicators and Errors for information about how to check the error indicators.

• 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.
• Any keys that are active for the input file when you call this macro will be ignored, but are preserved. Use the DBSRT macro if you want to select records from the input file.
• The output file cannot be in detac mode when you use the DBMRG macro.
• You cannot issue additional TPFDF macros to the input file if the following conditions are true:
  • You specified the FULLFILE parameter.
  • The end-of-file indicator is set.

  However, you can issue the DBCLS macro with the REUSE parameter specified and then continue with additional TPFDF macros. See Identifying Return Indicators and Errors for information about the end-of-file indicator.

• When macro processing has been completed, the output subfile remains open and must be closed by 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.
• The following figure shows how the DBMRG macro merges LRECs from two subfiles. The input file is defined by the INPUTREF parameter and the output file is defined by the REF parameter. Figure 21. Merging LRECs from Two Subfiles.
  

  This macro does not modify the input subfile that you specify with the INPUTREF parameter.

• 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.
• If the AUTODEINDEX=YES parameter is specified on the DBDEF macro and an indexed subfile is empty when the input subfile is merged, the input subfile will be de-indexed from all its indexes and all corresponding pool file addresses will be released. The application cannot open the indexes with the HOLD option in the same ECB in this case.

The following example merges files GR26DF and GR25DF.

DBMRG REF=GR26DF,INPUTREF=GR25DF,                *
      KEY1=(R=GR25KEY,L==AL2(L'GR25KEY))         *