APPLCTN macro

The APPLCTN macro allows you to define the program resource requirements for application programs that run under the control of the IMS™ DB/DC environment, and for application programs that access databases through DBCTL.

An APPLCTN macro combined with one or more TRANSACT macros defines the scheduling and resource requirements for an application program. Using the APPLCTN macro, you only describe programs that operate in message processing regions, Fast Path message-driven program regions, batch message processing regions, or CCTL threads. You do use the APPLCTN macro to describe application programs that operate in batch processing regions.

Requirement: When you define programs or transactions (using the APPLCTN and TRANSACT macros) to an IMSplex using shared queues, you must ensure that the programs and transactions are defined with the same attributes on all IMS systems in the IMSplex. If the attributes are defined differently on different IMS systems in the IMSplex, results can be unpredictable. For example, a transaction defined as conversational on one IMS and non-conversational on another IMS causes unpredictable results when messages for that transaction are put on the shared queues.

The APPLCTN macro is optional in DBCTL, DB/DC, and DCCTL environments. If you do not include this macro during stage 1 system definition, no warning is issued, and it is assumed that you define your application programs dynamically using CREATE PGM and UPDATE PGM commands.

This topic includes the following information:

Dynamic definition
Syntax
Positional parameters
Keyword Parameters

Dynamic definition

To define or change program resource requirements for application programs dynamically, you can use the CREATE PGM command and the UPDATE PGM type-2 command. The following table compares the APPLCTN macro keywords and the equivalent CREATE and UPDATE command keywords used for dynamic definition. Default values are shown in bold.

Table 1. APPLCTN macro keywords and the equivalent CREATE and UPDATE command keywords used in dynamic definition
APPLCTN macro keyword	CREATE \| UPDATE PGM keyword equivalent	Usage comments
PSB=name	NAME(name)
RESIDENT \| DOPT	RESIDENT(N \| Y) DOPT(N \| Y)
FPATH=(NO \| YES \| size)	FP(N \| E)	The size variable is not supported on the CREATE PGM and UPDATE PGM commands. Use the keyword variable EMHBSZ(size) on the CREATE TRAN command instead.
GPSB=name	NAME(name) GPSB(N \| Y)
LANG=(ASSEM \| COBOL \| PL/I \| JAVA \| PASCAL)	LANG(ASSEM \| COBOL \| PL/I \| JAVA \| PASCAL)
PGMTYPE=(TP \| BATCH, OVLY, 1 \| class)	BMPTYPE(Y \| N)	The class variable is used on the CREATE TRAN and UPDATE TRAN commands.
SCHDTYPE=SERIAL \| PARALLEL	SCHDTYPE(SERIAL \| PARALLEL)	SERIAL is the default on the APPLCTN macro. PARALLEL is the default on the CREATE and UPDATE commands.
SYSID=(remote system ID, local system ID)		The SYSID keyword is not supported on the CREATE PGM or UPDATE PGM command. Use the keyword variables SIDL(localsysid), SIDR(remotesysid), or MSNAME(msname) on the CREATE TRAN and UPDATE TRAN commands instead.
TRANSTAT=N \| Y	TRANSTAT(N \| Y)	The TRANSTAT keyword is optional. If a value is not specified for the TRANSTAT keyword, the system default is used.

Syntax


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

>--+-,GPSB=name-+-------------------+------------------------+-->
   |            |        .-ASSEM--. |                        |   
   |            '-,LANG=-+--------+-'                        |   
   |                     +-COBOL--+                          |   
   |                     +-JAVA---+                          |   
   |                     +-PL/I---+                          |   
   |                     '-PASCAL-'                          |   
   '-,PSB=name-+-------------------------------------------+-'   
               '-,SYSID=(remote system id,local system id)-'     

>--+-------------------------------------------------+---------->
   |             .-TP----.                           |   
   '-,PGMTYPE=-(-+-------+-+-------+-+-----------+-)-'   
                 '-BATCH-' '-,OVLY-' | .-,1----. |       
                                     '-+-------+-'       
                                       +-,-----+         
                                       '-class-'         

>--+------------------------+--+------------------+------------><
   |           .-SERIAL---. |  |            .-N-. |   
   '-,SCHDTYP=-+----------+-'  '-,TRANSTAT=-+---+-'   
               '-PARALLEL-'                 '-Y-'

Positional parameters

The APPLCTN macro includes two positional parameters, RESIDENT and DOPT, which are mutually exclusive.

RESIDENT

Specifies that the PSB associated with this application program is to be made resident during system initialization.

DOPT

Specifies that the PSB associated with this application program is to be located dynamically.

If you specify DOPT, you cannot specify SCHDTYP=PARALLEL. In addition, when the IMS control region executes:

Initialization does not perform a BLDL on the PSB associated with this application program. Thus the PSB does not need to be in any data set defined by the ACBLIB DD statement until it is required to process a transaction. However, this is not true of the DBDs that the PSB might reference. All DBDs that are to be used online must be available during initialization in a data set defined by the ACBLIB DD statement. PSBs referencing DBDs that are missing during initialization are not scheduled.
Each time the program that is associated with this PSB is scheduled, a BLDL is performed, and the latest copy of the PSB is located. A BLDL is not performed for associated DBDs, so the DBD cannot be modified until the system is initialized again or until online change is used.
When the program terminates, the PSB is deleted from the PSB pool as part of the termination process.

Usage information

Neither RESIDENT or DOPT is the default parameter. Rather, if neither RESIDENT or DOPT is selected, IMS system initialization causes a BLDL to be performed on the PSB associated with the application being defined. The PSB is not made resident (that is, loaded from the ACBLIB) until the application is scheduled.

To provide greater flexibility in your control of the library containing the dynamic PSBs, the following restrictions are imposed:

The PSB must reside in a library other than the primary ACBLIB and must be concatenated to it
The concatenated library containing the PSB must be in ACBLIB format.
The IMS.PSBLIB data set cannot be used.

When a dynamic PSB is scheduled, if the PSB resides in the first concatenated ACBLIB data set of the IMSACB DD statement, IMS stops the PSB and sends an error message to the master terminal. The PSB is not scheduled. If the dynamic PSB is added to the concatenation of the IMS.ACBLIB, causing the data set to be expanded to a secondary extent, that PSB is not available to the online system until the ACBLIB is closed and reopened by IMS.

For MSC remote applications, the APPLCTN macro provides documentation and a reference for its transactions. It does not generate a control block. The PSB need not be generated in systems where it is used as a remote reference. The PSB name is defined here for documentation purposes.

To dynamically reassign a transaction from remote to local processing, a control block must be present in the local system.

Thus, if dynamic reassignment is desired, a transaction must be defined as local. That is, it must be under a local application having the same PSB name as the remote application (using the APPLCTN macro without a SYSID parameter). If dynamic reassignment is not desired, local definition is unnecessary.

Online changes to both the RESIDENT and DOPT options can be made using a MODBLKS system definition. However, PSBs associated with new application programs defined as RESIDENT (that is, changed from NONRESIDENT or DOPT to RESIDENT) during a MODBLKS system definition are not made resident until the next restart of IMS. Until that time, they are to be treated as nonresident. Online changes made to already-resident PSBs (using an ACBGEN) cause the PSB to be treated as nonresident until the next IMS restart.

MPPs scheduled against dynamic PSBs are not allowed to go through the quick reschedule process or become pseudo WFIs.

Requirement: If, after IMS initialization, an ACB that was originally generated as LANG=non-Java and DOPT, is changed to LANG=JAVA and DOPT (and IMS is not restarted), you must ensure that both of the following regions are available the first time IMS tries to schedule the affected transaction:

An MPP region that has the same class as the application
A JMP region that has the same class as the application

The reverse situation is also true. If, after IMS initialization, an ACB that was originally generated as LANG=JAVA and DOPT, is changed to LANG=non-Java and DOPT (and IMS is not restarted), you must ensure both of the following regions are available the first time IMS tries to schedule the affected transaction:

A JMP region that has the same class as the application
An MPP region that has the same class as the application

Keyword Parameters

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

FPATH=

Specifies whether (YES) or not (NO) this is a Fast Path-exclusive application program. 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. FPATH=YES implicitly defines a wait-for-input (WFI) application program. The PGMTYPE= parameters that define the overlay structure and class are invalid if FPATH=YES is specified. The SYSID= parameter is also invalid if FPATH is specified.

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

Fast Path-potential transactions must be able to run under two applications. One of these applications must be defined with FPATH=YES; the other with FPATH=NO. The application with FPATH=YES must also be defined with a routing code that can be assigned by the user Input Edit/Routing exit routine. This routing code can have the same name as the Fast Path-potential transaction.

FPATH=NO must be specified if specifying LANG=JAVA.

When Fast Path is included during system definition, the FPBUF parameter on the TERMINAL macro statement is ignored, except to determine the default EMH buffer size. Fast Path buffers are provided by the EMHB pool, which expands and contracts dynamically depending on the number of ETO terminals concurrently entering Fast Path transactions.

GPSB=

Causes the scheduling process of all environments to generate a PSB containing an I/O PCB and an alternate modifiable PCB.

With the GPSB= keyword, you do not need to perform the PSBGEN and ACBGEN, thus eliminating I/O to the ACBLIB.

The name is 8 characters in length with blank spaces included.

GPSB= generates an I/O PCB named IOPCB (with 3 blank spaces on the right). The modifiable, alternate PCB is named TPPCB1 (with 2 blank spaces on the right). With an alternate modifiable PCB, an application can use the CHNG call to change the output destination and send output to a destination other than the input destination.

You can add the GPSB option to an existing application with a MODBLKS online change or, if dynamic resource definition is enabled, by issuing the UPDATE PGM command. However, the GPSB option does not take effect unless the ACBLIB is also changed with online change.

To add a new application with the GPSB option, perform a MODBLKS system definition or, if dynamic resource definition is enabled, issue the CREATE PGM command.

If LANG=JAVA is specified and the Java™ application is a message processing program, the name specified on GPSB= is the name of the Java application class.

LANG=

Defines the language interface of the application program. LANG= is used only with GPSB=. You can use the following values with the LANG= keyword:

ASSEM
COBOL
JAVA
PL/I
PASCAL

ASSEM is the default value.

Requirements:

If LANG=JAVA is specified, then FPATH=NO must also be specified.
If, after IMS initialization, an ACB that was originally generated as LANG=non-Java and DOPT, is changed to LANG=JAVA and DOPT (and IMS is not restarted), you must ensure that both of the following regions are available the first time IMS tries to schedule the affected transaction:
- An MPP region that has the same class as the application
- A JMP region that has the same class as the application
The reverse situation is also true. If, after IMS initialization, an ACB that was originally generated as LANG=JAVA and DOPT, is changed to LANG=non-Java and DOPT (and IMS is not restarted), you must ensure both of the following regions are available the first time IMS tries to schedule the affected transaction:
- A JMP region that has the same class as the application
- An MPP region that has the same class as the application

PGMTYPE=

Specifies whether the program executes in a BMP-type region or not. A BMP-type region includes BMP and JBP regions. The following PSBs can be defined with either BATCH or TP:

PSBs scheduled by Db2 for z/OS® stored procedures.
PSBs scheduled by programs running under WebSphere® Application Server for z/OS.
PSBs scheduled by programs running under IBM® InfoSphere® Data Replication for IMS for z/OS.
Other users of the ODBA interface.

TP

Specify TP for:

Programs that execute in IMS TM MPP, JMP, and IFP regions.
PSBs scheduled by IBM CICS® Transaction Server for z/OS programs using DBCTL.
Other users of the DRA interface.

This is the default.

BATCH

Specify BATCH for programs that execute in BMP-type regions, such as IMS BMP and JBP regions. Any associated transactions are assigned normal and limit priority values of zero (0).

OVLY

No longer used by IMS but is retained for compatibility. An execution time parameter, OVLA on procedure DFSMPR, is available when starting an MPP to indicate whether the overlay supervisor should be preloaded by IMS.

If a program is changed from batch to online using the online change facility, you must enter the /ASSIGN command to assign nonzero current, limit, and normal priorities (CPRI, NPRI, and LPRI keywords) to the transactions using that program. This is because the online change facility does not alter attributes that are changeable through the /ASSIGN command. Regardless of whether you specify new values for the transaction in the MODBLKS system definition, they are ignored during /MODIFY processing.

If FPATH=YES is specified:

TP specifies a message-driven Fast Path application program
BATCH cannot be specified. If BATCH is specified, an error message is issued. Fast Path nonmessage-driven application programs are not supported, and should be changed to run as BMPs.
The PGMTYPE= parameters that define the overlay structure and class are not valid.
The SYSID= parameter is not valid.

The third parameter of the PGMTYPE= keyword specifies the class to which the transaction codes specified in the following TRANSACT macro statements are to be assigned. This parameter must be a decimal number from 1 to 999. This value must not exceed the value given (by specification or default) on the MAXCLAS= keyword of the IMSCTRL macro. The default is 1. If the transaction code class is to be specified in the individual TRANSACT macro statements, this parameter need not be coded. If the transaction code class is specified in both the APPLCTN and TRANSACT macro statements, the APPLCTN macro specification is ignored, and the TRANSACT macro specification is used.

If the PGMTYPE= (,,class) parameter is to be changed online, the class value that is specified cannot exceed the definition (by specification or default) on the MAXCLAS= keyword of the IMSCTRL macro in the online system to which this change is to be made.

The numeric class subparameter must not be specified if FPATH=YES is specified.

PSB=

Specifies the name of the PSB associated with this application program definition. Each local PSB name must be unique. A remote and a local application can each be defined as having the same PSB name. This is required in order to dynamically reassign a transaction from remote to local processing. The first character of the PSB name must be a letter. If PGMTYPE=TP, the PSB name must also be the program name.

SYSID=

Specifies in the multiple-IMS system configuration, the system identification (SYSID) of the remote system (that 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 numbers in the range from 1 to 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 SYSID is specified, all other keywords except PSB are ignored.

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 TRANSACT macro statements, the TRANSACT specification is ignored.

The SYSID parameter is independent of the link type (BSC, 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, you should not add SYSID= to an existing APPLCTN macro for a MODBLKS system definition. Doing so causes the local application to be deleted after an online change sequence of commands.

A PSB cannot be initially defined or redefined from remote to local by using the SYSID= parameter on the APPLCTN macro during an online change.

The SYSID keyword parameter is invalid if FPATH=YES is specified.

SCHDTYP=

Specifies whether (PARALLEL) or not (SERIAL) this application program can be scheduled into more than one message region or batch message region simultaneously. The default value is SERIAL.

When the SCHDTYP= parameter is changed by a MODBLKS system definition from serial to parallel or vice versa, and the PSB, defined as resident, is not changed, the PSB is considered non-resident until the next IMS restart.

SCHDTYP=PARALLEL and the positional parameter DOPT are mutually exclusive.

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

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, the system default (N) is used. The system default for the transaction-level statistics parameter is set with the TRANSTAT parameter in the DFSDFxxx PROCLIB member. Use the TRANSTAT keyword on the CREATE PGM or CREATE PGMDESC command to override the system default when creating a program or program descriptor.

APPLCTN macro keyword	CREATE \| UPDATE PGM keyword equivalent	Usage comments
PSB=name	NAME(name)
RESIDENT \| DOPT	RESIDENT(N \| Y) DOPT(N \| Y)
FPATH=(NO \| YES \| size)	FP(N \| E)	The size variable is not supported on the CREATE PGM and UPDATE PGM commands. Use the keyword variable EMHBSZ(size) on the CREATE TRAN command instead.
GPSB=name	NAME(name) GPSB(N \| Y)
LANG=(ASSEM \| COBOL \| PL/I \| JAVA \| PASCAL)	LANG(ASSEM \| COBOL \| PL/I \| JAVA \| PASCAL)
PGMTYPE=(TP \| BATCH, OVLY, 1 \| class)	BMPTYPE(Y \| N)	The class variable is used on the CREATE TRAN and UPDATE TRAN commands.
SCHDTYPE=SERIAL \| PARALLEL	SCHDTYPE(SERIAL \| PARALLEL)	SERIAL is the default on the APPLCTN macro. PARALLEL is the default on the CREATE and UPDATE commands.
SYSID=(remote system ID, local system ID)		The SYSID keyword is not supported on the CREATE PGM or UPDATE PGM command. Use the keyword variables SIDL(localsysid), SIDR(remotesysid), or MSNAME(msname) on the CREATE TRAN and UPDATE TRAN commands instead.
TRANSTAT=N \| Y	TRANSTAT(N \| Y)	The TRANSTAT keyword is optional. If a value is not specified for the TRANSTAT keyword, the system default is used.