Associating User Data with a Connection

The connection descriptor provides information about various data type structures associated with the current connection. (For a list of this information, see Table 44.) 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.

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 will not support the task you need to perform. For more information, see Obtaining a Session-Duration Connection Descriptor.

Table 51 shows the functions that the DataBlade API provides to access the user data of a connection descriptor.

Table 51. DataBlade API Accessor Functions for User Data in the 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.