DB2 10.5 for Linux, UNIX, and Windows

SQLAllocHandle function (CLI) - Allocate handle

Allocates environment, connection, statement, or descriptor handles.

Note: This function replaces the deprecated ODBC 2.0 functions SQLAllocConnect(), SQLAllocEnv(), and SQLAllocStmt().

Specification:

CLI 5.0
ODBC 3.0
ISO CLI

Syntax

SQLRETURN   SQLAllocHandle (
               SQLSMALLINT       HandleType,         /* fHandleType */
               SQLHANDLE         InputHandle,        /* hInput */
               SQLHANDLE         *OutputHandlePtr);  /* *phOutput */

Function Arguments

Table 1. SQLAllocHandle arguments
Data type	Argument	Use	Description
SQLSMALLINT	HandleType	input	The type of handle to be allocated by `SQLAllocHandle()`. Must be one of the following values: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC
SQLHANDLE	InputHandle	input	Existing handle to use as a context for the new handle being allocated. If HandleType is SQL_HANDLE_ENV, this is SQL_NULL_HANDLE. If HandleType is SQL_HANDLE_DBC, this must be an environment handle, and if it is SQL_HANDLE_STMT or SQL_HANDLE_DESC, it must be a connection handle.
SQLHANDLE *	OutputHandlePtr	output	Pointer to a buffer in which to return the handle to the newly allocated data structure.

Usage

SQLAllocHandle() is used to allocate environment, connection, statement, and descriptor handles. An application can allocate multiple environment, connection, statement, or descriptor handles at any time a valid InputHandle exists.

If the application calls SQLAllocHandle() with *OutputHandlePtr set to an existing environment, connection, statement, or descriptor handle, CLI overwrites the handle, and new resources appropriate to the handle type are allocated. There are no changes made to the CLI resources associated with the original handle.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

If SQLAllocHandle() returns SQL_INVALID_HANDLE, it will set OutputHandlePtr to SQL_NULL_HENV, SQL_NULL_HDBC, SQL_NULL_HSTMT, or SQL_NULL_HDESC, depending on the value of HandleType, unless the output argument is a null pointer. The application can then obtain additional information from the diagnostic data structure associated with the handle in the InputHandle argument.

Diagnostics

Table 2. SQLAllocHandle SQLSTATEs
SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
08003	Connection is closed.	The HandleType argument was SQL_HANDLE_STMT or SQL_HANDLE_DESC, but the connection handle specified by the InputHandle argument did not have an open connection. The connection process must be completed successfully (and the connection must be open) for CLI to allocate a statement or descriptor handle.
HY000	General error.	An error occurred for which there was no specific SQLSTATE. The error message returned by `SQLGetDiagRec()` in the *MessageText buffer describes the error and its cause.
HY001	Memory allocation failure.	DB2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY013	Unexpected memory handling error.	The HandleType argument was SQL_HANDLE_DBC, SQL_HANDLE_STMT, or SQL_HANDLE_DESC; and the function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY014	No more handles.	The limit for the number of handles that can be allocated for the type of handle indicated by the HandleType argument has been reached, or in some cases, insufficient system resources exist to properly initialize the new handle.
HY092	Option type out of range.	The HandleType argument was not one of: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC

Restrictions

None.

Example

  SQLHANDLE henv; /* environment handle */
  SQLHANDLE hdbc; /* connection handle */
  SQLHANDLE hstmt; /* statement handle */
  SQLHANDLE hdesc; /* descriptor handle */
  
  /* ... */
  
  /* allocate an environment handle */
  cliRC = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
  
  /* ... */
  
  /* allocate a database connection handle */
  cliRC = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
  
  /* ... */
  /* connect to database using hdbc */
  /* ... */
  
  /* allocate one or more statement handles */
  cliRC = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);

  /* ... */
  /* allocate a descriptor handle */
  cliRC = SQLAllocHandle(SQL_HANDLE_DESC, hstmt, &hdesc);