Commitment Control Exit Program

Required Parameter Group:

1	Commitment control exit program information	Input	Char(80)
2	Status information	Input	Char(*)

Optional Parameter:

Return information

Output

Char(*)

QSYSINC Member Name: ETNCMTRB

Users who add API commitment resources to the commitment definition must supply a commitment control exit program as described in Qualified commitment control exit program name. The commitment control operations call this exit program:

Optionally when the commitment definition associated with this resource is placed in a rollback-required state.
Optionally during the classify phase of commit or rollback processing.
Optionally during the prepare phase of commit processing.
To commit during commit processing.
To roll back during rollback processing.
Optionally to reacquire locks during IPL or ASP device vary on.

The commitment control operations pass specific information to the commitment control exit program. The exit program must be coded to handle this specific information as described in Required Parameter Group.

Authorities and Locks

None.

Required Parameter Group

Commitment control exit program information: INPUT; CHAR(80)
Information associated with the commitment control exit program specified when the API commitment resource was added to the commitment definition. This information is passed to the exit program exactly as it was entered when the API commitment resource was added. The area may contain any data such as pointers or an object name. If pointers are used, each one must start on a 16-byte boundary. A pointer may refer to an area of storage that contains information required by your exit program. A pointer may refer only to an area of storage on an ASP that is available when the exit program is called.
Status information: INPUT; CHAR(*)
Status information from the commitment control operations. Each field of this information has a specific meaning. The fields, their meanings, and size are shown in Status Information Format.

Optional Parameter

Return information

OUTPUT; CHAR(*)

Information returned from the commitment control exit program. Each field of this information has a specific meaning. The fields, their meanings, and size are shown in Return Information Format.

This parameter is not passed to the commitment control exit program if the Add resource options parameter was not coded on the Add Commitment Resource (QTNADDCR) API when the resource was registered.

Status Information Format

The following table shows the offsets, type, and name for the fields passed to the exit program as status information. See Field Descriptions for a description of each of these fields.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Status information length
4	4	CHAR(1)	Action required
5	5	CHAR(1)	Called for IPL recovery or ASP device vary on
6	6	CHAR(4)	Reserved
10	A	CHAR(1)	Process error status
11	B	CHAR(1)	Process end status
12	C	CHAR(1)	Reserved
13	D	CHAR(1)	Commit or rollback qualifier
14	E	CHAR(1)	Commitment definition scope
15	F	CHAR(25)	Reserved
40	28	BINARY(4)	Commit cycle identifier
44	2C	CHAR(10)	Journal name
54	36	CHAR(10)	Journal library name
64	40	CHAR(39)	Logical unit of work identifier
103	67	CHAR(1)	Commitment definition status
104	68	Binary(4)	Active savepoint
108	6C	Binary(4)	Savepoint number
112	70	CHAR(20)	Commit cycle identifier - long
132	84	Char(4)	Reserved
136	88	Char(128)	Savepoint name

Field Descriptions

Action required. The action the commitment control exit program is called to perform. The possible values are:

A	Exit program called as a last agent. The program owns the decision of whether the logical unit of work is committed or rolled back. The program must commit or rollback its resources and inform the system of the decision with the Commit vote field of the Return information parameter.
B	Exit program called to place its resources in a rollback-required state.
C	Exit program called to commit its resources.
E	Exit program called to set a savepoint in its resources.
F	Exit program called to release a savepoint in its resources.
G	Exit program called to rollback its resources to a savepoint.
L	Exit program called to reacquire its locks. This happens when the status of the API commitment resource is found to be in doubt during an IPL or ASP device vary on. The locks should be released when the exit program is called to commit or rollback its resources after the IPL or vary on completes.
P	Exit program called to prepare its resources.
R	Exit program called to rollback its resources.
S	Exit program called to classify its resources prior to a rollback operation.
Y	Exit program called to classify its resources prior to a commit operation.

Note: The commitment control exit program is called for actions A, B, L, P, S, and Y only if it is indicated when the resource was added that calls should be made to do these actions.

Active savepoint. The identifier assigned to the savepoint that was active when the commit, set savepoint, release savepoint, rollback to savepoint or rollback was requested. A value of 1 indicates there were no active savepoints. This identifier may not increment by 1 for consecutive savepoints because of savepoints created internally by the system. This value applies only when the Action required field is C, E, F, G or R.

Called for IPL or ASP device vary on recovery. Whether the exit program was called to perform IPL or ASP device vary on recovery processing for the API commitment resource. The possible values are:

N	Not called to perform IPL or ASP device vary on recovery processing for the API commitment resource.The action required field may have any valid value.
P	Called to perform recovery for the API commitment resource after the IPL or ASP device vary on is completed. The purpose of this call is to commit or rollback resources whose status was found to be in doubt during the IPL or ASP device vary on. These resources were called to reacquire locks during the IPL or ASP device vary on if so indicated when the resource was added. The action required field will be C (exit program called to commit its resources) or R (exit program called to rollback its resources).
Y	Called during IPL recovery processing for the API commitment resource. The action required field will be C (exit program called to commit its resources), L (exit program called to reacquire its locks), or R (exit program called to rollback its resources).

Commit cycle identifier. Commit cycle identifier of the current commit cycle. This value is provided only if a journal name was specified when the API resource associated with the exit program was added. If no journal name was specified this field will be zero.

This commit cycle identifier applies only to the journal specified when the resource was added. If the journal has been placed in STANDBY state, this field will be zero.

This field will be -1 if the value could not fit in the specified Binary(4) field. The complete value will always be provided in the Commit cycle identifier - long field.

Commit cycle identifier - long. The same field as Commit cycle identifier except the information is in a Char(20) field that is treated as Zoned(20,0).

Commit or rollback qualifier. If the commit or rollback operation is being performed on behalf of an explicit request by a program or is being performed implicitly by the system.

E	Explicit commit or rollback (initiated by the user)
I	Implicit commit or rollback (initiated by the system)

This commit or rollback qualifier applies only when the action required is C, E, F, G, P, R, S, or Y. For all other actions, a blank is sent.

Commitment definition scope. The scope for the commitment definition. The possible values are:

A	Activation group level
J	Job level

Commitment definition status. The overall status of the commitment definition currently active for the activation group for the program performing the retrieve request. The scope for this commitment definition is returned in the commitment definition scope field. The possible values are:

The commitment definition is active on the local system within the activation group for the program performing the retrieve request. An L is returned if one or more of the following resources are under commitment control.

Local, open database files
Local, closed database files with pending changes
Resources with object-level changes
Local relational database resources
API commitment resources

The commitment definition is active on both the local and one or more remote systems.

Journal library name. The journal library name specified when the commitment resource was added to the commitment definition. If *CURLIB or *LIBL was specified for the library when the resource was added, the actual library name at the time the resource was added is placed in this field. If no journal was specified when the resource was added, blanks are placed in this field.

Journal name. The journal name specified when the commitment resource was added to the commitment definition. If no journal was specified when the resource was added, a value of *NONE is placed in this field.

Logical unit of work identifier. The identifier for the logical unit of work currently associated with this commitment definition.

Logical Unit of Work Identifier Format
Field	Type	Description
Network ID	CHAR(0-8)	Network identifier
Separator	CHAR(1)	The separator character "."
Local location name	CHAR(0-8)	The name of the local location
Separator	CHAR(3)	The separator characters ".X'"
Instance number	CHAR(12)	The hex value of the instance number converted to decimal
Separator	CHAR(2)	The separator characters "'."
Sequence number	CHAR(5)	The hex value of the sequence number converted to decimal

Process end status. If the exit program was called because of process end, and if so, how the process is ending, or if the exit program was called as the result of an activation group ending. The possible values are:

0	Not during the process or activation group end
1	Normal process end; job ended with a zero completion code
2	Abnormal process end; job ended with a completion code that is not zero
4	Activation group is ending

Process error status. If errors occurred in the commitment control processing for this logical unit of work prior to this call to the exit program. The possible values are:

0	No errors occurred
1	Errors occurred

Reserved. An ignored field.

Savepoint number. The identifier assigned to the savepoint that is being set, released or rolled back. This identifier may not increment by 1 for consecutive savepoints because of savepoints created internally by the system. This value applies only when the Action required field is E, F or G.

Savepoint name. The name that identifies the savepoint that is being set, released or rolled back. This value applies only when the Action required field is E, F or G.

Status information length. The length in bytes of all data passed to the Commitment control exit program.

Return Information Format

The following table shows the offsets, type, and name for the fields returned from the exit program.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	Binary(4)	Return information length
4	4	Char(1)	Commit vote
5	5	Char(1)	Classify result
6	6	Char(1)	Changes ended

Field Descriptions

Changes ended. This field is used when the commitment control exit program is called with the Action required field set to A, C, E, F, G or R. It determines whether the commitment resource should be removed at the end of the commit or rollback operation. The possible values are:

0	The resource should not be removed at the end of the commit or rollback operation.
1	The resource should be unconditionally removed at the end of the commit or rollback operation.
2	The resource should be removed only if the commit operation was successful. If the commit operation is not successful the resource is not removed and the Changes Ended field is set back to 0.

If a valid value is not returned, message CPD835E is issued and the resource is not removed.

Classify result. This field is used when the commitment control exit program is called with the Action required field set to S or Y. The possible values are:

0	The classify was successful.
1	The classify was not successful. The commit or rollback operation is ended and message CPF835F is issued. A recoverable failure should be reported for this resource.

If a valid value is not returned, message CPD835E is issued and the classify is considered unsuccessful.

Commit vote. This field is used when the commitment control exit program is called with the Action required field set to A or P. At this point the exit program has a chance to vote whether the entire logical unit of work should commit or roll back. If the exit program votes to roll back, the logical unit of work will roll back regardless of any other votes.

The exit program can also vote read-only. This tells the system that this resource has had no changes made to it and it does not matter if the logical unit of work commits or rolls back. If this exit program votes read-only, it will not be called to commit or roll back this logical unit of work. The possible values are:

1	The commitment control exit program votes to commit the logical unit of work.
2	The commitment control exit program votes to roll back the logical unit of work.
3	The commitment control exit program votes read-only and does not want a call to commit or roll back this logical unit of work.

If a valid value is not returned, message CPD83DE is issued and the logical unit of work is rolled back.

Return Information Length. The length in bytes of all data returned from the commitment control exit program. This field is used to determine whether a particular return value should be used or not. The only valid value for this field is 7. If the returned length is not 7, message CPD83DE is issued and all the other return fields are considered to be not valid.

Exit Program Locks

Commitment control obtains a shared-no-update (*SHRNUP) lock on the exit program when the commitment resource is added using the Add Commitment Resource (QTNADDCR) API. This lock is maintained until the resource is removed using the Remove Commitment Resource (QTNRMVCR) API. This locking is done to prevent any changes by other processes to the Commitment control exit program. Changes by other processes, such as deletion, modification, or authority changes, are prevented.

Exit Program Coding Guidelines

When coding a commitment control exit program, consider the items in the following lists.

Your exit program must:

Complete its processing within 5 minutes. During process end or IPL, or ASP device vary on recovery processing, the system does not allow a Commitment control exit program to run more than 5 minutes. An exit program will not be allowed to prevent a process from ending or an IPL or ASP device vary on from completing.
Return an exception to a commitment control operation only if there has been a failure in the exit program. If the exit program signals an escape message to commitment control, the system assumes there is a failure. A diagnostic message with a final escape message is returned to the calling program, or a message is sent to the system operator if the error occurs during or after IPL or ASP device vary on processing.
Perform any necessary cleanup of locks acquired by the exit program. This is especially important when the program is called after IPL or ASP device vary on recovery to commit or rollback resources whose statuses were found to be in doubt and were called to reacquire locks during IPL or ASP device vary on recovery.
Be written expecting to be called as part of every commitment control operation that is performed for a commitment definition, including implicit commitment control operations performed by the system at:
- Activation group end
- Job end
- IPL or ASP device vary on time (optionally)
Be threadsafe if the API commitment resource is added in a multithreaded job.

Not rely on the ASP group to be set the same as it was when the API commitment resource was added. The application may set a different ASP group before commit or rollback, or the system may fail in which case the exit program will be called in a system database server job as described in the next section. Also see the Add Commitment Resource (QTNADDCR) API for more ASP group considerations.

Your exit program must not perform any of these operations if the scope for the commitment definition is the job level, or any of these functions from the same activation group if the scope for the commitment definition is the activation group level.

Call any commit or rollback operations such as the CL COMMIT command or SQL COMMIT statement. If it does, message CPF8367 is returned to the exit program.
Call the QTNADDCR, the QTNRMVCR, or the QTNRBRQD API. If it does, message CPF8367 is returned to the exit program.
Open a local database or DDM file member under commitment control. If it does, message CPF432A is returned to the exit program.
Start commitment control. If it does, message CPF8351 is returned to the exit program.
End commitment control. If it does, message CPF8367 is returned to the exit program.
Use any protected conversations. If it does, a return code is returned to the exit program.
Connect to a remote relational database with a program that is running under commitment control. If it does, either a return code or an error message is returned to the exit program.

Your exit program should not attempt any of these functions if the scope for the commitment definition is the job level, or any of these functions from the same activation group if the scope for the commitment definition is the activation group level.

Record-level I/O for a local database or DDM file member opened under commitment control
SQL statements under commitment control

If either of these functions are performed, the results are unpredictable and no error messages are issued.

The following items are good guidelines to follow for any program you write. Your program should:

Handle all potential error conditions (fault tolerant). Perform any necessary cleanup of locks acquired by the exit program.
Prevent the potential for any infinite looping conditions. The system stops the exit program, after 5 minutes, during process end, IPL or ASP device vary on time.
Be relatively short and perform well.
Be callable during IPL or ASP device vary on to reacquire locks and to recover resources.
Notify the application when placing a commitment definition in rollback-required state.
Release all locks before finishing IPL or ASP device vary on recovery.

If your exit program changes any of the required parameter values passed to it, these changes are not preserved for future calls to the exit program.

Process End, Activation Group End, and IPL or ASP Device Vary On Recovery Processing Guidelines

During process end, activation group end, and IPL or ASP device vary on recovery processing, the debug functions are not available to help debug any exit program problems. The following operations may be performed during these processing phases. If any other actions take place, the Commitment control exit program may not run successfully or the results will be unpredictable.

Working with physical files, including creating, changing, opening, closing, clearing, and deleting
Database input and output operations
Working with data areas, including creation, changing, retrieving, and deletion
Working with data queues, including creation and deletion
Working with message queues, including creation, clearing, changing and deletion

Some examples of things your exit program might not be able to do during process end, activation group end, IPL, or ASP device vary on are:

Signal any inquiry messages.
Submit any other jobs.
Use or attempt to start any remote communications activities.
Start any subsystems.
Include a commit cycle identifier if sending journal entries using the Send Journal Entry (QJOSJRNE) API. This restriction applies during IPL only.

When called during IPL or ASP device vary on recovery, or after IPL or ASP device vary on recovery to commit or rollback resources whose status was found to be in doubt during IPL or ASP device vary on recovery, the exit program will be called in a system database server job related to the ASP group associated with the resource. If a journal was specified when the resource was registered with the QTNADDCR API, the journal's ASP group is considered to be the ASP group associated with the resource, regardless of the exit program's location. If no journal was specified, then the exit program's ASP group is considered to be the ASP group associated with the resource. For resources associated with *SYSBAS, the system database server job names start with the characters QDBSRV and end with a number beginning with 02 (for example, QDBSRV02, QDBSRV03, and so forth). For resources associated with an IASP, the job names start with the characters "QDBS" followed by three digits of the ASP device number and end with the character "V" and a number beginning with 02 (for example for ASP device number 34, QDBS034V02, QDBS034V03, and so forth). Debug functions can be used for these jobs by using the Start Service Job (STRSRVJOB) command.

Exit programs for resources associated wtih *SYSBAS must not attempt to access data in an IASP when called during IPL because it is not possible for an IASP to be varied on during the IPL, nor should they attempt to access data in an IASP when called after IPL because the IASP may not be varied on at that time. Exit programs for resources associated with an IASP may access *SYSBAS data during or after a vary on, but beware that there is nothing to prevent a geo-mirrored or switchable IASP from being varied on to a different system in the cluster after a system failure. In that case, any pointers to *SYSBAS data that are contained in the commitment control exit program information parameter will be stale and unusable.

For resources that are associated with a journal, it is recommended that the exit program and the journal be located on the same ASP group. If the exit program is located in *SYSBAS, but the journal is located in a switchable or geo-mirrored IASP, the identical exit program must exist on all systems in the cluster where the IASP may be varied on. If the system fails while such a resource is registered, and the IASP is varied on to a different system after the failure, the exit will be called on the new system. The exit program logic must take this into account. It will not have access to any persistent data from the original system. If no exit with the same qualified name exists on the new system, the call will fail.

Exit program introduced: V2R2. Formerly called Commit and Rollback.

[ Back to top | Journal and Commit APIs | APIs by category ]