Función SQLGetTypeInfo
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLGetTypeInfo devuelve información sobre los tipos de datos admitidos por el origen de datos. El controlador devuelve la información en forma de un conjunto de resultados de SQL. Los tipos de datos están diseñados para su uso en instrucciones de Lenguaje de definición de datos (DDL).
Importante
Las aplicaciones deben usar los nombres de tipo devueltos en la columna TYPE_NAME del conjunto de resultados SQLGetTypeInfo en las instrucciones ALTER TABLE y CREATE TABLE . SQLGetTypeInfo puede devolver más de una fila con el mismo valor en la columna DATA_TYPE.
Sintaxis
SQLRETURN SQLGetTypeInfo(
SQLHSTMT StatementHandle,
SQLSMALLINT DataType);
Argumentos
StatementHandle
[Entrada] Identificador de instrucción para el conjunto de resultados.
DataType
[Entrada] Tipo de datos SQL. Debe ser uno de los valores de la sección Tipos de datos SQL del Apéndice D: Tipos de datos o un tipo de datos SQL específico del controlador. SQL_ALL_TYPES especifica que se debe devolver información sobre todos los tipos de datos.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLGetTypeInfo devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando 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 SQLGetTypeInfo 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). |
| 01S02 | Valor de opción cambiado | Un atributo de instrucción especificado no era válido debido a las condiciones de trabajo de implementación, por lo que se sustituyó temporalmente un valor similar. (Llamada SQLGetStmtAttr para determinar el valor sustituido temporalmente). El valor sustituto es válido para StatementHandle hasta que se cierra el cursor. Los atributos de instrucción que se pueden cambiar son: SQL_ATTR_CONCURRENCY, SQL_ATTR_CURSOR_TYPE, SQL_ATTR_KEYSET_SIZE, SQL_ATTR_MAX_LENGTH, SQL_ATTR_MAX_ROWS, SQL_ATTR_QUERY_TIMEOUT y SQL_ATTR_SIMULATE_CURSOR. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 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. |
| 24000 | Estado de cursor no válido | Se ha abierto un cursor en StatementHandle y se ha llamado a SQLFetch o SQLFetchScroll. El Administrador de controladores devuelve este error si SQLFetch o SQLFetchScroll no ha devuelto SQL_NO_DATA y el controlador devuelve si SQLFetch o SQLFetchScroll ha devuelto SQL_NO_DATA. Se ha abierto un conjunto de resultados en StatementHandle, pero no se ha llamado a SQLFetch o SQLFetchScroll . |
| 40001 | Error de serialización | La transacción se revierte debido a un interbloqueo de recursos con otra transacción. |
| 40003 | Finalización de instrucciones desconocida | No se pudo determinar la conexión asociada durante la ejecución de esta función y el estado de la transacción. |
| 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. |
| HY004 | Tipo de datos SQL no válido | El valor especificado para el argumento DataType no era un identificador de tipo de datos ODBC SQL válido ni un identificador de tipo de datos específico del controlador admitido por el controlador. |
| HY008 | Operación cancelada | El procesamiento asincrónico se ha habilitado para StatementHandle y, después, 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 funciones | (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 la función SQLGetTypeInfo . (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 que ejecuta de forma asincrónica (no esta) para statementHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para el statementHandle 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 tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY117 | La conexión se suspende debido al estado de transacción desconocido. Solo se permiten las funciones de desconexión y solo lectura. | (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran. |
| HYC00 | Característica opcional no implementada | La combinación de la configuración actual de la SQL_ATTR_CONCURRENCY y los atributos de instrucción SQL_ATTR_CURSOR_TYPE no se admiten en el controlador o el origen de datos. El atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_VARIABLE y el atributo de instrucción SQL_ATTR_CURSOR_TYPE se estableció en un tipo de cursor para el que el controlador no admite marcadores. |
| HYT00 | Se ha agotado el tiempo de espera | El período de tiempo de espera de la consulta expiró antes de que el origen de datos devolva el conjunto de resultados. El período de tiempo de espera se establece mediante SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 correspondiente 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. |
Comentarios
SQLGetTypeInfo devuelve los resultados como un conjunto de resultados estándar, ordenado por DATA_TYPE y, a continuación, por la estrecha relación del tipo de datos asignado al tipo de datos ODBC SQL correspondiente. Los tipos de datos definidos por el origen de datos tienen prioridad sobre los tipos de datos definidos por el usuario. Por lo tanto, el criterio de ordenación no es necesariamente coherente, pero se puede generalizar como DATA_TYPE primero, seguido de TYPE_NAME, ambos ascendentes. Por ejemplo, supongamos que un origen de datos definió tipos de datos INTEGER y COUNTER, donde COUNTER es incremento automático y que también se ha definido un tipo de datos definido por el usuario WHOLENUM. Estos se devolverían en el orden INTEGER, WHOLENUM y COUNTER, porque WHOLENUM se asigna estrechamente al tipo de datos ODBC SQL SQL_INTEGER, mientras que el tipo de datos de incremento automático, aunque sea compatible con el origen de datos, no se asigna estrechamente a un tipo de datos ODBC SQL. Para obtener información sobre cómo se puede usar esta información, vea Instrucciones DDL.
Si el argumento DataType especifica un tipo de datos válido para la versión de ODBC compatible con el controlador, pero no es compatible con el controlador, devolverá un conjunto de resultados vacío.
Nota:
Para obtener más información sobre el uso general, los argumentos y los datos devueltos de funciones de catálogo ODBC, vea Funciones de catálogo.
Se ha cambiado el nombre de las columnas siguientes para ODBC 3.x. Los cambios de nombre de columna no afectan a la compatibilidad con versiones anteriores porque las aplicaciones enlazan por número de columna.
| Columna ODBC 2.0 | ODBC 3.columna x |
|---|---|
| PRECISION | COLUMN_SIZE |
| MONEY | FIXED_PREC_SCALE |
| AUTO_INCREMENT | AUTO_UNIQUE_VALUE |
Las columnas siguientes se han agregado al conjunto de resultados devuelto por SQLGetTypeInfo para ODBC 3.x:
SQL_DATA_TYPE
INTERVAL_PRECISION
SQL_DATETIME_SUB
NUM_PREC_RADIX
En la tabla siguiente se enumeran las columnas del conjunto de resultados. El controlador puede definir columnas adicionales más allá de la columna 19 (INTERVAL_PRECISION). Una aplicación debe obtener acceso a columnas específicas del controlador contando hacia abajo desde el final del conjunto de resultados en lugar de especificar una posición ordinal explícita. Para obtener más información, vea Datos devueltos por funciones de catálogo.
Nota:
SQLGetTypeInfo podría no devolver todos los tipos de datos. Por ejemplo, un controlador podría no devolver tipos de datos definidos por el usuario. Las aplicaciones pueden usar cualquier tipo de datos válido, independientemente de si SQLGetTypeInfo lo devuelve. Los tipos de datos devueltos por SQLGetTypeInfo son los admitidos por el origen de datos. Están diseñados para su uso en instrucciones DDL (Lenguaje de definición de datos). Los controladores pueden devolver datos del conjunto de resultados mediante tipos de datos distintos de los tipos devueltos por SQLGetTypeInfo. Al crear el conjunto de resultados para una función de catálogo, el controlador puede usar un tipo de datos que no sea compatible con el origen de datos.
| Nombre de la columna | Columna number |
Tipo de datos | Comentarios |
|---|---|---|---|
| TYPE_NAME (ODBC 2.0) | 1 | Varchar no NULL | Nombre del tipo de datos dependiente del origen de datos; por ejemplo, "CHAR()", "VARCHAR()", "MONEY", "LONG VARBINARY" o "CHAR ( ) FOR BIT DATA". Las aplicaciones deben usar este nombre en las instrucciones CREATE TABLE y ALTER TABLE . |
| DATA_TYPE (ODBC 2.0) | 2 | Smallint no NULL | Tipo de datos SQL. Puede ser un tipo de datos SQL ODBC o un tipo de datos SQL específico del controlador. Para los tipos de datos datetime o interval, esta columna devuelve el tipo de datos conciso (como SQL_TYPE_TIME o SQL_INTERVAL_YEAR_TO_MONTH). Para obtener una lista de los tipos de datos DE SQL ODBC válidos, 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. |
| COLUMN_SIZE (ODBC 2.0) | 3 | Entero | Tamaño máximo de columna que admite el servidor para este tipo de datos. Para los datos numéricos, esta es la precisión máxima. Para los datos de cadena, esta es la longitud en caracteres. Para los tipos de datos datetime, esta es la longitud en caracteres de la representación de cadena (suponiendo la precisión máxima permitida del componente fracciones de segundos). Se devuelve NULL para los tipos de datos en los que el tamaño de columna no es aplicable. Para los tipos de datos de intervalo, este es el número de caracteres de la representación de caracteres del literal de intervalo (tal y como se define en la precisión inicial del intervalo; vea Interval Data Type Length in Apéndice D: Tipos de datos). Para obtener más información sobre el tamaño de columna, vea Tamaño de columna, Dígitos decimales, Longitud de octeto de transferencia y Tamaño de visualización en el Apéndice D: Tipos de datos. |
| LITERAL_PREFIX (ODBC 2.0) | 4 | Varchar | Carácter o caracteres usados para prefijar un literal; por ejemplo, una comilla simple (') para los tipos de datos de caracteres o 0x para los tipos de datos binarios; Se devuelve NULL para los tipos de datos en los que no se aplica un prefijo literal. |
| LITERAL_SUFFIX (ODBC 2.0) | 5 | Varchar | Carácter o caracteres usados para finalizar un literal; por ejemplo, una comilla simple (') para los tipos de datos de caracteres; Null se devuelve para los tipos de datos en los que no se aplica un sufijo literal. |
| CREATE_PARAMS (ODBC 2.0) | 6 | Varchar | Lista de palabras clave, separadas por comas, correspondientes a cada parámetro que la aplicación puede especificar entre paréntesis al usar el nombre que se devuelve en el campo TYPE_NAME. Las palabras clave de la lista pueden ser cualquiera de las siguientes: longitud, precisión o escala. Aparecen en el orden en que la sintaxis requiere que se usen. Por ejemplo, CREATE_PARAMS para DECIMAL sería "precisión, escala"; CREATE_PARAMS para VARCHAR sería igual a "length". Se devuelve NULL si no hay parámetros para la definición del tipo de datos; por ejemplo, INTEGER. El controlador proporciona el texto CREATE_PARAMS en el idioma del país o región donde se usa. |
| NULLABLE (ODBC 2.0) | 7 | Smallint no NULL | Si el tipo de datos acepta un valor NULL: SQL_NO_NULLS si el tipo de datos no acepta valores NULL. SQL_NULLABLE si el tipo de datos acepta valores NULL. SQL_NULLABLE_UNKNOWN si no se sabe si la columna acepta valores NULL. |
| CASE_SENSITIVE (ODBC 2.0) | 8 | Smallint no NULL | Si un tipo de datos de caracteres distingue mayúsculas de minúsculas en intercalaciones y comparaciones: SQL_TRUE si el tipo de datos es un tipo de datos de caracteres y distingue mayúsculas de minúsculas. SQL_FALSE si el tipo de datos no es un tipo de datos de caracteres o no distingue mayúsculas de minúsculas. |
| SEARCHABLE (ODBC 2.0) | 9 | Smallint no NULL | Cómo se usa el tipo de datos en una cláusula WHERE : SQL_PRED_NONE si la columna no se puede usar en una cláusula WHERE . (Este es el mismo que el valor de SQL_UNSEARCHABLE en ODBC 2.x.) SQL_PRED_CHAR si la columna se puede usar en una cláusula WHERE , pero solo con el predicado LIKE . (Este es el mismo que el valor de SQL_LIKE_ONLY en ODBC 2.x.) SQL_PRED_BASIC si la columna se puede usar en una cláusula WHERE con todos los operadores de comparación excepto LIKE (comparación, comparación cuantificada, BETWEEN, DISTINCT, IN, MATCH y UNIQUE). (Este es el mismo que el valor de SQL_ALL_EXCEPT_LIKE en ODBC 2.x.) SQL_SEARCHABLE si la columna se puede usar en una cláusula WHERE con cualquier operador de comparación. |
| UNSIGNED_ATTRIBUTE (ODBC 2.0) | 10 | Smallint | Si el tipo de datos no está firmado: SQL_TRUE si el tipo de datos no está firmado. SQL_FALSE si el tipo de datos está firmado. Se devuelve NULL si el atributo no es aplicable al tipo de datos o el tipo de datos no es numérico. |
| FIXED_PREC_SCALE (ODBC 2.0) | 11 | Smallint no NULL | Si el tipo de datos tiene una precisión y una escala fijas predefinidas (que son específicas del origen de datos), como un tipo de datos money: SQL_TRUE si tiene una precisión y escala fija predefinidas. SQL_FALSE si no tiene predefinida precisión y escala fijas. |
| AUTO_UNIQUE_VALUE (ODBC 2.0) | 12 | Smallint | Indica si el tipo de datos es la creación automática: SQL_TRUE si el tipo de datos se está generando automáticamente. SQL_FALSE si el tipo de datos no se está generando automáticamente. Se devuelve NULL si el atributo no es aplicable al tipo de datos o el tipo de datos no es numérico. Una aplicación puede insertar valores en una columna que tenga este atributo, pero normalmente no puede actualizar los valores de la columna. Cuando se realiza una inserción en una columna de incremento automático, se inserta un valor único en la columna en tiempo de inserción. El incremento no está definido, pero es específico del origen de datos. Una aplicación no debe suponer que una columna de incremento automático se inicia en cualquier punto o incremento determinado por cualquier valor determinado. |
| LOCAL_TYPE_NAME (ODBC 2.0) | 13 | Varchar | Versión traducida del nombre del tipo de datos, dependiente del origen de datos. Se devuelve NULL si el origen de datos no admite un nombre traducido. Este nombre está pensado solo para mostrarse, como en cuadros de diálogo. |
| MINIMUM_SCALE (ODBC 2.0) | 14 | Smallint | Escala mínima del tipo de datos en el origen de datos. Si un tipo de datos tiene una escala fija, las columnas MINIMUM_SCALE y MAXIMUM_SCALE contienen este valor. Por ejemplo, una columna de SQL_TYPE_TIMESTAMP podría tener una escala fija durante fracciones de segundos. Se devuelve NULL cuando no se puede aplicar la escala. Para obtener más información, vea Tamaño de columna, Dígitos decimales, Longitud de octeto de transferencia y Tamaño de visualización en el Apéndice D: Tipos de datos. |
| MAXIMUM_SCALE (ODBC 2.0) | 15 | Smallint | Escala máxima del tipo de datos en el origen de datos. Se devuelve NULL cuando no se puede aplicar la escala. Si la escala máxima no se define por separado en el origen de datos, pero se define para que sea la misma precisión que la máxima, esta columna contiene el mismo valor que la columna COLUMN_SIZE. Para obtener más información, vea Tamaño de columna, Dígitos decimales, Longitud de octeto de transferencia y Tamaño de visualización en el Apéndice D: Tipos de datos. |
| SQL_DATA_TYPE (ODBC 3.0) | 16 | Smallint NOT NULL | Valor del tipo de datos SQL tal como aparece en el campo SQL_DESC_TYPE del descriptor. Esta columna es la misma que la columna DATA_TYPE, excepto para los tipos de datos interval y datetime. En el caso de los tipos de datos interval y datetime, el campo SQL_DATA_TYPE del conjunto de resultados devolverá SQL_INTERVAL o SQL_DATETIME, y el campo SQL_DATETIME_SUB devolverá el subcódigo para el tipo de datos datetime o intervalo específico. (Consulte Apéndice D: Tipos de datos). |
| SQL_DATETIME_SUB (ODBC 3.0) | 17 | Smallint | Cuando el valor de SQL_DATA_TYPE es SQL_DATETIME o SQL_INTERVAL, esta columna contiene el subcódigo datetime/interval. En el caso de los tipos de datos distintos de datetime e interval, este campo es NULL. Para los tipos de datos interval o datetime, el campo SQL_DATA_TYPE del conjunto de resultados devolverá SQL_INTERVAL o SQL_DATETIME, y el campo SQL_DATETIME_SUB devolverá el subcódigo para el tipo de datos datetime o intervalo específico. (Consulte Apéndice D: Tipos de datos). |
| NUM_PREC_RADIX (ODBC 3.0) | 18 | Entero | Si el tipo de datos es un tipo numérico aproximado, esta columna contiene el valor 2 para indicar que COLUMN_SIZE especifica un número de bits. Para los tipos numéricos exactos, esta columna contiene el valor 10 para indicar que COLUMN_SIZE especifica un número de dígitos decimales. De lo contrario, esta columna es NULL. |
| INTERVAL_PRECISION (ODBC 3.0) | 19 | Smallint | Si el tipo de datos es un tipo de datos interval, esta columna contiene el valor de la precisión inicial del intervalo. (Consulte Precisión del tipo de datos interval en el Apéndice D: Tipos de datos). De lo contrario, esta columna es NULL. |
La información de atributo se puede aplicar a los tipos de datos o a columnas específicas de un conjunto de resultados. SQLGetTypeInfo devuelve información sobre los atributos asociados a los tipos de datos; SQLColAttribute devuelve información sobre los atributos asociados a las columnas de un conjunto de resultados.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Enlazar un búfer a una columna de un conjunto de resultados | Función SQLBindCol |
| Cancelación del procesamiento de instrucciones | Función SQLCancel |
| Devolver información sobre una columna en un conjunto de resultados | Función SQLColAttribute |
| Capturar un bloque de datos o desplazarse por un conjunto de resultados | Función SQLFetchScroll |
| Capturar una sola fila o un bloque de datos en una dirección de solo avance | Función SQLFetch |
| Devolver información sobre un controlador o un origen de datos | Función SQLGetInfo |