Retrieve Commitment Information (QTNRCMTI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Error code | I/0 | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Commitment Information (QTNRCMTI) API allows you to determine if commitment control is active within the activation group for the program performing the retrieve request. Other information that can be retrieved includes:
- Default lock level and default journal name and library
- Commitment definition scope
- Activation group commitment definition status
- Commitment options
- Logical unit of work identifier
Information about commitment definitions that are started by the system for system use only is not available through this API.
Any call to this API will also refresh cached commitment control settings for the current job. The following settings are cached:
- The COMMITMENT_CONTROL_LOCK_LIMIT setting in the QAQQINI query options file to control maximum number of record locks.
- The QIBM_TN_COMMIT_DURABLE environment variable setting to control soft commit.
- The QTN_JRNSAVPT_* environment variable settings to control whether journal entries are sent for savepoint operations.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that is to receive the information requested. You can specify the size of the area smaller than the format requested as long as you specify the receiver variable length parameter correctly. As a result, the API returns only the data the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. The length must be at least 8 bytes. If the variable is not long enough to hold the information, the data is truncated. If the length is larger than the size of the receiver variable, the results are not predictable.
- Format name
- INPUT; CHAR(8)
The format name CMTI0100 is the only valid format name used by this API. For more information, see CMTI0100 Format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
CMTI0100 Format
The structure of the information returned is determined by the specified
format name. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(1) | Commitment definition status |
| 9 | 9 | CHAR(10) | Commitment definition default lock level |
| 19 | 13 | CHAR(1) | Commitment definition scope |
| 20 | 14 | CHAR(1) | Commitment definition status for the activation group |
| 21 | 15 | CHAR(1) | Wait for outcome commitment option |
| 22 | 16 | CHAR(1) | Action if problems commitment option |
| 23 | 17 | CHAR(1) | Vote read-only permitted commitment option |
| 24 | 18 | CHAR(1) | Action if ENDJOB commitment option |
| 25 | 19 | CHAR(10) | Default journal name |
| 35 | 23 | CHAR(10) | Default journal library name |
| 45 | 2D | CHAR(39) | Logical unit of work identifier |
| 84 | 54 | CHAR(1) | Last agent permitted commitment option |
| 85 | 55 | CHAR(1) | OK to leave out commitment option |
| 86 | 56 | CHAR(1) | Accept vote reliable commitment option |
Field Descriptions
For more detailed descriptions of these fields and their values, see Commitment Options Format in the Change Commitment Options (QTNCHGCO) API.
Accept vote reliable commitment option. The current value of this commitment option.
The possible values are:
| Y | The system accepts the vote reliable indicator if it is returned from its agents during the prepare wave of a commit operation. Control is returned to the application before the committed wave is completed for agents that send the vote reliable indicator if this system accepts it. If heuristic damage is encountered during the committed wave at any agents that voted reliable, it is not reported to the application. |
| N | The system does not accept the vote reliable indicator. Control is returned to the application after the committed wave is completed for all agents. If heuristic damage is encountered during the committed wave, it is reported to the application as an escape message. |
Action if ENDJOB commitment option. The current value of this commitment option.
The possible values are:
| W | The system waits to allow the normal processing of the logical unit of work to complete. |
| R | Local resources whose status is in doubt are rolled back in the event of an ENDJOB. |
| C | Local resources whose status is in doubt are committed in the event of an ENDJOB. |
Action if problems commitment option. The current value of this commitment option.
The possible values are:
| R | If a problem is detected and the local resources have not been committed or rolled back, the local resources will be rolled back. |
| C | If a problem is detected and the local resources have not been committed or rolled back, the local resources will be committed. |
Bytes available. The length in bytes of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length in bytes of all data actually returned.
Commitment-definition default lock level. The default lock level at the start of commitment control for the commitment definition. This is the level of record locking that applies to records in all commitment resources under commitment control for the commitment definition. The level of record locking is this value unless it is overridden when the file is opened. You cannot override this value; however, the system can override for files opened for system functions.
The possible values are:
| blank | Blanks are returned when I is returned for commitment definition status. |
| *ALL | Changed and retrieved records are protected from changes by other jobs running at the same time. |
| *CHG | Changed records are protected from changes by other jobs running at the same time. |
| *CS | Changed and retrieved records are protected from changes by other jobs running at the same time. Retrieved records are protected until they are released or until a different record is retrieved. |
Commitment definition scope. The scope for the commitment definition currently active within the activation group for the program performing the retrieve request.
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:
| I | Commitment control is not active at either the activation group level or the job level for the program making the retrieve request. |
| A | The commitment definition is active within the activation group for the program performing the retrieve request. No local, remote, or API commitment resource is associated with the commitment definition. |
| 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.
|
|
| R | The commitment definition is active on one or more remote systems within the activation group for the program performing the retrieve request. |
An R 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. |
| If both L and R could be returned, a B will be returned. |
Commitment definition status for the activation group. The status of the commitment definition currently active for the activation group for the program performing the retrieve request, but specifically regarding any commitment resource changes made by programs running within the activation group.
The possible values are:
| I | Commitment control is not active at the activation group level or the job level for the program making the retrieve request. The overall status for the job-level commitment definition is also not active. |
| A | The commitment definition is currently being used by one or more programs running within this activation group. Local, remote or API commitment resources may have been placed under commitment control to the commitment definition by a program running within the activation group. The overall status for the commitment definition is either active (A), active on the local system (L), active on a remote system (R), or active on both the local and one or more remote systems (B). |
| N | The job-level commitment definition is active but is not in use by any program running within this activation group. The overall status for the commitment definition is either active (A), active on the local system (L), active on a remote system (R), or active on both the local and one or more remote systems (B). It is possible to start the activation-group-level commitment definition for programs running within this activation group. |
Default journal name. The journal name specified for the default journal when this commitment definition was started. If no default journal was specified, blanks are returned.
Default journal library name. The journal library name specified for the default journal when this commitment definition was started. If no default journal was specified, blanks are returned.
Last agent permitted commitment option. The current value of this commitment option.
The possible values are:
| S | The system is allowed to select a last agent. |
| N | The system is not allowed to select a last agent. |
Logical unit of work identifier. The identifier for the logical unit of work currently associated with this commitment definition.
Table 1. 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 |
OK to leave out commitment option. The current value of this commitment option.
The possible values are:
| Y | If this location does not initiate the commit operation, it may be left out of subsequent logical units of work. Control is not returned to the application until a data flow is received from the initiator. |
| N | This location may not be left out of subsequent logical units of work. Control is returned to the application immediately after the commit operation completes. |
Vote read-only permitted commitment option. The current value of this commitment option.
The possible values are:
| N | This location is not allowed to vote read-only in response to a prepare request from a remote location. |
| Y | This location is allowed to vote read-only in response to a prepare request from a remote location. Control will not be returned to the application until data is sent from the remote location that sent the prepare request. |
Wait for outcome commitment option. The current value of this commitment option.
The possible values are:
| Y | If a remote resource failure occurs during a commit or rollback operation, the system will not return from the operation until resynchronization is complete. |
| L | Value L has the same effect as value Y when this location is the initiator of the commit or rollback operation. When this location is not the initiator and the initiator supports the presumed abort protocol, the Wait for outcome value is inherited from the initiator. When this location is not the initiator and the initiator does not support the presumed abort protocol, value L has the same effect as value Y. |
| N | If a remote resource failure occurs during a commit or rollback operation, the system will attempt to resynchronize with the failed resource once. If the one attempt fails, resynchronization will then be done in a system job and control is returned to the application. |
| U | Value U has the same effect as value N when this location is the initiator of the commit or rollback operation. When this location is not the initiator and the initiator supports the presumed abort protocol, the Wait for outcome value is inherited from the initiator. When this location is not the initiator and the initiator does not support the presumed abort protocol, value U has the same effect as value N. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2
[ Back to top | Journal and Commit APIs | APIs by category ]