Usar valores de indicador e de comprimento

  • Artigo

O buffer de comprimento/indicador é usado para passar o comprimento de byte dos dados no buffer de dados ou um indicador especial, como SQL_NULL_DATA, que indica que os dados são NULL. Dependendo da função na qual ele é usado, um buffer de comprimento/indicador é definido como um SQLINTEGER ou um SQLSMALLINT. Portanto, um só argumento é necessário para descrevê-lo. Se o buffer de dados for um buffer de entrada não adiado, esse argumento conterá o comprimento do byte dos dados em si ou um valor de indicador. Muitas vezes é chamado StrLen_or_Ind ou um nome semelhante. Por exemplo, o código a seguir chama SQLPutData para passar um buffer cheio de dados: o comprimento do byte (ValueLen) é passado diretamente porque o buffer de dados (ValuePtr) é um buffer 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);

Se o buffer de dados for um buffer de entrada adiado, um buffer de saída não adiado ou um buffer de saída, o argumento conterá o endereço do buffer de comprimento/indicador. Ele costuma se chamar StrLen_or_Ind ou um nome semelhante. Por exemplo, o código a seguir chama SQLGetData para recuperar um buffer cheio de dados. O comprimento do byte é retornado ao aplicativo no buffer de comprimento/indicador (ValueLenOrInd), cujo endereço é passado para SQLGetData porque o buffer de dados correspondente (ValuePtr) é um buffer de saída não adiado.

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

A menos que seja especificamente proibido, um argumento de buffer de comprimento/indicador poderá ser 0 (se entrada não adiada) ou um ponteiro nulo (se saída ou entrada adiada). Para buffers de entrada, isso faz o driver ignorar o comprimento do byte dos dados. Isso retorna um erro ao passar dados de comprimento variável, mas é comum ao passar dados de comprimento fixo não nulos, pois nem um comprimento nem um valor de indicador é necessário. Para buffers de saída, isso faz com que o driver não retorne o comprimento de byte dos dados ou um valor de indicador. Isso será um erro se os dados retornados pelo driver forem NULL, mas é comum ao recuperar dados de comprimento fixo e não anuláveis, pois nem um comprimento nem um valor de indicador é necessário.

Como quando o endereço de um buffer de dados adiado é passado para o driver, o endereço de um buffer de comprimento/indicador adiado deve continuar válido até o buffer ser desassociado.

Os seguintes comprimentos são válidos como valores de comprimento/indicador:

  • n, em que n> 0.

  • SQL_NTS. Uma cadeia de caracteres enviada ao driver no buffer de dados correspondente é terminada em nulo. Essa é uma forma conveniente de programadores C passarem cadeias de caracteres sem precisarem calcular o comprimento de byte. Esse valor é legal apenas quando o aplicativo envia os dados para o driver. Quando o driver retorna os dados para o aplicativo, ele sempre retorna o comprimento de byte real dos dados.

Os seguintes valores são válidos como valores de comprimento/indicador: SQL_NULL_DATA é armazenado no campo descritor SQL_DESC_INDICATOR_PTR. Todos os outros valores são armazenados no campo descritor SQL_DESC_OCTET_LENGTH_PTR.

  • SQL_NULL_DATA. Os dados são um valor de dados NULL e o valor no buffer de dados correspondente é ignorado. Esse valor é legal apenas para dados SQL que o driver enviou ou recuperou.

  • SQL_DATA_AT_EXEC. O buffer de dados não contém nenhum dado. Em vez disso, os dados serão enviados com SQLPutData quando a instrução for executada ou quando SQLBulkOperations ou SQLSetPos for chamado. Esse valor é legal somente para dados SQL enviados ao driver. Para obter mais informações, confira SQLBindParameter, SQLBulkOperations e SQLSetPos.

  • Resultado da macro SQL_LEN_DATA_AT_EXEC(length). Esse valor é parecido com SQL_DATA_AT_EXEC. Para obter mais informações, confira Como enviar dados longos.

  • SQL_NO_TOTAL. O driver não consegue determinar o número de bytes de dados longos ainda disponíveis para retornar em um buffer de saída. Esse valor é legal somente para dados SQL recuperados do driver.

  • SQL_DEFAULT_PARAM. Um procedimento é usar o valor padrão de um parâmetro de entrada em um procedimento, em vez do valor no buffer de dados correspondente.

  • SQL_COLUMN_IGNORE. SQLBulkOperations ou SQLSetPos é ignorar o valor no buffer de dados. Ao atualizar uma linha de dados por uma chamada para SQLBulkOperations ou SQLSetPos, o valor da coluna não muda. Ao inserir uma linha de dados por uma chamada para SQLBulkOperations, o valor da coluna é definido como padrão ou, se a coluna não tiver um padrão, como NULL.