Understanding State-Transition Events

Home | Previous Page | Next Page Database Access > Handling Exceptions and Events > State-Transition Events >

Understanding State-Transition Events

State-transition events occur when the database server changes its processing state. The DataBlade API represents a state transition as one of the enumerated values of the MI_TRANSITION_TYPE data type. The following table shows the transitions in the server-processing state and the corresponding MI_TRANSITION_TYPE values.

State-Transition Type	Description
MI_BEGIN	The database server is beginning a new transaction.
MI_NORMAL_END	The database server just completed the current event successfully.
MI_ABORT_END	The database server just rolled back the current event. (The statement failed, or the transaction was aborted or rolled back.)

The milib.h header file defines the MI_TRANSITION_TYPE data type and its state-transition values.

The following table shows the state-transition types and the state-transition events that they can cause.

State-Transition Type	Event in Client LIBMI Application	Event in C UDR
Begin transaction or savepoint (MI_BEGIN)	MI_Xact_State_Change	None
Event end: commit (MI_NORMAL_END)	MI_Xact_State_Change	MI_EVENT_SAVEPOINT MI_EVENT_COMMIT_ABORT MI_EVENT_POST_XACT MI_EVENT_END_STMT MI_EVENT_END_XACT MI_EVENT_END_SESSION
Event end: rolled back (MI_ABORT_END)	MI_Xact_State_Change	MI_EVENT_SAVEPOINT MI_EVENT_COMMIT_ABORT MI_EVENT_POST_XACT MI_EVENT_END_STMT MI_EVENT_END_XACT MI_EVENT_END_SESSION

Beginning a Transaction

Client Only

When the database server begins a transaction block, it raises only the MI_Xact_State_Change event. The MI_Xact_State_Change event occurs only in the context of a client LIBMI application when the database server enters and leaves a transaction block. Only client callback functions can catch this begin-transaction event.

You handle the MI_Xact_State_Change event only in the context of a client LIBMI application. It occurs within a client LIBMI application when the current transaction ends with either a commit or a rollback. The MI_Xact_State_Change event also occurs when the database server begins a transaction.

End of Client Only

A state-transition callback executes when the following state-transition event occurs.

State-Transition Event Type	Callback Type
MI_Xact_State_Change	State-change callback

Server Only

A C UDR does not begin transactions. It inherits the transaction of the client application that calls the SQL statement that contains the UDR.

End of Server Only

Ending a Session (Server)

The MI_EVENT_END_SESSION event occurs when the database server reaches the end of the current session. A session begins when the client application opens a database connection and ends when the client application closes the connection (or when the client application ends). For more information, see Closing a Connection.

These events occur only within the context of a C UDR. Their main purpose is to clean up resources that the UDR might have allocated. The database server does not throw the MI_EVENT_END_SESSION event when it terminates abnormally.