ROLS command

Format

Options

USING PCB(expression)

Specifies the DB PCB you want to use. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number.

TOKEN(token)

A 4-byte token associated with the current processing point. If you specify both TOKEN and AREA, the ROLS command backs out to the SETS or SETU you specified.

AREA(data_area)

The name of the area to be restored to the program when a ROLS command is issued. The first 2 bytes of the data-area field contain the length of the data-area, including the length itself. The second 2 bytes must be set to X'0000'. If you specify both TOKEN and AREA, the ROLS command backs out to the SETS you specified.

The ROLS call has two formats: with TOKEN and AREA (for IOPCB only) and without TOKEN and AREA (for IOPCB or DBPCB).

Usage

Use the SETS and ROLS commands to define multiple points at which to preserve the state of DL/I full-function databases and to return to these points later. (For example, you can use them so your program can handle situations that can occur when PSB scheduling completes without all of the referenced DL/I databases being available.)

Use of the SETS and ROLS commands apply only to DL/I full-function databases. This means that if a logical unit of work (LUW) is updating types of recoverable resources other than full-function databases, for example, VSAM files, the SETS and ROLS requests have no effect on the non-DL/I resources. The backout points are not CICS® commit points; they are intermediate backout points that apply only to DBCTL resources. It is up to you to ensure the consistency of all the resources involved.

You can use the ROLS command to backout to the state all full-function databases were in before either a specific SETS or SETU request or the most recent commit point.

Examples

EXEC DLI ROLS TOKEN(token1) AREA(data_area)

Explanation: In this example (for IOPCB only), backout takes place to the corresponding TOKEN, as specified by a prior SETS call, and control returns to the application.

EXEC DLI ROLS USING PCB(PCB5)

Explanation: In this example, for IOPCB or DBPCB, backout takes place to the prior sync point and the application is pseudoabended with a U3033 status code. Control does not return to the application.

In this example, PCB5 is the number of a DB PCB that has received a 'data unavailable' status code. This command results in the same action that would have occurred had the program not issued an ACCEPT STATUSGROUPA command. (See the topic "Data Availability Enhancements" in IMS Version 15.5 Application Programming.)

EXEC DLI ROLS

Explanation: In this example, for IOPCB or DBPCB, backout takes place to the prior sync point and the application is pseudoabended with a U3033, provided the previous reference to that PCB gave an unavailable status code. Control does not return to the application.

Restrictions

Restrictions for the ROLS command:

• To use this command you must first define an I/O PCB for your program.
• You cannot reestablish position in the midst of nonunique keys or nonkeyed segments.
• You cannot use this command when the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.