Associate user data with a connection
The connection descriptor provides information about various data type structures associated with the current connection. In addition, you can store the address of private information, called user data, in the connection descriptor. The connection descriptor can hold this user-data pointer, which points to the private user-data information.
For a list of the information the connection descriptor provides, see Session-context information in a connection descriptor.
Server only:
You allocate the user
data with a DataBlade®
API memory-management
function from the shared memory of the database server. The memory
duration of this user data must correspond with the connection descriptor
that holds the user-data pointer, as the following table shows.
| Type of connection descriptor | Memory duration of user data | Which UDRs can access user data |
|---|---|---|
| Public connection descriptor (with mi_open()) | MI_COMMAND | All UDR invocations in the same SQL command have access to the connection descriptor that mi_open() returns. |
| Session-duration connection descriptor (with mi_get_session_connection()) | MI_SESSION | All C UDR invocations in the session have access to the connection descriptor that mi_get_session_connection() returns. |
Therefore, your user data is available to all UDRs
that can access its connection descriptor.
Important: A
session-duration connection descriptor is a restricted feature that
can adversely affect your UDR if used incorrectly. Use it only when
a public connection descriptor cannot support the task you need to
perform.
Client only: The user data is allocated
in client-side memory. Therefore, your user data is available to all DataBlade
API functions
that execute in the session.
The following table shows the functions that the DataBlade
API provides
to access the user data of a connection descriptor.
| DataBlade API accessor function | User-state information |
|---|---|
| mi_get_connection_user_data() | Obtains the user-data pointer from the connection descriptor |
| mi_set_connection_user_data() | Sets the user-data pointer in the connection descriptor |
The size of the connection user data is the size of a pointer of type void *. The DataBlade API does not interpret or touch the associated user-data address, other than to store and retrieve it from the connection descriptor.