符合性
版本引入了: ODBC 1.0 标准符合性: ISO 92
摘要
SQLPutData ,应用程序可以将参数或列的数据发送到在语句执行时驱动程序。 此函数可用于将部分中的字符或二进制数据值发送到字符、 二进制或数据源特定于数据类型 (例如,SQL_LONGVARBINARY 或 SQL_LONGVARCHAR 类型参数) 的列。 SQLPutData支持绑定到 Unicode 的 C 数据类型,即使基础驱动程序不支持 Unicode 数据。
语法
SQLRETURN SQLPutData(
SQLHSTMT StatementHandle,
SQLPOINTER DataPtr,
SQLLEN StrLen_or_Ind);
参数
StatementHandle
[输入]语句句柄。
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,并且指定 SQL 数据类型的默认 C 数据类型为 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 和一个处理的StatementHandle。 下表列出了通常返回的 SQLSTATE 值SQLPutData ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。
| SQLSTATE | 错误 | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO。) |
| 01004 | 字符串数据,右截断 | 字符串或二进制数据返回为输出参数时截断了非空白字符或非 NULL 的二进制数据。 如果它是一个字符串值,它是右侧被截断。 (函数返回 SQL_SUCCESS_WITH_INFO。) |
| 07006 | 受限制的数据类型属性冲突 | 标识的数据值ValueType中的参数SQLBindParameter无法为数据类型由标识转换绑定的参数为ParameterType中的参数SQLBindParameter。 |
| 07S01 | 默认参数的使用无效 | 参数值,设置SQLBindParameter、 是 SQL_DEFAULT_PARAM,并且相应参数没有默认值。 |
| 08S01 | 通讯链接失败 | 该驱动程序和驱动程序已连接到数据源之间的通信链接失败之前函数已完成处理。 |
| 22001 | 字符串数据,右截断 | 字符或二进制值的列分配导致非空白 (字符) 或非 null (二进制) 字符或字节数的截断。 中的 SQL_NEED_LONG_DATA_LEN 信息类型SQLGetInfo为"Y",而且更多的数据已发送 (数据类型为 SQL_LONGVARCHAR、 SQL_LONGVARBINARY、 或的长整型数据源特定于数据类型) 的长参数不是指定了与StrLen_or_IndPtr中的参数SQLBindParameter。 中的 SQL_NEED_LONG_DATA_LEN 信息类型SQLGetInfo为"Y",而且比中指定了更多的数据已发送长列 (数据类型为 SQL_LONGVARCHAR、 SQL_LONGVARBINARY、 或的长整型数据源特定于数据类型)对应于已添加或使用更新的数据行中的列长度的缓冲区SQLBulkOperations或更新,它SQLSetPos。 |
| 22003 | 数值超出范围 | 数据将发送有关绑定的数值参数或列导致数字被截断时分配给关联的表的列的整个 (而不是小数) 部分。 返回一个数字值 (数值或字符串) 的一个或多个输入/输出参数或输出参数将导致要截断的数字的整个 (而不是小数) 部分。 |
| 22007 | 日期时间格式无效 | 发送参数或已绑定到日期、 时间或时间戳结构的列的数据时,分别,无效的日期、 时间戳。 输入/输出或输出参数绑定到日期、 时间或时间戳 C 结构,返回的参数中的值时,分别,无效的日期、 时间戳。 (函数返回 SQL_SUCCESS_WITH_INFO。) |
| 22008 | 日期时间字段溢出 | 日期时间表达式计算的输入/输出或输出参数导致了日期、 时间或时间戳 C 结构无效。 |
| 22012 | 被零除 | 算术表达式计算的输入/输出或输出参数导致除零。 |
| 22015 | 间隔字段溢出 | 为确切的数值或时间间隔列发送数据或间隔 SQL 数据类型的参数时导致重要数字丢失。 数据已发送间隔列或多个字段参数、 已转换为数值数据类型,和的数值数据类型中有没有表示形式。 列发送数据或参数数据分配到的时间间隔的 SQL 类型,并且没有在时间间隔内 SQL 类型的 C 类型的值没有表示形式。 精确数字或时间间隔 C 列或参数 C 间隔类型发送的数据时导致重要数字丢失。 列发送数据或参数数据已分配给一个 C 间隔结构,没有间隔数据结构中的数据的表示形式。 |
| 22018 | 转换指定的字符值无效 | C 类型为精确或近似数值、 日期时间或间隔数据类型;列的 SQL 类型是字符数据类型;和中的列或参数的值不是有效的绑定 C 类型的文本。 SQL 类型是精确或近似数值、 日期时间或间隔数据类型;C 类型为 SQL_C_CHAR;和中的列或参数的值不是绑定的 SQL 类型的有效文本。 |
| HY000 | 常规错误 | 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。 返回的错误消息SQLGetDiagRec中 *MessageText缓冲区描述错误以及其原因。 |
| HY001 | 内存分配错误 | 该驱动程序无法分配支持执行或完成该函数所需的内存。 |
| HY008 | 操作已取消 | 异步处理的已启用StatementHandle。 调用该函数,和之前执行完毕SQLCancel或SQLCancelHandle上调用了StatementHandle。 然后在再次调用该函数StatementHandle。 调用该函数,和之前执行完毕SQLCancel或SQLCancelHandle上调用了StatementHandle来自不同线程中多线程应用程序。 |
| HY009 | 使用空指针无效 | (DM) 参数DataPtr是空指针和参数StrLen_or_Ind不是 0,SQL_DEFAULT_PARAM 或 SQL_NULL_DATA。 |
| HY010 | 函数序列错误 | (DM) 以前的函数调用不是调用SQLPutData或SQLParamData。 (DM) 为与之关联的连接句柄调用以异步方式执行的函数StatementHandle。 此异步函数仍在执行调用 SQLPutData 函数时。 (数据挖掘) SQLExecute, SQLExecDirect,或SQLMoreResults曾为StatementHandle和返回 SQL_PARAM_DATA_可用。 数据已检索到的所有经过流处理参数之前调用此函数。 (DM) 的调用以异步方式执行的函数 (不是此类似) StatementHandle和仍在执行时调用此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存不足的情况。 |
| HY019 分段 | 分段发送非字符和非二进制数据 | SQLPutData已被调用超过一次参数或列中,并且从未被使用它将字符 C 数据发送到字符、 二进制或数据源特定于数据类型的列,或将二进制 C 数据发送到具有一个字符的列二进制文件或数据源特定于数据类型。 |
| HY020 | 尝试连接 null 值 | SQLPutData以来的调用返回 SQL_NEED_DATA,和一个这些调用中多次调用StrLen_or_Ind参数包含 SQL_NULL_DATA 或 SQL_DEFAULT_PARAM。 |
| HY090 | 字符串或缓冲区长度无效 | 自变量DataPtr不是 null 指针和参数StrLen_or_Ind小于 0,但不是等于 SQL_NTS 或 SQL_NULL_DATA。 |
| HY117 | 由于未知的事务状态而挂起连接。 仅断开连接,并允许使用只读的函数。 | (DM) 有关挂起状态的详细信息,请参阅SQLEndTran 函数。 |
| HYT01 | 连接超时时间已到 | 连接超时期限过期之前的数据源响应此请求。 通过设置连接超时期SQLSetConnectAttr,SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | (DM) 驱动程序与相关联StatementHandle不支持该函数。 |
| IM017 | 轮询异步通知模式中禁用 | 只要使用通知模型,将禁用轮询。 |
| IM018 | SQLCompleteAsync尚未调用以完成此句柄上以前的异步操作。 | 如果句柄上的上一个函数调用返回 SQL_STILL_EXECUTING,如果启用通知模式,则SQLCompleteAsync必须要对其进行后期处理并完成该操作的句柄上调用。 |
如果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 和中的另一个指示器 *ValuePtrPtr,它需要另一个参数或列的数据并SQLPutData再次调用。 如果驱动程序将返回 SQL_SUCCESS,然后所有数据在执行发送数据,并可以执行 SQL 语句或SQLBulkOperations或SQLSetPos调用可以进行处理。
在语句执行时传递的数据在执行参数数据的详细信息,请参阅"传递参数值"中SQLBindParameter并发送长数据。 有关如何执行时的数据列数据的详细信息更新或添加,请参阅"使用 SQLSetPos"一节中SQLSetPos,"执行大容量更新使用中的书签" SQLBulkOperations,和Long 数据和 SQLSetPos 及 SQLBulkOperations。
Note:
应用程序可以使用SQLPutData发送部分仅当将字符 C 数据发送到字符、 二进制或数据源特定于数据类型的列或将二进制 C 数据发送到具有二进制文件,一个字符的列中的数据特定于源的数据类型。 如果SQLPutData调用一次以上任何其他情况下,它将返回 SQL_ERROR 和 SQLSTATE hy019 分段 (分段发送非字符和非二进制数据)。
示例
下面的示例假定名为 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);
}
相关函数
| 有关信息 | 请参阅 |
|---|---|
| 绑定到参数的缓冲区 | SQLBindParameter 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行已准备的 SQL 语句 | SQLExecute 函数 |
| 返回下一个参数将数据发送用于 | SQLParamData 函数 |
请参阅
历史资料。此文对应 2018-11-30 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 MightyPen)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
