Oninit
Talk to an expert →

Informix Error -701: Statement is invalid within the XA environment.

Cause and resolution

Statement is invalid within the XA environment.

This error is generated when you attempt to execute any of the following statements within an X/Open distributed transaction-processing environment:

* CLOSE DATABASE

* CREATE DATABASE

* DROP DATABASE

* SET LOG

* SAVEPOINT

* RELEASE SAVEPOINT

* ROLLBACK TO SAVEPOINT

Within this environment, you can execute a single DATABASE statement after an xa_open call to specify a current database. However, after this database is selected, no other DATABASE statement can be executed. This error is generated when you attempt to execute a second DATABASE statement.

Oninit® Troubleshooting Guidance

Reasons / Common Causes

-701 fires when any of CLOSE DATABASE, CREATE DATABASE, DROP DATABASE, SET LOG, SAVEPOINT, RELEASE SAVEPOINT, or ROLLBACK TO SAVEPOINT is executed within an X/Open distributed transaction-processing (XA) environment — per the official guidance, exactly one DATABASE statement is allowed, right after xa_open(), to select the current database; no other DATABASE-related or savepoint statement is permitted after that.

  1. One of the seven listed statements issued anywhere inside the XA environment, per the official guidance — each is disallowed outright in this context.
  2. A second DATABASE statement issued after the current database was already selected following xa_open(), per the official guidance — only the first one is allowed.
  3. Savepoint-based transaction control (SAVEPOINT/RELEASE SAVEPOINT/ROLLBACK TO SAVEPOINT) attempted inside an XA transaction, when transaction control there belongs to the external transaction manager instead.
Solutions / Resolution
  1. Don't issue any of the seven listed statements inside the XA environment, per the official guidance — this is a hard restriction, not a configurable option.
  2. Select the current database exactly once, immediately after xa_open(), per the official guidance, and don't issue any further DATABASE statement afterward.
  3. Use the external transaction manager's own mechanisms for transaction control, rather than savepoints, inside an XA transaction.
Examples
The disallowed attempt
/* Inside an XA transaction, after the database was already selected once: */
DATABASE another_db;
-- -701: a second DATABASE statement isn't allowed

SAVEPOINT sp1;
-- -701: savepoints aren't allowed inside an XA transaction
Diagnostic Checks
  1. Check whether the connection is currently inside an XA environment, and scan for any of the seven listed statements in code paths that run there.
Related Errors / Related Topics
  • -700 — "Statement is invalid within a global transaction." A related restriction, on BEGIN/COMMIT/ROLLBACK WORK specifically rather than this broader list of statements.
  • -702 — "Cannot open database in exclusive mode." A related XA-environment restriction, on a specific database-open mode not included in this error's list.

A specific list of seven statements is disallowed inside the XA environment — select the database exactly once, right after xa_open(), and don't touch any of the others.