Diretrizes de programação

Baixar driver ODBC

Os recursos de programação do Microsoft ODBC Driver for SQL Server em macOS e Linux são baseados em ODBC no SQL Server Native Client (SQL Server Native Client (ODBC)). SQL Server Native Client é baseado em ODBC no Windows Data Access Components (Referência do Programador de ODBC).

Um aplicativo ODBC pode usar MARS (conjuntos de resultados ativos múltiplos) e outros recursos específicos do SQL Server, incluindo /usr/local/include/msodbcsql.h, após a inclusão dos cabeçalhos unixODBC (sql.h, sqlext.h, sqltypes.h e sqlucode.h). Em seguida, use os mesmos nomes simbólicos para os itens específicos do SQL Server que você usaria em seus aplicativos ODBC do Windows.

Recursos disponíveis

As seguintes seções da documentação do SQL Server Native Client para ODBC (SQL Server Native Client (ODBC)) são válidas ao usar o driver ODBC em macOS e Linux:

• Comunicando-se com o SQL Server (ODBC)
• Suporte de tempo limite de conexão e consulta
• Cursores
• Aprimoramentos de data/hora (ODBC)
• Executando consultas (ODBC)
• Tratando de erros e mensagens
• Autenticação Kerberos
• Tipos de dados CLR grandes definidos pelo usuário (ODBC)
• Executando transações (ODBC) (exceto transações distribuídas)
• Processando resultados (ODBC)
• Executando procedimentos armazenados
• Suporte a colunas esparsas (ODBC)
• Usando criptografia sem validação
• Parâmetros com valor de tabela
• UTF-8 e UTF-16 para a API de comando e dados
• Usando funções de catálogo

Recursos sem suporte

Os seguintes recursos não foram verificados para funcionar corretamente nessa versão do driver ODBC em Linux e macOS:

• Conexão de cluster de failover
• Resolução IP de Rede Transparente (antes do ODBC Driver 17)
• Rastreamento BID do Driver ODBC do Linux e do macOS (antes do Driver ODBC 17.3)

Os seguintes recursos não estão disponíveis nessa versão do driver ODBC em macOS e Linux:

• Transações Distribuídas (não há suporte para o atributo SQL_ATTR_ENLIST_IN_DTC)
• Espelhamento de banco de dados
• FILESTREAM
• Criação de perfil de desempenho do driver ODBC, discutido em SQLSetConnectAttr, e dos seguintes atributos de conexão relacionados ao 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 de C, como SQL_C_INTERVAL_YEAR_TO_MONTH (documentado em Identificadores e descritores de tipo de dados)
• O valor SQL_CUR_USE_ODBC do atributo SQL_ATTR_ODBC_CURSORS da função SQLSetConnectAttr.

Suporte a conjuntos de caracteres

Para o ODBC Driver 13 e 13.1, os dados SQLCHAR devem ser UTF-8. Não há suporte para nenhuma outra codificação.

Para o ODBC Driver 17, há suporte para dados SQLCHAR em um dos seguintes conjuntos/codificações de caracteres:

Após a conexão, o driver detecta a localidade atual do processo em que ele é carregado. Se ele usa uma das codificações acima, o driver usa a codificação para dados (caractere estreito) SQLCHAR; caso contrário, o padrão é UTF-8. Como todos os processos se iniciam na localidade "C" por padrão (e, portanto, fazem o driver usar UTF-8 como padrão), se um aplicativo precisar usar uma das codificações acima, ele deverá usar a função setlocale para definir a localidade adequadamente antes de conectar-se, seja especificando explicitamente a localidade, seja usando uma cadeia de caracteres vazia, por exemplo setlocale(LC_ALL, ""), para usar as configurações de localidade do ambiente.

Portanto, em um ambiente macOS ou Linux típico no qual a codificação é UTF-8, os usuários do ODBC Driver 17 que atualizarem da versão 13 ou 13.1 não notarão nenhuma diferença. No entanto, aplicativos que usam uma codificação não UTF-8 na lista acima por meio de setlocale() precisam usar essa codificação para dados de/para o driver, em vez de UTF-8.

Os dados SQLWCHAR devem ser UTF-16LE (Little Endian).

Ao associar parâmetros de entrada a SQLBindParameter, se o tipo SQL de um caractere estreito, como SQL_VARCHAR, for especificado, o driver converterá os dados fornecidos no da codificação do cliente na codificação SQL Server padrão (normalmente, página de código 1252). Para parâmetros de saída, o driver converte da codificação especificada nas informações de ordenação associadas aos dados na codificação do cliente. No entanto, é possível haver perda de dados: os caracteres na codificação de origem não representáveis na codificação de destino serão convertidos em um ponto de interrogação ('? ').

Para evitar essa perda de dados ao associar parâmetros de entrada, especifique um tipo de caractere SQL Unicode, como SQL_NVARCHAR. Nesse caso, o driver converte da codificação do cliente em UTF-16, que pode representar todos os caracteres Unicode. Além disso, a coluna ou parâmetro de destino no servidor também pode ser um tipo de Unicode (nchar, nvarchar, ntext) ou um arquivo com uma ordenação/codificação, que pode representar todos os caracteres dos dados de origem originais. Para evitar a perda de dados com parâmetros de saída, especifique um tipo SQL de Unicode e um Unicode tipo C (SQL_C_WCHAR), fazendo o driver retornar dados como UTF-16, ou um tipo C estreito, e verifique se a codificação do cliente pode representar todos os caracteres dos dados de origem (essa representação sempre é possível com UTF-8.)

Para obter mais informações sobre ordenações e codificações, confira Compatibilidade com ordenação e Unicode.

Há algumas diferenças de conversão de codificação entre o Windows e várias versões da biblioteca iconv no Linux e no macOS. Dados de texto na página de código 1255 (hebraico) têm um ponto de código (0xCA) que se comporta de forma diferente após a conversão em Unicode. No Windows, esse caractere converte no ponto de código UTF-16 de 0x05BA. Em macOS e Linux com versões de libiconv anteriores à 1.15, ele converte em 0x00CA. Em Linux com bibliotecas iconv que não dão suporte para a revisão de 2003 de Big5/CP950 (chamada BIG5-2003), os caracteres adicionados com essa revisão não serão convertidos corretamente. Na página de código 932 (japonês, Shift-JIS), o resultado da decodificação não originalmente definido no padrão de codificação de caracteres também é diferente. Por exemplo, o byte 0x80 é convertido em U+0080 no Windows, mas pode se tornar U+30FB no Linux e no macOS, dependendo da versão iconv.

No ODBC Driver 13 e 13.1, quando caracteres multibyte UTF-8 ou UTF-16 substitutos são divididos em buffers SQLPutData, isso resulta em dados corrompidos. Use buffers para transmitir SQLPutData que não terminem em codificações parciais de caracteres. Essa limitação foi removida com o ODBC Driver 17.

Openssl

Da versão 17.4 em diante, o driver carrega o OpenSSL dinamicamente, o que permite que ele seja executado em sistemas com as versões 1.0 ou 1.1 sem precisar de arquivos de driver separados. A partir da versão 17.9, o driver dá suporte ao OpenSSL 3.0, além das versões anteriores. Quando várias versões do OpenSSL estiverem presentes, o driver tentará carregar a mais recente.

Alpine Linux

No momento em que este artigo foi escrito, o tamanho da pilha padrão em MUSL é de 128 mil, o suficiente para a funcionalidade básica do driver ODBC. No entanto, de acordo com a função do aplicativo, não é difícil exceder esse limite, especialmente ao chamar o driver de vários threads. É recomendável que um aplicativo ODBC no Alpine Linux seja compilado com -Wl,-z,stack-size=<VALUE IN BYTES> para aumentar o tamanho da pilha. Para referência, o tamanho de pilha padrão na maioria dos sistemas GLIBC é de 2 MB.

Observações adicionais

• Você pode fazer uma conexão de administrador dedicada (DAC) usando autenticação do SQL Server e host,porta. Um membro da função Sysadmin precisa primeiro detectar a porta DAC. Veja Conexão de diagnóstico para administradores de banco de dados para descobrir como. Por exemplo, se a porta DAC for 33000, você poderá conectá-la ao sqlcmd da seguinte maneira:

  sqlcmd -U <user> -P <pwd> -S <host>,33000
  

  Observação

  As conexões DAC devem usar a Autenticação do SQL Server.

• O gerenciador de driver UnixODBC retorna "identificador de atributo/opção inválido" para todos os atributos de instrução quando eles são passados por meio do SQLSetConnectAttr. No Windows, quando o SQLSetConnectAttr recebe um valor de atributo de instrução, ele faz o driver definir esse valor em todas as instruções ativas que sejam filhos do identificador de conexão.

• Ao usar o driver com aplicativos altamente multi-threaded, a validação do identificador do unixODBC pode se tornar um gargalo de desempenho. Nesses cenários, um desempenho significativamente mais alto pode ser obtido com a compilação de unixODBC com a opção --enable-fastvalidate. No entanto, saiba que isso pode fazer com que os aplicativos que passam identificadores inválidos para APIs do ODBC falhem em vez de retornar erros de SQL_INVALID_HANDLE.

Consulte Também

Perguntas frequentes
Problemas conhecidos nesta versão do driver
Notas de Versão