发送 Long 数据Sending Long Data

Dbms 将长数据定义为一定大小的任何字符或二进制数据,例如254个字符。DBMSs define long data as any character or binary data over a certain size, such as 254 characters. 可能无法将长数据的整个项存储在内存中,如项表示长文本文档或位图。It might not be possible to store an entire item of long data in memory, such as when the item represents a long text document or a bitmap. 由于此类数据无法存储在单个缓冲区中,因此在执行语句时,数据源会将其发送到包含SQLPutData的部分中的驱动程序。Because such data cannot be stored in a single buffer, the data source sends it to the driver in parts with SQLPutData when the statement is executed. 用于在执行时发送数据的参数称为 "执行时数据" 参数Parameters for which data is sent at execution time are known as data-at-execution parameters.

备注

应用程序可以在执行时实际通过SQLPutData发送任意类型的数据,尽管只能在部分中发送字符和二进制数据。An application can actually send any type of data at execution time with SQLPutData, although only character and binary data can be sent in parts. 但是,如果数据太小,足以容纳在单个缓冲区中,通常没有理由使用SQLPutDataHowever, if the data is small enough to fit in a single buffer, there is generally no reason to use SQLPutData. 绑定缓冲区并让驱动程序从缓冲区中检索数据,这要简单得多。It is much easier to bind the buffer and let the driver retrieve the data from the buffer.

若要在执行时发送数据,应用程序需要执行以下操作:To send data at execution time, the application performs the following actions:

  1. SQLBindParameter中传递标识ParameterValuePtr参数中的参数的32位值,而不是传递缓冲区的地址。Passes a 32-bit value that identifies the parameter in the ParameterValuePtr argument in SQLBindParameter rather than passing the address of a buffer. 驱动程序不会分析此值。This value is not analyzed by the driver. 稍后会将其返回给应用程序,因此应用程序的意思应该是什么。It will be returned to the application later, so it should mean something to the application. 例如,它可能是参数的编号或包含数据的文件的句柄。For example, it might be the number of the parameter or the handle of a file containing data.

  2. SQLBindParameterStrLen_or_IndPtr参数中传递长度/指示器缓冲区的地址。Passes the address of a length/indicator buffer in the StrLen_or_IndPtr argument of SQLBindParameter.

  3. 将 SQL_DATA_AT_EXEC 或 SQL_LEN_DATA_AT_EXEC (长度)宏的结果存储在长度/指示器缓冲区中。Stores SQL_DATA_AT_EXEC or the result of the SQL_LEN_DATA_AT_EXEC(length) macro in the length/indicator buffer. 这两个值向驱动程序指示参数的数据将与SQLPutData一起发送。Both of these values indicate to the driver that the data for the parameter will be sent with SQLPutData. 向数据源发送长数据时,将使用 SQL_LEN_DATA_AT_EXEC (长度),该数据源需要知道将发送多少字节的长数据以便它能够预分配空间。SQL_LEN_DATA_AT_EXEC(length) is used when sending long data to a data source that needs to know how many bytes of long data will be sent so that it can preallocate space. 若要确定数据源是否需要此值,应用程序需要使用 SQL_NEED_LONG_DATA_LEN 选项调用SQLGetInfoTo determine if a data source requires this value, the application calls SQLGetInfo with the SQL_NEED_LONG_DATA_LEN option. 所有驱动程序都必须支持此宏;如果数据源不需要字节长度,则驱动程序可以忽略此长度。All drivers must support this macro; if the data source does not require the byte length, the driver can ignore it.

  4. 调用SQLExecuteSQLExecDirectCalls SQLExecute or SQLExecDirect. 驱动程序发现长度/指示器缓冲区包含 SQL_DATA_AT_EXEC 的值或 SQL_LEN_DATA_AT_EXEC (长度)宏的结果,并返回 SQL_NEED_DATA 作为函数的返回值。The driver discovers that a length/indicator buffer contains the value SQL_DATA_AT_EXEC or the result of the SQL_LEN_DATA_AT_EXEC(length) macro and returns SQL_NEED_DATA as the return value of the function.

  5. 调用SQLParamData以响应 SQL_NEED_DATA 返回值。Calls SQLParamData in response to the SQL_NEED_DATA return value. 如果需要发送长数据, SQLParamData返回 SQL_NEED_DATA。If long data needs to be sent, SQLParamData returns SQL_NEED_DATA. 在由ValuePtrPtr参数指向的缓冲区中,驱动程序将返回标识执行时数据参数的值。In the buffer pointed to by the ValuePtrPtr argument, the driver returns the value that identifies the data-at-execution parameter. 如果有多个执行时数据参数,则应用程序必须使用此值来确定要为其发送数据的参数;该驱动程序不要求以任何特定顺序为执行时数据参数请求数据。If there is more than one data-at-execution parameter, the application must use this value to determine which parameter to send data for; the driver is not required to request data for data-at-execution parameters in any particular order.

  6. 调用SQLPutData将参数数据发送给驱动程序。Calls SQLPutData to send the parameter data to the driver. 如果参数数据不适用于单个缓冲区,通常情况下,长数据的情况下,应用程序会重复调用SQLPutData以在部分中发送数据;驱动程序和数据源由驱动程序和数据源组成,用于重组数据。If the parameter data does not fit into a single buffer, as is often the case with long data, the application calls SQLPutData repeatedly to send the data in parts; it is up to the driver and data source to reassemble the data. 如果应用程序传递了以 null 结尾的字符串数据,则驱动程序或数据源必须删除 null 终止字符作为重汇编过程的一部分。If the application passes null-terminated string data, the driver or data source must remove the null-termination character as part of the reassembly process.

  7. 再次调用SQLParamData ,以指示它已发送参数的所有数据。Calls SQLParamData again to indicate that it has sent all of the data for the parameter. 如果有数据尚未发送的任何执行时数据参数,则驱动程序将返回 SQL_NEED_DATA 和标识下一个参数的值;应用程序返回到步骤6。If there are any data-at-execution parameters for which data has not been sent, the driver returns SQL_NEED_DATA and the value that identifies the next parameter; the application returns to step 6. 如果为所有执行时数据参数发送了数据,则执行该语句。If data has been sent for all data-at-execution parameters, the statement is executed. SQLParamData返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO,可以返回SQLExecuteSQLExecDirect可以返回的任何返回值或诊断。SQLParamData returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO and can return any return value or diagnostic that SQLExecute or SQLExecDirect can return.

SQLExecuteSQLExecDirect返回 SQL_NEED_DATA 之后,在为最后一个执行时数据参数完全发送数据之前,该语句处于需要数据状态。After SQLExecute or SQLExecDirect returns SQL_NEED_DATA and before data has been completely sent for the last data-at-execution parameter, the statement is in a Need Data state. 当语句处于需要数据状态时,应用程序只能调用SQLPutDataSQLParamDataSQLCancelSQLGetDiagFieldSQLGetDiagRec;所有其他函数返回 SQLSTATE HY010 (函数序列错误)。While a statement is in a Need Data state, the application can call only SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField, or SQLGetDiagRec; all other functions return SQLSTATE HY010 (Function sequence error). 调用SQLCancel将取消语句的执行,并将其返回到它以前的状态。Calling SQLCancel cancels execution of the statement and returns it to its previous state. 有关详细信息,请参阅附录 B: ODBC 状态转换表For more information, see Appendix B: ODBC State Transition Tables.

有关在执行时发送数据的示例,请参阅SQLPutData函数说明。For an example of sending data at execution time, see the SQLPutData function description.