DOC: Explicação dos argumentos de comprimento para funções de Unicode ODBC

O Gestor do controlador de ODBC versão 3.5 ou posterior suporta versões ANSI e Unicode avançados do todas as funções que aceitam apontadores para cadeias de caracteres ou SQLPOINTER nos respectivos argumentos. As funções de Unicode são implementadas como funções com um sufixo "W", como, por exemplo, SQLExecDirectW e SQLGetInfoW .

Para muitas destas funções de Unicode, referência a ODBC Programmer fornece descrições incorrectas ou ambíguas para alguns argumentos de função. Especificamente, este problema está relacionado com os argumentos que são utilizados para especificar o comprimento de caracteres da cadeia valores de entrada e saídos.

Os problemas na documentação do ODBC envolvem se um argumento de comprimento deve especificar o número de bytes ou o número de caracteres de uma cadeia de entrada ou saída. Para a versão ANSI destas funções, a contagem de bytes numa cadeia é igual a contagem de caracteres (porque caracteres ANSI ocupam apenas um byte cada), para os termos "bytes" e "caracteres" possam eficazmente ser utilizados alternadamente. No entanto, com cadeias Unicode, cada carácter ocupa dois bytes. Por conseguinte, é muito importante distinguir se entradas de comprimento para uma função de Unicode tem de especificar uma contagem de bytes ou caracteres.

Em alguns casos, a documentação utiliza a palavra "bytes" quando a palavra "caracteres" deve ter sido utilizada em vez disso. Noutros casos, a documentação não é necessariamente incorrecta mas Especifica um "período" de uma cadeia é necessário, sem explicitamente documentar se este valor deve ser uma contagem de bytes ou uma contagem de caracteres.

Independentemente do que a documentação indica para cada função ODBC, o parágrafo seguinte da secção Unicode de "Capítulo 17: Programming considerações" de referência para programadores de ODBC é a regra final para argumentos de comprimento em Unicode funções: Isto significa que, se o argumento em questão descreve o comprimento de outro argumento que é sempre uma cadeia (normalmente, representada como uma SQLCHAR), em seguida, o comprimento reflecte o número de caracteres da cadeia. Se o argumento de comprimento descreve outro argumento que pode ser uma cadeia ou outro tipo de dados (normalmente, representado como uma SQLPOINTER), o comprimento é em bytes.

A tabela seguinte lista todas as funções API do ODBC que tenham versões Unicode. Para cada função listada, a tabela realça os problemas conhecidos na documentação do ODBC e fornece uma descrição mais completa dos argumentos período em questão.


Utilizando o exemplo SQLDriverConnect da tabela acima, os argumentos InConnectionString e OutConnectionString são ambas definidas como SQLCHAR * para que StringLength1 e BufferLength devem indicar o número de caracteres de cadeias. Em contrapartida, considere a função SQLGetInfo . Esta função tem uma entrada de InfoValuePtr e o comprimento desta entrada é passado em BufferLength . Uma vez que InfoValuePtr podem conter cadeias e outros tipos de dados, é um SQLPOINTER. Assim, aplicar as regras descritas acima, BufferLength será uma contagem de bytes, em vez de caracteres.

O artigo da base de dados de conhecimento da Microsoft seguinte contém informações sobre o problema acima que já tenha sido corrigido para a documentação SQLGetDiagRecW :