Backing out to an intermediate backout point: SETS/SETU and ROLS

You can use a ROLS call either to back out to an intermediate backout point established by a prior SETS or SETU call or to back out to the prior commit point.

This topic refers only to the form of ROLS that backs out to the intermediate backout point. For information about the other form of ROLS, see 'Backing out to a prior commit point: ROLL, ROLB, and ROLS calls'.

The ROLS call that backs out to an intermediate point backs out only DL/I changes. This version of the ROLS call does not affect CICS® changes using CICS file control or CICS transient data.

The SETS and ROLS calls set intermediate backout points within the call processing of the application program and then backout database changes to any of these points. Up to nine intermediate backout points can be set. The SETS call specifies a token for each point. IMS then associates this token with the current processing point. A subsequent ROLS call, using the same token, backs out all database changes and discards all non-express messages that were performed following the SETS call with the same token. The figure below shows how the SETS and ROLS calls work together.

In addition, to assist the application program in reestablishing other variables following a ROLS call, user data can be included in the I/O area of the SETS call. This data is then returned when the ROLS call with the same token is issued.

Figure 1. SETS and ROLS calls working together
Sequence is Program Starts, SETS token=n, GHU, REPL, ISRT MSG1 segment 1 to I/O PCB, SETS token=b, GHU, DLET, ISRT MSG1 segment 2 to I/O PCB, ROLS token=b. ROLS call backs out program to SETS token=b.

SETS/SETU

The SETS call sets up to nine intermediate backout points or cancels all existing backout points. By using the SETS call, you can back out pieces of work. If the necessary data to complete one piece of work is unavailable, you can complete a different piece of work and then return to the former piece.

To set an intermediate backout point, issue the call using the I/O PCB and include an I/O area and a token. The I/O area has the format LLZZ user-data, where LL is the length of the data in the I/O area including the length of the LLZZ portion. The ZZ field must contain binary zeros. The data in the I/O area is returned to the application program on the related ROLS call. If you do not want to save some data to be returned on the ROLS call, you must set the LL that defines the length of the I/O area to 4.

For PLITDLI, you must define the LL field as a fullword rather than a halfword as it is for the other languages. The content of the LL field for PLITDLI is consistent with the I/O area for other calls using the LLZZ format; that is, the content is the total length of the area including the length of the 4-byte LL field minus 2.

A 4-byte token associated with the current processing point is also required. This token can be a new token for this program execution or match a token issued by a preceding SETS call. If the token is new, no preceding SETS calls are canceled. If the token matches the token of a preceding SETS call, the current SETS call assumes that position. In this case, all SETS calls that were issued subsequent to the SETS call with the matching token are canceled.

The parameters for this form of the SETS call are:

  • The call function SETS
  • The name of the I/O PCB or AIB
  • The name of the I/O area containing the user data
  • The name of an area containing the token

For the SETS call format, see the topic 'SETS/SETU Call' in IMS Version 15.2 Application Programming APIs.

To cancel all previous backout points, the call is issued using the I/O PCB but does not include an I/O area or a token. When no I/O area is included in the call, all intermediate backout points set by prior SETS calls are canceled.

The parameters for this form of the SETS call are:

  • The call function SETS
  • The name of the I/O PCB or AIB

Because it is not possible to back out committed data, commit point processing causes all outstanding SETS to be canceled.

If PCBs for DEDB, MSDB, and GSAM organizations are in the PSB, or if the program accesses an attached subsystem, a partial backout is not possible. In that case, the SETS call is rejected with an SC status code. If the SETU call is used instead, it is not rejected because of unsupported PCBs, but returns an SC status code as a warning that the PSB contains unsupported PCBs and the function is not applicable to these unsupported PCBs.

Related Reading: For the status codes that are returned after the SETS call and the explanation of those status codes and the response required, see IMS Version 15.2 Application Programming APIs.

ROLS

The ROLS call backs out database changes to a processing point set by a previous SETS or SETU call, or to the prior commit point and returns the processed input messages to the message queue.

To back out database changes and message activity that have occurred since a prior SETS call, you issue the ROLS call using the I/O PCB and specifying an I/O area and token in the call. If the token does not match a token set by a preceding SETS call, an error status is returned. If the token does match the token of a preceding SETS call, the database updates made since this corresponding SETS call are backed out, and all non-express messages inserted since the corresponding SETS are discarded. The ROLS call returns blanks if the call is processed, and returns a status code if an error or warning occurs. If you are using SETU with ROLS and have an external subsystem, the ROLS call will not be rejected, but an RC status code will be returned as a warning. All SETS points that were issued as part of the processing that was backed out are then canceled, and the existing database position for all supported PCBs is reset. For the ROLS call format, see the topic "ROLB Call" in IMS Version 15.2 Application Programming APIs.

The parameters for this form of the ROLS call are:

  • The call function ROLS
  • The name of the I/O PCB or AIB
  • The name of the I/O area to receive the user data
  • The name of an area containing the 4-byte token

Related reading: For the status codes that are returned after the ROLS call and the explanations of those status codes and the response required, see IMS Version 15.2 Messages and Codes, Volume 4: IMS Component Codes.