![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description |
struct GdaXaTransaction; enum GdaXaTransactionError; struct GdaXaTransactionId; GdaXaTransaction * gda_xa_transaction_new (guint32 format
,const gchar *global_transaction_id
); gboolean gda_xa_transaction_register_connection (GdaXaTransaction *xa_trans
,GdaConnection *cnc
,const gchar *branch
,GError **error
); void gda_xa_transaction_unregister_connection (GdaXaTransaction *xa_trans
,GdaConnection *cnc
); gboolean gda_xa_transaction_begin (GdaXaTransaction *xa_trans
,GError **error
); gboolean gda_xa_transaction_commit (GdaXaTransaction *xa_trans
,GSList **cnc_to_recover
,GError **error
); gboolean gda_xa_transaction_rollback (GdaXaTransaction *xa_trans
,GError **error
); gboolean gda_xa_transaction_commit_recovered (GdaXaTransaction *xa_trans
,GSList **cnc_to_recover
,GError **error
); gchar * gda_xa_transaction_id_to_string (const GdaXaTransactionId *xid
); GdaXaTransactionId * gda_xa_transaction_string_to_id (const gchar *str
);
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 sucessfull as the data stored during the prepare phase can be committed afterwards.
A distributed transaction involves the following steps:
Create a GdaXaTransaction object
Register the connections which will be part of the distributed transaction with that object
using gda_xa_transaction_register_connection()
Beging the distributed transaction using gda_xa_transaction_begin()
Work individually on each connection as normally (make modifications)
Commit the distributed transaction using gda_xa_transaction_commit()
Discard the GdaXaTransaction object using g_object_unref()
typedef enum { GDA_XA_TRANSACTION_ALREADY_REGISTERED_ERROR, GDA_XA_TRANSACTION_DTP_NOT_SUPPORTED_ERROR, GDA_XA_TRANSACTION_CONNECTION_BRANCH_LENGTH_ERROR } GdaXaTransactionError;
struct GdaXaTransactionId { guint32 format; /* any number */ gushort gtrid_length; /* 1-64 */ gushort bqual_length; /* 1-64 */ char data [128]; };
Distributed transaction identification, composed of a global format identifier, a global transaction identifier, and a branch qualifier. For any connection participating in the global transaction, the format and global transaction identifier should be the same, and the branch qualifier should vary between the connections.
Format ID, should be 0 if OSI CCR naming is used, otherwise any positive integer | |
length of the global transaction ID (1-64) | |
length of the branch qualification (1-64) | |
concatenated global transaction ID (bytes 0 to (gtrid_length -1) included) and branch qualification (bytes gtrid_length to (gtrid_length +bqual_length - 1) included) |
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.
|
a format ID |
|
the global transaction ID |
Returns : |
the newly created object. [transfer full] |
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.
|
a GdaXaTransaction object |
|
the connection to add to xa_trans
|
|
the branch qualifier |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
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()
.
|
a GdaXaTransaction object |
|
the connection to add to xa_trans
|
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
.
|
a GdaXaTransaction object |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
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).
|
a GdaXaTransaction object |
|
a place to store the list of connections for which the commit phase failed, or NULL . [allow-none][element-type Gda.Connection][out callee-allocates]
|
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred (there may be some connections to recover, though) |
gboolean gda_xa_transaction_rollback (GdaXaTransaction *xa_trans
,GError **error
);
Cancels a distributed transaction (managed by xa_trans
).
|
a GdaXaTransaction object |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
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.
|
a GdaXaTransaction object |
|
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 . [allow-none][element-type Gda.Connection][out callee-allocates]
|
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if all the data which was still uncommitted has been committed |
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.
|
a GdaXaTransactionId pointer |
Returns : |
a new string representation of xid . [transfer full]
|
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()
.
|
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 |