Establishing a Client Connection

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

Establishing a Client Connection

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

The mi_open( ) function
The mi_server_connect( ) function

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.

Memory Duration	Memory Operation	Function Name
For the duration of the session	Constructor	mi_open( ), mi_server_connect( )
For the duration of the session	Destructor	mi_close( )

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.

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

Connections with mi_open( )

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.

mi_open( ) Argument	Purpose	Default Used When Argument is NULL
Database name	The name of the database to open	None
User account name	The name of the login account for the user who is to open the database This account must be valid on the server computer.	The name of the system-defined user account (See Table 48.)
Account password	The password of the login account for the user who is to open the database This account must be valid on the server computer.	The password of the system-defined user account (See Table 48.)

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.

Connections with mi_server_connect( )

To exercise more control over which connection to establish, a client LIBMI application can use mi_server_connect( ), which establishes a 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.

This DataBlade API function provides greater flexibility for client LIBMI applications that run against different database servers. You can pass information about the connection through descriptors.