Obtain a session-duration connection descriptor

A session-duration connection descriptor provides a public copy of connection information, providing access to the actual session information of the client application.

Because this connection descriptor has a PER_SESSION memory duration, all UDR invocations in the session can share the session-context information (see Session-context information in a connection descriptor).

The following table summarizes the memory operations for a session-duration connection descriptor in a C UDR.


Memory duration	Memory operation	Initiator of operation
PER_SESSION	Constructor	mi_get_session_connection()
PER_SESSION	Destructor	End of session

Important: The advanced mi_get_session_connection() function can adversely affect your UDR if you use it incorrectly. Use it only when a regular function cannot perform the task you need done.

The mi_get_session_connection() function is not a true constructor, in the sense that it does not actually allocate a connection descriptor in a PER_SESSION duration. Instead, it returns a handle to the actual session connection, which has a PER_SESSION duration. Therefore, the mi_get_session_connection() is often faster than mi_open() (which does allocate a connection descriptor in PER_COMMAND memory).

The minmprot.h header file defines the restricted-access mi_get_session_connection() function. The minmmem.h header file automatically includes the minmprot.h header file. However, the mi.h header file does not automatically includes minmmem.h. To use mi_get_session_connection(), you must include minmmem.h in any DataBlade® API routine that calls these functions.

A session-duration connection descriptor is useful in the following cases:

As an alternative to frequent calls to mi_open()
The mi_open() function is a relatively expensive call. If you need to open connections frequently in your UDR, mi_get_session_connection() is the preferred alternative. With a session-duration connection descriptor, the database server caches a connection for you.
To obtain access to session-duration function descriptors
One of the DataBlade API data type structures that the connection descriptor holds is a function descriptor. When you pass a Fastpath look-up function (see Fastpath look-up functions) a public connection descriptor, the function descriptor that these functions allocate is valid until the SQL command completes. If you pass these look-up functions a session-duration connection descriptor instead of a public connection descriptor, you can obtain a session-duration function descriptor, which is valid until the session ends. In this way, other UDRs can use Fastpath to execute the same UDR without having to create and destroy its function descriptor for each execution.

Keep the following restrictions in mind when you decide to use a session-duration connection:

Do not use mi_close() to free a session-duration connection descriptor.
A session-duration connection descriptor has the duration of the session. An attempt to free a session-duration connection with mi_close() generates an error.
Do not cache a session-duration connection descriptor in the user state of an MI_FPARAM structure.
You must obtain a session-duration connection descriptor in each UDR that uses it.
Do not call mi_get_session_connection() in a parallelizable UDR.
If the UDR must be parallelizable, use mi_open() to obtain a connection descriptor.