Informix DataBlade API Programmer's Manual Establishing a Connection

The following DataBlade API functions are constructor functions for a connection descriptor:

• The mi_open() function
• The mi_server_connect() function

These functions establish a connection and return a pointer to a connection descriptor, which holds information from the session context. You can then pass this connection descriptor to subsequent DataBlade API functions that need to access the session context.

The DataBlade API supports the establishing of the two kinds of connections:

• A UDR connection
• A client connection

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.

The connection descriptor provides the C UDR with access to the session context. The following table summarizes the memory operations for a connection descriptor in a C UDR.

To establish a UDR connection, pass all three arguments of mi_open() as the NULL-valued pointer. 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

**                                    this user-defined routine
**        password = default specified for this user  */
	conn = mi_open(NULL, NULL, NULL);

/* If connection descriptor is NULL, then there was an error

** connecting to the session context.  */
	if ( conn == NULL )
		{
		mi_db_error_raise(conn, MI_EXCEPTION, 

			"Cannot open database: %s\n", argv[1], 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. However, Informix does not recommend passing in a NULL-valued pointer as a connection descriptor to most DataBlade API 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. For more information, see Saving a User State.

A client LIBMI application can establish a client connection in either of the following ways:

• The mi_open() function
• The mi_server_connect() and mi_login() functions

These DataBlade API functions obtain a connection descriptor for the client connection. The following table summarizes the memory operations for a connection descriptor in a client LIBMI application.

Important: When called within a client LIBMI application, DataBlade API functions always use the connection descriptor. Therefore, never send in a NULL-valued pointer as a connection descriptor to DataBlade API functions. Instead, pass in the connection descriptor that the mi_open(), mi_server_connect(), or mi_server_reconnect() function obtains.

Once the client LIBMI application has established a connection, the session begins.

The mi_open() function establishes a default connection for the calling DataBlade API module and returns a connection descriptor. A default connection is a connection to the default database server (which the INFORMIXSERVER environment variable specifies), and a specified database.

To establish a default connection, the mi_open() function accepts the following information as arguments.

All of these arguments are passed as pointers to character strings. You can specify NULL for any of these arguments, in which case mi_open() uses the specified default values. If the client LIBMI application uses a shared-memory communication, it can only establish one connection per application.

The following code fragment demonstrates the simplest way for a client LIBMI application to initiate a connection to the default database server and to open a database.

/*
** Use mi_open() to connect to the database passed on the
** client application command line. Close the connection with
** mi_close(). */
 
#include <mi.h>
#include <stdio.h>
 
main( mi_integer argc, char *argv[] )
{
  MI_CONNECTION  *conn;
 
/* Check incomming parameters from command line */
	if ( argc != 2 )
		{
		printf(stderr, "Usage:%s <db name>\n", argv[0]);
		exit(2);
		}
 
/* Open a connection from client LIBMI application to 
** database server.
**                   database = parameter on command line
**                   user = operating-system user account which is
**                                        running this application
**                   password = default specified for this user */
	conn = mi_open(argv[1], NULL, NULL);
 
/* If connection descriptor is NULL, there was an error
** attempting to connect to the database server and database
** specified.  Exit application. */
	if ( NULL == conn )
		{
		fprintf(stderr, "Cannot open database: %s\n",
			argv[1]);
		exit(3);
		}

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

/* Valid connection has occurred. Close the connection
** and exit the application. */
	mi_close(conn);
	exit(0);
}

In this example, the name of the database to be opened is passed on the command line. The user_name and the user_password arguments to mi_open() are both passed as NULL, which indicates that mi_open() uses the default user and password.

To exercise more control over which connection to establish, a client LIBMI application can use the following DataBlade API functions:

1. The mi_server_connect() function establishes the connection to a specified database server.

The mi_server_connect() function obtains information about which database server to connect to from a connection-information descriptor. This function does not open a database.

2. The mi_login() function opens a specified database.

The mi_login() function obtains information about which database to open from an database-information descriptor.

These DataBlade API functions provide greater flexibility for client LIBMI applications that run against different database servers and databases. They allow you to pass information about the connection and the database through descriptors.