ODBC API

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).

Syntax

RETCODE SQLPutData(hstmt, rgbValue, cbValue)

The SQLPutData function accepts the following arguments.

Type	Argument	Use	Description
HSTMT	hstmt	Input	Statement handle
PTR	rgbValue	Input	Pointer to storage for the actual data for the parameter or column. The data must use the C data type specified in the fCType argument of SQLBindParameter (for parameter data) or SQLBindCol (for column data).
SDWORD	cbValue	Input	Length of rgbValue. 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, cbValue is ignored unless it is 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; or 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 cbValue is not SQL_NULL_DATA or SQL_DEFAULT_PARAM, the driver assumes that the size of rgbValue is the size of the C data type specified with fCType and sends the entire data value. For more information, see "Converting Data from C to SQL 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 may be obtained by calling SQLError. 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.

SQLSTATE	Error	Description
01000	General warning	Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01004	Data truncated	The buffer szSqlStr was not large enough to return the entire SQL string, so the SQL string was truncated. The argument pcbSqlStr contains the length of the untruncated SQL string. (Function returns SQL_SUCCESS_WITH_INFO.)
08S01	Communication link failure	The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.
22001	String data right truncation	The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo was "Y" and more data was sent for a long parameter (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or a long, data-source-specific data type) than was specified with the pcbValue argument in SQLBindParameter. The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo was "Y" and more data was sent for a long column (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY or a long, data-source-specific data type) than was specified in the length buffer corresponding to a column in a row of data that was added or updated with SQLSetPos.
22003	Numeric value out of range	SQLPutData was called more than once for a parameter or column and it was not being used to send character C data to a column with a character, binary or data-source-specific data type or to send binary C data to a column with a character, binary or data-source-specific data type. The data send for a numeric parameter or column caused the whole (as opposed to fractional) part of the number to be truncated when assigned to the associated table column.
22005	Error in assignment	The data sent for a parameter or column was incompatible with the data type of the associated table column.
22008	Datetime field overflow	The prepared statement associated with the hstmt contained a date, time or timestamp parameter or literal and the value was, respectively, and invalid date, time or timestamp.
S1000	General error	An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause.
S1001	Memory allocation failure	(DM) The Driver Manager was unable to allocate memory for the connection handle. The driver was unable to allocate memory for the connection handle.
S1008	Operation Canceled	Asynchronous processing was enabled for the hstmt. The funtion was called and before it completed execution, SQLCancel was called on the hstmt from a different thread in a multithreaded application.
S1009	Invalid argument value	(DM) The argument rgbValue was a null pointer and the argument cbValue was not 0, SQL_DEFAULT_PARAM or SQL_NULL_DATA
S1010	Function sequence error	(DM) An application asynchronously execution function (not this one) was called for the hstmt and was still executing when this function was called. (DM) The previous funtion call was not a call to SQLPutData or SQLParamData. The previous funtion call was a call to SQLExecute, SQLExecute or SQLSetPos where the return code was SQL_NEED_DATA.
S1090	Invalid string or buffer length	A parameter value, set with SQLBindParameter, was a null pointer and the paramete rlength value was not 0, SQL_NULL_DATA, SQL_DATA_AT_EXEC, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET. A parameter value, set with SQLBindParameter, was not a null pointer and the parameter length value was less than 0, but was not SQL_NTS, SQL_NULL_DATA, or SQL_DATA_AT_EXEC, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET.
S1T00	Timeout expired	The timeout period expired before the data source returned the result set. The timeout period is set through SQLSetStmtOption, SQL_QUERY_TIMEOUT.

Comments

For an explanation of how data-at-execution parameter data is passed at statement execution time, see "Passing Parameter Values" in SQLBindParameter. For an explanation of how data-at-execution column data is updated or added, see "Using SQLSetPos" in SQLSetPos.

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 22003 (Numeric value out of range).

Code Example

Future

Related Functions

For information about	See
Canceling statement processing	SQLCancel
Executing an SQL statement	SQLExecDirect
Executing a prepared statement	SQLExecute
Returning the next parameter to send data for	SQLParamData
Assigning storage for a parameter	SQLBindParameter

ODBC Router

ODBC Router transparently makes all ODBC drivers on a central Windows Server useable by your network's Linux, Macintosh and Windows systems. Three years in the making, ODBC Router has saved its customers millions of dollars in DLL installation and ODBC support costs for less than the price of a new PC and a few minutes installation time. ODBC Router provides a low cost, turnkey database network with enterprise class IT support.

Ditching the ODBC Administrator Control Panel:

By linking your application with the free ODBC Router client-side SDK instead of the ODBC Driver Manager, the need for your end-users to deal with driver installation or an ODBC Control Panel is gone! We even provide a setup function your code may call to display a "network browser" that enables your customer to "find" their ODBC Router server on the network, then "choose" the exact database they want to work with and finally return to your application with a fully-formed ODBC connection-string that may be stored and passed back to SQLConnect or SQLDriverConnect anytime your user wants to initiate a connection that data source. No more walking your customers through the process of adding data sources to ODBC Control Panel or, in the case of non-Windows computers, no need to worry about whether or not a compatible third-party ODBC Driver Manager has been installed for use with your code. (Remember that ODBC Router supports Mac OS 9, Mac OS X, Linux and Windows.) If there ever are any client-side ODBC support issues, AugSoft can handle them directly with the customer freeing you to focus on the application.

ODBC or JDBC?

JDBC drivers launch a CPU-intensive virtual machine in the background on your machine, which is bad for shared servers and for battery powered laptops or entry level desktops (that typically have slow busses and drives). As the world shifted to laptops and shared servers, the whole "virtual machine" concept became a support nightmare and so these days good Java apps are compiled to run as native (not emulated) code. Java developers may use the operating system's native ODBC support from within the JDBC class library using the sun.jdbc.odbc.JdbcOdbcDriver driver with a URL as shown below.

jdbc:odbc:dsn[;key=value]*

Example:

jdbc:odbc:finance;UID=cfo;

IT techs may then complete the database connection on the Customer's machine using ODBC Router or the database vendor's official ODBC driver.

NOTE: By creating ODBC data sources with ODBC Router, your apps will enjoy native speed and database independent connections from either Java/C/C++/C#/ObjC or PHP/PERL/Python/Ruby/BASIC on Linux, Macintosh and Windows. Also be aware that using ODBC Router with the Mac platform is an especially good idea because database vendors have not kept their Mac drivers in sync with Windows and there are actual third-party vendors who wrap freeware and JDBC drivers inside of ODBC "shells" without warning their customers! This problem is of great concern to developers because fake drivers almost always fly past the IT guys who test with speed deamon desktops, but fail the enterprise when user laptops and iMacs take too long to run queries or slowly corrupt the database when they do. IT guys often chalk this up to "network problems" leaving users with poison drivers to avoid their database. ODBC Router addresses this issue by enabling official vendor supported Windows ODBC drivers (on a Windows Server) to be accessed from all platforms, network wide.

ODBC 3.x?

It's not here yet. Even in 2010, most ODBC drivers are ODBC 1.x and 2.x. The ODBC Driver Manager translates between 3.x and 2.x or 2.x and 1.x ODBC calls. Therefore, if you don't need UNICODE, it's a bad idea to use ODBC 3.x API calls. That said, UNICODE is a Good Thing and there are actually at least three databases that natively support it now, so look for 3.x to be here soon.

Need ODBC API Help?

We really know ODBC and we routinely provide code-level ODBC help to our customers. Our low cost ODBC Router systems are available now at our online store and if your site buys them, you may open a ticket to ask ODBC development questions --we offer both E-Mail and On-Call support options in seven of the G8's timezones! Be sure to test your ODBC Router and ask for any needed installation help before purchase because we aren't Fry's --no refunds please, our prices are too low for such nonsense and we're too busy supporting real Customers!