Compartir vía


Enviar datos de tipo Long

DbMS definen datos largos como cualquier carácter o datos binarios en un tamaño determinado, como 254 caracteres. Es posible que no sea posible almacenar un elemento completo de datos largos en memoria, como cuando el elemento representa un documento de texto largo o un mapa de bits. Dado que estos datos no se pueden almacenar en un único búfer, el origen de datos lo envía al controlador en partes con SQLPutData cuando se ejecuta la instrucción. Los parámetros para los que se envían datos durante la ejecución se conocen como parámetros de datos en ejecución.

Nota:

En realidad, una aplicación puede enviar cualquier tipo de datos en tiempo de ejecución con SQLPutData, aunque solo se pueden enviar datos binarios y de caracteres en partes. Sin embargo, si los datos son lo suficientemente pequeños como para caber en un solo búfer, por lo general no hay ninguna razón para usar SQLPutData. Es mucho más fácil enlazar el búfer y permitir que el controlador recupere los datos del búfer.

Para enviar datos en tiempo de ejecución, la aplicación realiza las siguientes acciones:

  1. Pasa un valor de 32 bits que identifica el parámetro en el argumento ParameterValuePtr en SQLBindParameter en lugar de pasar la dirección de un búfer. El controlador no analiza este valor. Se devolverá a la aplicación más adelante, por lo que debe significar algo para la aplicación. Por ejemplo, podría ser el número del parámetro o el identificador de un archivo que contiene datos.

  2. Pasa la dirección de un búfer de longitud o indicador en el argumentoStrLen_or_IndPtr de SQLBindParameter.

  3. Almacena SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC(longitud) en el búfer de longitud o indicador. Ambos valores indican al controlador que los datos del parámetro se enviarán con SQLPutData. SQL_LEN_DATA_AT_EXEC(longitud) se usa al enviar datos largos a un origen de datos que necesita saber cuántos bytes de datos largos se enviarán para que pueda asignar previamente espacio. Para determinar si un origen de datos requiere este valor, la aplicación llama a SQLGetInfo con la opción SQL_NEED_LONG_DATA_LEN. Todos los controladores deben admitir esta macro; Si el origen de datos no requiere la longitud de bytes, el controlador puede omitirlo.

  4. Llama a SQLExecute o SQLExecDirect. El controlador detecta que un búfer de longitud o indicador contiene el valor SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC(longitud) y devuelve SQL_NEED_DATA como valor devuelto de la función.

  5. Llama a SQLParamData en respuesta al valor SQL_NEED_DATA devuelto. Si es necesario enviar datos largos, SQLParamData devuelve SQL_NEED_DATA. En el búfer al que apunta el argumento ValuePtrPtr , el controlador devuelve el valor que identifica el parámetro data-at-execution. Si hay más de un parámetro de datos en ejecución, la aplicación debe usar este valor para determinar qué parámetro enviar datos; El controlador no es necesario para solicitar datos para los parámetros de datos en ejecución en cualquier orden determinado.

  6. Llama a SQLPutData para enviar los datos de parámetro al controlador. Si los datos del parámetro no caben en un único búfer, como sucede con los datos largos, la aplicación llama a SQLPutData repetidamente para enviar los datos en partes; es hasta el controlador y el origen de datos para volver a ensamblar los datos. Si la aplicación pasa datos de cadena terminadas en NULL, el controlador o el origen de datos deben quitar el carácter de terminación NULL como parte del proceso de reensamblaje.

  7. Llama a SQLParamData de nuevo para indicar que ha enviado todos los datos del parámetro . Si hay parámetros de datos en ejecución para los que no se han enviado datos, el controlador devuelve SQL_NEED_DATA y el valor que identifica el parámetro siguiente; la aplicación vuelve al paso 6. Si se han enviado datos para todos los parámetros de datos en ejecución, se ejecuta la instrucción . SQLParamData devuelve SQL_SUCCESS o SQL_SUCCESS_WITH_INFO y puede devolver cualquier valor devuelto o diagnóstico que SQLExecute o SQLExecDirect pueda devolver.

Después de que SQLExecute o SQLExecDirect devuelva SQL_NEED_DATA y antes de que los datos se hayan enviado por completo para el último parámetro de datos en ejecución, la instrucción se encuentra en un estado Need Data. Aunque una instrucción está en un estado Need Data, la aplicación solo puede llamar a SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField o SQLGetDiagRec; todas las demás funciones devuelven SQLSTATE HY010 (error de secuencia de funciones). Al llamar a SQLCancel se cancela la ejecución de la instrucción y se devuelve a su estado anterior. Para obtener más información, vea Apéndice B: Tablas de transición de estado ODBC.

Para obtener un ejemplo de envío de datos en tiempo de ejecución, consulte la descripción de la función SQLPutData.