Función SQLParamData

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92

Resumen
SQLParamData se usa junto con SQLPutData para proporcionar datos de parámetros en tiempo de ejecución de instrucciones y con SQLGetData para recuperar datos de parámetros de salida transmitidos.

Sintaxis

  
SQLRETURN SQLParamData(  
     SQLHSTMT       StatementHandle,  
     SQLPOINTER *   ValuePtrPtr);  

Argumentos

StatementHandle
[Entrada] Identificador de instrucción.

ValuePtrPtr
[Salida] Puntero a un búfer en el que devolver la dirección del búfer ParameterValuePtr especificado en SQLBindParameter (para los datos de parámetros) o la dirección del búfer TargetValuePtr especificado en SQLBindCol (para los datos de columna), tal como se encuentra en el campo de registro del descriptor de SQL_DESC_DATA_PTR.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE o SQL_PARAM_DATA_AVAILABLE.

Diagnóstico

Cuando SQLParamData 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 SQLParamData 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 valor de datos identificado por el argumento ValueType en SQLBindParameter para el parámetro enlazado no se pudo convertir en el tipo de datos identificado por el argumento ParameterType en SQLBindParameter. El valor de datos devuelto para un parámetro enlazado como SQL_PARAM_INPUT_OUTPUT o SQL_PARAM_OUTPUT no se pudo convertir al tipo de datos identificado por el argumento ValueType en SQLBindParameter. (Si los valores de datos de una o varias filas no se pudieron convertir, pero una o varias filas se devolvieron correctamente, esta función devuelve SQL_SUCCESS_WITH_INFO).
08S01	Error de vínculo de comunicación	Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento.
22026	Datos de cadena, desigualdad de longitud	El tipo de información SQL_NEED_LONG_DATA_LEN en SQLGetInfo era "Y" y se enviaron menos datos para un parámetro long (el tipo de datos se SQL_LONGVARCHAR, SQL_LONGVARBINARY o un tipo de datos largo específico del origen de datos) que se especificó con el argumento StrLen_or_IndPtr en SQLBindParameter. El tipo de información de SQL_NEED_LONG_DATA_LEN en SQLGetInfo era "Y" y se enviaron menos datos para una columna larga (el tipo de datos se SQL_LONGVARCHAR, SQL_LONGVARBINARY o un tipo de datos largo específico del origen de datos) que se especificó en el búfer de longitud correspondiente a una columna de una fila de datos que se agregó o actualizó con SQLBulkOperations o se actualizó con SQLSetPos.
40001	Error de serialización	La transacción se revierte debido a un interbloqueo de recursos con otra transacción.
40003	Finalización de instrucciones desconocida	Error en la conexión asociada durante la ejecución de esta función y no se puede determinar el estado de la transacción.
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.
HY008	Operación cancelada	El procesamiento asincrónico se ha habilitado para StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle; Después, se llamó a la función de nuevo en StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso.
HY010	Error de secuencia de función	(DM) La llamada a función anterior no era una llamada a SQLExecDirect, SQLExecute, SQLBulkOperations o SQLSetPos donde se SQL_NEED_DATA el código de retorno o la llamada de función anterior era una llamada a SQLPutData. La llamada de función anterior era una llamada a SQLParamData. (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 la función SQLParamData . (DM) Se llamó a una función de ejecución asincrónica (no esta) para statementHandle y todavía se estaba ejecutando cuando se llamó a esta función. Se llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para la instrucciónHandle y devolvió SQL_NEED_DATA. Se llamó a SQLCancel antes de enviar los 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 acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY117	La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura.	(DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
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 a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	El controlador no admite esta función	(DM) El controlador que corresponde a StatementHandle no admite la función .
IM017	El sondeo está deshabilitado en modo de notificación asincrónica	Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado.
IM018	No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador.	Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación.

Si se llama a SQLParamData al enviar datos para un parámetro en una instrucción SQL, puede devolver cualquier SQLSTATE que pueda devolver la función llamada para ejecutar la instrucción (SQLExecute o SQLExecDirect). Si se llama al enviar datos para una columna que se actualiza o se agrega con SQLBulkOperations o se actualiza con SQLSetPos, puede devolver cualquier SQLSTATE que SQLBulkOperations o SQLSetPos pueda devolver.

Comentarios

Se puede llamar a SQLParamData para proporcionar datos en ejecución para dos usos: datos de parámetros que se usarán en una llamada a SQLExecute o SQLExecDirect, o datos de columna que se usarán cuando una fila se actualiza o agrega mediante una llamada a SQLBulkOperations o se actualiza mediante una llamada a SQLSetPos. En tiempo de ejecución, SQLParamData vuelve a la aplicación un indicador de los datos que requiere el controlador.

Cuando una aplicación llama a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos, el controlador devuelve SQL_NEED_DATA si necesita datos en ejecución. A continuación, una aplicación llama a SQLParamData para determinar qué datos se van a enviar. Si el controlador requiere datos de parámetros, el controlador devuelve en el búfer de salida *ValuePtrPtr , el valor que la aplicación coloca en el búfer del conjunto de filas. La aplicación puede usar este valor para determinar qué datos de parámetro solicita el controlador. Si el controlador requiere datos de columna, el controlador devuelve en el búfer *ValuePtrPtr la dirección a la que se enlazaba originalmente la columna, como se indica a continuación:

Dirección + enlazada Desplazamiento de enlace + ((Número de fila - 1) x Tamaño del elemento)

donde las variables se definen como se indica en la tabla siguiente.

Variable	Descripción
Dirección enlazada	Dirección especificada con el argumento TargetValuePtr en SQLBindCol.
Desplazamiento de enlace	Valor almacenado en la dirección especificada con el atributo de instrucción SQL_ATTR_ROW_BIND_OFFSET_PTR.
Row Number	Número basado en 1 de la fila del conjunto de filas. Para las capturas de una sola fila, que son el valor predeterminado, es 1.
Tamaño del elemento	Valor del atributo de instrucción SQL_ATTR_ROW_BIND_TYPE para los búferes de datos y longitud o indicador.

También devuelve SQL_NEED_DATA, que es un indicador de la aplicación que debe llamar a SQLPutData para enviar los datos.

La aplicación llama a SQLPutData tantas veces como sea necesario para enviar los datos en ejecución para la columna o parámetro. Una vez enviados todos los datos para la columna o el parámetro, la aplicación vuelve a llamar a SQLParamData . Si SQLParamData devuelve de nuevo SQL_NEED_DATA, se deben enviar datos para otro parámetro o columna. Por lo tanto, la aplicación llama de nuevo a SQLPutData. Si se han enviado todos los datos en ejecución para todos los parámetros o columnas, SQLParamData devuelve SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el valor de *ValuePtrPtr es indefinido y la instrucción SQL se puede ejecutar o se puede ejecutar la llamada SQLBulkOperations o SQLSetPos .

Si SQLParamData proporciona datos de parámetros para una instrucción de actualización o eliminación buscada que no afecta a ninguna fila en el origen de datos, la llamada a SQLParamData devuelve SQL_NO_DATA.

Para obtener más información sobre cómo se pasan los datos de parámetros de ejecución en tiempo de ejecución de instrucciones, vea "Pasar valores de parámetro" en SQLBindParameter y Enviar datos largos. Para obtener más información sobre cómo se actualizan o agregan datos de columna de datos en ejecución, vea la sección "Using SQLSetPos" in SQLSetPos, "Performing Bulk Novedades Using Bookmarks" in SQLBulkOperations, and Long Data and SQLSetPos and SQLBulkOperations.

Se puede llamar a SQLParamData para recuperar parámetros de salida transmitidos. Cuando SQLMoreResults, SQLExecute, SQLGetData o SQLExecDirect devuelve SQL_PARAM_DATA_AVAILABLE, llame a SQLParamData para determinar qué parámetro tiene un valor 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.

Ejemplo de código

Consulte SQLPutData.

Funciones relacionadas

Para información acerca de	Vea
Enlace de un búfer a un parámetro	Función SQLBindParameter
Cancelación del procesamiento de instrucciones	Función SQLCancel
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
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