| 1 | Commitment control exit program information | Input | Char(80) |
| 2 | Status information | Input | Char(*) |
| 3 | Return information | Output | Char(*) |
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:
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.
None.
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 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.
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.
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 | ||
| 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 |
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:
| L | 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.
|
| B | 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.
The following table shows the offsets, type, and name for the fields returned from the exit program.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 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 |
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.
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.
When coding a commitment control exit program, consider the items in the following lists.
Your exit program must:
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.
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.
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:
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.
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.
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:
When called 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. The job name for these jobs The job name for these jobs on the system ASP start with the characters QDBSRV and end with a number beginning with 02 (for example, QDBSRV02, QDBSRV03, and so forth). On an IASP, the job name for these jobs starts with the characters "QDBS" followed by three digits of the ASP device number and ends 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.
| Top | Journal and Commit APIs | APIs by category |