SQLSetDescRec, funkcja
zgodności
Wersja wprowadzona: Zgodność ze standardami ODBC 3.0: ISO 92
podsumowania
Funkcja SQLSetDescRec ustawia wiele pól deskryptora mających wpływ na typ danych i bufor powiązany z danymi kolumny lub parametrów.
Składnia
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
Argumenty
DeskryptorHandle
[Dane wejściowe] Uchwyt deskryptora. Nie może to być uchwyt IRD.
RecNumber
[Dane wejściowe] Wskazuje rekord deskryptora zawierający pola do ustawienia. Rekordy deskryptora są numerowane z zakresu 0, a rekord 0 jest rekordem zakładki. Ten argument musi być równy lub większy niż 0. Jeśli RecNumber jest większa niż wartość SQL_DESC_COUNT, SQL_DESC_COUNTis została zmieniona na wartość RecNumber.
typu
[Dane wejściowe] Wartość, do której ma być ustawione pole SQL_DESC_TYPE dla rekordu deskryptora.
podtypu
[Dane wejściowe] W przypadku rekordów, których typ jest SQL_DATETIME lub SQL_INTERVAL, jest to wartość, do której należy ustawić pole SQL_DESC_DATETIME_INTERVAL_CODE.
długości
[Dane wejściowe] Wartość, do której ma być ustawione pole SQL_DESC_OCTET_LENGTH dla rekordu deskryptora.
precyzji
[Dane wejściowe] Wartość, do której ma być ustawione pole SQL_DESC_PRECISION dla rekordu deskryptora.
Skalowanie
[Dane wejściowe] Wartość, do której ma być ustawione pole SQL_DESC_SCALE dla rekordu deskryptora.
[Odroczone dane wejściowe lub wyjściowe] Wartość, do której ma być ustawione pole SQL_DESC_DATA_PTR dla rekordu deskryptora.
DataPtr można ustawić na wskaźnik o wartości null.
Argument DataPtr można ustawić na wskaźnik o wartości null, aby ustawić pole SQL_DESC_DATA_PTR na wskaźnik o wartości null. Jeśli uchwyt w DescriptorHandle argument jest skojarzony z ARD, spowoduje to usunięcie powiązania kolumny.
stringLengthPtr
[Odroczone dane wejściowe lub wyjściowe] Wartość, do której ma być ustawione pole SQL_DESC_OCTET_LENGTH_PTR dla rekordu deskryptora.
StringLengthPtr można ustawić wskaźnik o wartości null, aby ustawić pole SQL_DESC_OCTET_LENGTH_PTR na wskaźnik o wartości null.
[Odroczone dane wejściowe lub wyjściowe] Wartość, do której ma być ustawione pole SQL_DESC_INDICATOR_PTR dla rekordu deskryptora.
IndicatorPtr można ustawić wskaźnik o wartości null, aby ustawić pole SQL_DESC_INDICATOR_PTR na wskaźnik o wartości null.
Zwraca
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy
| SQLSTATE | Błąd | Opis |
|---|---|---|
| 01000 | Ostrzeżenie ogólne | Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 07009 | Nieprawidłowy indeks deskryptora | Argument Argument RecNumber był mniejszy niż 0. Argument RecNumber był większy niż maksymalna liczba kolumn lub parametrów, które źródło danych może obsługiwać, a argument DescriptorHandle był APD, IPD lub ARD. Argument RecNumber był równy 0, a argument DescriptorHandle odniósł się do niejawnie przydzielonego interfejsu APD. (Ten błąd nie występuje z jawnie przydzielonym deskryptorem aplikacji, ponieważ nie wiadomo, czy deskryptor jawnie przydzielonej aplikacji jest APD, czy ARD do czasu wykonania). |
| 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 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) DescriptorHandle została skojarzona z StatementHandle, dla której asynchronicznie wykonywana funkcja (a nie ta) została wywołana i nadal była wykonywana po wywołaniu tej funkcji. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationslub SQLSetPos został wywołany StatementHandle, z którym DescriptorHandle był skojarzony i zwracany SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn. (DM) Asynchronicznie wykonywana funkcja została wywołana dla dojścia połączenia skojarzonego z DescriptorHandle. Ta funkcja asynchroniczna była nadal wykonywana, gdy wywołano funkcję SQLSetDescRec. (DM) SQLExecute, SQLExecDirectlub SQLMoreResults został wywołany do jednego z dojść instrukcji skojarzonych z DescriptorHandle i zwrócił 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. |
| HY016 | Nie można zmodyfikować deskryptora wiersza implementacji | Argument DescriptorHandle został skojarzony z IRD. |
| HY021 | Niespójne informacje deskryptora | Pole Type lub inne pole skojarzone z polem SQL_DESC_TYPE w deskryptorze było nieprawidłowe lub spójne. Informacje deskryptora sprawdzane podczas sprawdzania spójności nie były spójne. (Zobacz sekcję "Sprawdzanie spójności", w dalszej części tej sekcji). |
| HY090 | Nieprawidłowa długość ciągu lub buforu | (DM) Sterownik był sterownikiem ODBC 2.x, deskryptor był ARD, argument ColumnNumber został ustawiony na 0, a wartość określona dla argumentu BufferLength nie była równa 4. |
| 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 funkcja SQLEndTran. |
| 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ą SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Sterownik nie obsługuje tej funkcji | (DM) Sterownik skojarzony z DescriptorHandle nie obsługuje funkcji. |
Komentarze
Aplikacja może wywołać SQLSetDescRec, aby ustawić następujące pola dla jednej kolumny lub parametru:
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (dla rekordów, których typ jest SQL_DATETIME lub SQL_INTERVAL)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
Nuta
Jeśli wywołanie metody SQLSetDescRec zakończy się niepowodzeniem, zawartość rekordu deskryptora zidentyfikowanego przez argument RecNumber jest niezdefiniowana.
Podczas tworzenia powiązania kolumny lub parametru SQLSetDescRec umożliwia zmianę wielu pól wpływających na powiązanie bez wywoływania SQLBindCol lub SQLBindParameter lub wykonywania wielu wywołań SQLSetDescField. SQLSetDescRec może ustawiać pola na deskryptorze, który nie jest obecnie skojarzony z instrukcją. Należy pamiętać, że SQLBindParameter ustawia więcej pól niż SQLSetDescRec, może ustawić pola zarówno na APD, jak i IPD w jednym wywołaniu i nie wymaga uchwytu deskryptora.
Nuta
Atrybut instrukcji SQL_ATTR_USE_BOOKMARKS należy zawsze ustawiać przed wywołaniem SQLSetDescRec z RecNum ber argumentem 0, aby ustawić pola zakładki. Chociaż nie jest to obowiązkowe, zdecydowanie zaleca się.
Sprawdzanie spójności
Sprawdzanie spójności jest wykonywane przez sterownik automatycznie za każdym razem, gdy aplikacja ustawia pole SQL_DESC_DATA_PTR APD, ARD lub IPD. Jeśli którekolwiek z pól jest niespójne z innymi polami, SQLSetDescRec zwróci sqlSTATE HY021 (niespójne informacje deskryptora).
Za każdym razem, gdy aplikacja ustawia pole SQL_DESC_DATA_PTR apD, ARD lub IPD, sterownik sprawdza, czy wartość pola SQL_DESC_TYPE i wartości dotyczące tego pola SQL_DESC_TYPE są prawidłowe i spójne. Ta kontrola jest zawsze wykonywana, gdy jest wywoływana sqlBindParameter lub SQLBindCol lub gdy SQLSetDescRec jest wywoływana dla usługi APD, ARD lub IPD. Ten sprawdzanie spójności obejmuje następujące kontrole pól deskryptora:
Pole SQL_DESC_TYPE musi być jednym z prawidłowych typów ODBC C lub SQL lub typu SQL specyficznego dla sterownika. Pole SQL_DESC_CONCISE_TYPE musi być jednym z prawidłowych typów C lub SQL ODBC albo typu C lub SQL specyficznego dla sterownika, w tym zwięzłe typy daty/godziny i interwału.
Jeśli pole rekordu SQL_DESC_TYPE jest SQL_DATETIME lub SQL_INTERVAL, pole SQL_DESC_DATETIME_INTERVAL_CODE musi być jednym z prawidłowych kodów daty/godziny lub interwału. (Zobacz opis pola SQL_DESC_DATETIME_INTERVAL_CODE w SQLSetDescField).)
Jeśli pole SQL_DESC_TYPE wskazuje typ liczbowy, pola SQL_DESC_PRECISION i SQL_DESC_SCALE są weryfikowane jako prawidłowe.
Jeśli pole SQL_DESC_CONCISE_TYPE jest typem danych znacznika czasu lub sygnatury czasowej, typ interwału ze składnikiem sekund lub jednym z typów danych interwału ze składnikiem czasu, pole SQL_DESC_PRECISION jest weryfikowane jako prawidłowa precyzja sekund.
Jeśli SQL_DESC_CONCISE_TYPE jest typem danych interwału, pole SQL_DESC_DATETIME_INTERVAL_PRECISION jest weryfikowane jako prawidłowa wartość precyzji wiodącej interwału.
Pole SQL_DESC_DATA_PTR ipD nie jest zwykle ustawione; jednak aplikacja może to zrobić, aby wymusić sprawdzanie spójności pól IPD. Nie można przeprowadzić sprawdzania spójności na IRD. Wartość ustawiona na wartość pola SQL_DESC_DATA_PTR adresu IPD nie jest rzeczywiście przechowywana i nie może zostać pobrana przez wywołanie polecenia SQLGetDescField lub SQLGetDescRec; ustawienie jest wykonywane tylko w celu wymuszenia sprawdzania spójności.
Powiązane funkcje
Zobacz też
dokumentacja interfejsu API ODBC
plików nagłówków ODBC