SQLSTATEs
Os SQLSTATEs fornecem informações detalhadas sobre a causa de um aviso ou erro. Os SQLSTATEs neste manual se baseiam naqueles encontrados na especificação ISO/IEF CLI, embora os SQLSTATEs que começam com IM sejam específicos para ODBC.
Diferentemente dos códigos de retorno, os SQLSTATEs neste manual são diretrizes, e os drivers não são obrigados a retorná-los. Portanto, embora os drivers devam retornar o SQLSTATE adequado para qualquer erro ou aviso que possam detectar, os aplicativos não devem contar que isso sempre ocorra. Há duas razões para esta situação:
Dados não exaustivos Embora este manual liste um grande número de erros e avisos e as possíveis causas para eles, não está completo e, provavelmente, nunca estará. As implementações do driver simplesmente variam muito. Qualquer driver provavelmente não retornará todos os SQLSTATEs listados neste manual e poderá retornar SQLSTATEs não listados aqui.
Complexidade Alguns mecanismos de banco de dados, principalmente mecanismos de banco de dados relacionais, retornam praticamente 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, à inexatidão dos mapeamentos e ao grande tamanho e ao baixo valor do código resultante, que, muitas vezes, retorna erros de programação que nunca deveriam ser encontrados em tempo de execução. Portanto, os drivers devem mapear tantos erros e avisos quanto parecer razoável e mapear os erros e avisos em que a lógica do aplicativo possa se basear, 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 com a mensagem de diagnóstico associada, que, geralmente, é adaptada ao erro ou ao aviso específico ocorrido 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. 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 embutida em código ou tiver sido criada pelo aplicativo, esse será um erro de programação, e o código precisará ser corrigido. Se a instrução SQL tiver sido inserida pelo usuário, isso será um erro do usuário. O aplicativo fez tudo o que era possível, informando o usuário sobre o problema.
Quando os aplicativos baseiam a lógica de programação em SQLSTATEs, devem estar preparados para que o SQLSTATE não seja retornado ou para que um SQLSTATE diferente seja retornado. A indicação de exatamente quais SQLSTATEs são retornados de forma confiável pode se basear apenas na experiência com vários drivers. No entanto, uma diretriz geral é que SQLSTATEs para erros que ocorrem no driver ou no Gerenciador de Driver, em vez da fonte de dados, têm maior probabilidade de 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 nos quais basear a lógica de programação. No entanto, não há garantia de que todos os mecanismos 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)
SQLSTATE HYC00 (Recurso opcional não implementado) é particularmente significativo, pois é a única maneira pela qual um aplicativo pode determinar se um driver dá suporte a determinada instrução ou atributo de conexão.
Para obter uma lista completa de SQLSTATEs e das funções que os retornam, consulte o 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.