Partage via


Fonction SQLGetFunctions

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

Résumé
SQLGetFunctions retourne des informations sur la prise en charge d’une fonction ODBC spécifique par un pilote. Cette fonction est implémentée dans le Gestionnaire de pilotes ; il peut également être implémenté dans les pilotes. Si un pilote implémente SQLGetFunctions, le Gestionnaire de pilotes appelle la fonction dans le pilote. Sinon, il exécute la fonction elle-même.

Syntaxe

  
SQLRETURN SQLGetFunctions(  
     SQLHDBC           ConnectionHandle,  
     SQLUSMALLINT      FunctionId,  
     SQLUSMALLINT *    SupportedPtr);  

Arguments

ConnectionHandle
[Entrée] Handle de connexion.

Id de fonction
[Entrée] Valeur #define qui identifie la fonction ODBC intéressante ; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS est utilisé par une application ODBC 3*.x* pour déterminer la prise en charge des fonctions ODBC 3*.x* et antérieures. SQL_API_ALL_FUNCTIONS est utilisé par une application ODBC 2*.x* pour déterminer la prise en charge des fonctions ODBC 2*.x* et antérieures.

Pour obtenir la liste des valeurs #define qui identifient les fonctions ODBC, consultez les tables dans « Commentaires ».

SupportedPtr
[Sortie] Si FunctionId identifie une seule fonction ODBC, SupportedPtr pointe vers une seule valeur SQLUSMALLINT qui est SQL_TRUE si la fonction spécifiée est prise en charge par le pilote et SQL_FALSE si elle n’est pas prise en charge.

Si FunctionId est SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr pointe vers un tableau SQLSMALLINT avec un nombre d’éléments égal à SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Ce tableau est traité par le Gestionnaire de pilotes comme une image bitmap 4 000 bits qui peut être utilisée pour déterminer si une fonction ODBC 3*.x* ou antérieure est prise en charge. La macro SQL_FUNC_EXISTS est appelée pour déterminer la prise en charge des fonctions. (Voir « Commentaires »). Une application ODBC 3*.x* peut appeler SQLGetFunctions avec SQL_API_ODBC3_ALL_FUNCTIONS sur un pilote ODBC 3*.x* ou ODBC 2*.x*.

Si FunctionId est SQL_API_ALL_FUNCTIONS, SupportedPtr pointe vers un tableau SQLUSMALLINT de 100 éléments. Le tableau est indexé par #define valeurs utilisées par FunctionId pour identifier chaque fonction ODBC ; certains éléments du tableau sont inutilisés et réservés à une utilisation ultérieure. Un élément est SQL_TRUE s’il identifie une fonction ODBC 2*.x* ou antérieure prise en charge par le pilote. Il est SQL_FALSE s’il identifie une fonction ODBC non prise en charge par le pilote ou s’il n’identifie pas une fonction ODBC.

Les tableaux retournés dans *SupportedPtr utilisent une indexation de base zéro.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLGetFunctions 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_DBC et un handle de ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLGetFunctions 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.
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.
HY010 Erreur de séquence de fonction (DM) SQLGetFunctions a été appelé avant SQLConnect, SQLBrowseConnect ou SQLDriverConnect.

(DM) SQLBrowseConnect a été appelé pour connectionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant que SQLBrowseConnect ne retourne SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour le ConnectionHandle 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.
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.
HY095 Type de fonction hors plage (DM) Une valeur FunctionId non valide a été spécifiée.
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.
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.

Commentaires

SQLGetFunctions retourne toujours que SQLGetFunctions, SQLDataSources et SQLDrivers sont pris en charge. Cela s’effectue, car ces fonctions sont implémentées dans le Gestionnaire de pilotes. Le Gestionnaire de pilotes mappe une fonction ANSI à la fonction Unicode correspondante si la fonction Unicode existe et mappe une fonction Unicode à la fonction ANSI correspondante si la fonction ANSI existe. Pour plus d’informations sur la façon dont les applications utilisent SQLGetFunctions, consultez Niveaux de conformité d’interface.

Voici une liste de valeurs valides pour FunctionId pour les fonctions qui sont conformes au niveau de conformité aux normes ISO 92 :

FunctionId Value FunctionId Value
SQL_API_SQLALLOCHANDLE SQL_API_SQLGETDESCFIELD
SQL_API_SQLBINDCOL SQL_API_SQLGETDESCREC
SQL_API_SQLCANCEL SQL_API_SQLGETDIAGFIELD
SQL_API_SQLCLOSECURSOR SQL_API_SQLGETDIAGREC
SQL_API_SQLCOLATTRIBUTE SQL_API_SQLGETENVATTR
SQL_API_SQLCONNECT SQL_API_SQLGETFUNCTIONS
SQL_API_SQLCOPYDESC SQL_API_SQLGETINFO
SQL_API_SQLDATASOURCES SQL_API_SQLGETSTMTATTR
SQL_API_SQLDESCRIBECOL SQL_API_SQLGETTYPEINFO
SQL_API_SQLDISCONNECT SQL_API_SQLNUMRESULTCOLS
SQL_API_SQLDRIVERS SQL_API_SQLPARAMDATA
SQL_API_SQLENDTRAN SQL_API_SQLPREPARE
SQL_API_SQLEXECDIRECT SQL_API_SQLPUTDATA
SQL_API_SQLEXECUTE SQL_API_SQLROWCOUNT
SQL_API_SQLFETCH SQL_API_SQLSETCONNECTATTR
SQL_API_SQLFETCHSCROLL SQL_API_SQLSETCURSORNAME
SQL_API_SQLFREEHANDLE SQL_API_SQLSETDESCFIELD
SQL_API_SQLFREESTMT SQL_API_SQLSETDESCREC
SQL_API_SQLGETCONNECTATTR SQL_API_SQLSETENVATTR
SQL_API_SQLGETCURSORNAME SQL_API_SQLSETSTMTATTR
SQL_API_SQLGETDATA

Voici une liste de valeurs valides pour FunctionId pour les fonctions conformes au niveau de conformité aux normes Open Group :

FunctionId Value FunctionId Value
SQL_API_SQLCOLUMNS SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS SQL_API_SQLTABLES

Voici une liste de valeurs valides pour FunctionId pour les fonctions conformes au niveau de conformité aux normes ODBC.

FunctionId Value FunctionId Value
SQL_API_SQLBINDPARAMETER SQL_API_SQLNATIVESQL
SQL_API_SQLBROWSECONNECT SQL_API_SQLNUMPARAMS
SQL_API_SQLBULKOPERATIONS[1] SQL_API_SQLPRIMARYKEYS
SQL_API_SQLCOLUMNPRIVILEGES SQL_API_SQLPROCEDURECOLUMNS
SQL_API_SQLDESCRIBEPARAM SQL_API_SQLPROCEDURES
SQL_API_SQLDRIVERCONNECT SQL_API_SQLSETPOS
SQL_API_SQLFOREIGNKEYS SQL_API_SQLTABLEPRIVILEGES
SQL_API_SQLMORERESULTS

[1] Lors de l’utilisation d’un pilote ODBC 2*.x*, SQLBulkOperations est retourné comme pris en charge uniquement si les deux éléments suivants sont vrais : le pilote ODBC 2*.x* prend en charge SQLSetPos et le type d’informations SQL_POS_OPERATIONS retourne le bit SQL_POS_ADD défini.

Voici une liste de valeurs valides pour FunctionId pour les fonctions introduites dans ODBC 3.8 ou version ultérieure :

FunctionId Value
SQL_API_SQLCANCELHANDLE [2]

[2] SQLCancelHandle est retourné comme pris en charge uniquement si le pilote prend en charge SQLCancel et SQLCancelHandle. Si SQLCancel est pris en charge, mais pas SQLCancelHandle , l’application peut toujours appeler SQLCancelHandle sur un handle d’instruction, car elle sera mappée à SQLCancel.

SQL_FUNC_EXISTS Macro

La macro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) est utilisée pour déterminer la prise en charge des fonctions ODBC 3*.x* ou antérieures après l’appel de SQLGetFunctions avec un argument FunctionId de SQL_API_ODBC3_ALL_FUNCTIONS. L’application appelle SQL_FUNC_EXISTS avec l’argument SupportedPtr défini sur SupportedPtr passé dans SQLGetFunctions, et avec l’argument FunctionID défini sur le #define pour la fonction. SQL_FUNC_EXISTS retourne SQL_TRUE si la fonction est prise en charge, et SQL_FALSE autrement.

Notes

Lors de l’utilisation d’un pilote ODBC 2*.x*, le Gestionnaire de pilotes ODBC 3*.x* retourne SQL_TRUE pour SQLAllocHandle et SQLFreeHandle , car SQLAllocHandle est mappé à SQLAllocEnv, SQLAllocConnect ou SQLAllocStmt, et parce que SQLFreeHandle est mappé à SQLFreeEnv, SQLFreeConnect ou SQLFreeStmt. SQLAllocHandle ou SQLFreeHandle avec un argument HandleType de SQL_HANDLE_DESC n’est pas pris en charge, même si SQL_TRUE est retourné pour les fonctions, car il n’existe aucune fonction ODBC 2*.x* à laquelle mapper dans ce cas.

Exemple de code

Les trois exemples suivants montrent comment une application utilise SQLGetFunctions pour déterminer si un pilote prend en charge SQLTables, SQLColumns et SQLStatistics. Si le pilote ne prend pas en charge ces fonctions, l’application se déconnecte du pilote. Le premier exemple appelle SQLGetFunctions une fois pour chaque fonction.

SQLUSMALLINT TablesExists, ColumnsExists, StatisticsExists;  
RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
  
retcodeTables = SQLGetFunctions(hdbc, SQL_API_SQLTABLES, &TablesExists);  
retcodeColumns = SQLGetFunctions(hdbc, SQL_API_SQLCOLUMNS, &ColumnsExists);  
retcodeStatistics = SQLGetFunctions(hdbc, SQL_API_SQLSTATISTICS, &StatisticsExists);  
  
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.  
if (retcodeTables == SQL_SUCCESS && TablesExists == SQL_TRUE &&   
retcodeColumns == SQL_SUCCESS && ColumnsExists == SQL_TRUE &&   
retcodeStatistics == SQL_SUCCESS && StatisticsExists == SQL_TRUE)   
{  
  
   // Continue with application  
  
}  
  
SQLDisconnect(hdbc);  

Dans le deuxième exemple, une application ODBC 3.x appelle SQLGetFunctions et lui transmet un tableau dans lequel SQLGetFunctions retourne des informations sur toutes les fonctions ODBC 3.x et antérieures.

RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
SQLUSMALLINT fExists[SQL_API_ODBC3_ALL_FUNCTIONS_SIZE];  
  
retcode = SQLGetFunctions(hdbc, SQL_API_ODBC3_ALL_FUNCTIONS, fExists);  
  
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.  
if (reccode == SQL_SUCCESS &&   
SQL_FUNC_EXISTS(fExists, SQL_API_SQLTABLES) == SQL_TRUE &&  
   SQL_FUNC_EXISTS(fExists, SQL_API_SQLCOLUMNS) == SQL_TRUE &&  
   SQL_FUNC_EXISTS(fExists, SQL_API_SQLSTATISTICS) == SQL_TRUE)   
{  
  
   // Continue with application  
  
}  
  
SQLDisconnect(hdbc);  

Le troisième exemple est une application ODBC 2.x qui appelle SQLGetFunctions et lui transmet un tableau de 100 éléments dans lequel SQLGetFunctions retourne des informations sur toutes les fonctions ODBC 2.x et antérieures.

#define FUNCTIONS 100  
  
RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
SQLUSMALLINT fExists[FUNCTIONS];  
  
retcode = SQLGetFunctions(hdbc, SQL_API_ALL_FUNCTIONS, fExists);  
  
/* SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver. */  
if (retcode == SQL_SUCCESS &&   
fExists[SQL_API_SQLTABLES] == SQL_TRUE &&  
   fExists[SQL_API_SQLCOLUMNS] == SQL_TRUE &&  
   fExists[SQL_API_SQLSTATISTICS] == SQL_TRUE)   
{  
  
   /* Continue with application */  
  
}  
  
SQLDisconnect(hdbc);  
Pour obtenir des informations sur Consultez
Retour du paramètre d’un attribut de connexion Fonction SQLGetConnectAttr
Retour d’informations sur un pilote ou une source de données Fonction SQLGetInfo
Retour du paramètre d’un attribut d’instruction Fonction SQLGetStmtAttr

Voir aussi

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