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
SQLPutData pozwala aplikacji wysyłać dane dla parametru lub kolumny do sterownika w momencie wykonywania instrukcji. Funkcja ta może być używana do przesyłania wartości danych znakowych lub binarnych w częściach do kolumny zawierającej typ danych ze znakiem, binarnym lub specyficznym dla źródła danych (na przykład parametry typów SQL_LONGVARBINARY lub SQL_LONGVARCHAR).
SQLPutData obsługuje powiązania z typem danych Unicode C, nawet jeśli podstawowy sterownik nie obsługuje danych Unicode.
Syntax
SQLRETURN SQLPutData(
SQLHSTMT StatementHandle,
SQLPOINTER DataPtr,
SQLLEN StrLen_or_Ind);
Arguments
StatementHandle
[Dane wejściowe] Uchwyt instrukcji.
DataPtr
[Input] Wskaźnik do bufora zawierającego rzeczywiste dane dla parametru lub kolumny. Dane muszą znajdować się w C typu danych określonego w argumentze ValueTypew SQLBindParameter (dla danych parametrów) lub w argumentze TargetTypew SQLBindCol (dla danych kolumnowych).
StrLen_or_Ind
[Input] Długość *DataPtr. Określa ilość danych przesyłanych w połączeniu do SQLPutData. Ilość danych może się różnić przy każdym wywołaniu danego parametru lub kolumny.
StrLen_or_Ind jest ignorowany, chyba że spełnia jeden z następujących warunków:
StrLen_or_Ind to SQL_NTS, SQL_NULL_DATA lub SQL_DEFAULT_PARAM.
Typ danych C określony w SQLBindParameter lub SQLBindCol to SQL_C_CHAR lub SQL_C_BINARY.
Typ danych C to SQL_C_DEFAULT, a domyślny typ danych C dla określonego typu SQL to SQL_C_CHAR lub SQL_C_BINARY.
Dla wszystkich innych typów danych C, jeśli StrLen_or_Ind nie jest SQL_NULL_DATA lub SQL_DEFAULT_PARAM, sterownik zakłada, że rozmiar bufora *DataPtr jest taki sam jak rozmiar typu danych C określonego za pomocą ValueType lub TargetType i wysyła całą wartość danych. Więcej informacji można znaleźć w artykule Konwersja danych z C do SQL w Załączniku D: Typy danych.
Zwroty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.
Diagnostyka
Gdy SQLPutData zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz Handle z StatementHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLPutData 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 | Dane ciągowe lub binarne zwracane dla parametru wyjściowego powodowały obcięcie danych binarnych znaków niepustych lub nie-NULL. Jeśli była to wartość ciągu, została ona obcięta prawym przyciskiem. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 07006 | Naruszenie atrybutu typu danych z ograniczeniami | Nie można przekonwertować wartości danych zidentyfikowanej przez argument ValueType w parametrze SQLBindParameter dla powiązanego parametru na typ danych zidentyfikowany przez argument ParameterType w parametrze SQLBindParameter. |
| 07S01 | Nieprawidłowe użycie parametru domyślnego | Wartość parametru ustawiona za pomocą parametru SQLBindParameter została SQL_DEFAULT_PARAM, a odpowiadający mu parametr nie miał wartości domyślnej. |
| 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. |
| 22001 | Dane ciągowe, obcinanie z prawej | Przypisanie znaku lub wartości binarnej do kolumny skutkowało obcięciem znaków lub bajtów niepustych (znaków) lub niezerowych (binarnych). Typ informacji SQL_NEED_LONG_DATA_LEN w SQLGetInfo to "Y", a dla długiego parametru (typ danych to SQL_LONGVARCHAR, SQL_LONGVARBINARY lub długi typ danych specyficzny dla źródła danych) był wysyłany więcej danych niż w SQLBindParameter w argumentze StrLen_or_IndPtr. Typ informacji SQL_NEED_LONG_DATA_LEN w SQLGetInfo to "Y", a dla długiej kolumny (typ danych to SQL_LONGVARCHAR, SQL_LONGVARBINARY lub długi typ danych specyficzny dla źródła danych) wysyłano więcej danych niż było określone w buforze długości odpowiadającej kolumnie w wierszu danych, które były dodawane lub aktualizowane za pomocą SQLBulkOperations albo aktualizowane za pomocą SQLSetPos. |
| 22003 | Wartość liczbowa poza zakresem | Dane wysyłane dla ograniczonego parametru numerycznego lub kolumny powodowały, że cała (a nie ułamkowa) część liczby została obcięta po przypisaniu do powiązanej kolumny tabeli. Zwracanie wartości liczbowej (jako liczbowej lub ciągu) dla co najmniej jednego parametru wejściowego/wyjściowego lub wyjściowego spowodowałoby, że cała (w przeciwieństwie do ułamkowej) część liczby została obcięta. |
| 22007 | Nieprawidłowy format daty/godziny | Dane wysyłane dla parametru lub kolumny powiązanej ze strukturą daty, godziny lub znacznika czasu były odpowiednio nieprawidłową datą, godziną lub znacznikiem czasu. Parametr wejściowy/wyjściowy lub wyjściowy był powiązany ze strukturą daty, godziny lub znacznika czasu C, a wartość zwróconego parametru była odpowiednio nieprawidłową datą, godziną lub znacznikiem czasu. (Funkcja zwraca SQL_SUCCESS_WITH_INFO). |
| 22008 | Przepełnienie pola daty/godziny | Wyrażenie daty/godziny obliczone dla parametru wejściowego/wyjściowego spowodowało nieprawidłową strukturę C daty, godziny lub znacznika czasu. |
| 22012 | Dzielenie według zera | Wyrażenie arytmetyczne obliczane dla parametru wejściowego/wyjściowego spowodowało podział o zero. |
| 22015 | Przepełnienie pola interwału | Dane przesyłane dla dokładnej kolumny numerycznej lub przedziałowej do typu SQL typu interwałowego powodowały utratę istotnych cyfr. Dane były wysyłane dla kolumny lub parametru przedziałowego z więcej niż jednym polem, konwertowane na typ danych numerycznych i nie miały reprezentacji w typie danych numerycznych. Dane wysyłane jako dane kolumnowe lub parametryczne były przypisywane do typu SQL interwałowego, a wartość typu C nie była reprezentowana w typie SQL interwału. Dane przesyłane dla dokładnej kolumny lub parametru przedziału C do typu przedziału C powodowały utratę istotnych cyfr. Dane wysyłane jako kolumny lub dane parametrów były przypisywane do struktury przedziału C, a w strukturze przedziałowej nie było reprezentacji tych danych. |
| 22018 | Nieprawidłowa wartość znaku dla specyfikacji rzutu | Typ C był dokładnym lub przybliżonym numerem, datą lub typem danych interwałowych; typ SQL kolumny był typem danych znaków; a wartość w kolumnie lub parametrze nie była prawidłowym literalem typu C z ograniczeniem. Typ SQL był dokładnym lub przybliżonym numerem, datą lub typem danych interwałowych; typ C był SQL_C_CHAR; a wartość w kolumnie lub parametrze nie była prawidłowym literalem powiązanego typu SQL. |
| 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 | Błąd 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. |
| HY009 | Nieprawidłowe użycie wskaźnika o wartości null | (DM) Argument DataPtr był wskaźnikiem zerowym, a argument StrLen_or_Ind nie był 0, SQL_DEFAULT_PARAM ani SQL_NULL_DATA. |
| HY010 | Błąd sekwencji funkcji | (DM) Poprzednie wywołanie funkcji nie było wywołaniem do SQLPutData ani SQLParamData. (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 funkcję SQLPutData. (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. |
| 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. |
| HY019 | Dane nie-znakowe i niebinarne przesyłane w kawałkach | SQLPutData był wywoływany więcej niż raz dla parametru lub kolumny i nie był używany do przesyłania danych znaku C do kolumny z typem danych specyficznym dla znaku, binarnego lub specyficznego dla źródła danych, ani do wysyłania binarnych danych C do kolumny zawierającej typ danych znakowy, binarny lub specyficzny dla źródła danych. |
| HY020 | Próba połączenia wartości zerowej | SQLPutData była wywoływana więcej niż raz od czasu zwrotu SQL_NEED_DATA, a w jednym z tych wywołań argument StrLen_or_Ind zawierał SQL_NULL_DATA lub SQL_DEFAULT_PARAM. |
| HY090 | Nieprawidłowa długość ciągu lub buforu | Argument DataPtr nie był wskaźnikiem zerowym, a argument StrLen_or_Ind był mniejszy niż 0, ale nie równy SQL_NTS ani SQL_NULL_DATA. |
| 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ę. |
Jeśli SQLPutData zostanie wywołany podczas wysyłania danych dla parametru w instrukcji SQL, może zwrócić dowolny stan SQL, który może zostać zwrócony przez funkcję wywołaną do wykonania polecenia (SQLExecute lub SQLExecDirect). Jeśli zostanie wywołany podczas wysyłania danych dla kolumny aktualizowanej lub dodawanej za pomocą SQLBulkOperations albo aktualizowanej przez SQLSetPos, może zwrócić dowolny stan SQL, który może zostać zwrócony przez SQLBulkOperations lub SQLSetPos.
Comments
SQLPutData może być wywołany do dostarczania danych podczas wykonania do dwóch zastosowań: danych parametrów do wywołania do SQLExecute lub SQLExecDirect, lub danych kolumnowych do użycia, gdy wiersz jest aktualizowany lub dodawany przez wywołanie do SQLBulkOperations lub aktualizowany przez wywołanie do SQLSetPos.
Gdy aplikacja wywołuje SQLParamData , aby określić, które dane powinna wysłać, sterownik zwraca wskaźnik, który aplikacja może wykorzystać, aby określić, które dane parametrów wysłać lub gdzie można znaleźć dane kolumnowe. Zwraca także SQL_NEED_DATA, co jest sygnałem dla aplikacji, że powinna wywołać SQLPutData , aby przesłać dane. W argumentze DataPtr do SQLPutData aplikacja przekazuje wskaźnik do bufora zawierający rzeczywiste dane dla parametru lub kolumny.
Gdy sterownik zwraca SQL_SUCCESS dla SQLPutData, aplikacja ponownie wywołuje SQLParamData . SQLParamData zwraca SQL_NEED_DATA, jeśli trzeba przesłać więcej danych, w takim przypadku aplikacja ponownie wywołuje SQLPutData . Zwraca SQL_SUCCESS, jeśli wszystkie dane z wykonania zostały wysłane. Następnie aplikacja ponownie wywołuje SQLParamData . Jeśli sterownik zwraca SQL_NEED_DATA i inny wskaźnik w *ValuePtrPtr, wymaga danych dla innego parametru lub kolumny i SQLPutData jest wywoływany ponownie. Jeśli sterownik zwraca SQL_SUCCESS, wszystkie dane z wykonania zostały wysłane i można wykonać polecenie SQL lub przetworzyć wywołanie SQLBulkOperations lub SQLSetPos .
Aby uzyskać więcej informacji o tym, jak dane parametrów danych danych podczas wykonania są przekazywane podczas wykonywania instrukcji, zobacz "Passing Parameter Values" w SQLBindParameter oraz Sending Long Data. Aby uzyskać więcej informacji o tym, jak dane kolumnowe danych danych podczas wykonania są aktualizowane lub dodawane, zobacz sekcję "Using SQLSetPos" w SQLSetPos, "Performing Bulk Updates Using Bookmarks" w SQLBulkOperations oraz Long Data i SQLSetPos i SQLBulkOperations.
Note
Aplikacja może używać SQLPutData do przesyłania danych w częściach tylko podczas wysyłania danych znaku C do kolumny zawierającej typ danych specyficznego dla znaku, binarnego lub źródła danych, albo gdy wysyła dane binarne C do kolumny zawierającej typ danych ze znakiem, binarnym lub specyficznym dla źródła danych. Jeśli SQLPutData jest wywoływany więcej niż raz w innych warunkach, zwraca SQL_ERROR oraz SQLSTATE HY019 (dane nieznakowe i niebinarne wysyłane w fragmentach).
Example
Poniższy przykład zakłada nazwę źródła danych o nazwie Test. Powiązana baza danych powinna zawierać tabelę, którą możesz utworzyć, w następujący sposób:
CREATE TABLE emp4 (NAME char(30), AGE int, BIRTHDAY datetime, Memo1 text)
// SQLPutData.cpp
// compile with: odbc32.lib user32.lib
#include <stdio.h>
#include <windows.h>
#include <sqlext.h>
#include <odbcss.h>
#define TEXTSIZE 12000
#define MAXBUFLEN 256
SQLHENV henv = SQL_NULL_HENV;
SQLHDBC hdbc1 = SQL_NULL_HDBC;
SQLHSTMT hstmt1 = SQL_NULL_HSTMT;
void Cleanup() {
if (hstmt1 != SQL_NULL_HSTMT)
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
if (hdbc1 != SQL_NULL_HDBC) {
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
}
if (henv != SQL_NULL_HENV)
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
int main() {
RETCODE retcode;
// SQLBindParameter variables.
SQLLEN cbTextSize, lbytes;
// SQLParamData variable.
PTR pParmID;
// SQLPutData variables.
UCHAR Data[] =
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyz";
SDWORD cbBatch = (SDWORD)sizeof(Data) - 1;
// Allocate the ODBC environment and save handle.
retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(Env) Failed\n\n");
Cleanup();
return(9);
}
// Notify ODBC that this is an ODBC 3.0 app.
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLSetEnvAttr(ODBC version) Failed\n\n");
Cleanup();
return(9);
}
// Allocate ODBC connection handle and connect.
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(hdbc1) Failed\n\n");
Cleanup();
return(9);
}
// Sample uses Integrated Security, create SQL Server DSN using Windows NT authentication.
retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"",SQL_NTS, (UCHAR*)"", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLConnect() Failed\n\n");
Cleanup();
return(9);
}
// Allocate statement handle.
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc1, &hstmt1);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLAllocHandle(hstmt1) Failed\n\n");
Cleanup();
return(9);
}
// Set parameters based on total data to send.
lbytes = (SDWORD)TEXTSIZE;
cbTextSize = SQL_LEN_DATA_AT_EXEC(lbytes);
// Bind the parameter marker.
retcode = SQLBindParameter (hstmt1, // hstmt
1, // ipar
SQL_PARAM_INPUT, // fParamType
SQL_C_CHAR, // fCType
SQL_LONGVARCHAR, // FSqlType
lbytes, // cbColDef
0, // ibScale
(VOID *)1, // rgbValue
0, // cbValueMax
&cbTextSize); // pcbValue
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLBindParameter Failed\n\n");
Cleanup();
return(9);
}
// Execute the command.
retcode =
SQLExecDirect(hstmt1, (UCHAR*)"INSERT INTO emp4 VALUES('Paul Borm', 46,'1950-11-12 00:00:00', ?)", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_NEED_DATA) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLExecDirect Failed\n\n");
Cleanup();
return(9);
}
// Check to see if NEED_DATA; if yes, use SQLPutData.
retcode = SQLParamData(hstmt1, &pParmID);
if (retcode == SQL_NEED_DATA) {
while (lbytes > cbBatch) {
SQLPutData(hstmt1, Data, cbBatch);
lbytes -= cbBatch;
}
// Put final batch.
retcode = SQLPutData(hstmt1, Data, lbytes);
}
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Make final SQLParamData call.
retcode = SQLParamData(hstmt1, &pParmID);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("Final SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Clean up.
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
Powiązane funkcje
| Aby uzyskać informacje o | Zobacz |
|---|---|
| Powiązanie bufora z parametrem | Funkcja SQLBindParameter |
| Anulowanie przetwarzania instrukcji | SQLCancel, funkcja |
| Wykonywanie instrukcji SQL | Funkcja SQLExecDirect |
| Wykonywanie przygotowanej instrukcji SQL | SQLExecute, funkcja |
| Zwracanie następnego parametru w celu wysłania danych dla | SQLParamData, funkcja |