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ść
Wersja wprowadzona: Zgodność ze standardami ODBC 1.0: ISO 92
Podsumowanie
SQLDescribeCol zwraca deskryptor wyników – nazwę kolumny, typ, rozmiar kolumny, cyfry dziesiętne i możliwość zerowania – dla jednej kolumny w zbiorze wyników. Informacje te są również dostępne w dziedzinach IRD.
Syntax
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Arguments
StatementHandle
[Dane wejściowe] Uchwyt instrukcji.
ColumnNumber
[Input] Liczba kolumn danych wyników, uporządkowana kolejno w rosnącej kolejności kolumn, zaczynając od 1. Argument ColumnNumber można również ustawić na 0, aby opisać kolumnę zakładek.
Nazwakolumny
[Wyjście] Wskaźnik do bufora zakończonego zerem, w którym zwraca nazwę kolumny. Ta wartość jest odczytywana z pola SQL_DESC_NAME IRD. Jeśli kolumna jest bezimienna lub nie można ustalić nazwy kolumny, sterownik zwraca pusty ciąg danych.
Jeśli ColumnName jest NULL, NameLengthPtr nadal zwraca łączną liczbę znaków (z wyłączeniem znaku zakończenia zera dla danych znakowych) dostępnych do zwrócenia w buforze wskazanym przez ColumnName.
BufferLength
[Input] Długość bufora *Nazwa kolumny , w znakach.
NameLengthPtr
[Wyjście] Wskaźnik do bufora, w którym zwraca się łączna liczba znaków (z wyłączeniem zakończenia null) dostępnych do zwrotu w *ColumnName. Jeśli liczba znaków dostępnych do zwracania jest większa lub równa BufferLength, nazwa kolumny w *ColumnName jest obcięta do BufferLength minus długość znaku zakończenia zerowego.
DataTypePtr
[Wyjście] Wskaźnik do bufora, w którym zwraca się typ danych SQL kolumny. Ta wartość jest odczytywana z pola SQL_DESC_CONCISE_TYPE IRD. Będzie to jedna z wartości w typach danych SQL lub specyficznym dla sterownika typie danych SQL. Jeśli nie można określić typu danych, sterownik zwraca SQL_UNKNOWN_TYPE.
W ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME lub SQL_TYPE_TIMESTAMP jest zwracane w *DataTypePtr odpowiednio dla daty, godziny lub znacznika czasu; w ODBC 2. x, SQL_DATE, SQL_TIME lub SQL_TIMESTAMP zostaje zwrócone. Driver Manager wykonuje wymagane mapowania podczas ODBC 2. Aplikacja x działa z ODBC 3. x lub gdy ODBC 3. Aplikacja x działa z ODBC 2. x driver.
Gdy ColumnNumber jest równy 0 (dla kolumny zakładek), SQL_BINARY jest zwracane w *DataTypePtr dla zakładek o zmiennej długości. (SQL_INTEGER zwraca, jeśli zakładki są używane przez ODBC 3. x aplikacja pracująca z ODBC 2. x lub przez ODBC 2. x aplikacja działająca z ODBC 3. x driver.)
Aby uzyskać więcej informacji na temat tych typów danych, zobacz Typy danych SQL w Załączniku D: Typy danych. Aby uzyskać informacje o typach danych SQL specyficznych dla sterownika, zobacz dokumentację sterownika.
ColumnSizePtr
[Wyjście] Wskaźnik do bufora, w którym zwraca się rozmiar (w znakach) kolumny na źródle danych. Jeśli nie można określić rozmiaru kolumny, sterownik zwraca 0. Więcej informacji o rozmiarze kolumny można znaleźć w artykule Column Size, Decimal Digits, Transfer Octet Length oraz Display Size w Załączniku D: Typy danych.
DecimalDigitsPtr
[Wyjście] Wskaźnik do bufora, w którym zwraca się liczbę cyfr dziesiętnych kolumny na źródle danych. Jeśli nie można określić liczby cyfr przecinkowych lub nie jest ona stosowalna, sterownik zwraca 0. Więcej informacji o cyfrach przecinkowych można znaleźć w artykule Column Size, Decimal Digits, Transfer Octet Length oraz Display Size w Załączniku D: Typy danych.
NullablePtr
[Wyjście] Wskaźnik do bufora, w którym zwraca wartość wskazującą, czy kolumna dopuszcza wartości NULL. Ta wartość jest odczytywana z pola SQL_DESC_NULLABLE IRD. Wartość jest jedną z następujących wartości:
SQL_NO_NULLS: Kolumna nie dopuszcza wartości NULL.
SQL_NULLABLE: Kolumna pozwala na wartości NULL.
SQL_NULLABLE_UNKNOWN: Sterownik nie może określić, czy kolumna dopuszcza wartości NULL.
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy SQLDescribeCol zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, powiązaną wartość SQLSTATE można uzyskać, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz Handle of StatementHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLDescribeCol 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 *ColumnName nie był wystarczająco duży, by zwrócić całą nazwę kolumny, więc nazwa kolumny została obcięta. Długość nieobciętej nazwy kolumny zwracana jest w *NameLengthPtr. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 07005 | Przygotowane zdanie, a nie specyfikacja kursora | Instrukcja powiązana z StatementHandle nie zwracała zbioru wyników. Nie było żadnych kolumn do opisania. |
| 07009 | Nieprawidłowy indeks deskryptorów | (DM) Wartość określona dla argumentu ColumnNumber była równa 0, a opcja SQL_ATTR_USE_BOOKMARKS wywołała SQL_UB_OFF. Wartość podana dla argumentu ColumnNumber była większa niż liczba kolumn w zbiorze wyników. |
| 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 | Awaria alokacji pamięci | Sterownik nie może przydzielić pamięci wymaganej do obsługi wykonywania lub ukończenia funkcji. |
| HY008 | Operacja anulowana | Przetwarzanie asynchroniczne zostało włączone dla instrukcji StatementHandle. Wywołano funkcję , a przed zakończeniem wykonywania wywołano metodę SQLCancel lub SQLCancelHandle w obiekcie StatementHandle. Następnie funkcja została ponownie wywołana w instrukcji StatementHandle. Wywołano funkcję , a przed zakończeniem wykonywania wywołano funkcję SQLCancel lub SQLCancelHandle na instrukcjiHandle z innego wątku w aplikacji wielowątku. |
| HY010 | Błąd sekwencji funkcji | (DM) Asynchronicznie wykonywana funkcja została wywołana dla dojścia połączenia skojarzonego z instrukcją StatementHandle. Ta asynchroniczna funkcja nadal działała, gdy wywoływano SQLDescribeCol . (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. (DM) Asynchronicznie wykonująca funkcję (a nie tę) została wywołana dla instrukcji StatementHandle i nadal była wykonywana, gdy ta funkcja została wywołana. (DM) Funkcja była wywoływana przed wywołaniem SQLPrepare, SQLExecute lub funkcji katalogowej na uchwytie instrukcji. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations lub SQLSetPos został wywołany dla instrukcjiHandle i zwrócił SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn. |
| 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ść określona dla argumentu BufferLength była mniejsza niż 0. |
| 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. |
| IM001 | Sterownik nie obsługuje tej funkcji | (DM) Sterownik skojarzony z instrukcją StatementHandle nie obsługuje funkcji. |
| IM017 | Sondowanie jest wyłączone w trybie powiadomień asynchronicznych | Za każdym razem, gdy jest używany model powiadomień, sondowanie jest wyłączone. |
| IM018 | Funkcja SQLCompleteAsync nie została wywołana w celu ukończenia poprzedniej operacji asynchronicznej na tym dojściu. | Jeśli poprzednie wywołanie funkcji na dojściu zwraca SQL_STILL_EXECUTING i jeśli tryb powiadomień jest włączony, narzędzie SQLCompleteAsync musi być wywoływane na dojściu, aby wykonać przetwarzanie końcowe i zakończyć operację. |
SQLDescribeCol może zwracać dowolny stan SQL, który SQLPrepare lub SQLExecute może być wywołany po SQLPrepare i przed SQLExecute, w zależności od tego, kiedy źródło danych ocenia polecenie SQL powiązane z uchwytem instrukcji.
Ze względów wydajnościowych aplikacja nie powinna wywoływać SQLDescribeCol przed wykonaniem instrukcji.
Comments
Aplikacja zazwyczaj wywołuje SQLDescribeCol po wywołaniu do SQLPrepare oraz przed lub po powiązanym wywołaniu do SQLExecute. Aplikacja może także wywołać SQLDescribeCol po wywołaniu do SQLExecDirect. Aby uzyskać więcej informacji, zobacz Metadane zestawu wyników.
SQLDescribeCol pobiera nazwę kolumny, typ i długość wygenerowaną przez polecenie SELECT . Jeśli kolumna jest wyrażeniem, *ColumnName jest albo pustym ciągiem znaków, albo nazwą definiowaną przez sterownik.
Note
ODBC obsługuje SQL_NULLABLE_UNKNOWN jako rozszerzenie, mimo że specyfikacja Open Group i SQL Access Group Call Level Interface nie określa opcji dla SQLDescribeCol.
Powiązane funkcje
| Aby uzyskać informacje o | Zobacz |
|---|---|
| Wiązanie buforu z kolumną w zestawie wyników | Sqlbindcol |
| Anulowanie przetwarzania instrukcji | Sqlcancel |
| Zwracanie informacji o kolumnie w zbiorze wyników | Sqlcolattribute |
| Pobieranie wielu wierszy danych | Sqlfetch |
| Zwracanie liczby kolumn zbioru wyników | Sqlnumresultcols |
| Przygotowywanie instrukcji do wykonania | Sqlprepare |