SQLSTATEs

Os SQLSTATEs fornecem informações detalhadas sobre a causa de um aviso ou erro. Os SQLSTATEs neste manual baseiam-se nos encontrados na especificação ISO/IEF CLI, embora os SQLSTATEs que começam com IM sejam específicos do ODBC.

Ao contrário dos códigos de retorno, os SQLSTATEs neste manual são diretrizes, e os drivers não são obrigados a devolvê-los. Portanto, embora os drivers devam devolver o SQLSTATE correto para qualquer erro ou aviso que consigam detetar, as aplicações não devem contar que isso ocorra sempre. As razões para esta situação são duas:

• Incompletude Embora este manual liste um grande número de erros e avisos e possíveis causas desses erros, não está completo e provavelmente nunca o será; As implementações dos drivers simplesmente variam demasiado. Qualquer driver provavelmente não devolverá todos os SQLSTATEs listados neste manual e poderá devolver SQLSTATEs não listados neste manual.

• Complexidade Alguns motores de bases de dados – particularmente motores relacionais – devolvem literalmente milhares de erros e avisos. Os drivers destes motores dificilmente mapeiam todos estes erros e avisos para SQLSTATEs devido ao esforço envolvido, à imprecisão dos mapeamentos, ao grande tamanho do código resultante e ao baixo valor do código resultante, que frequentemente devolve erros de programação que nunca deveriam ser encontrados em tempo de execução. Por isso, os drivers devem mapear tantos erros e avisos quanto parecer razoável e certificar-se de mapear esses erros e avisos nos quais a lógica da aplicação possa basear-se, como o SQLSTATE 01004 (Dados truncados).

Como os SQLSTATEs não são devolvidos de forma fiável, a maioria das aplicações apenas os apresenta ao utilizador juntamente com a sua mensagem de diagnóstico associada, que é frequentemente adaptada ao erro ou aviso específico que ocorreu, e ao código de erro nativo. Raramente há perda de funcionalidade ao fazer isto, porque as aplicações não conseguem basear a lógica de programação na maioria dos SQLSTATEs. Por exemplo, suponha que o SQLExecDirect devolve SQLSTATE 42000 (erro de sintaxe ou violação de acesso). Se a instrução SQL que causou este erro for codificada ou construída pela aplicação, isto é um erro de programação e o código precisa de ser corrigido. Se a instrução SQL for introduzida pelo utilizador, isto é um erro do utilizador e a aplicação fez tudo o que podia ao informar o utilizador do problema.

Quando as aplicações baseam a lógica em SQLSTATEs, devem estar preparadas para que o SQLSTATE não seja devolvido ou para que um SQLSTATE diferente seja devolvido. Quais SQLSTATEs são devolvidos de forma fiável apenas se podem basear na experiência com vários drivers. No entanto, uma orientação geral é que os SQLSTATEs para erros que ocorrem no driver ou no Gestor de Drivers, em vez da fonte de dados, têm maior probabilidade de serem devolvidos de forma fiável. Por exemplo, a maioria dos drivers provavelmente devolve SQLSTATE HYC00 (funcionalidade opcional não implementada), enquanto menos drivers provavelmente retornam SQLSTATE 42021 (A coluna já existe).

Os seguintes SQLSTATEs 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 condutores os devolvam.

• 01004 (Dados truncados)

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

• HY008 (Operação cancelada)

• HYC00 (Funcionalidade opcional não implementada)

• HYT00 (Tempo expirado)

SQLSTATE HYC00 (funcionalidade opcional não implementada) é particularmente significativo porque é a única forma de uma aplicação determinar se um driver suporta uma determinada instrução ou atributo de ligação.

Para uma lista completa de SQLSTATEs e que funções os retornam, veja o Apêndice A: Códigos de Erro ODBC. Para uma explicação detalhada das condições sob as quais cada função pode devolver um determinado estado SQL, veja essa função.