Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Zgodność
Wprowadzona wersja: Zgodność z normami ODBC 3.0: ISO 92
Podsumowanie
SQLGetDescField zwraca aktualne ustawienie lub wartość pojedynczego pola rekordu deskryptora.
Syntax
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
DeskryptorHandle
[Input] Uchwyt deskryptoru.
NumerRekordów
[Input] Wskazuje rekord deskryptorowy, z którego wniosek poszukuje informacji. Rekordy deskryptorów są numerowane od 0, gdzie numer rekordu 0 to zapis zakładek. Jeśli argument FieldIdentifier wskazuje pole nagłówka, RecNumber jest ignorowany. Jeśli RecNumber jest mniejszy lub równy SQL_DESC_COUNT, ale wiersz nie zawiera danych dla kolumny lub parametru, wywołanie SQLGetDescField zwróci domyślne wartości pól. (Więcej informacji można znaleźć w sekcji "Initialization of Descriptor Fields" w SQLSetDescField.)
FieldIdentifier
[Input] Wskazuje pole deskryptora, którego wartość ma zostać zwrócona. Więcej informacji można znaleźć w sekcji "FieldIdentifier Argument" w SQLSetDescField.
Valueptr
[Wyjście] Wskaźnik do bufora, w którym zwraca informacje deskryptoru. Typ danych zależy od wartości FieldIdentifier.
Jeśli ValuePtr jest typu całkowitoliczbowego, aplikacje powinny użyć bufora SQLULEN i zainicjować wartość do 0 przed wywołaniem tej funkcji, ponieważ niektóre sterowniki mogą zapisywać tylko dolny 32-bitowy lub 16-bitowy bufora, pozostawiając wyższy bit bez zmian.
Jeśli ValuePtr jest NULL, StringLengthPtr nadal zwraca łączną liczbę bajtów (z wyłączeniem znaku zakończenia zera dla danych znaków) dostępnych do zwrócenia w buforze wskazanym przez ValuePtr.
BufferLength
[Input] Jeśli FieldIdentifier jest polem zdefiniowanym przez ODBC, a ValuePtr wskazuje na ciąg znaków lub bufor binarny, ten argument powinien być długością *ValuePtr. Jeśli FieldIdentifier jest polem zdefiniowanym przez ODBC, a *ValuePtr jest liczbą całkowitą, BufferLength jest ignorowany. Jeśli wartość w *ValuePtr należy do typu danych Unicode (wywołując SQLGetDescFieldW), argument BufferLength musi mieć parzystą liczbę.
Jeśli FieldIdentifier jest polem definiowanym przez sterownik, aplikacja wskazuje charakter pola Driver Managerowi, ustawiając argument BufferLength . BufferLength może mieć następujące wartości:
Jeśli *ValuePtr jest wskaźnikiem do ciągu znaków, to BufferLength to długość ciągu lub SQL_NTS.
Jeśli *ValuePtr jest wskaźnikiem do bufora binarnego, aplikacja umieszcza wynik makra SQL_LEN_BINARY_ATTR(length) w BufferLength. To umieszcza wartość ujemną w BufferLength.
Jeśli *ValuePtr jest wskaźnikiem do wartości innej niż ciąg znaków lub ciąg binarny, to BufferLength powinien mieć wartość SQL_IS_POINTER.
Jeśli *ValuePtr zawiera typ danych o stałej długości, to BufferLength jest albo SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT lub SQL_IS_USMALLINT, w zależności od potrzeby.
StringLengthPtr
[Wyjście] Wskaźnik do bufora, w którym można zwrócić łączną liczbę bajtów (z wyłączeniem liczby bajtów wymaganych dla znaku zakończenia zerowego) dostępnych do zwrotu w *ValuePtr.
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA lub SQL_INVALID_HANDLE.
SQL_NO_DATA zwracany, jeśli RecNumber jest większy niż aktualna liczba rekordów deskryptorów.
SQL_NO_DATA zwracany, jeśli DescriptorHandle jest uchwytem IRD, a instrukcja znajduje się w stanie przygotowanym lub wykonanym, ale nie było z nią powiązanego otwartego kursora.
Diagnostyka
Gdy SQLGetDescField zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz HandleStatementHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLGetDescField 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). |
| 01004 | Dane ciągów, prawe obcięte | Bufor *ValuePtr nie był wystarczająco duży, by zwrócić całe pole deskryptoru, więc pole zostało obcięte. Długość nieobciętego pola deskryptorowego zwracana jest w *StringLengthPtr. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 07009 | Nieprawidłowy indeks deskryptorów | (DM) Argument RecNumber był równy 0, atrybut SQL_ATTR_USE_BOOKMARK instrukcji SQL_UB_OFF, a argument DescriptorHandle był handlem IRD. (Ten błąd może być zwrócony dla jawnie przydzielonego deskryptora tylko wtedy, gdy jest on powiązany z uchwytem instrukcji.) Argument FieldIdentifier był polem rekordu, argument RecNumber miał 0, a argument DescriptorHandle był handlem IPD. Argument RecNumber był mniejszy niż 0. |
| 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 był w stanie przydzielić pamięci potrzebnej do wykonania lub zakończenia funkcji. |
| HY007 | Powiązane oświadczenie nie jest przygotowane | DescriptorHandle był powiązany z StatementHandle jako IRD, a powiązany handle instrukcji nie był przygotowany ani wykonany. |
| HY010 | Błąd sekwencji funkcji | (DM) DescriptorHandle był powiązany z CommandHandle , dla którego wywoływano asynchronicznie wykonywaną funkcję (nie tę) i która nadal działała, gdy ta funkcja została wywołana. (DM) DescriptorHandle był powiązany z StatementHandle , dla którego wywoływano SQLExecute, SQLExecDirect, SQLBulkOperations lub SQLSetPos i zwracało SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn. (DM) Funkcja wykonywana asynchronicznie została wywołana dla uchwytu połączenia powiązanego z DescriptorHandle. Ta asynchroniczna funkcja działała nadal, gdy wywoływano funkcję SQLGetDescField . |
| 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. |
| HY021 | Niespójne informacje o deskryptorze | Pola SQL_DESC_TYPE i SQL_DESC_DATETIME_INTERVAL_CODE nie tworzą prawidłowego typu SQL ODBC, specyficznego dla sterownika typu SQL (dla IPD) ani ważnego typu ODBC C (dla APD lub ARD). |
| HY090 | Nieprawidłowa długość ciągu lub buforu | (DM) *ValuePtr był ciągiem znaków, a BufferLength był mniejszy niż zero. |
| HY091 | Nieprawidłowy identyfikator pola deskryptorowego |
FieldIdentifier nie był polem definiowanym przez ODBC i nie był wartością definiowaną przez implementację. FieldIdentifier nie był zdefiniowany dla DescriptorHandle. |
| HY117 | Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu. | (DM) Więcej informacji o stanie zawieszenia można znaleźć w sekcji SQLEndTran Function. |
| 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. |
| IM001 | Sterownik nie obsługuje tej funkcji | (DM) Sterownik powiązany z DescriptorHandle nie obsługuje tej funkcji. |
Comments
Aplikacja może wywołać pole SQLGetDescField , aby zwrócić wartość pojedynczego pola rekordu deskryptoru. Wywołanie do SQLGetDescField może zwrócić ustawienie dowolnego pola w dowolnym typie deskryptoru, w tym pola nagłówka, rekordu i zakładek. Aplikacja może uzyskać ustawienia wielu pól w tych samych lub różnych deskryptorach, w dowolnej kolejności, wykonując wielokrotne wywołania do SQLGetDescField. SQLGetDescField może być również wywołany, aby zwracać pola deskryptoryczne zdefiniowane przez sterowniki.
Ze względów wydajnościowych aplikacja nie powinna wywoływać SQLGetDescField dla IRD przed wykonaniem instrukcji.
Ustawienia wielu pól opisujących nazwę, typ danych oraz przechowywanie danych kolumnowych lub parametrów można również pobrać w jednym wywołaniu do SQLGetDescRec. SQLGetStmtAttr można wywołać, aby zwrócić ustawienie pojedynczego pola w nagłówku deskryptoru, które jest również atrybutem instrukcji. SQLColAttribute, SQLDescribeCol oraz SQLDescribeParam zwracają pole do zapisu lub zakładek.
Gdy aplikacja wywołuje SQLGetDescField , aby pobrać wartość pola niezdefiniowanego dla danego typu deskryptora, funkcja zwraca SQL_SUCCESS, ale wartość zwrócona dla pola jest niezdefiniowana. Na przykład, wywołanie pola SQLGetDescField dla pola SQL_DESC_NAME lub SQL_DESC_NULLABLE w APD lub ARD zwróci SQL_SUCCESS, ale niezdefiniowaną wartość dla pola.
Gdy aplikacja wywołuje SQLGetDescField , aby pobrać wartość pola zdefiniowanego dla określonego typu deskryptora, które nie ma wartości domyślnej i nie zostało jeszcze ustawione, funkcja zwraca SQL_SUCCESS, ale wartość zwrócona dla pola jest niezdefiniowana. Więcej informacji na temat inicjalizacji pól deskryptorowych oraz opisów pól można znaleźć w sekcji "Initialization of Descriptor Fields" w SQLSetDescField. Więcej informacji o deskryptorach można znaleźć w artykule Descriptors.
Powiązane funkcje
| Aby uzyskać informacje o | Zobacz |
|---|---|
| Uzyskanie wielu pól deskryptorowych | Funkcja SQLGetDescRec |
| Ustawianie pojedynczego pola deskryptorowego | Funkcja SQLSetDescField |
| Ustawianie wielu pól deskryptorowych | Funkcja SQLSetDescRec |