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.