TRANSACT macro

The TRANSACT macro statement is used one or more times with each APPLCTN macro statement to identify transactions as IMS exclusive, IMS Fast Path potential, or IMS Fast Path exclusive. It also provides the IMS control program with information that influences the application program scheduling algorithm. It can define a message editing routine.

If you do not include this macro during stage 1 system definition, no warning is issued, and it is assumed that you define your transaction codes dynamically. You can define them dynamically using either CREATE TRAN and UPDATE TRAN commands, or the Destination Creation exit routine (DFSINSX0).

If the TRANSACT macro statement is preceded by an APPLCTN macro defining it as remote (specifies SYSID), this transaction is generated as a remote transaction.

An IMS Fast Path-exclusive transaction is identified by a TRANSACT macro statement following an APPLCTN statement that specifies both PGMTYPE=TP and FPATH=YES.

TRANSACT macro statements that identify IMS Fast Path-exclusive transactions generate routing code entries. These entries are automatically generated and have the same name as the corresponding transaction codes. They are used by the IMS Fast Path Expedited Message Handler routines to locate the Fast Path application program named in the preceding APPLCTN macro statement that processes the input message.

An IMS Fast Path-potential transaction is identified by a TRANSACT macro statement that specifies FPATH=YES following an APPLCTN statement that specifies PGMTYPE=TP and FPATH=NO.

An application defined as FPATH=NO cannot be run in a Fast Path region (IFP), even though the application contains Fast Path-potential transactions. To run these Fast Path-potential transactions in an IFP region (a region that has FPATH=YES specified on the APPLCTN macro), both of the following conditions must be true:

• A routing code must be specified for the IFP on the RTCODE macro.
• The Fast Path-potential transaction must be routed to the IFP by the appropriate routing code.

All Fast Path transactions are implicitly defined as recoverable.

MSGTYPE=(SNGLSEG,RESPONSE) must be specified on the TRANSACT statement for Fast Path potential transactions.

Additional routing codes can be associated with a Fast Path application program by using the RTCODE macro statement following the corresponding APPLCTN macro statement.

TRANSACT macro statements with FPATH=YES and RTCODE macro statements are invalid after APPLCTN macro statements that define an IMS batch message processing (BMP) application.

Dynamic definition

If you do not include this macro during stage 1 system definition, no warning is issued, and it is assumed that you define your transaction codes dynamically.

It is recommended that you enable dynamic resource definition for MODBLKS resources to dynamically update existing transactions. Changes to existing transactions cannot be introduced through a MODBLKS online change if those attributes are changeable by online commands. You can use the /ASSIGN or /CHANGE commands to change existing transactions, but the command needs to be reissued after you perform a local online change or a global online change, before the affected transactions are scheduled. Dynamically updating transactions allows you to avoid issuing and then reissuing the /ASSIGN or /CHANGE commands for the existing transactions.

When DRD is disabled, CREATE, DELETE, IMPORT, and most UPDATE commands that change the definitional attributes of a resource are rejected.

The following table compares the TRANSACT macro keywords and the equivalent CREATE and UPDATE command keywords used for dynamic definition. The table also includes equivalent values for the INSXTRNQ DSECT, which is mapped to by the DFSINSX0 parameter list. The information in INSXTRNQ is used to create a transaction control block if the destination is a transaction. Default values are shown in bold.

Supported environments

The TRANSACT macro can be optionally used in IMS DB/DC and DCCTL environments.

Syntax

                      .-,----------------.       
                      V                  |       
>>-TRANSACT--CODE=(-----transaction code-+---)------------------>

>--+----------------+--+-----------------+---------------------->
   |       .-NO---. |  |         .-YES-. |   
   '-,AOI=-+------+-'  '-,DCLWA=-+-----+-'   
           +-YES--+              '-NO--'     
           +-TRAN-+                          
           '-CMD--'                          

>--+-------------------------+--+--------------------------+---->
   |         .-UC--.         |  |            .-0-------.   |   
   '-,EDIT=(-+-----+-,name-)-'  '-EXPRTIME=(-+---------+-)-'   
             '-ULC-'                         '-seconds-'       

>--+------------------+----------------------------------------->
   |         .-NO---. |   
   '-,FPATH=-+------+-'   
             +-YES--+     
             '-size-'     

>--+---------------------------------------+-------------------->
   |            .-NO--. .-,RECOVER-.   (1) |   
   '-,INQUIRY=(-+-----+-+----------+-)-----'   
                '-YES-' '-,NORECOV-'           

>--+---------------------+--+---------------------+------------->
   |          .-0------. |  |        .-MULT-. (2) |   
   '-,MAXRGN=-+--------+-'  '-,MODE=-+------+-----'   
              '-number-'             '-SNGL-'         

>--+------------------------------------------------------+----->
   |            .-MULTSEG-. .-,NONRESPONSE-. .-,1-----.   |   
   '-,MSGTYPE=(-+---------+-+--------------+-+--------+-)-'   
                '-SNGLSEG-' '-,RESPONSE----' '-,class-'       

>--+-------------------------+---------------------------------->
   |          .-65535--. (2) |   
   '-,PARLIM=-+--------+-----'   
              +-0------+         
              '-number-'         

>--+----------------------------------------------------------+-->
   |            .-65535-. .-,65535--------------------.   (2) |   
   '-,PROCLIM=(-+-------+-+---------------------------+-)-----'   
                '-count-' '-,CPU-time-per-transaction-'           

>--+--------------------------------------------------+--------->
   |         .-1------. .-,1-----. .-,65535-------.   |   
   '-,PRTY=(-+--------+-+--------+-+--------------+-)-'   
             '-normal-' '-,limit-' '-,limit count-'       

>--+-------------------+--+------------------------+------------>
   |           .-NO--. |  |         .-0------. (2) |   
   '-,ROUTING=-+-----+-'  '-,SEGNO=-+--------+-----'   
               '-YES-'              '-number-'         

                                                    (2)   
>--+------------------------+--+------------------+------------->
   |           .-0----. (2) |  |          .-NO--. |       
   '-,SEGSIZE=-+------+-----'  '-,SERIAL=-+-----+-'       
               '-size-'                   '-YES-'         

>--+--------------------------+--------------------------------->
   |            .-,STRUNC-.   |   
   '-,SPA=(size-+---------+-)-'   
                '-,RTRUNC-'       

>--+-------------------------------------------+---------------->
   '-,SYSID=(remote system id,local system id)-'   

>--+------------------+--+----------+--------------------------><
   |            .-N-. |  |      (2) |   
   '-,TRANSTAT=-+---+-'  '-,WFI-----'   
                '-Y-'                   

1. NORECOV is not valid when NO is specified.
2. These operands are not appropriate if a transaction destined for processing in another (remote) system is being specified.

Positional parameters

WFI is the only positional parameter for the TRANSACT macro.

Keyword Parameters

To find which parameters apply to your IMS configuration, refer to Selecting the appropriate macros to define your system.

AOI=

For type-1 AOI: For Type 1 Automated Operator Interface (AOI), specifies whether (YES | TRAN | CMD) or not (NO) a particular transaction is allowed to issue the AOI command (CMD) call.

NO

When AOI=NO, a particular transaction cannot issue the AOI command (CMD) call. If the EXEC parameter AOI1=N is defined, all transactions are allowed to issue the CMD call, including this transaction. AOI1=N overrides AOI=N.

YES

When AOI=YES is specified, the authorization of the commands is like authorization for ICMD calls; the user ID or program name is used for authorization. For some environments, if a Get Unique call has not yet happened, then the program name is used for the authorization. Specifying AOI=YES requests that the user ID of the user who entered the transaction be authorized against the command (in CIMS class).

TRAN

The TRAN specification is the same as YES, but it also requests that IMS use the transaction code, instead of the user ID of the user who entered the transaction, to check the authorization of the commands for the CMD calls issued by the transaction.

When a transaction is defined with AOI=TRAN, the first authorization check done for AOI for the transaction results in the accessor environment element (ACEE) being built. This environment is kept for use by future authorization checks. In this case, the type-1 AOI transactions need to be defined to RACF® (or equivalent product) as a user. The transactions are then specified on RACF PERMIT statements for each command they are allowed to issue from a type-1 AOI transaction. Specifying AOI transactions as users to RACF might conflict with the name of a user already defined to RACF. If this occurs, then either the transaction name or the existing user name needs to be changed.

CMD

The CMD specification is the same as YES, but also indicates that authorization checking is based on which transactions can issue a particular command. In this case, the commands (or the first three characters of the commands) need to be defined to RACF (or equivalent product) as a user. The type-1 AOI transactions must be defined as profiles under the TIMS class, and for each transaction, the commands it can issue must be specified. Using the CMD specification requires you to create fewer user IDs than you need to create for the AOI=TRAN specification. However, using the CMD specification requires you to create or modify a larger number of resource profiles.

Note: If you specify AOI=YES, AOI=TRAN, or AOI=CMD for a transaction and the message being returned on the GU call was received by IMS before the start of IMS execution, a CF status code results. If your application has not specified CF as an acceptable status code, an abend results.

The following table describes how the AOI= specification on the TRANSACT macro impacts the specifications on the EXEC parameter AOI1=.

Table 2. Relationship between AOI= and AOI1= specifications

EXEC parameter AOI1= specification	Effect on TRANSACT macro AOI= specifications
R | C | A	All specifications are retained.
N	NO specification is set to YES. YES specification is retained. TRAN and CMD specifications are reset.

For type-2 AOI: The AOI parameter is also available for type-2 AOI security. However, AOI=NO applies only to type-1 AOI. If AOI=NO is specified or set by default, RACF is used for security checking.

If the TRAN specification is used for type-2 AOI, IMS uses the transaction code, instead of the user ID of the user who entered the transaction, to check the authorization of the commands for the ICMD calls issued by the transaction.

If the CMD specification is used for type-2 AOI, authorization checking is based on which transactions can issue a particular command.

For IMS environments that do not support the use of a transaction, such as a non-message-driven BMP, the AOI=TRAN | CMD specification is not available, and the security checking that is performed is like the checking performed when only YES is specified.

CODE=

Specifies one or more one- to eight-character alphanumeric transaction codes or remote transaction codes. If more than one code is specified, each transaction code name is assumed to have the same characteristics as all other keyword or positional parameter specifications or defaults. Enclose multiple names in parentheses and separate them with commas. Each character of transaction codes and logical terminal names must be an alphanumeric character (A through Z, #, $, @, or 0 through 9). Transaction codes, logical terminals on the NAME macro, and linknames on MSNAME macros must comprise a set of values, each of which is unique in the system. That is, transaction codes, logical terminal names, and MSC linknames, collectively, cannot contain duplicates. The CODE operand is required.

Example:

CODE=(TRAN1,TRAN2,TRAN3)

DCLWA=

Specifies whether (YES) or not (NO) IMS should perform log write-ahead for recoverable, nonresponse mode input messages and transaction output messages. If not specified in the TRANSACT macro, the default is the DCLWA parameter in the IMSCTRL macro. The DCLWA parameter in the TRANSACT macro overrides the IMSCTRL macro parameter for this transaction.

Specify or accept a default of YES to ensure that both of the following occur:

• A nonresponse input transaction is made recoverable across IMS failures, before IMS acknowledging receipt of the input.
• Database changes are made recoverable before IMS sending associated output reply messages.

YES ensures that information in the log buffers is written to the IMS log, before the associated input acknowledgment or output reply is sent to the terminal.

Specify or accept a default of YES for all VTAM® terminal types.

Specify NO if input message integrity and the consistency of output messages with associated database updates is not required. DCLWA does not apply to response mode or Fast Path input processing, and is ignored during IMS execution.

EDIT=

Specifies whether (UC) or not (ULC) the input data is to be translated to uppercase. The first parameter of this operand defines whether the transaction is uppercase/lowercase (ULC) as entered from the terminal, or if it is to be translated to uppercase (UC) before being presented to the processing program. The default is UC.

Specifying UC for VTAM terminals prevents the transmission of embedded device control characters.

You can also use EDIT to specify the 1- to 8-character name of your own transaction input edit routine that edits messages before the program receiving the message. This name must begin with an alphabetic character. The specified edit routine (load module) must reside on the USERLIB data set before IMS system definition stage 2 execution. This routine cannot be the same as the one that is used on a LINEGRP or TYPE EDIT= parameter.

If FPATH=YES is specified, the EDIT= keyword parameter specifies whether (UC) or not (ULC) the transaction is to be translated to uppercase before being presented to the edit/routing exit routine. Specification of a user edit routine is valid on a Fast Path potential transaction; this specification is used when the transaction is routed to IMS. It is invalid on a Fast Path exclusive transaction.

For input from LU 6.2 devices, the LU 6.2 Edit exit routine (DFSLUEE0) is called instead of the transaction input edit routine specified in EDIT.

For input from OTMA devices, the OTMA Input/Output Edit user exit (OTMAIOED) is called instead of the transaction input edit routine specified in EDIT.

EXPRTIME=

The length of elapsed time, in seconds, that IMS can use to cancel the input transaction. For transactions that exceed the specified elapsed time, IMS identifies the input transaction as expired and discards the transaction. The value can range from 0 to 65535. The default is 0, meaning that no expiration is set for this transaction. If an invalid value is specified, message G316 is issued.

Restriction: Transaction expiration checking is not done at the time of the GU call for Fast Path transactions, IMS conversational transactions, and program-to-program switch transactions.

FPATH=

Specifies whether (YES, size) or not (NO) the transaction code is a potential candidate for Fast Path processing. FPATH=YES is effective only when specified on a TRANSACT statement that follows an APPLCTN statement that does not specify FPATH=YES; otherwise, the operand is ignored. FPATH=size, which determines the EMH buffer size required to run the transaction, overrides the EMHL execution parameter and implies FPATH=YES. The minimum specification for FPATH=size is 12; the maximum is 30720. The default is FPATH=NO.

Fast Path-potential transactions must be processed by a user edit/routing exit to determine whether the transaction is to be processed by IMS Fast Path. If it is to be processed by IMS Fast Path, the edit/routing exit routine associates the transaction with a routing code. This routing code identifies which Fast Path application program is to process the transaction.

If FPATH=YES is specified during a MODBLKS system definition, Fast Path must have been previously defined for the online system.

INQ= or

INQUIRY=

Specifies whether (YES) or not (NO) this is an inquiry transaction. The default is NO. You can specify this keyword either as INQ= or INQUIRY= If INQ= (or INQUIRY=) YES is specified, you can also specify whether (RECOVER) or not (NORECOV) this transaction should be recovered during an IMS emergency or normal restart. The specification of INQ=(NO,NORECOV) is invalid. The default is RECOVER.

For IMS Fast Path transactions, RECOVER must be specified.

INQ=YES should be specified only for those transactions that, when entered, do not cause a change in any database. Programs are prohibited from issuing ISRT, DLET, or REPL calls to a database when scheduled to process a transaction defined as INQ=YES. An application program cannot do an SQL INSERT, DELETE, or UPDATE when the IMS transaction is defined with INQ=YES. The INQ operands are not position dependent.

If the SPA parameter is specified (indicating that the transaction is conversational), INQ=(YES,NORECOV) cannot be specified.

If an attempt is made to enter a transaction that is not specified as INQ=YES from one of these terminals, the transaction is rejected. A message indicating that the update transaction cannot be processed is sent to the terminal that entered the transaction.

MAXRGN=

Limits the number of message processing program (MPP) regions that can be concurrently scheduled to process a transaction. When the number of MPP regions is not limited, one transaction might monopolize all available regions.

If you specify zero, or if zero is defaulted to, no limit is imposed. The maximum number you can specify is 255.

If you specify SERIAL=YES in the TRANSACT macro or SCHDTYP=SERIAL in the APPLCTN macro, omit the MAXRGN parameter or set it equal to 0. Also, omit the PARLIM parameter in the TRANSACT macro and accept the default (65 535).

For non-zero values, you cannot specify MAXRGN= unless you also specify PARLIM=.

The value associated with MAXRGN= can be changed using a /CHANGE TRAN command; therefore, it is not affected by an online change sequence of operator commands for an existing transaction, whether it is altered during a MODBLKS system definition or not.

MODE=

Specifies that database buffers are to be written to direct access (flushed) upon each request for a new message (SNGL) by the processing program, or upon program termination (MULT). The default is MULT. Conversational and WFI transactions must be defined as SNGL. SNGL is forced for WFI applications.

This operand affects emergency restart. When MODE=SNGL, emergency restart only reprocesses the last completed message, regardless of whether one or more messages are scheduled and processed by a single load of an application program. Otherwise, emergency restart reprocesses those messages that were scheduled and processed by the single load of an application program, since the time of the previous checkpoint. The number of messages processed depends upon when the last checkpoint is issued.

The MODE= keyword parameters are checked on all IMS Fast Path-potential transactions for MODE=SNGL. If not specified, a warning diagnostic is issued.

If the transaction results in the application calling an external subsystem, such as DB2®, the Commit Verify exit provided by the external subsystem can determine whether MODE=MULT is supported.

MSGTYPE=

Specifies the type of transaction code (single or multiple segment), and whether the communication line from which the transaction is entered is to be held until a response is received. The MSGTYPE operands are not position dependent.

The transaction code can be single segment (SNGLSEG), or multiple segment (MULTSEG). It specifies the time at which an incoming message is considered complete and available to be routed to an application program for subsequent processing. The defaults are (MULTSEG,NONRESPONSE,1).

If MSC-directed routing is used in a multiple IMS system configuration, IMS does not ensure that both the message and the transaction destined to process that message are either single segment or multiple segments.

The MSGTYPE= keyword parameters are checked on all IMS Fast Path-potential transactions for MSGTYPE=(SNGLSEG,RESPONSE). If not specified, a warning diagnostic is issued.

The first parameter of the MSGTYPE keyword specifies one of the following choices for number of segments:

MULTSEG

Specifies that the incoming message can be more than one segment in length. It is not eligible for scheduling to an application program until an end-of-message indication is received, or a complete message is created by MFS.

SNGLSEG

Specifies that the incoming message is one segment in length. It becomes eligible for scheduling when the terminal operator indicates end-of-segment.

The second parameter of the MSGTYPE keyword specifies one of the following response choices:

NONRESPONSE

Specifies that, for terminals specifying or accepting a default of OPTIONS=TRANRESP, input should not stop after this transaction is entered.

RESPONSE

Specifies that, for terminals specifying or accepting a default of OPTIONS=TRANRESP, no additional messages are to be allowed after this transaction is entered until this transaction sends a response message back to the terminal. Response mode can be forced or negated by individual terminal definition.

The third parameter of the MSGTYPE= keyword specifies the class to which this transaction code is to be assigned. This parameter must be a decimal number from 1 to 999. The default is 1.

Because the values associated with the class keyword can be changed using an /ASSIGN command, they are not affected by an online change sequence of /MODIFY operator commands for an existing transaction, regardless of whether these values are altered during a MODBLKS system definition. The value specified must not exceed the MAXCLAS= value specified or accepted by default on the IMSCTRL macro statement. Regardless of specification made or default taken, remote transaction codes are assigned a class of zero. If the transaction code class is specified in the APPLCTN macro, this parameter need not be specified. If the transaction code class is specified in both the APPLCTN and TRANSACT macros, the APPLCTN macro specification is ignored for this transaction. Define CPI transactions with a different message class from that used for non-CPI transactions. IMS handles all CPI transactions as priority zero within the transaction class.

MSGTYPE=RESPONSE is ignored during online processing for all terminals that do not operate in response mode.

PARLIM=

Specifies the threshold value to be used when SCHDTYP=PARALLEL is specified in the preceding APPLCTN macro instruction. In a non-shared queues environment, if the current transaction enqueue count exceeds the PARLIM value multiplied by the number of regions currently scheduled for this transaction, an additional region is scheduled when a subsequent schedule event for this transaction's class occurs. In a shared-queues environment, the successful consecutive GU count is used instead of the enqueue count. When the consecutive GU count equals the PARMLIM value multiplied by the number of regions currently scheduled (or when PARMLIM=0), an additional region is scheduled. Events can include the following:

• Message enqueue from terminal.
• Message insert from application. One region is allowed per sync point, EXPRESS=NO PCB. For example, when an application inserts two messages for the same transaction code, only one region is scheduled at sync point.
• /ASSIGN command.
• Application term thread.
• Successful application message GU (shared queues only)

If you do not specify a value for PARLIM, IMS:

• Assigns a value of 65 535 to PARLIM. You cannot specify 65 535 as a value for PARLIM.
• Allows the transaction to be scheduled in only one region at a time (that is, IMS disables transaction load balancing).

Valid values for PARLIM can be either any number from 0 to 32 767, or 65 535.

PARLIM=0 indicates that any input message (or successful GU, for shared queues) can cause a new region to be scheduled because the scheduling condition is always met (the number of messages is greater than zero).

The value specified for PARLIM applies to message processing programs (MPPs) only. PARLIM is not supported for batch message processing programs (BMPs).

PARLIM is not applicable to FPE transactions and should be allowed to default to 65 535. If a PARLIM value is specified for FPE transactions, it is ignored by scheduling. Specifying a PARLIM value other than the default value results in a branch and link (BAL) status shown for an FPE transaction on commands such as /DISPLAY TRAN or QUERY TRAN. The PARLIM and BAL status can be ignored for FPE transactions.

The value for PARLIM is not affected by an online change sequence of operator commands for an existing transaction, regardless of whether it is altered during a MODBLKS system definition because the value associated with the PARLIM= keyword can be changed using an /ASSIGN command.

Note: In a shared-queues environment, the PARLIM value behaves differently than it does in a non-shared-queues environment. In a non-shared-queues environment, the queue depth (the number of messages that are currently enqueued) for the transaction is used as the value that is compared with the PARLIM value to determine when to schedule another region. IMS responds to a growing queue of input transactions by scheduling more regions as the queue grows.

In a shared-queues environment, each individual IMS does not know the depth of the queue, because the queue is in the shared-queues coupling facility structure that is managed by Common Queue Server (CQS). The transaction queue might be added to by many different IMS systems. IMS is notified only when the first message is put in a queue (that is, when the queue becomes not empty). IMS is not notified for every subsequent message that is placed on the queue after that first message. In a shared-queues environment, the PARLIM comparison is done against a counter that each IMS keeps of the number of successful consecutive GU calls for the transaction by that IMS, rather than queue depth. IMS schedules more regions when it consistently gets messages from CQS when it asks for them. Thus, in a shared-queues environment, IMS infers the depth of the queue of messages based on processing activity, but it does not know the actual depth of the queue.

A PARLIM value of 0 in a shared-queues environment is the most responsive setting. PARLIM(0) ensures that message regions are scheduled until all messages are processed from the transaction queue, or until the maximum region value (MAXRGN) limit is reached. PARLIM(0) might, however, result in many unnecessary schedules (or false schedules). A false schedule occurs when a message region is scheduled and finds no more messages on the queue. This occurs particularly with PARLIM(0) because after each successful get unique (GU), IMS must always schedule an additional region to try to read the queue to see if there are more messages. This process continues for each successful GU until the queue becomes empty, at which time the successive GU count is reset to 0. This is a consequence of IMS not knowing how many messages are queued on the transaction queue.

Setting the PARLIM to a value greater than 0 can reduce the number of false schedules, because IMS then schedules a new message region only after a number of messages have been obtained consecutively without the queue becoming empty. Setting the PARLIM to a value of 2 or greater is useful for reducing false schedules for transactions that are low-volume and that run relatively quickly (such that the queue depth is typically 1), because it avoids scheduling a second region until the first region has obtained at least two messages in a row. However, be aware that while a PARLIM value greater than 0 can reduce unnecessary schedules, it is also less responsive. If a transaction is long running, or if its processing is delayed (for example, because of locking contention), the consecutive GU count does not change while the transaction is executing, and no additional message regions are scheduled. This can result in delayed processing of other messages for this same transaction until a currently-scheduled message completes. This delay can occur even if message regions are available to process the transaction.

Recommendations:

• If you specify PARLIM=0, specify a MAXRGN value to limit the number of regions that can be scheduled to process a particular transaction. If you specify PARLIM=0 and you do not specify a value for MAXRGN, one transaction might monopolize all the available regions.
• If you specify SERIAL=YES in the TRANSACT macro or SCHDTYP=SERIAL in the APPLCTN macro, omit the PARLIM parameter and accept the default (65 535). Also, omit the MAXRGN parameter in the TRANSACT macro or set it equal to 0.

PROCLIM=

Specifies the number of messages (count) of this transaction code a program can process in a single scheduling, and the amount of time (for non-Fast-Path transactions, in seconds; for Fast Path transactions, in hundredths of seconds) allowable to process a single transaction (or message). Batch Message Programs (BMPs) are not affected by these settings.

The first parameter, count, can be changed using an /ASSIGN command. Therefore, its value is not affected by an online change sequence of operator commands for an existing transaction, regardless of whether it was altered during a MODBLKS system definition.

The count specifies the maximum number of messages sent to the application program by the IMS control program for processing without reloading the application program. The count value can range from 0 through 65 535. If 0 is coded, the maximum number of messages sent to the application is one and the application program is reloaded before receiving a subsequent message. Code the count value at 65 535 if no limit is to be placed upon the number of messages processed at a single program load. Values 1 through 65 535 are eligible for quick reschedule processing.

The CPU-time-per-transaction parameter specifies the processing limit count time. This is the amount of time (for non-Fast-Path transactions, in seconds; for Fast Path transactions, in hundredths of seconds) allowable to process a single transaction (or message). The number specifies the maximum CPU time allowed for each message to be processed in the message processing region. The value is a number that can range from 1 to 65 535. Specifying the maximum value means that no time limit is placed on the application program.

For Fast Path transactions (both potential and exclusive), CPU-time-per-transaction represents real time that elapses during transaction processing (not accumulated task time). Real time is used because the input terminal is in response mode and cannot enter another transaction until the response is sent. The count subparameter is ignored.

The defaults for PROCLIM are 65 535 and 65 535.

The count value assigned is used to determine how many messages an application program is allowed to process in a single scheduling cycle. When the application program requests, and receives, the number of messages indicated in the count value, any subsequent requests result in one of two things.

1. IMS indicates no more messages exist if any of the following conditions are true:
   • The region is not an MPP.
   • The currently scheduled mode is not MODE=SNGL.
   • Equal or higher— priority transactions are enqueued for the region.

   IMS might, in fact, have other messages enqueued for the application program. It is the responsibility of the application program to terminate when it receives an indicator that no more messages are available. Termination of the application program makes the region it occupied available for rescheduling. This feature makes it possible for IMS to allow scheduling of higher-priority transactions that entered the system while the previous transactions were in process. In addition, if any equal-priority transactions are enqueued, they become eligible for scheduling on a first-in, first-out (FIFO) basis.

2. The region goes through quick reschedule and returns the next message to the application if all the following conditions are true:
   • The region is an MPP.
   • The transaction is MODE=SNGL.
   • No higher priority transactions are enqueued.
   • Messages are still enqueued for the application.

If equal priority transactions are enqueued, IMS allows the transaction to quick reschedule if the PROCLIM value has not been reached. If the PROCLIM value has been reached, IMS disallows the quick reschedule and processes the other transactions.

Quick rescheduling is also affected by the IMS scheduling algorithm, which takes into account the following factors and more:

• MAXRGN value
• PARLIM value
• Current number of regions in which the transaction is scheduled

The CPU-time-per-transaction value controls application program looping. You are not required to optimize the CPU-time-per-transaction value for program-transaction execution time. However, the CPU-time-per-transaction time value assigned should not be less than the expected per-transaction execution time. If the scheduled application program exceeds the product of CPU-time-per-transaction and count, the application program abends (if the product of CPU-time-per-transaction and count exceeds 24 hours, 24 hours is used). If an IMS STIMER value of 2 is specified on the DFSMPR macro, the region does not abend until completion of the DL/I call.

The application must not use z/OS® timer services, such as STIMER TASK, that override the IMS STIMER. IMS uses the IMS STIMER to time the execution of transactions. If a z/OS TIMER is issued, it disables the IMS STIMER.

The IMS STIMER task tracks processor time statistics, including time durations for:

• Application program execution time
• DL/I processing time
• CPU time for ESAF users such as Db2 for z/OS that continue to process under the TCB of the dependent region. If Db2 for z/OS switches to another TCB, which is the case with parallelism, logging, and prefetch, this time is not included.

PRTY=

Specifies the values that determine the scheduling priority of this transaction. This priority also controls the priority of messages created by this transaction and sent to a destination in a remote system.

normal

The priority assigned to this transaction when the number of input transactions enqueued and waiting to be processed is less than the limit count value. The valid specification range is from 0 through 14. The default is 1.

limit

The priority to which this transaction is raised when the number of input transactions enqueued and waiting to be processed is equal to or greater than the limit count value. The valid specification range is from 0 through 14. The default is 1.

limit count

The number that, when compared to the number of input transactions queued and waiting to be processed, determines whether the normal or limit priority value is assigned to this transaction. The limit count value can range from 1 through 65 535. The default is 65 535.

When the limit priority is used, and the priority is raised to the specified limit priority value, the priority is not reduced to the normal priority until all messages enqueued for this transaction code are processed.

If you do not want the limit priority for this transaction, code equal values for the normal and limit priorities, and a limit count of 65 535.

When a transaction is processed exclusively by a batch message program (BMP), code the normal and limit priorities as 0. The limit count value is ignored for a transaction processed by a BMP.

The APPLCTN macro statement forces the scheduling priority of all transaction codes associated with it to 0 if the program type is batch (PGMTYPE=BATCH on APPLCTN macro statement). However, a batch message processing region (BMP) can process transactions with scheduling priorities other than 0.

For remote transactions, the PRTY parameter determines the priority used to send the transaction to the processing system, which is termed the MSC link message priority. The three MSC link message priority groups are:

• Low
• Medium
• High

The low priority group consists of primary requests in the input terminal system. This group is assigned remote transaction priorities from 0 to 6. The medium group consists of secondary requests, responses, primary requests in an intermediate system, and primary requests in the input terminal system. This group is assigned a remote transaction priority of 7. The high group consists of primary requests in the input terminal system. Messages in this group are assigned remote transaction priorities from 8 to 14. Within each group, messages have a priority based on the current priority value of the transaction or remote transaction in the input terminal system for primary requests, and on the latest processing system for secondary requests and responses.

In an MSC configuration, the transaction priority determines the priority used to send messages inserted by this transaction across an MSC link. If the transaction inserts multiple messages to the same destination (for example, pages to a printer) and these messages must be sent in the order inserted, the normal and limit priority values should be the same. If the normal and limit priority values are not identical, messages inserted at a higher priority than previously inserted messages could arrive at their destination first. (This restriction does not apply to multiple segments of the same message.)

A transaction must have the same characteristics in all systems where it is defined. These characteristics include:

• Non-conversational/conversational
• SPA size if conversational
• Single-/multi-segment messages
• Non-inquiry/inquiry
• Recoverable/nonrecoverable

ROUTING=

If MSC directed routing is used in a multiple IMS system configuration, specifies whether (YES) or not (NO) the application program processing a transaction is informed of the system which originated the transaction.

If ROUTING=YES, an MSNAME corresponding to a logical path back to the originating system is placed in the I/O PCB. If ROUTING=NO, the name of the originating LTERM is placed in the I/O PCB. The default is NO.

SEGNO=

Specifies the maximum number of application program output segments that are allowed into the message queues per Get Unique (GU) call from the application program. It must be specified as a decimal number from 0 through 65 535. The default is 0. If the default specification of 0 is used, the number of segments is not checked by the online system at execution time.

Because the value associated with the SEGNO= keyword can be changed using an /ASSIGN command, it is not affected by an online change sequence of operator commands for an existing transaction, regardless of whether it is altered during a MODBLKS system definition.

SEGSIZE=

Specifies the maximum number of bytes allowed in any one output segment. It must be specified as a decimal number from 0 through 65 535. The default is 0. If the default specification of 0 is used, the segment size is not checked by the online system at execution time.

Because the value associated with the SEGSIZE= keyword can be changed using an /ASSIGN command, it is not affected by an online change sequence of operator commands for an existing transaction, regardless of whether it is altered during a MODBLKS system definition.

The maximum output message segment to a LU 6.2 device is 32,767. If a transaction is expected to send output to a LU 6.2 device, the SEGSIZE parameter should be no greater than 32,767. However, this is not enforced during processing of the TRANSACT macro, because IMS cannot determine the device type for the message destination until output time.

SERIAL=

Forces serial processing of messages for a given transaction. When SERIAL=YES, U3303 pseudoabends do not cause the message to be placed on the suspend queue but rather on the front of the transaction message queue, and the transaction is stopped with a USTOP.

The USTOP of the transaction is removed when the transaction or the class is started with a /START command.

The default for this keyword is NO, which means message processing is done as before with the messages placed on the suspend queue after a U3303 pseudoabend. Scheduling continues until repeated failures result in the transaction being stopped with a USTOP.

If you specify SERIAL=YES, omit the MAXRGN parameter in the TRANSACT macro or set it equal to 0. Also, omit the PARLIM parameter in the TRANSACT macro and accept the default (65 535).

SPA=

Defines, by inclusion, that this transaction is a conversational transaction.

size

Specifies the size of the conversational scratchpad area (SPA). The size specified must be between 16 bytes and 32767 bytes inclusive.

STRUNC│RTRUNC

You can turn on the truncated data option (STRUNC) or off (RTRUNC).

If you specify SPA=STRUNC, IMS preserves all the data in the SPA, even when a program switch is made to a transaction that is defined with a smaller SPA. The transaction with the smaller SPA does not see the truncated data, but when the transaction switches to a transaction with a larger SPA, the truncated data is used.

If you specify SPA=RTRUNC, the truncated data is not preserved.

STRUNC is the default.

When a conversation initially starts, and when a program switches, the STRUNC│RTRUNC option is checked and set or reset as specified. When the option is set, it remains set for the life of the conversation, or until a program switch occurs to a transaction that specifies the option is to be reset.

When a program switch occurs, the truncated data option for the new transaction is first checked, and if specified (either STRUNC or RTRUNC), that specification is set for the conversation and is used for the SPA inserted into the output message. If the option is not specified for the new transaction, the option currently in effect for the conversation is used.

Restriction: The CORE, DASD, and FIXED operands can no longer be used. If you specify them, assembly errors occur.

SYSID=

In the multiple-IMS system configuration, specifies the system identification (SYSID) of the remote system (the system on which the application executes) and the SYSID of the local system (the originating system to which the responses are returned). The values specified must be from 1 through 2036. The remote SYSID specified must also be defined in an MSNAME macro statement, but the local SYSID can be defined in any or all the MSNAME, TRANSACT, and APPLCTN macro statements.

If the SYSID parameter is specified in the APPLCTN macro statement, you need not specify the SYSID in the TRANSACT macro statement. If the SYSID is specified in both the APPLCTN and the TRANSACT macro statements, the TRANSACT specification is ignored.

The SYSID parameter is independent of the link type (CTC, MTM, VTAM) specified on the TYPE= keyword of the MSPLINK macro statement. Because the values associated with the SYSID= keyword can be changed using an /MSASSIGN command, they are not affected by an online change sequence of operator commands, regardless of whether the values are altered during a MODBLKS system definition. The values only take effect during an IMS cold start.

A Fast Path-exclusive transaction cannot have SYSID= specified. To assign a remote transaction as local, the associated APPLCTN macro must be defined as local. This means that no SYSID= parameter can be specified for the associated APPLCTN macro.

Restriction: A MODBLKS online change is rejected if you attempt to add the SYSID parameter when a change to any other parameter specified on the TRANSACT macro is also requested.

TRANSTAT=

Specifies whether transaction level statistics are logged. If you specify Y, transaction-level statistics are written to the log in an X'56FA' log record.

N

Transaction-level statistics are not logged.

Y

Transaction-level statistics are logged.

The TRANSTAT keyword is optional. If a value is not specified for the TRANSTAT keyword, and the default descriptor is the IMS-defined descriptor DFSDSTR1, the value in the DFSDFxxx PROCLIB member TRANSTAT parameter that was set at IMS cold start is used. Changing the DFSDFxxx TRANSTAT value across a restart does not affect the default descriptor TRANSTAT value. Use the TRANSTAT keyword on the CREATE TRAN or CREATE TRANDESC command to override the system default when creating a transaction or transaction descriptor.

WFI=

The positional parameter WFI specifies that this is a wait-for-input transaction. A message processing or batch processing application program that processes WFI transactions is scheduled and invoked normally. If the transaction to be processed is defined as WFI, the program is allowed to remain in main storage after it has processed the available input messages. The QC status code (no more messages) is returned to the program if any of the following are true:

• The PROCLIM count is reached.
• A command is entered to change the status of the scheduled transaction, database, program, or class.
• The /DBR, /DBD, or /STA commands that relate to the databases used by the transaction are entered.
• IMS is terminated with a checkpoint shutdown.

MODE=SNGL is forced when WFI is specified.