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 Informix® 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 $INFORMIXDIR/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 $INFORMIXDIR/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 Informix® 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 Informix® 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 Informix® 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.