SQLBindParameter--Enlazar un marcador de parámetro a un almacenamiento intermedio

Finalidad

Especificación:

CLI de DB2 2.1

ODBC 2.0

SQLBindParameter() se utiliza para asociar (enlazar) marcadores de parámetros de una sentencia de SQL con variables de aplicación, para todos los tipos de datos C. En este caso, se transfieren datos de la aplicación al DBMS cuando se invoca SQLExecute() o SQLExecDirect(). Durante la transferencia de datos puede producirse una conversión de los datos.

Sintaxis

SQLRETURN  SQL_API SQLBindParameter(
                SQLHSTMT          StatementHandle,  /* hstmt */
                SQLUSMALLINT      ParameterNumber,  /* ipar */
                SQLSMALLINT       InputOutputType,  /* fParamType */
                SQLSMALLINT       ValueType,        /* fCType */
                SQLSMALLINT       ParameterType,    /* fSqlType */
                SQLUINTEGER       ColumnSize,       /* cbColDef */
                SQLSMALLINT       DecimalDigits,    /* ibScale */
                SQLPOINTER        ParameterValuePtr,/* rgbValue */
                SQLINTEGER        BufferLength,      /* cbValueMax */
                SQLINTEGER *FAR   StrLen_or_IndPtr);/* pcbValue */

Argumentos de la función

Tabla 34. Argumentos de SQLBindParameter

Tipo de datos	Argumento	Uso	Descripción
SQLHSTMT	`StatementHandle`	entrada	Descriptor de contexto de sentencia.
SQLUSMALLINT	`ParameterNumber`	entrada	Número del marcador de parámetro, ordenado secuencialmente de izquierda a derecha y comenzando en 1.
SQLSMALLINT	`InputOutputType`	entrada	El tipo de parámetro. El tipo soportado es: SQL_PARAM_INPUT: Cuando se ejecuta la sentencia, se envía al servidor el valor de datos real del parámetro; el almacenamiento intermedio ParameterValuePtr debe contener valores válidos de datos de entrada; el almacenamiento intermedio `StrLen_or_IndPtr` debe contener el correspondiente valor de longitud o SQL_NTS, o SQL_NULL_DATA. DB2 Everyplace no da soporte a `SQLPutData()`, por lo que no se debe colocar el valor del parámetro en el almacenamiento intermedio ParameterValuePtr. SQL_PARAM_INPUT_OUTPUT: El marcador de parámetro está asociado a un parámetro de entrada/salida del procedimiento almacenado invocado. Una vez ejecutada la sentencia, se envían al servidor los valores de datos reales para el parámetro. El almacenamiento intermedio `ParameterValuePtr` debe contener valores válidos de datos de entrada; el almacenamiento intermedio `StrLen_or_IndPtr` debe contener el correspondiente valor de longitud o SQL_NTS, SQL_NULL_DATA. SQL_PARAM_OUTPUT: El marcador de parámetro está asociado a un parámetro de salida del procedimiento almacenado invocado o al valor de retorno del procedimiento almacenado. Una vez ejecutada la sentencia, los datos del parámetro de salida se devuelven al almacenamiento intermedio de la aplicación especificado mediante `ParameterValuePtr` y `StrLen_or_IndPtr`, a menos que ambos sean punteros NULL, en cuyo caso se descartan los datos de salida. Si un parámetro de salida no tiene un valor de retorno, `StrLen_or_IndPtr` se establece en SQL_NULL_DATA.
SQLSMALLINT	`ValueType`	entrada	Tipo de datos C del parámetro. Se da soporte a los tipos siguientes: SQL_C_BINARY SQL_C_BIT SQL_C_CHAR SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_TYPE_DATE SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP SQL_C_TINYINT Si se especifica SQL_C_DEFAULT, los datos se transfieren desde su tipo de datos C por omisión al tipo indicado en `ParameterType`.
SQLSMALLINT	`ParameterType`	entrada	Tipo de datos SQL del parámetro. Los tipos soportados son: SQL_BLOB SQL_CHAR SQL_DECIMAL SQL_INTEGER SQL_SMALLINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARCHAR
SQLUINTEGER	`ColumnSize`	entrada	Precisión del marcador de parámetro correspondiente. Si `ParameterType` denota una serie binaria o una serie de caracteres de un solo byte (tal como SQL_CHAR, SQL_BLOB), esta es la longitud máxima en bytes del marcador de parámetro. En otro caso, este argumento no se tiene en cuenta.
SQLSMALLINT	`DecimalDigits`	entrada	Escala del correspondiente parámetro si `ParameterType` es SQL_DECIMAL.
SQLPOINTER	`ParameterValuePtr`	entrada (diferido), salida (diferido), o ambos	En la entrada (`InputOutputType` establecido en SQL_PARAM_INPUT o SQL_PARAM_INPUT_OUTPUT): Durante la ejecución, si `StrLen_or_IndPtr` no contiene SQL_NULL_DATA, entonces `ParameterValuePtr` apunta a un almacenamiento intermedio que contiene los datos reales del parámetro. En la salida (InputOutputType establecido en SQL_PARAM_OUTPUT o SQL_PARAM_INPUT_OUTPUT): `ParameterValuePtr` apunta al almacenamiento intermedio donde se almacena el valor del parámetro de salida del procedimiento almacenado. Si `ParameterValuePtr` es nulo, denota la desvinculación del parámetro.
SQLINTEGER	`BufferLength`	entrada	Para datos binarios y de tipo de carácter, `BufferLength` especifica la longitud del almacenamiento intermedio `ParameterValuePtr`. Para datos que no sean binarios ni de tipo carácter, este argumento no se tiene en cuenta y se considera que el almacenamiento intermedio `ParameterValuePtr` tiene la longitud asociada al tipo de datos C. Para parámetros de salida, `BufferLength` se utiliza para determinar si se truncan los datos.
SQLINTEGER *	`StrLen_or_IndPtr`	entrada (diferido), salida (diferido), o ambos	Si es un parámetro de entrada o de entrada/salida: Es el puntero que apunta a la ubicación que contiene (cuando se ejecuta la sentencia) la longitud del valor de marcador de parámetro almacenado en `ParameterValuePtr`. Para especificar un valor nulo para un marcador de parámetro, esta ubicación de almacenamiento debe contener SQL_NULL_DATA. Si `ValueType` es SQL_C_CHAR, esta ubicación de almacenamiento debe contener la longitud exacta de los datos almacenados en `ParameterValuePtr` o SQL_NTS si el contenido de `ParameterValuePtr` termina en nulo. Si contiene la longitud exacta, no se permiten caracteres nulos en los datos almacenados en ParameterValuePtr. Si `ValueType` indica datos de tipo carácter, (explícitamente o implícitamente utilizando SQL_C_DEFAULT) y este puntero se establece en NULL, la aplicación debe proporcionar una serie terminada en nulo en `ParameterValuePtr`. Esto también implica que este marcador de parámetro nunca tiene un valor nulo. Si se trata de un parámetro de salida (`InputOutputType` se establece en SQL_PARAM_OUTPUT): Debe ser un parámetro de salida o un valor de retorno de una llamada (CALL) a un procedimiento almacenado y debe apuntar a uno de los siguientes valores, después de la ejecución del procedimiento almacenado: Número de bytes disponibles a devolver en `ParameterValuePtr`, excluyendo el carácter de terminación en nulo. SQL_NULL_DATA

Uso

Un marcador de parámetro se representa mediante un símbolo ? en una sentencia de SQL y sirve para indicar una posición en la sentencia donde se colocará un valor proporcionado por la aplicación cuando se ejecute la sentencia. Este valor se puede obtener a partir de una variable de aplicación. Se utiliza SQLBindParameter() para enlazar el área de almacenamiento de la aplicación con el marcador de parámetro.

La aplicación debe asociar una variable a cada marcador de parámetro de la sentencia de SQL antes de ejecutarse ésta. Para esta función, ParameterValuePtr y StrLen_or_IndPtr son argumentos diferidos. Las posiciones de almacenamiento deben ser válidas y contener valores de datos de entrada cuando se ejecute la sentencia. Esto significa que la llamada a SQLExecDirect() o a SQLExecute() se debe mantener en el mismo ámbito de procedimiento que las llamadas a SQLBindParameter(), o bien estas posiciones de almacenamiento se deben asignar dinámicamente o declarar de forma estática o global.

Se hace referencia a los marcadores de parámetros por un número (ColumnNumber) y están numerados secuencialmente de izquierda a derecha, comenzando en el 1.

Todos los parámetros enlazados por esta función permanecen en vigor hasta que se invoca una de las funciones siguientes:

Se invoca SQLFreeStmt() con la opción SQL_RESET_PARAMS
Se invoca SQLFreeHandle() con HandleType establecido en SQL_HANDLE_STMT
Se invoca de nuevo SQLBindParameter() para el mismo número de parámetro (ParameterNumber)

Una vez ejecutada la sentencia de SQL y procesados los resultados, la aplicación puede volver a utilizar el descriptor de sentencia para ejecutar otra sentencia de SQL. Si las especificaciones para el marcador de parámetro son diferentes (número de parámetros, longitud o tipo), se debe invocar SQLFreeStmt() con SQL_RESET_PARAMS para restaurar o borrar los enlaces de parámetros.

El tipo de datos del almacenamiento intermedio C indicado por ValueType debe ser compatible con el tipo de datos SQL indicado por ParameterType, de lo contrario se produce un error.

Debido a que los datos contenidos en las variables referenciadas por ParameterValuePtr y StrLen_or_IndPtr no se verifican hasta que se ejecuta la sentencia, los errores de contenido o formato de los datos no se detectan ni notifican hasta que se llama a SQLExecute() o a SQLExecDirect().

Para esta función, ParameterValuePtr y StrLen_or_IndPtr son argumentos diferidos. Cuando InputOutputType está establecido en SQL_PARAM_INPUT, las posiciones de almacenamiento deben ser válidas y contener valores de datos de entrada cuando se ejecute la sentencia. Esto significa que la llamada a SQLExecDirect() o a SQLExecute() se debe mantener en el mismo ámbito de procedimiento que las llamadas a SQLBindParameter(), o bien estas posiciones de almacenamiento se deben asignar dinámicamente o declarar de forma estática o global.

DB2 Everyplace da soporte a SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT y SQL_PARAM_OUTPUT. DB2 Everyplace no da soporte a SQLPutData(), por lo que no se debe colocar el valor del parámetro en el almacenamiento intermedio ParameterValuePtr.

Para datos C binarios y de tipo de carácter, el argumento BufferLength especifica la longitud del almacenamiento intermedio ParameterValuePtr. Para todos los demás tipos de datos C, el argumento BufferLength no se tiene en cuenta.

Códigos de retorno

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnósticos

Tabla 35. SQLSTATE de SQLBindParameter

SQLSTATE	Descripción	Explicación
07006	Conversión no válida.	La conversión desde el valor de datos identificado por el argumento `ValueType` al tipo de datos identificado por el argumento `ParameterType` no es una conversión válida. (Por ejemplo, la conversión desde SQL_C_DATE a SQL_DOUBLE.)
40003 08S01	Error en el enlace de comunicaciones.	El enlace de comunicaciones entre la aplicación y la fuente de datos se interrumpió antes de finalizar la función.
58004	Error inesperado del sistema.	Error no recuperable del sistema.
HY001	Error de asignación de memoria.	DB2 CLI no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY003	Tipo de programa fuera de rango.	El valor especificado por el argumento `ParameterNumber` no es un tipo de datos válido ni SQL_C_DEFAULT.
HY004	Tipo de datos SQL fuera de rango.	El valor especificado para el argumento `ParameterType` no es un tipo válido de datos SQL.
HY009	Valor no válido de argumento.	El argumento `ParameterValuePtr` es un puntero nulo y el argumento `StrLen_or_IndPtr` es un puntero nulo e `InputOutputType` no es SQL_PARAM_OUTPUT.
HY013	Error inesperado de gestión de la memoria.	DB2 CLI no puede acceder a la memoria necesaria para ejecutar o finalizar la función.
HY090	Longitud no válida de la serie de caracteres o del almacenamiento intermedio.	El valor especificado para el argumento `BufferLength` era menor que 0.
HY093	Número de parámetros no válido.	El valor especificado para el argumento `ValueType` es menor que uno o mayor que el número máximo de parámetros soportado por el servidor.
HY094	Valor no válido de escala.	El valor especificado para `ParameterType` es SQL_DECIMAL o SQL_NUMERIC y el valor especificado para `DecimalDigits` es menor que 0 o mayor que el valor del argumento `ParamDef` (precisión).
HY104	Valor no válido de precisión.	El valor especificado para `ParameterType` es SQL_DECIMAL o SQL_NUMERIC y el valor especificado para `ParamDef` es menor que uno.
HY105	Tipo de parámetro no válido.	`InputOutputType` no es SQL_PARAM_INPUT.
HYC00	Controlador no apropiado.	CLI de DB2 o la fuente de datos no da soporte a la conversión especificada por la combinación del valor especificado para el argumento `ValueType` y el valor especificado para el argumento `ParameterType`. El valor especificado para el argumento `ParameterType` no está soportado por CLI de DB2 o por la fuente de datos.

Consulta relacionada