Comprimento de dados, comprimento do buffer e truncamento

O comprimento de dados é o tamanho em bytes dos dados como eles seriam armazenados no buffer de dados do aplicativo, não como eles são armazenados na fonte de dados. Essa distinção é importante porque os dados geralmente são armazenados em tipos diferentes no buffer de dados e na fonte de dados. Portanto, para dados que estão sendo enviados à fonte de dados, esse é o tamanho em bytes dos dados antes da conversão para o tipo da fonte de dados. Para os dados que estão sendo recuperados da fonte de dados, esse é o tamanho em bytes dos dados após a conversão para o tipo do buffer de dados e antes de qualquer truncamento.

Para dados de comprimento fixo, como um inteiro ou uma estrutura de data, o tamanho em bytes é sempre o tamanho do tipo de dado. Em geral, os aplicativos alocam um buffer de dados que é o tamanho do tipo de dado. Se o aplicativo alocar um buffer menor, não é possível definir as consequências, já que o driver assume que o buffer de dados é do tamanho do tipo de dado e não trunca os dados para se ajustarem em um buffer menor. Se o aplicativo alocar um buffer maior, o espaço extra nunca será usado.

Para dados de comprimento variável, como dados de caracteres ou binários, é importante reconhecer que o tamanho em bytes dos dados é separado e, geralmente, diferente do tamanho em bytes do buffer. A relação desses dois comprimentos é descrita na seção Buffers. Se o tamanho em bytes dos dados for maior que o tamanho em bytes do buffer, o driver truncará os dados buscados para o tamanho em bytes do buffer e retornará SQL_SUCCESS_WITH_INFO com SQLSTATE 01004 (Dados truncados). No entanto, o tamanho em bytes retornado é o tamanho dos dados não truncados.

Por exemplo, suponha que um aplicativo aloca 50 bytes para um buffer de dados binário. Se o driver tiver 10 bytes de dados binários para retornar, ele retornará esses 10 bytes no buffer. O tamanho em bytes dos dados é 10 e o tamanho em bytes do buffer é 50. Se o driver tiver 60 bytes de dados binários para retornar, ele truncará os dados para 50 bytes, retornará esses bytes no buffer e retornará SQL_SUCCESS_WITH_INFO. O tamanho em bytes dos dados é 60 (antes do truncamento) e o tamanho em bytes do buffer ainda é 50.

Um registro de diagnóstico é criado para cada coluna truncada. Como leva tempo para o driver criar esses registros e para o aplicativo processá-los, o truncamento pode prejudicar o desempenho. Normalmente, um aplicativo pode evitar esse problema alocando buffers grandes o suficiente, embora isso possa não ser possível ao trabalhar com dados Longos. Quando ocorre o truncamento de dados, o aplicativo pode às vezes alocar um buffer maior e buscar novamente os dados, mas essa não é a regra em todos os casos. Se o truncamento ocorrer durante a obtenção de dados com chamadas para SQLGetData, o aplicativo não precisará chamar SQLGetData para dados que já foram retornados. Para obter mais informações, consulte Obter dados Longos.