Application Program Processing

Online message processing (the work performed by an MPP) can be divided into six phases. Figure 16-1 on page 282 illustrates these phases, and the following list describes the phases.

Figure 16-1. General MPP Structure and Flow

The six phases of the flow of an MPP are:

1. Initialization

   Initialization is the clearing of working storage, which might contain data that is left from processing a message from another terminal.

2. Retrieval of the scratch pad area (SPA) and input message

   The application issues a DL/I message call (GU) to IMS TM to retrieve a message from the message queue. The application retrieves the SPA first if the transaction is conversational.

3. Status code check

   The application checks the status code from IMS TM that indicates whether the message was successfully retrieved or not.

4. Input syntax check

   IMS TM checks the syntax of the input message. All checks which can be done without accessing the database, including a consistency check with the status of the conversation as maintained in the SPA, are performed.

5. Database processing

   Database processing is performed, preferably in one phase, which means that the retrieval of a database segment is immediately followed by its update. An example of database processing in more than one phase is to initially retrieve all the segments that the program requires and then perform a second retrieve and then update.

6. Output processing

   The application builds an output message and sends it (by issuing DL/I message calls) to the originating (or other) logical terminal. The SPA is also inserted in the message queue if the transaction is conversational.

After finishing the processing of one input message, the program goes back to step 1 and requests a new input message. If there are no more input messages, IMS returns a status code indicating that, and then the MPP must return control to IMS.

Role of the PSB

In addition to database PCBs, the program specification block (PSB) for an MPP or a BMP contains one or more PCBs for logical terminal linkage. The first PCB (called the I/O PCB) always identifies the originating logical terminal. The I/O PCB must be referenced in the get unique (GU) and get next message (GN) calls. The I/O PCB must also be used when inserting output messages to that logical terminal. In addition, one or more alternate output PCBs (TP PCBs) can be defined. Their logical terminal destinations can be defined in the PCBs or set dynamically with change destination calls.

DL/I Message Calls

The same DL/I language interface that is used for the access of databases is used to access the message queues.

The principal DL/I message calls are:

GU (get unique)

Used to retrieve the first, or only, segment of the input message.

GN (get next)

Used to retrieve second and subsequent message segments.

ISRT (insert)

Used to insert an output message segment into the output message queue. These output messages are not sent until the MPP terminates or requests another input message by issuing a get unique call.

CHNG (change destination)

Used to set the output destination for subsequent insert calls.

The IMS Java function provides Java methods for the DL/I message calls. Examples are IMSMessageQueuegetNextMessage and IMSMessageQueue.insertMessage.

For a detailed description of the DL/I database calls and guidelines for their use, see Chapter 15, "Application Programming for the IMS Database Manager," on page 241.

Conversational Processing

You can define a transaction code as belonging to a conversational transaction during IMS system definition. If the transaction code is defined as belonging to a conversational transaction, an application program that processes that transaction can interrelate messages from a given terminal. The vehicle to accomplish this is the scratch pad area (SPA). A unique SPA is created for each physical terminal that starts a conversational transaction.

Each time an input message is entered from a physical terminal in conversational mode, its SPA is presented to the application program as the first message segment (the actual input being the second segment). Before terminating or retrieving another message (from another terminal), the program must return the SPA to IMS with a message ISRT call.

The first time a SPA is presented to the application program when a conversational transaction is started from a terminal, IMS formats the SPA with binary zeroes (X'00'). If the program wants to terminate the conversation, it can indicate this by inserting the SPA with a blank transaction code.

Output Message Processing

As soon as an application reaches a synchronization point, its output messages in the message queue become eligible for output processing. A synchronization point is reached whenever the application program terminates or requests a new message from the input queue by issuing a GU call.

In general, output messages are processed by Message Format Service (MFS) before they are transmitted through the telecommunications access method.

Different output queues can exist for a given LTERM, depending on the message origin. They are, in transmission priority:

1. Response messages: messages that are generated as a direct response (same PCB) to an input message from this terminal.

2. Command responses.

3. Alternate output messages: messages generated through an alternate PCB.

Message Switching

A message switch is when a user wishes to send a message to another user. The basic format of a message switch is the destination LTERM name followed by a blank and the message text.

A program-to-program switch or program-to-program message switch is a program that is already executing that requests a new transaction be put on the IMS message queues for standard scheduling and execution.

This new transaction can:

• Continue the processing of the first transaction (which, in this case, has probably terminated) and respond (if required) to the originating terminal, which is probably still waiting for a response.

• Be a second transaction, purely an offshoot from the first, without any relationship or communications with the originating terminal. In this case, the original transaction must respond to the terminal, if required.

Application Program Termination

Application programs can terminate in two ways: normally or abnormally. The following sections describe both.

Normal Termination

Normal termination involves the program returning control to IMS TM when it finishes processing. When your program runs in a BMP or DB batch region, the program can set the return code and pass it to the next step in the job. If your program does not use the return code in this way, set the return code to zero as a programming convention.

Restriction:

MPPs cannot pass return codes.

Abnormal Termination

When a message or batch-message processing application program is abnormally terminated for reasons other than a deadlock resolution, internal commands are issued to prevent rescheduling. These commands are the equivalent of a /STOP command, and they prevent continued use of the program and the transaction code in process at the time of abnormal termination. The master terminal operator can restart either or both stopped resources.

At the time abnormal termination occurs, a message is sent to the master terminal and to the input terminal that identifies the application program, transaction code, and input terminal. The message also contains the system and user completion codes. In addition, the first segment of the input transaction, in process by the application at abnormal termination, is displayed on the master terminal.

The database changes of a failing program are dynamically backed out. Also, its output messages inserted in the message queue since the last synchronization point are cancelled.

Logging and Checkpoint/Restart Processing

To ensure the integrity of its databases and message processing, IMS uses logging and checkpoint/restart processing. In case of a system failure, either software or hardware, IMS can be restarted. This restart includes the repositioning of users' terminals, transactions, and databases.

Logging

During IMS execution, all information necessary to restart the system in the event of hardware or software failure is recorded on an online log data set (OLDS). The following critical system information is recorded on the OLDS:

• The receipt of an input message in the input queue

• The start of an application program

• The receipt of a message by an application program for processing

• Before and after images of database updates by an application program

• The insert of a message into the queue by an application program

• The termination of an application program

• The successful receipt of an output message by the terminal

In addition to this logging, all previous database record unchanged data is written to the log data set. This log information is used only for dynamic backout processing of a failing application program. As soon as the application program reaches a synchronization point, the dynamic log information of this program is discarded.

Related Reading: For further information on IMS logging facilities, see Chapter 22, "IMS Logging," on page 367.

Emergency Restart

In case of failure, IMS is restarted with the log data set that is active at the time of failure. Restart processing backs out the database changes of incomplete MPPs and BMP programs. The output messages that are inserted by these incomplete MPPs are deleted.

After backout, the input messages are re-enqueued, the MPPs restarted, and the pending output messages are retransmitted. If a BMP is active at the time of failure, it must be resubmitted by using a z/OS job. If the BMP uses the restart and checkpoint calls, it must be restarted from its last successful checkpoint. In this way, missing or inconsistent output is avoided.

Program Isolation and Dynamic Logging

When processing DL/I database calls, the IMS program isolation function ensures database integrity.

With program isolation, all activity (database modifications and message creation) of an application program is isolated from any other application programs running in the system until an application program commits, by reaching a synchronization point, the data it has modified or created. This ensures that only committed data can be used by concurrent application programs. A synchronization point is established with a get unique call for a new input message (single mode) or a checkpoint call (BMP programs only), or program normal termination (GOBACK or RETURN). Program normal termination is not always sufficient; for example, Fast Path aborts the last unit of work if the program just returns without a synchronization point. Therefore, a good coding practice is to end the program immediately after a synchronization point.

Program isolation allows two or more application programs to concurrently execute with common data segment types even when the processing intent is segment update, add, or delete. IMS accomplishes this concurrency by using a dynamic enqueue/dequeue routine, which enqueues the affected database elements (segments, pointers, and free space elements) between synchronization points.

At the same time, the dynamic log modules log the prior database record images between those synchronization points. This logging makes it possible to dynamically back out the effects of an application program that terminates abnormally, without affecting the integrity of the databases controlled by IMS. The logging does not affect the activity of other application programs running concurrently in the system.

With program isolation and dynamic backout, it is possible to provide database segment occurrence level control to application programs. A means is provided for resolving possible deadlock situations in a manner transparent to the application program.

The following sequence of events is an example of a deadlock:

1. Program A updates database element X.

2. Program B updates database element Y.

3. Program A requests Y and must wait for the synchronization point of program B.

4. Program B in turn requests X and must wait for the synchronization point of program A.

A deadlock has now occurred: both programs are waiting for each other's synchronization point. The dynamic enqueue/dequeue routines of IMS intercept possible deadlocks during enqueue processing (in the above example, during enqueue processing of event 4).

When a deadlock situation is detected, IMS abnormally terminates (pseudo abends) one of the application programs involved in the deadlock. The activity of the terminated program is dynamically backed out to a previous synchronization point. Its held resources are freed, which allows the other program to process to completion. The transaction that was being processed by the abnormal terminated program is saved. If the application program is an MPP, it is rescheduled. For a BMP region, the job must be restarted. This process is transparent to application programs and terminal operators.

There are two situations where the enqueue/dequeue routines of program isolation are not used in processing a database call:

• If PROCOPT=GO (read only) is specified for the referenced segments of the call.

• If PROCOPT=E (exclusive) is specified for the referenced segments in the call, except in a data sharing environment.

Possible conflicts with exclusive extent are resolved during scheduling time and, as such, cannot occur at call time.

Keep the following considerations in mind when using PROCOPT=GO or PROCOPT=E :

• With the PROCOPT=GO option, a program can retrieve data that has been altered or modified by another program still active in another region, and database changes made by that program are subject to being backed out.

• Exclusive intent might be required for long-running BMP programs that do not issue checkpoint calls. Otherwise, an excessively large enqueue/dequeue table in main storage might result.

• Even when PROCOPT=E is specified, dynamic logging will be done for database changes. The ultimate way to limit the length of the dynamic log chain in a BMP is by using the restart and checkpoint calls. The chain is deleted at each checkpoint call because it constitutes a synchronization point.

• If one MPP and one BMP program are involved in a deadlock situation, the MPP is subject to the abnormal termination, backout, and reschedule process. IMS gives preference to the task that is less easily restarted.

Internal Resource Lock Manager (IRLM)

When an IMS is involved in a data-sharing environment with other IMS systems, IRLM is used instead of program isolation for lock management. See "Internal Resource Lock Manager" on page 43 for further details.