ROLS call
The Roll Back to SETS/SETU (ROLS) call returns message queue positions to sync points established by the SETS/ SETU call.
For more information on the ROLS and SETS/SETU calls, see the topic "Backing out to a Prior Commit Point: ROLL, ROLB, and ROLS Calls" in IMS Version 13 Application Programming.
Format
>>-ROLS--+-i/o pcb-+--+----------+--+-------+------------------>< '-aib-----' '-i/o area-' '-token-'
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|---|---|---|---|---|---|
| ROLS | X | X | X | X | X |
Parameters
- i/o pcb
- Specifies the I/O PCB, the first PCB address in the list passed to the program. This parameter is an input and output parameter.
- aib
- Specifies the application interface block (AIB) that is used for
the call. This parameter is an input and output parameter. The following fields must be initialized in the AIB:
- AIBID
- Eye catcher. This 8-byte field must contain DFSAIBbb.
- AIBLEN
- AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
- AIBRSNM1
- Resource name. This 8-byte, left-justified field must contain the PCB name IOPCBbbb.
- AIBOALEN
- I/O area length. This field must contain the length of the I/O area that is specified in the call list.
- i/o area
- Specifies the I/O area. It has the same format as the I/O area supplied on the SETS/SETU call. This parameter is an output parameter.
- token
- Specifies the name of the area in your program that contains a 4-byte identifier. This parameter is an input parameter.
Usage
Issuing a ROLS in a conversational program causes IMS™ TM to back out the messages that the application program has sent. For conversation transactions, this means that if the program issues a ROLS call and then reaches a commit point without sending the required response to the originating terminal, IMS TM terminates the conversation and sends the message DFS2171l NO RESPONSE, CONVERSATION TERMINATED to the originating terminal.
When you issue a ROLS call with a token and the messages to be rolled back include nonexpress messages that are processed by IMS TM, message queue repositioning might occur. The repositioning can include the initial message segment, and the original input transaction can be presented again to the IMS TM application program.
Input and output positioning is determined by the SETS/SETU call in standard and modified DL/I application programs. Input and output positioning does not apply to CPI-C driven application programs.
The application program must notify any remote transaction programs of the ROLS.
On a ROLS without a token, IMS issues the APPC/MVS verb, ATBCMTP TYPE(ABEND), specifying the transaction program instance (TPI). This causes all conversations associated with the application program to be DEALLOCATED TYPE(ABEND_SVC). If the original transaction was entered from an LU 6.2 device and IMS TM received the message from APPC/MVS, a discardable transaction is discarded. Nondiscardable transactions are placed on the suspend queue.
Related reading: For more information on LU 6.2, see IMS Version 13 Communications and Connections.
Restrictions
When ROLS is issued during a conversational application program that includes resources outside of IMS TM (for example, a CPI-C driven application program), only the IMS TM resources are rolled back. The application program notifies the remote transactions of the ROLS call.
The Spool API functions do not restrict the use of the SETS/SETU and ROLS calls because these calls can be used by the application program outside the processing of print data sets. When these commands are issued, the Spool API takes no action because these commands cannot be used for the partial backout of print data sets. No special status codes are returned to the application program to indicate that the SETS/SETU or ROLS call was issued by an application that is using Spool API.
The ROLS call is not valid when the PSB contains a DEDB or MSDB PCB, or when the call is made to a DB2® database.