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 that was established by a prior SETS or SETU call, or to back out to the prior commit point.

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 that use 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 after the SETS call with the same token. The following figure shows how the SETS and ROLS calls work together.

In addition, to assist the application program in managing other variables that it may want to reestablish after 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 is issued with the same token.

Figure 1. SETS and ROLS calls working together
Timeline showing program execution. A SETS call specifies a token. IMS associates the token with a processing point. A subsequent ROLS call uses the same token to back out database changes

SETS and SETU calls

The SETS call sets up to nine intermediate backout points or cancels all existing backout points. With 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 LLZZuser-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 of the data that is to be returned on the ROLS call, 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. 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 it can match a token that was 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.5 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 an I/O area is not included in the call, all intermediate backout points that were 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 will return an SC status code as a warning that the PSB contains unsupported PCBs and that the function is not applicable to these unsupported PCBs.

Related reading: For status codes that are returned after the SETS call and the explanations of those status codes and the response required, see IMS Version 15.5 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. The ROLS call then 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, issue the ROLS call using the I/O PCB, and specify an I/O area and token in the call. If the token does not match a token that was set by a preceding SETS call, an error status is returned. If the token matches the token of a preceding SETS call, the database updates made since this corresponding SETS call are backed out, and all non-express messages that were inserted since the corresponding SETS are discarded. SETS that are issued as part of processing that was backed out are canceled. The existing database positions for all supported PCBs are reset.

If a ROLS call is in response to a SETU call, and if there are unsupported PCBs (DEDB, MSDB, or GSAM) in the PSB, the position of the PCBs is not affected. The token specified by the ROLS call can be set by either a SETS or SETU call. If no unsupported PCBs exist in the PSB, and if the program has not used an attached subsystem, the function of the ROLS call is the same regardless of whether the token was set by a SETS or SETU call.

If the ROLS call is in response to a SETS call, and if unsupported PCBs exist in the PSB or the program used an attached subsystem when the preceding SETS call was issued, the SETS call is rejected with an SC status code. The subsequent ROLS call is either rejected with an RC status code, indicating unsupported options, or it is rejected with an RA status code, indicating that a matching token that was set by a preceding successful SETS call does not exist.

If the ROLS call is in response to a SETU call, the call is not rejected because of unsupported options. If unsupported PCBs exist in the PSB, this is not reflected with a status code on the ROLS call. If the program is using an attached subsystem, the ROLS call is processed, but an RC status is returned as a warning indicating that if changes were made using the attached subsystem, those changes were not backed out.

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 status codes that are returned after the ROLS call and the explanations of those status codes and the response require, see IMS Version 15.5 Messages and Codes, Volume 4: IMSComponent Codes.