SQLPutData

Conformance

Version Introduced:ODBC 1.0
Standards Compliance:ISO 92

Summary

SQLPutData allows an application to send data for a parameter or column to the driver at statement execution time. This function can be used to send character or binary data values in parts to a column with a character, binary, or data source – specific data type (for example, parameters of the SQL_LONGVARBINARY or SQL_LONGVARCHAR types). SQLPutData supports binding to a Unicode C data type, even if the underlying driver does not support Unicode data.

Syntax

SQLRETURN SQLPutData(
SQLHSTMTStatementHandle,
SQLPOINTERDataPtr,
SQLINTEGERStrLen_or_Ind);

Arguments

StatementHandle

[Input]
Statement handle.

DataPtr

[Input]
Pointer to a buffer containing the actual data for the parameter or column. The data must be in the C data type specified in the ValueType argument of SQLBindParameter (for parameter data) or the TargetType argument of SQLBindCol (for column data).

StrLen_or_Ind

[Input]
Length of *DataPtr. Specifies the amount of data sent in a call to SQLPutData. The amount of data can vary with each call for a given parameter or column. StrLen_or_Ind is ignored unless it is one of the following:

• SQL_NTS, SQL_NULL_DATA, or SQL_DEFAULT_PARAM
  
  
• The C data type specified in SQLBindParameter or SQLBindCol is SQL_C_CHAR or SQL_C_BINARY.
  
  
• The C data type is SQL_C_DEFAULT and the default C data type for the specified SQL data type is SQL_C_CHAR or SQL_C_BINARY.

For all other types of C data, if StrLen_or_Ind is not SQL_NULL_DATA or SQL_DEFAULT_PARAM, the driver assumes that the size of the *DataPtr buffer is the size of the C data type specified with ValueType or TargetType and sends the entire data value. For more information, see “Converting Data from C to SQL Data Types" in Appendix D, “Data Types.”

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLPutData returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. The following table lists the SQLSTATE values commonly returned by SQLPutData and explains each one in the context of this function; the notation “(DM)” precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

If SQLPutData is called while sending data for a parameter in an SQL statement, it can return any SQLSTATE that can be returned by the function called to execute the statement (SQLExecute or SQLExecDirect). If it is called while sending data for a column being updated or added with SQLBulkOperations, or updated with SQLSetPos, it can return any SQLSTATE that can be returned by SQLBulkOperations or SQLSetPos.

Comments

SQLPutData can be called to supply data-at-execution data for two uses: parameter data to be used in a call to SQLExecute or SQLExecDirect, or column data to be used when a row is updated or added by a call to SQLBulkOperations, or updated by a call to SQLSetPos.

When an application calls SQLParamData to determine which data it should send, the driver returns an indicator that the application can use to determine which parameter data to send, or where column data can be found. It also returns SQL_NEED_DATA, which is an indicator to the application that it should call SQLPutData to send the data. In the DataPtr argument to SQLPutData, the application passes a pointer to the buffer containing the actual data for the parameter or column.

When the driver returns SQL_SUCCESS for SQLPutData, the application calls SQLParamData again. SQLParamData returns SQL_NEED_DATA if more data needs to be sent, in which case the application calls SQLPutData again. It returns SQL_SUCCESS if all data-at-execution data has been sent. The application then calls SQLParamData again. If the driver returns SQL_NEED_DATA and another indicator in *ValuePtrPtr, it requires data for another parameter or column, and SQLPutData is called again. If the driver returns SQL_SUCCESS, then all data-at-execution data has been sent, and the SQL statement can be executed or the SQLBulkOperations or SQLSetPos call can be processed.

For more information on how data-at-execution parameter data is passed at statement execution time, see “Passing Parameter Values” in SQLBindParameter and “Sending Long Data” in Chapter 9, “Executing Statements.” For more information on how data-at-execution column data is updated or added, see the section “Using SQLSetPos” in SQLSetPos, “Performing Bulk Updates Using Bookmarks” in SQLBulkOperations, and “Long Data and SQLSetPos and SQLBulkOperations” in Chapter 12, “Updating Data.”

Note An application can use SQLPutData to send data in parts only when sending character C data to a column with a character, binary, or data source – specific data type or when sending binary C data to a column with a character, binary, or data source – specific data type. If SQLPutData is called more than once under any other conditions, it returns SQL_ERROR and SQLSTATE HY019 (Non-character and non-binary data sent in pieces).

Code Example

In the following example, an application prepares an SQL statement to insert data into the PICTURES table. The statement contains parameters for the PARTID and PICTURE columns. For each parameter, the application calls SQLBindParameter to specify the C and SQL data types of the parameter. It also specifies that the data for the second parameter will be passed at execution time, and passes the value 2 for later retrieval by SQLParamData. This value will identify the parameter that is being processed.

The application calls GetNextID to get the next available part ID number. It then calls SQLExecute to execute the statement. SQLExecute returns SQL_NEED_DATA when it needs data for the second parameter. The application calls SQLParamData to retrieve the value it stored with SQLBindParameter; it uses this value to determine which parameter to send data for. For each parameter, the application calls InitUserData to initialize the data routine. It repeatedly calls GetUserData and SQLPutData to get and send the parameter data. Finally, it calls SQLParamData to indicate it has sent all the data for the parameter, at which point it returns SQL_SUCCESS.

For the second parameter, InitUserData calls a routine to prompt the user for the name of a file containing a bitmap photo of the part and opens the file. GetUserData retrieves the next MAX_DATA_LEN bytes of photo data from the file. After it has retrieved all the photo data, it closes the photo file.

Note that some application routines are omitted for clarity.

#define  MAX_DATA_LEN 1024
SQLINTEGER cbPartID = 0, cbPhotoParam, cbData;
SQLUINTEGER  sPartID;
     szPhotoFile;
SQLPOINTER pToken, InitValue;
SQLCHAR  Data[MAX_DATA_LEN];
SQLRETURN  retcode;
SQLHSTMT   hstmt;

retcode = SQLPrepare(hstmt,
    "INSERT INTO PICTURES (PARTID, PICTURE) VALUES 
         (?, ?)", SQL_NTS);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {

   /* Bind the parameters. For parameter 2, pass */
   /* the parameter number in ParameterValuePtr instead of a buffer */    
   /* address. */

   SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_ULONG, 
                  SQL_INTEGER, 0, 0, &sPartID, 0, &cbPartID);
   SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT,
          SQL_C_BINARY, SQL_LONGVARBINARY,
          0, 0, (SQLPOINTER) 2, 0, &cbPhotoParam);

   /* Set values so data for parameter 2 will be */
   /* passed at execution. Note that the length parameter in */
   /* the macro SQL_LEN_DATA_AT_EXEC is 0. This assumes that */
   /* the driver returns "N" for the SQL_NEED_LONG_DATA_LEN */
   /* information type in SQLGetInfo.         */

   cbPhotoParam = SQL_LEN_DATA_AT_EXEC(0);

   sPartID = GetNextID();  /* Get next available employee ID */
                   /* number. */

   retcode = SQLExecute(hstmt);

   /* For data-at-execution parameters, call SQLParamData to */
   /* get the parameter number set by SQLBindParameter. */
   /* Call InitUserData. Call GetUserData and SQLPutData */
   /* repeatedly to get and put all data for the parameter. */
   /* Call SQLParamData to finish processing this parameter */

   while (retcode == SQL_NEED_DATA) {
      retcode = SQLParamData(hstmt, &pToken);
      if (retcode == SQL_NEED_DATA) {
         InitUserData((SQLSMALLINT)pToken, InitValue);
         while (GetUserData(InitValue, (SQLSMALLINT)pToken, Data, 
                            &cbData))
            SQLPutData(hstmt, Data, cbData);
      }
   }
}

VOID InitUserData(sParam, InitValue)
SQLPOINTER InitValue;
{
 SQLCHAR  szPhotoFile[MAX_FILE_NAME_LEN];

 /* Prompt user for bitmap file containing employee */
 /* photo. OpenPhotoFile opens the file and returns the */
 /* file handle. */

 PromptPhotoFileName(szPhotoFile);
 OpenPhotoFile(szPhotoFile, (FILE *)InitValue);
 break;
 }

BOOL GetUserData(InitValue, sParam, Data, cbData)
SQLPOINTER InitValue;
SQLCHAR  *Data;
SQLINTEGER *cbData;
BOOL   Done;

{

 /* GetNextPhotoData returns the next piece of photo */
 /* data and the number of bytes of data returned    */
 /* (up to MAX_DATA_LEN). */

 Done = GetNextPhotoData((FILE *)InitValue, Data,
         MAX_DATA_LEN, &cbData);
 if (Done) {
    ClosePhotoFile((FILE *)InitValue);
    return (TRUE);
 }
 return (FALSE);
 }

Related Functions