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.

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.
N Corresponds to the STRCMTCTL OMTJRNE value *NONE.
L Corresponds to the STRCMTCTL OMTJRNE value *LUWID.

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):

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:
  • db2xa_end() with the TMSUCCESS or TMFAIL flag:
    • All cursors are closed.
  • db2xa_commit():
    • Cursors are not affected since db2xa_end() already closed them.
  • db2xa_rollback():
    • Cursors are not affected since db2xa_end() already closed them.
E Cursors are affected by XA operations as follows:
  • db2xa_end() with the TMSUCCESS or TMFAIL flag:
    • Cursors declared WITH HOLD are held open.
    • Cursors not declared WITH HOLD are closed.
  • db2xa_commit():
    • Cursors declared WITH HOLD are held open.
    • Cursors not declared WITH HOLD are closed.
  • db2xa_rollback():
    • All cursors are closed.
L Cursors are affected by XA operations as follows:
  • db2xa_end() with the TMSUCCESS or TMFAIL flag:
    • All cursors are held open.
  • db2xa_commit():
    • If the relational database resides on a System i® platform:
      • All cursors are left open.
    • If the relational database does not reside on a System i platform:
      • Cursors declared WITH HOLD are left open.
      • Cursors not declared WITH HOLD are closed.
  • db2xa_rollback():
    • If the relational database resides on a System i platform:
      • All cursors are left open.
    • If the relational database does not reside on a System i platform:
      • All cursors are closed.
N Cursors are affected by XA operations as follows:
  • db2xa_end() with the TMSUCCESS or TMFAIL flag:
    • All cursors are held open.
  • db2xa_commit():
    • Cursors declared WITH HOLD are held open.
    • Cursors not declared WITH HOLD are closed.
  • db2xa_rollback():
    • All cursors are closed.
Y Cursors are affected by XA operations as follows:
  • db2xa_end() with the TMSUCCESS or TMFAIL flag:
    • All cursors are held open.
  • db2xa_commit():
    • If the relational database resides on a System i platform:
      • All cursors are left open.
    • If the relational database does not reside on a System i platform:
      • The db2xa_commit() operation will fail. This value should not be used with relational databases that do not reside on a System i platform.
  • db2xa_rollback():
    • If the relational database resides on a System i platform:
      • All cursors are left open.
    • If the relational database does not reside on a System i platform:
      • The db2xa_rollback() operation will fail. This value should not be used with relational databases that do not reside on a System i platform.

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

[ Back to top | UNIX-Type APIs | APIs by category ]