Atualizar um driver 3.5 para um driver 3.8

Este tópico fornece diretrizes e considerações para atualizar um driver ODBC 3.5 para um driver ODBC 3.8.

Números de versão

As seguintes diretrizes estão relacionadas aos números de versão:

• Um driver deve dar suporte a SQL_OV_ODBC3_80 para SQL_ATTR_ODBC_VERSION, retornando SQL_ERROR para valores diferentes de SQL_OV_ODBC2, SQL_OV_ODBC3 e SQL_OV_ODBC3_80. Versões futuras do Gerenciador de Driver assumirão que um driver dá suporte a um nível de conformidade ODBC se o driver retornar SQL_SUCCESS da Função SQLSetEnvAttr.

• Um driver versão 3.8 deve retornar 03.80 de SQLGetInfo quando SQL_DRIVER_ODBC_VER é passado para InfoType. No entanto, os gerenciadores de driver mais antigos, incluídos em versões mais antigas do Microsoft Windows, tratarão o driver como sendo da versão 3.5 e emitirão um aviso.

  No Windows 7, a versão do Gerenciador de Driver é 03.80. No Windows 8, a versão do Gerenciador de Driver é 03.81 por meio do SQLGetInfo SQL_DM_VER (parâmetro InfoType). SQL_ODBC_VER relata a versão como 03.80 no Windows 7 e no Windows 8.

Tipos de dados C específicos do driver

Um driver pode ter tipos de dados C personalizados quando funciona com um aplicativo ODBC versão 3.8. (Para obter mais informações, consulte Tipos de dados C em ODBC.) No entanto, não há nenhum requisito para um driver 3.8 implementar quaisquer tipos C específicos do driver. Porém, o driver ainda deve realizar a verificação de intervalo dos tipos C. O Gerenciador de Driver não fará isso para drivers 3.8. Para facilitar o desenvolvimento do driver, o valor do tipo de dados C específico do driver pode ser definido no seguinte formato:

SQL_DRIVER_C_TYPE_BASE+0, SQL_DRIVER_C_TYPE_BASE+1  

Tipos de dados específicos do driver, tipos de descritor, tipos de informações, tipos de diagnóstico e atributos

Ao desenvolver um novo driver, você deve usar o intervalo específico do driver para tipos de dados, tipos de descritores, tipos de informações, tipos de diagnóstico e atributos. Os intervalos específicos do driver e seus valores de tipo base são discutidos em Tipos de dados específicos do driver, tipos de descritores, tipos de informações, tipos de diagnóstico e atributos.

Pool de conexões

Para melhor gerenciamento do pool de conexões, o ODBC 3.8 introduz o atributo de conexão SQL_ATTR_RESET_CONNECTION em SQLSetConnectAttr. SQL_RESET_CONNECTION_YES é o único valor válido para esse atributo. SQL_ATTR_RESET_CONNECTION será definido antes que o Gerenciador de Driver coloque uma conexão no pool de conexões, permitindo que o driver redefina os outros atributos de conexão para seus valores padrão.

Para evitar comunicação desnecessária com o servidor, um driver pode adiar a redefinição do atributo de conexão até a próxima comunicação com o servidor remoto, após a conexão ser reutilizada do pool.

Observe que SQL_ATTR_RESET_CONNECTION é usado apenas na comunicação entre o Gerenciador de Driver e um driver. Um aplicativo não pode configurar esse atributo diretamente. Todos os drivers da versão 3.8 devem implementar esse atributo de conexão.

Parâmetros de saída transmitidos

O ODBC versão 3.8 introduz parâmetros de saída transmitidos, uma forma mais escalonável de recuperar parâmetros de saída. (Para obter mais informações, consulte Recuperar parâmetros de saída usando SQLGetData.) Para dar suporte a esse recurso, um driver deve definir SQL_GD_OUTPUT_PARAMS no valor de retorno quando SQL_GETDATA_EXTENSIONS é o InfoType em uma chamada SQLGetInfo. O suporte para um tipo SQL com parâmetros de saída transmitidos deve ser implementado no driver. O Gerenciador de Driver não gerará um erro para um tipo SQL inválido. Os tipos SQL que dão suporte a parâmetros de saída transmitidos são definidos no driver.

Um driver deverá retornar SQL_ERROR se o aplicativo usou SQLGetData para recuperar um parâmetro que não é igual ao parâmetro retornado por SQLParamData.

Execução assíncrona para operações de conexão (método de sondagem)

Um driver pode habilitar suporte assíncrono para diversas operações de conexão.

A partir do Windows 7, o ODBC dá suporte ao método de sondagem (para obter mais informações, consulte Execução assíncrona (método de sondagem). Não há nenhum requisito para um driver ODBC versão 3.8 implementar operações assíncronas em identificadores de conexão. Mesmo que um driver não implemente operações assíncronas em identificadores de conexão, o driver ainda deverá implementar o SQL_ASYNC_DBC_FUNCTIONS InfoType e retornar SQL_ASYNC_DBC_NOT_CAPABLE.

Quando as operações de conexão assíncronas estão habilitadas, o tempo de execução de uma operação de conexão é o tempo total de todas as chamadas repetidas. Se a última chamada repetida ocorrer após o tempo total ter excedido o valor definido pelo atributo de conexão SQL_ATTR_CONNECTION_TIMEOUT e a operação não tiver sido concluída, o driver retornará SQL_ERROR e registrará um registro de diagnóstico com SQLState HYT01 e a mensagem "Tempo limite de conexão expirado". Não haverá tempo limite se a operação for concluída.

Função SQLCancelHandle

O ODBC 3.8 dá suporte a SQLCancelHandle Function, que é usada para cancelar operações de conexão e instrução. Um driver que dá suporte a SQLCancelHandle deve exportar a função. Um driver não deverá cancelar nenhuma função de conexão síncrona ou assíncrona que esteja em andamento se o aplicativo chamar SQLCancel ou SQLCancelHandle em um identificador de instrução. Da mesma forma, um driver não deverá cancelar nenhuma função de instrução síncrona ou assíncrona que esteja em andamento se um aplicativo chamar SQLCancelHandle no identificador de conexão. Além disso, um driver não deve cancelar a operação de navegação (SQLBrowseConnect retorna SQL_NEED_DATA) se o aplicativo chamar SQLCancelHandle no identificador de conexão. Nesses casos, um driver deve retornar HY010, “erro de sequência de função”.

Não é necessário dar suporte a SQLCancelHandle e operações de conexão assíncrona ao mesmo tempo. Um driver pode dar suporte a operações de conexão assíncronas, mas não SQLCancelHandle ou vice-versa.

Conexões suspensas

O Gerenciador de Driver do ODBC 3.8 pode colocar uma conexão em estado suspenso. Um aplicativo chamará SQLDisconnect para liberar recursos associados à conexão. Nesse caso, um driver deve tentar liberar tantos recursos quanto possível sem verificar o estado da conexão. Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran.

Pool de conexões com reconhecimento de driver

O ODBC no Windows 8 permite que os drivers personalizem o comportamento do pool de conexões. Para obter mais informações, confira Pool de conexões com reconhecimento de driver.

Execução assíncrona (método de notificação)

O ODBC 3.8 dá suporte ao método de notificação para operações assíncronas, disponível do Windows 8. Para obter mais informações, consulte Execução assíncrona (método de notificação).

Confira também

Desenvolvendo um driver ODBC
Drivers ODBC fornecidos pela Microsoft
Novidades no ODBC 3.8