Fonction SQLProcedures

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

Résumé
SQLProcedures retourne la liste des noms de procédure stockés dans une source de données spécifique. La procédure est un terme générique utilisé pour décrire un objet exécutable ou une entité nommée qui peut être appelée à l’aide de paramètres d’entrée et de sortie. Pour plus d’informations sur les procédures, consultez Procédures.

Syntaxe

  
SQLRETURN SQLProcedures(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      ProcName,  
     SQLSMALLINT    NameLength3);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

CatalogName
[Entrée] Catalogue de procédures. 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 (« ») désigne les tables 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 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, une chaîne vide (« ») désigne les procédures qui n’ont pas de schémas.

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.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLProcedures 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 couramment retournées par SQLProcedures 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	La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement.
24 000	État de curseur non valide	Un curseur a été ouvert sur l’InstructionHandle et SQLFetchScroll a é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 SQLFetchScroll n’avait pas été appelé.
40001	Échec de sérialisation	La transaction a été annulée en raison d’un blocage 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 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 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’instruction StatementHandle. La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle. Ensuite, la fonction a été appelée à nouveau sur l’InstructionHandle. La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un autre thread 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 le 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 ou ProcName était un pointeur null.
HY010	Erreur de séquence de fonction	(DM) Une fonction d’exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle 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. (DM) Une fonction d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle et s’exécutait toujours lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a renvoyé 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.
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 consultés, peut-être en raison de conditions de mémoire insuffisantes.
HY090	Chaîne ou longueur de mémoire tampon non valide	(DM) La valeur de l’un des arguments de longueur de nom était inférieure à 0, mais non égale à SQL_NTS. La valeur de l’un des arguments de longueur de nom a dépassé la valeur de longueur maximale du nom 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 sous forme de chaîne a été spécifié pour le schéma de procédure ou le nom de la procédure, 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 des attributs d’instruction SQL_ATTR_CONCURRENCY et 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 de la requête a expiré avant que la source de données renvoie le jeu de résultats demandé. 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 ne réponde à la demande. Le délai d’expiration de connexion est défini 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 cette 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 le post-traitement et terminer l’opération.

Commentaires

SQLProcedures répertorie toutes les procédures de la plage demandée. Un utilisateur peut être autorisé ou non à exécuter l’une de ces procédures. Pour vérifier l’accessibilité, une application peut appeler SQLGetInfo et vérifier la valeur d’informations SQL_ACCESSIBLE_PROCEDURES. Sinon, l’application doit être en mesure de gérer une situation où l’utilisateur sélectionne une procédure qu’il ne peut pas exécuter. Pour plus d’informations sur la façon dont ces informations peuvent être utilisées, consultez Procédures.

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.

SQLProcedures retourne les résultats sous la forme d’un jeu de résultats standard, classé par PROCEDURE_CAT, PROCEDURE_SCHEMA et PROCEDURE_NAME.

Notes

SQLProcedures peut ne pas retourner toutes les procédures. Les applications peuvent utiliser n’importe quelle procédure valide, qu’elle soit retournée ou non par SQLProcedures.

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 sont liées par numéro de colonne.

Colonne ODBC 2.0	Colonne ODBC 3*.x*
PROCEDURE_QUALIFIER	PROCEDURE_CAT
PROCÉDURE _OWNER	PROCÉDURE _SCHEM

Pour déterminer la longueur réelle des colonnes PROCEDURE_CAT, PROCEDURE_SCHEM et PROCEDURE_NAME, une application peut appeler SQLGetInfo avec les options SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN et SQL_MAX_PROCEDURE_NAME_LEN.

Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 8 (PROCEDURE_TYPE) 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.

Nom de la colonne	Numéro de colonne	Type de données	Commentaires
PROCEDURE_CAT (ODBC 2.0)	1	Varchar	Identificateur 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 quand 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	Identificateur de schéma de procédure ; NULL s’il n’est pas applicable à la source de données. Si un pilote prend en charge des schémas 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, il retourne une chaîne vide («  ») pour les procédures qui n’ont pas de schémas.
PROCEDURE_NAME (ODBC 2.0)	3	Varchar n’est pas NULL	Identificateur de procédure.
NUM_INPUT_PARAMS (ODBC 2.0)	4	N/A	Réservé pour un usage futur. Les applications ne doivent pas s’appuyer sur les données retournées dans ces colonnes de résultats.
NUM_OUTPUT_PARAMS (ODBC 2.0)	5	N/A	Réservé pour un usage futur. Les applications ne doivent pas s’appuyer sur les données retournées dans ces colonnes de résultats.
NUM_RESULT_SETS (ODBC 2.0)	6	N/A	Réservé pour un usage futur. Les applications ne doivent pas s’appuyer sur les données retournées dans ces colonnes de résultats.
REMARQUES (ODBC 2.0)	7	Varchar	Description de la procédure.
PROCEDURE_TYPE (ODBC 2.0)	8	Smallint	Définit le type de procédure : SQL_PT_UNKNOWN : impossible de déterminer si la procédure retourne une valeur. SQL_PT_PROCEDURE : l’objet retourné est une procédure ; autrement dit, il n’a pas de valeur de retour. SQL_PT_FUNCTION : l’objet retourné est une fonction ; autrement dit, il a une valeur de retour.

Les arguments SchemaName et ProcName acceptent les modèles de recherche. Pour plus d’informations sur les modèles de recherche valides, consultez Arguments de valeur de modèle.

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’informations sur un pilote ou une source de données	Fonction SQLGetInfo
Retour des colonnes de paramètres et de jeu de résultats d’une procédure	Fonction SQLProcedureColumns
Syntaxe pour appeler des procédures stockées	Exécution d’instructions

Voir aussi

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