SQLDrivers, funkcja

Zgodność
Wprowadzona wersja: Zgodność ze standardami ODBC 2.0: ODBC

Podsumowanie
SQLDrivers zawiera opisy sterowników oraz słowa kluczowe atrybutów sterowników. Funkcja ta jest realizowana wyłącznie przez Driver Manager.

Syntax

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);

Arguments

EnvironmentHandle
[Input] Zarządzanie środowiskiem.

Kierunek
[Input] Określa, czy Driver Manager pobiera następny opis sterownika z listy (SQL_FETCH_NEXT), czy też wyszukiwanie zaczyna się od początku listy (SQL_FETCH_FIRST).

DriverDescription
[Wyjście] Wskaźnik do bufora, w którym zwraca opis sterownika.

Jeśli DriverDescription jest NULL, DescriptionLengthPtr nadal zwraca łączną liczbę znaków (z wyłączeniem znaku zakończenia zera dla danych znaków) dostępnych do zwrócenia w buforze wskazanym przez DriverDescription.

BufferLength1
[Input] Długość bufora *DriverDescription , w znakach.

DescriptionLengthPtr
[Wyjście] Wskaźnik do bufora, w którym można zwrócić łączną liczbę znaków (z wyłączeniem znaku zakończenia zerowego) dostępnych do zwrócenia w *DriverDescription. Jeśli liczba znaków dostępnych do zwracania jest większa lub równa BufferLength1, opis sterownika w *DriverDescription jest skracany do BufferLength1 minus długość znaku zakończenia zerowego.

DriverAttributes
[Wyjście] Wskaźnik do bufora, w którym zwraca listę par wartości atrybutów sterownika (patrz "Komentarze").

Jeśli DriverAttributes jest NULL, AttributesLengthPtr nadal zwróci łączną liczbę bajtów (z wyłączeniem znaku zakończenia zera dla danych znaków) dostępnych do zwrócenia w buforze wskazanym przez DriverAttributes.

BufferLength2
[Input] Długość bufora *DriverAttributes , w znakach. Jeśli wartość *DriverDescription jest ciągiem znaków Unicode (wywołując SQLDriversW), argument BufferLength musi mieć parzystą liczbę.

AttributesLengthPtr
[Wyjście] Wskaźnik do bufora, w którym można zwrócić łączną liczbę bajtów (z wyłączeniem bajtu zakończenia zerowego) dostępnych do zwrotu w *DriverAttributes. Jeśli liczba bajtów dostępnych do zwrócenia jest większa lub równa BufferLength2, lista par wartości atrybutów w *DriverAttributes jest skracana do BufferLength2 minus długość znaku zakończenia zerowego.

Zwroty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy SQLDrivers zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_ENV oraz HandlemEnvironmentHandle. Poniższa tabela przedstawia wartości SQLSTATE typowo zwracane przez SQLDrivers 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 (DM) Komunikat informacyjny specyficzny dla Driver Managera. (Funkcja zwraca SQL_SUCCESS_WITH_INFO).
01004 Dane ciągów, prawe obcięte (DM) Bufor *DriverDescription nie był wystarczająco duży, aby zwrócić pełny opis sterownika. W związku z tym opis został skrócony. Długość pełnego opisu sterownika jest zwracana w *DescriptionLengthPtr. (Funkcja zwraca SQL_SUCCESS_WITH_INFO).

(DM) Bufor *DriverAttributes nie był wystarczająco duży, aby zwrócić pełną listę par wartości atrybutów. W związku z tym lista została skrócona. Długość nieobciętej listy par wartości atrybutów jest zwracana w *AttributesLengthPtr. (Funkcja zwraca SQL_SUCCESS_WITH_INFO).
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 (DM) Driver Manager nie był w stanie przydzielić pamięci potrzebnej do wsparcia wykonania lub zakończenia funkcji.
HY010 Błąd sekwencji funkcji (DM) SqlExecute, SQLExecDirect lub SQLMoreResults została wywołana dla instrukcji StatementHandle i zwrócona 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.
HY090 Nieprawidłowa długość ciągu lub buforu (DM) Wartość podania argumentu BufferLength1 była mniejsza niż 0.

(DM) Wartość podana dla argumentu BufferLength2 była mniejsza niż 0 lub równa 1.
HY103 Nieprawidłowy kod odzyskiwania (DM) Wartość określona dla argumentu Kierunek nie była równa SQL_FETCH_FIRST ani SQL_FETCH_NEXT.
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.

Comments

SQLDrivers zwraca opis sterownika w buforze *DriverDescription . Zwraca dodatkowe informacje o sterowniku w buforze *DriverAttributes jako listę par słów klucz-wartość. Wszystkie słowa kluczowe wymienione w informacjach systemowych sterowników będą zwracane dla wszystkich sterowników, z wyjątkiem CreateDSN, który służy do tworzenia źródeł danych i dlatego jest opcjonalny. Każda para kończy się bajtem zerowym, a pełna lista kończy się bajtem null (czyli dwa bajty zerowe oznaczają koniec listy). Na przykład sterownik oparty na plikach wykorzystujący składnię C może zwracać następującą listę atrybutów ("\0" oznacza znak null):

FileUsage=1\0FileExtns=*.dbf\0\0

Jeśli *DriverAttributes nie jest wystarczająco duży, by pomieścić całą listę, lista jest obcięta, SQLDrivers zwraca SQLSTATE 01004 (Data Truncated), a długość listy (z wyłączeniem ostatniego bajtu zakończenia zerowego) jest zwracana w *AttributesLengthPtr.

Słowa kluczowe atrybutów sterownika są dodawane z informacji systemowych podczas instalacji sterownika. Więcej informacji można znaleźć w artykule Instalacja komponentów ODBC.

Aplikacja może wielokrotnie wywoływać SQLDrivers , aby pobrać wszystkie opisy sterowników. Driver Manager pobiera te informacje z danych systemowych. Gdy nie ma już więcej opisów sterowników, SQLDrivers zwraca SQL_NO_DATA. Jeśli SQLDrivers zostanie wywołany z SQL_FETCH_NEXT zaraz po powrocie SQL_NO_DATA, zwraca pierwszy opis sterownika. Aby uzyskać informacje o tym, jak aplikacja wykorzystuje informacje zwracane przez SQLDrivers, zobacz Wybór źródła danych lub sterownika.

Jeśli SQL_FETCH_NEXT zostanie przekazany do SQLDrivers przy pierwszym wywołaniu, SQLDrivers zwraca pierwszą nazwę źródła danych.

Ponieważ SQLDrivers jest zaimplementowany w Driver Managerze, jest obsługiwany dla wszystkich sterowników niezależnie od zgodności standardów danego sterownika.

Aby uzyskać informacje o Zobacz
Odkrywanie i wypisywanie wartości wymaganych do połączenia ze źródłem danych Funkcja SQLBrowseConnect
Nawiązywanie połączenia ze źródłem danych Funkcja SQLConnect
Zwracanie nazw źródeł danych Funkcja SQLDataSources
Łączenie się ze źródłem danych za pomocą parametry połączenia lub okna dialogowego funkcja SQLDriverConnect

Treści powiązane

  • Last updated on