File maintenance utility runtime parameters

Edit online

There are several runtime parameters that you can pass to the file maintenance utility at its startup, all of which are optional. You can specify these parameters using any combination of the following methods:

Allow the file maintenance utility to use its built-in defaults.
Define your own values in CBKMAINT, which can be a member of either a CBKPARMS data set, or a data set in the MVS logical parmlib concatenation.
Define you own values in the PARM string of the EXEC JCL statement.

The file maintenance utility searches for startup parameters, and processes them, in the following way:

Default values: The file maintenance utility first sets the default values for each parameter and continues at step 2.
CBKPARMS data set: The file maintenance utility searches for a CBKMAINT member in the CBKPARMS data set, if present. If the utility finds a CBKMAINT member it uses any runtime parameters in the member to override the defaults. If the member is empty, the defaults are not changed. When the file maintenance utility has finished processing the CBKMAINT member, it continues at step 4.
Logical parmlib concatenation: If the file maintenance utility cannot find a CBKMAINT member in CBKPARMS, it searches for a CBKMAINT member in the MVS logical parmlib concatenation. If the utility finds a CBKMAINT member it uses any runtime parameters in the member to override the defaults. If the member is empty, the defaults are not changed.
PARM string: The file maintenance utility reads any parameters specified in the PARM string of the JCL EXEC statement, and uses these to override default or CBKMAINT parameter values.

Note: If you want to use only default values, or specify parameters in the PARM string only, do one of the following:

Include an empty CBKMAINT member in the CBKPARMS data set. The file maintenance utility skips to step 4 when it finds an empty CBKMAINT member.
Authorize the file maintenance utility to have READ access to all the data sets in the MVS logical parmlib concatenation. The file maintenance utility continues with step 4 if it cannot find a CBKMAINT member. If the file maintenance utility does not have at least READ access to the logical parmlib concatenation, the job step fails with a 913 abend.

The runtime parameters enable you to:

Specify the CICS region applid
Specify the message severity level for producing system dumps
Specify the language used by the file maintenance utility for messages written to the message log
Specify trace settings.

The runtime parameters are described in detail as follows:

APPLID(name)

Specifies the CICS region applid. If CICS® BAC is not active in the specified CICS region, the file maintenance utility can use the applid to locate the region control file table (CBKCFTBL) entry and obtain the fully-qualified name of the CICS region control file, which the utility can then update directly.

If you omit this option, you must specify the CBKCNTL DD statement in the batch job step of the file maintenance utility. The file maintenance utility uses the data set name specified on the CBKCNTL DD statement to perform a reverse lookup of the control file table (CBKCFTBL) to find the corresponding CICS region applid.

If you omit both APPLID and the CBKCNTL DD statement, the job step terminates with an error message (see message CBKxx7010 ).

CICSMIRRORTRANS({CSMI | transid})

Specifies the name of the CICS mirror transaction to be specified on EXCI requests issued by the file maintenance utility. When the EXCI request is executed in the target CICS region, it runs under this transaction ID as an MRO mirror transaction.

CSMI

This is the normal CICS EXCI default mirror transaction ID.

transid

Specifies the 4-character name that you want CICS to use as the name of the MRO mirror transaction when it executes the EXCI requests it receives from the file maintenance utility. To avoid confusion with other mirror transactions that might be running in your CICS regions, you might want to choose a unique ID to identify CICS BAC file maintenance utility mirror transactions. Define the appropriate transaction ID in the CICS region for a CICS mirror transaction, ensuring the following:

The program associated with the transaction ID must be DFHMIRS
The profile for the transaction ID must be DFHCICSA.

You might consider using the CICS-supplied CSMI transaction definition as a basis for this transaction ID.

LANGUAGE({ENU | JPN})

Specifies the language used by the file maintenance utility for messages written to the message log (DD name CBKPRINT). See CICS BAC national language support (NLS) for more information. The values you can specify are:

ENU: US English
JPN: Japanese

Note: Specify the language parameter only on the PARM string of the JCL EXEC statement for the file maintenance utility. The parameter is ignored if it is specified in the CBKMAINT member in either the CBKPARMS data set or the logical parmlib concatenation.

MAXDOWNLOADPAGES(256|number)

Specifies the maximum number of 4KB pages the file maintenance utility is to allocate as a buffer for downloading data from the target CICS region.

number: Specifies the number of pages in the range 1 through 999. The default is 256.

Note that if the allocated buffer is too small for the command being processed, the command fails and the file maintenance utility issues message CBKxx7310. For example, if you issue a LIST command with only the generic character as the identifier, the volume of data returned could be quite large if the region control file contains multiple object records of the specified resource type.

MSGLEVEL(16 | value)

Specifies when the file maintenance utility is to produce a dump, based on the return code severity. The default return code value is 16.

When the file maintenance utility is terminating, its final step is to compare the value of the return code with the value of the MSGLEVEL option. If the return code is greater than or equal to MSGLEVEL, the job step is terminated with abend code U3502 and takes a dump. Thus by default, any return code of 16 or greater causes the utility to abend and produce a dump.

MSGLEVEL is intended primarily for support and diagnosis purposes. For example, if Technical Support need a dump when you have a condition where the utility is terminating with return code 8, you can specify EXEC PGM=CBKFMAIN,PARM='MSGLEVEL(8)', and run the job again to force an abend and a dump.

TRACEOPTIONS({C0 | options})

Specifies the types of trace entries you want CICS BAC to create. There are eight trace entry types, each controlled by a single bit in the TRACEOPTIONS hexadecimal byte flag. Specify this option only at the direction of a Technical Support representative.

C0: The hexadecimal value C0 is the default trace setting.
options: Specify, in hexadecimal form, the options requested by Technical Support.

TRACESIZE({1000 | number-of-entries})

Specifies the size of the trace table in terms of the number of entries to be traced for diagnostic purposes. Change this value only at the direction of Technical Support.

1000: The default trace size.
number: Specify the trace size as requested by Technical Support.