SQLAllocHandle

SQLAllocHandle

SQLAllocHandle allocates and initializes the memory for the environment, connection, and statement handles.

Syntax

SQLRETURN  SQLAllocHandle (
    SQLSMALLINT     HandleType,
    SQLHANDLE       InputHandle,
    SQLHANDLE *     OutputHandlePtr );

Arguments

Data Type	Argument	In/Output	Description
SQLSMALLINT	HandleType	Input	One of the following handle type is allocated: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT
SQLHANDLE	InputHandle	Input	If the input HandleType is SQL_HANDLE_ENV, InputHandle will be SQL_Null_Handle. Or if the input HandleTyp is SQL_HANDLE_DBC, it will be the environment handle. In case of SQL_HANDLE_STMT, it will be the connection handle.
SQLHANDLE *	OutputHandlePtr	Output	The pointer of the allocated handle

Return Values

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

Description

SQLAllocHandle() allocates the environment, connection and statement handles to be described in the next paragraph.

This function will replace SQLAllocEnv(), SQLAllocConnect() and SQLAllocStmt() functions. To request the environment handle, an application calls SQLAllocHandle() of which HandleTyp is SQL_HANDLE_ENV and input handle is SQL_Null_Handle. To request the connection handle, an application must call SQLAllocHandle() of which HandleTyp is SQL_HANDLE_DBC and the input handle must be a valid environment handle. To request the statement handle, an application must call SQLAllocHandle() of which HandleTyp is SQL_HANDLE_STMT and the input handle must be a valid connection handle.

One application can allocate multiple environment, connection, and statement handles at one time. However, several environment, connection or statement handle cannot be used at the same time on another thread of one process.

Allocation of the Environment Handles

The environment handle provides global information about the validity or activation of the connection handle

To request an environment handle, an application must call SQLAllocHandle() of which HandleTyp is SQL_HANDLE_ENV and input handle is SQL_Null_Handle. The Altibase CLI driver allocates the memory needed for environment information and returns the handle related to the *OutputHandle. An application sends the *OutputHandle value to the subsequent callings that require the environment handles.

Allocation of the Connection Handles

The connection handle provides information about the validity of the statement handle or activation of the transaction.

To request the connection handle, an application calls SQLAllocHandle() of which HandleType is SQL_HANDLE_DBC. InputHandle argument calls SQLAllocHandle() and is set as the returned environment handle. The Altibase CLI driver allocates the memory necessary for the connection and returns the handle values related to the *OutputHandle. An application sends the *OutputHandle to the subsequent callings that require the connection handle.

Allocation of the Statement handles

The statement handle provides command information such as error messages about processing a SQL statement and status state.

To request the statement handle, an application connects to the database and calls SQLAllocHandle() before sending a SQL statement. For this calling, the HandleType must be set as SQL_HANDLE_STM and the I argument must be set as a connection handle to be returned by calling SQLAllocHandle(). The Altibase CLI driver allocates the memory necessary for the command, connects the statement handle, and returns the handle related to OutputHandle. An application sends *OutputHandle* value to the subsequent callings that require the statement handle.

Diagnosis

SQLSTATE	Description	Comments
HY000	General error
HY001	Memory allocation error	Failed to allocate the memory for the explicit handle
HY009	Invalid argumnets used (null pointer)	OutputHandlePtr is a NULL pointer

Related Functions

SQLExecDirect
SQLExecute
SQLFreeHandle
SQLPrepare
SQLSetConnectAttr
SQLSetEnvAttr
SQLSetStmtAttr

Example

< Refer to: $ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp >

/* Memory allocation for the environment */
if (SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HENV, &env) != SQL_SUCCESS)
{
    printf("SQLAllocEnv error!!\n");
    return SQL_ERROR;
}

/* Memory allocation for the connection  */
if (SQLAllocHandle(SQL_HANDLE_DBC, env, &dbc) != SQL_SUCCESS)
{   
    printf("SQLAllocConnect error!!\n");
    return SQL_ERROR;
}