Wysyłanie długich danych

Zestawy DBMS definiują długie dane jako dowolne znaki lub dane binarne o określonym rozmiarze, takie jak 254 znaki. Może nie być możliwe przechowywanie całego elementu długich danych w pamięci, na przykład gdy element reprezentuje długi dokument tekstowy lub mapę bitową. Ponieważ takie dane nie mogą być przechowywane w jednym buforze, źródło danych wysyła je do sterownika w częściach za pomocą funkcji SQLPutData po wykonaniu instrukcji. Parametry, dla których dane są wysyłane w czasie wykonywania, są nazywane parametrami data-at-execution.

Uwaga / Notatka

Aplikacja może faktycznie wysyłać dowolne typy danych w czasie wykonywania za pomocą funkcji SQLPutData, chociaż tylko dane znakowe i binarne mogą być wysyłane w częściach. Jeśli jednak dane są wystarczająco małe, aby zmieściły się w jednym buforze, zazwyczaj nie ma powodu do użycia funkcji SQLPutData. Znacznie łatwiej jest powiązać bufor i pozwolić sterownikowi pobrać dane z buforu.

Aby wysyłać dane w czasie wykonywania, aplikacja wykonuje następujące akcje:

1. Przekazuje wartość 32-bitową, która identyfikuje parametr w argumencie ParameterValuePtr w parametrze SQLBindParameter zamiast przekazywać adres buforu. Ta wartość nie jest analizowana przez sterownik. Zostanie ona później zwrócona do aplikacji, więc powinna ona oznaczać coś w aplikacji. Na przykład może to być liczba parametrów lub uchwyt pliku zawierającego dane.

2. Przekazuje adres buforu długości/wskaźnika w StrLen_or_IndPtr argumentu SQLBindParameter.

3. Przechowuje SQL_DATA_AT_EXEC lub wynik makra SQL_LEN_DATA_AT_EXEC(długość) w buforze długości/wskaźnika. Obie te wartości wskazują sterownikowi, że dane parametru zostaną wysłane za pomocą funkcji SQLPutData. SQL_LEN_DATA_AT_EXEC (długość) jest używana podczas wysyłania długich danych do źródła danych, które musi wiedzieć, ile bajtów długich danych zostanie wysłanych, aby można było wstępnie przydzielić miejsce. Aby określić, czy źródło danych wymaga tej wartości, aplikacja wywołuje element SQLGetInfo z opcją SQL_NEED_LONG_DATA_LEN. Wszystkie sterowniki muszą obsługiwać to makro; jeśli źródło danych nie wymaga długości bajtu, sterownik może go zignorować.

4. Wywołuje metodę SQLExecute lub SQLExecDirect. Sterownik wykrywa, że bufor długości/wskaźnika zawiera wartość SQL_DATA_AT_EXEC lub wynik makra SQL_LEN_DATA_AT_EXEC(długość) i zwraca SQL_NEED_DATA jako wartość zwracaną funkcji.

5. Wywołuje metodę SQLParamData w odpowiedzi na wartość zwracaną SQL_NEED_DATA. Jeśli należy wysłać długie dane, funkcja SQLParamData zwraca SQL_NEED_DATA. W buforze wskazywanym przez argument ValuePtrPtr sterownik zwraca wartość identyfikującą parametr data-at-execution. Jeśli istnieje więcej niż jeden parametr data-at-execution, aplikacja musi użyć tej wartości, aby określić, dla którego parametru wysyłać dane; sterownik nie musi żądać danych dla parametrów data-at-execution w jakiejkolwiek konkretnej kolejności.

6. Wywołuje metodę SQLPutData , aby wysłać dane parametrów do sterownika. Jeśli dane parametrów nie mieszczą się w pojedynczym buforze, co często ma miejsce w przypadku długich danych, aplikacja wielokrotnie wywołuje funkcję SQLPutData w celu wysłania danych w częściach; do sterownika i źródła danych należy złożenie danych w całość. Jeśli aplikacja przekazuje dane ciągu zakończonego znakiem null, sterownik lub źródło danych musi usunąć znak null w ramach procesu ponownego montażu.

7. Ponownie wywołuje metodę SQLParamData , aby wskazać, że wysłała wszystkie dane dla parametru. Jeśli istnieją jakiekolwiek parametry wykonywania danych, dla których dane nie zostały wysłane, sterownik zwraca SQL_NEED_DATA i wartość identyfikującą następny parametr; aplikacja powraca do kroku 6. Jeśli dane zostały wysłane dla wszystkich parametrów danych przy wykonywaniu, instrukcja zostaje wykonana. Funkcja SQLParamData zwraca SQL_SUCCESS lub SQL_SUCCESS_WITH_INFO i może zwrócić dowolną zwracaną wartość lub diagnostykę, którą może zwrócić program SQLExecute lub SQLExecDirect .

Po tym, jak funkcja SQLExecute lub SQLExecDirect zwróci SQL_NEED_DATA i zanim dane zostaną całkowicie wysłane dla ostatniego parametru data-at-execution, instrukcja znajduje się w stanie Potrzebne dane. Gdy instrukcja jest w stanie Need Data, aplikacja może wywoływać tylko SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField lub SQLGetDiagRec; wszystkie inne funkcje zwracają SQLSTATE HY010 (błąd sekwencji funkcji). Wywołanie metody SQLCancel anuluje wykonywanie instrukcji i zwraca ją do poprzedniego stanu. Aby uzyskać więcej informacji, zobacz Dodatek B: Tabele przejścia stanu ODBC.

Przykład wysyłania danych w czasie wykonywania można znaleźć w opisie funkcji SQLPutData .