Planning for program recovery in IMS programs

To be prepared for recovery situations for IMS™ programs that access DB2® data, you need to make several design decisions that are specific to IMS programs. These decisions are in addition to the general recommendations that you should follow when designing your application for recovery.

To plan for program recovery in IMS programs:

1. For a program that processes messages as its input, decide whether to specify single-mode or multiple-mode transactions on the TRANSACT statement of the APPLCTN macro for the program.

   Single-mode

   Indicates that a commit point in DB2 occurs each time the program issues a call to retrieve a new message. Specifying single-mode can simplify recovery; if the program abends, you can restart the program from the most recent call for a new message. When IMS restarts the program, the program starts by processing the next message.

   Multiple-mode

   Indicates that a commit point occurs when the program issues a checkpoint call or when it terminates normally. Those two events are the only times during the program that IMS sends the program's output messages to their destinations. Because fewer commit points are processed in multiple-mode programs than in single-mode programs, multiple-mode programs could perform slightly better than single-mode programs. When a multiple-mode program abends, IMS can restart it only from a checkpoint call. Instead of having only the most recent message to reprocess, a program might have several messages to reprocess. The number of messages to process depends on when the program issued the last checkpoint call.

   DB2 does some processing with single- and multiple-mode programs. When a multiple-mode program issues a call to retrieve a new message, DB2 performs an authorization check and closes all open cursors in the program.

2. Decide whether to issue checkpoint calls (CHKP) and if so, how often to issue them. Each call indicates to IMS that the program has reached a sync point and establishes a place in the program from which you can restart the program.
   Consider the following factors when deciding when to use checkpoint calls:

   • How long it takes to back out and recover that unit of work. The program must issue checkpoints frequently enough to make the program easy to back out and recover.
   • How long database resources are locked in DB2 and IMS.
   • For multiple-mode programs: How you want the output messages grouped. Checkpoint calls establish how a multiple-mode program groups its output messages. Programs must issue checkpoints frequently enough to avoid building up too many output messages.
   Restriction: You cannot use SQL COMMIT and ROLLBACK statements in the DB2 DL/I batch support environment, because IMS coordinates the unit of work.
3. Issue CLOSE CURSOR statements before any checkpoint calls or GU calls to the message queue, not after.
4. After any checkpoint calls, set the value of any special registers that were reset if their values are needed after the checkpoint:

   A CHKP call causes IMS to sign on to DB2 again, which resets the special registers that are shown in the following table.

   Table 1. Special registers that are reset by a checkpoint call.

   Special register	Value to which it is reset after a checkpoint call
   CURRENT PACKAGESET	blanks
   CURRENT SERVER	blanks
   CURRENT SQLID	blanks
   CURRENT DEGREE	1

5. After any commit points, reopen the cursors that you want and re-establish positioning
6. Decide whether to specify the WITH HOLD option for any cursors. This option determines whether the program retains the position of the cursor in the DB2 database after you issue IMS CHKP calls. You always lose the program database positioning in DL/I after an IMS CHKP call.
   The program database positioning in DB2 is affected according to the following criteria:

   • If you do not specify the WITH HOLD option for a cursor, you lose the position of that cursor.
   • If you specify the WITH HOLD option for a cursor and the application is message-driven, you lose the position of that cursor.
   • If you specify the WITH HOLD option for a cursor and the application is operating in DL/I batch or DL/I BMP, you retain the position of that cursor.
7. Use IMS rollback calls, ROLL and ROLB, to back out DB2 and DL/I changes to the last commit point. These options have the following differences:

   ROLL

   Specifies that all changes since the last commit point are to be backed out and the program is to be terminated. IMS terminates the program with user abend code U0778 and without a storage dump.

   When you issue a ROLL call, the only option you supply is the call function, ROLL.

   ROLLB

   Specifies that all changes since the last commit point are to be backed out and control is to be returned to the program so that it can continue processing.

   A ROLB call has the following options:

   • The call function, ROLB
   • The name of the I/O PCB

   How ROLL and ROLB calls effect DL/I changes in a batch environment depends on the IMS system log and back out options that are specified, as shown in the following table.

   Table 2. Effects of ROLL and ROLLB calls on DL/I changes in a batch environment

   Options specified			Result
   Rollback call	System log option	Backout option
   ROLL	tape	any	DL/I does not back out updates, and abend U0778 occurs. DB2 backs out updates to the previous checkpoint.
   	disk	BKO=NO
   	disk	BKO=YES	DL/I backs out updates, and abend U0778 occurs. DB2 backs out updates to the previous checkpoint.
   ROLB	tape	any	DL/I does not back out updates, and an AL status code is returned in the PCB. DB2 backs out updates to the previous checkpoint. The DB2 DL/I support causes the application program to abend when ROLB fails.
   	disk	BKO=NO
   	disk	BKO=YES	DL/I backs out database updates, and control is passed back to the application program. DB2 backs out updates to the previous checkpoint. Restriction: You cannot specify the address of an I/O area as one of the options on the call; if you do, your program receives an AD status code. However, you must have an I/O PCB for your program. Specify CMPAT=YES on the CMPAT keyword in the PSBGEN statement for your program's PSB.