SQLDescribeCol (función)
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLDescribeCol devuelve el descriptor de resultados ( nombre de columna, tipo, tamaño de columna, dígitos decimales y nulabilidad) para una columna del conjunto de resultados. Esta información también está disponible en los campos del IRD.
Sintaxis
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrucción.
ColumnNumber
[Entrada] Número de columnas de datos de resultados, ordenados secuencialmente en orden de columna creciente, empezando por 1. El argumento ColumnNumber también se puede establecer en 0 para describir la columna de marcador.
ColumnName
[Salida] Puntero a un búfer terminado en null en el que se va a devolver el nombre de columna. Este valor se lee desde el campo SQL_DESC_NAME del IRD. Si la columna no tiene nombre o no se puede determinar el nombre de la columna, el controlador devuelve una cadena vacía.
Si ColumnName es NULL, NameLengthPtr seguirá devolviendo el número total de caracteres (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta ColumnName.
BufferLength
[Entrada] Longitud del búfer *ColumnName , en caracteres.
NameLengthPtr
[Salida] Puntero a un búfer en el que se va a devolver el número total de caracteres (excepto la terminación nula) disponible para devolver en *ColumnName. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength, el nombre de columna de *ColumnName se trunca a BufferLength menos la longitud de un carácter de terminación null.
DataTypePtr
[Salida] Puntero a un búfer en el que se va a devolver el tipo de datos SQL de la columna. Este valor se lee desde el campo SQL_DESC_CONCISE_TYPE del IRD. Se trata de uno de los valores de tipos de datos sql o de un tipo de datos SQL específico del controlador. Si no se puede determinar el tipo de datos, el controlador devuelve SQL_UNKNOWN_TYPE.
En ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME o SQL_TYPE_TIMESTAMP se devuelve en *DataTypePtr para los datos de fecha, hora o marca de tiempo, respectivamente; en ODBC 2. Se devuelve x, SQL_DATE, SQL_TIME o SQL_TIMESTAMP. El Administrador de controladores realiza las asignaciones necesarias cuando odbc 2. La aplicación x funciona con ODBC 3. x driver o when an ODBC 3. La aplicación x funciona con ODBC 2. controlador x .
Cuando ColumnNumber es igual a 0 (para una columna de marcador), SQL_BINARY se devuelve en *DataTypePtr para marcadores de longitud variable. (SQL_INTEGER se devuelve si odbc 3 usa marcadores. x aplicación que funciona con ODBC 2. Controlador x o mediante ODBC 2. x aplicación que funciona con ODBC 3. controlador x ).
Para obtener más información sobre estos tipos de datos, vea Tipos de datos SQL en el Apéndice D: Tipos de datos. Para información sobre los tipos de datos SQL específicos del controlador, consulte la documentación del controlador.
ColumnSizePtr
[Salida] Puntero a un búfer en el que se va a devolver el tamaño (en caracteres) de la columna en el origen de datos. Si no se puede determinar el tamaño de columna, el controlador devuelve 0. Para obtener más información sobre el tamaño de columna, vea Tamaño de columna , Dígitos decimales, Longitud del octeto de transferencia y Tamaño de presentación en el Apéndice D: Tipos de datos.
DecimalDigitsPtr
[Salida] Puntero a un búfer en el que se va a devolver el número de dígitos decimales de la columna en el origen de datos. Si no se puede determinar el número de dígitos decimales o no es aplicable, el controlador devuelve 0. Para obtener más información sobre los dígitos decimales, vea Tamaño de columna, Dígitos decimales, Longitud del octeto de transferencia y Tamaño de presentación en el Apéndice D: Tipos de datos.
NullablePtr
[Salida] Puntero a un búfer en el que se va a devolver un valor que indica si la columna permite valores NULL. Este valor se lee desde el campo SQL_DESC_NULLABLE del IRD. El valor puede ser:
SQL_NO_NULLS: la columna no permite valores NULL.
SQL_NULLABLE: la columna permite valores NULL.
SQL_NULLABLE_UNKNOWN: el controlador no puede determinar si la columna permite valores NULL.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLDescribeCol devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLDescribeCol 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.
| SQLSTATE | Error | Descripción |
|---|---|---|
| 01000 | Advertencia general | Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01004 | Datos de cadena, truncados a la derecha | El búfer *ColumnName no era lo suficientemente grande como para devolver el nombre completo de la columna, por lo que el nombre de la columna se truncaba. La longitud del nombre de columna notruncado se devuelve en *NameLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 07005 | Instrucción preparada no es una especificación de cursor | La instrucción asociada a StatementHandle no devolvió un conjunto de resultados. No había columnas que describir. |
| 07009 | Índice de descriptor no válido | (DM) El valor especificado para el argumento ColumnNumber era igual a 0 y la opción de instrucción SQL_ATTR_USE_BOOKMARKS se SQL_UB_OFF. El valor especificado para el argumento ColumnNumber era mayor que el número de columnas del conjunto de resultados. |
| 08S01 | Error de vínculo de comunicación | Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento. |
| HY000 | Error general | Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa. |
| HY001 | Error de asignación de memoria | El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función. |
| HY008 | Operación cancelada | El procesamiento asincrónico se ha habilitado para StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en StatementHandle. A continuación, se llamó a la función de nuevo en StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso. |
| HY010 | Error de secuencia de función | (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a SQLDescribeCol . (DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para statementHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) Se llamó a una función de ejecución asincrónica (no esta) para StatementHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) Se llamó a la función antes de llamar a SQLPrepare, SQLExecute o una función de catálogo en el identificador de instrucción. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para la instrucciónHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. |
| HY013 | Error de administración de memoria | No se pudo procesar la llamada de función porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY090 | Longitud de búfer o cadena no válida | (DM) El valor especificado para el argumento BufferLength era menor que 0. |
| HY117 | La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura. | (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran. |
| HYT01 | Se ha agotado el tiempo de espera de la conexión. | El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | El controlador no admite esta función | (DM) El controlador asociado a StatementHandle no admite la función . |
| IM017 | El sondeo está deshabilitado en modo de notificación asincrónica | Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado. |
| IM018 | No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador. | Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación. |
SQLDescribeCol puede devolver cualquier SQLSTATE que sqlPrepare o SQLExecute pueda devolver cuando se llama después de SQLPrepare y antes de SQLExecute, dependiendo de cuándo el origen de datos evalúe la instrucción SQL asociada al identificador de instrucción.
Por motivos de rendimiento, una aplicación no debe llamar a SQLDescribeCol antes de ejecutar una instrucción .
Comentarios
Normalmente, una aplicación llama a SQLDescribeCol después de una llamada a SQLPrepare y antes o después de la llamada asociada a SQLExecute. Una aplicación también puede llamar a SQLDescribeCol después de una llamada a SQLExecDirect. Para obtener más información, vea Metadatos del conjunto de resultados.
SQLDescribeCol recupera el nombre de columna, el tipo y la longitud generados por una instrucción SELECT . Si la columna es una expresión, *ColumnName es una cadena vacía o un nombre definido por el controlador.
Nota
ODBC admite SQL_NULLABLE_UNKNOWN como extensión, aunque la especificación Open Group and SQL Access Group Call Level Interface no especifique la opción para SQLDescribeCol.
Funciones relacionadas
| Para información acerca de | Vea |
|---|---|
| Enlace de un búfer a una columna de un conjunto de resultados | SQLBindCol |
| Cancelación del procesamiento de instrucciones | SQLCancel |
| Devolver información sobre una columna en un conjunto de resultados | SQLColAttribute |
| Captura de varias filas de datos | SQLFetch |
| Devolver el número de columnas del conjunto de resultados | SQLNumResultCols |
| Preparación de una instrucción para su ejecución | SQLPrepare |