Transições de estado

O ODBC define estados separados para cada ambiente, cada conexão e cada instrução. Por exemplo, o ambiente tem três estados possíveis: Não alocado (no qual nenhum ambiente é alocado), Alocado (no qual um ambiente é alocado, mas nenhuma conexão é alocada) e Conexão (no qual um ambiente e uma ou mais conexões são alocados). As conexões têm sete estados possíveis; as instruções têm 13 estados possíveis.

Um item específico, conforme identificado pelo seu identificador, se move de um estado para outro quando o aplicativo chama uma ou mais determinadas funções e passa o identificador para esse item. Esse movimento é chamado de transição de estado. Por exemplo, alocar um identificador de ambiente com SQLAllocHandle move o ambiente de Não alocado para Alocado, e liberar esse identificador com SQLFreeHandle o retorna de Alocado para Não Alocado. O ODBC define um número limitado de transições de estado legal, que é outra maneira de dizer que as funções devem ser chamadas em uma determinada ordem.

Algumas funções, como SQLGetConnectAttr, não afetam o estado em nada. Outras funções afetam o estado de um só item. Por exemplo, SQLDisconnect move uma conexão de um estado de Conexão para um estado Alocado. Por fim, algumas funções afetam o estado de mais de um item. Por exemplo, alocar um identificador de conexão com SQLAllocHandle move uma conexão de um estado Não alocado para um estado Alocado e move o ambiente de um estado Alocado para um estado de Conexão.

Se um aplicativo chamar uma função fora de ordem, a função retornará um erro de transição de estado. Por exemplo, se um ambiente estiver em um estado de Conexão e o aplicativo chamar SQLFreeHandle com esse identificador de ambiente, SQLFreeHandle retornará SQLSTATE HY010 (erro de sequência de função), pois ele pode ser chamado apenas quando o ambiente está em um estado Alocado. Ao definir isso como uma transição de estado inválida, o ODBC impedirá que o aplicativo libere o ambiente enquanto houver conexões ativas.

Há transições de estado que são inerentes ao design do ODBC. Por exemplo, não é possível alocar um identificador de conexão sem primeiro alocar um identificador de ambiente, pois a função que aloca um identificador de conexão requer um identificador de ambiente. Outras transições de estado são impostas pelo Gerenciador de Driver e pelos drivers. Por exemplo, o SQLExecute executa uma instrução preparada. Se o identificador de instrução passado para ele não estiver em um estado Preparado, o SQLExecute retornará SQLSTATE HY010 (erro de sequência de função).

Do ponto de vista do aplicativo, as transições de estado costumam ser diretas: as transições de estado legal tendem a acompanhar o fluxo de um aplicativo bem escrito. As transições de estado são mais complexas para o Gerenciador de Driver e os drivers porque eles precisam controlar o estado do ambiente, cada conexão e cada instrução. A maior parte desse trabalho é feita pelo Gerenciador de Driver; a maior parte do trabalho que deve ser feito pelos drivers ocorre com instruções com resultados pendentes.

As partes 1 e 2 deste manual ("Introdução ao ODBC" e "Como desenvolver aplicativos e drivers") tendem a não mencionar explicitamente as transições de estado. Em vez disso, elas descrevem a ordem em que as funções devem ser chamadas. Por exemplo, "Como executar instruções" afirma que uma instrução deve ser preparada com SQLPrepare antes de ser executada com SQLExecute. Para obter uma descrição completa dos estados e das transições de estado, incluindo quais transições são verificadas pelo Gerenciador de Driver e quais devem ser verificadas pelos drivers, confira o Apêndice B: Tabelas de transição de estado do ODBC.