IIapi_initialize() Function--Initialize OpenAPI to a Specified Input Version
The IIapi_initialize() function prepares OpenAPI for operation. This function allocates an environment handle and returns it to the application. IIapi_initialize() must be called before the application performs any memory allocation and OpenAPI functions. When IIapi_initialize() completes, the application can begin issuing other OpenAPI functions. This function can be called more than once, but each call requires a corresponding call to IIapi_terminate().
The application specifies the OpenAPI interface version used by the application when calling this function. For version IIAPI_VERSION_1, a single default environment is used as the context for server connections (the returned environment handle is set to NULL). For version IIAPI_VERSION_2 (and higher), a new environment handle is allocated and returned to the application. The application can select environment settings by providing the environment handle as input to IIapi_setEnvParam(). The application can also make connections utilizing the environment settings by providing the environment handle as input to IIapi_setConnectParam() or IIapi_connect(). The environment handle must be released by calling IIapi_releaseEnv().
This function has the following syntax:
II_VOID IIapi_initialize (IIAPI_INITPARM *initParm);
typedef struct _IIAPI_INITPARM
{
II_LONG in_timeout;
II_LONG in_version;
IIAPI_STATUS in_status;
II_PTR in_envHandle;
} IIAPI_INITPARM;
This function has the following parameters:
in_timeout
Type: input
Specifies the maximum time in milliseconds to wait for OpenAPI initialization to occur. 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.
in_version
Type: input
The OpenAPI interface version being used by the application. Any version of OpenAPI can operate correctly with applications coded and compiled for previous versions of OpenAPI. Its value is one of the following:
IIAPI_VERSION_1
Specifies the initial version of OpenAPI.
IIAPI_VERSION_2
Specifies a version that supports an environment handle, which identifies storage for information about a specific environment setup.
IIAPI_VERSION_3
Indicates support for the National Character Set data types:
• IIAPI_NCHA_TYPE
• IIAPI_NVCH_TYPE
• IIAPI_LNVCH_TYPE
IIAPI_VERSION_4
Indicates support for eight-byte integers (bigint): IIAPI_INT_TYPE.
IIAPI_VERSION_5
Indicates support for 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_VERSION_6
Indicates support for Blob/Clob locator types:
• IIAPI_LCLOC_TYPE
• IIAPI_LBLOC_TYPE
• IIAPI_LNLOC_TYPE
IIAPI_VERSION_7
Indicates support for batch processing, positional database procedure parameters, and the Boolean type: IIAPI_BOOL_TYPE
IIAPI_VERSION_8
Indicates support for 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_VERSION_9
Indicates support for the IP types:
• IIAPI_IPV4_TYPE
• IIAPI_IPV6_TYPE
IIAPI_VERSION_10
Indicates support for 8 byte row counts and the extended spatial types.
IIAPI_VERSION_11
Indicates support for the UUID type: IIAPI_UUID_TYPE
in_status
Type: output
The status of the function upon its return. Its value is one of the following:
• IIAPI_ST_SUCCESS
• IIAPI_ST_OUT_OF_MEMORY
• IIAPI_ST_FAILURE
in_envHandle
Type: output
Specifies the environment handle returned to the application for the OpenAPI if the version being used by the application is IIAPI_VERSION_2.
The value is NULL if the OpenAPI version being used by the application is IIAPI_VERSION_1.