Handles
The handles to these storage areas for OpenAPI object information are returned to the application. The application then uses them in subsequent calls to OpenAPI functions to identify the objects.
An API function may allocate a handle even if the requested action fails (for example, a connect request may fail with an invalid password and still return a connection handle). In these cases, the associated OpenAPI function that releases the handle must still be called to release the resources associated with the handle and the failed request.
Types of Handles
There are several main types of handles:
Environment Handle
Identifies storage for information about user configuration settings. An application requests an environment handle with the IIapi_initialize() function by setting the in_version parameter to IIAPI_VERSION_2 (or higher). The application can then make various user configuration settings using the IIapi_setEnvParam() function.
The environment handle configuration settings are used when formatting data using the IIapi_formatData() function. The settings are also inherited by connections opened in the context of the environment by providing the environment handle as an input parameter to the IIapi_connect() or IIapi_setConnectParam() functions. Environment handle resources are released with the IIapi_releaseEnv() function.
Connection handle
Identifies storage for information about a specific connection to a database. An application requests a connection handle with the IIapi_connect() or the IIapi_setConnectParam() functions. The application then specifies the handle whenever it issues requests within the context of the connection. When the application no longer needs the connection, it releases the handle with the IIapi_disconnect() function.
Transaction handle
Identifies storage for information about a specific transaction. An application requests a transaction handle with the IIapi_query(), IIapi_autoCommit(), or IIapi_xaStart() function. The application then specifies the handle whenever it issues requests within the context of the transaction. When the application needs to end the transaction, it releases the handle with the IIapi_commit(), IIapi_rollback(), IIapi_autoCommit(), or IIapi_xaEnd() function.
Statement handle
Identifies storage for information about a specific query statement. An application requests a statement handle with the IIapi_query() function. The application then specifies the handle whenever it issues requests within the context of the statement. When the application no longer needs the statement handle, it releases it with the IIapi_close() function.
Event handle
Identifies storage for information about a specific database event retrieval. An application requests an event handle with the IIapi_catchEvent() function. The application then specifies this handle whenever it issues requests within the context of the database event registration. When the application no longer needs the event handle, it releases it with the IIapi_close() function.
Last modified date: 08/14/2024