Función SQLAllocHandle

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92

Resumen
SQLAllocHandle asigna un entorno, conexión, instrucción o identificador de descriptor.

Sintaxis

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

Argumentos

HandleType
[Entrada] Tipo de identificador que va a asignar SQLAllocHandle. Debe ser uno de los siguientes valores:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN controlador solo lo usa el Administrador de controladores y el controlador. Las aplicaciones no deben usar este tipo de identificador. Para obtener más información sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Desarrollo de reconocimiento del grupo de conexiones en un controlador ODBC.

InputHandle
[Entrada] Identificador de entrada en cuyo contexto se va a asignar el nuevo identificador. Si HandleType es SQL_HANDLE_ENV, se SQL_NULL_HANDLE. Si HandleType es SQL_HANDLE_DBC, debe ser un identificador de entorno y, si es SQL_HANDLE_STMT o SQL_HANDLE_DESC, debe ser un identificador de conexión.

OutputHandlePtr
[Salida] Puntero a un búfer en el que se va a devolver el identificador a la estructura de datos recién asignada.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE o SQL_ERROR.

Al asignar un identificador distinto de un identificador de entorno, si SQLAllocHandle devuelve SQL_ERROR, establece OutputHandlePtr en SQL_NULL_HDBC, SQL_NULL_HSTMT o SQL_NULL_HDESC, según el valor de HandleType, a menos que el argumento de salida sea un puntero nulo. A continuación, la aplicación puede obtener información adicional de la estructura de datos de diagnóstico asociada al identificador en el argumento InputHandle .

Errores de asignación de identificadores de entorno

La asignación del entorno se produce tanto en el Administrador de controladores como en cada controlador. El error devuelto por SQLAllocHandle con un HandleType de SQL_HANDLE_ENV depende del nivel en el que se produjo el error.

Si el Administrador de controladores no puede asignar memoria para *OutputHandlePtr cuando se llama a SQLAllocHandle con un HandleType de SQL_HANDLE_ENV, o la aplicación proporciona un puntero nulo para OutputHandlePtr, SQLAllocHandle devuelve SQL_ERROR. El Administrador de controladores establece *OutputHandlePtr en SQL_NULL_HENV (a menos que la aplicación proporcione un puntero nulo, que devuelve SQL_ERROR). No hay ningún identificador con el que asociar información de diagnóstico adicional.

El Administrador de controladores no llama a la función de asignación del entorno de nivel de controlador hasta que la aplicación llama a SQLConnect, SQLBrowseConnect o SQLDriverConnect. Si se produce un error en la función SQLAllocHandle de nivel de controlador, la función SQLConnect, SQLBrowseConnect o SQLDriverConnect de nivel de controlador devuelve SQL_ERROR. La estructura de datos de diagnóstico contiene SQLSTATE IM004 (error de SQLAllocHandle del controlador). El error se devuelve en un identificador de conexión.

Para obtener más información sobre el flujo de llamadas de función entre el Administrador de controladores y un controlador, vea Función SQLConnect.

Diagnóstico

Cuando SQLAllocHandle devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con el HandleType y Handle adecuado establecido en el valor de InputHandle. SQL_SUCCESS_WITH_INFO (pero no SQL_ERROR) se puede devolver para el argumento OutputHandle . En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLAllocHandle y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

SQLAllocHandle se usa para asignar identificadores para entornos, conexiones, instrucciones y descriptores, como se describe en las secciones siguientes. Para obtener información general sobre los identificadores, vea Handles( Controladores).

Una aplicación puede asignar más de un entorno, conexión o identificador de instrucción a la vez si el controlador admite varias asignaciones. En ODBC, no se define ningún límite en el número de identificadores de entorno, conexión, instrucción o descriptor que se pueden asignar en cualquier momento. Los controladores pueden imponer un límite en el número de un determinado tipo de controlador que se puede asignar a la vez; para obtener más información, consulte la documentación del controlador.

Si la aplicación llama a SQLAllocHandle con *OutputHandlePtr establecido en un entorno, conexión, instrucción o identificador de descriptor que ya existe, el controlador sobrescribe la información asociada al identificador, a menos que la aplicación use la agrupación de conexiones (vea "Asignar un atributo de entorno para la agrupación de conexiones" más adelante en esta sección). El Administrador de controladores no comprueba si el controlador especificado en *OutputHandlePtr ya se está usando, ni comprueba el contenido anterior de un identificador antes de sobrescribirlos.

En los sistemas operativos que admiten varios subprocesos, las aplicaciones pueden usar el mismo entorno, conexión, instrucción o identificador descriptor en diferentes subprocesos. Por lo tanto, los controladores deben admitir el acceso seguro y multiproceso a esta información; una manera de lograrlo, por ejemplo, es usar una sección crítica o un semáforo. Para obtener más información sobre el subproceso, consulte Multithreading.

SQLAllocHandle no establece el atributo de entorno SQL_ATTR_ODBC_VERSION cuando se llama para asignar un identificador de entorno; la aplicación debe establecer el atributo de entorno o SQLSTATE HY010 (error de secuencia de funciones) cuando se llama a SQLAllocHandle para asignar un identificador de conexión.

En el caso de las aplicaciones compatibles con estándares, SQLAllocHandle se asigna a SQLAllocHandleStd en tiempo de compilación. La diferencia entre estas dos funciones es que SQLAllocHandleStd establece el atributo de entorno SQL_ATTR_ODBC_VERSION en SQL_OV_ODBC3 cuando se llama con el argumento HandleType establecido en SQL_HANDLE_ENV. Esto se hace porque las aplicaciones compatibles con estándares siempre son ODBC 3.x aplicaciones. Además, los estándares no requieren que se registre la versión de la aplicación. Esta es la única diferencia entre estas dos funciones; de lo contrario, son idénticos. SQLAllocHandleStd se asigna a SQLAllocHandle dentro del administrador de controladores. Por lo tanto, los controladores de terceros no tienen que implementar SQLAllocHandleStd.

Las aplicaciones ODBC 3.8 deben usar:

• SQLAllocHandle y no SQLAllocHandleStd para asignar un identificador de entorno.

• SQLSetEnvAttr para establecer el atributo de entorno de SQL_ATTR_ODBC_VERSION en SQL_OV_ODBC3_80.

Asignar un identificador de entorno

Un identificador de entorno proporciona acceso a información global, como identificadores de conexión válidos y identificadores de conexión activos. Para obtener información general sobre los identificadores de entorno, consulte Identificadores de entorno.

Para solicitar un identificador de entorno, una aplicación llama a SQLAllocHandle con un HandleType de SQL_HANDLE_ENV y un InputHandle de SQL_NULL_HANDLE. El controlador asigna memoria para la información del entorno y pasa el valor del controlador asociado en el argumento *OutputHandlePtr . La aplicación pasa el valor *OutputHandle en todas las llamadas posteriores que requieren un argumento de identificador de entorno. Para obtener más información, consulte Asignación del identificador de entorno.

En el identificador de entorno del Administrador de controladores, si ya existe un identificador de entorno de un controlador, no se llama a SQLAllocHandle con un HandleType de SQL_HANDLE_ENV en ese controlador cuando se realiza una conexión, solo SQLAllocHandle con un HandleType de SQL_HANDLE_DBC. Si el identificador de entorno de un controlador no existe en el identificador de entorno del Administrador de controladores, tanto SQLAllocHandle con un HandleType de SQL_HANDLE_ENV como SQLAllocHandle con un HandleType de SQL_HANDLE_DBC se llaman en el controlador cuando el primer identificador de conexión del entorno está conectado al controlador.

Cuando el Administrador de controladores procesa la función SQLAllocHandle con un HandleType de SQL_HANDLE_ENV, comprueba la palabra clave Trace en la sección [ODBC] de la información del sistema. Si se establece en 1, el Administrador de controladores habilita el seguimiento de la aplicación actual. Si se establece la marca de seguimiento, el seguimiento se inicia cuando se asigna el primer identificador de entorno y finaliza cuando se libera el último identificador de entorno. Para obtener más información, consulte Configuración de orígenes de datos.

Después de asignar un identificador de entorno, una aplicación debe llamar a SQLSetEnvAttr en el identificador de entorno para establecer el atributo de entorno SQL_ATTR_ODBC_VERSION. Si este atributo no se establece antes de llamar a SQLAllocHandle para asignar un identificador de conexión en el entorno, la llamada a para asignar la conexión devolverá SQLSTATE HY010 (error de secuencia de funciones). Para obtener más información, consulte Declaración de la versión ODBC de la aplicación.

Asignación de entornos compartidos para la agrupación de conexiones

Los entornos se pueden compartir entre varios componentes en un único proceso. Un entorno compartido se puede usar en más de un componente al mismo tiempo. Cuando un componente usa un entorno compartido, puede usar conexiones agrupadas, que le permiten asignar y usar una conexión existente sin volver a crear esa conexión.

Antes de asignar un entorno compartido que se pueda usar para la agrupación de conexiones, una aplicación debe llamar a SQLSetEnvAttr para establecer el atributo de entorno de SQL_ATTR_CONNECTION_POOLING en SQL_CP_ONE_PER_DRIVER o SQL_CP_ONE_PER_HENV. En este caso, se llama a SQLSetEnvAttr con EnvironmentHandle establecido en NULL, lo que hace que el atributo sea un atributo de nivel de proceso.

Una vez habilitada la agrupación de conexiones, una aplicación llama a SQLAllocHandle con el argumento HandleType establecido en SQL_HANDLE_ENV. El entorno asignado por esta llamada será un entorno compartido implícito porque se ha habilitado la agrupación de conexiones.

Cuando se asigna un entorno compartido, el entorno que se usará no se determina hasta que se llame a SQLAllocHandle con un HandleType de SQL_HANDLE_DBC. En ese momento, el Administrador de controladores intenta encontrar un entorno existente que coincida con los atributos de entorno solicitados por la aplicación. Si no existe este entorno, se crea uno como un entorno compartido. El Administrador de controladores mantiene un recuento de referencias para cada entorno compartido; el recuento se establece en 1 cuando se crea el entorno por primera vez. Si se encuentra un entorno coincidente, se devuelve el identificador de ese entorno a la aplicación y se incrementa el recuento de referencias. Un identificador de entorno asignado de esta manera se puede usar en cualquier función ODBC que acepte un identificador de entorno como argumento de entrada.

Asignar un identificador de conexión

Un identificador de conexión proporciona acceso a información como la instrucción y los identificadores de descriptor válidos en la conexión y si una transacción está abierta actualmente. Para obtener información general sobre los identificadores de conexión, consulte Identificadores de conexión.

Para solicitar un identificador de conexión, una aplicación llama a SQLAllocHandle con un HandleType de SQL_HANDLE_DBC. El argumento InputHandle se establece en el identificador de entorno devuelto por la llamada a SQLAllocHandle que asignó ese identificador. El controlador asigna memoria para la información de conexión y pasa el valor del controlador asociado de nuevo en *OutputHandlePtr. La aplicación pasa el valor *OutputHandlePtr en todas las llamadas posteriores que requieren un identificador de conexión. Para obtener más información, consulte Asignación de un identificador de conexión.

El Administrador de controladores procesa la función SQLAllocHandle y llama a la función SQLAllocHandle del controlador cuando la aplicación llama a SQLConnect, SQLBrowseConnect o SQLDriverConnect. (Para obtener más información, consulte Función SQLConnect).

Si no se establece el atributo de entorno SQL_ATTR_ODBC_VERSION antes de llamar a SQLAllocHandle para asignar un identificador de conexión en el entorno, la llamada a para asignar la conexión devolverá SQLSTATE HY010 (error de secuencia de funciones).

Cuando una aplicación llama a SQLAllocHandle con el argumento InputHandle establecido en SQL_HANDLE_DBC y también se establece en un identificador de entorno compartido, el Administrador de controladores intenta encontrar un entorno compartido existente que coincida con los atributos de entorno establecidos por la aplicación. Si no existe este entorno, se crea uno, con un recuento de referencias (mantenido por el Administrador de controladores) de 1. Si se encuentra un entorno compartido coincidente, ese identificador se devuelve a la aplicación y se incrementa su recuento de referencias.

El Administrador de controladores no determina la conexión real que se usará hasta que se llame a SQLConnect o SQLDriverConnect . El Administrador de controladores usa las opciones de conexión de la llamada a SQLConnect (o las palabras clave de conexión de la llamada a SQLDriverConnect) y los atributos de conexión establecidos después de la asignación de conexión para determinar qué conexión del grupo se debe usar. Para obtener más información, vea Función SQLConnect.

Asignar un identificador de instrucción

Un identificador de instrucción proporciona acceso a la información de instrucciones, como mensajes de error, el nombre del cursor y la información de estado para el procesamiento de instrucciones SQL. Para obtener información general sobre los identificadores de instrucciones, vea Identificadores de instrucciones.

Para solicitar un identificador de instrucción, una aplicación se conecta a un origen de datos y, a continuación, llama a SQLAllocHandle antes de enviar instrucciones SQL. En esta llamada, HandleType debe establecerse en SQL_HANDLE_STMT y InputHandle debe establecerse en el identificador de conexión devuelto por la llamada a SQLAllocHandle que asignó ese identificador. El controlador asigna memoria para la información de la instrucción, asocia el controlador de instrucciones a la conexión especificada y pasa el valor del identificador asociado de nuevo en *OutputHandlePtr. La aplicación pasa el valor *OutputHandlePtr en todas las llamadas posteriores que requieren un identificador de instrucción. Para obtener más información, vea Asignar un identificador de instrucción.

Cuando se asigna el identificador de instrucción, el controlador asigna automáticamente un conjunto de cuatro descriptores y asigna los identificadores de estos descriptores a los atributos de instrucción SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC y SQL_ATTR_IMP_PARAM_DESC. Se conocen como descriptores asignados implícitamente . Para asignar explícitamente un descriptor de aplicación, consulte la sección siguiente: "Asignar un identificador de descriptor".

Asignar un identificador de descriptor

Cuando una aplicación llama a SQLAllocHandle con un HandleType de SQL_HANDLE_DESC, el controlador asigna un descriptor de aplicación. Estos se conocen como descriptores asignados explícitamente . La aplicación dirige a un controlador para que use un descriptor de aplicación asignado explícitamente en lugar de un asignado automáticamente uno para un identificador de instrucción determinado mediante una llamada a la función SQLSetStmtAttr con el atributo SQL_ATTR_APP_ROW_DESC o SQL_ATTR_APP_PARAM_DESC. No se puede asignar explícitamente un descriptor de implementación ni se puede especificar un descriptor de implementación en una llamada de función SQLSetStmtAttr .

Los descriptores asignados explícitamente se asocian a un identificador de conexión en lugar de a un identificador de instrucción (como los descriptores asignados automáticamente). Los descriptores solo se asignan cuando una aplicación está conectada realmente a la base de datos. Dado que los descriptores asignados explícitamente están asociados a un identificador de conexión, una aplicación puede asociar un descriptor asignado explícitamente a más de una instrucción dentro de una conexión. Por otro lado, un descriptor de aplicación asignado implícitamente no se puede asociar a más de un identificador de instrucción. (No se puede asociar a ningún identificador de instrucción distinto del asignado). La aplicación puede liberar explícitamente los identificadores de descriptor asignados explícitamente o mediante una llamada a SQLFreeHandle con un HandleType de SQL_HANDLE_DESC, o implícitamente cuando se cierra la conexión.

Cuando se libera el descriptor asignado explícitamente, el descriptor asignado implícitamente se asocia de nuevo a la instrucción . (El atributo SQL_ATTR_APP_ROW_DESC o SQL_ATTR_APP_PARAM_DESC para esa instrucción se establece de nuevo en el identificador del descriptor asignado implícitamente). Esto es cierto para todas las instrucciones asociadas al descriptor asignado explícitamente en la conexión.

Para obtener más información sobre los descriptores, vea Descriptores.

Ejemplo de código

Vea Programa ODBC de ejemplo, función SQLBrowseConnect, función SQLConnect y función SQLSetCursorName.

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC