Add Commitment Resource (QTNADDCR) API

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 Commitment Control topic collection.

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 Commitment Control Exit Program.

Authorities and Locks

Exit Program Authority

*USE

Exit Program Library Authority

*EXECUTE

Exit Program Lock

*SHRNUP

Journal Authority

*USE

Journal Library Authority

*EXECUTE

Journal Lock

*SHRUPD

Restrictions

You are prevented from adding a commitment resource using this API when:

• Distributed data management (DDM) or distributed relational database is used to update remote resources under commitment control and two-phase commit protocols are not supported at the remote system.

  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.

• Commitment control is not active for the program when making the request to add a commitment resource.
• Commitment control cannot get a shared-no-update (*SHRNUP) lock on the commitment control exit program.
• Commitment control cannot get a shared-for-update (*SHRUPD) lock on the journal associated with this resource. This is a restriction only if a journal is specified to be associated with the resource.
• A commitment control operation is currently in progress for the commitment definition that is to have the commitment resource added.
• The checkpoint processing for a save-while-active function is in progress in another job, when you specify the option to allow normal save processing or specify the default (N).
• The checkpoint processing for an independent ASP quiesce is in progress on the system, when you specify the option to allow independent ASP quiesce or specify the default (N).

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.

Required Parameter Group

Resource handle

OUTPUT; BINARY(4)

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.

Resource name

INPUT; CHAR(10)

The name that identifies this commitment resource. It is used, for example, in some error messages associated with the commitment control exit programs.

Qualified commitment control exit program name

INPUT; CHAR(20)

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 may reside on any ASP in the library name space for the thread that calls this API. However, you must consider the location of the journal, if any, specified for the Qualified journal name parameter, along with the value specified for the IPL and ASP device vary on processing option parameter, as some combinations of these parameters will cause unexpected results. See the IPL and ASP device vary on processing option parameter for details.

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:

1. The API user specifies PROGRAMA in *CURLIB when a commitment resource is added. LIBRARYA is the *CURLIB when the resource is added.
2. After the resource addition, *CURLIB is changed to LIBRARYB, which also happens to contain a PROGRAMA.
3. The commit operation occurs and PROGRAMA in LIBRARYA is called, not PROGRAMA in LIBRARYB.

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.

Commitment control exit program information

INPUT; CHAR(80)

Data needed by the commitment control exit program to behave correctly when called for this resource. A copy of this data is passed to the 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, and therefore it is recommended they be used only when the commitment control exit program resides in the same ASP group as the data the pointers reference.

If the exit program is to be called during IPL or ASP device vary on processing, any objects identified by this data 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.

IPL and ASP device vary on processing option

INPUT; CHAR(1)

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 or ASP device vary on recovery processing for the commitment definition.

Notes:

1. When called during IPL or ASP device vary on, the exit program runs under the same user profile that originally added the commitment resource.
2. 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.
3. 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. See Process End, Activation Group End, and IPL or ASP Device Vary On Recovery Processing Guidelines in Commitment Control Exit Program for details.
4. Each API commitment resource is associated with exactly one ASP group. If the Qualified journal name parameter is specified, the API commitment resource is associated with the ASP group in which the journal resides. If no journal is specified, it is associated with the ASP group in which the specified commitment control exit program resides. The ASP group determines when the exit program is eligible to be called in case of system or ASP device failure. If it is associated with *SYSBAS, the exit program is eligible to be called only during IPL recovery processing. If it is associated with an independent ASP, it is eligible to be called only during ASP device vary on. This must be considered when specifying the IPL and ASP device vary on processing option, or unexpected results may occur. If the resource is associated with *SYSBAS, its exit program will only be called for recovery if the option is set to Y or B. If the resource is associated with an independent ASP, its exit program will only be called for recovery if the option is set to V or B. Furthermore, if the API commitment resource is associated with an independent ASP, but the exit program resides in *SYSBAS, the exit program must reside on all systems in the cluster to which the independent ASP might be moved after the system ends abnormally.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group 1

Add resource options

INPUT; CHAR(*)

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.

Optional Parameter Group 2

Current savepoint number

OUTPUT; BINARY(4)

An identifier of the savepoint assigned to the savepoint name. This identifier may not increment by 1 because of internally created savepoints.

Input Options Structure

Field Descriptions

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:

Allow independent ASP quiesce. Whether the registration of this API commitment resource allows independent ASP to be quiesced.

Valid values for this option are:

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:

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:

Notes:

1. One-phase API commitment resources cannot be called for prepare.
2. Two-phase API commitment resources with a Last agent option value of Y cannot be called for prepare.

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 on is 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 IPL or ASP device vary on to reacquire locks.

Notes:

1. One-phase API commitment resources cannot be called to reacquire locks during IPL.
2. Two-phase API commitment resources with an IPL processing option value of N cannot be called to reacquire locks during IPL. If the optional parameter group is not specified, the commitment control exit program is not called during IPL to reacquire locks.
3. Each API commitment resource is associated with exactly one ASP group. If the Qualified journal name parameter is specified, the API commitment resource is associated with the ASP group in which the journal resides. If no journal is specified, it is associated with the ASP group in which the specified commitment control exit program resides. The ASP group determines when the exit program is eligible to be called to reacquire locks. If it is associated with *SYSBAS, the exit program is eligible to be called only during IPL recovery processing. If it is associated with an independent ASP, it is eligible to be called only during ASP device vary on. This must be considered when specifying the Call for reacquiring locks during IPL or ASP device vary on option, or unexpected results may occur. If the resource is associated with *SYSBAS, its exit program will only be called to reacquire locks if the option is set to Y or B. If the resource is associated with an independent ASP, its exit program will only be called to reacquire locks if the option is set to V or B. Furthermore, if the API commitment resource is associated with an independent ASP, but the exit program resides in *SYSBAS, the exit program must reside on all systems in the cluster to which the independent ASP might be moved after the system ends abnormally.

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:

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:

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:

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:

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:

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:

1. The API user specifies JOURNALA in *CURLIB when a commitment resource is added. LIBRARYA is the *CURLIB at the time the resource is added.
2. After the resource addition, *CURLIB is changed to LIBRARYB, which also happens to contain a JOURNALA.
3. The commit operation occurs using JOURNALA in LIBRARYA, not JOURNALA in LIBRARYB.

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 about 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.

It is recommended that the journal reside on the same ASP group as the commitment control exit program to ensure that it is always available during exit program calls. However, this is not enforced, and you must consider the location of the specified commitment control exit program along with the value specified for the IPL and ASP device vary on processing option parameter, as some combinations of these parameters will cause unexpected results. See the IPL and ASP device vary on processing option parameter for details.

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:

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:

Structure length. The length of the input structure provided. To provide a journal without the remaining options, specify 24 for the structure length. If a structure length greater than 24 is specified, and no journal is desired, specify special value *NONE for the journal.

Valid values for this option are:

Usage Notes

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.

Error Messages

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