Diretrizes de programação

Baixar driver ODBC

Este artigo descreve considerações de programação para aplicações que utilizam o Microsoft ODBC Driver for SQL Server em Linux ou macOS. Alguns links apontam para material do SQL Server Native Client. Estas páginas fornecem contexto histórico da API.

Escolha uma versão do driver

Use o Microsoft ODBC Driver 18 para SQL Server, a linha de drivers atual, para novos desenvolvimentos. O Microsoft ODBC Driver 17 para SQL Server continua suportado para aplicações que já o implementam, conforme descrito no ciclo de vida do suporte. O ODBC Driver 13, que foi incluído com o SQL Server 2017, é elegível para suporte alargado até 12 de outubro de 2027, apenas ao abrigo de um acordo de suporte alargado.

Especifique o nome do driver instalado na sua cadeia de ligação, colocado entre chavetas:

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

Num nome de fonte de dados (DSN) em odbc.ini, use o nome sem chavetas, por exemplo Driver = ODBC Driver 18 for SQL Server. Para a sintaxe DSN, veja Palavras-chave de cadeia de ligação e nomes de fontes de dados (DSNs).

Para definições de ligação específicas da versão, veja Diferenças principais de versão. Para datas de suporte e compatibilidade do sistema operativo, consulte o ciclo de vida do suporte e os requisitos do sistema.

Criar uma aplicação

Para a localização dos ficheiros de cabeçalho, incluindo ordem, comandos do compilador, nomes de bibliotecas e um exemplo de C++, consulte Desenvolver aplicações C e C++ com o controlador ODBC e Ligar e consultar com C++ e ODBC.

Uma aplicação ODBC pode usar Múltiplos Conjuntos de Resultados Ativos (MARS) e outras funcionalidades específicas do SQL Server, incluindo msodbcsql.h após os cabeçalhos unixODBC (sql.h, sqlext.h, sqltypes.h, e sqlucode.h). Utilize os mesmos nomes simbólicos para itens específicos do SQL Server que utiliza nas aplicações ODBC do Windows.

Localizar capacidades do controlador

Comece com a Referência do Programador ODBC para a interface padrão de programação de aplicações (API). Depois usa a documentação atual do driver para o comportamento específico do driver.

A visão geral do Microsoft ODBC Driver for SQL Server remete para a documentação do driver. Os seguintes artigos do SQL Server Native Client fornecem contexto de API para aplicações que utilizam o driver em Linux e macOS:

Limitations

As seguintes funcionalidades não foram verificadas para funcionar corretamente no driver ODBC em Linux e macOS:

Funcionalidades não suportadas

As seguintes funcionalidades não estão disponíveis no driver ODBC no Linux e macOS:

  • Transações distribuídas através do atributo SQL_ATTR_ENLIST_IN_DTC. O driver suporta transações XA através do Coordenador de Transações Distribuídas da Microsoft (DTC). Para mais informações, consulte Usar transações XA com DTC.

  • Espelhamento de banco de dados.

  • FILESTREAM.

  • Perfilamento do desempenho do driver ODBC, abordado em SQLSetConnectAttr, e estes atributos de ligação relacionados com o desempenho:

    • SQL_COPT_SS_PERF_DATA
    • SQL_COPT_SS_PERF_DATA_LOG
    • SQL_COPT_SS_PERF_DATA_LOG_NOW
    • SQL_COPT_SS_PERF_QUERY
    • SQL_COPT_SS_PERF_QUERY_INTERVAL
    • SQL_COPT_SS_PERF_QUERY_LOG

  • SQLBrowseConnect antes da versão 17.2.

  • Tipos de intervalo C como SQL_C_INTERVAL_YEAR_TO_MONTH, documentados em Identificadores e Descriptores de Tipo de Dados.

  • O SQL_CUR_USE_ODBC valor do atributo SQL_ATTR_ODBC_CURSORS de SQLSetConnectAttr.

Processar dados de caracteres

No Linux e macOS, use buffers UTF-16 SQLWCHAR com APIs ODBC de caracteres largos em vez do tipo nativo wchar_t. A interface do controlador utiliza unidades de código de 16 bits.

Codificações de caracteres

Para os drivers ODBC 13 e 13.1, deve usar UTF-8 para dados SQLCHAR. Estas versões não suportam outras codificações.

A partir do Driver ODBC 17, conjuntos de caracteres e codificações suportados para SQLCHAR dados incluem:

Observação

Devido a iconv diferenças entre musl e glibc, muitas destas localizações não são suportadas no Alpine Linux. Para mais informações, veja Diferenças funcionais em relação ao glibc.

Nome Description
UTF-8 Unicode
CP437 MS-DOS Latino-EUA
CP850 MS-DOS Latim 1
CP874 Latim/Tailandês
CP932 Japonês (página de códigos do Windows 932)
CP936 Chinês simplificado, GBK
CP949 Coreano (página de códigos do Windows 949)
CP950 Chinês Tradicional, Big5
CP1250 Centro-Europeu
CP1251 Cirílico
CP1252 Europa Ocidental
CP1253 Grego
CP1254 Turco (língua)
CP1255 Hebraico
CP1256 Árabe
CP1257 Báltico
CP1258 Vietnamita
ISO-8859-1 Latin-1
ISO-8859-2 Latin-2
ISO-8859-3 Latin-3
ISO-8859-4 Latin-4
ISO-8859-5 Latim/Cirílico
ISO-8859-6 Latim/Árabe
ISO-8859-7 Latim/Grego
ISO-8859-8 Hebraico
ISO-8859-9 Turco (língua)
ISO-8859-13 Latin-7
ISO-8859-15 Latin-9

Quando se liga, o driver deteta a configuração regional atual do processo em que está carregado. Se a configuração regional usar uma das codificações listadas, o driver usa essa codificação para dados de SQLCHAR (caracteres estreitos). Caso contrário, por defeito é UTF-8. Os processos iniciam-se na C locale por predefinição, o que faz com que o driver passe automaticamente para UTF-8. Se uma aplicação precisar de uma das codificações listadas, chame setlocale antes de estabelecer ligação. Especifique explicitamente a configuração regional, ou use uma cadeia vazia (por exemplo, setlocale(LC_ALL, "")) para usar as definições de configuração regional do ambiente.

Num ambiente típico Linux ou macOS onde a codificação é UTF-8, os utilizadores do ODBC Driver 17 que atualizam a partir do 13 ou 13.1 não notarão diferenças. Aplicações que utilizam uma codificação setlocale listada que não seja UTF-8 precisam de usar essa codificação para dados de e para o driver em vez de UTF-8.

Tens de usar UTF-16LE (little endian) para dados SQLWCHAR.

Quando atribui parâmetros de entrada usando SQLBindParameter, se especificar um tipo SQL de caracteres estreitos como SQL_VARCHAR, o driver converte os dados fornecidos da codificação do cliente para a codificação do lado do servidor para esse parâmetro. A codificação depende da ordenação; nem sempre é a página de código 1252. Para os parâmetros de saída, o driver converte da codificação especificada nas informações de ordenação associadas aos dados para a codificação do cliente. Caracteres na codificação de origem que não são representáveis na codificação de destino convertem-se num ponto de interrogação (?).

Para evitar esta perda de dados ao atribuir parâmetros de entrada, especifique um tipo de carácter SQL Unicode, como SQL_WVARCHAR. O driver converte a codificação do cliente para UTF-16, que pode representar todos os caracteres Unicode. A coluna ou parâmetro alvo deve também ser um tipo Unicode (nchar, nvarchar ou ntext) ou um tipo com uma colação ou codificação que possa representar todos os dados de origem. Para parâmetros de saída, especifique um tipo SQL Unicode e ou um tipo C Unicode (SQL_C_WCHAR), que faz com que o driver devolva dados como UTF-16, ou um tipo C restrito com uma codificação cliente que possa representar os dados fonte. O UTF-8 pode sempre representar estes dados.

Para mais informações sobre colações e codificações, consulte Agrupamento e suporte Unicode.

Existem diferenças de conversão entre versões do Windows e Linux ou macOSiconv:

  • Para a página de código 1255, o byte 0xCA converte para ponto 0x05BA de código UTF-16 no Windows e 0x00CA no macOS e Linux com libiconv versões anteriores à 1.15.
  • Bibliotecas Linux iconv sem a revisão de 2003 do Big5/CP950 (BIG5-2003) não convertem corretamente os caracteres adicionados nessa revisão.
  • Para a página de código 932 (japonês, Shift-JIS), a descodificação de caracteres não definidos na norma de codificação difere. Por exemplo, byte 0x80 converte-se em U+0080 no Windows e pode tornar-se U+30FB no Linux e macOS, dependendo da iconv versão.

No ODBC Driver 13 e 13.1, dividir caracteres multibyte UTF-8 ou pares substitutos UTF-16 entre SQLPutData buffers resulta em corrupção de dados. Utilize buffers de streaming que não terminem em codificações parciais de caracteres. Esta limitação foi removida no Driver 17 do ODBC.

Para orientações sobre codificação de caracteres, conversão, associação de parâmetros e dimensionamento do buffer, veja Problemas conhecidos.

OpenSSL

A partir do ODBC Driver 17.4, o driver carrega o OpenSSL dinamicamente, o que lhe permite correr em sistemas com versões 1.0 ou 1.1 sem ficheiros de driver separados. A partir da versão 17.9, o driver suporta OpenSSL 3.0 além das versões anteriores. Quando existem várias versões do OpenSSL, o driver tenta carregar uma versão suportada a partir dos seus caminhos de pesquisa de biblioteca.

Versão do controlador Versões OpenSSL suportadas
17.4 a 17.8 1.0, 1.1
versões 17.x a partir da 17.9 e posteriores, e todas as versões do Driver 18 1.0, 1.1, 3.0

O OpenSSL 4 não é suportado. No macOS, um link Homebrew openssl que aponta para o OpenSSL 4 pode impedir o driver de carregar o OpenSSL mesmo quando o OpenSSL 3 está instalado. Verifica o caminho da biblioteca, bem como as versões instaladas.

Observação

Pode ocorrer um conflito potencial se a aplicação que utiliza o driver, ou um dos seus componentes, se ligar ou carregar dinamicamente uma versão diferente do OpenSSL. Se várias versões do OpenSSL estiverem presentes no sistema e a aplicação o utilizar, certifique-se de que a versão carregada pela aplicação e o driver coincidem. Os erros podem corromper a memória e podem não manifestar-se de forma óbvia ou consistente.

Linux alpino

O tamanho padrão da pilha para novos threads em musl é de 128 KB, a menos que o executável solicite um tamanho de pilha predefinido maior. Um thread pode ultrapassar este limite quando chama o driver. Ligue uma aplicação ODBC em Alpine Linux com -Wl,-z,stack-size=<size_in_bytes> para pedir uma stack de threads padrão maior. Aplicações que criam threads com um tamanho de pilha explícito também devem escolher um tamanho adequado para essas threads.

A pilha da thread principal e a stack padrão para as novas threads não têm a mesma definição. Nos glibc sistemas, o padrão para novos threads normalmente segue o limite de recursos da pilha do processo, com uma alternativa predefinida específica da arquitetura quando esse limite é ilimitado. Não assumas um valor predefinido fixo de 2 MB em sistemas Linux.

Notas adicionais

Para estabelecer uma ligação de administrador dedicada (DAC) a partir de uma aplicação ODBC, defina Server=tcp:<server>,<dac_port> na sua cadeia de ligação. Utilize a porta DAC descoberta, não a porta de ligação normal da instância. Por exemplo, se a porta DAC for 33000, defina Server=tcp:<server>,33000. Estes fragmentos de cadeia de ligação à base de dados especificam apenas o ponto final, não a autenticação. Configure a autenticação e a validação do certificado do servidor separadamente.

O login deve ser um membro da sysadmin server role. O acesso remoto requer que a opção de ligação de administrador remoto do servidor esteja ativada. Para requisitos de acesso, configuração do servidor e procedimentos de administração na linha de comandos, veja Conexão de diagnóstico para administradores de bases de dados. Para descoberta de portas, veja porta DAC.

O gestor de drivers unixODBC gere os atributos de instrução passados SQLSetConnectAttr da mesma forma que o Windows Driver Manager. As opções de instruções ODBC 2.x, como SQL_ATTR_QUERY_TIMEOUT e SQL_ATTR_MAX_ROWS, aplicam-se a instruções existentes e novas na ligação. Atributos apenas de instruções ODBC 3.x, como SQL_ATTR_ROW_ARRAY_SIZE e SQL_ATTR_PARAMSET_SIZE, retornam SQLSTATE HY092. Atributos definidos tanto ao nível de ligação como de instrução, como SQL_ATTR_METADATA_ID, podem ser definidos em qualquer um dos níveis. Definir atributos apenas de instrução ao nível da ligação está obsoleto no ODBC 3.x, por isso, chame SQLSetStmtAttr em vez disso. Para mais informações, consulte a função SQLSetConnectAttr.

Em aplicações altamente multithread, a validação de handle unixODBC pode tornar-se um gargalo de desempenho. Compilar unixODBC com --enable-fastvalidate pode melhorar o desempenho. No entanto, esta opção pode fazer com que aplicações que passam handles inválidos para APIs ODBC crashem em vez de devolver SQL_INVALID_HANDLE.

Para os passos de instalação e configuração da plataforma, veja:

Conteúdo relacionado

  • Última atualização a