Fonction SQLPutData

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLPutData permet à une application d’envoyer des données pour un paramètre ou une colonne au pilote au moment de l’exécution de l’instruction. Cette fonction peut être utilisée pour envoyer des valeurs de données de caractères ou binaires en parties à une colonne avec un type de données spécifique à une source de données (par exemple, les paramètres des types SQL_LONGVARBINARY ou SQL_LONGVARCHAR). SQLPutData prend en charge la liaison à un type de données C Unicode, même si le pilote sous-jacent ne prend pas en charge les données Unicode.

Syntaxe

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

Arguments

StatementHandle
[Entrée] Handle d’instruction.

DataPtr
[Entrée] Pointeur vers une mémoire tampon contenant les données réelles du paramètre ou de la colonne. Les données doivent se trouver dans le type de données C spécifié dans l’argument ValueType de SQLBindParameter (pour les données de paramètre) ou l’argument TargetType de SQLBindCol (pour les données de colonne).

StrLen_or_Ind
[Entrée] Longueur de *DataPtr. Spécifie la quantité de données envoyées dans un appel à SQLPutData. La quantité de données peut varier avec chaque appel pour un paramètre ou une colonne donné. StrLen_or_Ind est ignorée, sauf si elle répond à l’une des conditions suivantes :

• StrLen_or_Ind est SQL_NTS, SQL_NULL_DATA ou SQL_DEFAULT_PARAM.

• Le type de données C spécifié dans SQLBindParameter ou SQLBindCol est SQL_C_CHAR ou SQL_C_BINARY.

• Le type de données C est SQL_C_DEFAULT, et le type de données C par défaut pour le type de données SQL spécifié est SQL_C_CHAR ou SQL_C_BINARY.

Pour tous les autres types de données C, si StrLen_or_Ind n’est pas SQL_NULL_DATA ou SQL_DEFAULT_PARAM, le pilote suppose que la taille de la mémoire tampon *DataPtr est la taille du type de données C spécifié avec ValueType ou TargetType et envoie la valeur de données entière. Pour plus d’informations, consultez Conversion de données de C en types de données SQL dans l’annexe D : Types de données.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLPutData retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLPutData et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Si SQLPutData est appelé lors de l’envoi de données pour un paramètre dans une instruction SQL, il peut retourner n’importe quel SQLSTATE qui peut être retourné par la fonction appelée pour exécuter l’instruction (SQLExecute ou SQLExecDirect). Si elle est appelée lors de l’envoi de données pour une colonne mise à jour ou ajoutée avec SQLBulkOperations ou mise à jour avec SQLSetPos, elle peut retourner n’importe quel SQLSTATE qui peut être retourné par SQLBulkOperations ou SQLSetPos.

Commentaires

SQLPutData peut être appelé pour fournir des données au moment de l’exécution pour deux utilisations : les données de paramètre à utiliser dans un appel à SQLExecute ou SQLExecDirect, ou les données de colonne à utiliser lorsqu’une ligne est mise à jour ou ajoutée par un appel à SQLBulkOperations ou est mise à jour par un appel à SQLSetPos.

Lorsqu’une application appelle SQLParamData pour déterminer les données qu’elle doit envoyer, le pilote retourne un indicateur que l’application peut utiliser pour déterminer les données de paramètre à envoyer ou où trouver les données de colonne. Elle retourne également SQL_NEED_DATA, qui est un indicateur à l’application qu’elle doit appeler SQLPutData pour envoyer les données. Dans l’argument DataPtr de SQLPutData, l’application transmet un pointeur vers la mémoire tampon contenant les données réelles du paramètre ou de la colonne.

Lorsque le pilote retourne SQL_SUCCESS pour SQLPutData, l’application appelle à nouveau SQLParamData. SQLParamData retourne SQL_NEED_DATA si davantage de données doivent être envoyées, auquel cas l’application appelle à nouveau SQLPutData . Elle retourne SQL_SUCCESS si toutes les données en cours d’exécution ont été envoyées. L’application appelle ensuite à nouveau SQLParamData . Si le pilote retourne SQL_NEED_DATA et un autre indicateur dans *ValuePtrPtr, il nécessite des données pour un autre paramètre ou colonne et SQLPutData est appelé à nouveau. Si le pilote retourne SQL_SUCCESS, toutes les données à l’exécution ont été envoyées et l’instruction SQL peut être exécutée ou l’appel SQLBulkOperations ou SQLSetPos peut être traité.

Pour plus d’informations sur la façon dont les données des paramètres d’exécution au moment de l’exécution des données sont passées au moment de l’exécution de l’instruction, consultez « Passage de valeurs de paramètre » dans SQLBindParameter et envoi de données longues. Pour plus d’informations sur la façon dont les données de colonne d’exécution sont mises à jour ou ajoutées, consultez la section « Utilisation de SQLSetPos » dans SQLSetPos, « Exécution de mises à jour en bloc à l’aide de signets » dans SQLBulkOperations et SqlSetPos et SQLBulkOperations.

Exemple

L’exemple suivant suppose un nom de source de données appelé Test. La base de données associée doit avoir une table que vous pouvez créer, comme suit :

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

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC