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);
Fonctions connexes
| 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