Declaring online application programs

Before application programs can be used in an IMS system, they must be declared. Use the APPLCTN macro, the CREATE PGM command, or the PGMCREAT user exit to specify a unique Program Specification Block (PSB) name, with which the online system identifies an application.

Declaring application program characteristics

Use the APPLCTN macro or the CREATE PGM command to specify characteristics for application programs that run under the control of DB/DC, DBCTL, and DCCTL systems; examples of these characteristics include:

  • The type of application program that is being defined, either batch message or message processing.
  • The transaction class for the messages that the program is to receive.
  • Whether the application program executes exclusively in Fast Path.

Use the Program Creation user exit routine (PGMCREAT) to specify characteristics for application programs that are scheduled for BMP and JBP dependent regions when the dynamic resource definition (DRD) is enabled. The PGMCREAT user exit only supports the creation of non-Fast Path BMP type programs in DB/DB, DBCTL, and DCCTL systems.

The APPLCTN macro requires that you specify whether the program can be concurrently scheduled into more than one message region or batch message region. Parallel scheduling (SCHDTYP=PARALLEL) permits the program to schedule into more than one region; however, this option requires that processing is truly independent. Each schedule requires its own section of any shared pools. Program isolation activity can increase if the processing has the potential to perform updates in the same database record. You cannot control the ultimate processing sequence for transactions of the same type.

Use the GPSB keyword of the APPLCTN macro or the CREATE PGM command, or the PGMCR_PF1_ GPSBY bit of the PGMCREAT user exit to cause the scheduling process of all environments to generate a PSB that contains an I/O PCB and an alternate modifiable PCB. This generated PSB can be used, for example, by an application that makes only SQL calls. PSBGEN and ACB generation are not required when a GPSB is used.

Specifying PSB performance options

The IMS online system uses a Program Specification Block (PSB) name to identify application programs. The message processing program uses this same name for identification. The PSB accesses the message input queue and declares any alternative destinations, other than the input source, for messages sent by the program. The PSB defines a complete list of database access intentions down to the segment level, or to the field within the segment. Before access, the PSB is prepared as a member of IMS.ACBLIB. The online system expects this control block to be predefined.

Use the RESIDENT option of the APPLCTN macro or the CREATE PGM command, or the PGMCR_PF2_ RESIDENTY bit of the PGMCREAT user exit to specify whether the PSB is to be made resident during system initialization. Using the RESIDENT option eliminates I/O to ACBLIB when the PSB is scheduled. No storage fragmentation occurs in the resident PSB space as it does in the PSB pool, so more efficient use of storage is the result.

If the PSB is resident, the PSB is managed as follows:

  • During system initialization, the total space for all resident PSBs is computed. This amount of space is obtained, and all resident PSBs are read from the active Application Control Block Library (ACBLIB) into this space.
  • If parallel scheduling is in effect, when the program is scheduled, the resident PSB is allocated for that scheduling if it is not currently allocated to an executing program. If the resident PSB is being used, the PSB pool is searched for an inactive copy of the PSB. If one is found, that copy is allocated and used. If none is found, space for a copy is obtained in the PSB pool, and the resident PSB is copied into that space. The addresses within the copied PSB are then updated based on its new location, and its status related to the former copy is reset.

    If serial scheduling is in effect, when the program is scheduled, the resident copy of the PSB is allocated for that scheduling. Multiple copies of the PSB are not required; therefore, copies of the PSB are not required in the PSB pool.

    Whether you specify serial or parallel scheduling, the PSB is read only once during initialization.

If the PSB is not resident, the PSB is managed as follows:

  • When the program is scheduled, the PSB pool is searched for an inactive copy of the PSB and, if one is found, it is allocated and used. If none is found, space for a copy is obtained in the PSB pool.

    If an active copy exists in the pool, it is copied, its addresses are updated, and its status is reset to make it available for use. If no active copy exists, the PSB is read from the active ACBLIB.

    When it is necessary to release a PSB in the pool, preference is given to retain only copies of PSBs to minimize ACBLIB I/O.

There is an option to put non-resident ACBs into 64-bit storage. Scheduling with non-resident ACB resources with the 64-bit ACB storage pool works as follows: At the first scheduling of a program, its PSB and any related DMBs are loaded into the 31-bit non-resident pools and are also loaded into the 64-bit ACB storage pool. At subsequent schedulings of this program, ACB members not found in the 31-bit non-resident pools are copied from the 64-bit ACB storage pool to the 31-bit non-resident pools, avoiding an I/O to ACBLIB. If the 64-bit ACB storage pool is full, an LRU algorithm is used to remove old members to make room for new members.

Base your use of the RESIDENT option on the frequency with which the PSB is used. If the frequency would cause at least one copy of the PSB to normally be in the pool even if it were not defined as resident, it should be declared resident. If the PSB is used only occasionally, it should not be declared resident, so that its space in the PSB pool can be released when the PSB is not being used.

Specifying a dynamic PSB

A dynamic (DOPT) PSB is loaded into online storage only when the program that uses it is scheduled in the online system. IMS loads the PSB from either the active ACBLIB data set or, if IMS manages ACBs, the IMS catalog. When the program terminates, the storage for the PSB is released.

To specify the dynamic option for a PSB, use the DOPT parameter on the APPLCTN macro or the CREATE PGM command, or the PGMCR_PF1_ DOPTY bit of the PGMCREAT user exit. DOPT and RESIDENT are mutually exclusive parameters. PGMCR_PF1_ DOPTY and PGMCR_PF2_ RESIDENTY are mutually exclusive parameters.

If you specify the dynamic option, the PSB is managed as follows:

  • The PSB is not initialized at system initialization. The PSB does not need to be in the active ACBLIB or the IMS catalog during system initialization.
  • When the program is scheduled, the PSB is loaded into the PSB pool from either the active ACBLIB data set or the IMS catalog.
  • The space in the PSB pool is released when the program terminates.

You can use the dynamic option in a test configuration. The dynamic option can also provide a PSB to be used with the Online Database Image Copy utility.

Restrictions for dynamic PSBs:

  • A dynamic PSB cannot be made resident.
  • A dynamic PSB cannot use the 64-bit storage pool.
  • A program that uses a dynamic PSB cannot be scheduled in parallel.
  • An MPP that is scheduled against a dynamic PSB cannot go through quick reschedule. Quick reschedule allows application programs to process more than the processing limit of messages for each physical schedule.
  • An MPP that is scheduled against a dynamic PSB cannot become a pseudo WFI (pseudo wait-for-input). The pseudo WFI option allows an MPP region to remain scheduled until another input message appears.

All databases that are referenced by the dynamic PSB must be defined to the system and their DBDs must be present in the set of active ACBs that are used by the system. If the system uses ACB libraries, the DBDs must be in the ACBLIB data set either at system initialization or after the last online change was performed. If the IMS systems manages the ACBs for you, the active DBDs must be in the IMS catalog either at system initialization or after the last IMPORT DEFN SOURCE(CATALOG) command was issued. This is because a corresponding dynamic option does not exist for DMBs, even though the PSB is dynamic.

If the IMS system uses ACB libraries, the current ACBLIB data set must consist of two or more concatenated data sets, and the dynamic PSB must reside in any data set in the concatenation other than the first. The concatenated data sets must be of the same format and contain the output from an ACB generation.

If the IMS system uses the IMS catalog to manage ACBs and the dynamic PSBs are generated by the PSB and ACB generation utilities, you add the PSBs to the IMS catalog by using the IMS Catalog Populate utility (DFS3PU00). No concatenation of data sets is required. If the dynamic PSBs are defined by using DDL statements, the PSBs are added to the IMS catalog automatically when IMS processes the DDL.

Declaring Batch Message Processing programs

Use the PGMTYPE parameter of the APPLCTN macro, the BMPTYPE parameter of the CREATE PGM command, or the PGMCR_ BMP bit of the PGMCREAT user exit to describe a batch message program in BMP. Include each BMP program as a separate application on its own APPLCTN macro. You declare the BMP program by its use of a PSB, even though the batch JCL allows you to specify a program name that is different from the PSB name.

If a generalized BMP program can execute with different PSBs, you must include APPLCTN macros for all of them. A choice of PSB typically involves several queues that can be processed by the one program. At execution, use the IN parameter to specify an input transaction code.