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 identifient de façon unique une ligne dans la table.

• Colonnes mises à jour automatiquement lorsqu’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 à partir 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 colonne 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 différents SGBD, une chaîne vide (« ») indique ces 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 significatif. Pour plus d’informations, consultez Arguments dans les 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 différents SGBD, une chaîne vide (« ») indique 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 significatif.

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 significatif.

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

Portée
[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 : le rowid est garanti être valide uniquement lors de sa position sur cette ligne. Une nouvelle sélection ultérieure à l’aide de rowid peut ne pas retourner une ligne si la ligne a été mise à jour ou supprimée par une autre transaction.

SQL_SCOPE_TRANSACTION : l’id de ligne est garanti valide pendant la durée de la transaction actuelle.

SQL_SCOPE_SESSION : le rowid est garanti valide pendant la durée de la session (entre les 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 : exclure des 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 s’il est absolument nécessaire.

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 de StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLSpecialColumns et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

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, 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 ROWID de pseudo-colonne Oracle. C’est pourquoi SQLSpecialColumns est utilisé pour retourner ces colonnes. Pour plus d’informations, consultez Utilisations des données de catalogue.

S’il n’existe 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, de sorte qu’ils ne peuvent 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.

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 les fonctions de catalogue.

Une fois que l’application a récupéré 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 désélectionne une ligne en fonction de la colonne ou des colonnes rowid et que la ligne est introuvable, 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 lorsqu’elles sont positionnées 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 déterminer cela en case activée 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 pouvoir case activée si des 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 que vous venez d’extraire. Si la valeur d’une colonne SQL_ROWVER diffère de la valeur précédente, l’application peut alerter 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.

Fonctions connexes

Voir aussi

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