| Especificación: | CLI de DB2 1.1 | ODBC 1.0 | ISO CLI |
SQLBindCol() se utiliza para asociar (enlazar) columnas de un conjunto resultante con variables de aplicación, para todos los tipos de datos C. Se transfieren datos del DBMS a la aplicación cuando se invoca SQLFetch(). Durante la transferencia de datos puede producirse una conversión de los datos.
SQLBindCol() se invoca una vez para cada columna del conjunto resultante que la aplicación necesite recuperar.
En general, SQLPrepare() o SQLExecDirect() se invocan antes que esta función y SQLFetch() se invoca después. Pueden también ser necesarios atributos de columnas antes de invocar SQLBindCol() y se pueden obtener utilizando SQLDescribeCol().
Sintaxis
SQLRETURN SQLBindCol (SQLHSTMT
StatementHandle, /* hstmt */
SQLUSMALLINT ColumnNumber, /* icol */
SQLSMALLINT TargetType, /* fCType */
SQLPOINTER TargetValuePtr, /* rgbValue */
SQLINTEGER BufferLength, /* cbValueMax */
SQLINTEGER *FAR StrLen_or_IndPtr); /* pcbValue */
Argumentos de la función
Tabla 32. Argumentos de SQLBindCol
| Tipo de datos | Argumento | Uso | Descripción |
|---|---|---|---|
| SQLHSTMT | StatementHandle | entrada | Descriptor de contexto de sentencia |
| SQLUSMALLINT | ColumnNumber | entrada | Número identificador de la columna. Las columnas están numeradas secuencialmente, de izquierda a derecha. Los números de columna comienzan en el 1. |
| SQLSMALLINT | TargetType | entrada | El tipo de datos C del número de columna ColumnNumber en el
conjunto resultante. Se da soporte a los tipos siguientes:
Si se especifica SQL_C_DEFAULT, los datos se transfieren a su tipo de datos C por omisión. |
| SQLPOINTER | TargetValuePtr | entrada/ salida (diferido) | Puntero que apunta al almacenamiento intermedio donde CLI de DB2 debe
guardar los datos de columna cuando se obtienen los datos.
Si TargetValuePtr es nulo, la columna no se enlaza. |
| SQLINTEGER | BufferLength | entrada | Tamaño, en bytes, del almacenamiento intermedio TargetValuePtr
disponible para almacenar los datos de columna.
Si TargetType denota una serie binaria o de caracteres o es SQL_C_DEFAULT, BufferLength debe ser mayor que 0 o se devuelve un error. En otro caso, este argumento no se tiene en cuenta. |
| SQLINTEGER * | StrLen_or_IndPtr | entrada/salida (diferido) | Puntero que apunta a un valor que indica el número de bytes que CLI de
DB2 puede devolver en el almacenamiento intermedio
TargetValuePtr.
SQLFetch() devuelve SQL_NULL_DATA en este argumento si el valor de datos de la columna es nulo. También puede devolverse SQL_NO_LENGTH. Consulte la sección sobre uso para obtener más información. |
Para esta función, TargetValuePtr y StrLen_or_Ind son salidas diferidas, es decir, las posiciones de memoria a las que apuntan estos punteros no se actualizan hasta que se obtiene una fila del conjunto resultante. En consecuencia, las posiciones referenciadas por estos punteros deben permanecer válidas hasta que se invoque SQLFetch(). Por ejemplo, si se invoca SQLBindCol() dentro de una función local, SQLFetch() se debe llamar desde dentro del mismo ámbito de la función o el almacenamiento intermedio TargetValuePtr debe estar asignado o declarado como estático o global.
Uso
La aplicación llama a SQLBindCol() una vez para cada columna del conjunto resultante para la que la aplicación necesite recuperar datos. Los conjuntos resultantes se generan llamando a SQLExecute() o a SQLExecDirect(). Cuando se invoca SQLFetch(), los datos de cada una de estas columnas enlazadas se colocan en la ubicación asignada (proporcionada por los punteros TargetValuePtr y StrLen_or_Ind).
Las columnas se identifican mediante un número, que se asigna secuencialmente de izquierda a derecha. Los números de columna comienzan en el 1.
El número de columnas del conjunto resultante se puede determinar invocando SQLNumResultCols().
La aplicación puede consultar los atributos de la columna (tales como el tipo de datos y la longitud) invocando primero SQLDescribeCol(). Luego, esta información se puede utilizar para asignar una ubicación de memoria, con el tipo de datos y tamaño apropiados, para indicar una conversión a otro tipo de datos.
Una aplicación puede elegir no enlazar todas las columnas, o incluso no enlazar ninguna columna. Los datos de cualquiera de las columnas también se pueden recuperar utilizando SQLGetData() una vez obtenidas las columnas enlazadas correspondientes a la fila actual.
En recuperaciones subsiguientes de datos, la aplicación puede cambiar el enlace de estas columnas o puede invocar SQLBindCol() para enlazar columnas previamente desenlazadas. El nuevo enlace no afecta a los datos ya capturados, se utiliza en la recuperación siguiente. Para desenlazar una columna individual, llame a SQLBindCol() con el puntero TargetValuePtr establecido en NULL. Para desenlazar todas las columnas, la aplicación debe invocar SQLFreeStmt().
La aplicación debe asegurarse de que se asigna suficiente almacenamiento para los datos que deben recuperarse. Si el almacenamiento intermedio debe contener datos de longitud variable, la aplicación debe asignar suficiente almacenamiento para la longitud máxima de la columna enlazada, de lo contrario se puede producir un truncamiento de los datos. Si el almacenamiento intermedio debe contener datos de longitud fija, CLI de DB2 considera que el tamaño del almacenamiento intermedio es la longitud del tipo de datos C. Si se especifica conversión de datos, ello puede afectar al tamaño de almacenamiento necesario.
Si se produce truncamiento de la serie, se devuelve SQL_SUCCESS_WITH_INFO y StrLen_or_IndPtr se establece en el tamaño real de TargetValuePtr para devolverlo a la aplicación.
Códigos de retorno
Diagnósticos
Tabla 33. SQLSTATE de SQLBindCol
| SQLSTATE | Descripción | Explicación |
|---|---|---|
| 07009 | Índice descriptor no válido. | El valor especificado para el argumento ColumnNumber excede el número máximo de columnas del conjunto resultante. |
| 40003 08S01 | Error en el enlace de comunicaciones. | El enlace de comunicaciones entre la aplicación y la fuente de datos se interrumpió antes de finalizar la función. |
| 58004 | Error inesperado del sistema. | Error no recuperable del sistema. |
| HY001 | Error de asignación de memoria. | CLI de DB2 no puede asignar la memoria necesaria para ejecutar o finalizar la función. |
| HY002 | Número de columna no válido. | El valor especificado para el argumento ColumnNumber es menor
que 0.
El valor especificado para el argumento ColumnNumber excedía el número máximo de columnas soportadas por la fuente de datos. |
| HY003 | Tipo de programa fuera de rango. | TargetType no es un tipo de datos válido ni SQL_C_DEFAULT. |
| HY013 | Error inesperado de gestión de la memoria. | CLI de DB2 no puede acceder a la memoria necesaria para ejecutar o finalizar la función. |
| HY090 | Longitud no válida de la serie de caracteres o del almacenamiento intermedio. | El valor especificado para el argumento BufferLength es menor que 1 y el argumento TargetType es SQL_C_CHAR, SQL_C_BINARY o SQL_C_DEFAULT. |
| HYC00 | Controlador no apropiado. | CLI de DB2 reconoce, pero no da soporte al tipo de datos especificado en el argumento TargetType. |
Durante la recuperación de datos pueden presentarse otros mensajes de diagnóstico referentes a las columnas enlazadas.
Restricciones
Los almacenamientos intermedios de salida deben estar alineados por palabras (igual). Muchos procesadores, como Motorola 68000, tienen reglas para la alineación por palabras y la aplicación debería alinear de manera apropiada el almacenamiento intermedio para los tipos de datos que no son caracteres.
Consulta relacionada