Функция SQLBindParameterSQLBindParameter 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 поддерживает привязку к типу данных Юникода C, даже если базовый драйвер не поддерживает данные в Юникоде.SQLBindParameter supports binding to a Unicode C data type, even if the underlying driver does not support Unicode data.

Примечание

Эта функция заменяет функцию SQLSETPARAMODBC 1,0.This 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

статеменсандлеStatementHandle
Входной Маркер инструкции.[Input] Statement handle.

параметернумберParameterNumber
Входной Номер параметра, упорядоченный последовательно в порядке возрастания параметров, начиная с 1.[Input] Parameter number, ordered sequentially in increasing parameter order, starting at 1.

инпутаутпуттипеInputOutputType
Входной Тип параметра.[Input] The type of the parameter. Дополнительные сведения см. в разделе "аргументинпутаутпуттипе " в разделе "Комментарии".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-bit.If your application will run on a 64-bit Windows operating system, see ODBC 64-Bit Information.

деЦималдигитсDecimalDigits
Входной Десятичные разряды столбца или выражения соответствующего маркера параметра.[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.

параметервалуептрParameterValuePtr
[Отложенный вход] Указатель на буфер для данных параметра.[Deferred Input] A pointer to a buffer for the parameter's data. Дополнительные сведения см. в разделе "аргументпараметервалуептр " в разделе "Комментарии".For more information, see "ParameterValuePtr Argument" in "Comments."

BufferLengthBufferLength
[Входные и выходные данные] Длина буфера параметервалуептр в байтах.[Input/Output] Length of the ParameterValuePtr buffer in bytes. Дополнительные сведения см. в разделе "аргументBufferLength " в разделе "Комментарии".For more information, see "BufferLength Argument" in "Comments."

Если приложение будет работать в 64-разрядной операционной системе, см. сведения о ODBC 64-bit.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, связанное значение SQLSTATE может быть получено путем вызова SQLGetDiagRec с параметром handletype SQL_HANDLE_STMT и маркером статеменсандле.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. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые функцией SQLBindParameter , и объясняется каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATE, возвращаемым диспетчером драйверов.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 DescriptionDescription
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. Обратите внимание, что эта ошибка может возвращаться SQLExecDirect, SQLExecuteили SQLPutData во время выполнения, а не 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) значение, указанное для аргумента параметернумбер , было меньше 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. Сообщение об ошибке, возвращаемое функцией SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.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 Недопустимый тип данных SQLInvalid SQL data type Значение, указанное для аргумента ParameterType , не является допустимым идентификатором типа данных SQL ODBC или идентификатором типа данных 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) аргумент параметервалуептр был пустым указателем, аргумент StrLen_or_IndPtr был пустым указателем, а аргумент инпутаутпуттипе не SQL_PARAM_OUTPUT.(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, где аргумент параметервалуептр был пустым указателем, тип C — char или binary, а BufferLength (кбвалуемакс) больше 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) вызвана асинхронно исполняемая функция для маркера соединения, связанного с статеменсандле.(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.

(DM) SQLExecute, SQLExecDirectили SQLMoreResults были вызваны для статеменсандле и возвращены 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) была вызвана асинхронно исполняемая функция для статеменсандле и все еще выполнялась при вызове этой функции.(DM) An asynchronously executing function was called for the StatementHandle and was still executing when this function was called.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperationsили SQLSetPos были вызваны для статеменсандле и возвращены 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.)

Значение, указанное для аргумента деЦималдигитс , находится вне диапазона значений, поддерживаемых источником данных для столбца типа данных SQL, указанного аргументом ParameterType .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. (См. Описание поля SQL_DESC_DATA_PTR в SQLSetDescField.)(See the description of the SQL_DESC_DATA_PTR field in SQLSetDescField.)
HY104HY104 Недопустимое значение точности или масштабаInvalid precision or scale value Значение, указанное для аргумента ColumnSize или деЦималдигитс , находится вне диапазона значений, поддерживаемых источником данных для столбца типа данных SQL, указанного аргументом ParameterType .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) значение, указанное для аргумента инпутаутпуттипе , недопустимо.(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) Дополнительные сведения о состоянии SUSPENDED см. в разделе функция 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 SQL для версии ODBC, поддерживаемой драйвером, но не поддерживаемой драйвером или источником данных.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

и все типы данных интервала C, перечисленные в разделе типы данных c в приложении D: типы данных.and all the interval C data types listed in C Data Types in Appendix D: Data Types.

Драйвер поддерживает только версии ODBC до 3,50, а аргумент ValueType SQL_C_GUID.The 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) драйвер, связанный с статеменсандле , не поддерживает функцию.(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 , чтобы задать SQL_DESC_COUNT в поле заголовка APD значение 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 Argument

Если параметернумбер в вызове SQLBindParameter больше, чем значение SQL_DESC_COUNT, вызывается SQLSetDescField , чтобы увеличить значение SQL_DESC_COUNT в параметернумбер.If 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 Argument

Аргумент инпутаутпуттипе указывает тип параметра.The InputOutputType argument specifies the type of the parameter. Этот аргумент задает SQL_DESC_PARAMETER_TYPE поле для IPD.This argument sets the SQL_DESC_PARAMETER_TYPE field of the IPD. Все параметры в инструкциях SQL, которые не вызывают процедуры, такие как инструкции INSERT , являются *входными параметрами * **.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.)

Аргумент инпутаутпуттипе может иметь одно из следующих значений: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. Например, параметры в инструкции INSERT в значениях сотрудников (?,?,?) являются входными параметрами, тогда как параметры в {call аддемп (?,?,?)} могут быть, но не обязательно являются входными параметрами.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.

    При выполнении инструкции драйвер отправляет данные для параметра в источник данных. *буфер параметервалуептр должен содержать допустимое входное значение, либо буфер *StrLen_or_IndPtr должен содержать SQL_NULL_DATA, SQL_DATA_AT_EXEC или результат макроса SQL_LEN_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.

    Если приложение не может определить тип параметра в вызове процедуры, оно устанавливает для инпутаутпуттипе значение 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 жетемпдепт (?)} является входным и выходным параметром, который принимает имя сотрудника и возвращает имя отдела сотрудника.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.

    При выполнении инструкции драйвер отправляет данные для параметра в источник данных. * параметервалуептр должен содержать допустимое входное значение, либо *буфер StrLen_or_IndPtr должен содержать SQL_NULL_DATA, SQL_DATA_AT_EXEC или результат макроса SQL_LEN_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 вызывает SQLSetParam в драйвере ODBC 2,0, диспетчер драйверов преобразует его в вызов SQLBindParameter , в котором аргумент инпутаутпуттипе имеет значение 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. Параметр помечает возвращаемое значение процедуры или выходного параметра в процедуре; в любом случае они называются выходными параметрами.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 жетнекстемпид} является выходным параметром, который ВОЗВРАЩАЕТ следующий идентификатор сотрудника.For example, the parameter in {?=call GetNextEmpID} is an output parameter that returns the next employee ID.

    После выполнения инструкции драйвер возвращает данные для параметра в приложение, если только аргументы параметервалуептр и StrLen_or_IndPtr не являются пустыми указателями, в этом случае драйвер отклоняет выходное значение.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. Если источник данных не возвращает значение для выходного параметра, драйвер устанавливает буфер *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. BufferLength игнорируется, так как длина буфера определяется при вызове SQLGetData.BufferLength 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. Параметервалуептр может быть любым значением указателя, отличным от NULL, которое будет возвращено метод SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с помощью параметервалуептр для входных и выходных данных.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. То же, что и SQL_PARAM_INPUT_OUTPUT_STREAM, для выходного параметра.Same as SQL_PARAM_INPUT_OUTPUT_STREAM, for an output parameter.\ *Во входных данных StrLen_or_IndPtr игнорируется.\ *StrLen_or_IndPtr is ignored at input.

В следующей таблице перечислены различные сочетания инпутаутпуттипе и *StrLen_or_IndPtr.The following table lists different combinations of InputOutputType and *StrLen_or_IndPtr:

инпутаутпуттипеInputOutputType *StrLen_or_IndPtr*StrLen_or_IndPtr РезультатOutcome Замечание на Параметервалуептр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 Параметервалуептр может быть любым значением указателя, которое будет возвращено метод SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с помощью параметервалуептр.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 Не 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 is the address of the input buffer.
SQL_PARAM_OUTPUTSQL_PARAM_OUTPUT Во входных данных игнорируется.Ignored at input. Буфер привязки выводаOutput bound buffer Параметервалуептр — это адрес выходного буфера.ParameterValuePtr is the address of the output buffer.
SQL_PARAM_OUTPUT_STREAMSQL_PARAM_OUTPUT_STREAM Во входных данных игнорируется.Ignored at input. Потоковый выводStreamed output Параметервалуептр может быть любым значением указателя, которое будет возвращено метод SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с помощью параметервалуептр.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 Параметервалуептр — это адрес выходного буфера, который также будет возвращен метод SQLParamData в качестве определяемого пользователем маркера, значение которого было передано в параметервалуептр.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 Не 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 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 Параметервалуептр может быть любым значением указателя, отличным от NULL, которое будет возвращено метод SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с помощью параметервалуептр для входных и выходных данных.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 разрешены, когда приложение привязывает параметр Output или Input-Output к потоковой передаче.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.

Аргумент ValueTypeValueType Argument

Аргумент ValueType задает тип данных C для параметра.The ValueType argument specifies the C data type of the parameter. Этот аргумент задает поля SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE объекта APD.This argument sets the SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, and SQL_DESC_DATETIME_INTERVAL_CODE fields of the APD. Это должно быть одно из значений в разделе " типы данных C " приложения г: типы данных.This must be one of the values in the C Data Types section of Appendix D: Data Types.

Если аргумент ValueType является одним из типов данных интервала, поле SQL_DESC_TYPE записи параметернумбер APD имеет значение SQL_INTERVAL, поле SQL_DESC_CONCISE_TYPE APD имеет тип данных краткая интервал, а в поле SQL_DESC_DATETIME_INTERVAL_CODE записи параметернумбер задается подкод для определенного типа данных Interval.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. (См. приложение г. типы данных.) Начальная точность по умолчанию (2) и интервал в секундах (6), заданная в полях SQL_DESC_DATETIME_INTERVAL_PRECISION и SQL_DESC_PRECISION APD, соответственно, используются для данных.(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. Если точность по умолчанию не подходит, приложение должно явно задать поле дескриптора путем вызова SQLSetDescField или SQLSetDescRec.If either default precision is not appropriate, the application should explicitly set the descriptor field by a call to SQLSetDescField or SQLSetDescRec.

Если аргумент ValueType является одним из типов данных DateTime, то поле SQL_DESC_TYPE записи параметернумбер APD имеет значение SQL_DATETIME, в поле SQL_DESC_CONCISE_TYPE записи параметернумбер для APD задается тип данных Краткая дата и время, а в поле 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. (См. приложение г. типы данных.)(See Appendix D: Data Types.)

Если аргумент ValueType имеет тип данных SQL_C_NUMERIC, точность по умолчанию (определяемая драйвером) и масштаб по умолчанию (0), заданный в полях SQL_DESC_PRECISION и SQL_DESC_SCALE APD, используются для данных.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. Если точность или масштаб по умолчанию не подходят, приложение должно явно задать поле дескриптора путем вызова SQLSetDescField или SQLSetDescRec.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 указывает, что значение параметра должно быть передано из типа данных C по умолчанию для типа данных SQL, указанного параметром ParameterType.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. Дополнительные сведения о типах данных см. в разделе Типы данных C в ODBC.For more information, see C Data Types in ODBC.

Дополнительные сведения см. в разделе Типы данных 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

Это должно быть одно из значений, перечисленных в разделе типы данных SQL приложения D: типы данных, или это значение должно быть зависящим от драйвера.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. Этот аргумент задает SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE поля IPD.This argument sets the SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, and SQL_DESC_DATETIME_INTERVAL_CODE fields of the IPD.

Если аргумент ParameterType является одним из идентификаторов DateTime, поле SQL_DESC_TYPE IPD имеет значение SQL_DATETIME, SQL_DESC_CONCISE_TYPE поле IPD имеет тип данных 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 является одним из идентификаторов интервалов, в поле SQL_DESC_TYPE IPD задается значение SQL_INTERVAL, в поле SQL_DESC_CONCISE_TYPE IPD задается сокращенный тип данных интервала SQL, а в поле SQL_DESC_DATETIME_INTERVAL_CODE IPD задается соответствующий код интервала.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. В поле SQL_DESC_DATETIME_INTERVAL_PRECISION IPD задается начальная точность интервала, а для поля 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. Дополнительные сведения о любом из этих полей см. в разделе SQLSetDescField.For more information about any of these fields, see SQLSetDescField.

Если аргумент ValueType является SQL_NUMERIC типом данных, точность по умолчанию (определяемая драйвером) и масштаб по умолчанию (0), заданный в полях SQL_DESC_PRECISION и SQL_DESC_SCALE IPD, используются для данных.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. Если точность или масштаб по умолчанию не подходят, приложение должно явно задать поле дескриптора путем вызова SQLSetDescField или SQLSetDescRec.If the default precision or scale is not appropriate, the application should explicitly set the descriptor field by a call to SQLSetDescField or SQLSetDescRec.

Сведения о преобразовании данных см. в разделе Преобразование данных из 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, в поле SQL_DESC_LENGTH IPD задается значение 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. (Дополнительные сведения см. в разделе размер столбца, десятичные цифры, длина октета и размер отображаемого раздела в приложении г: типы данных.)(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, поле SQL_DESC_PRECISION для IPD задается в значении 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.

Дополнительные сведения см. в разделе "передача значений параметров" и SQL_DATA_AT_EXEC в "аргументеStrLen_or_IndPtr ".For more information, see "Passing Parameter Values" and SQL_DATA_AT_EXEC in "StrLen_or_IndPtr Argument."

ДеЦималдигитс, аргумент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, поле SQL_DESC_PRECISION для IPD устанавливается в значение деЦималдигитс.If 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, для поля SQL_DESC_SCALE IPD устанавливается значение деЦималдигитс.If ParameterType is SQL_NUMERIC or SQL_DECIMAL, the SQL_DESC_SCALE field of the IPD is set to DecimalDigits. Для всех остальных типов данных аргумент деЦималдигитс игнорируется.For all other data types, the DecimalDigits argument is ignored.

Параметервалуептр, аргументParameterValuePtr Argument

Аргумент параметервалуептр указывает на буфер, который при вызове SQLExecute или SQLExecDirect содержит фактические данные для параметра.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. Этот аргумент задает SQL_DESC_DATA_PTR поле APD.This argument sets the SQL_DESC_DATA_PTR field of the APD. Приложение может установить для аргумента параметервалуептр указатель null, если * *StrLen_or_IndPtr* SQL_NULL_DATA или SQL_DATA_AT_EXEC.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, то параметервалуептр является значением указателя, определяемым приложением и связанным с параметром.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. Например, параметервалуептр может быть ненулевым токеном, таким как номер параметра, указатель на данные или указатель на структуру, которую приложение использовало для привязки входных параметров.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. Однако обратите внимание, что если параметр является входным или выходным параметром, параметервалуептр должен быть указателем на буфер, в котором будет храниться выходное значение.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, вместе с аргументом параметервалуептр .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. Например, параметервалуептр может указывать на массив значений, и приложение может использовать значение, на которое указывает, 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.

Если аргумент инпутаутпуттипе имеет SQL_PARAM_INPUT_OUTPUT или SQL_PARAM_OUTPUT, параметервалуептр указывает на буфер, в котором драйвер возвращает выходное значение.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. Если процедура возвращает один или несколько результирующих наборов, не *гарантируется, что буфер параметервалуептр будет установлен до тех пор, пока не будут обработаны все результирующие наборы или количество строк.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. Вызов SQLCloseCursor или SQLFreeStmt с параметром SQL_CLOSE приведет к отмене этих значений.Calling SQLCloseCursor or SQLFreeStmt with an Option of SQL_CLOSE will cause these values to be discarded.

Если значение в атрибуте оператора SQL_ATTR_PARAMSET_SIZE больше 1, параметервалуептр указывает на массив.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 задает *длину буфера параметервалуептр (если это единственный элемент) или длину элемента в *массиве параметервалуептр (если значение в атрибуте оператора 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). Этот аргумент задает SQL_DESC_OCTET_LENGTH поле записи для APD.This argument sets the SQL_DESC_OCTET_LENGTH record field of the APD. Если в приложении указано несколько значений, BufferLength используется для определения местоположения значений в массиве *параметервалуептр , как на входе, так и на выходе.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, данные в * параметервалуептр усекаются до BufferLength меньше длины символа завершения, равного 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, данные в * параметервалуептр усекаются до 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. Длина * параметервалуептр (если он является единственным элементом) или длина элемента в *массиве параметервалуептр (если приложение вызывает 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 вызывает SQLSetParam в ODBC 3. драйвер 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, способ, которым приложение определяет длину буферапараметервалуептр , чтобы драйвер мог вернуть символьные или двоичные данные, и способ, которым приложение отправляет в драйвер массив значений символьных или двоичных параметров, определяется драйвером.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 указывает на буфер, который при вызове SQLExecute или SQLExecDirect содержит один из следующих элементов.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.)

  • Длина значения параметра, хранящегося в *параметервалуептр.The length of the parameter value stored in *ParameterValuePtr. Этот параметр игнорируется, за исключением символьных или двоичных данных C.This is ignored except for character or binary C data.

  • SQL_NTS.SQL_NTS. Значение параметра является строкой, завершающейся нулем.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, а затем только в том случае, если аргумент инпутаутпуттипе имеет значение 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. Если * StrLen_or_IndPtr имеет SQL_DEFAULT_PARAM, аргументы ValueType, ParameterType, ColumnSize, деЦималдигитс, BufferLengthи параметервалуептр игнорируются для входных параметров и используются только для определения значения выходного параметра для входных и выходных параметров.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 (length).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 или длинный тип данных, зависящий от источника данных, а драйвер возвращает значение "Y" для SQL_NEED_LONG_DATA_LENного типа сведений в SQLGetInfo, то Длина — это число байтов данных, отправляемых для параметра. в противном случае Длина должна быть неотрицательным значением и игнорироваться.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.

    Например, чтобы указать, что 10 000 байт данных будут отправляться с помощью SQLPutData в одном или нескольких вызовах, для параметра 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, а символьные и двоичные данные завершаются нулем.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. Если инпутаутпуттипе имеет значение SQL_PARAM_OUTPUT или SQL_PARAM_OUTPUT_STREAM и StrLen_or_IndPtr являются пустыми указателями, драйвер отклоняет выходное значение.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.

Примечание

Разработчикам приложений настоятельно не рекомендуется указывать указатель null для StrLen_or_IndPtr , если тип данных параметра — SQL_C_BINARY.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.

Если аргумент инпутаутпуттипе имеет значение SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM или SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr указывает на буфер, в котором драйвер возвращает SQL_NULL_DATA, число байтов, доступных для возврата в * параметервалуептр (за исключением байта завершающего нуль символа символьных данных) или 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

Приложение может передать значение для параметра либо в *буфер параметервалуептр , либо с помощью одного или нескольких вызовов 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 для каждого параметра, чтобы привязать буферы для значения параметра (аргументапараметервалуептр ) и длины или индикатора (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). Для параметров, выполняемых при выполнении данных, параметервалуептр — это определяемое приложением значение указателя, например номер параметра или указатель на данные.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. Помещает значения для входных и выходных параметров в *буферах параметервалуептр иStrLen_or_IndPtr *:Places values for input and input/output parameters in the *ParameterValuePtr and *StrLen_or_IndPtr buffers:

    • Для обычных параметров приложение помещает значение параметра в *буфер параметервалуептр и длину этого значения в буфер *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 (length) макроса (при вызове драйвера 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. Вызывает SQLExecute или SQLExecDirect для выполнения инструкции 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 для получения определяемого приложением значения, указанного в аргументе параметервалуептр SQLBindParameter , для первого обрабатываемого параметра обработки данных.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, для которых данные будут отправляться с помощью SQLPutData при выполнении инструкции с SQLExecDirect или SQLExecute.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 , является значением указателя, передаваемым в SQLBindParameter в аргументе параметервалуептр .The value returned by SQLParamData is a pointer value passed to SQLBindParameter in the ParameterValuePtr argument. Столбцы "данные в ходе выполнения" — это столбцы в наборе строк, для которых данные будут отправляться с помощью SQLPutData при обновлении или добавлении строки с помощью SQLBulkOperations или при обновлении с помощью функции SQLSetPos.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 , является адресом строки в буфере *таржетвалуептр (задается вызовом 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, требуется более одного вызова. несколько вызовов SQLPutData для одного и того же параметра разрешены только при отправке символьных данных c в столбец с типом данных символьного, двоичного или конкретного источника данных, а также при отправке двоичных данных 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 и значение, определяемое приложением для следующего обрабатываемого параметра data-by-Execution.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, которое может возвращаться функцией, используемой для выполнения инструкции (SQLExecDirect или SQLExecute).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).

      Выходные значения для всех входных и выходных или выходных параметров доступны в *буферах параметервалуептр и *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.

Вызов SQLExecute или SQLExecDirect помещает инструкцию в состояние SQL_NEED_DATA.Calling SQLExecute or SQLExecDirect puts the statement in an SQL_NEED_DATA state. На этом этапе приложение может вызывать только SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, метод SQLParamDataили SQLPutData с инструкцией или с маркером соединения , связанным с инструкцией.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). Инструкция оставляет SQL_NEED_DATA состояние, когда метод SQLParamData или SQLPutData возвращает ошибку, метод 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 , а драйверу по-прежнему требуются данные для параметров выполнения, драйвер отменяет выполнение инструкции. Затем приложение может снова вызвать SQLExecute или SQLExecDirect .If 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

Когда приложение устанавливает инпутаутпуттипе в 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 в ответ на вызов следующих функций: SQLMoreResults, SQLExecuteи SQLExecDirect.When 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. Массивы параметров не могут использоваться с оператором Update, в котором находится текущая инструкция.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. Параметр SQL_PARAM_ARRAY_ROW_COUNTS в SQLGetInfo указывает, доступны ли счетчики строк для каждого набора параметров (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).

Параметр SQL_PARAM_ARRAY_SELECTS в SQLGetInfo указывает, доступен ли результирующий набор для каждого набора параметров (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, поля SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR объекта APD должны указывать на массивы.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.

Поле SQL_DESC_ROWS_PROCESSED_PTR APD указывает на буфер, содержащий количество обработанных параметров, включая наборы ошибок.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. При использовании массивов параметров значение, на которое указывает SQL_DESC_ROWS_PROCESSED_PTR поле APD, заполняется, даже если функция настройки возвращает SQL_ERROR.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, значение, на которое указывает SQL_DESC_ROWS_PROCESSED_PTR поле APD, задается набором обрабатываемых параметров.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. Вызывает SQLBindParameter со следующими аргументами:Calls 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 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.

Дополнительные сведения об использовании этих сведений см. в подразделе «аргумент Параметервалуептр» в «комментариях» ниже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. При использовании оператора sizeof в ANSI C это поведение гарантировано.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 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.

Дополнительные сведения об использовании этих сведений см. в подразделе «аргументпараметервалуептр » далее в этом подразделе.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. Если драйвер реализует массивы параметров как пакеты, приложение может использовать поле заголовка SQL_DESC_ARRAY_STATUS_PTR IPD для определения того, какой параметр инструкции SQL или какой параметр в массиве параметров привел к возврату ошибки SQLExecDirect или SQLExecute .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. Число элементов в массиве определяется полем SQL_DESC_ARRAY_SIZE заголовка в APD, которое может быть задано атрибутом инструкции 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.

Примечание

Поле заголовка SQL_DESC_ARRAY_STATUS_PTR в APD используется для пропуска параметров.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."

Когда SQLExecute или SQLExecDirect возвращает SQL_ERROR, элементы массива, на которые указывает поле SQL_DESC_ARRAY_STATUS_PTR в IPD, будут содержать 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 введено, если параметр не использовался из-за ошибки в более раннем параметре, который вынужден прервать SQLExecute или SQLExecDirect .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 параметров и произошла ошибка при выполнении фортиес набора параметров, вызвавших прерывание SQLExecute или SQLExecDirect , то SQL_PARAM_UNUSED в массиве состояний для параметров 41 – 50.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. x.ODBC 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. Буфер, на который указывает аргумент пиров объекта SQLParamOptions , содержал номер строки ошибки.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.

Когда SQLExecute или SQLExecDirect возвращает значение до завершения обработки всех наборов параметров в массиве параметров, например при возвращении 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. Расположение, на которое указывает поле SQL_DESC_ROWS_PROCESSED_PTR в IPD, содержит номер строки в массиве параметров, вызвавший 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

Поле SQL_DESC_ARRAY_STATUS_PTR APD (как задано атрибутом 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 , чтобы задать поле заголовка SQL_DESC_ARRAY_STATUS_PTR APD, чтобы оно указывало на массив значений склусмаллинт, содержащих сведения о состоянии.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. Это поле также может быть задано путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAM_OPERATION_PTR, который позволяет приложению устанавливать поле без получения дескриптора дескриптора.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. Задайте для каждого элемента массива, определенного SQL_DESC_ARRAY_STATUS_PTR полем APD, одно из двух значений: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. Вызовите SQLExecDirect или SQLExecute , чтобы выполнить подготовленную инструкцию.Call SQLExecDirect or SQLExecute to execute the prepared statement.

К массиву, определяемому полем SQL_DESC_ARRAY_STATUS_PTR APD, применяются следующие правила.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.

Приложение может задать SQL_DESC_ARRAY_STATUS_PTR поле в APD, чтобы оно указывало на тот же массив, на который указывает поле SQL_DESC_ARRAY_STATUS_PTR в IRD.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

Повторная привязка параметров особенно полезна, если в приложении имеется настройка буферной области, которая может содержать много параметров, но вызов SQLExecDirect или SQLExecute использует только несколько параметров.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.

Поле заголовка SQL_DESC_BIND_OFFSET_PTR в APD указывает на смещение привязки.The SQL_DESC_BIND_OFFSET_PTR header field in the APD points to the binding offset. Если поле не равно null, драйвер отменяет ссылку на указатель и, если ни одно из значений в полях SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR не является пустым указателем, добавляет значение разыменования в эти поля дескриптора. записи во время выполнения.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 является указателем на смещение, а не само смещение, приложение может изменить смещение напрямую, не требуя вызова SQLSetDescField или SQLSetDescRec для изменения поля дескриптора.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. Поле SQL_DESC_BIND_OFFSET_PTR АРД может быть задано вызовом SQLSetDescField или вызовом SQLSetStmtAttrс фаттрибуте SQL_ATTR_PARAM_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

Привязка параметра определяется полями Апдс и ИПДС.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. Это происходит, когда АРД, связанный с инструкцией, явным образом выделяется и также связывается с другими инструкциями.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 , чтобы получить поле SQL_DESC_COUNT APD, и если значение аргумента ColumnNumber превышает значение SQL_DESC_COUNT, вызывает SQLSetDescField , чтобы увеличить значение SQL_DESC_COUNT до columnNumber.Calls 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 в соответствующий код даты и времени.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 для получения поля SQL_DESC_COUNT IPD. Если значение аргумента ColumnNumber превышает значение SQL_DESC_COUNT, вызывает SQLSetDescField , чтобы увеличить значение SQL_DESC_COUNT до columnNumber.Calls 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 в соответствующий код даты и времени.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.

    • Задает один или несколько SQL_DESC_LENGTH, SQL_DESC_PRECISION и SQL_DESC_DATETIME_INTERVAL_PRECISION в соответствии с подходящим для ParameterType.Sets one or more of SQL_DESC_LENGTH, SQL_DESC_PRECISION, and SQL_DESC_DATETIME_INTERVAL_PRECISION, as appropriate for ParameterType.

    • Задает SQL_DESC_SCALE значение деЦималдигитс.Sets SQL_DESC_SCALE to the value of DecimalDigits.

Если вызов SQLBindParameter завершается ошибкой, содержимое полей дескриптора, которое было бы задано в APD, не определено, а SQL_DESC_COUNT поле APD не изменяется.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. Кроме того, поля SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE и SQL_DESC_TYPE соответствующей записи IPD не определены, и поле SQL_DESC_COUNT IPD не изменяется.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 вызывает SQLSetParam в ODBC 3. драйвер 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,0Call by ODBC 1.0 application Вызов ODBC 3. драйвер xCall to ODBC 3.x driver
SQLSetParam (Статеменсандле, Параметернумбер, ValueType, ParameterType, ЛенгспреЦисион, Параметерскале, Параметервалуептр, StrLen_or_IndPtr);SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); SQLBindParameter (Статеменсандле, Параметернумбер, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, деЦималдигитс, параметервалуептр, 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.

В следующем примере предполагается, что у вас есть источник данных ODBC на компьютере с именем Northwind, связанный с базой данных 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 Функция SQLDescribeParamSQLDescribeParam Function
Исполнение инструкции SQLExecuting an SQL statement Функция SQLExecDirectSQLExecDirect Function
Исполнение подготовленной инструкции SQLExecuting a prepared SQL statement Функция SQLExecuteSQLExecute 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 Функция SQLParamDataSQLParamData Function
Указание нескольких значений параметровSpecifying multiple parameter values Функция SQLParamOptionsSQLParamOptions Function
Отправка данных параметров во время выполненияSending parameter data at execution time SQLPutData, функцияSQLPutData Function

См. также:See Also

Справочник по API ODBC ODBC API Reference
Файлы заголовков ODBC ODBC Header Files
Получение выходных параметров с помощью метода SQLGetDataRetrieving Output Parameters Using SQLGetData