Transições de estado

O ODBC define estados discretos 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 (em que um ambiente e uma ou mais conexões são alocadas). As conexões têm sete estados possíveis; as instruções têm 13 estados possíveis.

Um item específico, conforme identificado por seu identificador, passa de um estado para outro quando o aplicativo chama uma determinada função ou 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. Outras funções afetam o estado de um único item. Por exemplo, o 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ções), pois ele só poderá ser chamado quando o ambiente estiver em um estado Alocado. Ao definir isso como uma transição de estado inválida, o ODBC impede que o aplicativo libere o ambiente enquanto há conexões ativas.

Algumas transições de estado 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, SQLExecute executa uma instrução preparada. Se o identificador de instrução passado para ele não estiver em um estado Preparado, SQLExecute retornará SQLSTATE HY010 (erro de sequência de funções).

Do ponto de vista do aplicativo, as transições de estado geralmente são simples: transições de estado legal tendem a andar lado a lado com o fluxo de um aplicativo bem escrito. As transições de estado são mais complexas para o Gerenciador de Driver e os drivers, pois estes devem acompanhar o estado do ambiente, de cada conexão e de cada instrução. A maior parte desse trabalho é feita pelo Gerenciador de Drivers; a maior parte do trabalho que deve ser feito pelos drivers ocorre com declarações com resultados pendentes.

As partes 1 e 2 deste manual ("Introdução ao ODBC" e "Desenvolvendo aplicativos e drivers") tendem a não mencionar explicitamente as transições de estado. Em vez disso, eles descrevem a ordem na qual as funções devem ser chamadas. Por exemplo, "Executing Statements" afirma que uma instrução deve ser preparada com SQLPrepare antes de ser executada com SQLExecute. Para obter uma descrição completa de estados e transições de estado, incluindo quais transições são verificadas pelo Gerenciador de Driver e que devem ser verificadas por drivers, consulte Apêndice B: Tabelas de Transição de Estado ODBC.