Apêndice B: Tabelas de transição de estado ODBC
As tabelas neste apêndice mostram como as funções ODBC causam transições dos estados de ambiente, conexão, instrução e descritor. O estado do ambiente, da conexão, da instrução ou do descritor geralmente determina quando as funções que usam o tipo correspondente de identificador (ambiente, conexão, instrução ou descritor) podem ser chamadas. Os estados de ambiente, conexão, instrução e descritor se sobrepõem aproximadamente conforme mostrado nas ilustrações a seguir. Por exemplo, a sobreposição exata dos estados de conexão C5 e C6 e dos estados de instrução S1 a S12 depende da fonte de dados, uma vez que as transações começam em momentos diferentes em diferentes fontes de dados, e o estado do descritor D1i (descritor implicitamente alocado) depende do estado da instrução com a qual o descritor está associado, enquanto o estado D1e (descritor explicitamente alocado) é independente do estado de qualquer instrução. Para obter uma descrição de cada estado, consulte Transições de ambiente, transições de conexão, transições de instrução e transições de descritor, posteriormente neste apêndice.
Os estados de ambiente e conexão se sobrepõem da seguinte maneira:
Os estados de conexão e instrução se sobrepõem da seguinte maneira:
Os estados de instrução e descritor se sobrepõem da seguinte maneira:
Os estados de conexão e descritor se sobrepõem da seguinte maneira:
Cada entrada em uma tabela de transição pode ser um dos seguintes valores:
-- -O estado é inalterado após a execução da função.
E
n , C_n_, S_n_ ou D_n_ – o ambiente, a conexão, a instrução ou o estado do descritor são movidos para o estado especificado.
(IH) - Um identificador inválido foi passado para a função . Se o identificador era um identificador nulo ou era um identificador válido do tipo errado – por exemplo, um identificador de conexão foi passado quando um identificador de instrução era necessário – a função retorna SQL_INVALID_HANDLE; caso contrário, o comportamento é indefinido e provavelmente fatal. Esse erro é mostrado somente quando é o único resultado possível de chamar a função no estado especificado. Esse erro não altera o estado e sempre é detectado pelo Gerenciador de Driver, conforme indicado pelos parênteses.
NS – Próximo estado. A transição de instrução é a mesma que se a instrução não tivesse passado pelos estados assíncronos. Por exemplo, suponha que uma instrução que cria um conjunto de resultados insira o estado S11 do estado S1 porque SQLExecDirect retornou SQL_STILL_EXECUTING. A notação NS no estado S11 significa que as transições para a instrução são iguais às de uma instrução no estado S1 que cria um conjunto de resultados. Se SQLExecDirect retornar um erro, a instrução permanecerá no estado S1; se for bem-sucedida, a instrução passará para o estado S5; se precisar de dados, a instrução passará para o estado S8; e, se ainda estiver em execução, ele permanecerá no estado S11.
XXXXX ou (XXXXX) – UM SQLSTATE relacionado à tabela de transição; SQLSTATEs detectados pelo Gerenciador de Driver estão entre parênteses. A função retornou SQL_ERROR e o SQLSTATE especificado, mas o estado não é alterado. Por exemplo, se SQLExecute for chamado antes de SQLPrepare, ele retornará SQLSTATE HY010 (erro de sequência de funções).
Observação
As tabelas não mostram erros não relacionados às tabelas de transição que não alteram o estado. Por exemplo, quando SQLAllocHandle é chamado no estado de ambiente E1 e retorna SQLSTATE HY001 (erro de alocação de memória), o ambiente permanece no estado E1; isso não é mostrado na tabela de transição de ambiente para SQLAllocHandle.
Se o ambiente, a conexão, a instrução ou o descritor puderem se mover para mais de um estado, cada estado possível será mostrado e uma ou mais notas de rodapé explicarão as condições sob as quais cada transição ocorre. As notas de rodapé a seguir podem aparecer em qualquer tabela.
| Nota | Significado |
|---|---|
| b | Antes ou depois. O cursor foi posicionado antes do início do conjunto de resultados ou após o final do conjunto de resultados. |
| c | Função atual. A função atual estava sendo executada de forma assíncrona. |
| d | Precisa de dados. A função retornou SQL_NEED_DATA. |
| e | Erro. A função retornou SQL_ERROR. |
| i | Linha inválida. O cursor foi posicionado em uma linha no conjunto de resultados e a linha foi excluída ou ocorreu um erro em uma operação na linha. Se a matriz de status da linha existisse, o valor na matriz de status da linha era SQL_ROW_DELETED ou SQL_ROW_ERROR. (A matriz de status da linha é apontada pelo atributo de instrução SQL_ATTR_ROW_STATUS_PTR.) |
| nf | Não encontrado. A função retornou SQL_NO_DATA. Isso não se aplica quando SQLExecDirect, SQLExecute ou SQLParamData retorna SQL_NO_DATA depois de executar uma instrução de atualização ou exclusão pesquisada. |
| np | Não está preparado. A declaração não foi preparada. |
| nr | Sem resultados. A instrução não criará ou não um conjunto de resultados. |
| o | Outra função. Outra função foi executar de forma assíncrona. |
| p | Preparado. A declaração foi preparada. |
| r | Resultados. A instrução criará ou criará um conjunto de resultados (possivelmente vazio). |
| s | Sucesso. A função retornou SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. |
| v | Linha válida. O cursor foi posicionado em uma linha no conjunto de resultados e a linha foi inserida com êxito, atualizada com êxito ou outra operação na linha foi concluída com êxito. Se a matriz de status da linha existisse, o valor na matriz de status da linha era SQL_ROW_ADDED, SQL_ROW_SUCCESS ou SQL_ROW_UPDATED. (A matriz de status da linha é apontada pelo atributo de instrução SQL_ATTR_ROW_STATUS_PTR.) |
| x | Em execução. A função retornou SQL_STILL_EXECUTING. |
SQLFreeHandle
Neste exemplo, a linha na tabela de transição de estado do ambiente para SQLFreeHandle quando HandleType é SQL_HANDLE_ENV é a seguinte.
| E0 Não alocado |
E1 Alocado |
E2 Conexão |
|---|---|---|
| (IH) | E0 | (HY010) |
Se SQLFreeHandle for chamado no estado de ambiente E0 com HandleType definido como SQL_HANDLE_ENV, o Gerenciador de Driver retornará SQL_INVALID_HANDLE. Se for chamado no estado E1 com HandleType definido como SQL_HANDLE_ENV, o ambiente passará para o estado E0 se a função for bem-sucedida e permanecerá no estado E1 se a função falhar. Se ele for chamado no estado E2 com HandleType definido como SQL_HANDLE_ENV, o Gerenciador de Driver sempre retornará SQL_ERROR e SQLSTATE HY010 (erro de sequência de funções) e o ambiente permanecerá no estado E2.
Para entender as tabelas de transição de estado, é necessário entender a qual item (ambiente, conexão, instrução ou descritor) eles se referem. Suponha que uma função aceite o identificador de um item do tipo X. A tabela de transição de estado X para essa função descreve como chamar a função, com o identificador de um item do tipo X, afeta esse item. Por exemplo, SQLDisconnect aceita um identificador de conexão. A tabela de transição de estado de conexão para SQLDisconnect descreve como SQLDisconnect afeta o estado da conexão para a qual ela é chamada.
Suponha que uma função aceite o identificador de um item do tipo Y, em que Y não é igual a X. A tabela de transição de estado X para essa função descreve como chamar a função, com um identificador do tipo X associado ao item do tipo Y, afeta o item do tipo Y. Por exemplo, a tabela de transição de estado da instrução para SQLDisconnect descreve como SQLDisconnect afeta o estado de uma instrução quando chamado com o identificador da conexão com a qual a instrução está associada.
Este apêndice contém os tópicos a seguir.