ERROR_LINE() to funkcja Transact-SQL zwracająca numer linii kodu, w której wystąpił błąd w bloku obsługi wyjątków.
ERROR_LINE() w obsłudze błędów Transact-SQL
ERROR_LINE() jest funkcją języka Transact-SQL dostępnego w Microsoft SQL Server. Zwraca numer wiersza instrukcji, w którym wystąpił błąd powodujący przejście do bloku CATCH. Funkcja nie przyjmuje argumentów, dlatego zapisuje się ją jako ERROR_LINE(). Wynikiem jest wartość typu int, a numer można wykorzystać bezpośrednio w komunikacie diagnostycznym, zapisać w tabeli logów albo przekazać do procedury rejestrującej błędy.
Funkcja ma praktyczne znaczenie przede wszystkim wewnątrz konstrukcji TRY...CATCH. Instrukcje, które mogą wygenerować błąd, umieszcza się w części TRY, natomiast kod reakcji na wyjątek w części CATCH. Po wystąpieniu błędu SQL Server przerywa odpowiednią instrukcję i przekazuje sterowanie do bloku CATCH, gdzie można odczytać między innymi numer błędu przez ERROR_NUMBER(), tekst przez ERROR_MESSAGE(), poziom przez ERROR_SEVERITY(), stan przez ERROR_STATE(), nazwę procedury przez ERROR_PROCEDURE() oraz numer wiersza przez ERROR_LINE().
Jak odczytywany jest numer wiersza
Wartość zwracana przez ERROR_LINE() wskazuje wiersz kodu, w którym wystąpił błąd obsługiwany przez aktualny blok CATCH. Numer odnosi się do kodu wykonywanego w danym kontekście, na przykład do instrukcji procedury składowanej albo do partii poleceń przesłanej do silnika. Nie jest to numer pozycji znaku w tekście, numer kolumny ani numer rekordu tabeli. Przy analizie wyniku trzeba więc porównać go z dokładną wersją kodu, która była wykonywana w momencie wystąpienia błędu.
Numer wiersza nie zawsze wskazuje miejsce, w którym znajduje się pierwotna przyczyna problemu. W jednej instrukcji może wystąpić kilka operacji, a błąd może być skutkiem niezgodności typów, naruszenia ograniczenia, nieprawidłowej nazwy obiektu albo błędnych danych wejściowych. ERROR_LINE() pomaga zawęzić obszar poszukiwań, ale pełna interpretacja wymaga zestawienia tej wartości z treścią ERROR_MESSAGE(), numerem błędu i kontekstem wykonywania procedury.
Przykład rejestrowania informacji z bloku CATCH
Przykładowa konstrukcja może zapisać podstawowe dane o błędzie do zmiennych i zwrócić je operatorowi:
BEGIN TRY
SELECT 1 / 0;
END TRY
BEGIN CATCH
SELECT
ERROR_NUMBER() AS NumerBledu,
ERROR_MESSAGE() AS Komunikat,
ERROR_LINE() AS NumerWiersza,
ERROR_PROCEDURE() AS Procedura;
END CATCH;
W takim układzie ERROR_LINE() należy wywołać przed opuszczeniem bloku CATCH albo w procedurze wywołanej z tego bloku, jeżeli kontekst błędu jest nadal dostępny zgodnie z mechanizmem obsługi wyjątków SQL Server. Dane można również przypisać do zmiennej typu int, a następnie użyć ich w instrukcji INSERT zapisującej zdarzenie w tabeli. Rejestrowanie numeru wiersza razem z pełnym komunikatem ogranicza ryzyko pomylenia podobnych błędów występujących w różnych miejscach kodu.
Ograniczenia funkcji i znaczenie podczas diagnostyki
ERROR_LINE() zwraca użyteczną wartość w kontekście obsługi błędu przez CATCH. Wywołana poza aktywnym blokiem CATCH zwraca wartość NULL, ponieważ nie ma wtedy bieżącego błędu, którego lokalizację można odczytać. Z tego powodu samo umieszczenie funkcji w zwykłym zapytaniu kontrolnym nie pokaże ostatniego błędu z wcześniejszego wykonania. Informacje o błędzie trzeba pobrać w czasie obsługi konkretnego wyjątku.
Przy diagnozowaniu problemu na komputerze z Microsoft SQL Server należy sprawdzić, czy analizowany plik lub procedura odpowiada kodowi faktycznie uruchomionemu przez aplikację. Zmiana liczby wierszy, wykonanie tylko fragmentu skryptu albo uruchomienie innej wersji procedury może sprawić, że wskazany numer będzie interpretowany nieprawidłowo. W środowisku użytkownika końcowego analiza błędu może obejmować także stan usługi SQL Server, połączenie aplikacji, uprawnienia i poprawność konfiguracji, jednak ERROR_LINE() pozostaje wyłącznie informacją o lokalizacji wiersza w kodzie obsługiwanego wykonania.
