ERROR_NUMBER()

ERROR_NUMBER() to funkcja Transact-SQL zwracająca numeryczny kod ostatnio wystąpionego błędu.

ERROR_NUMBER() w Transact-SQL: czym jest i do czego służy

ERROR_NUMBER() jest funkcją języka Transact-SQL używaną do odczytania numerycznego identyfikatora błędu, który wystąpił podczas wykonywania instrukcji objętej obsługą wyjątków. Funkcja znajduje zastosowanie przede wszystkim w konstrukcji TRY...CATCH. Po przejściu wykonania do bloku CATCH można za jej pomocą ustalić, jaki numer został przypisany ostatniemu przechwyconemu błędowi. Dzięki temu komunikat dla użytkownika, wpis w dzienniku zdarzeń albo decyzja aplikacji mogą zostać dopasowane do rzeczywistej przyczyny problemu.

Warto odróżnić numer błędu od jego opisu. ERROR_NUMBER() zwraca kod liczbowy, natomiast ERROR_MESSAGE() udostępnia tekst komunikatu. W podobny sposób ERROR_SEVERITY() zwraca poziom ważności, ERROR_STATE() stan błędu, ERROR_LINE() numer wiersza, a ERROR_PROCEDURE() nazwę procedury lub wyzwalacza, w którym pojawił się problem. Zestaw tych funkcji pozwala zbudować pełniejszą informację diagnostyczną bez zgadywania na podstawie samego tekstu komunikatu.

Typowy schemat wygląda następująco:

• instrukcje mogące wygenerować błąd umieszcza się w bloku TRY,
• po wystąpieniu problemu wykonanie przechodzi do bloku CATCH,
• w CATCH odczytuje się ERROR_NUMBER() i pozostałe funkcje ERROR_*,
• informacje zapisuje się, przekazuje dalej albo wykorzystuje do kontrolowanego zakończenia operacji.

Funkcja nie służy do przewidywania błędu przed wykonaniem instrukcji. Nie zwraca także ogólnego stanu połączenia z bazą ani kodu ostatniego problemu z dowolnego miejsca skryptu. Jej znaczenie jest związane z aktualnie obsługiwanym kontekstem błędu.

ERROR_NUMBER() a komunikat, poziom ważności i stan błędu

Sam numer zwrócony przez ERROR_NUMBER() jest przydatny, ale najczęściej nie powinien być analizowany w izolacji. Dwa błędy mogą wymagać odmiennych działań, nawet jeśli występują w podobnym miejscu procedury. Z kolei ten sam numer może wymagać innej reakcji zależnie od tabeli, danych wejściowych lub etapu transakcji. Dlatego praktyczna obsługa wyjątków zwykle rejestruje komplet informacji, w którym numer pełni rolę jednoznacznego identyfikatora, a opis i kontekst wyjaśniają przebieg zdarzenia.

ERROR_NUMBER() różni się od ERROR_STATE(). Numer wskazuje rodzaj błędu rozpoznawany przez silnik, natomiast stan pomaga rozróżnić okoliczności, w których błąd został zgłoszony. ERROR_SEVERITY() opisuje poziom ważności, lecz nie jest zamiennikiem numeru. ERROR_LINE() wskazuje miejsce w kodzie, a ERROR_PROCEDURE() ułatwia ustalenie obiektu, w którym problem został wykryty. Takie rozdzielenie informacji jest istotne przy analizowaniu logów oraz przy tworzeniu warunków sterujących dalszym działaniem procedury.

Przykładowy zapis diagnostyczny może mieć postać:

• numer błędu pobrany przez ERROR_NUMBER(),
• opis pobrany przez ERROR_MESSAGE(),
• poziom ważności odczytany za pomocą ERROR_SEVERITY(),
• stan zwrócony przez ERROR_STATE(),
• numer wiersza i nazwa procedury ustalone przez ERROR_LINE() oraz ERROR_PROCEDURE().

W konstrukcjach przeznaczonych do wielokrotnego użycia należy pamiętać, że funkcje ERROR_* mają sens w obrębie bloku CATCH. Wywołanie ich poza obsługą przechwyconego błędu może zwrócić wartość NULL. Nie oznacza to, że błąd nie wystąpił w przeszłości, lecz że w bieżącym miejscu wykonania nie ma aktywnego kontekstu CATCH.

ERROR_NUMBER() przy typowych problemach z bazą danych

Numery błędów są szczególnie pomocne w sytuacjach, gdy ręczne odczytywanie komunikatów staje się niewygodne. Problem może dotyczyć naruszenia unikalności, braku powiązanego rekordu, niezgodności typu danych, przerwanej transakcji, braku uprawnień albo nieprawidłowej składni polecenia. ERROR_NUMBER() pozwala rozdzielić te przypadki w sposób przewidywalny. Aplikacja może na przykład potraktować błąd danych jako sytuację wymagającą korekty formularza, a błąd infrastruktury przekazać do dalszej diagnostyki.

Warto zachować ostrożność przy budowaniu warunków opartych na numerach. Kod nie powinien zakładać, że każdy błąd da się naprawić przez ponowienie tej samej instrukcji. Ponowienie może być uzasadnione tylko wtedy, gdy wiadomo, że przyczyna jest chwilowa i że kolejna próba nie doprowadzi do powielenia danych. W przypadku błędów integralności, nieprawidłowych parametrów lub uszkodzonej logiki biznesowej potrzebna jest korekta przyczyny, a nie automatyczne powtarzanie operacji.

ERROR_NUMBER() pomaga również w kontroli transakcji. Po przechwyceniu błędu można sprawdzić stan transakcji i zdecydować, czy należy wykonać wycofanie zmian. Sam numer błędu nie gwarantuje jednak, że każda transakcja jest w identycznym stanie. Znaczenie mają także ustawienia sesji, rodzaj instrukcji oraz moment, w którym wyjątek został zgłoszony. Przy projektowaniu procedur należy więc analizować całą ścieżkę wykonania, w tym zatwierdzanie i wycofywanie zmian.

W dziennikach technicznych dobrze jest zapisywać numer razem z datą zdarzenia, nazwą operacji, identyfikatorem żądania oraz ograniczonym zestawem danych potrzebnych do odtworzenia problemu. Nie należy bez potrzeby utrwalać poufnych wartości parametrów. Czytelny log powinien pomagać w rozpoznaniu przyczyny, ale nie może sam stawać się źródłem ujawnienia danych.

ERROR_NUMBER() i praktyczne wskazówki dla procedur T-SQL

Obsługa ERROR_NUMBER() powinna być spójna w całym rozwiązaniu. Jeżeli w jednej procedurze błąd jest rejestrowany, w innej ignorowany, a w jeszcze innej zamieniany na przypadkowy komunikat, późniejsza diagnostyka staje się trudniejsza. Korzystne jest przyjęcie jednego schematu: przechwycenie informacji, zapis technicznego kontekstu, uporządkowanie transakcji oraz przekazanie kontrolowanego komunikatu do warstwy wywołującej.

Nie należy zastępować numeru błędu własnym, przypadkowym kodem bez zachowania informacji źródłowej. Jeżeli konieczne jest przekazanie uproszczonego komunikatu, oryginalny ERROR_NUMBER() powinien pozostać dostępny w logu albo w kontrolowanym mechanizmie diagnostycznym. Ułatwia to porównywanie zdarzeń po zmianach wersji kodu i odróżnianie błędów danych od błędów środowiskowych.

Warto także sprawdzić, gdzie znajduje się granica obsługi wyjątku. Jeżeli błąd zostanie przechwycony zbyt wcześnie i bez przekazania dalej, wyższa warstwa może uznać operację za zakończoną poprawnie. Jeżeli natomiast każdy wyjątek jest propagowany bez żadnego kontekstu, użytkownik może otrzymać komunikat niezrozumiały i nieprzydatny. ERROR_NUMBER() najlepiej wykorzystać jako element świadomego kontraktu między procedurą a aplikacją.

Podczas testów powinno się wywołać kilka różnych sytuacji błędnych i zweryfikować, czy numer jest odczytywany w bloku CATCH, czy zapis zawiera odpowiednie dane oraz czy transakcja pozostaje w oczekiwanym stanie. Należy także sprawdzić zachowanie po zmianie schematu, uprawnień i parametrów wejściowych. Taka próba często ujawnia problemy, których nie widać przy jednym poprawnym scenariuszu.

ERROR_NUMBER() a moment zgłoszenia do serwisu technicznego

Jeżeli ERROR_NUMBER() pojawia się w powtarzalnym komunikacie, a przyczyny nie da się ustalić na podstawie procedury, logów i parametrów, przydatne może być zebranie pełnego kontekstu zdarzenia przed przekazaniem sprawy do specjalisty. Należy zanotować treść komunikatu, numer błędu, nazwę wykonywanej operacji, moment wystąpienia problemu oraz informację, czy błąd pojawia się przy każdym uruchomieniu, czy tylko przy określonych danych. Nie powinno się usuwać logów ani zmieniać wielu ustawień jednocześnie, ponieważ utrudnia to odtworzenie sytuacji.

W przypadku problemów obejmujących całe stanowisko komputerowe, niestabilną pracę systemu lub trudności z uruchomieniem narzędzi diagnostycznych można skorzystać z pomocy Warszawskiego Pogotowia Komputerowego 24/7, gdzie diagnoza laptopa jest bezpłatna. Przy zgłoszeniu dobrze jest przekazać numer ERROR_NUMBER(), zrzut komunikatu oraz opis czynności wykonanych bezpośrednio przed pojawieniem się problemu. Pozwala to szybciej rozdzielić błąd wynikający z kodu T-SQL od kłopotu z konfiguracją, nośnikiem danych albo samym środowiskiem pracy.

Najważniejsza zasada pozostaje prosta: ERROR_NUMBER() powinien być odczytywany w odpowiednim kontekście i zestawiany z pozostałymi informacjami o wyjątku. Sam numer jest punktem zaczepienia, natomiast poprawna diagnoza wynika z połączenia kodu błędu, komunikatu, miejsca wykonania, stanu transakcji i powtarzalności problemu.