| 1 | Resource handle | Output | Binary(4) |
| 2 | Resource name | Input | Char(10) |
| 3 | Qualified commitment control exit program name | Input | Char(20) |
| 4 | Commitment control exit program information | Input | Char(80) |
| 5 | IPL and ASP device vary on processing option | Input | Char(1) |
| 6 | Error code | I/O | Char(*) |
| 7 | Add resource options | Input | Char(*) |
| 8 | Current savepoint number | Output | Binary(4) |
The Add Commitment Resource (QTNADDCR) API adds an API commitment resource to a commitment definition. When the resource has been added, the specified exit program is called during commitment control operations performed for the commitment definition until the resource is removed. Once an API commitment resource is added, it must be removed with the Remove Commitment Resource (QTNRMVCR) API before commitment control can be ended for the commitment definition, unless activation-group-level commitment definitions are used. Activation-group-level commitment definitions for nondefault activation groups are automatically ended by the system and any API commitment resources are implicitly removed when the activation group is ended. See Remove Commitment Resource (QTNRMVCR) API for more information about this API.
To have several API commitment resources at once, you must use this API to add each resource, one at a time. This API does not check for duplicate resource names or duplicate commitment control exit programs.
API commitment resources are considered either one-phase or two-phase. One-phase API commitment resources cannot be registered with any remote resource. One-phase resources are called once during both commit and rollback processing. Two-phase resources are optionally called three times for commit processing and twice for rollback processing. Optionally, two-phase resources may also be called to reacquire their locks during IPL and ASP device vary on. IPL and ASP device vary on recovery may need to take place after the IPL or vary on finishes and resources that are not locked may not be able to be recovered. For more information about one-phase and two-phase API commitment resources, see the Journal management topic.
For each API commitment resource that is added, and specified not to be called during both the classify and prepare phases, a single call is made to the associated exit program by commit or rollback processing. For each two-phase resource added and specified to be called during both the classify and prepare phases, the associated exit program is called three times for commit processing and twice for rollback processing. During the first call (or classify call), the exit program should place its conversations in protected states and force any buffered data. During the second call (or prepare call), the exit program must place its resources in a state where they can be committed, rolled back, or recovered from a system failure. The prepare call is made only for commit processing, not rollback processing. During the third call, the exit program is told to commit or roll back its resources.
A journal name can be specified when the API commitment resource is added to associate a journal with the resource. If specified, the journal must not be a remote journal. The resource can use this journal to permanently store information that may be needed to commit, rollback, or reacquire locks on the resource. This journal can be used in a manner similar to the way the database uses journals to keep track of record-level I/O. When the commitment control exit program is called to commit or roll back the resource or to reacquire locks during IPL, the commit cycle identifier of the current logical unit of work is passed to the program. This commit cycle identifier can be used as a starting or ending point when receiving, retrieving, or displaying entries from the journal.
Exit programs are grouped according to what is specified for the journal name in the add resource options. All exit programs that have been associated with the same journal are grouped together and all exit programs that are not associated with a journal are grouped together. During commit processing the exit programs are called in the order within the group in which they were added to their particular commitment definition. During rollback processing the exit programs are called in the reverse order. All calls to API commitment resources are made before record-level I/O operations are processed.
For more information about the exit program and information that is passed to it, see the Commitment Control Exit Program.
You are prevented from adding a commitment resource using this API when:
Note: If remote resources are read-only, the API can be used to register a commitment resource as long as the resource is compatible with remote resources. See the Add resource options parameter for more details.
Note: You can use the Retrieve Commitment Information (QTNRCMTI) API to retrieve information about what type of commitment control resources are currently associated with the currently active commitment definition for the program making the retrieve request.
In addition to the preceding restrictions, you are prevented from adding a one-phase API commitment resource when any remote resources exist for the commitment definition. Adding a resource is also disallowed when incompatible option values are specified.
In all other instances, the API commitment resource is added to the commitment definition.
Once a resource has been added to a commitment definition, the process must not change the authorities to the commitment control exit program or delete the exit program.
An identifier made up of an arbitrary number returned by the API and used to identify the commitment resource for subsequent operations, such as the Remove Commitment Resource (QTNRMVCR) API.
The name that identifies this commitment resource. It is used, for example, in some error messages associated with the commitment control exit programs.
The name of the commitment control exit program to be called from the commitment control operations and the library in which it is located. The exit program must exist when this API is called.
The exit program must reside on the same ASP as the commitment definition to which the API commitment resource is added. If the exit program can be called during ASP device vary on processing, it may also reside on the system ASP.
The first 10 characters of this name contain the program name, and the second 10 characters contain the library name. The special values supported for the library name are *LIBL and *CURLIB.
Note: The special values *LIBL and *CURLIB apply only to the time the resource is added. For example:
The user of this API must supply this exit program. The considerations for coding this exit program, as well as the information that the commitment control operations pass to this exit program, are described in the Commitment Control Exit Program.
Data to be passed directly to the commitment control exit program. This may be any data that is needed by the exit program, such as a reference to an object or area to be used by the exit program. This may be any type of data, including pointers. However, if pointers are used, this field must be on a 16-byte boundary.
Pointers provide better performance than if this parameter were an object name. Resolving to an object on every commit or rollback operation degrades performance. However, pointers to data residing on an ASP may become not usable if the ASP is no longer available.
If the exit program is to be called during IPL or ASP device vary on processing, the information passed-in or pointed-to by this parameter must not be temporary. That is, the information referred to and used by the exit program must persist across an IPL and ASP device vary on.
Whether the commitment control exit program will be called during any commitment control processing that occurs during IPL and/or ASP device vary on recovery processing for the commitment definition.
| N | If the API resource is in the commitment definition when the system ends abnormally, the commitment control exit program is not called during the IPL recovery processing for the commitment definition. |
| Y | If the API resource is in the commitment definition when the system ends abnormally, the commitment control exit program is called during the IPL recovery processing for the commitment definition. |
| V | If the API resource is in the commitment definition when the ASP device ends abnormally, the commitment control exit program is called during the ASP device vary on recovery processing for the commitment definition. |
| B | If the API resource is in the commitment definition when the system or ASP device ends abnormally, the commitment control exit program is called during the IPL and ASP device vary on recovery processing for the commitment definition. |
Note: When called during IPL or ASP device vary on, the exit program runs under the same user profile that originally added the commitment resource.
The order in which commitment definitions are processed during IPL or ASP device vary on recovery processing is not predictable. However, for each particular commitment definition, the commitment control exit programs are grouped according to what was specified for the associated journal name when they were added with the QTNADDCR API. All exit programs that were associated with the same journal are grouped together, and all exit programs that were not associated with a journal are grouped together. If a commit operation is being finished during IPL or ASP device vary on recovery, the programs within each group are called in the order they were added. If a rollback is being performed, the programs are called in reverse order.
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
A structure of input options. See Input Options Structure for the format of the options and a description of the individual options.
When this parameter is specified, the optional parameters will be passed to the commitment control exit program when it is called. See the Commitment Control Exit Program for more information.
If the add resource options parameter is left out, the API commitment resource is assumed to be a one-phase API commitment resource. The other options are ignored and the options are not passed to the exit program.
An identifier of the savepoint assigned to the savepoint name. This identifier may not increment by 1 because of internally created savepoints.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Structure length |
| 4 | 4 | CHAR(20) | Qualified journal name |
| 24 | 18 | CHAR(1) | Resource protocol |
| 25 | 19 | CHAR(1) | Call for classify |
| 26 | 1A | CHAR(1) | Call for prepare |
| 27 | 1B | CHAR(1) | Call for rollback required |
| 28 | 1C | CHAR(1) | Call for reacquiring locks during IPL or ASP device vary on |
| 29 | 1D | CHAR(1) | Last agent |
| 30 | 1E | CHAR(1) | Allow normal save processing |
| 31 | 1F | CHAR(1) | Savepoint compatible |
| 32 | 20 | CHAR(1) | Call for setting a savepoint |
| 33 | 21 | CHAR(1) | Call for rollback to a savepoint |
| 34 | 22 | CHAR(1) | Call for release a savepoint |
Allow normal save processing. Whether the registration of this API commitment resource allows save processing to perform normally.
If multiple API commitment resources are to be registered, they all must specify Y in order to prevent poor performance of save-while-active processing.
Valid values for this option are:
| N | This resource does not allow all save requests to perform
normally.
|
| Y | This resource will allow all save requests to perform normally. |
| Note: If the optional parameter group is not specified, this resource does not allow all save requests to perform normally. |
Call for classify. Whether the commitment control exit program should be called during the classify phase of a commit or rollback. The commitment control exit program is called during the classify phase to use protected conversations and force any buffered data.
Valid values for this option are:
| N | Do not call the commitment control exit program during the classify phase of commit or rollback processing. |
| Y | Call the commitment control exit program during the classify phase of commit or rollback processing. |
| Note: One-phase API commitment resources cannot be called for classify. |
Call for prepare. Whether the commitment control exit program should be called during the prepare phase of a commit. The commitment control exit program is called during the prepare phase of the commit to put its resources in a position to either commit, rollback, or recover from a system failure. The commitment control exit program is also given a chance to vote whether this logical unit of work should commit, rollback, or that the resources associated with this commitment control exit program have not been changed. If the resources have not been changed then the exit program can choose not to be called during the second phase of the commit. This is commonly referred to as voting read-only.
Voting is done by setting flags in the parameter structure which is passed to the commitment control exit program when it is called.
Valid values for this option are:
| N | Do not call the commitment control exit program during the prepare phase of commit processing. Commit processing assumes the vote is to commit the logical unit of work. |
| Y | Call the commitment control exit program during the prepare phase of commit processing. |
Notes:
Call for reacquiring locks during IPL or ASP device vary on. Whether the commitment control exit program should be called during IPL or ASP device vary on if locks need to be reacquired. Under some circumstances, IPL or ASP device vary on recovery cannot be completed for this resource until after the IPL or ASP device vary on is complete. A call can be made to the commitment control exit program so that any locks which were protecting this resource can be reacquired before the IPL or ASP device vary onis complete.
It is the responsibility of the application that added the resource to keep track of which locks need to be reacquired during IPL or ASP device vary on.
Valid values for this option are:
| N | Do not call the commitment control exit program during IPL to reacquire locks. |
| Y | Call the commitment control exit program during IPL to reacquire locks. |
| V | Call the commitment control exit program during ASP device vary on to reacquire locks. |
| B | Call the commitment control exit program during both IPL and ASP device vary on to reacquire locks. |
Notes:
Call for rollback required. Whether the commitment control exit program should be called if the commitment definition to which this resource was added is put in a rollback-required state. When a commitment definition is placed in a rollback-required state, the use of protected resources is not allowed until the commitment definition is rolled back. The commitment control exit program should take the necessary action so that the API resources registered cannot be used until a rollback is done.
Valid values for this option are:
| N | Do not call the commitment control exit program when the commitment definition is put into a rollback-required state. |
| Y | Call the commitment control exit program when the commitment definition is put into a rollback-required state. |
| Note: One-phase API commitment resources cannot be called for rollback-required state. |
Call for rollback to a savepoint. Whether the commitment
control exit program should be called when rollback to savepoint is requested
for the commitment definition to which this resource was added.
Valid values for this option are:
| N | Do not call the commitment control exit program when rollback to savepoint is requested for the commitment definition. |
| Y | Call the commitment control exit program when rollback to savepoint is requested for the commitment definition. |
Call for release a savepoint. Whether the commitment control
exit program should be called when release savepoint is requested for the
commitment definition to which this resource was added.
Valid values for this option are:
| N | Do not call the commitment control exit program when release savepoint is requested for the commitment definition. |
| Y | Call the commitment control exit program when release savepoint is requested for the commitment definition. |
Call for setting a savepoint. Whether the commitment control
exit program should be called when a savepoint is established for the
commitment definition to which this resource was added.
Valid values for this option are:
| N | Do not call the commitment control exit program when a savepoint is established for the commitment definition. |
| Y | Call the commitment control exit program when a savepoint is established for the commitment definition. |
Last agent. Whether this commitment resource should be called as the last agent. The last agent is called after all resources have been prepared and before any resources have been committed. This resource will make the decision about whether this logical unit of work commits or rolls back.
Specifying an API commitment resource to be called as the last agent could cause incompatibilities between applications. It will also cause the logical unit of work to be rolled back if a last agent cannot be selected.
A single call will be made to the commitment control exit program if it is the last agent. This exit program must commit or roll back its resources and then inform commitment control of what it did through the Commit Vote return field.
If the call to the exit program fails (an exception is returned) or if the system fails during the call to the exit program, the logical unit of work will be committed or rolled back according to the Action if problems commitment option. The Action if problems commitment option can be changed with the Change Commitment Options (QTNCHGCO) API.
There can be only one last agent per commitment definition. Escape message CPF8369 is issued with reason code 13 if an attempt is made to add a last agent commitment resource when one is already registered.
Escape message CPF8369 is issued with reason code 7 if an attempt is made to add a last agent commitment resource when the Last agent permitted commitment option is set to N. The Last agent permitted commitment option can be changed with the Change Commitment Options (QTNCHGCO) API.
Valid values for this option are:
| N | This resource should not be called as the last agent. |
| Y | This resource should be called as the last agent. |
Notes:
|
Qualified journal name. The name of the journal that will be associated with this resource. The first 10 characters of this name contain the journal name, and the second 10 characters contain the library name. The special value *NONE is supported for the journal name if no journal is to be associated with this API resource. The special value *DFTJRN specifies that the default journal specified when the commitment definition was started should be associated with this commitment resource. The special value of *DFTJRN will be substituted by the journal name specified when the commitment definition was started. If either of these special values are specified, the library name is ignored. The special values supported for the library name are *LIBL and *CURLIB.
Note: The special values *LIBL and *CURLIB apply only to the time the resource is added. For example:
Entries can be placed in the specified journal which could be used later by the commitment control exit program to recover resources or reacquire locks. See Send Journal Entry (QJOSJRNE) API for information on sending journal entries. If a commit cycle has not been started for the journal during the current logical unit of work, one is started when the user requests to include the commit cycle identifier when sending a journal entry using the QJOSJRNE API. The commit cycle identifier will be passed to the commitment control exit program and this commit cycle identifier can be used as a starting or ending point when receiving, retrieving, or displaying entries from the journal. The CL commands RCVJRNE and RTVJRNE can be used to receive and retrieve journal entries. The DSPJRN command can display, print to a spool file, or put to an output file the journal entries.
If the optional parameter group is not specified, no journal will be associated with the API resource.
Resource protocol. Whether this API commitment resource is a one-phase or a two-phase commitment resource. One-phase commitment resources are not compatible with any remote commitment resources and cannot be called to classify, prepare, reacquire locks during IPL, or as the last agent. Two-phase commitment resources can optionally be called to classify, prepare, reacquire locks during IPL, or as the last agent.
Valid values for this option are:
| 1 | This is a one-phase API commitment resource. |
| 2 | This is a two-phase API commitment resource. |
One-phase API commitment resources do not have the ability to fully protect themselves against a remote resource failure.
Savepoint compatible. Whether the commitment control resource
is compatible with savepoints.
Valid values for this option are:
| N | The commitment control resource cannot be registered while a savepoint is in effect. |
| Y | The commitment control resource can be registered while a savepoint is in effect. Also, the exit program may be optionally called when a savepoint is set, released or rolled back. |
Structure length. The length of the input structure provided. To provide a journal without the remaining options, specify 24 for the structure length. To provide all options but the journal, specify 31 for the structure length and the special value *NONE for the journal.
Valid values for this option are:
| 24 | Only the journal is provided as an option. |
| 31 | Only the journal and two-phase commit related options are provided. |
| 35 | All options are provided. |
This API is always threadsafe. However, since the specified commitment control exit program is called during commitment control operations performed in the same job, the exit program must also be threadsafe if the API is used in a multithreaded job.
| 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. |
| CPF705A E | Operation failed due to remote journal. |
| CPF836A E | Value &1 not valid for option &2. |
| CPF836D E | Resource name &1 not valid. |
| CPF8367 E | Cannot perform commitment control operation. |
| CPF8369 E | Cannot place API commitment resource under commitment control; reason code &1. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1in library &2 ended. Reason code &3. |
| Top | Journal and Commit APIs | APIs by category |