SQLAllocHandle - Allocate handle

Purpose

SQLAllocHandle() allocates any type of handle.

Syntax

SQLRETURN SQLAllocHandle (SQLSMALLINT htype,
                          SQLINTEGER ihandle,
                          SQLINTEGER *handle);

Function arguments

Table 1. SQLAllocHandle arguments
Data type	Argument	Use	Description
SQLINTEGER *	handle	Output	Pointer to the handle.
SQLINTEGER	ihandle	Input	The handle that describes the context in which the new handle is allocated; however, if htype is SQL_HANDLE_ENV, this is SQL_NULL_HANDLE.
SQLSMALLINT	htype	Input	Type of handle to allocate. Must be either SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_DESC, or SQL_HANDLE_STMT.

Usage

This function combines the functions of SQLAllocEnv(), SQLAllocConnect(), and SQLAllocStmt().

If htype is SQL_HANDLE_ENV, ihandle must be SQL_NULL_HANDLE. If htype is SQL_HANDLE_DBC, ihandle must be a valid environment handle. If htype is either SQL_HANDLE_DESC or SQL_HANDLE_STMT, ihandle must be a valid connection handle.

Return codes

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

SQL_ERROR is returned if the argument handle is a null pointer.

Table 2. SQLAllocHandle SQLSTATEs
SQLSTATE	Description	Explanation
58004	System error	Unrecoverable system error.
HY014	Too many handles	The maximum number of handles has been allocated.