IIapi_connect() Function--Connect to a DBMS Server or Name Server
The IIapi_connect() function establishes a connection to a DBMS Server or the Name Server, based on the connection type, and allocates a connection handle. When connecting to the Name Server an environment handle must be provided as input.
This function returns the co_apiLevel output parameter, which specifies the level of functionality provided by OpenAPI for the current connection. If the output connection handle is not NULL after this function returns, even if an error occurs, IIapi_disconnect() or IIapi_abort() must be called to release the connection handle.
This function has the following syntax:
II_VOID IIapi_connect (IIAPI_CONNPARM *connParm);
typedef struct _IIAPI_CONNPARM
{
IIAPI_GENPARM co_genParm;
II_CHAR *co_target;
II_CHAR *co_username;
II_CHAR *co_password;
II_LONG co_timeout;
II_PTR co_connHandle;
II_PTR co_tranHandle
II_LONG co_sizeAdvise;
II_LONG co_apiLevel;
II_LONG co_type;
} IIAPI_CONNPARM;
This function has the following parameters:
co_genParm
Type: input and delayed output
co_target
Type: input
The name of the database. When connecting to a DBMS Server, this parameter cannot be NULL. It contains a NULL-terminated string naming the database to which the application will connect. When connecting to a Name Server, NULL is used for the local installation and the vnode name is used for a remote installation.
The syntax of the target name is:
[node_id::]dbname[/svr_class]
co_username
Type: input
The name of the user connecting to the server. This parameter contains a NULL-terminated string, which is the user name authorized to connect to the server.
If this parameter is NULL, a default user name will be used and co_password should also be NULL.
co_password
Type: input
A NULL-terminated string containing the password for the user specified in co_username. If co_username is NULL, this parameter should be NULL as well.
If connecting to the Name Server, this parameter is not required if the current user has the NET_ADMIN privilege.
co_timeout
Type: input
Specifies the maximum time in milliseconds to wait for a connection to be established. A value of -1 is used if a timeout is not desired.
Support for timeouts is platform-dependent. If timeouts are not supported, all values are treated the same as -1.
co_connHandle
Type: input and immediate output
Input
Specifies a connection handle returned by IIapi_setConnectParam(), an environment handle returned by IIapi_initialize(), or NULL.
Output
Specifies the connection handle identifying the connection for subsequent OpenAPI function calls that invoke query statements and transactions within the context of this connection.
co_tranHandle
Type: input and immediate output
Specifies a transaction ID handle that can be used to re-connect to a distributed transaction, obtained from IIapi_registerXID(), as input. This parameter (input and output) is usually NULL. A transaction handle for the distributed transaction is returned.
co_sizeAdvise
Type: delayed output
Specifies the advised buffer size for long varchar or long byte segment sizes used within this connection.
co_apiLevel
Type: delayed output
Specifies the OpenAPI level of functionality supported by the server for the connection. Valid values for this parameter are:
IIAPI_LEVEL_0
Specifies level 0. All level 1 data types are supported except the following:
IIAPI_DEC_TYPE
IIAPI_BYTE_TYPE
IIAPI_VBYTE_TYPE
IIAPI_LBYTE_TYPE
IIAPI_LVCH_TYPE
IIAPI_LEVEL_1
Specifies level 1. All level 2 data types are supported except the National Character Set data types:
IIAPI_NCHA_TYPE
IIAPI_NVCH_TYPE
IIAPI_LNVCH_TYPE
IIAPI_LEVEL_2
Specifies level 2. (Requires initialization at IIAPI_VERSION_3.) All level 3 data types are supported except eight-byte integers (bigint):
IIAPI_INT_TYPE with length 8
IIAPI_LEVEL_3
Specifies level 3. (Requires initialization at IIAPI_VERSION_4.) All level 4 data types are supported except ANSI date/time types:
IIAPI_DATE_TYPE
IIAPI_TIME_TYPE
IIAPI_TMWO_TYPE
IIAPI_TMTZ_TYPE
IIAPI_TS_TYPE
IIAPI_TSWO_TYPE
IIAPI_TSTZ_TYPE
IIAPI_INTYM_TYPE
IIAPI_INTDS_TYPE
IIAPI_LEVEL_4
Specifies level 4. (Requires initialization at IIAPI_VERSION_5.) All level 5 data types are supported except Blob/Clob locator types:
IIAPI_LCLOC_TYPE
IIAPI_LBLOC_TYPE
IIAPI_LNLOC_TYPE
IIAPI_LEVEL_5
Specifies level 5. (Requires initialization at IIAPI_VERSION_6.) All level 6 capabilities and data types are supported except batch processing, positional database procedure parameters, and the Boolean type IIAPI_BOOL_TYPE.
IIAPI_LEVEL_6
Specifies level 6. (Requires initialization at IIAPI_VERSION_7.) All level 7 data types are supported except the spatial types:
IIAPI_GEOM_TYPE
IIAPI_POINT_TYPE
IIAPI_MPOINT_TYPE
IIAPI_LINE_TYPE
IIAPI_MLINE_TYPE
IIAPI_POLY_TYPE
IIAPI_MPOLY_TYPE
IIAPI_NBR_TYPE
IIAPI_GEOMC_TYPE
IIAPI_LEVEL_7
Specifies level 7. (Requires initialization at IIAPI_VERSION_8.) All level 8 data types are supported except the IP types:
IIAPI_IPV4_TYPE
IIAPI_IPV6_TYPE
IIAPI_LEVEL_8
Specifies level 8. (Requires initialization at IIAPI_VERSION_9.) All level 9 capabilities and data types are supported except gq_rowCountEx in IIAPI_GETQINFOPARM and the extended spatial types.
IIAPI_LEVEL_9
Specifies level 9. (Requires initialization at IIAPI_VERSION_10.) All level 10 data types are supported except the UUID type IIAPI_UUID_TYPE.
IIAPI_LEVEL_10
Specifies level 10. (Requires initialization at IIAPI_VERSION_11.) All data types and capabilities in this guide are supported.
co_type
Type: input
Specifies the connection type. Its value is one of the following:
IIAPI_CT_NS
Establishes a connection to the Name Server.
IIAPI_CT_SQL
Establishes a connection to a relational DBMS Server.
This parameter is ignored (IIAPI_CT_SQL assumed) if co_connHandle is NULL or is a connection handle that was created with a NULL environment handle.