发送 Long 数据

  • 项目

DBMS 将长数据定义为特定大小的任意字符或二进制数据，例如 254 个字符。 可能无法将整个长数据项存储在内存中，例如，当该项表示长文本文档或位图时。 由于此类数据不能存储在单个缓冲区中，因此在执行语句时，数据源会通过 SQLPutData 将其分部分发送到驱动程序。 在执行时发送其数据的参数称为执行时数据参数。

注意

应用程序实际上可以使用 SQLPutData 在执行时发送任何类型的数据，尽管只能分部分发送字符和二进制数据。 但是，如果数据足够小，无法容纳在单个缓冲区中，则通常没有理由使用 SQLPutData。 绑定缓冲区并让驱动程序从缓冲区中检索数据要容易得多。

要在执行时发送数据，应用程序将执行以下操作：

  1. 传递一个 32 位值，该值标识 SQLBindParameter 中 ParameterValuePtr 参数中的参数，而不是传递缓冲区的地址。 驱动程序不会分析此值。 稍后会将其返回到应用程序，因此它对于应用程序应该具有一定的意义。 例如，它可能是包含数据的参数或文件的句柄的数量。

  2. 在 SQLBindParameter 的 StrLen_or_IndPtr 参数中传递长度/标记缓冲区的地址。

  3. 将长度/标记缓冲区中存储 SQL_DATA_AT_EXEC 或 SQL_LEN_DATA_AT_EXEC(length) 宏的结果。 这些值向驱动程序指示将使用 SQLPutData 发送参数的数据。 向数据源发送长数据时，将使用 SQL_LEN_DATA_AT_EXEC(length)，该数据源需要知道将发送多少字节的长数据，以便它可以预先分配空间。 若要确定数据源是否需要此值，应用程序使用 SQL_NEED_LONG_DATA_LEN 选项调用 SQLGetInfo。 所有驱动程序都必须支持此宏；如果数据源不需要字节长度，驱动程序可以忽略它。

  4. 调用 SQLExecute 或 SQLExecDirect。 驱动程序发现长度/标记缓冲区包含 SQL_DATA_AT_EXEC 值或 SQL_LEN_DATA_AT_EXEC(length) 宏的结果，并将 SQL_NEED_DATA 作为函数的返回值返回。

  5. 调用 SQLParamData 以响应 SQL_NEED_DATA 返回值。 如果需要发送长数据，SQLParamData 将返回 SQL_NEED_DATA。 在 ValuePtrPtr 参数指向的缓冲区中，驱动程序返回标识执行时数据参数的值。 如果有多个执行时数据参数，则应用程序必须使用此值来确定要向其发送数据的参数；驱动程序不需要以任何特定顺序请求执行时数据参数的数据。

  6. 调用 SQLPutData 将参数数据发送到驱动程序。 如果参数数据不适合单个缓冲区，与长数据的情况一样，应用程序会反复调用 SQLPutData 以分部分发送数据；重组数据由驱动程序和数据源决定。 如果应用程序传递以 NULL 结尾的字符串数据，驱动程序或数据源必须在重组过程中删除 NULL 终止字符。

  7. 再次调用 SQLParamData 以指示它已发送参数的所有数据。 如果存在尚未发送数据的任何执行时数据参数，驱动程序将返回 SQL_NEED_DATA 和下一个参数的值；应用程序返回到步骤 6。 如果已为所有数据执行参数发送数据，则执行该语句。 SQLParamData 将返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，并且可能返回 SQLBulkOperations 或 SQLSetPos 能够返回的任何返回值或诊断。

在 SQLExecute 或 SQLExecDirect 返回 SQL_NEED_DATA 之后，为最后一个执行时数据参数完全发送数据之前，该语句处于“需要数据”状态。 当语句处于“需要数据”状态时，应用程序只能调用 SQLPutData、SQLParamData、SQLCancel、SQLGetDiagField 或 SQLGetDiagRec；所有其他函数返回 SQLSTATE HY010（函数序列错误）。 调用 SQLCancel 会取消语句的执行，并将其返回到其以前的状态。 有关详细信息，请参阅附录 B：ODBC 状态转换表。

有关在执行时发送数据的示例，请参阅 SQLPutData 函数说明。