The ax_reg() function

The ax_reg() function allows DataBlade® modules or applications using user-defined routines (UDRs) to register XA-compliant, external data sources (also called resource managers) with the HCL OneDB™ transaction manager. The registration is dynamic and is applicable for the current transaction only. The DataBlade must register participating data sources into each transaction.

Syntax

int ax_reg(int rmid,
       XID *xid,
       int4 flags)
rmid
The resource manager ID.
xid
A valid pointer to the XID data structure, which is defined in the $ONEDB_HOME/incl/public/xa.h file. Valid XID information is returned if the ax_reg() function returns TM_OK.
flags
Must be set to TMNOFLAGS. The value for TMNOFLAGS is defined in the $ONEDB_HOME/incl/public/xa.h file.
Valid in client LIBMI application? Valid in user-defined routine?
No Yes

Usage

The ax_reg() function registers the resource manager ID of the XA data source into the current transaction. When the ax_reg() function is called, you must set flags to TMNOFLAGS.

Multiple registrations of the same XA data source in a transaction have the same effect as a single registration. HCL OneDB does not maintain a count of the number of times an application has registered. A single call to ax_unreg() unregisters the data source from the transaction.

The caller is responsible for allocating the space to which xid points.

The resource manager ID must be present in a row in the ’informix’.sysxadatasources system catalog table created with this SQL statement: 
CREATE XADATASOURCE datasourcename USING xadstype

An application can use the mi_xa_get_xadatasource_rmid() function to get the resource manager ID.

For more information about this statement, see the HCL OneDB Guide to SQL: Syntax.

The ax_reg() function must be repeated for each transaction.
Important: If xid does not point to a buffer that is at least as large as the size of an XID, the ax_reg() function can overwrite the caller's data space. In addition, the buffer must be properly aligned on a long word boundary in case structure assignments are performed.

If the function call is successful, the function returns TM_OK and the xid value. If the function call is not successful, an error appears.

If you receive an error, check for any of the following problems:
  1. Make sure the rmid value is correct.
  2. Make sure memory for xid is allocated.
  3. Make sure flags is set to TMNOFLAGS.
  4. Make sure that the ax_reg() function is called from within the transaction.
  5. Make sure that the ax_reg() function is not called:
    • From the subordinator of a distributed transaction.
    • From within the resource manager global transaction.
    • In a nonlogging database.
    • From any of the XA purpose functions that are specified in a CREATE XADATASOURCE TYPE statement, which creates a type of XA-compliant external data source.

The mi_xa_register_xadatasource() function also allows DataBlade modules to register XA-compliant, external data sources. However, the ax_reg() function and the mi_xa_register_xadatasource() function use different parameters and have different return values.

For more information about working with XA data sources, see the HCL OneDB DataBlade API Programmer's Guide. Also refer to the "Distributed Transaction Processing: The XA Specification." This is the X/OPEN standard specification that is available on the Internet.

Return values

TM_OK
The data source is registered.
TMER_TMERR
indicates that an error occurred and the data source is not registered.
TMER_INVAL
indicates that invalid arguments were specified.
TMER_PROTO
The routine was invoked in an improper context.