Backing out to a prior commit point: ROLL, ROLB, and ROLS

When a program determines that some of its processing is invalid, some calls enable the program to remove the effects of its incorrect processing. These are the Roll Back calls: ROLL, ROLS using a DB PCB (or ROLS without an I/O area or token), and ROLB.

When you issue one of these calls, IMS:

Backs out the database updates that the program has made since the program's most recent commit point.
Cancels the non-express output messages that the program has created since the program's most recent commit point.

The main difference between these calls is that ROLB returns control to the application program after backing out updates and canceling output messages, ROLS does not return control to the application program, and ROLL terminates the program with an abend code of U0778. ROLB can return the first message segment to the program since the most recent commit point, but ROLL and ROLS cannot.

The ROLL and ROLB calls, and the ROLS call without a specified token, are valid when the PSB contains PCBs for GSAM data sets. However, segments inserted in the GSAM data sets since the last commit point are not backed out by these calls. An extended checkpoint-restart can be used to reposition the GSAM data sets when restarting.

You can use a ROLS call either to back out to the prior commit point or to back out to an intermediate backout point that was established by a prior SETS call. This section refers only to the form of the ROLS call that backs out to the prior commit point. For information about the other form of ROLS, see 'Backing out to an intermediate backout point: SETS, SETU, and ROLS'.

The table below summarizes the similarities and the differences between the ROLB, ROLL, and ROLS calls.

Table 1. Comparison of ROLB, ROLL, and ROLS
Actions Taken:	ROLB	ROLL	ROLS
Back out database updates since the last commit point.	X	X	X
Cancel output messages created since the last commit point.	X¹	X¹	X¹
Delete from the queue the message in process. Previous messages (if any) processed since the last commit point are returned to the queue to be reprocessed.		X
Return the first segment of the first input message issued since the most recent commit point.	X²
U3303 abnormal termination. Returns the processed input messages to the message queue.			X³
U0778 abnormal termination. No dump.		X
No abend. Program continues processing.	X

Notes:

ROLB, ROLL, or ROLS calls cancel output messages that are sent with an express PCB unless the program issued a PURG. For example, if the program issues the call sequence that follows, MSG1 would be sent to its destination because PURG tells IMS that MSG1 is complete and the I/O area now contains the first segment of the next message (which in this example is MSG2). MSG2, however, would be canceled.
```
ISRT   EXPRESS PCB, MSG1
PURG   EXPRESS PCB, MSG2
ROLB   I/O PCB
```
Because IMS has the complete message (MSG1) and because an express PCB is being used, the message can be sent before a commit point.
Returned only if you supply the address of an I/O area as one of the call parameters.
The transaction is suspended and requeued for subsequent processing.

ROLL call

A ROLL call backs out the database updates and cancels any non-express output messages the program has created since the last commit point. It also deletes the current input message. Any other input messages that were processed since the last commit point are returned to the queue to be reprocessed. IMS then terminates the program with an abend code U0778. This type of abnormal termination terminates the program without a storage dump.

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

You can use the ROLL call in a batch program. If your system log is on DASD, and if dynamic backout has been specified through the use of the BKO execution parameter, database changes made since the last commit point will be backed out; otherwise they will not. One reason for issuing ROLL in a batch program is for compatibility.

After backout is complete, the original transaction is discarded if it can be, and it is not re-executed. IMS issues the APPC/MVS verb, ATBCMTP TYPE(ABEND), specifying the TPI to notify remote transaction programs. Issuing the APPC/MVS verb causes all active conversations (including any that are spawned by the application program) to be DEALLOCATED TYP(ABEND_SVC).

ROLB call

The advantage of using a ROLB call is that IMS returns control to the program after executing a ROLB call, so the program can continue processing. The parameters for the ROLB call are:

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

The total effect of the ROLB call depends on the type of IMS application program that issued it.

For current IMS application programs:
After IMS backout is complete, the original transaction is represented to the IMS application program. Any resources that cannot be rolled back by IMS are ignored; for example, output that is sent to an express alternate PCB and a PURG call that is issued before the ROLB call.
For modified IMS application programs:
The same consideration for the current IMS application program applies. The application program must notify any spawned conversations that a ROLB was issued.
For CPI-C driven IMS application programs:
Only IMS resources are affected. All database changes are backed out. Any messages that are inserted to non-express alternate PCBs are discarded. Also, any messages that are inserted to express PCBs that have not had a PURG call are discarded. The application program must notify the originating remote program and any spawned conversations that a ROLB call was issued.

MPPs and transaction-oriented BMPs

If the program supplies the address of an I/O area as one of the ROLB parameters, the ROLB call acts as a message retrieval call and returns the first segment of the first input message issued since the most recent commit point. This is true only if the program has issued a GU call to the message queue since the last commit point; it if has not, it was not processing a message when it issued the ROLB call.

If the program issues GN call to the message queue after issuing a ROLB call, IMS returns the next segment of the message that was being processed when the ROLB call was issued. If no more segments exist for that message, IMS returns a QD status code.

If the program issues a GU call to the message queue after the ROLB call, IMS returns the first segment of the next message to the application program. If no more messages exist on the message queue for the program to process, IMS returns a QC status code.

If you include the I/O area parameter, but you have not issued a successful GU call to the message queue since the last commit point, IMS returns a QE status code to your program.

If you do not include the address of an I/O area in the ROLB call, IMS does the same thing for you. If the program has issued a successful GU call in the commit interval and then issues a GN call, IMS returns a QD status code. If the program issues a GU call after the ROLB call, IMS returns the first segment of the next message or a QC status code, if no more messages exist for the program.

If you have not issued a successful GU call since the last commit point, and you do not include an I/O area parameter on the ROLB call, IMS backs out the database updates and cancels the output messages that were created since the last commit point.

Batch programs

If your system log is on DASD, and if dynamic backout has been specified through the use of the BKO execution parameter, you can use the ROLB call in a batch program. The ROLB call does not process messages as it does for MPPs; it backs out the database updates made since the last commit point and returns control to your program. You cannot specify the address of an I/O area as one of the parameters on the call; if you do, an AD status code is returned to your program. You must, however, have an I/O PCB for your program. Specify CMPAT=YES on the CMPAT keyword in the PSBGEN statement for your program's PSB.

ROLS call

You can use the ROLS call in two ways to back out to the prior commit point and return the processed input messages to IMS for later reprocessing:

Have your program issue the ROLS call using the I/O PCB but without an I/O area or token in the call. The parameters for this form of the ROLS call are:
- The call function, ROLS
- The name of the I/O PCB or AIB
Have your program issue the ROLS call using a database PCB that has received one of the data-unavailable status codes. This has the same result as if unavailable data were encountered and the INIT call was not issued. A ROLS call must be the next call for that PCB. Intervening calls using other PCBs are permitted.

On a ROLS call with a TOKEN, message queue repositioning can occur for all non-express messages, including all messages processed by IMS. The processing uses APPC/MVS calls, and includes the initial message segments. The original input transaction can be represented to the IMS application program. Input and output positioning is determined by the SETS call. This positioning applies to current and modified IMS application programs but does not apply to CPI-C driven IMS programs. The IMS application program must notify all remote transaction programs of the ROLS.

On a ROLS call without a TOKEN, IMS issues the APPC/MVS verb, ATBCMTP TYPE(ABEND), specifying the TPI. Issuing this verb causes all conversations associated with the application program to be DEALLOCATED TYPE(ABEND_SVC). If the original transaction is entered from an LU 6.2 device and IMS receives the message from APPC/MVS, a discardable transaction is discarded rather than being placed on the suspend queue like a non-discardable transaction.

The parameters for this form of the ROLS call are:

The call function, ROLS
The name of the DB PCB that received the BA or BB status code

In both of the these parameters, the ROLS call causes a U3303 abnormal termination and does not return control to the application program. IMS keeps the input message for future processing.