Working with application programs

RRS provides an application programming interface (API) consisting of two callable services:

Application_Commit_UR
Application_Backout_UR

These callable services are described in z/OS MVS Programming: Callable Services for High-Level Languages, including a description of the return codes intended for the application programmer. To provide additional information a system programmer or data base administrator might need to help the application programmer, the following table explains conditions that cause RRS to issue each return code.

Table 1. Application program conditions that cause RRS to issue return codes
Return Code in: Hexadecimal Decimal Equate Symbol	Conditions
0 0 RR_OK	One of the following: No resource manager expressed interest in the UR. The collective vote from the PREPARE exit routines is FORGET. The collective vote from the PREPARE exit routines is COMMIT. No COMMIT exit routine returned ATRX_HM, ATRX_HR, or ATRX_OK_OUTCOME_PENDING. No resource manager became unregistered or unset with an incomplete protected interest in the UR. The return code from the ONLY_AGENT exit routine, if invoked, is ATRX_OK.
65 101 RR_COMMITTED_OUTCOME_PENDING	One of the following: The collective vote from the PREPARE exit routines is COMMIT. No COMMIT exit routine returned ATRX_HM or ATRX_HR. However, at least one COMMIT exit routine returned ATRX_OK_OUTCOME_PENDING or a resource manager became unregistered or unset with an incomplete protected interest in the UR. The return code from the ONLY_AGENT exit routine, if invoked, is ATRX_OK_OUTCOME_PENDING.
66 102 RR_COMMITTED_OUTCOME_ MIXED	The collective vote from the PREPARE exit routines is COMMIT. However, one of the following is true: At least one COMMIT exit routine set a heuristic mix (HM) or heuristic reset (HR) return code. The resource manager called Set_Side_Information and set heuristic mix (HM). A DISTRIBUTED_SYNCPOINT exit routine set a heuristic mix (HM) return code.
C8 200 RR_PROGRAM_STATE_CHECK	A STATE_CHECK exit routine returned an ATRX_STATE_INCORRECT code. None of the STATE_CHECK exit routines returned an ATRX_REDRIVE code.
12C 300 RR_BACKED_OUT	One of the following: The collective vote from the PREPARE exit routines is BACKOUT. No BACKOUT exit routine returned ATRX_HM, ATRX_HC, or ATRX_OK_OUTCOME_PENDING. No resource manager became unregistered or unset with an incomplete protected interest in the UR. The return code from the ONLY_AGENT exit routine, if invoked, is ATRX_BACKOUT.
12D 301 RR_BACKED_OUT_OUTCOME_ PENDING	One of the following: The collective vote from the PREPARE exit routines is BACKOUT. No BACKOUT exit routine returned ATRX_HM or ATRX_HC. However, at least one BACKOUT exit routine returned ATRX_OK_OUTCOME_PENDING or a resource manager became unregistered or unset with an incomplete protected interest in the UR. The return code from the ONLY_AGENT exit routine, if invoked, is ATRX_BACKOUT_OUTCOME_PENDING.
12E 302 RR_BACKED_OUT_OUTCOME_ MIXED	One of the following: The collective vote from the PREPARE exit routines is HM. The collective vote from the PREPARE exit routines is BACKOUT. At least one BACKOUT exit routine returned ATRX_HM or ATRX_HC. The return code from the ONLY_AGENT exit routine, if invoked, is ATRX_HM. The resource manager called Set_Side_Information and set heuristic mix (HM). A DISTRIBUTED_SYNCPOINT exit routine set a heuristic mix (HM) return code.
Note: In COBOL, the equate symbols are truncated at 30 characters. In PL/I, the equate symbols are truncated at 31 characters.

During syncpoint operations, RRS default actions are to commit on normal context termination and backout on abnormal context termination.

If RRS fails during a syncpoint operation, the application terminates abnormally. If RRS fails before the application issues a commit or backout, RRS ensures that the application will receive an OUTCOME_PENDING return code for each incomplete UR. However, for an in-doubt UR, RRS does not issue a return code. Later, if RRS restarts without a system reIPL and the application is still active when the In-doubt UR is resolved, RRS issues a return code to the application at that time.

When an application ends abnormally during syncpoint processing, and the ABEND is caused by an outside source, such as the CANCEL command, the condition is called an asynchronous ABEND. The application needs to consider the following points related to an asynchronous ABEND:

If the application encounters an asynchronous ABEND during processing of a backout request, the application can, on restart, retry the backout request.
If the application encounters an asynchronous ABEND during processing of a commit request, the application receives, on restart, no indication of the outcome for the UR. To continue processing, the application should retry the commit request that failed rather than trying to back out the UR. Retrying the commit request can cause any of the following:
- RRS might commit the original UR.
- RRS might commit an empty UR, which is a new UR with no changed resources.
- An X'5C4' abend might occur.
If the attempt to retry the commit request succeeds (the service return code is ATR_OK), the application cannot assume that the original commit request succeeded. The outcome of the original request is unknown. All the application can assume from the ATR_OK return code is that the context and the current UR are consistent and that normal syncpoint operations can continue.
If a resource manager restarts, it can obtain its failed protected interests unless the syncpoints completed successfully under the RRS server task.