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.
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
14 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
14 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
14 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
14 Messages and Codes, Volume 4: IMS Component
Codes.