EXEC parameters for IMS message processing regions

Using IMS™ EXEC parameters, you can control many IMS message processing region characteristics including data communications, PSBs, performance, recovery and restart, and security.

Start of change These EXEC parameters do not apply to DBCTL. End of change

Start of change The PARM= positional parameters for a message processing region's EXEC statement are shown in Table 1. See the DFSMPR procedure for more information. End of change

Table 1. Categories and purpose of message processing region parameters
Category	Parameter	Purpose
Database and PSB	PCB	Specify size of pool for PSB copy
	VALCK	Check validity of addresses in DL/I calls
	NBA	Specify Fast Path database buffers
	OBA	Specify Fast Path overflow buffers
Data Communication	CL1	Specify priority of message class
	CL2-4	Specify up to three lower-priority message classes
Region Control and Performance	LOCKMAX	Turn off locking limitations
	MSG	Specify MSG for message region
	OPT	Coordinate region start with control region
	OVLA	Retain overlay supervisor
	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
	DBLDL	Specify maximum number of IMS.PGMLIB directory entries to be saved
	SOD	Specify output class for spin-off dump
	SSM	Specify access to Db2 for z/OS® or IBM® MQ subsystems
	ALTID	Specify alternate IMS system
	PWFI	Activate pseudo wait-for-input
	APARM	Specify application parameter
Recovery and restart	SPIE	Allow user program SPIE during DL/I call
	TLIM	Specify number of abnormal terminations allowed
Security options	IMSID	Override IMS subsystem identifier

PSB-related EXEC parameters for a message processing region

The PCB parameter is an optional parameter that 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).

The default value for the VALCK parameter signifies that address validity checking is not to be performed for DL/I calls issued by the application programs in this region. (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.) With adequate testing of and controls over the DL/I call parameter coding, validity checking should not be necessary.

Data communication EXEC parameters for a message region

A message region requires the set of four parameters, CL1=, CL2=, CL3=, CL4=, to specify transaction classes. Express each class as a three-digit number. The first message class for the region causes all messages assigned to that class to be selected first as eligible for scheduling. Only when all possibility of scheduling a transaction in that class has been exhausted does scheduling begin for the second message class. Priorities determine the order that programs are to be selected for scheduling into the region. The message classes you specify need to be coordinated with your transaction scheduling rules and the numbers entered with the PRTY keyword on the TRANSACT macro.

Region control EXEC parameters for a message region

MSG is the first positional parameter for a message processing region. When transactions are encountered on the queue, programs are automatically scheduled in these regions, if the message class priority is suitable.

The parameter OPT= helps you control the region startup. If, for some reason, the control region is not active or is terminating when the MPP region is invoked, you can have the MTO decide whether to start the MPP region again (the default), let it wait until the control region is ready, or cancel it.

Use STIMER= to invoke timer facilities. If you use the non-default LSO option, LSO=S, both application program and DL/I processing times are recorded. Most DL/I processing time is not included when you use the default, LSO=Y. A value of 1 causes a timer sequence to be issued once for each DL/I call that can adversely affect the performance of the region. This parameter is used with the TIME= parameter on the //JOB statement.

Recommendation: Because a timeout of a message region causes an abnormal termination of the message region, have processing limits coded within the application program.

Use the SSM= parameter, which is required when using Db2 for z/OS group names to point to a member in IMS.PROCLIB that identifies the Db2 for z/OS subsystems that can be accessed from this MPP region. To prevent any access to subsystems from an MPP scheduled into this region, use the name of a null member (no entries). The SSM= default, a null value, allows the MPP 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.

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. 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 subfunction is used to receive the APARM character string.

Related reading: For more information, see IMS Version 13 Application Programming.

Use the SOD parameter to specify the output class for a spin-off dump. In this way, you can obtain a printed copy of the storage immediately at abnormal termination of the message region immediately rather than being placed on general SYSOUT queues.

Performance-related EXEC parameters for a message region

Four performance-related options are available. The parameter OVLA= enables you to retain a copy of the overlay supervisor in the message region. The default is to have the overlay control loaded each time you schedule an overlay application program in the region. If you have arranged the message priorities so that an overlay program is likely to be scheduled in the region, you should use this option.

Use the DBLDL= parameter to minimize the cost of program loading by increasing the number of program directory entries maintained in the message region. The effect is to reduce the I/O to the program library (and the search) to obtain the direct address of the program. The default is 20.

Use the PRLD= parameter to specify the two-character suffix of the member DFSMPLxx in IMS.PROCLIB. This member contains the list of programs that are to be preloaded. The effect is to reduce the repetition of I/O for program load. The region address space retains the modules.

PREINIT allows you to specify the two-character suffix of the member DFSINTxx in IMS.PROCLIB. This member contains the preinitialization modules to are to receive control.

The type of program load selected depends on the order of the following:

Preload list
Standard z/OS fetch

The fourth performance-related parameter is the PWFI= (Pseudo WFI) parameter. Specifying PWFI=Y can potentially reduce CPU time by eliminating the termination and rescheduling of resources. On a message GU call, if MODE=SNGL is specified on the TRANSACT macro and no more messages are available, IMS checks to see if other work needs to be done for the region. If no other work is available and the resources owned by the region are not needed by another region with work to do, the region becomes idle and waits until another message is queued (wait-for-input mode). It does not return a QC status code to the application program. If the new message is for the transaction that is scheduled in the region, IMS returns the new message to the application program without having to terminate and reschedule the resources.

If the next message that comes in is not for the transaction that is scheduled in the region, but it can be processed by the region, there is a delay before the new transaction can be processed. Because termination of the previous message is delayed until after the new message comes in, the region must go through termination before it can schedule the new transaction.

Recovery-related EXEC parameters for a message region

The TLIM parameter addresses a problem with an application program that causes an abnormal termination. Because the program can be scheduled many times into a region as a result of transactions in the queue, you need to be able to stop the operation of this region. The value for TLIM specifies the limiting number of abnormal terminations permitted. In the case where the application program has a SPIE in effect, the SPIE option allows it to be left on during the DL/I call or for it to be turned off during the DL/I call and reinstated when returning to the application program. For performance reasons, it is not recommended to turn it on and off for each DL/I call. With PL/I Release 5 or later, 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 message region

The parameter IMSID is related to security and to operations. You specify the 1- to four-character identifier for the name of the control region (the name given for the IMSID parameter). If the value does not match the current IMSID of any operating control region, the message region is not scheduled.