Uso de longitud y valores de indicador

El búfer de longitud o indicador se usa para pasar la longitud de bytes de los datos en el búfer de datos o un indicador especial, como SQL_NULL_DATA, que indica que los datos son NULL. Dependiendo de la función en la que se usa, se define un búfer de longitud o indicador como SQLINTEGER o SQLSMALLINT. Por lo tanto, se necesita un único argumento para describirlo. Si el búfer de datos es un búfer de entrada no deducido, este argumento contiene la longitud de bytes de los datos en sí o un valor de indicador. A menudo se denomina StrLen_or_Ind o un nombre similar. Por ejemplo, el código siguiente llama a SQLPutData para pasar un búfer lleno de datos; la longitud de bytes (ValueLen) se pasa directamente porque el búfer de datos (ValuePtr) es un búfer de entrada.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLen;  
  
// Call local function to place data in ValuePtr. In ValueLen, return the  
// number of bytes of data placed in ValuePtr. If there is not enough  
// data, this will be less than 50.  
FillBuffer(ValuePtr, sizeof(ValuePtr), &ValueLen);  
  
// Call SQLPutData to send the data to the driver.  
SQLPutData(hstmt, ValuePtr, ValueLen);  

Si el búfer de datos es un búfer de entrada diferido, un búfer de salida no diferido o un búfer de salida, el argumento contiene la dirección del búfer de longitud o indicador. A menudo se denomina StrLen_or_IndPtr o un nombre similar. Por ejemplo, el código siguiente llama a SQLGetData para recuperar un búfer lleno de datos; la longitud de bytes se devuelve a la aplicación en el búfer de longitud/indicador (ValueLenOrInd), cuya dirección se pasa a SQLGetData porque el búfer de datos correspondiente (ValuePtr) es un búfer de salida no deducido.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLenOrInd;  
SQLGetData(hstmt, 1, SQL_C_CHAR, ValuePtr, sizeof(ValuePtr), &ValueLenOrInd);  

A menos que esté prohibido específicamente, un argumento de búfer de longitud/indicador puede ser 0 (si no se deduce la entrada) o un puntero nulo (si la salida o la entrada diferida). En el caso de los búferes de entrada, esto hace que el controlador omita la longitud de bytes de los datos. Esto devuelve un error al pasar datos de longitud variable, pero es común al pasar datos que no son NULL y de longitud fija, ya que no se necesita una longitud ni un valor de indicador. En el caso de los búferes de salida, esto hace que el controlador no devuelva la longitud de bytes de los datos o un valor de indicador. Se trata de un error si los datos devueltos por el controlador son NULL, pero son comunes al recuperar datos de longitud fija y que no aceptan valores NULL, ya que no se necesita una longitud ni un valor de indicador.

Como cuando la dirección de un búfer de datos diferido se pasa al controlador, la dirección de un búfer de longitud o indicador diferido debe permanecer válida hasta que el búfer se desenlade.

Las longitudes siguientes son válidas como valores de longitud o indicador:

• n, donde n> 0.

• SQL_NTS. Una cadena enviada al controlador en el búfer de datos correspondiente está terminada en null; se trata de una manera cómoda para que los programadores de C pasen cadenas sin tener que calcular su longitud de bytes. Este valor es legal solo cuando la aplicación envía datos al controlador. Cuando el controlador devuelve datos a la aplicación, siempre devuelve la longitud real de bytes de los datos.

Los valores siguientes son válidos como valores de longitud o indicador. SQL_NULL_DATA se almacena en el campo descriptor de SQL_DESC_INDICATOR_PTR; todos los demás valores se almacenan en el campo descriptor de SQL_DESC_OCTET_LENGTH_PTR.

• SQL_NULL_DATA. Los datos son un valor de datos NULL y se omite el valor del búfer de datos correspondiente. Este valor solo es legal para los datos SQL enviados a o recuperados del controlador.

• SQL_DATA_AT_EXEC. El búfer de datos no contiene ningún dato. En su lugar, los datos se enviarán con SQLPutData cuando se ejecute la instrucción o cuando se llame a SQLBulkOperations o SQLSetPos . Este valor solo es legal para los datos SQL enviados al controlador. Para obtener más información, vea SQLBindParameter, SQLBulkOperations y SQLSetPos.

• Resultado de la macro SQL_LEN_DATA_AT_EXEC(longitud). Este valor es similar a SQL_DATA_AT_EXEC. Para más información, consulte Envío de datos largos.

• SQL_NO_TOTAL. El controlador no puede determinar el número de bytes de datos largos que todavía están disponibles para devolverse en un búfer de salida. Este valor solo es legal para los datos SQL recuperados del controlador.

• SQL_DEFAULT_PARAM. Un procedimiento consiste en usar el valor predeterminado de un parámetro de entrada en un procedimiento en lugar del valor en el búfer de datos correspondiente.

• SQL_COLUMN_IGNORE. SQLBulkOperations o SQLSetPos para omitir el valor en el búfer de datos. Al actualizar una fila de datos mediante una llamada a SQLBulkOperations o SQLSetPos, el valor de columna no cambia. Al insertar una nueva fila de datos mediante una llamada a SQLBulkOperations, el valor de columna se establece en su valor predeterminado o, si la columna no tiene un valor predeterminado, en NULL.