Envío de datos largos

DbMS define 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 los datos en tiempo de 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 argumento StrLen_or_IndPtr de SQLBindParameter.

3. Almacena SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC(length) 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(length) 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/indicador contiene el valor SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC(length) y devuelve SQL_NEED_DATA como valor devuelto de la función.

5. Llama a SQLParamData en respuesta al valor devuelto SQL_NEED_DATA. 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 de datos en ejecución. Si hay más de un parámetro de datos durante la ejecución, la aplicación debe usar este valor para determinar para qué parámetro enviar datos; no se requiere que el controlador solicite datos para los parámetros de datos durante la ejecución en un orden específico.

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 suele ocurrir con datos largos, la aplicación llama a SQLPutData repetidamente para enviar los datos en partes; corresponde al controlador y al origen de datos reensamblar 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 el momento de la 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. Mientras 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 retorna 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 .