SQLGetData--Obtener datos de una columna

Finalidad

Especificación: CLI de DB2 1.1 ODBC 1.0 ISO CLI

SQLGetData() recupera datos de una columna individual en la fila actual del conjunto resultante. Esta función es una alternativa al uso de SQLBindCol(), que se utiliza para transferir datos directamente a variables de aplicación en cada llamada a SQLFetch().

Se debe invocar SQLFetch() antes de SQLGetData().

Después de llamar a SQLGetData() para cada columna que sea necesario, se llama a SQLFetch() para recuperar la fila siguiente.

Sintaxis 

SQLRETURN   SQLGetData       (
                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 66. Argumentos de SQLGetData

Tipo de datos Argumento Uso Descripción
SQLHSTMT StatementHandle entrada Descriptor de contexto de sentencia.
SQLUSMALLINT ColumnNumber entrada Número de columna para el que se solicita la obtención de datos. Las columnas del conjunto resultante están numeradas secuencialmente. Los números de columna comienzan en el 1.
SQLSMALLINT TargetType entrada El tipo de datos C de la columna identificada por ColumnNumber. Se da soporte a los tipos siguientes:

SQL_C_BINARY

SQL_C_BIT

SQL_C_CHAR

SQL_C_DOUBLE

SQL_C_FLOAT

SQL_C_LONG

SQL_C_SHORT

SQL_C_TYPE_DATE

SQL_C_TYPE_TIME

SQL_C_TYPE_TIMESTAMP

SQL_C_TINYINT

Si se especifica SQL_C_DEFAULT, los datos se convierten a su tipo de datos C por omisión.

SQLPOINTER TargetValuePtr salida Puntero al almacenamiento intermedio donde deben almacenarse los datos de la columna recuperada.

El almacenamiento intermedio de salida debe estar alineado por palabras (igual). Muchos procesadores, tales como Motorola 68000, tienen reglas para la alineación por palabras, y la aplicación debe alinear debidamente el almacenamiento intermedio para los datos que no son de tipo carácter.

SQLINTEGER BufferLength entrada Tamaño máximo del almacenamiento intermedio al que apunta TargetValuePtr.

Si TargetType denota una serie binaria o de caracteres, 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 salida Puntero al valor que indica el número de bytes que CLI de DB2 tiene disponibles para devolverlos en el almacenamiento intermedio TargetValuePtr. Si se produce el truncamiento de los datos, esto contiene el número total de bytes necesarios para recuperar la columna entera.

Para los tipos de datos binarios y de caracteres, la aplicación puede elegir, alternativamente, la modalidad de recuperación gradual a fin de recuperar grandes cantidades de datos por partes. En esta modalidad, el argumento StrLen_or_IndPtr contiene el número de bytes que quedan en la columna.

El valor es SQL_NULL_DATA si el valor de datos de la columna es nulo. Si este puntero es nulo (NULL) y SQLFetch() obtuvo una columna que contiene datos nulos, esta función falla porque no tiene forma de notificar este hecho.

Si SQLFetch() recuperó una columna que contiene datos binarios, el puntero que apunta a StrLen_or_IndPtr no debe ser nulo (NULL) o la función fallará porque no tiene otra forma de notificar a la aplicación la longitud de los datos recuperados en el almacenamiento intermedio TargetValuePtr.

Uso

SQLGetData() se puede utilizar con SQLBindCol() para el mismo conjunto resultante si se utiliza SQLFetch(). Los pasos generales son:

  1. SQLFetch() avanza el cursor hasta la primera fila, recupera la primera fila y transfiere datos para columnas enlazadas.
  2. SQLGetData() transfiere datos para la columna especificada.
  3. SQLGetData() repite el paso 2 para cada columna necesaria.
  4. SQLFetch() avanza el cursor hasta la fila siguiente, recupera la fila siguiente y transfiere datos para columnas enlazadas.
  5. Se repiten los pasos 2, 3 y 4 para cada fila del conjunto resultante, o hasta que el conjunto resultante ya no sea necesario.

Para desechar los datos de la columna antes de terminar el proceso de recuperación, la aplicación puede invocar SQLGetData() con ColumnNumber establecido en la posición de columna deseada. Para desechar datos que no se han recuperado para la fila completa, la aplicación debe llamar a SQLFetch() para avanzar hasta la fila siguiente; o, si la aplicación no desea más datos del conjunto resultante, llama a SQLFreeStmt().

El argumento de entrada TargetType determina el tipo de conversión de datos (si la hay) que es necesaria antes de colocar los datos de la columna en el área de almacenamiento indicada por TargetValuePtr.

El valor devuelto en TargetValuePtr termina siempre en nulo, a menos que los datos de columna a recuperar sean binarios.

El truncamiento de tipos de datos numéricos se notifica en forma de aviso si el truncamiento afecta a dígitos situados a la derecha de la coma decimal. Si el truncamiento se produce a la izquierda de la coma decimal, se devuelve un error.

Códigos de retorno

Se devuelve SQL_SUCCESS si SQLGetData() recupera una serie de longitud cero. En este caso, StrLen_or_IndPtr contendrá 0 y TargetValuePtr contendrá un terminador nulo.

Si la llamada anterior a SQLFetch() ha fallado, no llame a SQLGetData() porque el resultado es indefinido

Diagnósticos

Tabla 67. SQLSTATE de SQLGetData

SQLSTATE Descripción Explicación
01004 Datos truncados. Los datos devueltos para la columna especificada (ColumnNumber) están truncados. Los valores de tipo serie o los valores numéricos se truncan por la derecha. Se devuelve SQL_SUCCESS_WITH_INFO.
07006 Conversión no válida. El valor de datos no se puede convertir al tipo de datos C especificado por el argumento TargetType.

Se ha llamado anteriormente a la función para el mismo valor de ColumnNumber, pero con un valor diferente de TargetType.

22002 Almacenamiento intermedio de salida o de indicadores no valido. El valor de puntero especificado para el argumento StrLen_or_IndPtr era un puntero nulo y el valor de la columna es nulo. No existe ninguna manera de notificar SQL_NULL_DATA.
22005 Error de asignación. Un valor devuelto es incompatible con el tipo de datos indicado por el argumento TargetType.
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. La columna especificada es menor que 0 o mayor que el número de columnas resultantes.
HY003 Tipo de programa fuera de rango. TargetType no es un tipo de datos válido ni SQL_C_DEFAULT.
HY010 Error de secuencia de función. Se llama a la función sin antes llamar a SQLFetch().
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 del argumento BufferLength es menor que 0 y el argumento TargetType es SQL_C_CHAR o SQL_C_BINARY, o bien TargetType es SQL_C_DEFAULT y el tipo por omisión es SQL_C_CHAR, SQL_C_BINARY o SQL_C_DBCHAR.
HYC00 Controlador no apropiado. CLI de DB2 reconoce, pero no da soporte a, el tipo de datos SQL especificado.

CLI de DB2 o la fuente de datos no puede convertir el tipo de datos SQL al tipo TargetType de los datos de la aplicación

Restricciones

Ninguna.

Consulta relacionada