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

Using Connection Parameters

To indicate which database server the client LIBMI application needs to connect to, the application uses connection parameters. The DataBlade API provides a connection-information descriptor, MI_CONNECTION_INFO, to access connection parameters. This data type 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. Table 45 shows the fields in the connection-information descriptor.

Table 45. Fields in the Connection-Information Descriptor
Field Data Type Description
server_name char * The name of the default database server

This field corresponds to the value of the INFORMIXSERVER environment variable.
server_port mi_integer This value is ignored. It must always be set to zero (0).

A client LIBMI application does not need to specify the server port. It only needs to specify a database server by its name (the server_name field).
locale char * In a C UDR: The name of the server locale

This field corresponds to the SERVER_LOCALE environment variable (as set on the computer with the database server).

In a client LIBMI application: the name of the database locale

This field corresponds to the DB_LOCALE environment variable (as set on the computer with the client LIBMI application).
reserved1 mi_integer Unused
reserved2 mi_integer Unused

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.

Connection-Parameter Task DataBlade API Function
Access the default connection parameters to determine the database server for the connection mi_set_default_connection_info( ), mi_get_default_connection_info( )
Obtain current connection parameters for an open connection mi_get_connection_info( )

Establishing Default Connection Parameters

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:

System-Default Connection Parameters

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.

Table 46 shows the system-default connection parameters that the database server uses to establish a connection.

Table 46. System-Default Connection Parameters
System-Default Connection Parameter System-Default Connection Value
Database server name INFORMIXSERVER environment variable
(Server) Server locale SERVER_LOCALE environment variable or default locale (en_us)
(Client) Database locale DB_LOCALE environment variable or default locale (en_us)

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.

To use the default database server, initialize the server_name field to a NULL-valued pointer and server_port to 0.

User-Defined Connection Parameters

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 Table 50. 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
  1. Allocate a connection-information descriptor.
  2. Fill the fields of the connection-information descriptor with the default connection parameters you need.

    To change the database server, specify a value for server_name. Any non-zero value for the server_port field is ignored. If you do not set a particular field, the database server uses the system-default value in Table 46 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 obtain 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.

Server Only

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 UDR.

End of Server Only

Obtaining Current Connection Parameters

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.

Server Only

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

End of Server Only
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]