EXEC parameters for IMS batch message processing regions

Using EXEC parameters, you can override definitions for IMS batch message processing regions that were initially set during IMS system definition, including definitions for databases, PSBs, data communications, region control and performance, recovery and restart, and security.

The PARM= positional parameters for the BMP region's EXEC statement are shown in Table 1. See the IMSBATCH procedure for more information.

Table 1. Categories and purpose of BMP region parameters
Category Parameter Purpose
Database and PSB MBR Specify name of batch message program
  PSB Specify PSB name
  TEST Check validity of addresses in DL/I calls
  NBA Specify Fast Path database buffers
  OBA Specify Fast Path overflow buffers
Data Communication IN Specify an input transaction queue
  OUT Specify an output transaction queue
Region Control and Performance BMP Specify BMP for batch message region
  OPT Coordinate region start with control region
  LOCKMAX Specify locking limitations
  PRLD Specify suffix of DFSMPLxx for program preload
  PREINIT Specify suffix of DFSINTxx for modules to be preinitialized in readiness for takeover
  STIMER Specify timer options
  CPUTIME Specify processing time limit
  PARDLI Specify region for DL/I processing
  DIRCA Specify interregion communication size
  SSM Specify access to Db2 for z/OS® subsystems
  ALTID Specify alternate IMS system
  APARM Specify application parameter
Recovery and Restart SPIE Allow user program SPIE during DL/I call
  CKPTID Specify checkpoint for program restart
Security options IMSID Override IMS subsystem identifier

PSB-related EXEC parameters for a batch message region

The MBR= parameter specifies the name of the program and is often the same as the PSB name. This parameter is required. The BMP has flexibility in using a program and PSB combination. This allows you to test modifications of the BMP using a temporary program name. You can also use a different PSB with the same program.

The PSB= parameter is optional if it matches the MBR name. If an APPLCTN macro has been included for the PSB specifying BATCH as the program type, the PSB parameter specifies one of several PSBs for a given BMP. You should identify application programs that can process several types of transactions. These programs often require larger amounts of virtual storage, and you can need to adjust the size of the region.

The TEST= parameter is required, but the IMSBATCH procedure generates a 0 to specify that validity checking of the addresses in a DL/I call is not performed. (An address is invalid if it is either lower than the lowest address not in the z/OS nucleus or higher than the highest address in virtual storage.) Adequate testing of the program and controls over the DL/I call parameter list coding should make the generated option (no validity checking) appropriate.

The NBA= parameter specifies the number of Fast Path database buffers to be made available, up to the maximum number available. If you are using the Fast Path 64-bit buffer manager, it manages the segmentation of the buffer pool into subpools. Otherwise, the buffers are taken from the global pool that is defined by the DBBF= parameter in the IMS control region procedure.

The OBA= parameter specifies the number of additional database buffers to be made available in the CSA/ECSA, up to the maximum number available. Fast Path allocates only the largest OBA specification from all currently active regions. If you are using the Fast Path 64-bit buffer manager, be aware that multiple regions can access the overflow buffers concurrently.

Data communication EXEC parameters for a batch message region

For the batch message program, you have the flexibility of declaring that the input transaction queue is to be made available to the program at execution time. You do this by specifying one transaction code as the value for the IN parameter.

Some BMP programs do not access a message queue; however, they have a requirement to send output to a terminal or to generate transactions to be processed by other application programs. Specify the LTERM name or transaction code (as appropriate) on the OUT parameter.

A null value for the IN parameter prevents the program from accessing message queues. When you specify the transaction code for the IN parameter, the program has no restrictions on generated transactions or output messages.

Region control EXEC parameters for a batch message region

BMP= is the first positional parameter for a batch message processing region. These regions are not scheduled automatically. They must be invoked by the operator.

The OPT= parameter helps you control the start of a batch message region. If the control region is not active when the BMP region is invoked, you must decide whether to wait for a control program, cancel the batch message region, or ask the operator to decide. This might occur when JCL in the z/OS job stream for the BMP region is scheduled before the control region has completed its initialization or when the control region is terminating. Specifying 'wait' is a risk because the z/OS resource is reserved until the control region resumes. If you are starting the region from the master terminal, the default generated for the IMSBATCH procedure is satisfactory.

The optional PRLD= parameter specifies the two-character suffix for the member DFSMPLxx in IMS.PROCLIB, which lists the preloaded modules. It is optional; it is generated as a null parameter for the IMSBATCH procedure. For BMP regions that do not have other programs scheduled in them, PRLD provides no performance gain.

The PREINIT= parameter specifies the two-character suffix of the member DFSINTxx in IMS.PROCLIB. This member contains the preinitialization modules that are to receive control.

The optional STIMER= and CPUTIME= parameters are generated as null parameters, their defaults are no use of the timer.

The optional PCB= parameter specifies the size of the interregion communication area. This area holds the PCBs included in the PSBs that are used by programs executing in this region. If you do not specify this parameter, the default value is 000. This allocates an area large enough to hold all the PCBs for the largest PSB defined to this IMS system and present in the active IMS.ACBLIBA/B. To specify a value, enter the number of 1024-byte blocks as a three-digit number (for example, 001).

Use the SSM parameter to reference a member in IMS.PROCLIB that identifies the Db2 for z/OS subsystems that can be accessed from this BMP region. To prevent any access to a Db2 for z/OS subsystem from the BMP, use the name of a null member (no entries). The default (a null value) allows the BMP region to attach to any of the subsystems declared to the IMS control region. If necessary, coordinate this parameter with the corresponding SSM parameter in the IMS procedure. Refer to the description in System control and performance EXEC parameters for the IMS control region.

The FMTO= parameter and the type of z/OS dump DD statements selected determine whether IMS dumps are formatted online or offline.

Use the APARM= parameter to specify execution-time parameters unique to this dependent region. This parameter specifies a character string for the application program or Data Capture exit routine. For batch or BMP regions, the APARM= can be used to specify the frequency for checkpoint calls. The APARM= can also be used to pass parameters to the Data Capture exit routine to indicate whether the data should be captured.

The maximum length of the parameter is 32 characters; the parameter must be enclosed in single quotation marks (') if special characters are used; embedded commas are not allowed. The INQY call with the ENVIRON or ENVIRON2 subfunctions is used to receive the APARM character string.

Recovery-related EXEC parameters for a batch message region

For a BMP program, you can use the CKPTID= parameter to set a restart position for the program processing. The IMSBATCH procedure generates CKPTID as a null parameter. To invoke restart, create a special version of the procedure containing the exact checkpoint identification. This can be a 1- to 8-character extended checkpoint identifier generated by the program itself, or a 14-character time stamp identifier issued within a message from checkpoint processing. Alternatively, you can specify the value LAST as the identifier to cause the last recorded checkpoint to be used. One technique is to restart BMPs with JCL entered in the system reader and have the CKPTID symbolic parameter coded for the EXEC statement.

Related reading: For more details regarding BMP restart for BMPs that use extended checkpoint, refer to IMS Version 15.3 Operations and Automation.

In the case where the application program has a SPIE in effect, you specify whether the SPIE is to remain on or off during the DL/I call. Negated SPIEs are reinstated before returning to the application program.
Recommendation: For performance reasons, do not turn the SPIE on and off for each DL/I call. With PL/I Release 5 and later releases, you can use the PL/I SPIE facility without having IMS reset the SPIE on each DL/I call.

Security-related EXEC parameters for a batch message region

The parameter IMSID is related to security and to operations. You specify the 1-to 4-character identifier for the name of the operational IMS DB/DC environment. If the value does not match the current IMSID of any operating control region, the batch message region is not scheduled.