Función SQLBindParameter
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 2.0: ODBC
Resumen
SQLBindParameter enlaza un búfer a un marcador de parámetro en una instrucción SQL. SQLBindParameter admite el enlace a un tipo de datos Unicode C, aunque el controlador subyacente no admita datos Unicode.
Nota:
Esta función reemplaza a la función SQLSetParam de ODBC 1.0. Para obtener más información, vea "Comentarios".
Sintaxis
SQLRETURN SQLBindParameter(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT InputOutputType,
SQLSMALLINT ValueType,
SQLSMALLINT ParameterType,
SQLULEN ColumnSize,
SQLSMALLINT DecimalDigits,
SQLPOINTER ParameterValuePtr,
SQLLEN BufferLength,
SQLLEN * StrLen_or_IndPtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
ParameterNumber
[Entrada] Número de parámetro, ordenado secuencialmente en orden de aumento de parámetros, a partir de 1.
InputOutputType
[Entrada] Tipo del parámetro. Para obtener más información, vea "InputOutputType Argument" en "Comments".
ValueType
[Entrada] Tipo de datos C del parámetro . Para obtener más información, vea "ValueType Argument" en "Comments".
ParameterType
[Entrada] Tipo de datos SQL del parámetro . Para obtener más información, vea "ParameterType Argument" en "Comments".
ColumnSize
[Entrada] Tamaño de la columna o expresión del marcador de parámetro correspondiente. Para obtener más información, vea "ColumnSize Argument" en "Comments".
Si la aplicación se ejecutará en un sistema operativo Windows de 64 bits, consulte Información de 64 bits odbc.
DecimalDigits
[Entrada] Dígitos decimales de la columna o expresión del marcador de parámetro correspondiente. Para obtener más información sobre el tamaño de columna, vea Tamaño de columna, Dígitos decimales, Longitud del octeto de transferencia y Tamaño de visualización.
ParameterValuePtr
[Entrada diferida] Puntero a un búfer para los datos del parámetro. Para obtener más información, vea "ParameterValuePtr Argument" en "Comments".
BufferLength
[Entrada/salida] Longitud del búfer ParameterValuePtr en bytes. Para obtener más información, vea "BufferLength Argument" en "Comments".
Consulte Información de ODBC de 64 bits si la aplicación se ejecutará en un sistema operativo de 64 bits.
StrLen_or_IndPtr
[Entrada diferida] Puntero a un búfer para la longitud del parámetro. Para obtener más información, vea "StrLen_or_IndPtr Argument" en "Comments".
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLBindParameter devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLBindParameter y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.
| SQLSTATE | Error | Descripción |
|---|---|---|
| 01000 | Advertencia general | Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 07006 | Infracción de atributo de tipo de datos restringido | El tipo de datos identificado por el argumento ValueType no se puede convertir al tipo de datos identificado por el argumento ParameterType . Tenga en cuenta que SQLExecDirect, SQLExecute o SQLPutData pueden devolver este error en tiempo de ejecución, en lugar de SQLBindParameter. |
| 07009 | Índice de descriptor no válido | (DM) El valor especificado para el argumento ParameterNumber era menor que 1. |
| HY000 | Error general | Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa. |
| HY001 | Error de asignación de memoria | El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función. |
| HY003 | Tipo de búfer de aplicación no válido | El valor especificado por el argumento ValueType no era un tipo de datos de C válido ni SQL_C_DEFAULT. |
| HY004 | Tipo de datos SQL no válido | El valor especificado para el argumento ParameterType no era un identificador de tipo de datos SQL ODBC válido ni un identificador de tipo de datos SQL específico del controlador admitido por el controlador. |
| HY009 | Valor de argumento no válido | (DM) El argumento ParameterValuePtr era un puntero nulo, el argumento StrLen_or_IndPtr era un puntero nulo y el argumento InputOutputType no era SQL_PARAM_OUTPUT. (DM) SQL_PARAM_OUTPUT, donde el argumento ParameterValuePtr era un puntero nulo, el tipo C era char o binario, y bufferLength (cbValueMax) era mayor que 0. |
| HY010 | Error de secuencia de funciones | (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a SQLBindParameter . (DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para statementHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) Se llamó a una función de ejecución asincrónica para statementHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para el statementHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. |
| HY013 | Error de administración de memoria | No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY021 | Información de descriptor incoherente | La información del descriptor activada durante una comprobación de coherencia no era coherente. (Consulte la sección "Comprobaciones de coherencia" en SQLSetDescField). El valor especificado para el argumento DecimalDigits estaba fuera del intervalo de valores admitidos por el origen de datos para una columna del tipo de datos SQL especificado por el argumento ParameterType . |
| HY090 | Longitud de búfer o cadena no válida | (DM) El valor de BufferLength era menor que 0. (Consulte la descripción del campo SQL_DESC_DATA_PTR en SQLSetDescField). |
| HY104 | Precisión o valor de escala no válidos | El valor especificado para el argumento ColumnSize o DecimalDigits estaba fuera del intervalo de valores admitidos por el origen de datos para una columna del tipo de datos SQL especificado por el argumento ParameterType . |
| HY105 | Tipo de parámetro no válido | (DM) El valor especificado para el argumento InputOutputType no era válido. (Vea "Comentarios"). |
| HY117 | Conectar ion se suspende debido al estado de transacción desconocido. Solo se permiten las funciones de desconexión y solo lectura. | (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran. |
| HYC00 | Característica opcional no implementada | El controlador o el origen de datos no admiten la conversión especificada por la combinación del valor especificado para el argumento ValueType y el valor específico del controlador especificado para el argumento ParameterType. El valor especificado para el argumento ParameterType era un identificador de tipo de datos ODBC SQL válido para la versión de ODBC compatible con el controlador, pero no era compatible con el controlador o el origen de datos. El controlador solo admite ODBC 2.x y el argumento ValueType era uno de los siguientes: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT y todos los tipos de datos de intervalo C enumerados en Tipos de datos de C en el Apéndice D: Tipos de datos. El controlador solo admite versiones ODBC anteriores a la versión 3.50 y el argumento ValueType se SQL_C_GUID. |
| HYT01 | Se ha agotado el tiempo de espera de la conexión. | El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece mediante SQLSet Conectar Attr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | El controlador no admite esta función | (DM) El controlador asociado a StatementHandle no admite la función . |
Comentarios
Una aplicación llama a SQLBindParameter para enlazar cada marcador de parámetro en una instrucción SQL. Los enlaces permanecen en vigor hasta que la aplicación llama a SQLBindParameter de nuevo, llama a SQLFreeStmt con la opción SQL_RESET_PARAMS, o llama a SQLSetDescField para establecer el campo de encabezado SQL_DESC_COUNT del APD en 0.
Para obtener más información sobre los parámetros, consulte Parámetros de instrucciones. Para obtener más información sobre los tipos de datos de parámetros y los marcadores de parámetros, vea Parameter Data Types and Parameter Markers in Apéndice C: Sql Grammar.
ParameterNumber (argumento)
Si ParameterNumber en la llamada a SQLBindParameter es mayor que el valor de SQL_DESC_COUNT, se llama a SQLSetDescField para aumentar el valor de SQL_DESC_COUNT a ParameterNumber.
Argumento InputOutputType
El argumento InputOutputType especifica el tipo del parámetro . Este argumento establece el campo SQL_DESC_PARAMETER_TYPE del IPD. Todos los parámetros de las instrucciones SQL que no llaman a procedimientos, como instrucciones INSERT, son parámetros de entrada. Los parámetros de las llamadas a procedimiento pueden ser parámetros de entrada, entrada/salida o salida. (Una aplicación llama a SQLProcedureColumns para determinar el tipo de un parámetro en una llamada a procedimiento; se supone que los parámetros cuyo tipo no se puede determinar son parámetros de entrada).
El argumento InputOutputType es uno de los valores siguientes:
SQL_PARAM_INPUT. El parámetro marca un parámetro en una instrucción SQL que no llama a un procedimiento, como una instrucción INSERT , o marca un parámetro de entrada en un procedimiento. Por ejemplo, los parámetros de INSERT INTO Employee VALUES (?, ?, ?) son parámetros de entrada, mientras que los parámetros de {call AddEmp(?, ?, ?)} pueden ser, pero no necesariamente, parámetros de entrada.
Cuando se ejecuta la instrucción , el controlador envía datos para el parámetro al origen de datos; El búfer *ParameterValuePtr debe contener un valor de entrada válido o el búfer *StrLen_or_IndPtr debe contener SQL_NULL_DATA, SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC.
Si una aplicación no puede determinar el tipo de un parámetro en una llamada a procedimiento, establece InputOutputType en SQL_PARAM_INPUT; si el origen de datos devuelve un valor para el parámetro, el controlador lo descarta.
SQL_PARAM_INPUT_OUTPUT. El parámetro marca un parámetro de entrada y salida en un procedimiento. Por ejemplo, el parámetro de {call GetEmpDept(?)} es un parámetro input/output que acepta el nombre de un empleado y devuelve el nombre del departamento del empleado.
Cuando se ejecuta la instrucción , el controlador envía datos para el parámetro al origen de datos; El búfer *ParameterValuePtr debe contener un valor de entrada válido o el búfer *StrLen_or_IndPtr debe contener SQL_NULL_DATA, SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC. Una vez ejecutada la instrucción , el controlador devuelve datos del parámetro a la aplicación; Si el origen de datos no devuelve un valor para un parámetro de entrada y salida, el controlador establece el búfer *StrLen_or_IndPtr en SQL_NULL_DATA.
Nota:
Cuando una aplicación ODBC 1.0 llama a SQLSetParam en un controlador ODBC 2.0, el Administrador de controladores lo convierte en una llamada a SQLBindParameter en el que el argumento InputOutputType se establece en SQL_PARAM_INPUT_OUTPUT.
SQL_PARAM_OUTPUT. El parámetro marca el valor devuelto de un procedimiento o un parámetro de salida en un procedimiento; en cualquier caso, se conocen como parámetros de salida. Por ejemplo, el parámetro de {?=call GetNextEmpID} es un parámetro de salida que devuelve el siguiente identificador de empleado.
Una vez ejecutada la instrucción , el controlador devuelve datos para el parámetro a la aplicación, a menos que los argumentos ParameterValuePtr y StrLen_or_IndPtr sean punteros NULOs, en cuyo caso el controlador descarta el valor de salida. Si el origen de datos no devuelve un valor para un parámetro de salida, el controlador establece el búfer *StrLen_or_IndPtr en SQL_NULL_DATA.
SQL_PARAM_INPUT_OUTPUT_STREAM. Indica que se debe transmitir un parámetro de entrada/salida. SQLGetData puede leer valores de parámetro en partes. BufferLength se omite porque la longitud del búfer se determinará en la llamada de SQLGetData. El valor del búfer de StrLen_or_IndPtr debe contener SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC o el resultado de la macro de SQL_LEN_DATA_AT_EXEC. Un parámetro debe enlazarse como parámetro data-at-execution (DAE) en la entrada si se transmitirá en la salida. ParameterValuePtr puede ser cualquier valor de puntero distinto de null devuelto por SQLParamData como token definido por el usuario cuyo valor se pasó con ParameterValuePtr para la entrada y salida. Para obtener más información, vea el tema que trata sobre recuperar parámetros de salida mediante SQLGetData.
SQL_PARAM_OUTPUT_STREAM. Igual que SQL_PARAM_INPUT_OUTPUT_STREAM, para un parámetro de salida. * StrLen_or_IndPtr se omite en la entrada.
En la tabla siguiente se enumeran diferentes combinaciones de InputOutputType y *StrLen_or_IndPtr:
| InputOutputType | *StrLen_or_IndPtr | Resultado | Comentario sobre ParameterValuePtr |
|---|---|---|---|
| SQL_PARAM_INPUT | SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC | Entrada en partes | ParameterValuePtr puede ser cualquier valor de puntero devuelto por SQLParamData como token definido por el usuario cuyo valor se pasó con ParameterValuePtr. |
| SQL_PARAM_INPUT | No SQL_LEN_DATA_AT_EXEC(len) ni SQL_DATA_AT_EXEC | Búfer enlazado a entrada | ParameterValuePtr es la dirección del búfer de entrada. |
| SQL_PARAM_OUTPUT | Se omite en la entrada. | Búfer enlazado a la salida | ParameterValuePtr es la dirección del búfer de salida. |
| SQL_PARAM_OUTPUT_STREAM | Se omite en la entrada. | Salida transmitida | ParameterValuePtr puede ser cualquier valor de puntero, que SQLParamData devolverá como token definido por el usuario cuyo valor se pasó con ParameterValuePtr. |
| SQL_PARAM_INPUT_OUTPUT | SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC | Entrada en partes y búfer enlazado a la salida | ParameterValuePtr es la dirección del búfer de salida, que también devolverá SQLParamData como token definido por el usuario cuyo valor se pasó con ParameterValuePtr. |
| SQL_PARAM_INPUT_OUTPUT | No SQL_LEN_DATA_AT_EXEC(len) ni SQL_DATA_AT_EXEC | Búfer enlazado a entrada y búfer enlazado a salida | ParameterValuePtr es la dirección del búfer de entrada y salida compartido. |
| SQL_PARAM_INPUT_OUTPUT_STREAM | SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC | Entrada en partes y salida transmitida | ParameterValuePtr puede ser cualquier valor de puntero que no sea NULL, que SQLParamData devolverá como token definido por el usuario cuyo valor se pasó con ParameterValuePtr para la entrada y salida. |
Nota:
El controlador debe decidir qué tipos SQL se permiten cuando una aplicación enlaza un parámetro output o input-output como transmitido. El administrador de controladores no generará un error para un tipo SQL no válido.
Argumento ValueType
El argumento ValueType especifica el tipo de datos C del parámetro . Este argumento establece los campos SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE y SQL_DESC_DATETIME_INTERVAL_CODE del APD. Debe ser uno de los valores de la sección Tipos de datos de C del Apéndice D: Tipos de datos.
Si el argumento ValueType es uno de los tipos de datos interval, el campo SQL_DESC_TYPE del registro ParameterNumber del APD se establece en SQL_INTERVAL, el campo SQL_DESC_CONCISE_TYPE del APD se establece en el tipo de datos interval conciso y el campo SQL_DESC_DATETIME_INTERVAL_CODE del registro ParameterNumber se establece en un subcódigo para el tipo de datos de intervalo específico. (Consulte Apéndice D: Tipos de datos). La precisión inicial del intervalo predeterminado (2) y la precisión del intervalo predeterminado (6), como se establece en los campos SQL_DESC_DATETIME_INTERVAL_PRECISION y SQL_DESC_PRECISION del APD, respectivamente, se usan para los datos. Si la precisión predeterminada no es adecuada, la aplicación debe establecer explícitamente el campo descriptor mediante una llamada a SQLSetDescField o SQLSetDescRec.
Si el argumento ValueType es uno de los tipos de datos datetime, el campo SQL_DESC_TYPE del registro ParameterNumber del APD se establece en SQL_DATETIME, el campo SQL_DESC_CONCISE_TYPE del registro ParameterNumber del APD se establece en el tipo de datos datetime C conciso y el campo SQL_DESC_DATETIME_INTERVAL_CODE del registro ParameterNumber se establece en un subcódigo para el tipo de datos datetime específico. (Consulte Apéndice D: Tipos de datos).
Si el argumento ValueType es un tipo de datos SQL_C_NUMERIC, la precisión predeterminada (definida por el controlador) y la escala predeterminada (0), como se establece en los campos SQL_DESC_PRECISION y SQL_DESC_SCALE del APD, se usan para los datos. Si la precisión o la escala predeterminadas no son adecuadas, la aplicación debe establecer explícitamente el campo descriptor mediante una llamada a SQLSetDescField o SQLSetDescRec.
SQL_C_DEFAULT especifica que el valor del parámetro se transfiere del tipo de datos C predeterminado para el tipo de datos SQL especificado con ParameterType.
También puede especificar un tipo de datos de C extendido. Para obtener más información, vea el tema sobre tipos de datos C en ODBC.
Para obtener más información, vea Tipos de datos de C predeterminados, conversión de datos de C a tipos de datos sql y conversión de datos de SQL a tipos de datos de C en el apéndice D: Tipos de datos.
ParameterType Argument
Debe ser uno de los valores enumerados en la sección Tipos de datos SQL del Apéndice D: Tipos de datos o debe ser un valor específico del controlador. Este argumento establece los campos SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE y SQL_DESC_DATETIME_INTERVAL_CODE del IPD.
Si el argumento ParameterType es uno de los identificadores datetime, el campo SQL_DESC_TYPE del IPD se establece en SQL_DATETIME, el campo SQL_DESC_CONCISE_TYPE del IPD se establece en el tipo de datos datetime SQL conciso y el campo SQL_DESC_DATETIME_INTERVAL_CODE se establece en el valor de subcódigo datetime adecuado.
Si ParameterType es uno de los identificadores de intervalo, el campo SQL_DESC_TYPE del IPD se establece en SQL_INTERVAL, el campo SQL_DESC_CONCISE_TYPE del IPD se establece en el tipo de datos intervalo SQL conciso y el campo SQL_DESC_DATETIME_INTERVAL_CODE del IPD se establece en el subcódigo de intervalo adecuado. El campo SQL_DESC_DATETIME_INTERVAL_PRECISION del IPD se establece en la precisión inicial del intervalo y el campo SQL_DESC_PRECISION se establece en la precisión de segundos del intervalo, si procede. Si el valor predeterminado de SQL_DESC_DATETIME_INTERVAL_PRECISION o SQL_DESC_PRECISION no es adecuado, la aplicación debe establecerla explícitamente llamando a SQLSetDescField. Para obtener más información sobre cualquiera de estos campos, vea SQLSetDescField.
Si el argumento ValueType es un tipo de datos SQL_NUMERIC, la precisión predeterminada (definida por el controlador) y la escala predeterminada (0), como se establece en los campos SQL_DESC_PRECISION y SQL_DESC_SCALE del IPD, se usan para los datos. Si la precisión o la escala predeterminadas no son adecuadas, la aplicación debe establecer explícitamente el campo descriptor mediante una llamada a SQLSetDescField o SQLSetDescRec.
Para obtener información sobre cómo se convierten los datos, vea Conversión de datos de C a tipos de datos sql y conversión de datos de SQL a tipos de datos de C en el apéndice D: Tipos de datos.
ColumnSize (argumento)
El argumento ColumnSize especifica el tamaño de la columna o expresión que corresponde al marcador de parámetros, la longitud de esos datos o ambos. Este argumento establece distintos campos del IPD, según el tipo de datos SQL (el argumento ParameterType ). Las reglas siguientes se aplican a esta asignación:
Si ParameterType es SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY o uno de los tipos de datos datetime o interval de SQL concisos, el campo SQL_DESC_LENGTH del IPD se establece en el valor de ColumnSize. (Para obtener más información, consulte Tamaño de columna, dígitos decimales, longitud de octeto de transferencia y tamaño de visualización del apéndice D: Tipos de datos).
Si ParameterType es SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL o SQL_DOUBLE, el campo SQL_DESC_PRECISION del IPD se establece en el valor de ColumnSize.
Para otros tipos de datos, se omite el argumento ColumnSize .
Para obtener más información, vea "Pasar valores de parámetro" y SQL_DATA_AT_EXEC en "argumento StrLen_or_IndPtr ".
Argumento DecimalDigits
Si ParameterType es SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND o SQL_INTERVAL_MINUTE_TO_SECOND, el campo SQL_DESC_PRECISION del IPD se establece en DecimalDigits. Si ParameterType es SQL_NUMERIC o SQL_DECIMAL, el campo SQL_DESC_SCALE del IPD se establece en DecimalDigits. Para todos los demás tipos de datos, se omite el argumento DecimalDigits .
ParameterValuePtr (argumento)
El argumento ParameterValuePtr apunta a un búfer que, cuando se llama a SQLExecute o SQLExecDirect , contiene los datos reales del parámetro . Los datos deben estar en el formato especificado por el argumento ValueType . Este argumento establece el campo SQL_DESC_DATA_PTR del APD. Una aplicación puede establecer el argumento ParameterValuePtr en un puntero nulo, siempre que *StrLen_or_IndPtr sea SQL_NULL_DATA o SQL_DATA_AT_EXEC. (Esto solo se aplica a los parámetros de entrada o entrada/salida).
Si *StrLen_or_IndPtr es el resultado de la macro SQL_LEN_DATA_AT_EXEC(length) o SQL_DATA_AT_EXEC, ParameterValuePtr es un valor de puntero definido por la aplicación asociado al parámetro . Se devuelve a la aplicación a través de SQLParamData. Por ejemplo, ParameterValuePtr podría ser un token distinto de cero, como un número de parámetro, un puntero a los datos o un puntero a una estructura que la aplicación usó para enlazar parámetros de entrada. Sin embargo, tenga en cuenta que si el parámetro es un parámetro de entrada y salida, ParameterValuePtr debe ser un puntero a un búfer donde se almacenará el valor de salida. Si el valor del atributo de instrucción SQL_ATTR_PARAMSET_SIZE es mayor que 1, la aplicación puede usar el valor al que apunta el atributo de instrucción SQL_ATTR_PARAMS_PROCESSED_PTR junto con el argumento ParameterValuePtr . Por ejemplo, ParameterValuePtr podría apuntar a una matriz de valores y la aplicación podría usar el valor al que apunta SQL_ATTR_PARAMS_PROCESSED_PTR para recuperar el valor correcto de la matriz. Para obtener más información, vea "Pasar valores de parámetro" más adelante en esta sección.
Si el argumento InputOutputType es SQL_PARAM_INPUT_OUTPUT o SQL_PARAM_OUTPUT, ParameterValuePtr apunta a un búfer en el que el controlador devuelve el valor de salida. Si el procedimiento devuelve uno o varios conjuntos de resultados, no se garantiza que el búfer *ParameterValuePtr se establezca hasta que se hayan procesado todos los conjuntos de resultados o recuentos de filas. Si el búfer no se establece hasta que se complete el procesamiento, los parámetros de salida y los valores devueltos no estarán disponibles hasta que SQLMoreResults devuelva SQL_NO_DATA. Llamar a SQLCloseCursor o SQLFreeStmt con una opción de SQL_CLOSE hará que estos valores se descarten.
Si el valor del atributo de instrucción SQL_ATTR_PARAMSET_SIZE es mayor que 1, ParameterValuePtr apunta a una matriz. Una sola instrucción SQL procesa la matriz completa de valores de entrada para un parámetro de entrada o entrada/salida y devuelve una matriz de valores de salida para un parámetro de entrada/salida o salida.
BufferLength (argumento)
Para los datos de caracteres y C binarios, el argumento BufferLength especifica la longitud del búfer *ParameterValuePtr (si es un solo elemento) o la longitud de un elemento de la matriz *ParameterValuePtr (si el valor del atributo de instrucción de SQL_ATTR_PARAMSET_SIZE es mayor que 1). Este argumento establece el campo de registro SQL_DESC_OCTET_LENGTH del APD. Si la aplicación especifica varios valores, BufferLength se usa para determinar la ubicación de los valores en la matriz *ParameterValuePtr , tanto en la entrada como en la salida. Para los parámetros de entrada/salida y salida, se usa para determinar si se truncan los datos de caracteres y binarios de C en la salida:
En el caso de los datos de caracteres C, si el número de bytes disponibles para devolver es mayor o igual que BufferLength, los datos de *ParameterValuePtr se truncan en BufferLength menos la longitud de un carácter de terminación NULL y el controlador termina con null.
Para los datos binarios de C, si el número de bytes disponibles para devolver es mayor que BufferLength, los datos de *ParameterValuePtr se truncan en bytes BufferLength.
Para todos los demás tipos de datos de C, se omite el argumento BufferLength . Se supone que la longitud del búfer *ParameterValuePtr (si es un solo elemento) o la longitud de un elemento de la matriz *ParameterValuePtr (si la aplicación llama a SQLSetStmtAttr con un argumento Attribute de SQL_ATTR_PARAMSET_SIZE para especificar varios valores para cada parámetro) se supone que es la longitud del tipo de datos C.
En el caso de los parámetros de entrada y salida transmitidos por secuencias, se omite el argumento BufferLength porque la longitud del búfer se especifica en SQLGetData.
Nota:
Cuando una aplicación ODBC 1.0 llama a SQLSetParam en odbc 3.x driver, el Administrador de controladores convierte esto en una llamada a SQLBindParameter en el que el argumento BufferLength siempre está SQL_SETPARAM_VALUE_MAX. Dado que el Administrador de controladores devuelve un error si odbc 3.x aplicación establece BufferLength en SQL_SETPARAM_VALUE_MAX, un ODBC 3.El controlador x puede usarlo para determinar cuándo se llama mediante una aplicación ODBC 1.0.
Nota:
En SQLSetParam, la forma en que una aplicación especifica la longitud del búfer *ParameterValuePtr para que el controlador pueda devolver datos binarios o de caracteres, y la forma en que una aplicación envía una matriz de valores de parámetro binarios o de caracteres al controlador, son definidos por el controlador.
argumento StrLen_or_IndPtr
El argumento StrLen_or_IndPtr apunta a un búfer que, cuando se llama a SQLExecute o SQLExecDirect , contiene uno de los siguientes elementos. (Este argumento establece los campos de registro SQL_DESC_OCTET_LENGTH_PTR y SQL_DESC_INDICATOR_PTR de los punteros de parámetros de la aplicación).
Longitud del valor del parámetro almacenado en *ParameterValuePtr. Esto se omite, excepto para los datos binarios de caracteres o C.
SQL_NTS. El valor del parámetro es una cadena terminada en null.
SQL_NULL_DATA. El valor del parámetro es NULL.
SQL_DEFAULT_PARAM. Un procedimiento consiste en usar el valor predeterminado de un parámetro, en lugar de un valor recuperado de la aplicación. Este valor solo es válido en un procedimiento denominado en sintaxis canónica ODBC y, a continuación, solo si el argumento InputOutputType es SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT o SQL_PARAM_INPUT_OUTPUT_STREAM. Cuando *StrLen_or_IndPtr es SQL_DEFAULT_PARAM, los argumentos ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength y ParameterValuePtr se omiten para los parámetros de entrada y solo se usan para definir el valor del parámetro de salida para los parámetros de entrada y salida.
Resultado de la macro SQL_LEN_DATA_AT_EXEC(length). Los datos del parámetro se enviarán con SQLPutData. Si el argumento ParameterType es SQL_LONGVARBINARY, SQL_LONGVARCHAR o un tipo de datos largo específico del origen de datos y el controlador devuelve "Y" para el tipo de información de SQL_NEED_LONG_DATA_LEN en SQLGetInfo, la longitud es el número de bytes de datos que se enviarán para el parámetro; de lo contrario, la longitud debe ser un valor no negativo y se omite. Para obtener más información, vea "Pasar valores de parámetro", más adelante en esta sección.
Por ejemplo, para especificar que se enviarán 10 000 bytes de datos con SQLPutData en una o varias llamadas, para un parámetro SQL_LONGVARCHAR, una aplicación establece *StrLen_or_IndPtr en SQL_LEN_DATA_AT_EXEC(10000).
SQL_DATA_AT_EXEC. Los datos del parámetro se enviarán con SQLPutData. Las aplicaciones ODBC 1.0 usan este valor cuando llaman a ODBC 3.controladores x . Para obtener más información, vea "Pasar valores de parámetro", más adelante en esta sección.
Si StrLen_or_IndPtr es un puntero nulo, el controlador asume que todos los valores de parámetro de entrada no son NULL y que los datos binarios y de carácter están terminados en null. Si InputOutputType es SQL_PARAM_OUTPUT o SQL_PARAM_OUTPUT_STREAM y ParameterValuePtr y StrLen_or_IndPtr son punteros NULOs, el controlador descarta el valor de salida.
Nota:
No se recomienda encarecidamente a los desarrolladores de aplicaciones especificar un puntero NULO para StrLen_or_IndPtr cuando se SQL_C_BINARY el tipo de datos del parámetro. Para asegurarse de que un controlador no trunca inesperadamente SQL_C_BINARY datos, StrLen_or_IndPtr debe contener un puntero a un valor de longitud válido.
Si el argumento InputOutputType es SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM o SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr apunta a un búfer en el que el controlador devuelve SQL_NULL_DATA, el número de bytes disponibles para devolver en *ParameterValuePtr (excluyendo el byte de terminación null de los datos de caracteres) o SQL_NO_TOTAL (si no se puede determinar el número de bytes disponibles para devolver). Si el procedimiento devuelve uno o varios conjuntos de resultados, no se garantiza que el búfer *StrLen_or_IndPtr se establezca hasta que se hayan capturado todos los resultados.
Si el valor del atributo de instrucción SQL_ATTR_PARAMSET_SIZE es mayor que 1, StrLen_or_IndPtr apunta a una matriz de valores de SQLLEN. Estos pueden ser cualquiera de los valores enumerados anteriormente en esta sección y se procesan con una sola instrucción SQL.
Pasar valores de parámetro
Una aplicación puede pasar el valor de un parámetro en el búfer *ParameterValuePtr o con una o varias llamadas a SQLPutData. Los parámetros cuyos datos se pasan con SQLPutData se conocen como parámetros de datos en ejecución . Normalmente se usan para enviar datos para SQL_LONGVARBINARY y parámetros de SQL_LONGVARCHAR, y se pueden mezclar con otros parámetros.
Para pasar valores de parámetro, una aplicación realiza la siguiente secuencia de pasos:
Llama a SQLBindParameter para cada parámetro para enlazar búferes para el valor del parámetro (argumento ParameterValuePtr ) y length/indicator (StrLen_or_IndPtr argumento). Para los parámetros de datos en ejecución, ParameterValuePtr es un valor de puntero definido por la aplicación, como un número de parámetro o un puntero a los datos. El valor se devolverá más adelante y se puede usar para identificar el parámetro .
Coloca valores para los parámetros de entrada y entrada/salida en los búferes *ParameterValuePtr y *StrLen_or_IndPtr :
Para los parámetros normales, la aplicación coloca el valor del parámetro en el búfer *ParameterValuePtr y la longitud de ese valor en el búfer *StrLen_or_IndPtr . Para obtener más información, vea Establecer valores de parámetro.
Para los parámetros de datos en ejecución, la aplicación coloca el resultado de la macro SQL_LEN_DATA_AT_EXEC(length) (al llamar a un controlador ODBC 2.0) en el búfer *StrLen_or_IndPtr .
Llama a SQLExecute o SQLExecDirect para ejecutar la instrucción SQL.
Si no hay parámetros de datos en ejecución, el proceso se completa.
Si hay parámetros de datos en ejecución, la función devuelve SQL_NEED_DATA.
Llama a SQLParamData para recuperar el valor definido por la aplicación especificado en el argumento ParameterValuePtr de SQLBindParameter para que se procese el primer parámetro de datos en ejecución. SQLParamData devuelve SQL_NEED_DATA.
Nota:
Aunque los parámetros de datos en ejecución se asemejan a las columnas de datos en ejecución, el valor devuelto por SQLParamData es diferente para cada uno. Los parámetros de datos en ejecución son parámetros en una instrucción SQL para la que los datos se enviarán con SQLPutData cuando la instrucción se ejecute con SQLExecDirect o SQLExecute. Se enlazan con SQLBindParameter. El valor devuelto por SQLParamData es un valor de puntero pasado a SQLBindParameter en el argumento ParameterValuePtr. Las columnas de datos en ejecución son columnas de un conjunto de filas para las que se enviarán datos con SQLPutData cuando se actualice o agregue una fila con SQLBulkOperations o se actualice con SQLSetPos. Se enlazan con SQLBindCol. El valor devuelto por SQLParamData es la dirección de la fila en el búfer *TargetValuePtr (establecido por una llamada a SQLBindCol) que se está procesando.
Llama a SQLPutData una o varias veces para enviar datos para el parámetro . Se necesita más de una llamada si el valor de datos es mayor que el búfer *ParameterValuePtr especificado en SQLPutData; solo se permiten varias llamadas a SQLPutData para el mismo parámetro cuando se envían datos de caracteres C a una columna con un tipo de datos específico de caracteres, binarios o datos específicos del origen de datos o al enviar datos binarios de C a una columna con un carácter, tipo de datos binario o específico del origen de datos.
Llama a SQLParamData de nuevo para indicar que se han enviado todos los datos para el parámetro .
Si hay más parámetros de datos en ejecución, SQLParamData devuelve SQL_NEED_DATA y el valor definido por la aplicación para el siguiente parámetro data-at-execution que se va a procesar. La aplicación repite los pasos 4 y 5.
Si no hay más parámetros de datos en ejecución, el proceso se completa. Si la instrucción se ejecutó correctamente, SQLParamData devuelve SQL_SUCCESS o SQL_SUCCESS_WITH_INFO; si se produjo un error en la ejecución, devuelve SQL_ERROR. En este momento, SQLParamData puede devolver cualquier SQLSTATE que pueda devolver la función que se usa para ejecutar la instrucción (SQLExecDirect o SQLExecute).
Los valores de salida de los parámetros de entrada,salida o salida están disponibles en los búferes *ParameterValuePtr y *StrLen_or_IndPtr después de que la aplicación recupere todos los conjuntos de resultados generados por la instrucción .
Al llamar a SQLExecute o SQLExecDirect , la instrucción se coloca en un estado SQL_NEED_DATA. En este momento, la aplicación solo puede llamar a SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData o SQLPutData con la instrucción o el identificador de conexión asociado a la instrucción . Si llama a cualquier otra función con la instrucción o la conexión asociada a la instrucción , la función devuelve SQLSTATE HY010 (error de secuencia de función). La instrucción deja el estado SQL_NEED_DATA cuando SQLParamData o SQLPutData devuelve un error, SQLParamData devuelve SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, o se cancela la instrucción.
Si la aplicación llama a SQLCancel mientras el controlador todavía necesita datos para los parámetros de datos en ejecución, el controlador cancela la ejecución de la instrucción; la aplicación puede llamar a SQLExecute o SQLExecDirect de nuevo.
Recuperación de parámetros de salida transmitidos
Cuando una aplicación establece InputOutputType en SQL_PARAM_INPUT_OUTPUT_STREAM o SQL_PARAM_OUTPUT_STREAM, el valor del parámetro de salida debe recuperarse mediante una o varias llamadas a SQLGetData. Cuando el controlador tiene un valor de parámetro de salida transmitido para volver a la aplicación, devolverá SQL_PARAM_DATA_AVAILABLE en respuesta a una llamada a las siguientes funciones: SQLMoreResults, SQLExecute y SQLExecDirect. Una aplicación llama a SQLParamData para determinar qué valor de parámetro está disponible.
Para obtener más información sobre SQL_PARAM_DATA_AVAILABLE y los parámetros de salida transmitidos, vea Recuperación de parámetros de salida mediante SQLGetData.
Utilizar matrices de parámetros
Cuando una aplicación prepara una instrucción con marcadores de parámetros y pasa una matriz de parámetros, puede ejecutarse de dos maneras diferentes. Una manera es que el controlador dependa de las capacidades de procesamiento de matriz del back-end, en cuyo caso toda la instrucción con la matriz de parámetros se trata como una unidad atómica. Oracle es un ejemplo de un origen de datos que admite funcionalidades de procesamiento de matrices. Otra manera de implementar esta característica es que el controlador genere un lote de instrucciones SQL, una instrucción SQL para cada conjunto de parámetros de la matriz de parámetros y ejecute el lote. Las matrices de parámetros no se pueden usar con una instrucción UPDATE WHERE CURRENT OF .
Cuando se procesa una matriz de parámetros, los conjuntos de resultados o recuentos de filas individuales (uno para cada conjunto de parámetros) pueden estar disponibles o los conjuntos de resultados o los recuentos de filas se pueden inscribir en uno. La opción SQL_PARAM_ARRAY_ROW_COUNTS de SQLGetInfo indica si los recuentos de filas están disponibles para cada conjunto de parámetros (SQL_PARC_BATCH) o solo hay disponible un recuento de filas (SQL_PARC_NO_BATCH).
La opción SQL_PARAM_ARRAY_SELECTS en SQLGetInfo indica si un conjunto de resultados está disponible para cada conjunto de parámetros (SQL_PAS_BATCH) o solo hay disponible un conjunto de resultados (SQL_PAS_NO_BATCH). Si el controlador no permite ejecutar una instrucción de generación de conjuntos de resultados con una matriz de parámetros, SQL_PARAM_ARRAY_SELECTS devuelve SQL_PAS_NO_SELECT.
Para obtener más información, vea Función SQLGetInfo.
Para admitir matrices de parámetros, el atributo de instrucción SQL_ATTR_PARAMSET_SIZE se establece para especificar el número de valores de cada parámetro. Si el campo es mayor que 1, los campos SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR del APD deben apuntar a matrices. La cardinalidad de cada matriz es igual al valor de SQL_ATTR_PARAMSET_SIZE.
El campo SQL_DESC_ROWS_PROCESSED_PTR del APD apunta a un búfer que contiene el número de conjuntos de parámetros que se han procesado, incluidos los conjuntos de errores. A medida que se procesa cada conjunto de parámetros, el controlador almacena un nuevo valor en el búfer. No se devolverá ningún número si se trata de un puntero nulo. Cuando se usan matrices de parámetros, el valor al que apunta el campo SQL_DESC_ROWS_PROCESSED_PTR del APD se rellena incluso si la función de configuración devuelve SQL_ERROR. Si se devuelve SQL_NEED_DATA, el valor al que apunta el campo SQL_DESC_ROWS_PROCESSED_PTR del APD se establece en el conjunto de parámetros que se está procesando.
Lo que ocurre cuando se enlaza una matriz de parámetros y se ejecuta una instrucción UPDATE WHERE CURRENT OF es definida por el controlador.
Enlace de parámetros de columna
En el enlace con columnas, la aplicación enlaza matrices de parámetros y longitud/indicador independientes a cada parámetro.
Para usar el enlace con columnas, la aplicación establece primero el atributo de instrucción SQL_ATTR_PARAM_BIND_TYPE en SQL_PARAM_BIND_BY_COLUMN. (Este es el valor predeterminado). Para cada columna que se va a enlazar, la aplicación realiza los pasos siguientes:
Asigna una matriz de búfer de parámetros.
Asigna una matriz de búferes de longitud o indicador.
Nota:
Si la aplicación escribe directamente en descriptores cuando se usa el enlace en modo de columna, se pueden usar matrices independientes para los datos de longitud e indicador.
Llama a SQLBindParameter con los argumentos siguientes:
ValueType es el tipo C de un único elemento de la matriz de búfer de parámetros.
ParameterType es el tipo SQL del parámetro .
ParameterValuePtr es la dirección de la matriz de búfer de parámetros.
BufferLength es el tamaño de un único elemento de la matriz de búfer de parámetros. El argumento BufferLength se omite cuando los datos son de longitud fija.
StrLen_or_IndPtr es la dirección de la matriz length/indicator.
Para obtener más información sobre cómo se usa esta información, vea "ParameterValuePtr Argument" en "Comments", más adelante en esta sección. Para obtener más información sobre el enlace con columnas de parámetros, vea Binding Arrays of Parameters (Enlazar matrices de parámetros).
Enlace de parámetros de fila
En el enlace de fila, la aplicación define una estructura que contiene búferes de longitud y longitud e indicador para cada parámetro que se va a enlazar.
Para usar el enlace de fila, la aplicación realiza los pasos siguientes:
Define una estructura para contener un único conjunto de parámetros (incluidos los búferes de longitud y longitud y indicador) y asigna una matriz de estas estructuras.
Nota:
Si la aplicación escribe directamente en descriptores cuando se usa el enlace de fila, se pueden usar campos independientes para los datos de longitud e indicador.
Establece el atributo de instrucción SQL_ATTR_PARAM_BIND_TYPE en el tamaño de la estructura que contiene un único conjunto de parámetros o en el tamaño de una instancia de un búfer en el que se enlazarán los parámetros. La longitud debe incluir espacio para todos los parámetros enlazados y cualquier relleno de la estructura o el búfer, para asegurarse de que cuando la dirección de un parámetro enlazado se incremente con la longitud especificada, el resultado apuntará al principio del mismo parámetro en la fila siguiente. Cuando se usa el operador sizeof en ANSI C, se garantiza este comportamiento.
Llama a SQLBindParameter con los argumentos siguientes para cada parámetro que se va a enlazar:
ValueType es el tipo del miembro del búfer de parámetros que se va a enlazar a la columna.
ParameterType es el tipo SQL del parámetro .
ParameterValuePtr es la dirección del miembro del búfer de parámetros en el primer elemento de matriz.
BufferLength es el tamaño del miembro del búfer de parámetros.
StrLen_or_IndPtr es la dirección del miembro de longitud o indicador que se va a enlazar.
Para obtener más información sobre cómo se usa esta información, vea "ParameterValuePtr Argument", más adelante en esta sección. Para obtener más información sobre el enlace de filas de parámetros, vea Binding Arrays of Parameters (Matrices de enlaces de parámetros).
Información del error
Si un controlador no implementa matrices de parámetros como lotes (la opción SQL_PARAM_ARRAY_ROW_COUNTS es igual a SQL_PARC_NO_BATCH), las situaciones de error se controlan como si se ejecutara una instrucción. Si el controlador implementa matrices de parámetros como lotes, una aplicación puede usar el campo de encabezado SQL_DESC_ARRAY_STATUS_PTR del IPD para determinar qué parámetro de una instrucción SQL o qué parámetro de una matriz de parámetros provocó que SQLExecDirect o SQLExecute devuelvan un error. Este campo contiene información de estado para cada fila de valores de parámetro. Si el campo indica que se ha producido un error, los campos de la estructura de datos de diagnóstico indicarán la fila y el número de parámetro del parámetro que produjo un error. El número de elementos de la matriz se definirá mediante el campo de encabezado SQL_DESC_ARRAY_SIZE del APD, que puede establecer el atributo de instrucción SQL_ATTR_PARAMSET_SIZE.
Nota:
El campo de encabezado SQL_DESC_ARRAY_STATUS_PTR del APD se usa para pasar por alto los parámetros. Para obtener más información sobre cómo omitir parámetros, vea la sección siguiente, "Ignorar un conjunto de parámetros".
Cuando SQLExecute o SQLExecDirect devuelve SQL_ERROR, los elementos de la matriz a los que apunta el campo SQL_DESC_ARRAY_STATUS_PTR del IPD contendrán SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED o SQL_PARAM_DIAG_UNAVAILABLE.
Para cada elemento de esta matriz, la estructura de datos de diagnóstico contiene uno o varios registros de estado. El campo SQL_DIAG_ROW_NUMBER de la estructura indica el número de fila de los valores de parámetro que provocaron el error. Si es posible determinar el parámetro determinado en una fila de parámetros que provocó el error, el número de parámetro se escribirá en el campo SQL_DIAG_COLUMN_NUMBER.
SQL_PARAM_UNUSED se especifica cuando no se ha usado un parámetro porque se produjo un error en un parámetro anterior que obligó a SQLExecute o SQLExecDirect a anular. Por ejemplo, si hay 50 parámetros y se produjo un error al ejecutar el conjunto de parámetros fortieth que provocó la anulación de SQLExecute o SQLExecDirect , SQL_PARAM_UNUSED se escribe en la matriz de estado para los parámetros 41 a 50.
SQL_PARAM_DIAG_UNAVAILABLE se introduce cuando el controlador trata las matrices de parámetros como una unidad monolítica, por lo que no genera este nivel de parámetro individual de información de error.
Algunos errores en el procesamiento de un único conjunto de parámetros hacen que el procesamiento de los conjuntos de parámetros subsiguientes de la matriz se detenga. Otros errores no afectan al procesamiento de parámetros posteriores. Qué errores dejarán de procesarse es definido por el controlador. Si no se detiene el procesamiento, se procesan todos los parámetros de la matriz, SQL_SUCCESS_WITH_INFO se devuelven como resultado del error y el búfer definido por SQL_ATTR_PARAMS_PROCESSED_PTR se establece en el número total de conjuntos de parámetros procesados (tal como se define en el atributo de instrucción SQL_ATTR_PARAMSET_SIZE), que incluye conjuntos de errores.
Precaución
El comportamiento de ODBC cuando se produce un error en el procesamiento de una matriz de parámetros es diferente en ODBC 3.x que en ODBC 2.x. En ODBC 2.x, la función devolvió SQL_ERROR y el procesamiento dejaron de funcionar. El búfer al que apunta el argumento pirow de SQLParamOptions contenía el número de la fila de error. En ODBC 3.x, la función devuelve SQL_SUCCESS_WITH_INFO y el procesamiento pueden detener o continuar. Si continúa, el búfer especificado por SQL_ATTR_PARAMS_PROCESSED_PTR se establecerá en el valor de todos los parámetros procesados, incluidos los que provocaron un error. Este cambio en el comportamiento puede provocar problemas para las aplicaciones existentes.
Cuando SQLExecute o SQLExecDirect devuelve antes de completar el procesamiento de todos los conjuntos de parámetros de una matriz de parámetros, como cuando se devuelve SQL_ERROR o SQL_NEED_DATA, la matriz de estado contiene estados para esos parámetros que ya se han procesado. La ubicación a la que apunta el campo SQL_DESC_ROWS_PROCESSED_PTR del IPD contiene el número de fila de la matriz de parámetros que provocó el código de error SQL_ERROR o SQL_NEED_DATA. Cuando se envía una matriz de parámetros a una instrucción SELECT, la disponibilidad de los valores de matriz de estado es definida por el controlador; pueden estar disponibles una vez ejecutada la instrucción o cuando se capturan los conjuntos de resultados.
Omitir un conjunto de parámetros
El campo SQL_DESC_ARRAY_STATUS_PTR del APD (establecido por el atributo de instrucción SQL_ATTR_PARAM_STATUS_PTR) se puede usar para indicar que se debe omitir un conjunto de parámetros enlazados en una instrucción SQL. Para dirigir al controlador que omita uno o varios conjuntos de parámetros durante la ejecución, una aplicación debe seguir estos pasos:
Llame a SQLSetDescField para establecer el campo de encabezado SQL_DESC_ARRAY_STATUS_PTR del APD para que apunte a una matriz de valores SQLUSMALLINT para contener información de estado. Este campo también se puede establecer llamando a SQLSetStmtAttr con un atributo de SQL_ATTR_PARAM_OPERATION_PTR, lo que permite a una aplicación establecer el campo sin obtener un identificador de descriptor.
Establezca cada elemento de la matriz definida por el campo SQL_DESC_ARRAY_STATUS_PTR del APD en uno de los dos valores:
SQL_PARAM_IGNORE, para indicar que la fila se excluye de la ejecución de instrucciones.
SQL_PARAM_PROCEED, para indicar que la fila se incluye en la ejecución de instrucciones.
Llame a SQLExecDirect o SQLExecute para ejecutar la instrucción preparada.
Las reglas siguientes se aplican a la matriz definida por el campo SQL_DESC_ARRAY_STATUS_PTR del APD:
El puntero se establece en NULL de forma predeterminada.
Si el puntero es NULL, se usan todos los conjuntos de parámetros, como si todos los elementos se establecieran en SQL_ROW_PROCEED.
Establecer un elemento en SQL_PARAM_PROCEED no garantiza que la operación use ese conjunto determinado de parámetros.
SQL_PARAM_PROCEED se define como 0 en el archivo de encabezado.
Una aplicación puede establecer el campo SQL_DESC_ARRAY_STATUS_PTR en el APD para que apunte a la misma matriz a la que apunta el campo SQL_DESC_ARRAY_STATUS_PTR del IRD. Esto resulta útil cuando se enlazan parámetros a datos de fila. A continuación, los parámetros se pueden omitir según el estado de los datos de fila. Además de SQL_PARAM_IGNORE, los códigos siguientes hacen que se omita un parámetro en una instrucción SQL: SQL_ROW_DELETED, SQL_ROW_UPDATED y SQL_ROW_ERROR. Además de SQL_PARAM_PROCEED, los códigos siguientes hacen que una instrucción SQL continúe: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO y SQL_ROW_ADDED.
Reenlazamiento de parámetros
Una aplicación puede realizar una de estas dos operaciones para cambiar un enlace:
Llame a SQLBindParameter para especificar un nuevo enlace para una columna que ya está enlazada. El controlador sobrescribe el enlace anterior con el nuevo.
Especifique un desplazamiento que se va a agregar a la dirección del búfer especificada por la llamada de enlace a SQLBindParameter. Para obtener más información, consulte la sección siguiente, "Reenlazamiento con desplazamientos".
Reenlace con desplazamientos
La reenlazamiento de parámetros es especialmente útil cuando una aplicación tiene una configuración de área de búfer que puede contener muchos parámetros, pero una llamada a SQLExecDirect o SQLExecute solo usa algunos de los parámetros. El espacio restante en el área del búfer se puede usar para el siguiente conjunto de parámetros modificando el enlace existente mediante un desplazamiento.
El SQL_DESC_BIND_OFFSET_PTR campo de encabezado del APD apunta al desplazamiento de enlace. Si el campo no es NULL, el controlador desreferencia el puntero y, si ninguno de los valores de la SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR campos es un puntero nulo, agrega el valor desreferenciado a esos campos en los registros del descriptor en tiempo de ejecución. Los nuevos valores de puntero se usan cuando se ejecutan las instrucciones SQL. El desplazamiento sigue siendo válido después de volver a enlazar. Dado que SQL_DESC_BIND_OFFSET_PTR es un puntero al desplazamiento en lugar del propio desplazamiento, una aplicación puede cambiar el desplazamiento directamente, sin tener que llamar a SQLSetDescField o SQLSetDescRec para cambiar el campo descriptor. El puntero se establece en NULL de forma predeterminada. El campo SQL_DESC_BIND_OFFSET_PTR del ARD se puede establecer mediante una llamada a SQLSetDescField o mediante una llamada a SQLSetStmtAttr con un fAttribute de SQL_ATTR_PARAM_BIND_OFFSET_PTR.
El desplazamiento de enlace siempre se agrega directamente a los valores de los campos SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR. Si el desplazamiento se cambia a un valor diferente, el nuevo valor todavía se agrega directamente al valor de cada campo descriptor. El nuevo desplazamiento no se agrega a la suma del valor del campo y a los desplazamientos anteriores.
Descriptores de
La forma en que un parámetro está enlazado viene determinado por los campos de los APD e IPD. Los argumentos de SQLBindParameter se usan para establecer esos campos descriptores. Las funciones SQLSetDescField también pueden establecer los campos, aunque SQLBindParameter es más eficaz para su uso, ya que la aplicación no tiene que obtener un identificador de descriptor para llamar a SQLBindParameter.
Precaución
Llamar a SQLBindParameter para una instrucción puede afectar a otras instrucciones. Esto ocurre cuando el ARD asociado a la instrucción se asigna explícitamente y también está asociado a otras instrucciones. Dado que SQLBindParameter modifica los campos del APD, las modificaciones se aplican a todas las instrucciones con las que está asociado este descriptor. Si no es el comportamiento necesario, la aplicación debe desasociar este descriptor de las demás instrucciones antes de llamar a SQLBindParameter.
Conceptualmente, SQLBindParameter realiza los pasos siguientes en secuencia:
Llama a SQLGetStmtAttr para obtener el identificador de APD.
Llama a SQLGetDescField para obtener el campo SQL_DESC_COUNT del APD y, si el valor del argumento ColumnNumber supera el valor de SQL_DESC_COUNT, llama a SQLSetDescField para aumentar el valor de SQL_DESC_COUNT a ColumnNumber.
Llama a SQLSetDescField varias veces para asignar valores a los siguientes campos del APD:
Establece SQL_DESC_TYPE y SQL_DESC_CONCISE_TYPE en el valor de ValueType, excepto que si ValueType es uno de los identificadores concisos de un subtipo datetime o interval, establece SQL_DESC_TYPE en SQL_DATETIME o SQL_INTERVAL, respectivamente, establece SQL_DESC_CONCISE_TYPE en el identificador conciso y establece SQL_DESC_DATETIME_INTERVAL_CODE en el subcódigo de intervalo o fecha y hora correspondientes.
Establece el campo SQL_DESC_OCTET_LENGTH en el valor de BufferLength.
Establece el campo SQL_DESC_DATA_PTR en el valor de ParameterValue.
Establece el campo SQL_DESC_OCTET_LENGTH_PTR en el valor de StrLen_or_Ind.
Establece el campo SQL_DESC_INDICATOR_PTR también en el valor de StrLen_or_Ind.
El parámetro StrLen_or_Ind especifica tanto la información del indicador como la longitud del valor del parámetro.
Llama a SQLGetStmtAttr para obtener el identificador IPD.
Llama a SQLGetDescField para obtener el campo SQL_DESC_COUNT del IPD y, si el valor del argumento ColumnNumber supera el valor de SQL_DESC_COUNT, llama a SQLSetDescField para aumentar el valor de SQL_DESC_COUNT a ColumnNumber.
Llama a SQLSetDescField varias veces para asignar valores a los siguientes campos del IPD:
Establece SQL_DESC_TYPE y SQL_DESC_CONCISE_TYPE en el valor de ParameterType, salvo que si ParameterType es uno de los identificadores concisos de un subtipo datetime o interval, establece SQL_DESC_TYPE en SQL_DATETIME o SQL_INTERVAL, respectivamente, establece SQL_DESC_CONCISE_TYPE en el identificador conciso y establece SQL_DESC_DATETIME_INTERVAL_CODE en el subcódigo datetime o interval correspondiente.
Establece uno o varios SQL_DESC_LENGTH, SQL_DESC_PRECISION y SQL_DESC_DATETIME_INTERVAL_PRECISION, según corresponda para ParameterType.
Establece SQL_DESC_SCALE en el valor de DecimalDigits.
Si se produce un error en la llamada a SQLBindParameter , el contenido de los campos descriptores que habría establecido en el APD no está definido y el campo SQL_DESC_COUNT del APD no cambia. Además, los campos SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE y SQL_DESC_TYPE del registro adecuado en el IPD no están definidos y el campo SQL_DESC_COUNT del IPD no cambia.
Conversión de llamadas a y desde SQLSetParam
Cuando una aplicación ODBC 1.0 llama a SQLSetParam en odbc 3.x driver, ODBC 3.x Driver Manager asigna la llamada como se muestra en la tabla siguiente.
| Llamada por aplicación ODBC 1.0 | Llame a ODBC 3.Controlador x |
|---|---|
| SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); | SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr); |
Ejemplos
A Uso de la función SQLBindParameter
En el ejemplo siguiente, una aplicación prepara una instrucción SQL para insertar datos en la tabla ORDERS. Para cada parámetro de la instrucción , la aplicación llama a SQLBindParameter para especificar el tipo de datos ODBC C y el tipo de datos SQL del parámetro y enlazar un búfer a cada parámetro. Para cada fila de datos, la aplicación asigna valores de datos a cada parámetro y llama a SQLExecute para ejecutar la instrucción .
En el ejemplo siguiente se supone que tiene un origen de datos ODBC en el equipo denominado Northwind que está asociado a la base de datos Northwind.
Para obtener más ejemplos de código, vea Función SQLBulkOperations, Función SQLProcedures, Función SQLPutData y Función SQLSetPos.
// 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);
}
B. Ejecución de un procedimiento almacenado mediante un parámetro con nombre
En el ejemplo siguiente, una aplicación ejecuta un procedimiento almacenado de SQL Server mediante un parámetro con nombre.
// 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);
}
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Devolver información sobre un parámetro en una instrucción | Función SQLDescribeParam |
| Ejecución de una instrucción SQL | Función SQLExecDirect |
| Ejecución de una instrucción SQL preparada | Función SQLExecute |
| Liberar búferes de parámetros en la instrucción | Función SQLFreeStmt |
| Devolver el número de parámetros de instrucción | Función SQLNumParams |
| Devolver el siguiente parámetro para enviar datos | Función SQLParamData |
| Especificación de varios valores de parámetro | Función SQLParamOptions |
| Envío de datos de parámetros en tiempo de ejecución | Función SQLPutData |
Consulte también
Referencia de API ODBC
Archivos de encabezado de ODBC
Recuperar parámetros de salida mediante SQLGetData
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de