SQLSTATEs

SQLSTATEs bieden gedetailleerde informatie over de oorzaak van een waarschuwing of fout. De SQLSTATEs in deze handleiding zijn gebaseerd op de SQLSTATEs in de ISO/IEF CLI-specificatie, hoewel deze SQLSTATEs die beginnen met IM specifiek zijn voor ODBC.

In tegenstelling tot retourneringscodes dienen de SQLSTATEs in deze handleiding als richtlijnen en zijn drivers niet verplicht om ze te retourneren. Daarom moeten stuurprogramma's de juiste SQLSTATE retourneren voor elke fout of waarschuwing die ze kunnen detecteren, maar toepassingen mogen er niet op rekenen dat dit altijd gebeurt. De redenen voor deze situatie zijn tweeledig:

• Onvolledigheid Hoewel in deze handleiding een groot aantal fouten en waarschuwingen en mogelijke oorzaken voor deze fouten en waarschuwingen worden vermeld, is deze waarschijnlijk niet volledig en zal dit waarschijnlijk nooit zijn; implementaties van stuurprogramma's variëren gewoon te veel. Elk gegeven stuurprogramma retourneert waarschijnlijk niet alle SQLSTATEs die in deze handleiding worden vermeld en retourneert mogelijk SQLSTATEs die niet in deze handleiding worden vermeld.

• Complexiteit Sommige database-engines, met name relationele database-engines, retourneren letterlijk duizenden fouten en waarschuwingen. De stuurprogramma's voor dergelijke engines zullen waarschijnlijk niet al deze fouten en waarschuwingen aan SQLSTATEs toewijzen vanwege de inspanning die nodig is, de onnauwkeurigheid van de toewijzingen, de omvang van de resulterende code en de lage waarde van de resulterende code, die vaak programmeerfouten teruggeeft die tijdens runtime nooit mogen optreden. Daarom moeten stuurprogramma's zoveel mogelijk fouten en waarschuwingen in kaart brengen als redelijk lijkt en ervoor zorgen dat deze fouten en waarschuwingen worden vastgelegd waarop de toepassingslogica gebaseerd kan zijn, zoals SQLSTATE 01004 (gegevens zijn afgekapt).

Omdat SQLSTATEs niet betrouwbaar worden geretourneerd, geven de meeste toepassingen ze alleen weer aan de gebruiker samen met het bijbehorende diagnostische bericht, dat vaak is afgestemd op de specifieke fout of waarschuwing die is opgetreden, en systeemeigen foutcode. Er is zelden sprake van verlies van functionaliteit, omdat toepassingen toch geen programmeerlogica kunnen baseren op de meeste SQLSTATEs. Stel dat SQLExecDirect SQLSTATE 42000 retourneert (syntaxisfout of schending van toegang). Als de SQL-instructie die deze fout heeft veroorzaakt, in code is vastgelegd of gebouwd door de toepassing, is dit een programmeerfout en moet de code worden opgelost. Als de SQL-instructie door de gebruiker wordt ingevoerd, is dit een gebruikersfout en heeft de toepassing alles gedaan dat mogelijk is door de gebruiker op de hoogte te stellen van het probleem.

Wanneer toepassingen basisprogrammeerlogica uitvoeren op SQLSTATEs, moeten ze worden voorbereid om de SQLSTATE niet te retourneren of om een andere SQLSTATE te retourneren. Precies welke SQLSTATEs betrouwbaar worden geretourneerd, kan alleen worden gebaseerd op ervaring met talloze stuurprogramma's. Een algemene richtlijn is echter dat SQLSTATEs voor foutmeldingen die optreden in het stuurprogramma of de Driver Manager, in plaats van de gegevensbron, op een betrouwbaardere manier worden geretourneerd. De meeste stuurprogramma's retourneren bijvoorbeeld waarschijnlijk SQLSTATE HYC00 (optionele functie niet geïmplementeerd), terwijl minder stuurprogramma's waarschijnlijk SQLSTATE 42021 retourneren (kolom bestaat al).

De volgende SQLSTATEs geven runtimefouten of -waarschuwingen aan en zijn goede kandidaten voor het baseren van programmeerlogica. Er is echter geen garantie dat alle drivers ze retourneren.

• 01004 (gegevens afgekapt)

• 01S02 (optiewaarde gewijzigd)

• HY008 (bewerking geannuleerd)

• HYC00 (optionele functie niet geïmplementeerd)

• HYT00 (time-out verlopen)

SQLSTATE HYC00 (optionele functie niet geïmplementeerd) is bijzonder belangrijk omdat dit de enige manier is waarop een toepassing kan bepalen of een stuurprogramma een bepaalde instructie of verbindingskenmerk ondersteunt.

Zie bijlage A: ODBC-foutcodes voor een volledige lijst met SQLSTATEs en welke functies deze retourneren. Zie deze functie voor een gedetailleerde uitleg van de voorwaarden waaronder elke functie een bepaalde SQLSTATE kan retourneren.