The mi_open() function

The mi_open() function establishes a connection to a database server.

Syntax

MI_CONNECTION *mi_open(db_name, user_name, user_passwd)
   const char *db_name;
   const char *user_name;
   const char *user_passwd;
db_name
The name of the database to open.
user_name
The name of the user account on the server computer.
user_passwd
The account password.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_open() function obtains a connection descriptor for a connection. This function is a constructor function for a connection descriptor. The DataBlade® API module can pass the new connection descriptor to subsequent routines that require a connection. The mi_open() function also initializes the DataBlade API when this function is the first DataBlade API function in a client LIBMI application or a C UDR.

Server only: For a C UDR, the mi_open() function establishes a UDR connection, which gives the UDR access to the session in which the SQL statement that initiated the UDR executed. To open a UDR connection, pass all three arguments to mi_open() as the NULL-valued pointers. The mi_open() function allocates a new connection descriptor in the PER_STMT_EXEC memory duration.

In a C UDR, do not specify the name of a database or user account to the mi_open() function. If you do not provide the three arguments as NULL-valued pointers, mi_open() fails but does not generate a message.

Client only: For a client LIBMI application, the mi_open() function establishes a client connection to the default database server and opens the db_name database. You can also specify the user account with the user_name and user_passwd arguments. The establishment of a client connection begins a session. The mi_open() function allocates a new connection descriptor that is valid until the end of the session.
If a client LIBMI application sets default database parameters with mi_set_default_database_info(), mi_open() uses these defaults when it receives NULL-valued pointers as arguments. Otherwise, mi_open() uses the following default values.
The mi_open() argument
Default value when argument is NULL
Database name
None
User name
The name of the user login account that is running the executable file
Password
The password of the user account that is running the executable file

If the client LIBMI application uses a shared-memory communication, it can establish only one connection per application.

The mi_open() function uses the default connection parameters to establish a client connection. To specify a nondefault system name for a client session, call the mi_sysname() function before the call to mi_open().
Restriction: Do not specify the system name in the format “dbname@servername” within the “dbname” argument of the mi_open() function. Instead, call the mi_sysname() function before mi_open().

Return values

An MI_CONNECTION pointer
A pointer to the connection descriptor for the newly established connection.
NULL
The function was not successful.