Función SQLSpecialColumns

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: Open Group

Resumen
SQLSpecialColumns recupera la siguiente información sobre las columnas dentro de una tabla especificada:

• Conjunto óptimo de columnas que identifica de forma única una fila de la tabla.

• Las columnas que se actualizan automáticamente cuando una transacción actualiza cualquier valor de la fila.

Sintaxis

  
SQLRETURN SQLSpecialColumns(  
     SQLHSTMT      StatementHandle,  
     SQLSMALLINT   IdentifierType,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLSMALLINT   Scope,  
     SQLSMALLINT   Nullable);  

Argumentos

StatementHandle
[Entrada] Identificador de instrucciones.

IdentifierType
[Entrada] Tipo de columna que se va a devolver. Debe ser uno de los siguientes valores:

SQL_BEST_ROWID: devuelve la columna o conjunto óptimo de columnas que, al recuperar valores de la columna o columnas, permite identificar de forma única cualquier fila de la tabla especificada. Una columna puede ser una pseudocolumnas diseñada específicamente para este propósito (como en Oracle ROWID o TID de entrada) o la columna o columnas de cualquier índice único para la tabla.

SQL_ROWVER: devuelve la columna o columnas de la tabla especificada, si existe, que el origen de datos actualiza automáticamente cuando cualquier valor de la fila se actualiza mediante cualquier transacción (como en SQLBase ROWID o Sybase TIMESTAMP).

CatalogName
[Entrada] Nombre del catálogo de la tabla. Si un controlador admite catálogos para algunas tablas, pero no para otras, como cuando el controlador recupera datos de dbMS diferentes, una cadena vacía ("") denota esas tablas que no tienen catálogos. CatalogName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, CatalogName se trata como identificador y su caso no es significativo. Si es SQL_FALSE, CatalogName es un argumento ordinario; se trata literalmente y su caso es significativo. Para obtener más información, consulte Argumentos en funciones de catálogo.

NameLength1
[Entrada] Longitud en caracteres de *CatalogName.

SchemaName
[Entrada] Nombre de esquema de la tabla. Si un controlador admite esquemas para algunas tablas, pero no para otras, como cuando el controlador recupera datos de diferentes DBMS, una cadena vacía ("") denota esas tablas que no tienen esquemas. SchemaName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de instrucción SQL_ATTR_METADATA_ID está establecido en SQL_TRUE, SchemaName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, SchemaName es un argumento ordinario; se trata literalmente y su caso es significativo.

NameLength2
[Entrada] Longitud en caracteres de *SchemaName.

TableName
[Entrada] Nombre de la tabla. Este argumento no puede ser un puntero nulo. TableName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, TableName se trata como identificador y su caso no es significativo. Si es SQL_FALSE, TableName es un argumento ordinario; se trata literalmente y su caso es significativo.

NameLength3
[Entrada] Longitud en caracteres de *TableName.

Ámbito
[Entrada] Ámbito mínimo necesario del rowid. El rowid devuelto puede ser de mayor ámbito. Debe ser una de las siguientes:

SQL_SCOPE_CURROW: se garantiza que rowid solo es válido mientras se coloca en esa fila. Una nueva selección posterior mediante rowid puede no devolver una fila si otra transacción actualizó o eliminó la fila.

SQL_SCOPE_TRANSACTION: se garantiza que rowid es válido mientras dure la transacción actual.

SQL_SCOPE_SESSION: se garantiza que el valor de rowid es válido durante la sesión (entre límites de transacción).

Admisión de valores NULL
[Entrada] Determina si se devuelven columnas especiales que pueden tener un valor NULL. Debe ser una de las siguientes:

SQL_NO_NULLS: excluya columnas especiales que puedan tener valores NULL. Algunos controladores no pueden admitir SQL_NO_NULLS y estos controladores devolverán un conjunto de resultados vacío si se especificó SQL_NO_NULLS. Las aplicaciones deben estar preparadas para este caso y solicitar SQL_NO_NULLS solo si es absolutamente necesaria.

SQL_NULLABLE: devuelve columnas especiales incluso si pueden tener valores NULL.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLSpecialColumns 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 SQLSpecialColumns 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).
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 cursor 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	Error en la conexión asociada durante la ejecución de esta función y no se puede determinar 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.
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.
HY009	Uso no válido del puntero nulo	El argumento TableName era un puntero nulo. El atributo de instrucción SQL_ATTR_METADATA_ID se estableció en SQL_TRUE, el argumento CatalogName era un puntero nulo y el SQL_CATALOG_NAME InfoType devuelve que se admiten los nombres de catálogo. (DM) El atributo de instrucción SQL_ATTR_METADATA_ID se estableció en SQL_TRUE y el argumento SchemaName era un puntero nulo.
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 todavía se estaba ejecutando cuando se llamó a SQLSpecialColumns . (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.
HY090	Longitud de búfer o cadena no válida	(DM) El valor de uno de los argumentos de longitud era menor que 0, pero no igual a SQL_NTS. El valor de uno de los argumentos de longitud superó el valor de longitud máxima para el nombre correspondiente. La longitud máxima de cada nombre se puede obtener llamando a SQLGetInfo con los valores de InfoType : SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN o SQL_MAX_TABLE_NAME_LEN.
HY097	Tipo de columna fuera del intervalo	(DM) Se especificó un valor IdentifierType no válido.
HY098	Tipo de ámbito fuera del intervalo	(DM) Se especificó un valor de ámbito no válido.
HY099	Tipo que acepta valores NULL fuera del intervalo	(DM) Se especificó un valor que acepta valores NULL no válidos.
HY117	Conectar ion 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	Se especificó un catálogo y el controlador o el origen de datos no admite catálogos. Se especificó un esquema y el controlador o el origen de datos no admite esquemas. 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 devolviera el conjunto de resultados solicitado. 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 mediante SQLSet Conectar Attr, 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.

Comentarios

Cuando el argumento IdentifierType es SQL_BEST_ROWID, SQLSpecialColumns devuelve la columna o columnas que identifican de forma única cada fila de la tabla. Estas columnas siempre se pueden usar en una cláusula select-list o WHERE . SQLColumns, que se usa para devolver una variedad de información sobre las columnas de una tabla, no devuelve necesariamente las columnas que identifican de forma única cada fila o columnas que se actualizan automáticamente cuando una transacción actualiza cualquier valor de la fila. Por ejemplo, SQLColumns podría no devolver rowID de pseudocolumnas de Oracle. Por este motivo se usa SQLSpecialColumns para devolver estas columnas. Para obtener más información, consulte Usos de los datos de catálogo.

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.

Si no hay ninguna columna que identifique de forma única cada fila de la tabla, SQLSpecialColumns devuelve un conjunto de filas sin filas; una llamada posterior a SQLFetch o SQLFetchScroll en la instrucción devuelve SQL_NO_DATA.

Si los argumentos IdentifierType, Scope o Nullable especifican características que no son compatibles con el origen de datos, SQLSpecialColumns devuelve un conjunto de resultados vacío.

Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, los argumentos CatalogName, SchemaName y TableName se tratan como identificadores, por lo que no se pueden establecer en un puntero nulo en determinadas situaciones. (Para obtener más información, consulte Argumentos en funciones de catálogo).

SQLSpecialColumns devuelve los resultados como un conjunto de resultados estándar, ordenado por SCOPE.

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	Columna ODBC 3.x
PRECISION	COLUMN_SIZE
LENGTH	BUFFER_LENGTH
SCALE	DECIMAL_DIGITS

Para determinar la longitud real de la columna COLUMN_NAME, una aplicación puede llamar a SQLGetInfo con la opción SQL_MAX_COLUMN_NAME_LEN.

En la tabla siguiente se enumeran las columnas del conjunto de resultados. El controlador puede definir columnas adicionales más allá de la columna 8 (PSEUDO_COLUMN). 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.

Nombre de la columna	Column number	Tipo de datos	Comentarios
SCOPE (ODBC 1.0)	1	Smallint	Ámbito real del rowid. Contiene uno de los siguientes valores: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION Se devuelve NULL cuando Se SQL_ROWVER IdentifierType . Para obtener una descripción de cada valor, vea la descripción de Ámbito en "Sintaxis", anteriormente en esta sección.
COLUMN_NAME (ODBC 1.0)	2	Varchar no NULL	Nombre de la columna. El controlador devuelve una cadena vacía para una columna que no tiene un nombre.
DATA_TYPE (ODBC 1.0)	3	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 obtener una lista de los tipos de datos DE SQL ODBC válidos, vea Tipos de datos SQL. Para información sobre los tipos de datos SQL específicos del controlador, consulte la documentación del controlador.
TYPE_NAME (ODBC 1.0)	4	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".
COLUMN_SIZE (ODBC 1.0)	5	Entero	Tamaño de la columna en el origen de datos. 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 visualización.
BUFFER_LENGTH (ODBC 1.0)	6	Entero	Longitud en bytes de datos transferidos en una operación SQLGetData o SQLFetch si se especifica SQL_C_DEFAULT. Para los datos numéricos, este tamaño puede ser diferente del tamaño de los datos almacenados en el origen de datos. Este valor puede diferir de COLUMN_SIZE columna para los datos de caracteres. Para obtener más información, vea Tamaño de columna, Dígitos decimales, Longitud de octeto de transferencia y Tamaño de presentación.
DECIMAL_DIGITS (ODBC 1.0)	7	Smallint	Dígitos decimales de la columna en el origen de datos. Null se devuelve para los tipos de datos en los que los dígitos decimales no son aplicables. Para obtener más información sobre los dígitos decimales, vea Tamaño de columna, Dígitos decimales, Longitud de octeto de transferencia y Tamaño de presentación.
PSEUDO_COLUMN (ODBC 2.0)	8	Smallint	Indica si la columna es una pseudo-columna, como Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Nota: Para obtener la interoperabilidad máxima, las pseudocolumnas no deben citarse con el carácter de comilla de identificador devuelto por SQLGetInfo.

Después de que la aplicación recupere los valores de SQL_BEST_ROWID, la aplicación puede usar estos valores para volver a seleccionar esa fila dentro del ámbito definido. Se garantiza que la instrucción SELECT no devuelva filas ni una fila.

Si una aplicación vuelve a seleccionar una fila basada en la columna o columnas rowid y no se encuentra la fila, la aplicación puede suponer que se eliminó la fila o que se modificaron las columnas rowid. Lo contrario no es cierto: aunque el identificador de fila no haya cambiado, es posible que las otras columnas de la fila hayan cambiado.

Las columnas devueltas para el tipo de columna SQL_BEST_ROWID son útiles para las aplicaciones que necesitan desplazarse hacia delante y hacia atrás dentro de un conjunto de resultados para recuperar los datos más recientes de un conjunto de filas. Se garantiza que la columna o columnas del rowid no cambien mientras se colocan en esa fila.

La columna o columnas del rowid puede permanecer válida incluso cuando el cursor no está colocado en la fila; La aplicación puede determinarlo comprobando la columna SCOPE en el conjunto de resultados.

Las columnas devueltas para el tipo de columna SQL_ROWVER son útiles para las aplicaciones que necesitan la capacidad de comprobar si se han actualizado las columnas de una fila determinada mientras la fila se reeleccionó mediante rowid. Por ejemplo, después de volver a seleccionar una fila mediante rowid, la aplicación puede comparar los valores anteriores de las columnas de SQL_ROWVER con las que acaba de capturar. Si el valor de una columna de SQL_ROWVER difiere del valor anterior, la aplicación puede avisar al usuario de que los datos de la pantalla han cambiado.

Ejemplo de código

Para obtener un ejemplo de código de una función similar, vea SQLColumns.

Funciones relacionadas

Para información acerca de	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 las columnas de una tabla o tablas	Función SQLColumns
Capturar una sola fila o un bloque de datos en una dirección de solo avance	Función SQLFetch
Capturar un bloque de datos o desplazarse por un conjunto de resultados	Función SQLFetchScroll
Devolver las columnas de una clave principal	Función SQLPrimaryKeys

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC