Długie Dane i SQLSetPos i SQLBulkOperations

Podobnie jak w przypadku parametrów w instrukcjach SQL, długie dane można wysyłać podczas aktualizowania wierszy za pomocą sqlBulkOperations lub SQLSetPos lub podczas wstawiania wierszy za pomocą sqlBulkOperations. Dane są wysyłane w częściach z wieloma wywołaniami do sqlPutData. Kolumny, dla których dane są wysyłane w czasie wykonywania, są nazywane kolumnami data-at-execution.

Uwaga / Notatka

Aplikacja może wysyłać dane dowolnego typu 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.

Ponieważ długie kolumny danych zwykle nie są powiązane, aplikacja musi powiązać kolumnę przed wywołaniem sqlBulkOperations lub SQLSetPos i usunąć powiązanie ich po wywołaniu sqlBulkOperations lub SQLSetPos. Kolumna musi być powiązana, ponieważ operacje SQLBulkOperations lub SQLSetPos działają tylko na powiązanych kolumnach i muszą być niezwiązane, aby można było użyć funkcji SQLGetData do pobrania danych z kolumny.

Aplikacja wysyła dane podczas wykonywania, wykonując następujące kroki:

1. Umieszcza wartość 32-bitową w buforze zestawu wierszy zamiast wartości danych. Ta wartość zostanie później zwrócona do aplikacji, więc aplikacja powinna ustawić ją na zrozumiałą wartość, taką jak liczba kolumny lub uchwyt pliku zawierającego dane.

2. Ustawia wartość w buforze długości/wskaźnika na wynik makra SQL_LEN_DATA_AT_EXEC(length). Ta wartość wskazuje sterownikowi, że dane parametru zostaną wysłane za pomocą funkcji SQLPutData. Wartość długości 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ć.

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

4. 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 unikatową wartość, którą aplikacja umieściła w buforze wierszy. Jeśli istnieje więcej niż jedna kolumna przetwarzana podczas wykonywania, aplikacja używa tej wartości do określenia, z której kolumny wysyłać dane; sterownik nie musi żądać danych dla kolumn przetwarzanych podczas wykonywania w jakiejkolwiek określonej kolejności.

5. Wywołuje metodę SQLPutData , aby wysłać dane kolumny do sterownika. Jeśli dane kolumny nie mieszczą się w pojedynczym buforze, tak jak często 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 ponownie zmontować dane. 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.

6. Ponownie wywołuje metodę SQLParamData , aby wskazać, że wysłała wszystkie dane dla kolumny. Jeśli istnieją jakiekolwiek kolumny wykonywania danych, dla których dane nie zostały wysłane, sterownik zwraca SQL_NEED_DATA i unikatową wartość dla następnej kolumny wykonywania danych; aplikacja powraca do kroku 5. Jeśli dane zostały wysłane dla wszystkich kolumn danych przetwarzanych podczas wykonywania, dane dla wiersza są wysyłane do źródła danych. Następnie funkcja SQLParamData zwraca SQL_SUCCESS lub SQL_SUCCESS_WITH_INFO i może zwrócić dowolny element SQLSTATE, który może zwrócić sqlBulkOperations lub SQLSetPos .

Po tym, jak funkcja SQLBulkOperations lub SQLSetPos zwróci SQL_NEED_DATA i zanim dane zostaną całkowicie przesłane dla ostatniej kolumny realizowanej podczas wykonania, instrukcja jest w stanie Oczekiwania na dane. W tym stanie 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.