GdaXaTransaction: libgda Reference Manual

## GdaXaTransaction GdaXaTransaction — Distributed transaction manager |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaXaTransaction * | gda_xa_transaction_new ()
gboolean | gda_xa_transaction_register_connection ()
void | gda_xa_transaction_unregister_connection ()
gboolean | gda_xa_transaction_begin ()
gboolean | gda_xa_transaction_commit ()
gboolean | gda_xa_transaction_rollback ()
gboolean | gda_xa_transaction_commit_recovered ()
gchar * | gda_xa_transaction_id_to_string ()
GdaXaTransactionId * | gda_xa_transaction_string_to_id ()

## Properties

guint | format-id | Read / Write / Construct Only
char * | transaction-id | Read / Write / Construct Only

## Types and Values

| GdaXaTransaction
enum | GdaXaTransactionError
| GdaXaTransactionId

## Object Hierarchy

        GBoxed
        ╰── GdaXaTransactionId
        GObject
        ╰── GdaXaTransaction

## Description

The GdaXaTransaction object acts as a distributed transaction manager: to make sure local transactions on several connections (to possibly different databases and database types) either all succeed or all fail. For more information, see the X/Open CAE document Distributed Transaction Processing: The XA Specification. This document is published by The Open Group and available at

http://www.opengroup.org/public/pubs/catalog/c193.htm.

The two phases commit protocol is implemented during the execution of a distributed transaction: modifications made on any connection are first prepared (which means that they are store in the database), and if that phase succeeded for all the involved connections, then the commit phase is executed (where all the data previously stored during the prepare phase are actually committed). That second phase may actually fail, but the distributed transaction will still be considered as successfull as the data stored during the prepare phase can be committed afterwards.

A distributed transaction involves the following steps:

1. Create a GdaXaTransaction object

2. Register the connections which will be part of the distributed transaction with that object using `gda_xa_transaction_register_connection()`

3. Beging the distributed transaction using `gda_xa_transaction_begin()`

4. Work individually on each connection as normally (make modifications)

5. Commit the distributed transaction using `gda_xa_transaction_commit()`

6. Discard the GdaXaTransaction object using `g_object_unref()`

## Functions

### gda_xa_transaction_new ()

    GdaXaTransaction *
    gda_xa_transaction_new (guint32 format,
                            const gchar *global_transaction_id);

Creates a new GdaXaTransaction object, which will control the process of performing a distributed transaction across several connections.

#### Parameters

format | a format ID |
global_transaction_id | the global transaction ID |

#### Returns

the newly created object.

[transfer full]

### gda_xa_transaction_register_connection ()

    gboolean
    gda_xa_transaction_register_connection
                                   (GdaXaTransaction *xa_trans,
                                    GdaConnection *cnc,
                                    const gchar *branch,
                                    GError **error);

Registers `cnc` to be used by `xa_trans` to create a distributed transaction.

Note: any GdaConnection object can only be registered with at most one GdaXaTransaction object; also some connections may not be registered at all with a GdaXaTransaction object because the database provider being used does not support it.

#### Parameters

xa_trans | a GdaXaTransaction object |
cnc | the connection to add to `xa_trans` |
branch | the branch qualifier |
error | a place to store errors, or `NULL`. | [nullable]

#### Returns

`TRUE` if no error occurred

### gda_xa_transaction_unregister_connection ()

    void
    gda_xa_transaction_unregister_connection
                                   (GdaXaTransaction *xa_trans,
                                    GdaConnection *cnc);

Unregisters `cnc` to be used by `xa_trans` to create a distributed transaction. This is the opposite of `gda_xa_transaction_register_connection()`.

#### Parameters

xa_trans | a GdaXaTransaction object |
cnc | the connection to add to `xa_trans` |

### gda_xa_transaction_begin ()

    gboolean
    gda_xa_transaction_begin (GdaXaTransaction *xa_trans,
                              GError **error);

Begins a distributed transaction (managed by `xa_trans` ). Please note that this phase may fail for some connections if a (normal) transaction is already started (this depends on the database provider being used), so it's better to avoid starting any (normal) transaction on any of the connections registered with `xa_trans` .

#### Parameters

xa_trans | a GdaXaTransaction object |
error | a place to store errors, or `NULL`. | [nullable]

#### Returns

TRUE if no error occurred

### gda_xa_transaction_commit ()

    gboolean
    gda_xa_transaction_commit (GdaXaTransaction *xa_trans,
                               GSList **cnc_to_recover,
                               GError **error);

Commits a distributed transaction (managed by `xa_trans` ). The commit is composed of two phases:

- a PREPARE phase where all the connections are required to store their transaction data to a permanent place (to be able to complete the commit should a problem occur afterwards)

- a COMMIT phase where the transaction data is actually written to the database

If the PREPARE phase fails for any of the connection registered with `xa_trans` , then the distributed commit fails and FALSE is returned. During the COMMIT phase, some commit may actually fail but the transaction can still be completed because the PREPARE phase succeeded (through the recover method).

#### Parameters

xa_trans | a GdaXaTransaction object |
cnc_to_recover | a place to store the list of connections for which the commit phase failed, or `NULL`. | [nullable][element-type Gda.Connection][out callee-allocates]
error | a place to store errors, or `NULL` |

#### Returns

TRUE if no error occurred (there may be some connections to recover, though)

### gda_xa_transaction_rollback ()

    gboolean
    gda_xa_transaction_rollback (GdaXaTransaction *xa_trans,
                                 GError **error);

Cancels a distributed transaction (managed by `xa_trans` ).

#### Parameters

xa_trans | a GdaXaTransaction object |
error | a place to store errors, or `NULL`. | [nullable]

#### Returns

`TRUE` if no error occurred

### gda_xa_transaction_commit_recovered ()

    gboolean
    gda_xa_transaction_commit_recovered (GdaXaTransaction *xa_trans,
                                         GSList **cnc_to_recover,
                                         GError **error);

Tries to commit the data prepared but which failed to commit (see `gda_xa_transaction_commit()`). This method allows one to terminate a distributed transaction which succeeded but for which some connections needed to be recovered.

#### Parameters

xa_trans | a GdaXaTransaction object |
cnc_to_recover | a place to store the list of connections for which the there were data to recover and which failed to be actually committed, or `NULL`. | [nullable][element-type Gda.Connection][out callee-allocates]
error | a place to store errors, or `NULL`. | [nullable]

#### Returns

`TRUE` if all the data which was still uncommitted has been committed

### gda_xa_transaction_id_to_string ()

    gchar *
    gda_xa_transaction_id_to_string (const GdaXaTransactionId *xid);

Creates a string representation of `xid` , in the format <gtrid>,<bqual>,<formatID> the <gtrid> and <bqual> strings contain alphanumeric characters, and non alphanumeric characters are converted to "`ab`" where ab is the hexadecimal representation of the character.

#### Parameters

xid | a GdaXaTransactionId pointer |

#### Returns

a new string representation of `xid` .

[transfer full]

### gda_xa_transaction_string_to_id ()

    GdaXaTransactionId *
    gda_xa_transaction_string_to_id (const gchar *str);

Creates a new GdaXaTransactionId structure from its string representation, it's the opposite of `gda_xa_transaction_id_to_string()`.

#### Parameters

str | a string representation of a GdaXaTransactionId, in the "gtrid,bqual,formatID" format |

#### Returns

a new GdaXaTransactionId structure, or `NULL` in `str` has a wrong format

Free-function: g_free

## Types and Values

### GdaXaTransaction

    typedef struct _GdaXaTransaction GdaXaTransaction;

### enum GdaXaTransactionError

#### Members

GDA_XA_TRANSACTION_ALREADY_REGISTERED_ERROR |  |
GDA_XA_TRANSACTION_DTP_NOT_SUPPORTED_ERROR |  |
GDA_XA_TRANSACTION_CONNECTION_BRANCH_LENGTH_ERROR |  |

### GdaXaTransactionId

    typedef struct {
    	guint32  format;
    	gushort  gtrid_length;
    	gushort  bqual_length;
    	char     data [128];
    } GdaXaTransactionId;

#### Members

guint32 `format`; | any number |
gushort `gtrid_length`; | number between 1 and 64 |
gushort `bqual_length`; | number between 1 and 64 |
char `data`[128]; |  |

## Property Details

### The `“format-id”` property

      “format-id”                guint

Owner: GdaXaTransaction

Flags: Read / Write / Construct Only

Default value: 1

### The `“transaction-id”` property

      “transaction-id”           char *

Owner: GdaXaTransaction

Flags: Read / Write / Construct Only

Default value: NULL