db2xa_open()--Open an XA Resource Manager (Job Scoped Locks)
Syntax
#include <xa.h>
int db2xa_switch.xa_open_entry(char *xa_info,
int rmid, long flags);
Default Public Authority: *USE
Service Program: QTNXADTP
Threadsafe: Yes
A transaction manager calls db2xa_open() to open the XA resource manager and to prepare it for use in the XA distributed transaction environment. This function must be called before any other resource manager (db2xa_) calls are made.
For additional information about parameters, authorities required, return values, and error conditions, see the xa_open() API.
Authorities
In addition to those documented for the xa_open() API, the following authorities are required.
- Exit Program Authority (specified via the xa_info parameter SRVPGM keyword)
- *USE
- Exit Program Library Authority (specified via the xa_info parameter SRVPGM keyword)
- *EXECUTE
- Journal Authority (if specified via the xa_info parameter DFTJRN keyword)
- *OBJOPR *ADD
- Journal Library Authority (if specified via the xa_info parameter DFTJRN keyword)
- *EXECUTE
Usage Notes
The usage notes for the xa_open() API apply to this API with the following differences.
- Additional xa_info keywords shown in xainfo String Keywords and
Values are allowed.
- The LOCKWAIT xa_info keyword is not allowed.
xainfo String Keywords and Values
| Keyword Name | Keyword Value | ||||
|---|---|---|---|---|---|
| DFTJRN | Default Journal. See the online help
for the DFTJRN keyword of the STRCMTCTL CL command for a description of the
effect of this keyword. The journal should be specified as the journal's
library, concatenated with a '/', concatenated with the journal's
name (for example, MYLIB/MYJRN). Both the library and journal name
must follow the IBM® i conventions for naming system objects.
The special value *NONE is supported for default journal. The special value *LIBL is accepted for the library portion of the default journal and is the default if the library portion is not specified. If this keyword is not specified, no default journal is used. If this keyword is specified but unresolvable, [XAER_INVAL] is returned. |
||||
| OMTJRNE | Omit Journal Entries. See the online
help for the OMTJRNE keyword of the STRCMTCTL CL command for a description of
the effect of this keyword.
If this keyword is not specified, OMTJRNE defaults to N. |
||||
| SQLHOLD | SQL HOLD value. Whether SQL cursors
are closed during some XA operations. Refer to SQLHOLD
Values for detailed information about this keyword.
If this keyword is not specified, SQLHOLD defaults to A. |
||||
| SRVPGM | The name of a library qualified
service program that contains functions ax_reg() and
ax_unreg() to be called by the resource manager to register
and unregister itself with the transaction manager. The service program should
be specified as the program's library, concatenated with a '/',
concatenated with the program's name (for example, TMLIB/TMPGM). Both the library and program name must follow the IBM i conventions for naming
system objects.
The special value *LIBL is supported for the library portion of the service program and is the default if the library portion is not specified. This is a required keyword. If this keyword is not specified, or is unresolvable, [XAER_INVAL] is returned. See ax_reg()--Exit Program to Dynamically Register an XA Resource Manager and ax_unreg()--Exit Program to Dynamically Unregister an XA Resource Manager for details on these service functions. |
Sqlhold values
This section documents how the SQLHOLD keyword value affects SQL cursors during the following XA operations (other XA operations do not affect cursors):
- db2xa_end() unless the TMSUSPEND flag is specified
- db2xa_commit()
- db2xa_rollback()
This applies only to cursors associated with the connection that is used for the transaction branch affected by the XA operation. As shown below, cursors declared WITH HOLD are treated differently in some cases than those not declared WITH HOLD. Note that cursors can be declared WITH HOLD only when embedded SQL is used. CLI cursors are not declared WITH HOLD.
| A | Cursors are affected by XA operations as follows:
|
| E | Cursors are affected by XA operations as follows:
|
| L | Cursors are affected by XA operations as follows:
|
| N | Cursors are affected by XA operations as follows:
|
| Y | Cursors are affected by XA operations as follows:
|
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <xa.h>
main() {
char xa_info[1024]=
"tmname=mytranmgr srvpgm=tmlib/tmserv rdbname=myrdb";
int rmid;
long flags;
int retcode;
extern struct xa_switch_t db2xa_switch;
retcode =
db2xa_switch.xa_open_entry(xa_info, rmid, flags);
}
API introduced: V4R3