isc_transaction_info()
Go Up to API Function Reference
Returns information about the specified named transaction.
Syntax
ISC_STATUS isc_transaction_info(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short item_list_buffer_length,
char *item_list_buffer,
short result_buffer_length,
char *result_buffer);
| Parameter | Type | Description |
|---|---|---|
|
|
|
Pointer to the error status vector |
|
|
|
Pointer to a transaction handle whose value has been set by a previous |
|
|
|
Number of bytes in the item-list buffer |
|
|
|
Pointer to the item-list buffer |
|
|
|
Number of bytes in the result buffer |
|
|
|
Pointer to the result buffer |
Description
isc_transaction_info() returns information necessary for keeping track of transaction IDs. This call is used internally by isc_prepare_transaction(). You should not need to use it in your own applications.
You can explicitly retrieve information about the transaction ID by including the following constant in the item-list buffer, where the transaction items about which you want information are listed:
| Item | Purpose | Size of next value | Value |
|---|---|---|---|
|
|
Determine the transaction ID |
2 bytes |
transaction ID |
isc_transaction_info() uses two buffers defined in the calling program: the item-list buffer, which lists transaction items about which you want information, and a result buffer, where the information requested is reported.
To define the item-list buffer, include the parameters item_list_buffer_length and item_list_buffer_address. The item-list buffer is a regular byte vector with no structure.
To define the result buffer, include the parameters result_buffer_length and result_buffer_address. These parameters specify the length and address of a buffer where the InterBase engine will place the return values from the function call.
The values returned to the result buffer are unaligned clusters of generic binary numbers. Furthermore, all numbers are represented in a generic format, with the least significant byte first, and the most significant byte last. Signed numbers have the sign in the last byte. Convert the numbers to a data type native to your system before interpreting them.
In your call, include the item specifying the transaction ID, isc_info_tra_id. InterBase returns the transaction ID in the result buffer. In addition to the information InterBase returns in response to a request, InterBase can also return one or more of the following status messages to the result buffer. Each status message is one unsigned byte in length:
| Item | Description |
|---|---|
|
|
End of the messages |
|
|
Result buffer is too small to hold any more requested information |
|
|
Requested information is unavailable; check the status vector for an error code and message. |
The function return value indicates only that InterBase accepted the request for information. It does not mean that it understood the request or that it supplied all of the requested information. Your application must interpret the contents of the result buffer for details about the transaction.
Example
The following code fragment gets information about a transaction:
static char /* Declare item-list buffer. */
tra_items[] = {isc_info_tra_id}; /* Declare result buffer. */
CHAR tra_info[32];
isc_transaction_info(status_vector, &tr_handle,
sizeof (tra_items), /* Length of item-list buffer. */
&tra_items, /* Address of item-list buffer. */
sizeof (tra_info), /* Length of result buffer. */
&tra_info); /* Address of result buffer. */
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector);
return(1);
}
Return value
isc_transaction_info() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code.
To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.