37. Контекстные переменные

В SQL РЕД База Данных существует четыре предварительно определенных литерала и множество контекстных переменных. Фактически все они неявно являются функциями. Обращение к предварительно определенному литералу или к контекстной переменной является обращением к соответствующей функции, определенной в системе управления базами данных, каждая из которых возвращает одно требуемое значение.

37.1. CURRENT_CONNECTION

Контекстная переменная CURRENT_CONNECTION имеет тип данных INTEGER. Она возвращает число — системный идентификатор текущего соединения с базой данных. Значение переменной хранится в странице заголовка базы и сбрасывается после восстановления базы. Переменная увеличивается на единицу при каждом последующем соединении с базой данных (соединения также могут быть внутренними вызванными самим ядром). Следовательно, переменная показывает количество подключений произошедших к базе после её восстановления (или после её создания).

Для обычных программ работы с базой данных эта переменная вряд ли может быть полезной.

37.2. CURRENT_DATE

CURRENT_DATE типа DATE возвращает текущую дату сервера.

37.3. CURRENT_ROLE

Контекстная переменная CURRENT_ROLE типа VARCHAR(63) возвращает имя роли, под которой с базой данных соединился пользователь в операторе CONNECT. Если при соединении с базой данных роль не была указана, то возвращается пустое значение NONE.

37.4. CURRENT_TIME

CURRENT_TIME типа TIME WITH TIME ZONE возвращает текущее время сервера. Время вычисляется в момент начала выполнения запроса и не меняется до его завершения. Эта контекстная переменная возвращает не только время, но и тысячные доли секунды. В обращении к контекстной переменной CURRENT_TIME можно указывать и количество знаков в требуемых долях секунды:

CURRENT_TIME [(<количество знаков в долях секунды>)]

Количество знаков может быть числом от 0 до 3. Если количество знаков не указано, предполагается 0.

37.5. CURRENT_TIMESTAMP

Контекстная переменная CURRENT_TIMESTAMP типа TIMESTAMP WITH TIME ZONE возвращает текущую дату и текущее время сервера. Время вычисляется в момент начала выполнения запроса и не меняется до его завершения. В текущем времени указываются и миллисекунды - три знака после десятичной точки. При обращении к этой контекстной переменной также можно задавать требуемое количество долей секунды:

CURRENT_TIMESTAMP [(<количество знаков в долях секунды>)]

Количество знаков может быть числом от 0 до 3. Если количество знаков не указано, предполагается 3.

37.6. CURRENT_TRANSACTION

Контекстная переменная CURRENT_TRANSACTION типа INTEGER возвращает число - системный идентификатор транзакции, под управлением которой выполняется текущий запрос. Значение хранится в странице заголовка базы данных и сбрасывается в 0 после восстановления (или создания базы). Оно увеличивается при старте новой транзакции.

Вряд ли это значение может быть полезно при использовании обычных средств SQL.

37.7. CURRENT_USER

CURRENT_USER типа VARCHAR(63) возвращает имя пользователя, который в настоящий момент соединен с базой данных. Возвращаемое значение точно такое же, как и при использовании контекстной переменной USER.

37.8. DECFLOAT_ROUND

Контекстная переменная DECFLOAT_ROUND определяет режим округления, используемый в операциях со значениями DECFLOAT.

37.9. DECFLOAT_TRAPS

Контекстная переменная DECFLOAT_TRAPS определяет условия, приводящие к вызову исключений в операциях со значениями DECFLOAT.

37.10. INSERTING, UPDATING и DELETING

Контекстные переменные INSERTING, UPDATING и DELETING позволяют определить, какой тип операции с данными базы данных в настоящий момент выполняется. Они возвращают значение TRUE, если выполняется, соответственно, оператор добавления новых данных, изменения существующих данных или удаления строк. Эти переменные могут быть использованы только в табличных триггерах.

37.11. LOCALTIME

LOCALTIME типа TIME WITHOUT TIME ZONE возвращает текущее время сервера в часовом поясе сессии. В обращении к контекстной переменной LOCALTIME можно указать количество знаков в долях секунды:

LOCALTIME [(<количество знаков в долях секунды>)]

Количество знаков может быть числом от 0 до 3. Если количество знаков не указано, предполагается 0.

37.12. LOCALTIMESTAMP

Контекстная переменная LOCALTIMESTAMP типа TIMESTAMP WITHOUT TIME ZONE возвращает текущую дату и текущее время сервера в часовом поясе сессии. В текущем времени указываются и миллисекунды - три знака после десятичной точки. При обращении к этой контекстной переменной можно задавать требуемое количество долей секунды:

LOCALTIMESTAMP [(<количество знаков в долях секунды>)]

Количество знаков может быть числом от 0 до 3. Если количество знаков не указано, предполагается 0.

37.13. NEW

Контекстная переменная NEW содержит новую версию записи базы данных, которая была вставлена или обновлена. Эта переменная может быть использована только в табличных триггерах.

Примечание

Эта переменная в триггерах после события (AFTER) доступна только для чтения. Попытка записи в переменную NEW вызовет исключение.

Примечание

В триггерах на несколько типов событий контекстная переменная NEW доступна всегда. Но при срабатывании триггера по событию DELETE новой версии записи не создаётся, т.е. чтение переменной NEW всегда будет возвращать значение NULL, а запись в неё вызовет исключение времени выполнения.

См. также переменную OLD.

37.14. NOW

NOW является не переменной, а строковой константой. Однако, при её приведении (CAST()) к типу даты/времени, результатом будет текущая дата и/или время. Точность составляет до миллисекунды. NOW нечувствительна к регистру и при приведении типов игнорируются начальные и конечные пробелы.

select CAST('NOW' as DATE) from rdb$database;
––––––––––––––––––––––––––––––––––––––––––––-
2024-07-03

select CAST('now' as TIMESTAMP) from rdb$database;
––––––––––––––––––––––––––––––––––––––––––––-
2024-07-03 12:45:19.4567

Примечание

При использовании приведения типов NOW всегда возвращает фактическую дату/время, даже в модулях PSQL, где CURRENT_DATE, CURRENT_TIME и CURRENT_TIMESTAMP возвращают одно и то же значение вплоть до окончания выполнения кода. Это делает NOW полезным для измерения временных интервалов в триггерах, процедурах и исполнимых блоках;

См. также переменные CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, TODAY.

37.15. OLD

Контекстная переменная OLD содержит существующую версию записи базы данных перед удалением или обновлением. Эта переменная доступна только для чтения и только коде триггеров. Тип значения совпадает с типом данных строки.

Примечание

В триггерах на несколько типов событий контекстная переменная OLD доступна всегда. Очевидно, что при срабатывании триггера по событию INSERT нет никакой существующей ранее версии записи. В этой ситуации переменная OLD всегда будет возвращать NULL; попытка записи в неё вызовет исключение на этапе выполнения.

См. также переменную NEW.

37.16. ROW_COUNT

Контекстная переменная ROW_COUNT содержит количество строк, затронутых (были прочитаны, добавлены, изменены или удалены) последним оператором DML (INSERT, UPDATE, DELETE, SELECT или FETCH) в текущем модуле PSQL.

ROW_COUNT нельзя использовать для определения количества строк, затронутых оператором EXECUTE STATEMENT или EXECUTE PROCEDURE.

Поведение при выполнении SELECT и FETCH:

После однократного SELECT значение ROW_COUNT равно 1, если был получен какой-либо набор данных, и 0 в противном случае.
В цикле FOR SELECT значение ROW_COUNT увеличивается с каждой итерацией (начиная с 0 перед первым циклом).
После FETCH из курсора ROW_COUNT равен 1, если была получена строка данных, и 0 в противном случае. Получение большего количества записей из одного и того же курсора не делает ROW_COUNT больше 1.

Пример:

update Figures set Number = 0 where id = :id;
if (row_count = 0) then
        insert into Figures (id, Number) values (:id, 0);

37.17. SQLCODE, GDSCODE

Контекстные переменные SQLCODE и GDSCODE типа INTEGER позволяют получить значения соответствующих кодов ошибок базы данных. Могут использоваться только в хранимых процедурах или триггерах в блоках обработки ошибок базы данных WHEN. За пределами таких блоков эти переменные имеют нулевое значение.

37.18. SQLSTATE

В SQL-2003 механизмом, передающим информацию об ошибке, является контекстная переменная состояния SQLSTATE. Она представляет собой строку из пяти символов, в которой могут находиться буквы латинского алфавита в верхнем регистре и цифры. Эта строка делится на две группы: двухсимвольный код класса и трехсимвольный код подкласса. Вне обработчиков ошибок переменная SQLSTATE равна 00000, а вне PSQL не существует вообще.

SQLSTATE предназначен для замены SQLCODE.

Если в параметре SQLCODE код класса равен 00, оператор завершился успешно, если 01 - оператор вывел предупреждение, а 02 означает, что нет данных. Любое другое значение кода класса означает, что выполнение оператора не было успешным. Поскольку классы 00, 01 и 02 не вызывают ошибку, они никогда не будут обнаруживаться в переменной SQLSTATE.

WHEN ANY DO
BEGIN
    ERR = CASE SQLSTATE
       WHEN '2207' THEN 'Неверный формат даты и времени!'
       WHEN '3D001' THEN 'Имя каталога не найдено!'
       WHEN '42S22' THEN 'Столбец не найден!'
       WHEN '22012' THEN 'Деление на ноль!'
       ELSE 'Есть ошибка!'
    END;
    EXCEPTION EX_EXAMPLE ERR;
END

37.19. TODAY

Строковая константа TODAY типа CHAR(5). При её приведении (CAST()) к типу даты/времени, результатом будет текущая дата. Написание 'TODAY' нечувствительна к регистру и при приведении типов игнорируются начальные и конечные пробелы.

См. также NOW, TOMORROW, YESTERDAY.

37.20. TOMORROW

Строковая константа TOMORROW типа CHAR(8). При её приведении (CAST()) к типу даты/времени, результатом будет дата, следующая за текущей. Написание 'TOMORROW' нечувствительна к регистру и при приведении типов игнорируются начальные и конечные пробелы.

См. также NOW, TODAY, YESTERDAY.

37.21. USER

USER - имя пользователя, связанного с текущим экземпляром клиентской библиотеки. Тип данных: VARCHAR(63). Это имя того же самого пользователя, которое может быть получено и при обращении к контекстной переменной CURRENT_USER.

37.22. YESTERDAY

Строковая константа YESTERDAY типа CHAR(9). При её приведении (CAST()) к типу даты/времени, результатом будет дата, которая была днем ранее. Написание 'YESTERDAY' нечувствительна к регистру и при приведении типов игнорируются начальные и конечные пробелы.

См. также NOW, TODAY, TOMORROW.