SQLAllocHandle--Asignar descriptor de contexto

Finalidad

SQLAllocHandle() asigna descriptores de contexto de entorno, de conexión o de sentencia.

Esta función es una función genérica para asignar descriptores de contexto que sustituye a las funciones de la versión 2 desaprobadas, SQLAllocConnect(), SQLAllocEnv() y SQLAllocStmt().

Sintaxis

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

Argumentos de la función

Tabla 30. Argumentos de SQLAllocHandle

Uso

SQLAllocHandle() se utiliza para asignar descriptores de contexto de entorno, de conexión y de sentencia, tal como se describe a continuación.

Una aplicación puede asignar al mismo tiempo varios descriptores de contexto de sentencia.

Si la aplicación invoca SQLAllocHandle() con *OutputHandlePtr establecido en un descriptor de entorno, de conexión o de sentencia que ya existe, CLI de DB2 sobreescribe la información asociada al descriptor de contexto. CLI de DB2 no comprueba si el descriptor de contexto entrado en *OutputHandlePtr ya está en uso, ni comprueba el contenido anterior de un descriptor de contexto antes de sobreescribirlo.

Para DB2 Everyplace, todos los descriptores de contexto, excepto el descriptor de sentencia, son descriptores de contexto ficticios y no llevan información utilizable.

El descriptor de sentencia proporciona acceso a información sobre una sentencia, tal como mensajes de error, e información de estado para el proceso de sentencias de SQL. Para solicitar un descriptor de sentencia, la aplicación se conecta a una fuente de datos y luego invoca SQLAllocHandle() antes de someter sentencias de SQL. En esta llamada, HandleType se debe establecer en SQL_HANDLE_STMT y InputHandle se debe establecer en el descriptor de conexión devuelto por la llamada a SQLAllocHandle() que hizo que se asignara ese descriptor de contexto. CLI de DB2 asigna el descriptor de sentencia, asocia el descriptor de sentencia a la conexión especificada y devuelve en *OutputHandlePtr el valor del descriptor de contexto asociado. La aplicación pasa el valor de *OutputHandlePtr en todas las llamadas subsiguientes que necesiten un descriptor de sentencia.

Cuando una aplicación finaliza, se liberan todos los recursos de DB2 Everyplace asignados para la aplicación, por lo que los descriptores de contexto utilizados por la aplicación dejan de ser válidos.

Para DB2 Everyplace, no existe ningún descriptor asociado a un descriptor de sentencia con atributos que puedan ser cambiados por una aplicación.

Cuando se esté utilizando DB2 Everyplace con Visual Basic y la interfaz CLI/ODBC de DB2 Everyplace, debe llamar de manera explícita las funciones de CLI correlacionadas/subyacentes definidas en sqlcli.h. Por ejemplo, una llamada a SQLAllocHandle() falla. Pero la llamada a SQLAllocHandleVer(SQL_HANDLE_STMT, hdbc, hstmt, DB2eVersion) será satisfactoria.

Códigos de retorno

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_INVALID_HANDLE
• SQL_ERROR

Cuando se asigna un descriptor de contexto que no sea un descriptor de contexto de entorno, si SQLAllocHandle() devuelve SQL_ERROR, establece OutputHandlePtr en SQL_NULL_HENV, SQL_NULL_HDBC o SQL_NULL_HSTMT, en función del valor de HandleType, a menos que el argumento de salida sea un puntero nulo. La aplicación puede entonces obtener información adicional a partir de la estructura de datos de diagnóstico asociada al descriptor de contexto en el argumento InputHandle.

Diagnósticos

Tabla 31. SQLSTATE de SQLAllocHandle

Consulta relacionada

• Clave para las descripciones de funciones de CLI de DB2
• Resumen de las funciones de CLI de DB2
• SQLExecDirect--Ejecutar una sentencia directamente
• SQLFreeHandle--Liberar recursos de descriptor de contexto