Fonction SQLProcedureColumns
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ODBC
Résumé
SQLProcedureColumns retourne la liste des paramètres d’entrée et de sortie, ainsi que les colonnes qui composent le jeu de résultats pour les procédures spécifiées. Le pilote retourne les informations sous forme de jeu de résultats sur l’instruction spécifiée.
Syntaxe
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Arguments
StatementHandle
[Entrée] Handle d’instruction.
CatalogName
[Entrée] Nom du catalogue de procédures. Si un pilote prend en charge des catalogues pour certaines procédures, mais pas pour d’autres, par exemple quand le pilote récupère des données à partir de différents SGBD, une chaîne vide (« ») désigne les procédures qui n’ont pas de catalogues. CatalogName ne peut pas contenir un modèle de recherche de chaîne.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, CatalogName est traité comme un identificateur et sa casse n’est pas significative. 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] Modèle de recherche de chaîne pour les noms de schéma de procédure. Si un pilote prend en charge des schémas pour certaines procédures, 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 (« ») désigne les procédures qui n’ont pas de schéma.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, SchemaName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, SchemaName est un argument de valeur de modèle ; il est traité littéralement, et son cas est significatif.
NameLength2
[Entrée] Longueur en caractères de *SchemaName.
ProcName
[Entrée] Modèle de recherche de chaîne pour les noms de procédure.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, ProcName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, ProcName est un argument de valeur de modèle ; il est traité littéralement, et son cas est significatif.
NameLength3
[Entrée] Longueur en caractères de *ProcName.
ColumnName
[Entrée] Modèle de recherche de chaînes pour les noms de colonnes.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, ColumnName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, ColumnName est un argument de valeur de modèle ; il est traité littéralement, et son cas est significatif.
NameLength4
[Entrée] Longueur en caractères de *ColumnName.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLProcedureColumns 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 SQLProcedureColumns 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.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Avertissement général | Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Échec de la liaison de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin du traitement de la fonction. |
| 24 000 | État de curseur non valide | Un curseur était ouvert sur l’InstructionHandle et 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 était ouvert sur l’InstructionHandle, mais SQLFetchou SQLFetchScroll n’avait pas été appelé. |
| 40001 | Échec de sérialisation | La transaction a été annulée en raison d’un interblocage de ressources avec une autre transaction. |
| 40003 | Saisie semi-automatique d’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 SQLError 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 la 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 l’InstructionHandle. La fonction a été appelée et, avant la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle. Ensuite, la fonction a été appelée à nouveau sur l’InstructionHandle. La fonction a été appelée et, avant la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un thread différent dans une application multithread. |
| HY009 | Utilisation non valide du 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 que les noms de catalogue sont pris en charge. (DM) L’attribut d’instruction SQL_ATTR_METADATA_ID a été défini sur SQL_TRUE, et l’argument SchemaName, ProcName ou ColumnName était un pointeur Null. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction en exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction aynschronous était toujours en cours d’exécution lorsque la fonction SQLProcedureColumns a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’InstructionHandle et a retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution. |
| HY090 | Chaîne ou longueur de mémoire tampon non valide | (DM) La valeur de l’un des arguments de longueur de nom est inférieure à 0, mais n’est pas égale à SQL_NTS. La valeur de l’un des arguments de longueur de nom a dépassé la valeur de longueur maximale pour le nom de catalogue, de schéma, de procédure ou de colonne correspondant. |
| HY117 | La connexion est suspendue en raison d’un é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 FONCTION SQLEndTran. |
| HYC00 | Fonctionnalité facultative non implémentée | Un catalogue de procédures a été spécifié et le pilote ou la source de données ne prend pas en charge les catalogues. Un schéma de procédure a été spécifié et le pilote ou la source de données ne prend pas en charge les schémas. Un modèle de recherche de chaîne a été spécifié pour le schéma de procédure, le nom de la procédure ou le nom de colonne, et la source de données ne prend pas en charge les modèles de recherche pour un ou plusieurs de ces arguments. La combinaison des paramètres actuels de l’SQL_ATTR_CONCURRENCY et des attributs d’instruction SQL_ATTR_CURSOR_TYPE n’était pas 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é | Le délai d’expiration a expiré avant que la source de données retourne le jeu de résultats. Le délai d’expiration est défini via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Délai d’attente de la connexion expiré | Le délai d’expiration de la connexion a expiré avant que la source de données réponde à la demande. La période de délai d’expiration de la connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à l’InstructionHandle 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 effectuer 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 terminer l’opération. |
Commentaires
Cette fonction est généralement utilisée avant l’exécution de l’instruction pour récupérer des informations sur les paramètres de procédure et les colonnes qui composent le jeu de résultats ou les jeux retournés par la procédure, le cas échéant. Pour plus d’informations, consultez Procédures.
Notes
SQLProcedureColumns peut ne pas retourner toutes les colonnes utilisées par une procédure. Par exemple, un pilote peut retourner uniquement des informations sur les paramètres utilisés par une procédure et non sur les colonnes d’un jeu de résultats qu’il génère.
Les arguments SchemaName, ProcName et ColumnName acceptent les modèles de recherche. Pour plus d’informations sur les modèles de recherche valides, consultez Arguments de valeur de modèle.
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 de catalogue.
SQLProcedureColumns retourne les résultats sous forme de jeu de résultats standard, triés par PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME et COLUMN_TYPE. Les noms de colonnes sont retournés pour chaque procédure dans l’ordre suivant : le nom de la valeur de retour, les noms de chaque paramètre dans l’appel de procédure (dans l’ordre d’appel), puis les noms de chaque colonne dans le jeu de résultats retourné par la procédure (dans l’ordre des colonnes).
Les applications doivent lier des colonnes spécifiques au pilote par rapport à la fin du jeu de résultats. Pour plus d’informations, consultez Données retournées par les fonctions de catalogue.
Pour déterminer la longueur réelle des colonnes PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME et COLUMN_NAME, une application peut appeler SQLGetInfo avec les options SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN SQL_MAX_PROCEDURE_NAME_LEN et SQL_MAX_COLUMN_NAME_LEN.
Les colonnes suivantes ont été renommées pour ODBC 3. x. Les changements de nom de colonne n’affectent pas la compatibilité descendante, car les applications se lient par numéro de colonne.
| Colonne ODBC 2.0 | ODBC 3. colonne x |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| _OWNER DE PROCÉDURE | PROCEDURE_SCHEM |
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
Les colonnes suivantes ont été ajoutées au jeu de résultats retourné par SQLProcedureColumns pour ODBC 3. x :
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 19 (IS_NULLABLE) peuvent être définies par le pilote. Une application doit accéder à des colonnes spécifiques au pilote en comptant vers le bas à 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.
| Nom de la colonne | Numéro de colonne | Type de données | Commentaires |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Nom du catalogue de procédures ; NULL s’il n’est pas applicable à la source de données. Si un pilote prend en charge les catalogues pour certaines procédures, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de différents SGBD, il retourne une chaîne vide (« ») pour les procédures qui n’ont pas de catalogues. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Nom du schéma de procédure ; NULL s’il n’est pas applicable à la source de données. Si un pilote prend en charge les schémas pour certaines procédures, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de différents SGBD, il retourne une chaîne vide (« ») pour les procédures qui n’ont pas de schémas. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar not NULL | Nom de la procédure. Une chaîne vide est retournée pour une procédure qui n’a pas de nom. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar not NULL | Nom de la colonne de procédure. Le pilote retourne une chaîne vide pour une colonne de procédure qui n’a pas de nom. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint non NULL | Définit la colonne de procédure en tant que paramètre ou colonne de jeu de résultats : SQL_PARAM_TYPE_UNKNOWN : la colonne de procédure est un paramètre dont le type est inconnu. (ODBC 1.0) SQL_PARAM_INPUT : la colonne de procédure est un paramètre d’entrée. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT : la colonne de procédure est un paramètre d’entrée/sortie. (ODBC 1.0) SQL_PARAM_OUTPUT : la colonne de procédure est un paramètre de sortie. (ODBC 2.0) SQL_RETURN_VALUE : la colonne de procédure est la valeur de retour de la procédure. (ODBC 2.0) SQL_RESULT_COL : la colonne de procédure est une colonne de jeu de résultats. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint non NULL | Type de données SQL. Il peut s’agir d’un type de données SQL ODBC ou d’un type de données SQL spécifique au pilote. Pour les types de données datetime et interval, cette colonne retourne les types de données concis (par exemple, SQL_TYPE_TIME ou SQL_INTERVAL_YEAR_TO_MONTH). Pour obtenir la liste des types de données SQL ODBC valides, consultez Types de données SQL dans l’Annexe D : 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 2.0) | 7 | Varchar n’est pas 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 2.0) | 8 | Integer | Taille de colonne de la colonne de procédure sur la source de données. Null est retourné pour les types de données pour lesquels la taille de colonne n’est pas applicable. Pour plus d’informations sur la précision, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage dans l’Annexe D : Types de données. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Integer | Longueur en octets des 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. Pour plus d’informations, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage, dans l’Annexe D : Types de données. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | Chiffres décimaux de la colonne de procédure 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, dans l’Annexe D : Types de données. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Pour les types de données numériques, 10 ou 2. Si la valeur est 10, les valeurs dans COLUMN_SIZE et DECIMAL_DIGITS donnent le nombre de chiffres décimaux autorisés pour la colonne. Par exemple, une colonne DECIMAL(12,5) renvoie une NUM_PREC_RADIX de 10, une COLUMN_SIZE de 12 et une DECIMAL_DIGITS de 5 ; une colonne FLOAT peut retourner une NUM_PREC_RADIX de 10, une COLUMN_SIZE de 15 et une DECIMAL_DIGITS null. Si la valeur est 2, les valeurs dans COLUMN_SIZE et DECIMAL_DIGITS donnent le nombre de bits autorisé dans la colonne. Par exemple, une colonne FLOAT peut retourner une NUM_PREC_RADIX de 2, une COLUMN_SIZE de 53 et une DECIMAL_DIGITS null. Null est retourné pour les types de données où NUM_PREC_RADIX n’est pas applicable. |
| NULLABLE (ODBC 2.0) | 12 | Smallint non NULL | Indique si la colonne de procédure accepte une valeur NULL : SQL_NO_NULLS : la colonne de procédure n’accepte pas les valeurs NULL. SQL_NULLABLE : la colonne de procédure accepte les valeurs NULL. SQL_NULLABLE_UNKNOWN : on ne sait pas si la colonne de procédure accepte des valeurs NULL. |
| REMARQUES (ODBC 2.0) | 13 | Varchar | Description de la colonne de procédure. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | Valeur par défaut de la colonne. Si NULL a été spécifié comme valeur par défaut, cette colonne est le mot NULL, et non entre guillemets. Si la valeur par défaut ne peut pas être représentée sans troncation, cette colonne contient TRUNCATED, sans guillemets simples. Si aucune valeur par défaut n’a été spécifiée, cette colonne a la valeur NULL. La valeur de COLUMN_DEF peut être utilisée pour générer une nouvelle définition de colonne, sauf quand elle contient la valeur TRUNCATED. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint non NULL | Valeur du type de données SQL telle qu’elle apparaît dans le champ SQL_DESC_TYPE du descripteur. Cette colonne est identique à la colonne DATA_TYPE, à l’exception des types de données datetime et interval. Pour les types de données datetime et interval, le champ SQL_DATA_TYPE dans le jeu de résultats retourne SQL_INTERVAL ou SQL_DATETIME, et le champ SQL_DATETIME_SUB renvoie le sous-code pour le type de données interval ou datetime spécifique. (Voir Annexe D : Types de données.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | Code de sous-type pour les types de données datetime et interval. Pour les autres types de données, cette colonne retourne une valeur NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Integer | Longueur maximale, en octets, d’une colonne de type de données de type caractère ou binaire. Pour tous les autres types de données, cette colonne retourne une valeur NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Entier non NULL | Pour les paramètres d’entrée et de sortie, position ordinale du paramètre dans la définition de procédure (dans l’ordre croissant des paramètres, à partir de 1). Pour une valeur de retour (le cas échéant), 0 est retourné. Pour les colonnes de jeu de résultats, position ordinale de la colonne dans le jeu de résultats, la première colonne du jeu de résultats étant le numéro 1. S’il existe plusieurs jeux de résultats, les positions ordinales de colonne sont retournées de manière spécifique au pilote. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | « NO » si la colonne n’inclut pas de VALEURS NULL. « OUI » si la colonne peut inclure des VALEURS NULL. Cette colonne renvoie une chaîne de longueur zéro si la possibilité de valeurs Null n'est pas connue. Les règles ISO sont utilisées pour déterminer la possibilité de valeur Null. Un SGBD compatible avec la norme ISO SQL ne peut pas renvoyer de chaîne vide. La valeur renvoyée pour cette colonne est différente de celle renvoyée pour la colonne NULLABLE. (Consultez la description de la colonne NULLABLE.) |
Exemple de code
Consultez Appels de procédure.
Fonctions connexes
| 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 |
| Extraction d’une seule ligne ou d’un bloc de données dans une direction avant uniquement | SQLFetch, fonction |
| Extraction d’un bloc de données ou défilement d’un jeu de résultats | Fonction SQLFetchScroll |
| Retour d’une liste de procédures dans une source de données | Fonction SQLProcedures |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC