Establishing a UDR Connection (Server)

Home | Previous Page | Next Page Database Access > Handling Connections > Establishing a Connection >

Establishing a UDR Connection (Server)

A UDR connection is the way that a C UDR obtains access to the session context; that is, to the database server and database that the calling client application has already established. For a summary of restrictions that the UDR imposes on a session, see Session Restrictions.

A C UDR can establish one of two kinds of connections to a session:

The public connection descriptor provides the C UDR invocations within an SQL command with access to the session context.
The session-duration connection descriptor provides the C UDR invocations within a session with access to the session context.

Obtaining 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 Table 44). 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 IBM 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 Figure 61 shows. For more information, see Saving a User State.

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. For more information, see Obtaining a Session-Duration Connection Descriptor.

Obtaining 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 Table 44). (For more information on a session, see PER_SESSION Memory Duration.)

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

Warning:

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 Table 65) 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. For more information, see Reusing a Function Descriptor.

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.