SQLBindParameter 函数SQLBindParameter Function

Conformance
引入的版本: ODBC 2.0 标准符合性: ODBCVersion Introduced: ODBC 2.0 Standards Compliance: ODBC

总结Summary
SQLBindParameter将缓冲区绑定到 SQL 语句中的参数标记。SQLBindParameter binds a buffer to a parameter marker in an SQL statement. SQLBindParameter支持绑定到 unicode C 数据类型,即使基础驱动程序不支持 unicode 数据。SQLBindParameter supports binding to a Unicode C data type, even if the underlying driver does not support Unicode data.

备注

此函数取代了 ODBC 1.0 函数SQLSetParamThis function replaces the ODBC 1.0 function SQLSetParam. 有关详细信息,请参阅 "注释"。For more information, see "Comments."

语法Syntax

  
SQLRETURN SQLBindParameter(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT     InputOutputType,  
      SQLSMALLINT     ValueType,  
      SQLSMALLINT     ParameterType,  
      SQLULEN         ColumnSize,  
      SQLSMALLINT     DecimalDigits,  
      SQLPOINTER      ParameterValuePtr,  
      SQLLEN          BufferLength,  
      SQLLEN *        StrLen_or_IndPtr);  

参数Arguments

StatementHandleStatementHandle
送语句句柄。[Input] Statement handle.

ParameterNumberParameterNumber
送参数编号,按递增参数顺序排序,从1开始。[Input] Parameter number, ordered sequentially in increasing parameter order, starting at 1.

InputOutputTypeInputOutputType
送参数的类型。[Input] The type of the parameter. 有关详细信息,请参阅 "备注" 中的 "InputOutputType参数"。For more information, see "InputOutputType Argument" in "Comments."

ValueTypeValueType
送参数的 C 数据类型。[Input] The C data type of the parameter. 有关详细信息,请参阅 "备注" 中的 "ValueType参数"。For more information, see "ValueType Argument" in "Comments."

ParameterTypeParameterType
送参数的 SQL 数据类型。[Input] The SQL data type of the parameter. 有关详细信息,请参阅 "备注" 中的 "ParameterType参数"。For more information, see "ParameterType Argument" in "Comments."

ColumnSizeColumnSize
送相应参数标记的列或表达式的大小。[Input] The size of the column or expression of the corresponding parameter marker. 有关详细信息,请参阅 "备注" 中的 "ColumnSize参数"。For more information, see "ColumnSize Argument" in "Comments."

如果你的应用程序将在64位 Windows 操作系统上运行,请参阅ODBC 64 位信息If your application will run on a 64-bit Windows operating system, see ODBC 64-Bit Information.

DecimalDigitsDecimalDigits
送相应参数标记的列或表达式的十进制数字。[Input] The decimal digits of the column or expression of the corresponding parameter marker. 有关列大小的详细信息,请参阅列大小、十进制数字、传输八位字节长度和显示大小For more information about column size, see Column Size, Decimal Digits, Transfer Octet Length, and Display Size.

ParameterValuePtrParameterValuePtr
[延迟输入]指向参数数据缓冲区的指针。[Deferred Input] A pointer to a buffer for the parameter's data. 有关详细信息,请参阅 "备注" 中的 "ParameterValuePtr参数"。For more information, see "ParameterValuePtr Argument" in "Comments."

BufferLengthBufferLength
[输入/输出]ParameterValuePtr缓冲区的长度(以字节为单位)。[Input/Output] Length of the ParameterValuePtr buffer in bytes. 有关详细信息,请参阅 "备注" 中的 "BufferLength参数"。For more information, see "BufferLength Argument" in "Comments."

如果你的应用程序将在64位操作系统上运行,请参阅ODBC 64 位信息See ODBC 64-Bit Information, if your application will run on a 64-bit operating system.

StrLen_or_IndPtrStrLen_or_IndPtr
[延迟输入]指向参数长度的缓冲区的指针。[Deferred Input] A pointer to a buffer for the parameter's length. 有关详细信息,请参阅 "备注" 中的 "StrLen_or_IndPtr参数"。For more information, see "StrLen_or_IndPtr Argument" in "Comments."

返回Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLBindParameter返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时,可以通过使用HandleType的 SQL_HANDLE_STMT 和StatementHandle句柄调用SQLGetDiagRec来获取关联的 SQLSTATE 值。When SQLBindParameter 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. 下表列出了通常由SQLBindParameter返回的 SQLSTATE 值,并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values typically returned by SQLBindParameter and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 除非另有说明,否则与每个 SQLSTATE 值相关联的返回代码将 SQL_ERROR。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE 错误Error 说明Description
0100001000 一般警告General warning 驱动程序特定的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
0700607006 受限制的数据类型属性冲突Restricted data type attribute violation ValueType参数标识的数据类型无法转换为ParameterType参数标识的数据类型。The data type identified by the ValueType argument cannot be converted to the data type identified by the ParameterType argument. 请注意,此错误可能由SQLExecDirectSQLExecuteSQLPutData在执行时返回,而不是由SQLBindParameter返回。Notice that this error may be returned by SQLExecDirect, SQLExecute, or SQLPutData at execution time, instead of by SQLBindParameter.
0700907009 描述符索引无效Invalid descriptor index (DM)为参数ParameterNumber指定的值小于1。(DM) The value specified for the argument ParameterNumber was less than 1.
HY000HY000 常规错误General error 发生了一个错误,该错误没有特定的 SQLSTATE,没有为其定义实现特定的 SQLSTATE。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. MessageText*缓冲区中的SQLGetDiagRec**返回的错误消息描述了错误及其原因。The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 驱动程序无法分配支持执行或完成此函数所需的内存。The driver was unable to allocate memory that is required to support execution or completion of the function.
HY003HY003 应用程序缓冲区类型无效Invalid application buffer type 参数ValueType指定的值不是有效的 C 数据类型或 SQL_C_DEFAULT。The value specified by the argument ValueType was not a valid C data type or SQL_C_DEFAULT.
HY004HY004 SQL 数据类型无效Invalid SQL data type 为参数ParameterType指定的值既不是有效的 ODBC sql 数据类型标识符,也不是驱动程序支持的特定于驱动程序的 SQL 数据类型标识符。The value specified for the argument ParameterType was neither a valid ODBC SQL data type identifier nor a driver-specific SQL data type identifier supported by the driver.
HY009HY009 参数值无效Invalid argument value (DM)参数ParameterValuePtr为 null 指针,参数StrLen_or_IndPtr为 null 指针,并且未 SQL_PARAM_OUTPUT 参数InputOutputType(DM) The argument ParameterValuePtr was a null pointer, the argument StrLen_or_IndPtr was a null pointer, and the argument InputOutputType was not SQL_PARAM_OUTPUT.

(DM) SQL_PARAM_OUTPUT,其中,参数ParameterValuePtr为 null 指针,C 类型为 char 或 Binary,BufferLength (cbValueMax)大于0。(DM) SQL_PARAM_OUTPUT, where the argument ParameterValuePtr was a null pointer, the C type was char or binary, and the BufferLength (cbValueMax) was greater than 0.
HY010HY010 函数序列错误Function sequence error (DM)为与StatementHandle关联的连接句柄调用了异步执行的函数。(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 调用SQLBindParameter时仍在执行此异步函数。This asynchronous function was still executing when SQLBindParameter was called.

StatementHandle调用了SQLExecuteSQLExecDirectSQLMoreResults ,并返回 SQL_PARAM_DATA_AVAILABLE。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 在检索所有流式处理参数的数据之前调用此函数。This function was called before data was retrieved for all streamed parameters.

(DM)为StatementHandle调用了异步执行的函数,并且在调用此函数时仍在执行该函数。(DM) An asynchronously executing function was called for the StatementHandle and was still executing when this function was called.

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos调用了StatementHandle并返回 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 在为所有执行时数据参数或列发送数据之前,将调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.
HY013HY013 内存管理错误Memory management error 未能处理函数调用,原因可能是由于内存不足而无法访问基础内存对象。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY021HY021 描述符信息不一致Inconsistent descriptor information 在一致性检查过程中检查的描述符信息不一致。The descriptor information checked during a consistency check was not consistent. (请参阅SQLSetDescField中的 "一致性检查" 一节。)(See the "Consistency Checks" section in SQLSetDescField.)

为参数DecimalDigits指定的值超出了由ParameterType参数指定的 SQL 数据类型列的数据源所支持的值的范围。The value specified for the argument DecimalDigits was outside the range of values supported by the data source for a column of the SQL data type specified by the ParameterType argument.
HY090HY090 字符串或缓冲区长度无效Invalid string or buffer length (DM) BufferLength中的值小于0。(DM) The value in BufferLength was less than 0. (请参阅SQLSetDescField中的 SQL_DESC_DATA_PTR 字段的说明。)(See the description of the SQL_DESC_DATA_PTR field in SQLSetDescField.)
HY104HY104 无效的精度或小数位数值Invalid precision or scale value 为参数ColumnSizeDecimalDigits指定的值超出了由ParameterType参数指定的 SQL 数据类型列的数据源所支持的值的范围。The value specified for the argument ColumnSize or DecimalDigits was outside the range of values supported by the data source for a column of the SQL data type specified by the ParameterType argument.
HY105HY105 无效的参数类型Invalid parameter type (DM)为参数InputOutputType指定的值无效。(DM) The value specified for the argument InputOutputType was invalid. (请参阅 "备注"。)(See "Comments.")
HY117HY117 由于未知的事务状态,连接被挂起。Connection is suspended due to unknown transaction state. 仅允许断开连接和只读函数。Only disconnect and read-only functions are allowed. (DM)有关挂起状态的详细信息,请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYC00HYC00 未实现的可选功能Optional feature not implemented 驱动程序或数据源不支持通过为参数ValueType指定的值和为参数ParameterType指定的驱动程序特定值的组合指定的转换。The driver or data source does not support the conversion specified by the combination of the value specified for the argument ValueType and the driver-specific value specified for the argument ParameterType.

为参数ParameterType指定的值为驱动程序支持的 odbc 版本的有效 odbc SQL 数据类型标识符,但驱动程序或数据源不支持此标识符。The value specified for the argument ParameterType was a valid ODBC SQL data type identifier for the version of ODBC supported by the driver but was not supported by the driver or data source.

驱动程序仅支持 ODBC 2。x和参数ValueType为以下其中一项:The driver supports only ODBC 2.x and the argument ValueType was one of the following:

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINTSQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

以及附录 D:数据类型中c 数据类型中列出的所有时间间隔 c 数据类型。and all the interval C data types listed in C Data Types in Appendix D: Data Types.

驱动程序仅支持3.50 之前的 ODBC 版本,并 SQL_C_GUID 参数ValueTypeThe driver only supports ODBC versions prior to 3.50, and the argument ValueType was SQL_C_GUID.
HYT01HYT01 连接超时已过期Connection timeout expired 连接超时期限在数据源响应请求之前过期。The connection timeout period expired before the data source responded to the request. 连接超时期限通过SQLSetConnectAttr设置,SQL_ATTR_CONNECTION_TIMEOUT。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此功能Driver does not support this function (DM)与StatementHandle关联的驱动程序不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.

注释Comments

应用程序调用SQLBindParameter来绑定 SQL 语句中的每个参数标记。An application calls SQLBindParameter to bind each parameter marker in an SQL statement. 绑定始终有效,直到应用程序再次调用SQLBindParameter ,将SQLFreeStmt与 SQL_RESET_PARAMS 选项一起调用,或调用SQLSetDescField将 APD 的 SQL_DESC_COUNT 标头字段设置为0。Bindings remain in effect until the application calls SQLBindParameter again, calls SQLFreeStmt with the SQL_RESET_PARAMS option, or calls SQLSetDescField to set the SQL_DESC_COUNT header field of the APD to 0.

有关参数的详细信息,请参阅语句参数For more information about parameters, see Statement Parameters. 有关参数数据类型和参数标记的详细信息,请参阅附录 C: SQL 语法中的参数数据类型参数标记For more information about parameter data types and parameter markers, see Parameter Data Types and Parameter Markers in Appendix C: SQL Grammar.

ParameterNumber 参数ParameterNumber Argument

如果对SQLBindParameter的调用中的ParameterNumber大于 SQL_DESC_COUNT 的值,则调用SQLSetDescField以将 SQL_DESC_COUNT 的值增加到ParameterNumberIf ParameterNumber in the call to SQLBindParameter is greater than the value of SQL_DESC_COUNT, SQLSetDescField is called to increase the value of SQL_DESC_COUNT to ParameterNumber.

InputOutputType 参数InputOutputType Argument

InputOutputType参数指定参数的类型。The InputOutputType argument specifies the type of the parameter. 此参数设置 IPD 的 SQL_DESC_PARAMETER_TYPE 字段。This argument sets the SQL_DESC_PARAMETER_TYPE field of the IPD. 不调用过程的 SQL 语句中的所有参数(如INSERT语句)都是input * * 参数All parameters in SQL statements that do not call procedures, such as INSERT statements, are input**parameters. 过程调用中的参数可以是输入、输入/输出或输出参数。Parameters in procedure calls can be input, input/output, or output parameters. (应用程序调用SQLProcedureColumns来确定过程调用中的参数类型; 不能确定其类型的参数假定为输入参数。)(An application calls SQLProcedureColumns to determine the type of a parameter in a procedure call; parameters whose type cannot be determined are assumed to be input parameters.)

InputOutputType参数是下列值之一:The InputOutputType argument is one of the following values:

  • SQL_PARAM_INPUT。SQL_PARAM_INPUT. 参数在不调用过程的 SQL 语句(如INSERT语句)中标记参数,或在过程中标记输入参数。The parameter marks a parameter in an SQL statement that does not call a procedure, such as an INSERT statement, or it marks an input parameter in a procedure. 例如,插入到员工值(?,?,?) 中的参数是输入参数,而 {call AddEmp (?,?,?)} 中的参数可以是(但不一定)输入参数。For example, the parameters in INSERT INTO Employee VALUES (?, ?, ?) are input parameters, whereas the parameters in {call AddEmp(?, ?, ?)} can be, but are not necessarily, input parameters.

    执行语句时,驱动程序将参数的数据发送到数据源;* ParameterValuePtr缓冲区必须包含有效的输入值,或者 *StrLen_or_IndPtr缓冲区必须包含 SQL_LEN_DATA_AT_EXEC 宏 SQL_NULL_DATA、SQL_DATA_AT_EXEC 或结果。When the statement is executed, the driver sends data for the parameter to the data source; the *ParameterValuePtr buffer must contain a valid input value, or the *StrLen_or_IndPtr buffer must contain SQL_NULL_DATA, SQL_DATA_AT_EXEC, or the result of the SQL_LEN_DATA_AT_EXEC macro.

    如果应用程序不能在过程调用中确定参数的类型,则会将InputOutputType设置为 SQL_PARAM_INPUT;如果数据源返回参数的值,则驱动程序会将其丢弃。If an application cannot determine the type of a parameter in a procedure call, it sets InputOutputType to SQL_PARAM_INPUT; if the data source returns a value for the parameter, the driver discards it.

  • SQL_PARAM_INPUT_OUTPUT。SQL_PARAM_INPUT_OUTPUT. 参数标记过程中的输入/输出参数。The parameter marks an input/output parameter in a procedure. 例如, {Call GetEmpDept (?)} 中的参数是一个输入/输出参数,该参数接受雇员姓名,并返回雇员的部门名称。For example, the parameter in {call GetEmpDept(?)} is an input/output parameter that accepts an employee's name and returns the name of the employee's department.

    执行语句时,驱动程序将参数的数据发送到数据源;* ParameterValuePtr缓冲区必须包含有效的输入值,或者* StrLen_or_IndPtr缓冲区必须包含 SQL_LEN_DATA_AT_EXEC 宏的 SQL_NULL_DATA、SQL_DATA_AT_EXEC 或结果。When the statement is executed, the driver sends data for the parameter to the data source; the *ParameterValuePtr buffer must contain a valid input value, or the *StrLen_or_IndPtr buffer must contain SQL_NULL_DATA, SQL_DATA_AT_EXEC, or the result of the SQL_LEN_DATA_AT_EXEC macro. 执行语句之后,驱动程序将参数的数据返回到应用程序;如果数据源不返回输入/输出参数的值,则驱动程序将 *StrLen_or_IndPtr缓冲区设置为 SQL_NULL_DATA。After the statement is executed, the driver returns data for the parameter to the application; if the data source does not return a value for an input/output parameter, the driver sets the *StrLen_or_IndPtr buffer to SQL_NULL_DATA.

    备注

    当 ODBC 1.0 应用程序在 ODBC 2.0 驱动程序中调用SQLSetParam时,驱动程序管理器会将其转换为对SQLBindParameter的调用,其中InputOutputType参数设置为 SQL_PARAM_INPUT_OUTPUT。When an ODBC 1.0 application calls SQLSetParam in an ODBC 2.0 driver, the Driver Manager converts this to a call to SQLBindParameter in which the InputOutputType argument is set to SQL_PARAM_INPUT_OUTPUT.

  • SQL_PARAM_OUTPUT。SQL_PARAM_OUTPUT. 参数在过程中标记过程或 output 参数的返回值;在这两种情况下,它们称为output 参数The parameter marks the return value of a procedure or an output parameter in a procedure; in either case, these are known as output parameters. 例如, {? = Call GetNextEmpID} 中的参数是一个输出参数,该参数返回下一个雇员 ID。For example, the parameter in {?=call GetNextEmpID} is an output parameter that returns the next employee ID.

    执行语句之后,驱动程序将参数的数据返回到应用程序,除非ParameterValuePtrStrLen_or_IndPtr参数都是 null 指针,在这种情况下,驱动程序会丢弃输出值。After the statement is executed, the driver returns data for the parameter to the application, unless the ParameterValuePtr and StrLen_or_IndPtr arguments are both null pointers, in which case the driver discards the output value. 如果数据源不返回 output 参数的值,则驱动程序将 *StrLen_or_IndPtr缓冲区设置为 SQL_NULL_DATA。If the data source does not return a value for an output parameter, the driver sets the *StrLen_or_IndPtr buffer to SQL_NULL_DATA.

  • SQL_PARAM_INPUT_OUTPUT_STREAM。SQL_PARAM_INPUT_OUTPUT_STREAM. 指示应对输入/输出参数进行流式处理。Indicates that an input/output parameter should be streamed. SQLGetData可以读取部分中的参数值。SQLGetData can read parameter values in parts. 由于将在调用SQLGetData时确定缓冲区长度,因此忽略BufferLengthBufferLength is ignored because the buffer length will be determined at the call of SQLGetData. StrLen_or_IndPtr缓冲区的值必须包含 SQL_NULL_DATA、SQL_DEFAULT_PARAM、SQL_DATA_AT_EXEC 或 SQL_LEN_DATA_AT_EXEC 宏的结果。The value of the StrLen_or_IndPtr buffer must contain SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC, or the result of the SQL_LEN_DATA_AT_EXEC macro. 如果参数将在输出中进行流式处理,则必须将参数作为执行时数据(DAE)参数绑定到输入中。A parameter must be bound as a data-at-execution (DAE) parameter at input if it will be streamed at output. ParameterValuePtr可以是将由SQLParamData返回的任何非 null 指针值作为用户定义的标记,其值与ParameterValuePtr一起传递给输入和输出。ParameterValuePtr can be any non-null pointer value that will be returned by SQLParamData as the user-defined token whose value was passed with ParameterValuePtr for both input and output. 有关详细信息,请参阅使用 SQLGetData 检索输出参数For more information, see Retrieving Output Parameters Using SQLGetData.

  • SQL_PARAM_OUTPUT_STREAM。SQL_PARAM_OUTPUT_STREAM. 对于 OUTPUT 参数,与 SQL_PARAM_INPUT_OUTPUT_STREAM 相同。Same as SQL_PARAM_INPUT_OUTPUT_STREAM, for an output parameter. 输入时将忽略StrLen_or_IndPt\r* 。\ *StrLen_or_IndPtr is ignored at input.

下表列出了InputOutputType和 *StrLen_or_IndPtr的不同组合:The following table lists different combinations of InputOutputType and *StrLen_or_IndPtr:

InputOutputTypeInputOutputType *StrLen_or_IndPtr*StrLen_or_IndPtr 业务成效Outcome ParameterValuePtr 上的注释Remark on ParameterValuePtr
SQL_PARAM_INPUTSQL_PARAM_INPUT SQL_LEN_DATA_AT_EXEC (LEN)或 SQL_DATA_AT_EXECSQL_LEN_DATA_AT_EXEC(len) or SQL_DATA_AT_EXEC 部分输入Input in parts ParameterValuePtr可以是将由SQLParamData返回的任何指针值,它是其值与ParameterValuePtr一起传递的用户定义的标记。ParameterValuePtr can be any pointer value that will be returned by SQLParamData as the user-defined token whose value was passed with ParameterValuePtr.
SQL_PARAM_INPUTSQL_PARAM_INPUT Not SQL_LEN_DATA_AT_EXEC (LEN)或 SQL_DATA_AT_EXECNot SQL_LEN_DATA_AT_EXEC(len) or SQL_DATA_AT_EXEC 输入绑定缓冲区Input bound buffer ParameterValuePtr是输入缓冲区的地址。ParameterValuePtr is the address of the input buffer.
SQL_PARAM_OUTPUTSQL_PARAM_OUTPUT 在输入时忽略。Ignored at input. 输出绑定缓冲区Output bound buffer ParameterValuePtr是输出缓冲区的地址。ParameterValuePtr is the address of the output buffer.
SQL_PARAM_OUTPUT_STREAMSQL_PARAM_OUTPUT_STREAM 在输入时忽略。Ignored at input. 流式处理输出Streamed output ParameterValuePtr可以是任何指针值, SQLParamData将其作为其值与ParameterValuePtr一起传递的用户定义标记返回。ParameterValuePtr can be any pointer value, which will be returned by SQLParamData as the user-defined token whose value was passed with ParameterValuePtr.
SQL_PARAM_INPUT_OUTPUTSQL_PARAM_INPUT_OUTPUT SQL_LEN_DATA_AT_EXEC (LEN)或 SQL_DATA_AT_EXECSQL_LEN_DATA_AT_EXEC(len) or SQL_DATA_AT_EXEC 部分输入和输出绑定缓冲区Input in parts and output bound buffer ParameterValuePtr是输出缓冲区的地址, SQLParamData将返回其值与ParameterValuePtr一起传递的用户定义标记。ParameterValuePtr is the address of the output buffer, which will also be returned by SQLParamData as the user-defined token whose value was passed with ParameterValuePtr.
SQL_PARAM_INPUT_OUTPUTSQL_PARAM_INPUT_OUTPUT Not SQL_LEN_DATA_AT_EXEC (LEN)或 SQL_DATA_AT_EXECNot SQL_LEN_DATA_AT_EXEC(len) or SQL_DATA_AT_EXEC 输入绑定缓冲区和输出绑定缓冲区Input bound buffer and output bound buffer ParameterValuePtr是共享的输入/输出缓冲区的地址。ParameterValuePtr is the address of the shared input/output buffer.
SQL_PARAM_INPUT_OUTPUT_STREAMSQL_PARAM_INPUT_OUTPUT_STREAM SQL_LEN_DATA_AT_EXEC (LEN)或 SQL_DATA_AT_EXECSQL_LEN_DATA_AT_EXEC(len) or SQL_DATA_AT_EXEC 部分输入和流式输出Input in parts and streamed output ParameterValuePtr可以是任何非 null 指针值, SQLParamData将它作为用户定义的标记返回,其值与ParameterValuePtr一起传递输入和输出。ParameterValuePtr can be any non-null pointer value, which will be returned by SQLParamData as the user-defined token whose value was passed with ParameterValuePtr for both input and output.

备注

当应用程序将输出或输入输出参数绑定为流式处理时,驱动程序必须决定允许哪些 SQL 类型。The driver must decide which SQL types are allowed when an application binds an output or input-output parameter as streamed. 对于无效的 SQL 类型,驱动程序管理器不会生成错误。The driver manager will not generate an error for an invalid SQL type.

ValueType 参数ValueType Argument

ValueType参数指定参数的 C 数据类型。The ValueType argument specifies the C data type of the parameter. 此参数设置 APD 的 SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE 和 SQL_DESC_DATETIME_INTERVAL_CODE 字段。This argument sets the SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, and SQL_DESC_DATETIME_INTERVAL_CODE fields of the APD. 这必须是附录 D:数据类型的C 数据类型部分中的值之一。This must be one of the values in the C Data Types section of Appendix D: Data Types.

如果ValueType参数是 interval 数据类型之一,则将 APD 的ParameterNumber记录的 "SQL_DESC_TYPE" 字段设置为 "SQL_INTERVAL,将 APD 的" SQL_DESC_CONCISE_TYPE "字段设置为" 简洁间隔 "数据类型,并将ParameterNumber记录的" SQL_DESC_DATETIME_INTERVAL_CODE "字段设置为特定" 时间间隔 "数据类型的子代码。If the ValueType argument is one of the interval data types, the SQL_DESC_TYPE field of the ParameterNumber record of the APD is set to SQL_INTERVAL, the SQL_DESC_CONCISE_TYPE field of the APD is set to the concise interval data type, and the SQL_DESC_DATETIME_INTERVAL_CODE field of the ParameterNumber record is set to a subcode for the specific interval data type. (请参阅附录 D:数据类型。)默认间隔的默认间隔(2)和默认间隔秒精度(6),分别在 APD 的 "SQL_DESC_DATETIME_INTERVAL_PRECISION" 和 "SQL_DESC_PRECISION" 字段中设置,用于数据。(See Appendix D: Data Types.) The default interval leading precision (2) and default interval seconds precision (6), as set in the SQL_DESC_DATETIME_INTERVAL_PRECISION and SQL_DESC_PRECISION fields of the APD, respectively, are used for the data. 如果任何一个默认精度不合适,则应用程序应通过调用SQLSetDescFieldSQLSetDescRec显式设置描述符字段。If either default precision is not appropriate, the application should explicitly set the descriptor field by a call to SQLSetDescField or SQLSetDescRec.

如果ValueType参数是日期时间数据类型之一,则将 APD 的ParameterNumber记录的 "SQL_DESC_TYPE" 字段设置为 "SQL_DATETIME,将 APD 的ParameterNumber记录的" SQL_DESC_CONCISE_TYPE "字段设置为简明日期时间 C 数据类型,将" ParameterNumber "记录的" SQL_DESC_DATETIME_INTERVAL_CODE "字段设置为特定 datetime 数据类型的子代码。If the ValueType argument is one of the datetime data types, the SQL_DESC_TYPE field of the ParameterNumber record of the APD is set to SQL_DATETIME, the SQL_DESC_CONCISE_TYPE field of the ParameterNumber record of the APD is set to the concise datetime C data type, and the SQL_DESC_DATETIME_INTERVAL_CODE field of the ParameterNumber record is set to a subcode for the specific datetime data type. (请参阅附录 D:数据类型。)(See Appendix D: Data Types.)

如果ValueType参数是 SQL_C_NUMERIC 的数据类型,则将使用在 APD 的 SQL_DESC_PRECISION 和 SQL_DESC_SCALE 字段中设置的默认精度(驱动程序定义的值)和默认刻度(0)作为数据。If the ValueType argument is an SQL_C_NUMERIC data type, the default precision (which is driver-defined) and the default scale (0), as set in the SQL_DESC_PRECISION and SQL_DESC_SCALE fields of the APD, are used for the data. 如果默认的精度或小数位数不合适,应用程序应该通过调用SQLSetDescFieldSQLSetDescRec显式设置描述符字段。If the default precision or scale is not appropriate, the application should explicitly set the descriptor field by a call to SQLSetDescField or SQLSetDescRec.

SQL_C_DEFAULT 指定将从ParameterType指定的 SQL 数据类型的默认 C 数据类型传输参数值。SQL_C_DEFAULT specifies that the parameter value be transferred from the default C data type for the SQL data type specified with ParameterType.

还可以指定扩展的 C 数据类型。You can also specify an extended C data type. 有关详细信息,请参阅ODBC 中的 C 数据类型For more information, see C Data Types in ODBC.

有关详细信息,请参阅附录 D:数据类型中的默认 c 数据类型将数据从 C 转换为 sql 数据类型将数据从 SQL 转换为 C 数据类型For more information, see Default C Data Types, Converting Data from C to SQL Data Types, and Converting Data from SQL to C Data Types in Appendix D: Data Types.

ParameterType 参数ParameterType Argument

此值必须是 "附录 D:数据类型" 的 " SQL 数据类型" 部分中列出的值之一,或者必须是驱动程序特定的值。This must be one of the values listed in the SQL Data Types section of Appendix D: Data Types, or it must be a driver-specific value. 此参数设置 IPD 的 SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE 和 SQL_DESC_DATETIME_INTERVAL_CODE 字段。This argument sets the SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, and SQL_DESC_DATETIME_INTERVAL_CODE fields of the IPD.

如果ParameterType参数是日期时间标识符之一,则 ipd 的 SQL_DESC_TYPE 字段设置为 SQL_DATETIME,ipd 的 SQL_DESC_CONCISE_TYPE 字段设置为简明日期时间 SQL 数据类型,SQL_DESC_DATETIME_INTERVAL_CODE 字段设置为相应的 datetime 子代码值。If the ParameterType argument is one of the datetime identifiers, the SQL_DESC_TYPE field of the IPD is set to SQL_DATETIME, the SQL_DESC_CONCISE_TYPE field of the IPD is set to the concise datetime SQL data type, and the SQL_DESC_DATETIME_INTERVAL_CODE field is set to the appropriate datetime subcode value.

如果ParameterType是某个间隔标识符,则 ipd 的 "SQL_DESC_TYPE" 字段将设置为 SQL_INTERVAL,ipd 的 "SQL_DESC_CONCISE_TYPE" 字段设置为 "简洁 SQL interval" 数据类型,而 ipd 的 "SQL_DESC_DATETIME_INTERVAL_CODE" 字段设置为相应的间隔子代码。If ParameterType is one of the interval identifiers, the SQL_DESC_TYPE field of the IPD is set to SQL_INTERVAL, the SQL_DESC_CONCISE_TYPE field of the IPD is set to the concise SQL interval data type, and the SQL_DESC_DATETIME_INTERVAL_CODE field of the IPD is set to the appropriate interval subcode. IPD 的 "SQL_DESC_DATETIME_INTERVAL_PRECISION" 字段设置为间隔前导精度,并且 SQL_DESC_PRECISION 字段设置为间隔秒精度(如果适用)。The SQL_DESC_DATETIME_INTERVAL_PRECISION field of the IPD is set to the interval leading precision, and the SQL_DESC_PRECISION field is set to the interval seconds precision, if applicable. 如果 SQL_DESC_DATETIME_INTERVAL_PRECISION 或 SQL_DESC_PRECISION 的默认值不合适,则应用程序应通过调用SQLSetDescField进行显式设置。If the default value of SQL_DESC_DATETIME_INTERVAL_PRECISION or SQL_DESC_PRECISION is not appropriate, the application should explicitly set it by calling SQLSetDescField. 有关这些字段的详细信息,请参阅SQLSetDescFieldFor more information about any of these fields, see SQLSetDescField.

如果ValueType参数是 SQL_NUMERIC 数据类型,则将使用 IPD 的 "SQL_DESC_PRECISION" 和 "SQL_DESC_SCALE" 字段中设置的默认精度(驱动程序定义的值)和默认刻度(0)作为数据。If the ValueType argument is a SQL_NUMERIC data type, the default precision (which is driver-defined) and the default scale (0), as set in the SQL_DESC_PRECISION and SQL_DESC_SCALE fields of the IPD, are used for the data. 如果默认的精度或小数位数不合适,应用程序应该通过调用SQLSetDescFieldSQLSetDescRec显式设置描述符字段。If the default precision or scale is not appropriate, the application should explicitly set the descriptor field by a call to SQLSetDescField or SQLSetDescRec.

有关如何转换数据的信息,请参阅附录 D:数据类型中的将数据从 C 转换为 Sql 数据类型将数据从 SQL 转换为 C 数据类型For information about how data is converted, see Converting Data from C to SQL Data Types and Converting Data from SQL to C Data Types in Appendix D: Data Types.

ColumnSize 参数ColumnSize Argument

ColumnSize参数指定对应于参数标记的列或表达式的大小、该数据的长度或两者。The ColumnSize argument specifies the size of the column or expression that corresponds to the parameter marker, the length of that data, or both. 此参数设置 IPD 的不同字段,具体取决于 SQL 数据类型( ParameterType参数)。This argument sets different fields of the IPD, depending on the SQL data type (the ParameterType argument). 以下规则适用于此映射:The following rules apply to this mapping:

  • 如果ParameterType是 SQL_CHAR、SQL_VARCHAR、SQL_LONGVARCHAR、SQL_BINARY、SQL_VARBINARY、SQL_LONGVARBINARY 或简洁的 SQL 日期时间或间隔数据类型之一,则 IPD 的 SQL_DESC_LENGTH 字段将设置为ColumnSize的值。If ParameterType is SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY, or one of the concise SQL datetime or interval data types, the SQL_DESC_LENGTH field of the IPD is set to the value of ColumnSize. (有关详细信息,请参阅附录 D:数据类型中的列大小、十进制数字、传输八位字节长度和显示大小部分。)(For more information, see the Column Size, Decimal Digits, Transfer Octet Length, and Display Size section in Appendix D: Data Types.)

  • 如果ParameterType是 SQL_DECIMAL、SQL_NUMERIC、SQL_FLOAT、SQL_REAL 或 SQL_DOUBLE,则 IPD 的 SQL_DESC_PRECISION 字段将设置为ColumnSize的值。If ParameterType is SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL, or SQL_DOUBLE, the SQL_DESC_PRECISION field of the IPD is set to the value of ColumnSize.

  • 对于其他数据类型,将忽略ColumnSize参数。For other data types, the ColumnSize argument is ignored.

有关详细信息,请参阅 "StrLen_or_IndPtr参数" 中的 "传递参数值" 和 SQL_DATA_AT_EXEC。For more information, see "Passing Parameter Values" and SQL_DATA_AT_EXEC in "StrLen_or_IndPtr Argument."

DecimalDigits 参数DecimalDigits Argument

如果ParameterType SQL_TYPE_TIME,SQL_TYPE_TIMESTAMP,SQL_INTERVAL_SECOND,SQL_INTERVAL_DAY_TO_SECOND,SQL_INTERVAL_HOUR_TO_SECOND 或 SQL_INTERVAL_MINUTE_TO_SECOND,则 IPD 的 SQL_DESC_PRECISION 字段将设置为DecimalDigitsIf ParameterType is SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND, or SQL_INTERVAL_MINUTE_TO_SECOND, the SQL_DESC_PRECISION field of the IPD is set to DecimalDigits. 如果ParameterType是 SQL_NUMERIC 或 SQL_DECIMAL,则 IPD 的 SQL_DESC_SCALE 字段将设置为DecimalDigitsIf ParameterType is SQL_NUMERIC or SQL_DECIMAL, the SQL_DESC_SCALE field of the IPD is set to DecimalDigits. 对于所有其他数据类型,将忽略DecimalDigits参数。For all other data types, the DecimalDigits argument is ignored.

ParameterValuePtr 参数ParameterValuePtr Argument

ParameterValuePtr参数指向一个缓冲区,当调用SQLExecuteSQLExecDirect时,该缓冲区包含参数的实际数据。The ParameterValuePtr argument points to a buffer that, when SQLExecute or SQLExecDirect is called, contains the actual data for the parameter. 数据必须采用ValueType参数所指定的格式。The data must be in the form specified by the ValueType argument. 此参数设置 APD 的 SQL_DESC_DATA_PTR 字段。This argument sets the SQL_DESC_DATA_PTR field of the APD. 只要*StrLen_or_IndPtr SQL_NULL_DATA 或 SQL_DATA_AT_EXEC,应用程序就可以将ParameterValuePtr参数设置为 null 指针。An application can set the ParameterValuePtr argument to a null pointer, as long as *StrLen_or_IndPtr is SQL_NULL_DATA or SQL_DATA_AT_EXEC. (这仅适用于输入参数或输入/输出参数。)(This applies only to input or input/output parameters.)

如果* StrLen_or_IndPtr是 SQL_LEN_DATA_AT_EXEC (长度)宏或 SQL_DATA_AT_EXEC 的结果,则ParameterValuePtr是一个与参数相关联的应用程序定义的指针值。If *StrLen_or_IndPtr is the result of the SQL_LEN_DATA_AT_EXEC(length) macro or SQL_DATA_AT_EXEC, then ParameterValuePtr is an application-defined pointer value that is associated with the parameter. 它通过SQLParamData返回到应用程序。It is returned to the application through SQLParamData. 例如, ParameterValuePtr可能是非零标记,如参数号、指向数据的指针或指向应用程序用于绑定输入参数的结构的指针。For example, ParameterValuePtr might be a non-zero token such as a parameter number, a pointer to data, or a pointer to a structure that the application used to bind input parameters. 但请注意,如果参数是一个输入/输出参数,则ParameterValuePtr必须是指向缓冲区的指针,将在其中存储输出值。However, note that if the parameter is an input/output parameter, ParameterValuePtr must be a pointer to a buffer where the output value will be stored. 如果 SQL_ATTR_PARAMSET_SIZE 语句特性中的值大于1,则应用程序可将 SQL_ATTR_PARAMS_PROCESSED_PTR 语句特性指向的值与ParameterValuePtr参数一起使用。If the value in the SQL_ATTR_PARAMSET_SIZE statement attribute is greater than 1, the application can use the value pointed to by the SQL_ATTR_PARAMS_PROCESSED_PTR statement attribute together with the ParameterValuePtr argument. 例如, ParameterValuePtr可能指向值的数组,并且应用程序可能使用指向的值 SQL_ATTR_PARAMS_PROCESSED_PTR 从数组中检索正确的值。For example, ParameterValuePtr might point to an array of values and the application might use the value pointed to by SQL_ATTR_PARAMS_PROCESSED_PTR to retrieve the correct value from the array. 有关详细信息,请参阅本节后面的 "传递参数值"。For more information, see "Passing Parameter Values" later in this section.

如果InputOutputType参数 SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_OUTPUT,则ParameterValuePtr将指向驱动程序返回输出值的缓冲区。If the InputOutputType argument is SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT, ParameterValuePtr points to a buffer in which the driver returns the output value. 如果过程返回一个或多个结果集,则*在处理完所有结果集/行计数之前,不能保证ParameterValuePtr缓冲区的设置。If the procedure returns one or more result sets, the *ParameterValuePtr buffer is not guaranteed to be set until all result sets/row counts have been processed. 如果在处理完成之前未设置缓冲区,则在SQLMoreResults返回 SQL_NO_DATA 之前,输出参数和返回值将不可用。If the buffer is not set until processing is complete, the output parameters and return values are unavailable until SQLMoreResults returns SQL_NO_DATA. 使用 SQL_CLOSE 的选项调用SQLCloseCursorSQLFreeStmt将导致这些值被丢弃。Calling SQLCloseCursor or SQLFreeStmt with an Option of SQL_CLOSE will cause these values to be discarded.

如果 SQL_ATTR_PARAMSET_SIZE 语句特性中的值大于1,则ParameterValuePtr指向数组。If the value in the SQL_ATTR_PARAMSET_SIZE statement attribute is greater than 1, ParameterValuePtr points to an array. 单个 SQL 语句处理输入或输入/输出参数的完整输入值数组,并返回输入/输出或输出参数的输出值的数组。A single SQL statement processes the complete array of input values for an input or input/output parameter and returns an array of output values for an input/output or output parameter.

BufferLength 参数BufferLength Argument

对于字符和二进制 C 数据, BufferLength参数指定* ParameterValuePtr缓冲区的长度(如果它是单个元素)或* ParameterValuePtr数组中元素的长度(如果 SQL_ATTR_PARAMSET_SIZE 语句特性中的值大于1)。For character and binary C data, the BufferLength argument specifies the length of the *ParameterValuePtr buffer (if it is a single element) or the length of an element in the *ParameterValuePtr array (if the value in the SQL_ATTR_PARAMSET_SIZE statement attribute is greater than 1). 此参数设置 APD 的 "SQL_DESC_OCTET_LENGTH 记录" 字段。This argument sets the SQL_DESC_OCTET_LENGTH record field of the APD. 如果应用程序指定了多个值,则BufferLength用于确定 *ParameterValuePtr数组中的值的位置,这些值在输入和输出上都是如此。If the application specifies multiple values, BufferLength is used to determine the location of values in the *ParameterValuePtr array, both on input and on output. 对于输入/输出和输出参数,它用于确定是否在输出时截断字符和二进制 C 数据:For input/output and output parameters, it is used to determine whether to truncate character and binary C data on output:

  • 对于字符 C 数据,如果可返回的字节数大于或等于BufferLength,则* ParameterValuePtr中的数据将被截断为BufferLength小于 null 终止字符的长度,并以 null 值终止于驱动程序。For character C data, if the number of bytes available to return is greater than or equal to BufferLength, the data in *ParameterValuePtr is truncated to BufferLength less the length of a null-termination character and is null-terminated by the driver.

  • 对于二进制 C 数据,如果可返回的字节数大于BufferLength,则* ParameterValuePtr中的数据将被截断为BufferLength字节。For binary C data, if the number of bytes available to return is greater than BufferLength, the data in *ParameterValuePtr is truncated to BufferLength bytes.

对于所有其他类型的 C 数据,将忽略BufferLength参数。For all other types of C data, the BufferLength argument is ignored. * ParameterValuePtr缓冲区的长度(如果它是单个元素)或* ParameterValuePtr数组中的元素的长度(如果应用程序调用SQLSetStmtAttr ,其中属性SQL_ATTR_PARAMSET_SIZE 参数为每个参数指定多个值)假定为 C 数据类型的长度。The length of the *ParameterValuePtr buffer (if it is a single element) or the length of an element in the *ParameterValuePtr array (if the application calls SQLSetStmtAttr with an Attribute argument of SQL_ATTR_PARAMSET_SIZE to specify multiple values for each parameter) is assumed to be the length of the C data type.

对于流式处理的输出或流式输入/输出参数, BufferLength参数将被忽略,因为缓冲区长度是在SQLGetData中指定的。For streamed output or streamed input/output parameters, the BufferLength argument is ignored because the buffer length is specified in SQLGetData.

备注

当 ODBC 1.0 应用程序调用 ODBC 3 中的SQLSetParam时。x驱动程序,驱动程序管理器将此转换为对SQLBindParameter的调用,其中BufferLength参数始终 SQL_SETPARAM_VALUE_MAX。When an ODBC 1.0 application calls SQLSetParam in an ODBC 3.x driver, the Driver Manager converts this to a call to SQLBindParameter in which the BufferLength argument is always SQL_SETPARAM_VALUE_MAX. 因为如果 ODBC 3,驱动程序管理器会返回错误。x应用程序将BufferLength设置为 SQL_SETPARAM_VALUE_MAX,这是一个 ODBC 3。x驱动程序可以使用它来确定 ODBC 1.0 应用程序调用它的时间。Because the Driver Manager returns an error if an ODBC 3.x application sets BufferLength to SQL_SETPARAM_VALUE_MAX, an ODBC 3.x driver can use this to determine when it is called by an ODBC 1.0 application.

备注

SQLSetParam中,应用程序指定 *ParameterValuePtr缓冲区长度的方式,以便驱动程序可以返回字符或二进制数据,以及应用程序将字符或二进制参数值数组发送到驱动程序的方式由驱动程序定义。In SQLSetParam, the way in which an application specifies the length of the *ParameterValuePtr buffer so that the driver can return character or binary data, and the way in which an application sends an array of character or binary parameter values to the driver, are driver-defined.

StrLen_or_IndPtr 参数StrLen_or_IndPtr Argument

StrLen_or_IndPtr参数指向一个缓冲区,当调用SQLExecuteSQLExecDirect时,它包含以下内容之一。The StrLen_or_IndPtr argument points to a buffer that, when SQLExecute or SQLExecDirect is called, contains one of the following. (此参数设置应用程序参数指针的 SQL_DESC_OCTET_LENGTH_PTR 和 SQL_DESC_INDICATOR_PTR 记录字段。)(This argument sets the SQL_DESC_OCTET_LENGTH_PTR and SQL_DESC_INDICATOR_PTR record fields of the application parameter pointers.)

  • *ParameterValuePtr中存储的参数值的长度。The length of the parameter value stored in *ParameterValuePtr. 这会被忽略,但字符或二进制 C 数据除外。This is ignored except for character or binary C data.

  • SQL_NTS。SQL_NTS. 参数值为以 null 值结束的字符串。The parameter value is a null-terminated string.

  • SQL_NULL_DATA。SQL_NULL_DATA. 参数值为 NULL。The parameter value is NULL.

  • SQL_DEFAULT_PARAM。SQL_DEFAULT_PARAM. 过程是使用参数的默认值,而不是从应用程序中检索到的值。A procedure is to use the default value of a parameter, instead of a value retrieved from the application. 此值仅在 ODBC 规范语法中调用的过程中有效,并且仅当InputOutputType参数 SQL_PARAM_INPUT、SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_INPUT_OUTPUT_STREAM 时才有效。This value is valid only in a procedure called in ODBC canonical syntax, and then only if the InputOutputType argument is SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT, or SQL_PARAM_INPUT_OUTPUT_STREAM. SQL_DEFAULT_PARAM * StrLen_or_IndPtr时,将忽略ValueTypeParameterTypeColumnSizeDecimalDigitsBufferLengthParameterValuePtr参数的输入参数,这些参数仅用于定义输入/输出参数的输出参数值。When *StrLen_or_IndPtr is SQL_DEFAULT_PARAM, the ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength, and ParameterValuePtr arguments are ignored for input parameters and are used only to define the output parameter value for input/output parameters.

  • SQL_LEN_DATA_AT_EXEC (长度)宏的结果。The result of the SQL_LEN_DATA_AT_EXEC(length) macro. 参数的数据将与SQLPutData一起发送。The data for the parameter will be sent with SQLPutData. 如果ParameterType参数 SQL_LONGVARBINARY、SQL_LONGVARCHAR 或特定于数据源的数据类型,并且驱动程序为SQLGetInfo中的 SQL_NEED_LONG_DATA_LEN 信息类型返回 "Y",则length是要为参数发送的数据的字节数;否则,长度必须为非负值并且将被忽略。If the ParameterType argument is SQL_LONGVARBINARY, SQL_LONGVARCHAR, or a long, data source-specific data type, and the driver returns "Y" for the SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo, length is the number of bytes of data to be sent for the parameter; otherwise, length must be a nonnegative value and is ignored. 有关详细信息,请参阅本节后面的 "传递参数值"。For more information, see "Passing Parameter Values," later in this section.

    例如,若要指定在一个或多个调用中使用SQLPutData发送10000字节的数据,请为 SQL_LONGVARCHAR 参数指定一个应用程序,将 *StrLen_or_IndPtr SQL_LEN_DATA_AT_EXEC (10000)。For example, to specify that 10,000 bytes of data will be sent with SQLPutData in one or more calls, for an SQL_LONGVARCHAR parameter, an application sets *StrLen_or_IndPtr to SQL_LEN_DATA_AT_EXEC(10000).

  • SQL_DATA_AT_EXEC。SQL_DATA_AT_EXEC. 参数的数据将与SQLPutData一起发送。The data for the parameter will be sent with SQLPutData. 此值由 ODBC 1.0 应用程序在调用 ODBC 3 时使用。x驱动程序。This value is used by ODBC 1.0 applications when they call ODBC 3.x drivers. 有关详细信息,请参阅本节后面的 "传递参数值"。For more information, see "Passing Parameter Values," later in this section.

如果StrLen_or_IndPtr为 null 指针,则驱动程序会假定所有输入参数值均为非 null,并且字符和二进制数据以 null 结尾。If StrLen_or_IndPtr is a null pointer, the driver assumes that all input parameter values are non-NULL and that character and binary data is null-terminated. 如果InputOutputType是 SQL_PARAM_OUTPUT 或 SQL_PARAM_OUTPUT_STREAM 并且ParameterValuePtrStrLen_or_IndPtr都是 null 指针,则驱动程序将丢弃输出值。If InputOutputType is SQL_PARAM_OUTPUT or SQL_PARAM_OUTPUT_STREAM and ParameterValuePtr and StrLen_or_IndPtr are both null pointers, the driver discards the output value.

备注

当 SQL_C_BINARY 参数的数据类型时,强烈建议应用程序开发人员为StrLen_or_IndPtr指定 null 指针。Application developers are strongly discouraged from specifying a null pointer for StrLen_or_IndPtr when the data type of the parameter is SQL_C_BINARY. 若要确保驱动程序不会意外截断 SQL_C_BINARY 的数据, StrLen_or_IndPtr应包含指向有效长度值的指针。To make sure that a driver does not unexpectedly truncate SQL_C_BINARY data, StrLen_or_IndPtr should contain a pointer to a valid length value.

如果InputOutputType参数 SQL_PARAM_INPUT_OUTPUT、SQL_PARAM_OUTPUT、SQL_PARAM_INPUT_OUTPUT_STREAM 或 SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr指向驱动程序返回的缓冲区 SQL_NULL_DATA、可在* ParameterValuePtr中返回的字节数(不包括字符数据的 NULL 终止字节)或 SQL_NO_TOTAL (如果无法确定可返回的字节数)。If the InputOutputType argument is SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM, or SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr points to a buffer in which the driver returns SQL_NULL_DATA, the number of bytes available to return in *ParameterValuePtr (excluding the null-termination byte of character data), or SQL_NO_TOTAL (if the number of bytes available to return cannot be determined). 如果过程返回一个或多个结果集,则在提取所有结果之前,不能保证 *StrLen_or_IndPtr缓冲区的设置。If the procedure returns one or more result sets, the *StrLen_or_IndPtr buffer is not guaranteed to be set until all results have been fetched.

如果 SQL_ATTR_PARAMSET_SIZE 语句特性中的值大于1,则StrLen_or_IndPtr指向 SQLLEN 值的数组。If the value in the SQL_ATTR_PARAMSET_SIZE statement attribute is greater than 1, StrLen_or_IndPtr points to an array of SQLLEN values. 这些值可以是本部分前面列出的任何值,并使用单个 SQL 语句进行处理。These can be any of the values listed earlier in this section and are processed with a single SQL statement.

传递参数值Passing Parameter Values

应用程序可以在* ParameterValuePtr缓冲区中或者通过一个或多个对SQLPutData的调用传递参数的值。An application can pass the value for a parameter either in the *ParameterValuePtr buffer or with one or more calls to SQLPutData. 其数据与SQLPutData一起传递的参数称为执行时数据参数。Parameters whose data is passed with SQLPutData are known as data-at-execution parameters. 这些参数通常用于发送 SQL_LONGVARBINARY 和 SQL_LONGVARCHAR 参数的数据,并且可以与其他参数混合使用。These are typically used to send data for SQL_LONGVARBINARY and SQL_LONGVARCHAR parameters, and can be mixed with other parameters.

若要传递参数值,应用程序需要执行以下一系列步骤:To pass parameter values, an application performs the following sequence of steps:

  1. 为每个参数调用SQLBindParameter ,以便绑定参数值(ParameterValuePtr参数)和长度/指示器(StrLen_or_IndPtr参数)的缓冲区。Calls SQLBindParameter for each parameter to bind buffers for the parameter's value (ParameterValuePtr argument) and length/indicator (StrLen_or_IndPtr argument). 对于执行时数据参数, ParameterValuePtr是应用程序定义的指针值,如参数号或指向数据的指针。For data-at-execution parameters, ParameterValuePtr is an application-defined pointer value such as a parameter number or a pointer to data. 稍后将返回值,并可将其用于标识参数。The value will be returned later and can be used to identify the parameter.

  2. 将*输入和输入/输出参数的值放置在ParameterValuePtr和 *StrLen_or_IndPtr缓冲区中:Places values for input and input/output parameters in the *ParameterValuePtr and *StrLen_or_IndPtr buffers:

    • 对于普通参数,应用程序会将参数值放在* ParameterValuePtr缓冲区中,并将该值的长度置于 *StrLen_or_IndPtr缓冲区中。For normal parameters, the application places the parameter value in the *ParameterValuePtr buffer and the length of that value in the *StrLen_or_IndPtr buffer. 有关详细信息,请参阅设置参数值For more information, see Setting Parameter Values.

    • 对于执行时数据参数,应用程序会将 SQL_LEN_DATA_AT_EXEC (长度)宏(在调用 ODBC 2.0 驱动程序时)的结果放入 *StrLen_or_IndPtr缓冲区。For data-at-execution parameters, the application puts the result of the SQL_LEN_DATA_AT_EXEC(length) macro (when calling an ODBC 2.0 driver) in the *StrLen_or_IndPtr buffer.

  3. 调用SQLExecuteSQLExecDirect执行 SQL 语句。Calls SQLExecute or SQLExecDirect to execute the SQL statement.

    • 如果没有执行时数据参数,则该过程已完成。If there are no data-at-execution parameters, the process is complete.

    • 如果有任何执行时数据参数,则函数将返回 SQL_NEED_DATA。If there are any data-at-execution parameters, the function returns SQL_NEED_DATA.

  4. 调用SQLParamData ,以检索在SQLBindParameterParameterValuePtr参数中指定的应用程序定义的值,以便处理第一个执行时数据参数。Calls SQLParamData to retrieve the application-defined value specified in the ParameterValuePtr argument of SQLBindParameter for the first data-at-execution parameter to be processed. SQLParamData返回 SQL_NEED_DATA。SQLParamData returns SQL_NEED_DATA.

    备注

    尽管执行时数据参数与执行时数据列类似,但SQLParamData返回的值对于每个都是不同的。Although data-at-execution parameters resemble data-at-execution columns, the value returned by SQLParamData is different for each. 执行时数据参数是 SQL 语句中的参数,当使用SQLExecDirectSQLExecute执行语句时,该语句中的数据将与SQLPutData一起发送。Data-at-execution parameters are parameters in an SQL statement for which data will be sent with SQLPutData when the statement is executed with SQLExecDirect or SQLExecute. 它们与SQLBindParameter绑定在一起。They are bound with SQLBindParameter. SQLParamData返回的值是在ParameterValuePtr参数中传递给SQLBindParameter的指针值。The value returned by SQLParamData is a pointer value passed to SQLBindParameter in the ParameterValuePtr argument. 执行时数据列是行集中的列,当使用SQLBulkOperations更新或添加行或使用SQLSetPos更新行时,数据将随SQLPutData一起发送。Data-at-execution columns are columns in a rowset for which data will be sent with SQLPutData when a row is updated or added with SQLBulkOperations or updated with SQLSetPos. 它们与SQLBindCol绑定在一起。They are bound with SQLBindCol. SQLParamData返回的值是正在处理的 TargetValuePtr*缓冲区中的行地址(由对SQLBindCol**的调用设置)。The value returned by SQLParamData is the address of the row in the *TargetValuePtr buffer (set by a call to SQLBindCol) that is being processed.

  5. 调用SQLPutData一次或多次以发送参数的数据。Calls SQLPutData one or more times to send data for the parameter. 如果数据值大于在SQLPutData中指定的* ParameterValuePtr缓冲区,则需要多个调用;仅当使用字符、二进制或数据源特定数据类型将字符 C 数据发送到具有字符、二进制或数据源特定数据类型的列时,才允许对同一参数进行多个调用。More than one call is needed if the data value is larger than the *ParameterValuePtr buffer specified in SQLPutData; multiple calls to SQLPutData for the same parameter are allowed 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.

  6. 再次调用SQLParamData ,以指示已发送参数的所有数据。Calls SQLParamData again to signal that all data has been sent for the parameter.

    • 如果有多个执行时数据参数,则SQLParamData将返回 SQL_NEED_DATA 和应用程序定义的值,以便处理下一个执行时数据参数。If there are more data-at-execution parameters, SQLParamData returns SQL_NEED_DATA and the application-defined value for the next data-at-execution parameter to be processed. 应用程序重复步骤4和5。The application repeats steps 4 and 5.

    • 如果没有其他执行时数据参数,则该过程已完成。If there are no more data-at-execution parameters, the process is complete. 如果语句已成功执行,则SQLParamData将返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO;如果执行失败,则它将返回 SQL_ERROR。If the statement was successfully executed, SQLParamData returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO; if the execution failed, it returns SQL_ERROR. 此时, SQLParamData可以返回可由用于执行语句的函数返回的任何 SQLSTATE (SQLExecDirectSQLExecute)。At this point, SQLParamData can return any SQLSTATE that can be returned by the function that is used to execute the statement (SQLExecDirect or SQLExecute).

      在应用程序检索完语句生成的所有结果集后, * ParameterValuePtr和 *StrLen_or_IndPtr缓冲区中会提供任何输入/输出或输出参数的输出值。Output values for any input/output or output parameters are available in the *ParameterValuePtr and *StrLen_or_IndPtr buffers after the application retrieves all result sets generated by the statement.

调用SQLExecuteSQLExecDirect会将语句置于 SQL_NEED_DATA 状态。Calling SQLExecute or SQLExecDirect puts the statement in an SQL_NEED_DATA state. 此时,应用程序只能调用带有语句的SQLCancelSQLGetDiagFieldSQLGetDiagRecSQLGetFunctionsSQLParamDataSQLPutData以及与该语句关联的连接句柄At this point, the application can call only SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData, or SQLPutData with the statement or the connection handle associated with the statement. 如果它调用具有语句的任何其他函数或与该语句关联的连接,则函数返回 SQLSTATE HY010 (函数序列错误)。If it calls any other function with the statement or the connection associated with the statement, the function returns SQLSTATE HY010 (Function sequence error). SQLParamDataSQLPutData返回错误时,语句将离开 SQL_NEED_DATA 状态, SQLParamData将返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO,否则语句将被取消。The statement leaves the SQL_NEED_DATA state when SQLParamData or SQLPutData returns an error, SQLParamData returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, or the statement is canceled.

如果应用程序调用SQLCancel ,但驱动程序仍需要执行执行时数据参数的数据,则驱动程序将取消语句执行;然后,应用程序可以再次调用SQLExecuteSQLExecDirectIf the application calls SQLCancel while the driver still needs data for data-at-execution parameters, the driver cancels statement execution; the application can then call SQLExecute or SQLExecDirect again.

检索流式处理输出参数Retrieving Streamed Output Parameters

当应用程序将InputOutputType设置为 SQL_PARAM_INPUT_OUTPUT_STREAM 或 SQL_PARAM_OUTPUT_STREAM 时,必须通过对SQLGetData的一个或多个调用来检索输出参数值。When an application sets InputOutputType to SQL_PARAM_INPUT_OUTPUT_STREAM or SQL_PARAM_OUTPUT_STREAM, the output parameter value must be retrieved by one or more calls to SQLGetData. 当驱动程序具有要返回到应用程序的流式输出参数值时,它将返回 SQL_PARAM_DATA_AVAILABLE 来响应对以下函数的调用: SQLMoreResultsSQLExecuteSQLExecDirectWhen the driver has a streamed output parameter value to return to the application, it will return SQL_PARAM_DATA_AVAILABLE in response to a call to the following functions: SQLMoreResults, SQLExecute, and SQLExecDirect. 应用程序调用SQLParamData来确定可用的参数值。An application calls SQLParamData to determine which parameter value is available.

有关 SQL_PARAM_DATA_AVAILABLE 和流式输出参数的详细信息,请参阅使用 SQLGetData 检索输出参数For more information about SQL_PARAM_DATA_AVAILABLE and streamed output parameters, see Retrieving Output Parameters Using SQLGetData.

使用参数的数组Using Arrays of Parameters

当应用程序使用参数标记准备语句并传入参数数组时,可以执行两种不同的方式。When an application prepares a statement with parameter markers and passes in an array of parameters, there are two different ways this can be executed. 一种方法是让驱动程序依赖后端的阵列处理功能,在这种情况下,具有参数数组的整个语句将被视为一个原子单元。One way is for the driver to rely on the array-processing capabilities of the back end, in which case the whole statement with the array of parameters is treated as one atomic unit. Oracle 是支持数组处理功能的数据源的一个示例。Oracle is an example of a data source that supports array processing capabilities. 实现此功能的另一种方法是,驱动程序生成一批 SQL 语句,一个 SQL 语句用于参数数组中的每个参数集,然后执行批处理。Another way to implement this feature is for the driver to generate a batch of SQL statements, one SQL statement for each set of parameters in the parameter array, and execute the batch. 参数数组不能与当前语句的更新一起使用。Arrays of parameters cannot be used with an UPDATE WHERE CURRENT OF statement.

当处理参数数组时,可以使用单个结果集/行计数(每个参数集一个),也可以将结果集/行计数汇总到其中。When an array of parameters is processed, individual result sets/row counts (one for each parameter set) can be available or result sets/rows counts can be rolled up into one. SQLGetInfo中的 SQL_PARAM_ARRAY_ROW_COUNTS 选项指示行计数是否适用于每个参数集(SQL_PARC_BATCH)或仅有一个行计数可用(SQL_PARC_NO_BATCH)。The SQL_PARAM_ARRAY_ROW_COUNTS option in SQLGetInfo indicates whether row counts are available for each set of parameters (SQL_PARC_BATCH) or only one row count is available (SQL_PARC_NO_BATCH).

SQLGetInfo中的 SQL_PARAM_ARRAY_SELECTS 选项指示结果集是否可用于每个参数集(SQL_PAS_BATCH)或仅有一个结果集可用(SQL_PAS_NO_BATCH)。The SQL_PARAM_ARRAY_SELECTS option in SQLGetInfo indicates whether a result set is available for each set of parameters (SQL_PAS_BATCH) or only one result set is available (SQL_PAS_NO_BATCH). 如果驱动程序不允许使用一组参数执行结果集生成语句,SQL_PARAM_ARRAY_SELECTS 将返回 SQL_PAS_NO_SELECT。If the driver does not allow a result set-generating statement to be executed with an array of parameters, SQL_PARAM_ARRAY_SELECTS returns SQL_PAS_NO_SELECT.

有关详细信息,请参阅SQLGetInfo 函数For more information, see SQLGetInfo Function.

为了支持参数数组,将 SQL_ATTR_PARAMSET_SIZE 语句特性设置为指定每个参数的值的数目。To support arrays of parameters, the SQL_ATTR_PARAMSET_SIZE statement attribute is set to specify the number of values for each parameter. 如果字段大于1,则 APD 的 SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR 和 SQL_DESC_OCTET_LENGTH_PTR 字段必须指向数组。If the field is greater than 1, the SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, and SQL_DESC_OCTET_LENGTH_PTR fields of the APD must point to arrays. 每个数组的基数等于 SQL_ATTR_PARAMSET_SIZE 的值。The cardinality of each array is equal to the value of SQL_ATTR_PARAMSET_SIZE.

APD 的 "SQL_DESC_ROWS_PROCESSED_PTR" 字段指向一个缓冲区,该缓冲区包含已处理的参数集的数目,包括错误集。The SQL_DESC_ROWS_PROCESSED_PTR field of the APD points to a buffer that contains the number of sets of parameters that have been processed, including error sets. 处理每组参数时,驱动程序会在缓冲区中存储新值。As each set of parameters is processed, the driver stores a new value in the buffer. 如果为 null 指针,则不返回任何数字。No number will be returned if this is a null pointer. 使用参数数组时,即使由 setting 函数返回 SQL_ERROR,APD 的 SQL_DESC_ROWS_PROCESSED_PTR 字段所指向的值也将被填充。When arrays of parameters are used, the value pointed to by the SQL_DESC_ROWS_PROCESSED_PTR field of the APD is populated even if SQL_ERROR is returned by the setting function. 如果返回 SQL_NEED_DATA,则 APD 的 SQL_DESC_ROWS_PROCESSED_PTR 字段所指向的值将设置为正在处理的参数集。If SQL_NEED_DATA is returned, the value pointed to by the SQL_DESC_ROWS_PROCESSED_PTR field of the APD is set to the set of parameters that is being processed.

绑定参数数组和执行当前语句的更新时,会发生什么情况。What occurs when an array of parameters is bound and an UPDATE WHERE CURRENT OF statement is executed is driver-defined.

按列参数绑定Column-Wise Parameter Binding

在按列绑定中,应用程序将单独的参数和长度/指示器数组绑定到每个参数。In column-wise binding, the application binds separate parameter and length/indicator arrays to each parameter.

若要使用按列绑定,应用程序首先将 SQL_ATTR_PARAM_BIND_TYPE 语句特性设置为 SQL_PARAM_BIND_BY_COLUMN。To use column-wise binding, the application first sets the SQL_ATTR_PARAM_BIND_TYPE statement attribute to SQL_PARAM_BIND_BY_COLUMN. (这是默认值。)对于每个要绑定的列,应用程序执行以下步骤:(This is the default.) For each column to be bound, the application performs the following steps:

  1. 分配参数缓冲区数组。Allocates a parameter buffer array.

  2. 分配长度/指示器缓冲区的数组。Allocates an array of length/indicator buffers.

    备注

    当使用按列绑定时,如果应用程序直接写入描述符,则可以使用单独的数组作为长度和指示器数据。If the application writes directly to descriptors when column-wise binding is used, separate arrays can be used for length and indicator data.

  3. 调用具有以下参数的SQLBindParameterCalls SQLBindParameter with the following arguments:

    • ValueType是参数缓冲区数组中单个元素的 C 类型。ValueType is the C type of a single element in the parameter buffer array.

    • ParameterType是参数的 SQL 类型。ParameterType is the SQL type of the parameter.

    • ParameterValuePtr是参数缓冲区数组的地址。ParameterValuePtr is the address of the parameter buffer array.

    • BufferLength是参数缓冲区数组中单个元素的大小。BufferLength is the size of a single element in the parameter buffer array. 当数据为固定长度数据时,将忽略BufferLength参数。The BufferLength argument is ignored when the data is fixed-length data.

    • StrLen_or_IndPtr是长度/指示器数组的地址。StrLen_or_IndPtr is the address of the length/indicator array.

有关如何使用此信息的详细信息,请参阅本节后面的 "注释" 中的 "ParameterValuePtr 参数"。For more information about how this information is used, see "ParameterValuePtr Argument" in "Comments," later in this section. 有关参数的列绑定的详细信息,请参阅绑定参数数组For more information about column-wise binding of parameters, see Binding Arrays of Parameters.

按行参数绑定Row-Wise Parameter Binding

在按行绑定中,应用程序将定义一个结构,该结构包含每个要绑定的参数的参数和长度/指示器缓冲区。In row-wise binding, the application defines a structure that contains parameter and length/indicator buffers for each parameter to be bound.

若要使用按行绑定,应用程序需要执行以下步骤:To use row-wise binding, the application performs the following steps:

  1. 定义用于保存一组参数(包括参数和长度/指示器缓冲区)的结构,并分配这些结构的数组。Defines a structure to hold a single set of parameters (including both parameter and length/indicator buffers) and allocates an array of these structures.

    备注

    当使用按行绑定时,如果应用程序直接写入描述符,则可以将单独的字段用于长度和指示器数据。If the application writes directly to descriptors when row-wise binding is used, separate fields can be used for length and indicator data.

  2. 将 SQL_ATTR_PARAM_BIND_TYPE 语句特性设置为结构的大小,该结构包含一组参数,或参数将绑定到的缓冲区的实例大小。Sets the SQL_ATTR_PARAM_BIND_TYPE statement attribute to the size of the structure that contains a single set of parameters or to the size of an instance of a buffer into which the parameters will be bound. 长度必须包含所有绑定参数的空间以及结构或缓冲区的任何填充,以确保当绑定参数的地址递增指定长度时,结果将指向中的相同参数的开头。下一行。The length must include space for all the bound parameters, and any padding of the structure or buffer, to make sure that when the address of a bound parameter is incremented with the specified length, the result will point to the beginning of the same parameter in the next row. 在 ANSI C 中使用sizeof运算符时,此行为是保证的。When you use the sizeof operator in ANSI C, this behavior is guaranteed.

  3. 对要绑定的每个参数调用SQLBindParameter ,并提供以下参数:Calls SQLBindParameter with the following arguments for each parameter to be bound:

    • ValueType是要绑定到列的参数缓冲区成员的类型。ValueType is the type of the parameter buffer member to be bound to the column.

    • ParameterType是参数的 SQL 类型。ParameterType is the SQL type of the parameter.

    • ParameterValuePtr是第一个数组元素中的参数缓冲区成员的地址。ParameterValuePtr is the address of the parameter buffer member in the first array element.

    • BufferLength是参数缓冲区成员的大小。BufferLength is the size of the parameter buffer member.

    • StrLen_or_IndPtr是要绑定的长度/指示器成员的地址。StrLen_or_IndPtr is the address of the length/indicator member to be bound.

有关如何使用此信息的详细信息,请参阅本节后面的 "ParameterValuePtr参数"。For more information about how this information is used, see "ParameterValuePtr Argument," later in this section. 有关参数的按行绑定的详细信息,请参阅参数的绑定数组For more information about row-wise binding of parameters, see the Binding Arrays of Parameters.

错误信息Error Information

如果驱动程序未将参数数组作为批处理实现(SQL_PARAM_ARRAY_ROW_COUNTS 选项等于 SQL_PARC_NO_BATCH),则将处理错误情况,就好像执行了一条语句。If a driver does not implement parameter arrays as batches (the SQL_PARAM_ARRAY_ROW_COUNTS option is equal to SQL_PARC_NO_BATCH), error situations are handled as if one statement were executed. 如果驱动程序将参数数组作为批处理实现,则应用程序可以使用 IPD 的 SQL_DESC_ARRAY_STATUS_PTR 标头字段来确定 SQL 语句的参数或参数数组中的哪个参数导致SQLExecDirectSQLExecute返回错误。If the driver does implement parameter arrays as batches, an application can use the SQL_DESC_ARRAY_STATUS_PTR header field of the IPD to determine which parameter of an SQL statement or which parameter in an array of parameters caused SQLExecDirect or SQLExecute to return an error. 此字段包含参数值的每一行的状态信息。This field contains status information for each row of parameter values. 如果字段指示已发生错误,则诊断数据结构中的字段将指示失败的参数的行和参数号。If the field indicates that an error has occurred, fields in the diagnostic data structure will indicate the row and parameter number of the parameter that failed. 数组中的元素数将由 APD 中的 SQL_DESC_ARRAY_SIZE 标头字段定义,该字段可通过 SQL_ATTR_PARAMSET_SIZE 语句特性进行设置。The number of elements in the array will be defined by the SQL_DESC_ARRAY_SIZE header field in the APD, which can be set by the SQL_ATTR_PARAMSET_SIZE statement attribute.

备注

APD 中的 SQL_DESC_ARRAY_STATUS_PTR 标头字段用于忽略参数。The SQL_DESC_ARRAY_STATUS_PTR header field in the APD is used to ignore parameters. 有关忽略参数的详细信息,请参阅下一节 "忽略一组参数"。For more information about ignoring parameters, see the next section, "Ignoring a Set of Parameters."

SQLExecuteSQLExecDirect返回 SQL_ERROR 时,IPD 中的 SQL_DESC_ARRAY_STATUS_PTR 字段所指向的数组中的元素将包含 SQL_PARAM_ERROR、SQL_PARAM_SUCCESS、SQL_PARAM_SUCCESS_WITH_INFO、SQL_PARAM_UNUSED 或 SQL_PARAM_DIAG_UNAVAILABLE。When SQLExecute or SQLExecDirect returns SQL_ERROR, the elements in the array pointed to by the SQL_DESC_ARRAY_STATUS_PTR field in the IPD will contain SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED, or SQL_PARAM_DIAG_UNAVAILABLE.

对于此数组中的每个元素,诊断数据结构包含一个或多个状态记录。For each element in this array, the diagnostic data structure contains one or more status records. 结构的 "SQL_DIAG_ROW_NUMBER" 字段指示导致错误的参数值的行号。The SQL_DIAG_ROW_NUMBER field of the structure indicates the row number of the parameter values that caused the error. 如果可以确定导致错误的参数行中的特定参数,则将在 SQL_DIAG_COLUMN_NUMBER 字段中输入参数号。If it is possible to determine the particular parameter in a row of parameters that caused the error, the parameter number will be entered in the SQL_DIAG_COLUMN_NUMBER field.

当未使用参数时,将会输入 SQL_PARAM_UNUSED,因为在强制SQLExecuteSQLExecDirect中止的之前的参数中发生错误。SQL_PARAM_UNUSED is entered when a parameter has not been used because an error occurred in an earlier parameter that forced SQLExecute or SQLExecDirect to abort. 例如,如果存在50个参数,而在执行导致SQLExecuteSQLExecDirect的 fortieth 参数集时出现错误,则会在参数41到50的状态数组中输入 SQL_PARAM_UNUSED。For example, if there are 50 parameters and an error occurred while executing the fortieth set of parameters that caused SQLExecute or SQLExecDirect to abort, then SQL_PARAM_UNUSED is entered in the status array for parameters 41 through 50.

当驱动程序将参数数组视为单一单元时,将会输入 SQL_PARAM_DIAG_UNAVAILABLE,因此不会生成此单个参数级别的错误信息。SQL_PARAM_DIAG_UNAVAILABLE is entered when the driver treats arrays of parameters as a monolithic unit, so it does not generate this individual parameter level of error information.

处理一组参数时的一些错误会导致在数组中处理后面的参数集以停止。Some errors in the processing of a single set of parameters cause processing of the subsequent sets of parameters in the array to stop. 其他错误不会影响后续参数的处理。Other errors do not affect the processing of subsequent parameters. 将停止处理的错误由驱动程序定义。Which errors will stop processing is driver-defined. 如果未停止处理,则将处理数组中的所有参数,SQL_SUCCESS_WITH_INFO 将作为错误的结果返回,并且 SQL_ATTR_PARAMS_PROCESSED_PTR 定义的缓冲区设置为处理的参数集总数(由SQL_ATTR_PARAMSET_SIZE 语句特性),其中包括错误集。If processing is not stopped, all parameters in the array are processed, SQL_SUCCESS_WITH_INFO is returned as a result of the error, and the buffer defined by SQL_ATTR_PARAMS_PROCESSED_PTR is set to the total number of sets of parameters processed (as defined by the SQL_ATTR_PARAMSET_SIZE statement attribute), which includes error sets.

注意

当处理参数数组时出现错误时的 ODBC 行为在 ODBC 3 中不同。x与 ODBC 2 中的相同。xODBC behavior when an error occurs in the processing of an array of parameters is different in ODBC 3.x than it was in ODBC 2.x. 在 ODBC 2 中。x,函数返回 SQL_ERROR 和处理停止。In ODBC 2.x, the function returned SQL_ERROR and processing ceased. SQLParamOptionspirow参数指向的缓冲区包含错误行号。The buffer pointed to by the pirow argument of SQLParamOptions contained the number of the error row. ODBC 3 中的。x,函数返回 SQL_SUCCESS_WITH_INFO 并且处理可能会停止或继续。In ODBC 3.x, the function returns SQL_SUCCESS_WITH_INFO and processing may either stop or continue. 如果继续,SQL_ATTR_PARAMS_PROCESSED_PTR 指定的缓冲区将被设置为处理的所有参数的值,包括导致错误的参数。If it continues, the buffer specified by SQL_ATTR_PARAMS_PROCESSED_PTR will be set to the value of all parameters processed, including those that resulted in an error. 此行为更改可能会导致现有应用程序出现问题。This change in behavior may cause problems for existing applications.

SQLExecuteSQLExecDirect在完成处理参数数组中的所有参数集之前返回时(例如,当返回 SQL_ERROR 或 SQL_NEED_DATA 时),状态数组将包含已经处理的那些参数的状态。When SQLExecute or SQLExecDirect returns before completing the processing of all parameter sets in a parameter array, such as when SQL_ERROR or SQL_NEED_DATA is returned, the status array contains statuses for those parameters that have already been processed. IPD 中 SQL_DESC_ROWS_PROCESSED_PTR 字段指向的位置包含导致 SQL_ERROR 或 SQL_NEED_DATA 错误代码的参数数组中的行号。The location pointed to by the SQL_DESC_ROWS_PROCESSED_PTR field in the IPD contains the row number in the parameter array that caused the SQL_ERROR or SQL_NEED_DATA error code. 将参数数组发送到 SELECT 语句时,状态数组值的可用性是由驱动程序定义的;它们可能在执行语句后或提取结果集后可用。When an array of parameters is sent to a SELECT statement, the availability of status array values is driver-defined; they may be available after the statement has been executed or as result sets are fetched.

忽略一组参数Ignoring a Set of Parameters

APD 的 SQL_DESC_ARRAY_STATUS_PTR 字段(由 SQL_ATTR_PARAM_STATUS_PTR 语句特性设置)可用于指示应忽略 SQL 语句中的一组绑定参数。The SQL_DESC_ARRAY_STATUS_PTR field of the APD (as set by the SQL_ATTR_PARAM_STATUS_PTR statement attribute) can be used to indicate that a set of bound parameters in an SQL statement should be ignored. 若要指示驱动程序在执行过程中忽略一个或多个参数集,应用程序应遵循以下步骤:To direct the driver to ignore one or more sets of parameters during execution, an application should follow these steps:

  1. 调用SQLSetDescField ,将 APD 的 SQL_DESC_ARRAY_STATUS_PTR 标题字段设置为指向 SQLUSMALLINT 值的数组,使其包含状态信息。Call SQLSetDescField to set the SQL_DESC_ARRAY_STATUS_PTR header field of the APD to point to an array of SQLUSMALLINT values to contain status information. 还可以通过使用 SQL_ATTR_PARAM_OPERATION_PTR 的属性调用SQLSetStmtAttr来设置此字段,这允许应用程序在不获取描述符句柄的情况下设置字段。This field can also be set by calling SQLSetStmtAttr with an Attribute of SQL_ATTR_PARAM_OPERATION_PTR, which allows an application to set the field without obtaining a descriptor handle.

  2. 将 APD 的 SQL_DESC_ARRAY_STATUS_PTR 字段定义的数组的每个元素设置为以下两个值之一:Set each element of the array defined by the SQL_DESC_ARRAY_STATUS_PTR field of the APD to one of two values:

    • SQL_PARAM_IGNORE,指示行已从语句执行中排除。SQL_PARAM_IGNORE, to indicate that the row is excluded from statement execution.

    • SQL_PARAM_PROCEED,指示该行包含在语句执行中。SQL_PARAM_PROCEED, to indicate that the row is included in statement execution.

  3. 调用SQLExecDirectSQLExecute以执行预定义语句。Call SQLExecDirect or SQLExecute to execute the prepared statement.

以下规则适用于 APD 的 "SQL_DESC_ARRAY_STATUS_PTR" 字段定义的数组:The following rules apply to the array defined by the SQL_DESC_ARRAY_STATUS_PTR field of the APD:

  • 默认情况下,指针设置为 null。The pointer is set to null by default.

  • 如果指针为 null,则将使用所有参数集,就像所有元素都设置为 SQL_ROW_PROCEED。If the pointer is null, all sets of parameters are used, as if all elements were set to SQL_ROW_PROCEED.

  • 将元素设置为 SQL_PARAM_PROCEED 不保证操作将使用该特定参数集。Setting an element to SQL_PARAM_PROCEED does not guarantee that the operation will use that particular set of parameters.

  • SQL_PARAM_PROCEED 在头文件中定义为0。SQL_PARAM_PROCEED is defined as 0 in the header file.

应用程序可以设置 APD 中的 "SQL_DESC_ARRAY_STATUS_PTR" 字段,使其指向 IRD 中 SQL_DESC_ARRAY_STATUS_PTR 字段所指向的相同数组。An application can set the SQL_DESC_ARRAY_STATUS_PTR field in the APD to point to the same array as that pointed to by the SQL_DESC_ARRAY_STATUS_PTR field in the IRD. 当将参数绑定到行数据时,这很有用。This is useful when binding parameters to row data. 然后,可以根据行数据的状态忽略参数。Parameters can then be ignored according to the status of the row data. 除了 SQL_PARAM_IGNORE 之外,以下代码还会导致忽略 SQL 语句中的参数: SQL_ROW_DELETED、SQL_ROW_UPDATED 和 SQL_ROW_ERROR。In addition to SQL_PARAM_IGNORE, the following codes cause a parameter in an SQL statement to be ignored: SQL_ROW_DELETED, SQL_ROW_UPDATED, and SQL_ROW_ERROR. 除了 SQL_PARAM_PROCEED 之外,以下代码还会导致 SQL 语句继续: SQL_ROW_SUCCESS、SQL_ROW_SUCCESS_WITH_INFO 和 SQL_ROW_ADDED。In addition to SQL_PARAM_PROCEED, the following codes cause an SQL statement to proceed: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO, and SQL_ROW_ADDED.

重新绑定参数Rebinding Parameters

应用程序可以执行以下两个操作之一来更改绑定:An application can perform either of two operations to change a binding:

  • 调用SQLBindParameter为已绑定的列指定新绑定。Call SQLBindParameter to specify a new binding for a column that is already bound. 驱动程序用新的绑定覆盖旧的绑定。The driver overwrites the old binding with the new one.

  • 指定要添加到由对SQLBindParameter的绑定调用指定的缓冲区地址的偏移量。Specify an offset to be added to the buffer address that was specified by the binding call to SQLBindParameter. 有关详细信息,请参阅下一节 "用偏移量重新绑定"。For more information, see the next section, "Rebinding with Offsets."

用偏移量重新绑定Rebinding with Offsets

当应用程序具有可包含多个参数但调用SQLExecDirectSQLExecute仅使用几个参数的缓冲区域设置时,参数的重新绑定特别有用。Rebinding of parameters is especially useful when an application has a buffer area setup that can contain many parameters but a call to SQLExecDirect or SQLExecute uses only a few of the parameters. 缓冲区中的剩余空间可用于通过按偏移量修改现有绑定来使用下一组参数。The remaining space in the buffer area can be used for the next set of parameters by modifying the existing binding by an offset.

APD 中的 SQL_DESC_BIND_OFFSET_PTR 标头字段指向绑定偏移量。The SQL_DESC_BIND_OFFSET_PTR header field in the APD points to the binding offset. 如果该字段非空,则驱动程序将取消引用指针,如果 SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR 和 SQL_DESC_OCTET_LENGTH_PTR 字段中没有任何值为 null 指针,则将取消引用的值添加到描述符中的这些字段执行时记录。If the field is non-null, the driver dereferences the pointer and, if none of the values in the SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, and SQL_DESC_OCTET_LENGTH_PTR fields is a null pointer, adds the dereferenced value to those fields in the descriptor records at execution time. 当执行 SQL 语句时,将使用新的指针值。The new pointer values are used when the SQL statements are executed. 重新绑定后,偏移量仍有效。The offset remains valid after rebinding. 由于 SQL_DESC_BIND_OFFSET_PTR 是指向偏移量的指针而不是偏移本身,因此,应用程序可以直接更改偏移量,而不必调用SQLSetDescFieldSQLSetDescRec来更改描述符字段。Because SQL_DESC_BIND_OFFSET_PTR is a pointer to the offset rather than the offset itself, an application can change the offset directly, without having to call SQLSetDescField or SQLSetDescRec to change the descriptor field. 默认情况下,指针设置为 null。The pointer is set to null by default. 可以通过调用SQLSetDescField 或通过fAttribute SQL_ATTR_PARAM_BIND_OFFSET_PTR 的** 来设置 ARD 的 "SQL_DESC_BIND_OFFSET_PTR" 字段。The SQL_DESC_BIND_OFFSET_PTR field of the ARD can be set by a call to SQLSetDescField or by a call to SQLSetStmtAttrwith an fAttribute of SQL_ATTR_PARAM_BIND_OFFSET_PTR.

绑定偏移量始终直接添加到 SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR 和 SQL_DESC_OCTET_LENGTH_PTR 字段的值。The binding offset is always added directly to the values in the SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, and SQL_DESC_OCTET_LENGTH_PTR fields. 如果偏移量更改为不同的值,则新值仍会直接添加到每个描述符字段中的值。If the offset is changed to a different value, the new value is still added directly to the value in each descriptor field. 新偏移量不会添加到字段值和任何以前的偏移量之和。The new offset is not added to the sum of the field value and any earlier offsets.

描述符Descriptors

如何绑定参数由 Apd 和 Ipd 的字段确定。How a parameter is bound is determined by fields of the APDs and IPDs. SQLBindParameter中的参数用于设置这些描述符字段。The arguments in SQLBindParameter are used to set those descriptor fields. 还可以通过SQLSetDescField函数设置字段,但SQLBindParameter更有效地使用,因为应用程序不必获得用于调用SQLBindParameter的描述符句柄。The fields can also be set by the SQLSetDescField functions, although SQLBindParameter is more efficient to use because the application does not have to obtain a descriptor handle to call SQLBindParameter.

注意

对一个语句调用SQLBindParameter可能会影响其他语句。Calling SQLBindParameter for one statement can affect other statements. 如果与该语句关联的 ARD 已显式分配并与其他语句相关联,则会发生这种情况。This occurs when the ARD associated with the statement is explicitly allocated and is also associated with other statements. 因为SQLBindParameter修改了 APD 的字段,所以修改将应用到与此描述符关联的所有语句。Because SQLBindParameter modifies the fields of the APD, the modifications apply to all statements with which this descriptor is associated. 如果这不是所需的行为,应用程序应在调用SQLBindParameter之前,将此描述符与其他语句取消关联。If this is not the required behavior, the application should dissociate this descriptor from the other statements before it calls SQLBindParameter.

从概念上讲, SQLBindParameter按顺序执行以下步骤:Conceptually, SQLBindParameter performs the following steps in sequence:

  1. 调用SQLGetStmtAttr以获取 APD 句柄。Calls SQLGetStmtAttr to obtain the APD handle.

  2. 调用SQLGetDescField以获取 APD 的 SQL_DESC_COUNT 字段,如果ColumnNumber参数的值超过了 SQL_DESC_COUNT 的值,则调用SQLSetDescField将 SQL_DESC_COUNT 的值增加到ColumnNumberCalls SQLGetDescField to get the APD's SQL_DESC_COUNT field, and if the value of the ColumnNumber argument exceeds the value of SQL_DESC_COUNT, calls SQLSetDescField to increase the value of SQL_DESC_COUNT to ColumnNumber.

  3. 多次调用SQLSetDescField ,将值分配给 APD 的以下字段:Calls SQLSetDescField multiple times to assign values to the following fields of the APD:

    • 将 SQL_DESC_TYPE 和 SQL_DESC_CONCISE_TYPE 设置为ValueType的值,只不过如果ValueType是 datetime 或 interval 子类型的一个简洁标识符,则它会将 SQL_DESC_TYPE 分别设置为 SQL_DATETIME 或 SQL_INTERVAL,将 SQL_DESC_CONCISE_TYPE 设置为简明标识符,并将 SQL_DESC_DATETIME_INTERVAL_CODE 设置为相应的 datetime 或 interval 子代码。Sets SQL_DESC_TYPE and SQL_DESC_CONCISE_TYPE to the value of ValueType, except that if ValueType is one of the concise identifiers of a datetime or interval subtype, it sets SQL_DESC_TYPE to SQL_DATETIME or SQL_INTERVAL, respectively, sets SQL_DESC_CONCISE_TYPE to the concise identifier, and sets SQL_DESC_DATETIME_INTERVAL_CODE to the corresponding datetime or interval subcode.

    • 将 SQL_DESC_OCTET_LENGTH 字段设置为BufferLength的值。Sets the SQL_DESC_OCTET_LENGTH field to the value of BufferLength.

    • 将 SQL_DESC_DATA_PTR 字段设置为ParameterValue的值。Sets the SQL_DESC_DATA_PTR field to the value of ParameterValue.

    • 将 SQL_DESC_OCTET_LENGTH_PTR 字段设置为StrLen_or_Ind的值。Sets the SQL_DESC_OCTET_LENGTH_PTR field to the value of StrLen_or_Ind.

    • 将 SQL_DESC_INDICATOR_PTR 字段还设置为StrLen_or_Ind的值。Sets the SQL_DESC_INDICATOR_PTR field also to the value of StrLen_or_Ind.

    StrLen_or_Ind参数同时指定指标信息和参数值的长度。The StrLen_or_Ind parameter specifies both the indicator information and the length for the parameter value.

  4. 调用SQLGetStmtAttr以获取 IPD 句柄。Calls SQLGetStmtAttr to obtain the IPD handle.

  5. 调用SQLGetDescField获取 IPD 的 SQL_DESC_COUNT 字段,如果ColumnNumber参数的值超过了 SQL_DESC_COUNT 的值,则调用SQLSetDescField以将 SQL_DESC_COUNT 的值增加到ColumnNumberCalls SQLGetDescField to get the IPD's SQL_DESC_COUNT field, and if the value of the ColumnNumber argument exceeds the value of SQL_DESC_COUNT, calls SQLSetDescField to increase the value of SQL_DESC_COUNT to ColumnNumber.

  6. 多次调用SQLSetDescField ,将值分配给 IPD 的以下字段:Calls SQLSetDescField multiple times to assign values to the following fields of the IPD:

    • 将 SQL_DESC_TYPE 和 SQL_DESC_CONCISE_TYPE 设置为ParameterType的值,但如果ParameterType是 datetime 或 interval 子类型的一个简洁标识符,则它会将 SQL_DESC_TYPE 分别设置为 SQL_DATETIME 或 SQL_INTERVAL,将 SQL_DESC_CONCISE_TYPE 设置为简明标识符,并将 SQL_DESC_DATETIME_INTERVAL_CODE 设置为相应的 datetime 或 interval 子代码。Sets SQL_DESC_TYPE and SQL_DESC_CONCISE_TYPE to the value of ParameterType, except that if ParameterType is one of the concise identifiers of a datetime or interval subtype, it sets SQL_DESC_TYPE to SQL_DATETIME or SQL_INTERVAL, respectively, sets SQL_DESC_CONCISE_TYPE to the concise identifier, and sets SQL_DESC_DATETIME_INTERVAL_CODE to the corresponding datetime or interval subcode.

    • 根据ParameterType的需要,设置一个或多个 SQL_DESC_LENGTH、SQL_DESC_PRECISION 和 SQL_DESC_DATETIME_INTERVAL_PRECISION。Sets one or more of SQL_DESC_LENGTH, SQL_DESC_PRECISION, and SQL_DESC_DATETIME_INTERVAL_PRECISION, as appropriate for ParameterType.

    • 将 SQL_DESC_SCALE 设置为DecimalDigits的值。Sets SQL_DESC_SCALE to the value of DecimalDigits.

如果对SQLBindParameter的调用失败,则它将在 APD 中设置的描述符字段的内容是未定义的,且 APD 的 "SQL_DESC_COUNT" 字段不变。If the call to SQLBindParameter fails, the content of the descriptor fields that it would have set in the APD are undefined, and the SQL_DESC_COUNT field of the APD is unchanged. 此外,IPD 中相应记录的 "SQL_DESC_LENGTH"、"SQL_DESC_PRECISION"、"SQL_DESC_SCALE" 和 "SQL_DESC_TYPE" 字段未定义,并且 IPD 的 "SQL_DESC_COUNT" 字段保持不变。In addition, the SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, and SQL_DESC_TYPE fields of the appropriate record in the IPD are undefined and the SQL_DESC_COUNT field of the IPD is unchanged.

与 SQLSetParam 的调用之间的转换Conversion of Calls to and from SQLSetParam

当 ODBC 1.0 应用程序调用 ODBC 3 中的SQLSetParam时。x驱动程序,ODBC 3。x驱动程序管理器按下表所示映射调用。When an ODBC 1.0 application calls SQLSetParam in an ODBC 3.x driver, the ODBC 3.x Driver Manager maps the call as shown in the following table.

由 ODBC 1.0 应用程序调用Call by ODBC 1.0 application 调用 ODBC 3。x驱动程序Call to ODBC 3.x driver
SQLSetParam (StatementHandle、ParameterNumber、ValueType、ParameterType、LengthPrecision、ParameterScale、ParameterValuePtr、StrLen_or_IndPtr);SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); SQLBindParameter (StatementHandle、ParameterNumber、SQL_PARAM_INPUT_OUTPUT、ValueType、ParameterType、 ColumnSizeDecimalDigits、ParameterValuePtr、SQL_SETPARAM_VALUE_MAX、StrLen_or_IndPtr);SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr);

代码示例Code Example

在下面的示例中,应用程序准备 SQL 语句,以便将数据插入 ORDERS 表。In the following example, an application prepares an SQL statement to insert data into the ORDERS table. 对于语句中的每个参数,应用程序会调用SQLBindParameter来指定 ODBC C 数据类型和参数的 SQL 数据类型,并将缓冲区绑定到每个参数。For each parameter in the statement, the application calls SQLBindParameter to specify the ODBC C data type and the SQL data type of the parameter, and to bind a buffer to each parameter. 对于每个数据行,应用程序将数据值分配给每个参数,并调用SQLExecute来执行该语句。For each row of data, the application assigns data values to each parameter and calls SQLExecute to execute the statement.

下面的示例假设计算机上有一个名为 Northwind 的 ODBC 数据源,该数据源与 Northwind 数据库相关联。The following sample assumes that you have an ODBC data source on your computer called Northwind that is associated with the Northwind database.

有关更多代码示例,请参阅SQLBulkOperations 函数SQLProcedures 函数SQLPutData 函数SQLSetPos 函数For more code examples, see SQLBulkOperations Function, SQLProcedures Function, SQLPutData Function, and SQLSetPos Function.

// SQLBindParameter_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define EMPLOYEE_ID_LEN 10  
  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLSMALLINT sCustID;  
  
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];  
SQL_DATE_STRUCT dsOrderDate;  
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);  
   retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);  
   retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);  
  
   strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");  
   sCustID = 5;  
   dsOrderDate.year = 2006;  
   dsOrderDate.month = 3;  
   dsOrderDate.day = 17;  
  
   retcode = SQLExecute(hstmt);  
}  

代码示例Code Example

在下面的示例中,应用程序使用命名参数执行 SQL Server 存储过程。In the following example, an application executes a SQL Server stored procedure using a named parameter.

// SQLBindParameter_Function_2.cpp  
// compile with: ODBC32.lib  
// sample assumes the following stored procedure:  
// use northwind  
// DROP PROCEDURE SQLBindParameter  
// GO  
//   
// CREATE PROCEDURE SQLBindParameter @quote int  
// AS  
// delete from orders where OrderID >= @quote  
// GO  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
SQLHDESC hIpd = NULL;  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLCHAR szQuote[50] = "100084";  
SQLINTEGER cbValue = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);  
   retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
   retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
   retcode = SQLExecute(hstmt);  
}  
有关以下方面的信息For information about 请参阅See
在语句中返回有关参数的信息Returning information about a parameter in a statement SQLDescribeParam 函数SQLDescribeParam Function
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
释放语句的参数缓冲区Releasing parameter buffers on the statement SQLFreeStmt 函数SQLFreeStmt Function
返回语句参数的数目Returning the number of statement parameters SQLNumParams 函数SQLNumParams Function
返回要为其发送数据的下一个参数Returning the next parameter to send data for SQLParamData 函数SQLParamData Function
指定多个参数值Specifying multiple parameter values SQLParamOptions 函数SQLParamOptions Function
在执行时发送参数数据Sending parameter data at execution time SQLPutData 函数SQLPutData Function

另请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件 ODBC Header Files
使用 SQLGetData 检索输出参数Retrieving Output Parameters Using SQLGetData