SQLPutData, функция

Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLPutData позволяет приложению отправлять данные для параметра или столбца драйверу во время выполнения инструкции. Эту функцию можно использовать для отправки символьных или двоичных значений данных в столбцы с типом данных, двоичным или двоичным источником данных (например, параметрами SQL_LONGVARBINARY или типами SQL_LONGVARCHAR). SQLPutData поддерживает привязку к типу данных ЮникодА C, даже если базовый драйвер не поддерживает данные Юникода.

Синтаксис

  
SQLRETURN SQLPutData(  
      SQLHSTMT     StatementHandle,  
      SQLPOINTER   DataPtr,  
      SQLLEN       StrLen_or_Ind);  

Аргументы

ОператорHandle
[Входные данные] Дескриптор инструкции.

DataPtr
[Входные данные] Указатель на буфер, содержащий фактические данные для параметра или столбца. Данные должны находиться в типе данных C, указанном в аргументе ValueType SQLBindParameter (для данных параметров) или аргументе TargetType SQLBindCol (для данных столбцов).

StrLen_or_Ind
[Входные данные] Длина *DataPtr. Указывает объем данных, отправленных в вызове SQLPutData. Объем данных может отличаться при каждом вызове заданного параметра или столбца. StrLen_or_Ind игнорируется, если он не соответствует одному из следующих условий:

• StrLen_or_Ind SQL_NTS, SQL_NULL_DATA или SQL_DEFAULT_PARAM.

• Тип данных C, указанный в SQLBindParameter или SQLBindCol , SQL_C_CHAR или SQL_C_BINARY.

• Тип данных C — SQL_C_DEFAULT, а тип данных C по умолчанию для указанного типа данных SQL — SQL_C_CHAR или SQL_C_BINARY.

Для всех других типов данных C, если StrLen_or_Ind не SQL_NULL_DATA или SQL_DEFAULT_PARAM, драйвер предполагает, что размер буфера *DataPtr является размером типа данных C, указанного с помощью ValueType или TargetType , и отправляет все значение данных. Дополнительные сведения см. в разделе "Преобразование данных из C в типы данных SQL" в приложении D: Типы данных.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLPutData возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLPutData и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

Если SQLPutData вызывается при отправке данных для параметра в инструкции SQL, он может возвращать любой SQLSTATE, который может быть возвращен функцией, вызываемой для выполнения инструкции (SQLExecute или SQLExecDirect). Если он вызывается при отправке данных для столбца, обновляемого или добавляемого с помощью SQLBulkOperations или обновляемого с помощью SQLSetPos, он может возвращать любой SQLSTATE, который может быть возвращен SQLBulkOperations или SQLSetPos.

Комментарии

SQLPutData можно вызывать для предоставления данных во время выполнения данных для двух используемых: данные параметров, которые будут использоваться в вызове SQLExecute или SQLExecDirect, или данные столбцов, которые будут использоваться при обновлении строки или добавлении вызова SQLBulkOperations или обновляется вызовом SQLSetPos.

Когда приложение вызывает SQLParamData , чтобы определить, какие данные следует отправлять, драйвер возвращает индикатор, который приложение может использовать для определения данных параметров для отправки или расположения данных столбцов. Он также возвращает SQL_NEED_DATA, который является индикатором для приложения, которое должно вызывать SQLPutData для отправки данных. В аргументе DataPtr в SQLPutData приложение передает указатель на буфер, содержащий фактические данные для параметра или столбца.

Когда драйвер возвращает SQL_SUCCESS для SQLPutData, приложение снова вызывает SQLParamData . SQLParamData возвращает SQL_NEED_DATA, если требуется отправить больше данных, в этом случае приложение снова вызывает SQLPutData . Он возвращает SQL_SUCCESS, если отправлены все данные во время выполнения. Затем приложение снова вызывает SQLParamData . Если драйвер возвращает SQL_NEED_DATA и другой индикатор в *ValuePtrPtrPtr, он требует данных для другого параметра или столбца, а SQLPutData вызывается снова. Если драйвер возвращает SQL_SUCCESS, то все данные во время выполнения отправлены, а инструкция SQL может быть выполнена, или вызов SQLBulkOperations или SQLSetPos можно обработать.

Дополнительные сведения о передаче данных параметра во время выполнения инструкции см. в разделе "Передача значений параметров" в SQLBindParameter и отправке длинных данных. Дополнительные сведения о том, как данные столбца при выполнении обновляются или добавляются, см. в разделе "Использование SQLSetPos" в SQLSetPos, "Выполнение массовых обновлений с помощью закладок" в SQLBulkOperations, а также long Data и SQLSetPos и SQLBulkOperations.

Пример

В следующем примере предполагается имя источника данных с именем Test. Связанная база данных должна иметь таблицу, которую можно создать, как показано ниже.

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);  
}  

Связанные функции

См. также

Справочник по API ODBC
Файлы заголовков ODBC