SQLSTATEs

OS SQLSTATEs fornecem informações detalhadas sobre a causa de um aviso ou erro. Os SQLSTATEs neste manual são baseados nos encontrados na especificação da CLI ISO/IEF, embora esses SQLSTATEs que começam com IM sejam específicos para ODBC.

Ao contrário dos códigos de retorno, os SQLSTATEs neste manual são diretrizes e os drivers não são necessários para devolvê-los. Portanto, enquanto os drivers devem retornar o SQLSTATE adequado para qualquer erro ou aviso que sejam capazes de detectar, os aplicativos não devem contar com isso sempre ocorrendo. Os motivos para essa situação são duplos:

• Incompletude Embora este manual liste um grande número de erros e avisos e possíveis causas para esses erros e avisos, ele não está concluído e provavelmente nunca será; as implementações de driver simplesmente variam demais. Qualquer driver determinado provavelmente não retornará todos os SQLSTATEs listados neste manual e poderá retornar SQLSTATEs não listados neste manual.

• Complexidade Alguns mecanismos de banco de dados - particularmente mecanismos de banco de dados relacionais - retornam literalmente milhares de erros e avisos. É improvável que os drivers desses mecanismos mapeiem todos esses erros e avisos para SQLSTATEs devido ao esforço envolvido, à inexactidade dos mapeamentos, ao grande tamanho do código resultante e ao baixo valor do código resultante, que geralmente retorna erros de programação que nunca devem ser encontrados em tempo de execução. Portanto, os drivers devem mapear quantos erros e avisos parecerem razoáveis e ter certeza de mapear esses erros e avisos nos quais a lógica do aplicativo pode ser baseada, como SQLSTATE 01004 (Dados truncados).

Como os SQLSTATEs não são retornados de forma confiável, a maioria dos aplicativos apenas os exibe ao usuário junto com sua mensagem de diagnóstico associada, que geralmente é adaptada ao erro ou aviso específico que ocorreu e ao código de erro nativo. Raramente há perda de funcionalidade ao fazer isso, pois os aplicativos não podem basear a lógica de programação na maioria dos SQLSTATEs de qualquer maneira. Por exemplo, suponha que SQLExecDirect retorne SQLSTATE 42000 (erro de sintaxe ou violação de acesso). Se a instrução SQL que causou esse erro for codificada ou compilada pelo aplicativo, esse será um erro de programação e o código precisará ser corrigido. Se a instrução SQL for inserida pelo usuário, esse será um erro do usuário e o aplicativo fez tudo o que é possível informando ao usuário sobre o problema.

Quando os aplicativos fazem lógica de programação base em SQLSTATEs, eles devem estar preparados para que o SQLSTATE não seja retornado ou para que um SQLSTATE diferente seja retornado. Exatamente quais SQLSTATEs são retornados com confiabilidade pode ser determinado apenas pela experiência com vários drivers. No entanto, uma diretriz geral é que os SQLSTATEs para erros que ocorrem no driver ou no Gerenciador de Driver, ao contrário da fonte de dados, são mais propensos a serem retornados de forma confiável. Por exemplo, a maioria dos drivers provavelmente retorna SQLSTATE HYC00 (recurso opcional não implementado), enquanto menos drivers provavelmente retornam SQLSTATE 42021 (a coluna já existe).

Os SQLSTATEs a seguir indicam erros ou avisos em tempo de execução e são bons candidatos para basear a lógica de programação. No entanto, não há garantia de que todos os motoristas os retornem.

• 01004 (Dados truncados)

• 01S02 (Valor da opção alterado)

• HY008 (Operação cancelada)

• HYC00 (recurso opcional não implementado)

• HYT00 (tempo limite expirado)

O SQLSTATE HYC00 (recurso opcional não implementado) é particularmente significativo porque é a única maneira pela qual um aplicativo pode determinar se um driver dá suporte a uma instrução ou atributo de conexão específico.

Para obter uma lista completa de SQLSTATEs e quais funções os retornam, consulte Apêndice A: Códigos de Erro ODBC. Para obter uma explicação detalhada das condições sob as quais cada função pode retornar um SQLSTATE específico, consulte essa função.