SQLGetData, funkcja

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

podsumowania
SQLGetData pobiera dane dla pojedynczej kolumny w zestawie wyników lub dla pojedynczego parametru po SQLParamData zwraca SQL_PARAM_DATA_AVAILABLE. Można go wywołać wiele razy, aby pobrać dane o zmiennej długości w częściach.

Składnia

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);  

Argumenty

, instrukcjaHandle
[Dane wejściowe] Uchwyt instrukcji.

Col_or_Param_Num
[Dane wejściowe] W przypadku pobierania danych kolumny jest to liczba kolumn, dla której mają być zwracane dane. Kolumny zestawu wyników są numerowane w rosnącej kolejności kolumn rozpoczynających się od 1. Kolumna zakładki to numer kolumny 0; Można to określić tylko wtedy, gdy zakładki są włączone.

W przypadku pobierania danych parametrów jest to porządkowa parametru, który rozpoczyna się od 1.

TargetType
[Dane wejściowe] Identyfikator typu typu C buforu *TargetValuePtr. Aby uzyskać listę prawidłowych typów danych języka C i identyfikatorów typów, zobacz sekcję Typy danych języka C w dodatku D: Typy danych.

Jeśli TargetType jest SQL_ARD_TYPE, sterownik używa identyfikatora typu określonego w polu SQL_DESC_CONCISE_TYPE ARD. Jeśli TargetType jest SQL_APD_TYPE, SQLGetData użyje tego samego typu danych C określonego w SQLBindParameter. W przeciwnym razie typ danych języka C określony w SQLGetData zastępuje typ danych C określony w SQLBindParameter. Jeśli jest SQL_C_DEFAULT, sterownik wybiera domyślny typ danych C na podstawie typu danych SQL źródła.

Można również określić rozszerzony typ danych języka C. Aby uzyskać więcej informacji, zobacz C Data Types in ODBC.

TargetValuePtr
[Dane wyjściowe] Wskaźnik do buforu, w którym mają być zwracane dane.

TargetValuePtr nie może mieć wartości NULL.

BufferLength
[Dane wejściowe] Długość buforu *TargetValuePtr w bajtach.

Sterownik używa BufferLength, aby uniknąć zapisywania po końcu *TargetValuePtr bufor podczas zwracania danych o zmiennej długości, takich jak dane znakowe lub binarne. Należy pamiętać, że sterownik zlicza znak zakończenia wartości null podczas zwracania danych znaków do *TargetValuePtr. * TargetValuePtr musi zatem zawierać miejsce dla znaku zakończenia wartości null lub sterownik obcina dane.

Gdy sterownik zwraca dane o stałej długości, takie jak liczba całkowita lub struktura dat, sterownik ignoruje BufferLength i zakłada, że bufor jest wystarczająco duży, aby przechowywać dane. Dlatego ważne jest, aby aplikacja przydzieliła wystarczająco duży bufor dla danych o stałej długości lub sterownik zapisze go obok końca buforu.

SQLGetData zwraca wartość SQLSTATE HY090 (nieprawidłowy ciąg lub długość buforu), gdy BufferLength jest mniejsza niż 0, ale nie wtedy, gdy BufferLeng th wynosi 0.

StrLen_or_IndPtr
[Dane wyjściowe] Wskaźnik do buforu, w którym ma być zwracana wartość długości lub wskaźnika. Jeśli jest to wskaźnik o wartości null, nie jest zwracana żadna długość ani wartość wskaźnika. Spowoduje to zwrócenie błędu, gdy pobierane dane mają wartość NULL.

SQLGetData może zwrócić następujące wartości w buforze długości/wskaźnika:

• Długość dostępnych danych do zwrócenia

• SQL_NO_TOTAL

• SQL_NULL_DATA

Aby uzyskać więcej informacji, zobacz Używanie wartości długości/wskaźnika i "Komentarze" w tym temacie.

Zwraca

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy SQLGetData zwraca wartość SQL_ERROR lub SQL_SUCCESS_WITH_INFO, skojarzona wartość SQLSTATE można uzyskać, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT i handle instrukcji Handle. W poniższej tabeli wymieniono wartości SQLSTATE, które są często zwracane przez SQLGetData i objaśniono poszczególne wartości w kontekście tej funkcji; notacja "(DM)" poprzedza opisy obiektów SQLSTATEs zwróconych przez menedżera sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.

Komentarze

sqlGetData zwraca dane w określonej kolumnie. sqlGetData można wywołać tylko po pobraniu co najmniej jednego wiersza z zestawu wyników przez SQLFetch, SQLFetchScrolllub SQLExtendedFetchFetch. Jeśli dane o zmiennej długości są zbyt duże, aby zostały zwrócone w jednym wywołaniu, aby sqlGetData (ze względu na ograniczenie w aplikacji), SQLGetData mogą je pobrać w częściach. Istnieje możliwość powiązania niektórych kolumn z rzędu i wywołania SQLGetData dla innych, chociaż podlega to pewnym ograniczeniom. Aby uzyskać więcej informacji, zobacz Getting Long Data.

Aby uzyskać informacje na temat używania SQLGetData z parametrami wyjściowymi strumieniowymi, zobacz Pobieranie parametrów wyjściowych przy użyciuSQLGetData.

Korzystanie z danych SQLGetData

Jeśli sterownik nie obsługuje rozszerzeń SQLGetData, funkcja może zwracać dane tylko dla kolumn niepowiązanych z liczbą większą niż ostatnia powiązana kolumna. Ponadto w wierszu danych wartość argumentu Col_or_Param_Num w każdym wywołaniu SQLGetData musi być większa lub równa wartości Col_or_Param_Num w poprzednim wywołaniu; oznacza to, że dane muszą być pobierane w kolejności rosnącej liczby kolumn. Jeśli na koniec nie są obsługiwane żadne rozszerzenia, SQLGetData nie można wywołać, jeśli rozmiar zestawu wierszy jest większy niż 1.

Kierowcy mogą złagodzić dowolne z tych ograniczeń. Aby określić ograniczenia, które sterownik rozluźnia, aplikacja wywołuje SQLGetInfo z dowolną z następujących opcji SQL_GETDATA_EXTENSIONS:

• SQL_GD_OUTPUT_PARAMS = SQLGetData można wywołać w celu zwrócenia wartości parametrów wyjściowych. Aby uzyskać więcej informacji, zobacz Pobieranie parametrów wyjściowych przy użyciuSQLGetData.

• SQL_GD_ANY_COLUMN. Jeśli ta opcja zostanie zwrócona, sqlGetData można wywołać dla dowolnej niezwiązanej kolumny, w tym tych przed ostatnią powiązaną kolumną.

• SQL_GD_ANY_ORDER. Jeśli ta opcja zostanie zwrócona, sqlGetData można wywołać dla kolumn niepowiązanych w dowolnej kolejności.

• SQL_GD_BLOCK. Jeśli ta opcja jest zwracana przez SQLGetInfo dla SQL_GETDATA_EXTENSIONS InfoType, sterownik obsługuje wywołania SQLGetData, gdy rozmiar zestawu wierszy jest większy niż 1, a aplikacja może wywołać SQLSetPos z opcją SQL_POSITION umieścić kursor w odpowiednim wierszu przed wywołaniem SQLGetData.

• SQL_GD_BOUND. Jeśli ta opcja zostanie zwrócona, SQLGetData można wywołać dla powiązanych kolumn, a także niezwiązanych kolumn.

Istnieją dwa wyjątki od tych ograniczeń i zdolność kierowcy do ich złagodzenia. Najpierw sqlGetData nigdy nie należy wywoływać kursora tylko do przodu, gdy rozmiar zestawu wierszy jest większy niż 1. Po drugie, jeśli sterownik obsługuje zakładki, zawsze musi obsługiwać możliwość wywoływania SQLGetData dla kolumny 0, nawet jeśli nie zezwala aplikacjom na wywoływanie SQLGetData dla innych kolumn przed ostatnią kolumną powiązana. (Gdy aplikacja współpracuje ze sterownikiem ODBC 2*.x*, sqlGetData zostanie pomyślnie zwrócona zakładka po wywołaniu Col_or_Param_Num równej 0 po wywołaniu SQLFetch, ponieważ SQLFetch jest mapowany przez odBC 3*.x* Driver Manager do SQLExtendedFetchFetch z SQL_FETCH_NEXT, a sqlGetData z Col_or_Param_Num 0 jest mapowany przez menedżera sterowników ODBC 3*.x* na SQLGetStmtOption z fOption SQL_GET_BOOKMARK).

sqlGetData nie można użyć do pobrania zakładki dla wiersza właśnie wstawionego przez wywołanie SQLBulkOperations z opcją SQL_ADD, ponieważ kursor nie jest umieszczony w wierszu. Aplikacja może pobrać zakładkę dla takiego wiersza przez powiązanie kolumny 0 przed wywołaniem SQLBulkOperations za pomocą SQL_ADD, w tym przypadku SQLBulkOperations zwraca zakładkę w powiązanym buforze. SQLFetchScroll można wywołać za pomocą SQL_FETCH_BOOKMARK, aby zmienić położenie kursora w tym wierszu.

Jeśli argument TargetType jest typem danych interwału, domyślna precyzja wiodącej interwału (2) i domyślna precyzja interwału (6), zgodnie z ustawieniem w polach SQL_DESC_DATETIME_INTERVAL_PRECISION i SQL_DESC_PRECISION ARD, są używane dla danych. Jeśli argument TargetType jest typem danych SQL_C_NUMERIC, domyślna precyzja (zdefiniowana przez sterownik) i domyślna skala (0) ustawiona w polach SQL_DESC_PRECISION i SQL_DESC_SCALE ARD są używane dla danych. Jeśli jakakolwiek domyślna precyzja lub skala nie jest odpowiednia, aplikacja powinna jawnie ustawić odpowiednie pole deskryptora przez wywołanie metody SQLSetDescField lub SQLSetDescRec. Można ustawić pole SQL_DESC_CONCISE_TYPE na SQL_C_NUMERIC i wywołać SQLGetData z argumentem TargetType SQL_ARD_TYPE, co spowoduje dokładność i skalowanie wartości w polach deskryptora do użycia.

Pobieranie danych Variable-Length w częściach

SQLGetData mogą służyć do pobierania danych z kolumny zawierającej dane o zmiennej długości w częściach — to znaczy, gdy identyfikator typu danych SQL kolumny jest SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY lub identyfikator specyficzny dla sterownika dla typu o zmiennej długości.

Aby pobrać dane z kolumny w częściach, aplikacja wywołuje SQLGetData wiele razy z rzędu dla tej samej kolumny. W każdym wywołaniu SQLGetData zwraca następną część danych. Jest to aplikacja, aby ponownie połączyć części, dbając o usunięcie znaku zakończenia wartości null z pośrednich części danych znaków. Jeśli dla znaku zakończenia przydzielono więcej danych lub za mało buforu, sqlGetData zwraca wartość SQL_SUCCESS_WITH_INFO i SQLSTATE 01004 (dane obcięte). Gdy zwraca ostatnią część danych, funkcja SQLGetData zwraca SQL_SUCCESS. Ani SQL_NO_TOTAL, ani zero nie mogą być zwracane podczas ostatniego prawidłowego wywołania w celu pobrania danych z kolumny, ponieważ aplikacja nie ma możliwości sprawdzenia, ile danych w buforze aplikacji jest prawidłowych. Jeśli SQLGetData jest wywoływana po tym, zwraca SQL_NO_DATA. Aby uzyskać więcej informacji, zobacz następną sekcję "Pobieranie danych za pomocą danych SQLGetData".

Zakładki o zmiennej długości mogą być zwracane w częściach przez SQLGetData. Podobnie jak w przypadku innych danych, wywołanie SQLGetData zwracać zakładki o zmiennej długości w części zwróci sqlSTATE 01004 (dane ciągu, prawe obcięte) i SQL_SUCCESS_WITH_INFO, gdy zostanie zwrócona więcej danych. Różni się to od przypadku, gdy zakładka o zmiennej długości jest obcięta przez wywołanie sqlFetch lub SQLFetchScroll, która zwraca SQL_ERROR i SQLSTATE 22001 (dane ciągu, prawe obcięte).

sqlGetData nie można użyć do zwracania danych o stałej długości w częściach. Jeśli SQLGetData jest wywoływana więcej niż raz w wierszu dla kolumny zawierającej dane o stałej długości, zwraca SQL_NO_DATA dla wszystkich wywołań po pierwszym.

Pobieranie strumieniowych parametrów wyjściowych

Jeśli sterownik obsługuje parametry wyjściowe przesyłane strumieniowo, aplikacja może wywołać SQLGetData z małym buforem wiele razy, aby pobrać dużą wartość parametru. Aby uzyskać więcej informacji na temat parametru danych wyjściowych przesyłanych strumieniowo, zobacz Pobieranie parametrów wyjściowych przy użyciuSQLGetData.

Pobieranie danych za pomocą polecenia SQLGetData

Aby zwrócić dane dla określonej kolumny, SQLGetData wykonuje następującą sekwencję kroków:

1. Zwraca SQL_NO_DATA, jeśli zwrócił już wszystkie dane dla kolumny.

2. UstawiaStrLen_or_IndPtr SQL_NULL_DATA, jeśli dane mają wartość NULL. Jeśli dane mają wartość NULL i StrLen_or_IndPtr był wskaźnikiem o wartości null, SQLGetData zwraca wartość SQLSTATE 22002 (zmienna wskaźnika jest wymagana, ale nie została podana).

   Jeśli dane kolumny nie mają wartości NULL, sqlGetData przechodzi do kroku 3.

3. Jeśli atrybut instrukcji SQL_ATTR_MAX_LENGTH jest ustawiony na wartość niezerową, jeśli kolumna zawiera znaki lub dane binarne, a jeśli SQLGetData nie została wcześniej wywołana dla kolumny, dane są obcinane do SQL_ATTR_MAX_LENGTH bajtów.

   Nuta

   Atrybut instrukcji SQL_ATTR_MAX_LENGTH ma na celu zmniejszenie ruchu sieciowego. Jest on zwykle implementowany przez źródło danych, które obcina dane przed zwróceniem ich przez sieć. Sterowniki i źródła danych nie są wymagane do jej obsługi. W związku z tym, aby zagwarantować, że dane są obcięte do określonego rozmiaru, aplikacja powinna przydzielić bufor o tym rozmiarze i określić rozmiar argumentu BufferLength.

4. Konwertuje dane na typ określony w TargetType. Dane mają domyślną precyzję i skalę dla tego typu danych. Jeśli TargetType jest SQL_ARD_TYPE, używany jest typ danych w polu SQL_DESC_CONCISE_TYPE ARD. Jeśli SQL_ARD_TYPE Target Type SQL_ARD_TYPE, dane mają dokładność i skalę w polach SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION i SQL_DESC_SCALE ARD, w zależności od typu danych w polu SQL_DESC_CONCISE_TYPE. Jeśli jakakolwiek domyślna precyzja lub skala nie jest odpowiednia, aplikacja powinna jawnie ustawić odpowiednie pole deskryptora przez wywołanie metody SQLSetDescField lub SQLSetDescRec.

5. Jeśli dane zostały przekonwertowane na typ danych o zmiennej długości, taki jak znak lub plik binarny, SQLGetData sprawdza, czy długość danych przekracza BufferLength. Jeśli długość danych znaków (w tym znak zakończenia wartości null) przekracza BufferLength, SQLGetData obcina dane, aby BufferLength mniejszą długość znaku zakończenia wartości null. Następnie powoduje zakończenie danych o wartości null. Jeśli długość danych binarnych przekracza długość buforu danych, SQLGetData obcina je do BufferLength bajtów.

   Jeśli podany bufor danych jest zbyt mały, aby przechowywać znak zakończenia wartości null, SQLGetData zwraca SQL_SUCCESS_WITH_INFO i SQLSTATE 01004.

   SQLGetData nigdy nie obcina danych przekonwertowanych na typy danych o stałej długości; Zawsze zakłada się, że długość *TargetValuePtr jest rozmiarem typu danych.

6. Umieszcza przekonwertowane (i prawdopodobnie obcięte) dane w *TargetValuePtr. Należy pamiętać, że SQLGetData nie może zwracać danych poza wierszem.

7. Umieszcza długość danych w *StrLen_or_IndPtr. Jeśli StrLen_or_IndPtr był wskaźnikiem o wartości null, sqlGetData nie zwraca długości.

   • W przypadku danych znaków lub danych binarnych jest to długość danych po konwersji i przed obcięciem z powodu BufferLength. Jeśli sterownik nie może określić długości danych po konwersji, tak jak czasami w przypadku długich danych, zwraca SQL_SUCCESS_WITH_INFO i ustawia długość na SQL_NO_TOTAL. (Ostatnie wywołanie SQLGetData musi zawsze zwracać długość danych, a nie zero lub SQL_NO_TOTAL). Jeśli dane zostały obcięte z powodu atrybutu instrukcji SQL_ATTR_MAX_LENGTH, wartość tego atrybutu — w przeciwieństwie do rzeczywistej długości — jest umieszczana w *StrLen_or_IndPtr. Jest to spowodowane tym, że ten atrybut jest przeznaczony do obcinania danych na serwerze przed konwersją, więc sterownik nie ma możliwości ustalenia, jaka jest rzeczywista długość. Gdy sqlGetData jest wywoływana wiele razy z rzędu dla tej samej kolumny, jest to długość danych dostępnych na początku bieżącego wywołania; oznacza to, że długość zmniejsza się wraz z każdym kolejnym wywołaniem.

   • W przypadku wszystkich innych typów danych jest to długość danych po konwersji; oznacza to, że jest to rozmiar typu, do którego przekonwertowano dane.

8. Jeśli dane są obcięte bez utraty znaczenia podczas konwersji (na przykład Liczba rzeczywista 1.234 jest obcięta po przekonwertowaniu na liczbę całkowitą 1) lub ponieważ BufferLength jest zbyt mała (na przykład ciąg "abcdef" jest umieszczany w buforze 4-bajtowym), SQLGetData zwraca wartość SQLSTATE 01004 (dane obcięte) i SQL_SUCCESS_WITH_INFO. Jeśli dane są obcięte bez utraty istotności ze względu na atrybut instrukcji SQL_ATTR_MAX_LENGTH, SQLGetData zwraca SQL_SUCCESS i nie zwraca wartości SQLSTATE 01004 (Data obcięte).

Zawartość powiązanego buforu danych (jeśli SQLGetData jest wywoływana w powiązanej kolumnie), a bufor długości/wskaźnika jest niezdefiniowany, jeśli SQLGetData nie zwraca SQL_SUCCESS lub SQL_SUCCESS_WITH_INFO.

Kolejne wywołania SQLGetData pobierają dane z ostatniej żądanej kolumny; wcześniejsze przesunięcia stają się nieprawidłowe. Na przykład po wykonaniu następującej sekwencji:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)  

drugie wywołanie metody SQLGetData(icol=n) pobiera dane z początku n kolumny. Każde przesunięcie danych z powodu wcześniejszych wywołań SQLGetData dla kolumny nie jest już prawidłowe.

Deskryptory i SQLGetData

sqlGetData nie współdziała bezpośrednio z żadnymi polami deskryptora.

Jeśli TargetType jest SQL_ARD_TYPE, używany jest typ danych w polu SQL_DESC_CONCISE_TYPE ARD. Jeśli TargetType jest SQL_ARD_TYPE lub SQL_C_DEFAULT, dane mają dokładność i skalę w SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION i SQL_DESC_SCALE polach ARD, w zależności od typu danych w polu SQL_DESC_CONCISE_TYPE.

Przykład kodu

W poniższym przykładzie aplikacja wykonuje instrukcję SELECT, aby zwrócić zestaw wyników identyfikatorów klientów, nazw i numerów telefonów posortowanych według nazwy, identyfikatora i numeru telefonu. Dla każdego wiersza danych wywołuje SQLFetch, aby umieścić kursor w następnym wierszu. Wywołuje SQLGetData w celu pobrania pobranych danych; dla danych i zwróconej liczby bajtów są określone w wywołaniu SQLGetData. Na koniec drukuje nazwisko, identyfikator i numer telefonu każdego pracownika.

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}  

Powiązane funkcje

Zobacz też

dokumentacja interfejsu API ODBC
plików nagłówków ODBC
pobieranie parametrów wyjściowych przy użyciu SQLGetData