Informix DataBlade API Programmer's Manual Establishing a Connection

Before a client LIBMI application can establish a connection, it must initialize the connection with the name of the database server and database to which it needs to connect. This initialization occurs in the following steps.

To indicate which database server it needs to connect to, the client LIBMI application uses connection parameters. The DataBlade API provides a connection-information descriptor, MI_CONNECTION_INFO, to access connection parameters. This data structure is similar in concept to a file descriptor in UNIX. It identifies the database server for a particular session.

Unlike most DataBlade API structures, the connection-information descriptor is not an opaque C data structure. To access connection parameters, you must allocate a connection-information descriptor and directly access its fields. Figure 7-1 shows the fields in the connection-information descriptor.

The milib.h header file defines the MI_CONNECTION_INFO structure.

With the connection-information descriptor, you can use the following DataBlade API functions to perform the connection-parameter tasks.

The default connection parameters identify to which database server to connect. Before you establish a connection, determine which of the following connection parameters to use:

• The system-default connection parameters
• Default connection parameters that you specify

The database server obtains values for the system-default connection parameters from the execution environment of the client LIBMI application. When you use system-default connection parameters, you enable your application to be portable across client/server environments. However, before the application begins execution, you must ensure that the client/server environment is correctly initialized.

Figure 7-2 shows the system-default connection parameters that the database server uses to establish a connection.

The system-default connection parameters provide connection information for all connections made within a client LIBMI application unless you explicitly override them within the application.

The database server obtains values for the connection parameters from the connection-information descriptor. The database server initializes the connection-information descriptor with the system-default connection parameters in Figure 7-2 on page 7-8. You can initialize your own connection-information descriptor to override the system-default connection parameters. When you override system-default connection parameters, you enable your application to have connection information that is independent of the client/server environment in which it runs.

To override the system-default connection parameters, follow these steps:

1. Allocate a connection-information descriptor.
2. Fill the fields of the connection-information descriptor with the default connection parameters you need.

If you do not set a particular field, the database server uses the system-default value in Figure 7-2 on page 7-8 for the associated connection parameter.

3. Pass a pointer to this connection-information descriptor to the mi_set_default_connection_info() function.

The user-defined connection parameters provide connection information for all connections made within a client LIBMI application after these functions execute (unless the functions are called again to set new default values).

You can examine existing default connection parameters with the mi_get_default_connection_info() function. This function populates a user-defined connection-information descriptor with the current default connection parameters.

In a C UDR, mi_get_default_connection_info() obtains the same information as mi_get_connection_info(). The mi_set_default_connection_info() function is ignored when it is used in a user-defined routine.

To obtain connection parameters associated with an open connection, use the mi_get_connection_info() function. This function populates a user-defined connection-information descriptor with values from the specified open connection.

The mi_get_connection_info() function is valid when it is used in a C UDR. For more information, see Accessing the Session Environment.

To indicate which database it needs to connect to, the client LIBMI application uses database parameters. The DataBlade API provides a database-information descriptor, MI_DATABASE_INFO, to access database parameters. This data structure identifies the database for a particular session.

Unlike most DataBlade API structures, the database-information descriptor is not an opaque C data structure. To access database information, you must allocate a database-information descriptor and directly access its fields. Figure 7-3 shows the fields in the database-information descriptor.

The milib.h header file defines the MI_DATABASE_INFO structure.

With the database-information descriptor, you can use the following DataBlade API functions to perform the database-parameter tasks.

Establishing Default Database Parameters

The default database parameters identify the database and user for the connection. Before you establish a connection, you can determine which of the following database parameters to use:

• The system-default database parameters
• Default database parameters that you specify

The database server obtains values for the system-default database parameters from the execution environment of the client LIBMI application. When you use system-default database parameters, you enable your application to be portable across client/server environments. However, you must ensure that the client/server environment is correctly initialized to provide the system-default values.

Figure 7-4 shows the system-default database parameters that the database server uses to open a database.

The system-default database parameters provide database information for all connections made within a client LIBMI application unless you explicitly override them within the application.

The database server obtains values for the database parameters from the database-information descriptor. The database server initializes the database-information descriptor with the system-default database parameters in Figure 7-4 on page 7-12. You can initialize your own database-information descriptor to override the default database parameters. When you override system-default database parameters, you enable your application to have database information that is independent of the client/server environment in which it runs.

To override the system-default database parameters, follow these steps:

1. Allocate a database-information descriptor.
2. Fill the fields of the database-information descriptor with the default database parameters you need.

If you do not set a particular field, the database server uses the system-default value in Figure 7-4 on page 7-12 for the associated database parameter.

3. Pass a pointer to this database-information descriptor to the mi_set_default_database_info() function.

The user-defined database parameters provide database information for all connections made within a client LIBMI application after these functions execute (unless the functions are called again to set new default values).

You can examine existing default database parameters with the mi_get_default_database_info() function. This function populates a user-defined database-information descriptor with the current default database parameters.

In a C UDR, mi_get_default_database_info() obtains the same information as mi_get_database_info(). The mi_set_default_database_info() function is ignored.

To obtain database parameters associated with an open connection, use the mi_get_database_info() function. This function populates a user-defined database-information descriptor with values from the specified open connection.

The mi_get_database_info() function is valid with a C UDR.

The parameter-information descriptor, MI_PARAMETER_INFO, allows you to set the following session parameters for the client LIBMI application:

• Disables invocation of callbacks
• Enables checking of pointers

Unlike most DataBlade API structures, the parameter-information descriptor is not an opaque C data structure. To access session-parameter information, you must directly access the fields of a parameter-information descriptor that you allocate. Figure 7-5 shows the fields in the MI_PARAMETER_INFO structure.

The milib.h header file defines the MI_PARAMETER_INFO structure.

Before you establish a connection, you can determine which of the following session parameters to use:

• The system-default session parameters
• Default session parameters that you specify

When the database server establishes a connection, it uses the values in Figure 7-6 as the system-default session parameters.

The system-default session parameters provide session-parameter information for all connections made within a client LIBMI application unless you explicitly override them within the application.

The database server obtains values for the session parameters from the parameter-information descriptor. The database server initializes the parameter-information descriptor with the system-default session parameters in page 7-14. To override these system-default values, you can initialize your own parameter-information descriptor to set session parameters.

The following DataBlade API functions access default session parameters for a client LIBMI application.

To override the system-default session parameters, follow these steps:

1. Allocate a parameter-information descriptor.
2. Fill the fields of the parameter-information descriptor with the default session parameters you need.

If you do not set a particular field, the database server uses the system-default value in Figure 7-6 on page 7-14 for the associated session parameter.

3. Pass a pointer to this parameter-information descriptor to the mi_set_parameter_info() function.

You can examine existing session parameters with the mi_get_parameter_info() function. This function populates a user-defined parameter-information descriptor with the current session parameters.

The following example shows one way to set default connection parameters. Assume that the system-default connection parameters are as follows.

The following code fragment uses DataBlade API functions to change some of the default system values.

extern void MI_PROC_CALLBACK all_callback();
MI_CONNECTION							*conn;
MI_CONNECTION_INFO							conn_info;
MI_DATABASE_INFO							db_info;

/* Initialize DataBlade API */
mi_register_callback(conn, MI_All_Events, all_callback,
	NULL, NULL);

/* Assign default connection parameter in the 
** connection-information descriptor */
conn_info.server_name = "beth";
conn_info.server_port = 143;

/* Set default connection parameters for the application */
if ( mi_set_default_connection_info(&conn_info) == MI_ERROR )
		printf("FAILED: 
mi_set_default_connection_info()\n");

/* Assign default database parameters in the 
** database-information descriptor */
db_info.user_name = "miadmin";
db_info.database_name = "template1";
db_info.password = NULL;

/* Set default database parameters for the application */
if ( mi_set_default_database_info(&db_info) == MI_ERROR )
		printf("FAILED: mi_set_default_database_info()\n");

/* Get default connection and database parameters for
** application */
mi_get_default_connection_info(&conn_info);
mi_get_default_database_info(&db_info);

/* Make sure the right database server is set as the default */
if ( strcmp("beth", conn_info.server_name) != 0 )
	printf("FAILED: got server_name %s, should be beth\n",
		conn_info.server_name);

/* Connect to database server 'beth' */
conn = mi_server_connect(&conn_info);
if ( conn == NULL )
	printf("FAILED: CONNECT to beth\n");
else
	{
	printf("OK: connected to %s\n", conn_info.server_name);

	/* log in to "template1" database as user "miadmin" */
	if ( mi_login(conn, &db_info) != MI_ERROR )
		printf("OK: connected to db %s\n",
			db_info.database_name);
	else
		printf("FAILED: connect to db %s\n",
			db_info.database_name);
}

Once these new defaults are established, the application calls mi_server_connect() to request a connection to the beth database server. If this request is successful, the application opens the template1 database with mi_login(). For more information on mi_server_connect(), see Connections with mi_server_connect() and mi_login(). For a description of the all_callback() function, see Creating an All-Events Callback.