Fonction SQLSpecialColumns

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : Open Group

Résumé
SQLSpecialColumns récupère les informations suivantes sur les colonnes d’une table spécifiée :

  • Ensemble optimal de colonnes qui identifie de façon unique une ligne dans la table.

  • Colonnes mises à jour automatiquement quand une valeur de la ligne est mise à jour par une transaction.

Syntaxe

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

Arguments

StatementHandle
[Entrée] Handle d’instruction.

IdentifierType
[Entrée] Type de colonne à retourner. Il doit s’agir de l’une des valeurs suivantes :

SQL_BEST_ROWID : retourne la colonne ou l’ensemble optimal de colonnes qui, en récupérant des valeurs de la colonne ou des colonnes, permet à n’importe quelle ligne de la table spécifiée d’être identifiée de manière unique. Une colonne peut être une pseudo-colonne spécifiquement conçue à cet effet (comme dans Oracle ROWID ou Ingres TID) ou la colonne ou les colonnes d’un index unique pour la table.

SQL_ROWVER : retourne la ou les colonnes de la table spécifiée, le cas échéant, qui sont automatiquement mises à jour par la source de données lorsqu’une valeur de la ligne est mise à jour par n’importe quelle transaction (comme dans SQLBase ROWID ou Sybase TIMESTAMP).

CatalogName
[Entrée] Nom du catalogue pour la table. Si un pilote prend en charge les catalogues pour certaines tables, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de SGBD différents, une chaîne vide ( » « ) indique les tables qui n’ont pas de catalogues. CatalogName ne peut pas contenir de modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID est défini sur SQL_TRUE, CatalogName est traité comme un identificateur et son cas n’est pas significatif. S’il est SQL_FALSE, CatalogName est un argument ordinaire ; il est traité littéralement, et son cas est important. Pour plus d’informations, consultez Arguments dans fonctions de catalogue.

NameLength1
[Entrée] Longueur en caractères de *CatalogName.

SchemaName
[Entrée] Nom du schéma pour la table. Si un pilote prend en charge des schémas pour certaines tables, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de SGBD différents, une chaîne vide ( » « ) désigne ces tables qui n’ont pas de schémas. SchemaName ne peut pas contenir de modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID est défini sur SQL_TRUE, SchemaName est traité comme un identificateur et son cas n’est pas significatif. S’il est SQL_FALSE, SchemaName est un argument ordinaire ; il est traité littéralement, et son cas est important.

NameLength2
[Entrée] Longueur en caractères de *SchemaName.

TableName
[Entrée] Nom de la table. Cet argument ne peut pas être un pointeur Null. TableName ne peut pas contenir de modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID est défini sur SQL_TRUE, TableName est traité comme un identificateur et son cas n’est pas significatif. S’il est SQL_FALSE, TableName est un argument ordinaire ; il est traité littéralement, et son cas est important.

NameLength3
[Entrée] Longueur en caractères de *TableName.

Étendue
[Entrée] Étendue minimale requise du rowid. Le rowid retourné peut avoir une plus grande étendue. Doit prendre l'une des valeurs suivantes :

SQL_SCOPE_CURROW : l’id de ligne est garanti être valide uniquement lorsqu’il est positionné sur cette ligne. Une nouvelle sélection ultérieure à l’aide de rowid peut ne pas retourner de ligne si la ligne a été mise à jour ou supprimée par une autre transaction.

SQL_SCOPE_TRANSACTION : Le rowid est garanti valide pendant la durée de la transaction actuelle.

SQL_SCOPE_SESSION : l’id de ligne est garanti valide pour la durée de la session (au-delà des limites de transaction).

Nullable
[Entrée] Détermine s’il faut retourner des colonnes spéciales qui peuvent avoir une valeur NULL. Doit prendre l'une des valeurs suivantes :

SQL_NO_NULLS : excluez les colonnes spéciales qui peuvent avoir des valeurs NULL. Certains pilotes ne peuvent pas prendre en charge SQL_NO_NULLS, et ces pilotes retournent un jeu de résultats vide si SQL_NO_NULLS a été spécifié. Les demandes doivent être préparées pour ce cas et demander SQL_NO_NULLS uniquement si elles sont absolument requises.

SQL_NULLABLE : retournez des colonnes spéciales même si elles peuvent avoir des valeurs NULL.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLSpecialColumns retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLSpecialColumns et explique chacune d’elles dans le contexte de cette fonction; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE Erreur Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
08S01 Échec du lien de communication Le lien de communication entre le pilote et la source de données auquel le pilote a été connecté a échoué avant que la fonction ait terminé le traitement.
24 000 État de curseur non valide Un curseur a été ouvert sur StatementHandle, et SQLFetch ou SQLFetchScroll avait été appelé. Cette erreur est retournée par le Gestionnaire de pilotes si SQLFetch ou SQLFetchScroll n’a pas retourné SQL_NO_DATA et est retournée par le pilote si SQLFetch ou SQLFetchScroll a retourné SQL_NO_DATA.

Un curseur a été ouvert sur StatementHandle, mais SQLFetch ou SQLFetchScroll n’avait pas été appelé.
40001 Échec de sérialisation La transaction a été restaurée en raison d’un interblocage de ressources avec une autre transaction.
40003 Saisie semi-automatique de l’instruction inconnue La connexion associée a échoué pendant l’exécution de cette fonction, et l’état de la transaction ne peut pas être déterminé.
HY000 Erreur générale Une erreur s’est produite pour laquelle il n’y avait pas de SQLSTATE spécifique et pour laquelle aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon *MessageText décrit l’erreur et sa cause.
HY001 Erreur d’allocation de mémoire Le pilote n’a pas pu allouer de mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY008 Opération annulée Le traitement asynchrone a été activé pour StatementHandle. La fonction a été appelée et avant qu’elle n’ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur StatementHandle. Ensuite, la fonction a été appelée à nouveau sur StatementHandle.

La fonction a été appelée et avant qu’elle n’ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle à partir d’un thread différent dans une application multithread.
HY009 Utilisation non valide du pointeur Null L’argument TableName était un pointeur null.

L’attribut d’instruction SQL_ATTR_METADATA_ID a été défini sur SQL_TRUE, l’argument CatalogName était un pointeur null et l’SQL_CATALOG_NAME InfoType retourne les noms de catalogue pris en charge.

(DM) L’attribut d’instruction SQL_ATTR_METADATA_ID a été défini sur SQL_TRUE, et l’argument SchemaName était un pointeur null.
HY010 Erreur de séquence de fonction (DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. Cette fonction était toujours en cours d’exécution lorsque SQLSpecialColumns a été appelé.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour statementHandle et retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant que les données ne soit récupérées pour tous les paramètres diffusés en continu.

(DM) Une fonction en cours d’exécution asynchrone (pas celle-ci) a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lorsque cette fonction était appelée.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour statementHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution.
HY013 Erreur de gestion de la mémoire L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, éventuellement en raison de conditions de mémoire faible.
HY090 Longueur de chaîne ou de mémoire tampon non valide (DM) La valeur de l’un des arguments de longueur était inférieure à 0, mais pas égale à SQL_NTS.

La valeur de l’un des arguments de longueur a dépassé la valeur de longueur maximale du nom correspondant. La longueur maximale de chaque nom peut être obtenue en appelant SQLGetInfo avec les valeurs InfoType : SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN ou SQL_MAX_TABLE_NAME_LEN.
HY097 Type de colonne hors plage (DM) Une valeur IdentifierType non valide a été spécifiée.
HY098 Type d’étendue hors plage (DM) Une valeur d’étendue non valide a été spécifiée.
HY0999 Type nullable hors plage (DM) Une valeur nullable non valide a été spécifiée.
HY117 La connexion est suspendue en raison de l’état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées. (DM) Pour plus d’informations sur l’état suspendu, consultez LA fonction SQLEndTran.
HYC00 Fonctionnalité facultative non implémentée Un catalogue a été spécifié et la source de données ou le pilote ne prend pas en charge les catalogues.

Un schéma a été spécifié, et le pilote ou la source de données ne prend pas en charge les schémas.

La combinaison des paramètres actuels des attributs d’instruction SQL_ATTR_CONCURRENCY et SQL_ATTR_CURSOR_TYPE n’a pas été prise en charge par le pilote ou la source de données.

L’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_VARIABLE, et l’attribut d’instruction SQL_ATTR_CURSOR_TYPE a été défini sur un type de curseur pour lequel le pilote ne prend pas en charge les signets.
HYT00 Délai expiré La période d’expiration de la requête a expiré avant que la source de données ne retourne le jeu de résultats demandé. La période d’expiration est définie via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Délai d’attente de la connexion expiré La période d’expiration du délai de connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote associé à StatementHandle ne prend pas en charge la fonction.
IM017 L’interrogation est désactivée en mode de notification asynchrone Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée.
IM018 SQLCompleteAsync n’a pas été appelé pour terminer l’opération asynchrone précédente sur ce handle. Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer un post-traitement et effectuer l’opération.

Commentaires

Lorsque l’argument IdentifierType est SQL_BEST_ROWID, SQLSpecialColumns retourne la colonne ou les colonnes qui identifient de manière unique chaque ligne de la table. Ces colonnes peuvent toujours être utilisées dans une clause select-list ou WHERE . SQLColumns, qui est utilisé pour retourner diverses informations sur les colonnes d’une table, ne retourne pas nécessairement les colonnes qui identifient de manière unique chaque ligne ou colonnes qui sont automatiquement mises à jour lorsqu’une valeur de la ligne est mise à jour par une transaction. Par exemple, SQLColumns peut ne pas retourner le PSEUDO-colonne ROWID Oracle. C’est pourquoi SQLSpecialColumns est utilisé pour retourner ces colonnes. Pour plus d’informations, consultez Utilisations des données de catalogue.

Notes

Pour plus d’informations sur l’utilisation générale, les arguments et les données retournées des fonctions de catalogue ODBC, consultez Fonctions catalogue.

S’il n’y a pas de colonnes qui identifient de manière unique chaque ligne de la table, SQLSpecialColumns retourne un ensemble de lignes sans ligne ; un appel ultérieur à SQLFetch ou SQLFetchScroll sur l’instruction retourne SQL_NO_DATA.

Si les arguments IdentifierType, Scope ou Nullable spécifient des caractéristiques qui ne sont pas prises en charge par la source de données, SQLSpecialColumns retourne un jeu de résultats vide.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID est défini sur SQL_TRUE, les arguments CatalogName, SchemaName et TableName sont traités comme des identificateurs. Ils ne peuvent donc pas être définis sur un pointeur Null dans certaines situations. (Pour plus d’informations, consultez Arguments dans fonctions de catalogue.)

SQLSpecialColumns retourne les résultats sous la forme d’un jeu de résultats standard, classé par SCOPE.

Les colonnes suivantes ont été renommées pour ODBC 3.x. Les modifications de nom de colonne n’affectent pas la compatibilité descendante, car les applications sont liées par numéro de colonne.

Colonne ODBC 2.0 Colonne ODBC 3.x
PRECISION COLUMN_SIZE
LENGTH BUFFER_LENGTH
SCALE DECIMAL_DIGITS

Pour déterminer la longueur réelle de la colonne COLUMN_NAME, une application peut appeler SQLGetInfo avec l’option SQL_MAX_COLUMN_NAME_LEN.

Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 8 (PSEUDO_COLUMN) peuvent être définies par le pilote. Une application doit accéder à des colonnes spécifiques au pilote en comptant à partir de la fin du jeu de résultats plutôt que de spécifier une position ordinale explicite. Pour plus d’informations, consultez Données retournées par fonctions catalogue.

Nom de la colonne Numéro de colonne Type de données Commentaires
ÉTENDUE (ODBC 1.0) 1 Smallint Étendue réelle du rowid. Contient l’une des valeurs suivantes :

SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION

NULL est retourné lorsque IdentifierType est SQL_ROWVER. Pour obtenir une description de chaque valeur, consultez la description de l’étendue dans « Syntaxe », plus haut dans cette section.
COLUMN_NAME (ODBC 1.0) 2 Varchar non NULL Nom de la colonne. Le pilote retourne une chaîne vide pour une colonne qui n’a pas de nom.
DATA_TYPE (ODBC 1.0) 3 Smallint non NULL SQL type de données. Il peut s’agir d’un type de données ODBC SQL ou d’un type de données spécifique au pilote SQL. Pour obtenir la liste des types de données ODBC SQL valides, consultez SQL Types de données. Pour plus d’informations sur les types de données SQL spécifiques au pilote, consultez la documentation du pilote.
TYPE_NAME (ODBC 1.0) 4 Varchar non NULL Nom du type de données dépendant de la source de données ; par exemple, « CHAR », « VARCHAR », « MONEY », « LONG VARBINARY » ou « CHAR ( ) FOR BIT DATA ».
COLUMN_SIZE (ODBC 1.0) 5 Integer Taille de la colonne sur la source de données. Pour plus d’informations sur la taille de colonne, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage.
BUFFER_LENGTH (ODBC 1.0) 6 Integer Longueur en octets de données transférées sur une opération SQLGetData ou SQLFetch si SQL_C_DEFAULT est spécifié. Pour les données numériques, cette taille peut être différente de la taille des données stockées sur la source de données. Cette valeur est identique à la colonne COLUMN_SIZE pour les données binaires ou caractère. Pour plus d’informations, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage.
DECIMAL_DIGITS (ODBC 1.0) 7 Smallint Chiffres décimaux de la colonne sur la source de données. NULL est retourné pour les types de données où les chiffres décimaux ne sont pas applicables. Pour plus d’informations sur les chiffres décimaux, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage.
PSEUDO_COLUMN (ODBC 2.0) 8 Smallint Indique si la colonne est une pseudo-colonne, telle que Oracle ROWID :

SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Remarque : Pour une interopérabilité maximale, les pseudo-colonnes ne doivent pas être guillemets avec le caractère de guillemet d’identificateur retourné par SQLGetInfo.

Une fois que l’application récupère des valeurs pour SQL_BEST_ROWID, l’application peut utiliser ces valeurs pour réélectionner cette ligne dans l’étendue définie. L’instruction SELECT est garantie de retourner aucune ligne ou une ligne.

Si une application réélectionne une ligne en fonction de la colonne ou des colonnes rowid et que la ligne n’est pas trouvée, l’application peut supposer que la ligne a été supprimée ou que les colonnes rowid ont été modifiées. L’inverse n’est pas vrai : même si le rowid n’a pas changé, les autres colonnes de la ligne peuvent avoir changé.

Les colonnes retournées pour le type de colonne SQL_BEST_ROWID sont utiles pour les applications qui doivent faire défiler vers l’avant et le retour dans un jeu de résultats pour récupérer les données les plus récentes à partir d’un ensemble de lignes. La colonne ou les colonnes du rowid sont garanties de ne pas changer lors de la position sur cette ligne.

La colonne ou les colonnes du rowid peuvent rester valides même si le curseur n’est pas positionné sur la ligne; l’application peut le déterminer en vérifiant la colonne SCOPE dans le jeu de résultats.

Les colonnes retournées pour le type de colonne SQL_ROWVER sont utiles pour les applications qui ont besoin de vérifier si les colonnes d’une ligne donnée ont été mises à jour pendant que la ligne a été réélectionnée à l’aide du rowid. Par exemple, après avoir réélectionné une ligne à l’aide de rowid, l’application peut comparer les valeurs précédentes dans les colonnes SQL_ROWVER aux colonnes extraites. Si la valeur d’une colonne SQL_ROWVER diffère de la valeur précédente, l’application peut avertir l’utilisateur que les données de l’affichage ont changé.

Exemple de code

Pour obtenir un exemple de code d’une fonction similaire, consultez SQLColumns.

Pour obtenir des informations sur Consultez
Liaison d’une mémoire tampon à une colonne dans un jeu de résultats Fonction SQLBindCol
Annulation du traitement des instructions SQLCancel, fonction
Retour des colonnes d’une table ou d’une table Fonction SQLColumns
Extraction d’une seule ligne ou d’un bloc de données dans une direction de transfert uniquement SQLFetch, fonction
Extraction d’un bloc de données ou défilement d’un jeu de résultats Fonction SQLFetchScroll
Retour des colonnes d’une clé primaire Fonction SQLPrimaryKeys

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC