SQLGetFunctions, funkcja

Zgodność
Wersja wprowadzona: Zgodność ze standardami ODBC 1.0: ISO 92

Podsumowanie
SQLGetFunctions zwraca informację o tym, czy dany sterownik obsługuje konkretną funkcję ODBC. Funkcja ta jest implementowana w Driver Managerze; Może być również implementowany w sterownikach. Jeśli sterownik implementuje SQLGetFunctions, Driver Manager wywołuje tę funkcję w sterowniku. W przeciwnym razie sam wykonuje tę funkcję.

Syntax

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

Arguments

ConnectionHandle
[Dane wejściowe] Uchwyt połączenia.

FunctionId
[Input] Wartość #define , która identyfikuje interesującą funkcję ODBC; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS jest używany przez aplikację ODBC 3*.x* do określenia wsparcia funkcji ODBC 3*.x* i wcześniejszych. SQL_API_ALL_FUNCTIONS jest używany przez aplikację ODBC 2*.x* do określenia wsparcia dla funkcji ODBC 2*.x* i wcześniejszych.

Listę wartości #define identyfikujących funkcje ODBC znajdziesz w tabelach w sekcji "Komentarze".

SupportedPtr
[Wyjście] Jeśli FunctionId identyfikuje pojedynczą funkcję ODBC, SupportedPtr wskazuje na jedną wartość SQLUSMALLINT, która jest SQL_TRUE, jeśli dana funkcja jest obsługiwana przez sterownik, a SQL_FALSE, jeśli nie jest obsługiwana.

Jeśli FunctionId jest SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr wskazuje tablicę SQLSMALLINT z liczbą elementów równą SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Ta tablica jest traktowana przez Driver Manager jako bitmapa o długości 4 000 bitów, która może być użyta do określenia, czy obsługiwana jest funkcja ODBC 3*.x* lub wcześniejsza. Makro SQL_FUNC_EXISTS jest wywoływane do określenia wsparcia funkcji. (Zobacz "Komentarze.") Aplikacja ODBC 3*.x* może wywołać SQLGetFunctions z SQL_API_ODBC3_ALL_FUNCTIONS przeciwko sterownikowi ODBC 3*.x* lub ODBC 2*.x*.

Jeśli FunctionId jest SQL_API_ALL_FUNCTIONS, SupportedPtr wskazuje na tablicę SQLUSMALLINT składającą się ze 100 elementów. Tablica jest indeksowana przez #define wartości używane przez FunctionId do identyfikacji każdej funkcji ODBC; niektóre elementy tablicy są nieużywane i zarezerwowane na przyszłość. Element jest SQL_TRUE, jeśli identyfikuje funkcję ODBC 2*.x* lub starszą obsługiwaną przez sterownik. Jest SQL_FALSE, jeśli identyfikuje funkcję ODBC nieobsługiwaną przez sterownik lub nie identyfikuje funkcji ODBC.

Tablice zwracane w *SupportedPtr wykorzystują indeksowanie oparte na zerze.

Zwroty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy SQLGetFunctions zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLGetDiagRec, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_DBC oraz HandleConnectionHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLGetFunctions i wyjaśnia każdą z nich w kontekście tej funkcji; notacja "(DM)" poprzedza opisy stanów SQL zwracanych przez Menedżera Sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.

SQLSTATE Error Description
01000 Ostrzeżenie ogólne Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO).
08S01 Błąd połączenia komunikacyjnego Połączenie komunikacyjne między sterownikiem a źródłem danych, z którym sterownik został połączony, nie powiodło się przed zakończeniem przetwarzania funkcji.
HY000 Błąd ogólny Wystąpił błąd, dla którego nie było określonego stanu SQLSTATE i dla którego nie zdefiniowano parametru SQLSTATE specyficznego dla implementacji. Komunikat o błędzie zwrócony przez element SQLGetDiagRec w buforze *MessageText opisuje błąd i jego przyczynę.
HY001 Błąd alokacji pamięci Sterownik nie może przydzielić pamięci wymaganej do obsługi wykonywania lub ukończenia funkcji.
HY010 Błąd sekwencji funkcji (DM) SQLGetFunctions był wywoływany przed SQLConnect, SQLBrowseConnect lub SQLDriverConnect.

(DM) SQLBrowseConnect został wywołany dla ConnectionHandle i zwrócił SQL_NEED_DATA. Funkcja ta była wywoływana przed zwróceniem przez SQLBrowseConnect SQL_SUCCESS_WITH_INFO lub SQL_SUCCESS.

(DM) SQLExecute, SQLExecDirect lub SQLMoreResults zostały wywołane dla ConnectionHandle i zwracały SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo.
HY013 Błąd zarządzania pamięcią Nie można przetworzyć wywołania funkcji, ponieważ nie można uzyskać dostępu do bazowych obiektów pamięci, prawdopodobnie z powodu niskich warunków pamięci.
HY095 Typ funkcji poza zakresem (DM) Podano nieprawidłową wartość FunctionId .
HY117 Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu. (DM) Aby uzyskać więcej informacji na temat stanu wstrzymania, zobacz SQLEndTran, funkcja.
HYT01 Upłynął limit czasu połączenia Okres przekroczenia limitu czasu połączenia wygasł, zanim źródło danych odpowiedziało na żądanie. Limit czasu połączenia jest ustawiany za pomocą parametru SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.

Comments

SQLGetFunctions zawsze zwraca informację, że obsługiwane są SQLGetFunctions, SQLDataSources i SQLDrivers . Robi to, ponieważ funkcje te są zaimplementowane w Menedżerze Sterowników. Driver Manager mapuje funkcję ANSI na odpowiadającą mu funkcję Unicode, jeśli taka funkcja istnieje, a także mapuje funkcję Unicode na odpowiadającą mu funkcję ANSI, jeśli funkcja ANSI istnieje. Aby uzyskać informacje o tym, jak aplikacje wykorzystują SQLGetFunctions, zobacz Poziomy zgodności interfejsów.

Poniżej znajduje się lista prawidłowych wartości dla FunctionId dla funkcji spełniających poziom zgodności norm ISO 92:

Wartość FunctionId Wartość FunctionId
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

Poniżej znajduje się lista poprawnych wartości FunctionId dla funkcji spełniających poziom zgodności ze standardami Open Group:

Wartość FunctionId Wartość FunctionId
SQL_API_SQLCOLUMNS SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS SQL_API_SQLTABLES

Poniżej znajduje się lista poprawnych wartości FunctionId dla funkcji zgodnych z poziomem zgodności ze standardami ODBC.

Wartość FunctionId Wartość FunctionId
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] Podczas pracy z sterownikiem ODBC 2*.x*, SQLBulkOperations będzie zwracany jako obsługiwany tylko wtedy, gdy oba poniższe elementy są prawdziwe: sterownik ODBC 2*.x* obsługuje SQLSetPos, a typ informacji SQL_POS_OPERATIONS zwraca SQL_POS_ADD bit zgodnie z ustawieniami.

Poniżej znajduje się lista poprawnych wartości dla FunctionId dla funkcji wprowadzonych w ODBC 3.8 lub nowszych:

Wartość FunctionId
SQL_API_SQLCANCELHANDLE [2]

[2] SQLCancelHandle zostanie zwrócony jako wspierany tylko wtedy, gdy sterownik obsługuje zarówno SQLCancel, jak i SQLCancelHandle. Jeśli SQLCancel jest obsługiwany, a SQLCancelHandle nie, aplikacja nadal może wywołać SQLCancelHandle na poleceniu instrukcji, ponieważ będzie on przypisany do SQLCancel.

SQL_FUNC_EXISTS Macro

Makro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) służy do określenia wsparcia funkcji ODBC 3*.x* lub wcześniejszych po wywołaniu SQLGetFunctions za pomocą argumentu FunctionId SQL_API_ODBC3_ALL_FUNCTIONS. Wywołania aplikacji SQL_FUNC_EXISTS z argumentem SupportedPtr ustawionym na SupportedPtr przekazanym w SQLGetFunctions oraz z argumentem FunctionID ustawionym na #define dla tej funkcji. SQL_FUNC_EXISTS zwraca SQL_TRUE, jeśli funkcja jest wspierana, a SQL_FALSE w przeciwnym przypadku.

Note

Podczas pracy z sterownikiem ODBC 2*.x*, menedżer sterowników ODBC 3*.x* zwraca SQL_TRUE dla SQLAllocHandle i SQLFreeHandle , ponieważ SQLAllocHandle jest mapowany na SQLAllocEnv, SQLAllocConnect lub SQLAllocStmt, a także dlatego, że SQLFreeHandle jest mapowany na SQLFreeEnv, SQLFreeConnect lub SQLFreeStmt. SQLAllocHandle lub SQLFreeHandle z argumentem HandleType SQL_HANDLE_DESC nie jest obsługiwany, mimo że SQL_TRUE jest zwracany dla funkcji, ponieważ w tym przypadku nie ma funkcji ODBC 2*.x*, do której można by się odwzorować.

Przykład kodu

Poniższe trzy przykłady pokazują, jak aplikacja wykorzystuje SQLGetFunctions do określenia, czy sterownik obsługuje SQLTables, SQLColumns i SQLStatistics. Jeśli sterownik nie obsługuje tych funkcji, aplikacja rozłącza się z sterownikiem. Pierwszy przykład wywołuje SQLGetFunctions raz dla każdej funkcji.

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

W drugim przykładzie aplikacja ODBC 3.x wywołuje SQLGetFunctions i przekazuje mu tablicę, w której SQLGetFunctions zwraca informacje o wszystkich funkcjach ODBC 3.x i wcześniejszych.

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 (retcode == 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);

Trzecim przykładem jest aplikacja ODBC 2.x wywołująca SQLGetFunctions i przekazuje jej tablicę 100 elementów, w której SQLGetFunctions zwraca informacje o wszystkich funkcjach ODBC 2.x i wcześniejszych.

#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);
Aby uzyskać informacje o Zobacz
Zwracanie ustawienia atrybutu połączenia SQLGetConnectAttr, funkcja
Zwracanie informacji o sterowniku lub źródle danych Funkcja SQLGetInfo
Zwracanie ustawienia atrybutu instrukcji SQLGetStmtAttr, funkcja

Treści powiązane

  • Last updated on