RSET Roll back transaction

You use the RSET (roll back transaction) call to roll back changes and operations of local transactions. Open database transactions are also rolled back. All output operations since the last local synchronization point are cancelled. Control is returned to the program unit. The program unit is continued after the RSET call. Further KDCS calls and database calls are subsequently possible (except INIT).

You can use the RSET call to react to application errors with specific actions. You can roll back a transaction and at the same time pass control back to the application program.

This approach is useful for errors which are not program errors (e.g. as a response to error codes >= 40Z). You can react specifically in the program unit, e.g. by

• sending a message to the appropriate client or to the administrator (MPUT)

• writing an item of logging information (LPUT)

• sending an output job, e.g. to a printer (FPUT/DPUT)

The RSET call may, for example, also be useful in the event that database accesses yield unexpected return codes (e.g. “data record does not exist”) and UPDATE operations have already been performed.

Setting the 1st parameter (KDCS parameter area)

For the RSET call, you only have to enter the “RSET” operation code in the KCOP field.

Setting the parameters
Field name in the KDCS parameter area	Contents
KCOP	"RSET"

KDCS call
1st parameter	2nd parameter
KDCS parameter area	—

C/C++ macro calls
Macro name	Parameters
KDCS_RSET	()

openUTM return information
Field name in the KB return area	Contents
KCRCCC	Return code
KCRCDC	Internal return code

For the RSET call you make the following entries in the KDCS parameter area:

KCOP

in the KCOP field, the RSET operation code.

openUTM does not evaluate any other operands of the parameter area.

You specify the following for the KDCS call:

1st parameter

The address of the KDCS parameter area.

Macro name

The use of C/C++ calls is described in detail in the section "C/C++ macro interface".

openUTM returns:

KCRCCC

in the KCRCCC field: the KDCS return code.

KCRCDC

in the KCRCDC field: the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).

KDCS return codes in the KCRCCC field for the RSET call

The following codes can be analyzed in the program:

000	Operation carried out

Additional return codes can be found in the dump:

70Z	System cannot perform the operation (generation error or system error), see KCRCDC.
71Z	INIT missing in this program.

Features of the RSET call

• All resources occupied by this transaction up to the RSET call are released.

• All service-specific data is rolled back to the last synchronization point. In this way, the KB program area, all LSSBs and GSSBs and TLS and ULS blocks are again made available with their original contents.

• Data in SPAB and in program-specific working storage areas is not changed.

• An open DB transaction is rolled back.

• Each rollback of a DB transaction has the same effect as an RSET call, and thus implicitly causes the UTM transaction to be rolled back.

• The program unit again regains control following the RSET call and continues the program run with the next statement after the RSET call. It is then possible to issue additional KDCS (except INIT) and DB calls in the program unit.

• After this, it is no longer possible to read a dialog input message which was read prior to the RSET call, but it is possible to read a dialog input message which was not yet read prior to the RSET call.

• Input messages read with FGET or DGET can again be read following an RSET. With DGET messages this is possible only if the maximum number of redeliveries specified at generation has not been reached. For more information refer to the openUTM manual “Generating Applications”, REDELIVERY operand in the MAX control statement.

  If the maximum number of redeliveries has been reached then the message is either deleted or saved in the dead letter queue by UTM (only possible in the case of messages to a TAC queue), see openUTM manual “Generating Applications”, DEAD-LETTER-Q operand in the TAC statement.

Features of the RSET call with distributed processing

The behavior of openUTM following an RSET call in a program unit run belonging to a distributed transaction is governed by the RSET generation parameter of the UTMD statement (see the openUTM manual “Generating Applications”):

• If RSET=LOCAL is generated, then the RSET call has no effect on the distributed transaction.
  Here, inconsistencies may occur in the distributed databases, if some of the local transactions participating in the distributed transactions are continued and others rolled back. With this generation, the global data consistency is no longer guaranteed by the relevant system components, but is the responsibility of the application program units. These must decide the situations in which it is more practical to terminate the distributed transaction and the situations in which it must be rolled back.

• If RSET=GLOBAL is generated, then openUTM forces termination of the program unit run with a PEND variant which causes the distributed transaction to be rolled back (see also the section "PEND Terminate program unit").