Obtain a connection descriptor

A public connection descriptor (usually just called a connection descriptor) provides a local copy of session information for the use of the UDR.

Because it has a PER_STMT_EXEC memory duration, all UDR invocations in the same SQL statement can share the session-context information (see Session-context information in a connection descriptor). The following table summarizes the memory operations for a connection descriptor in a C UDR.


Memory duration	Memory operation	Function name
PER_STMT_EXEC	Constructor	mi_open()
PER_STMT_EXEC	Destructor	mi_close()

To establish a UDR connection, pass all three arguments of mi_open() as NULL-valued pointers. The following code fragment uses mi_open() to establish a connection for a UDR:

mi_integer func1()
{
   MI_CONNECTION *conn;

/* Open a connection from C UDR to database server
 * of current session context:
 *    database = currently open database 
 *    user = operating-system user account which is running
 *               the SQL statement that called this 
 *               user-defined routine
 *    password = default specified for this user 
 */
   conn = mi_open(NULL, NULL, NULL);

/* If connection descriptor is NULL, there was an error
 * connecting to the session context. 
 */
   if ( conn == NULL )
      {
      mi_db_error_raise(conn, MI_EXCEPTION, 
         "func1: cannot establish connection", NULL);
      }

... /* Code for use of this connection goes here */
}

Important: When called within a C UDR, many DataBlade® API functions do not use the connection descriptor. You can pass a NULL-valued pointer as a connection descriptor to the DataBlade API functions for smart large objects, which have the mi_lo_ prefix. The Informix® DataBlade API Function Reference describes these functions. Exceptions to this rule are listed in the documentation. Instead, pass in the connection descriptor that the mi_open() function obtains.

The mi_open() call can be expensive in a C UDR. If the UDR instance contains many invocations, you can obtain the connection descriptor the first time the UDR is invoked and store it as part of the MI_FPARAM state information, as Caching the connection descriptor in an exception callback shows.

Tip: It is not valid for a UDR to cache a connection descriptor at a memory duration higher than PER_COMMAND. If you need session-context information with a higher duration, use a session-duration connection descriptor.