Руководство По Языку SQL СУБД Firebird 5.0

`INSERTING`

Доступно в

PSQL

Синтаксис

INSERTING

Тип возвращаемого результата

BOOLEAN

Контекстная переменная INSERTING доступна только коде табличных триггеров.Используется в триггерах на несколько типов событий и показывает, что триггер сработал при выполнении операции INSERT.

Example 1. Использование переменной INSERTING

...
IF (INSERTING OR UPDATING) THEN
BEGIN
  IF (NEW.SERIAL_NUM IS NULL) THEN
    NEW.SERIAL_NUM = GEN_ID (GEN_SERIALS, 1);
END
...

См. также:

[fblangref-contextvars-updating], [fblangref-contextvars-deleting].

`LOCALTIME`

Доступно в

DSQL, PSQL, ESQL

Синтаксис

LOCALTIME [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Параметры контекстной переменной LOCALTIME
Параметр	Описание
precision	Точность.Значение по умолчанию 0.Не поддерживается в ESQL.

Тип возвращаемого результата

TIME WITHOUT TIME ZONE

Переменная LOCALTIME возвращает текущее время в часовом поясе сессии, без информации о часовом поясе.Точность определяет, сколько учитывать знаков после запятой в долях секунды.Точность по умолчанию равна 0.

Note

В блоке кода PSQL (процедура, триггер, исполняемый блок) значение LOCALTIME не меняется по мере выполнения.При вызове вложенного кода, значение также не изменится и будет равно значению в коде самого верхнего уровня.Для определения реального времени используйте CAST('NOW' AS TIME WITHOUT TIME ZONE).

Example 1. Использование переменной LOCALTIME

SELECT LOCALTIME(2) FROM RDB$DATABASE;
-- результат будет (например) 23:35:33.1200

См. также:

[fblangref-contextvars-current-time],[fblangref-contextvars-current-timestamp],[fblangref-contextvars-current-date].

`LOCALTIMESTAMP`

Доступно в

DSQL, PSQL, ESQL

Синтаксис

LOCALTIMESTAMP [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Параметры контекстной переменной LOCALTIMESTAMP
Параметр	Описание
precision	Точность.Значение по умолчанию 3.Не поддерживается в ESQL.

Тип возвращаемого результата

TIMESTAMP WITHOUT TIME ZONE

Переменная LOCALTIMESTAMP возвращает текущую дату и время в часовом поясе сессии, без информации о часовом поясе.Точность определяет, сколько учитывать знаков после запятой в долях секунды.Точность по умолчанию равна 3.

Note

В блоке кода PSQL (процедура, триггер, исполняемый блок) значение LOCALTIMESTAMP не меняется по мере выполнения.При вызове вложенного кода, значение также не изменится и будет равно значению в коде самого верхнего уровня.Для определения реального времени используйте CAST('NOW' AS TIMESTAMP WITHOUT TIME ZONE).

Example 1. Использование переменной LOCALTIMESTAMP

SELECT LOCALTIMESTAMP(2) FROM RDB$DATABASE;
-- результат будет (например) 02.03.2014 23:35:33.1200

См. также:

[fblangref-contextvars-current-timestamp],[fblangref-contextvars-current-time],[fblangref-contextvars-current-date].

`NEW`

Доступно в

PSQL

Синтаксис

NEW

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

В AFTER триггерах переменная доступна только для чтения.

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

Important

Попытка записи в переменную NEW в AFTER триггере вызовет исключение в коде.

Example 1. Использование переменной NEW

...
  IF (NEW.SERIAL_NUM IS NULL) THEN
    NEW.SERIAL_NUM = GEN_ID (GEN_SERIALS, 1);
...

См. также:

[fblangref-contextvars-old].

`OLD`

Доступно в

PSQL

Синтаксис

OLD

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

Переменная OLD доступна только для чтения.

Note

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

Example 1. Использование переменной OLD

...
  IF (NEW.QUANTITY IS DISTINCT FROM OLD.QUANTITY) THEN
    DELTA = NEW.QUANTITY - OLD.QUANTITY;
...

См. также:

[fblangref-contextvars-new].

`RESETTING`

Доступно в

PSQL

Синтаксис

RESETTING

Тип возвращаемого результата

BOOLEAN

Контекстная переменная RESETTING доступна только коде триггеров на события ON CONNECT и ON DISCONNECT, и может использоваться в любом месте, где можно использовать логический предикат.Системная переменная RESETTING, позволяет обнаружить случай, когда триггер базы данных срабатывает из-за сброса сеанса, например с помощью оператора ALTER SESSION RESET.Её значение TRUE, если выполняется сброс сеанса, и FALSE в противном случае.

Example 1. Использование переменной RESETTING

...
IF (RESETTING) THEN
BEGIN
  -- выполняется сброс сеанса
END
...

См. также:

ALTER SESSION RESET.

`ROW_COUNT`

Доступно в

PSQL

Синтаксис

ROW_COUNT

Тип возвращаемого результата

BIGINT

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

Поведение с SELECT и FETCH:

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

Important

Переменная ROW_COUNT не может быть использована для определения количества строк, затронутых при выполненииоператоров EXECUTE STATEMENT или EXECUTE PROCEDURE.Для оператора MERGE переменная ROW_COUNT будет содержать 0 или 1, даже если было затронуто более записей

Warning

Не используйте переменную ROW_COUNT внутри DML операторов.Дело в том, что эта переменная сбрасывает своё значение в 0 перед началом выполнения любого DML оператора, а потому вы можете получить не то что ожидаете.

...
UPDATE t2 SET
    evt='upd',
    old_id = old.id, old_x = old.x,
    new_id = new.id, new_x = new.x
WHERE new_id = old.id;

INSERT INTO t2log(evt, affected_rows) VALUES('upd', ROW_COUNT);
...

В вышеприведённом примере в столбец affected_rows будут записаны нулевые значения, даже если оператором UPDATE были затронуты строки.Для того чтобы исправить эту ошибку, необходимо сохранить значение контекстной переменной ROW_COUNT в локальную переменную PSQL модуля и использовать эту локальную переменную в DML операторе.

...
DECLARE rc INT;
...
UPDATE t2 SET
    evt='upd',
    old_id = old.id, old_x = old.x,
    new_id = new.id, new_x = new.x
WHERE new_id = old.id;

rc = ROW_COUNT;
INSERT INTO t2log(evt, affected_rows) VALUES('upd', rc);
...

Example 1. Использование переменной ROW_COUNT

...
UPDATE Figures SET Number = 0 WHERE id = :id;
IF (row_count = 0) THEN
  INSERT INTO Figures (id, Number)
  VALUES (:id, 0);
...

`SQLCODE`

Доступно в

PSQL

Синтаксис

SQLCODE

Тип возвращаемого результата

INTEGER

В блоках обработки ошибок WHEN … DO контекстная переменная SQLCODE содержит текущий код ошибки SQL.До Firebird 2.0 значение SQLCODE можно было получить только в блоках обработки ошибок WHEN SQLCODE и WHEN ANY.Теперь она может быть отлична от нуля в блоках WHEN GDSCODE и WHEN EXCEPTION при условии, что ошибка, вызвавшее срабатывание блока, соответствует коду ошибки SQL.Вне обработчиков ошибок SQLCODE всегда равен 0, а вне PSQL не существует вообще.

Example 1. Использование переменной SQLCODE

...
WHEN ANY DO
BEGIN
  IF (SQLCODE <> 0) THEN
    MSG = 'Обнаружена ошибка SQL!';
  ELSE
    MSG = 'Ошибки нет!';
  EXCEPTION EX_CUSTOM MSG;
END
...

См. также:

[fblangref-contextvars-gdscode], [fblangref-contextvars-sqlstate].

`SQLSTATE`

Доступно в

PSQL

Синтаксис

SQLSTATE

Тип возвращаемого результата

CHAR(5)

В блоках обработки ошибок WHEN … DO контекстная переменная SQLSTATE переменная содержит 5 символов SQL-2003 — совместимого кода состояния, переданного оператором, вызвавшим ошибку.Вне обработчиков ошибок SQLSTATE всегда равен '00000', а вне PSQL не существует вообще.

Note

SQLSTATE предназначен для замены SQLCODE. Последняя, в настоящее время устарела и буден удалена будущих версиях Firebird;
Любой код SQLSTATE состоит из двух символов класса и трёх символов подкласса. Класс 00 (успешное выполнение), 01 (предупреждение) и 02 (нет данных) представляют собой условия завершения. Каждый код статуса вне этих классов является исключением. Поскольку классы 00, 01 и 02 не вызывают ошибку, они никогда не будут обнаруживаться в переменной SQLSTATE.

Example 1. Использование переменной SQLSTATE

WHEN ANY DO
BEGIN
  MSG = CASE SQLSTATE
          WHEN '22003' THEN
            'Число вышло за пределы диапазона!'
          WHEN '22012' THEN
            'Деление на ноль!'
          WHEN '23000' THEN
            'Нарушение ограничения целостности!'
          ELSE 'Ошибок нет! SQLSTATE = ' || SQLSTATE;
        END;
  EXCEPTION EX_CUSTOM MSG;
END

См. также:

[fblangref-contextvars-gdscode], [fblangref-contextvars-sqlcode], Коды ошибок SQLSTATE.

`UPDATING`

Доступно в

PSQL

Синтаксис

UPDATING

Тип возвращаемого результата

BOOLEAN

Контекстная переменная UPDATING доступна только коде табличных триггеров.Используется в триггерах на несколько типов событий и показывает, что триггер сработал при выполнении операции UPDATE.

Example 1. Использование переменной UPDATING

...
IF (INSERTING OR UPDATING) THEN
BEGIN
  IF (NEW.SERIAL_NUM IS NULL) THEN
    NEW.SERIAL_NUM = GEN_ID (GEN_SERIALS, 1);
END
...

См. также:

[fblangref-contextvars-inserting], [fblangref-contextvars-deleting].

`CURRENT_DATE`

Доступно в

DSQL, PSQL, ESQL

Синтаксис

CURRENT_DATE

Тип возвращаемого результата

DATE

Переменная CURRENT_DATE возвращает текущую дату сервера.

Note

В модуле PSQL (процедура, функция, триггер или исполняемый блок) значение CURRENT_DATE будет оставатьсяпостоянным при каждом чтении. Если несколько модулей вызывают или запускают друг друга, значение будет оставатьсяпостоянным на протяжении всего времени работы самого внешнего модуля. Если вам нужно прогрессирующее значение в PSQL(например, для измерения временных интервалов), используйте преобразование литерала 'TODAY' в дату или временную метку.

Example 1. Использование переменной CURRENT_DATE

select current_date from rdb$database

См. также:

[fblangref-contextvars-current-timestamp], [fblangref-contextvars-current-time].

`USER`

Доступно в

DSQL, PSQL

Синтаксис

USER

Тип возвращаемого результата

VARCHAR(63)

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

Example 1. Использование переменной USER

NEW.ADDED_BY = USER;

См. также:

[fblangref-contextvars-current-user], [fblangref-contextvars-current-role].

`CURRENT_ROLE`

Доступно в

DSQL, PSQL

Синтаксис

CURRENT_ROLE

Тип возвращаемого результата

VARCHAR(63)

Контекстная переменная CURRENT_ROLE, содержащая имя роли, которая была указана при подключении к базе данных, илироль установленную с помощью оператора SET ROLE. В случае если произошло подключение без указания роли,и роль не была указана позже с помощью оператора SET ROLE, переменная принимает значение NONE.

CURRENT_ROLE всегда представляет допустимую роль или NONE. Если пользователь подключается с несуществующей ролью,ядро молча сбрасывает её на NONE, не возвращая ошибку.

Note

Контекстная переменная CURRENT_ROLE содержит только имя явно указанной роли (при входе в систему или с помощью SET ROLE), неявно определяемые роли (выданные оператором GRANT с использованием ключевого слова DEFAULT) не будут попадать в неё.Для того чтобы узнать, используется ли текущим пользователем неявно указанная роль, используйте системнуюфункцию RDB$ROLE_IN_USE().

Example 1. Использование переменной CURRENT_ROLE

SELECT CURRENT_ROLE FROM RDB$DATABASE

Note	Такое же значение можно будет получить и в результате выполнения запроса: `SELECT RDB$GET_CONTEXT ('SYSTEM', 'CURRENT_ROLE') FROM RDB$DATABASE;`

См. также:

SET ROLE,RDB$GET_CONTEXT(),RDB$ROLE_IN_USE().

`CURRENT_TIME`

Доступно в

DSQL, PSQL, ESQL

Синтаксис

CURRENT_TIME [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Параметры контекстной переменной `CURRENT_TIME`
Параметр	Описание
precision	Точность.Значение по умолчанию 0.Не поддерживается в ESQL.

Тип возвращаемого результата

TIME WITH TIME ZONE

Переменная CURRENT_TIME возвращает текущее время в часовом поясе сессии, включая информацию о часовом поясе.Точность определяет, сколько учитывать знаков после запятой в долях секунды.По умолчанию точность равна 0.

Note	В блоке кода PSQL (процедура, триггер, исполняемый блок) значение `CURRENT_TIME` не меняется по мере выполнения.При вызове вложенного кода, значение также не изменится и будет равно значению в коде самого верхнего уровня.Для определения реального времени используйте `CAST('NOW' AS TIME)`.

Example 1. Использование переменной CURRENT_TIME

SELECT CURRENT_TIME(2) FROM RDB$DATABASE;
-- результат будет (например) 23:35:33.1200 Europe/Moscow

См. также:

[fblangref-contextvars-current-timestamp], [fblangref-contextvars-current-date].

`CURRENT_TIMESTAMP`

Доступно в

DSQL, PSQL, ESQL

Синтаксис

CURRENT_TIMESTAMP [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Параметры контекстной переменной CURRENT_TIMESTAMP
Параметр	Описание
precision	Точность.Значение по умолчанию 3.Не поддерживается в ESQL.

Тип возвращаемого результата

TIMESTAMP WITH TIME ZONE

Переменная CURRENT_TIMESTAMP возвращает текущую дату и время в часовом поясе сессии, включая информацию о часовом поясе.Точность определяет, сколько учитывать знаков после запятой в долях секунды.Точность по умолчанию равна 3.

Note	В блоке кода PSQL (процедура, триггер, исполняемый блок) значение `CURRENT_TIMESTAMP` не меняется по мере выполнения.При вызове вложенного кода, значение также не изменится и будет равно значению в коде самого верхнего уровня.Для определения реального времени используйте `CAST('NOW' AS TIMESTAMP)`.

Example 1. Использование переменной CURRENT_TIMESTAMP

SELECT CURRENT_TIMESTAMP(2) FROM RDB$DATABASE;
-- результат будет (например) 02.03.2014 23:35:33.1200 Europe/Moscow

См. также:

[fblangref-contextvars-current-time], [fblangref-contextvars-current-date].

`CURRENT_TRANSACTION`

Доступно в

DSQL, PSQL

Синтаксис

CURRENT_TRANSACTION

Тип возвращаемого результата

BIGINT

Переменная CURRENT_TRANSACTION содержит уникальный номер текущей транзакции.

Значение `CURRENT_TRANSACTION хранится в странице заголовка базы данных и сбрасывается в 0 после восстановления (или создания базы). Оно увеличивается при старте новой транзакции.

Example 1. Использование переменной CURRENT_TRANSACTION

SELECT CURRENT_TRANSACTION FROM RDB$DATABASE;

NEW.TRANS_ID = CURRENT_TRANSACTION;

См. также:

[fblangref-contextvars-current-connection], RDB$GET_CONTEXT().

`CURRENT_USER`

Доступно в

DSQL, PSQL

Синтаксис

CURRENT_USER

Тип возвращаемого результата

VARCHAR(63)

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

Example 1. Использование переменной CURRENT_USER

NEW.ADDED_BY = CURRENT_USER;

См. также:

[fblangref-contextvars-user], [fblangref-contextvars-current-role].

`DELETING`

Доступно в

PSQL

Синтаксис

DELETING

Тип возвращаемого результата

BOOLEAN

Контекстная переменная DELETING доступна только в коде табличных триггеров.Используется в триггерах на несколько типов событий и показывает, что триггер сработал при выполнении операции DELETE.

Example 1. Использование переменной DELETING

...
IF (DELETING) THEN
BEGIN
  INSERT INTO REMOVED_CARS (
    ID, MAKE, MODEL, REMOVED)
  VALUES (
    OLD.ID, OLD.MAKE, OLD.MODEL, CURRENT_TIMESTAMP);
END
...

См. также:

[fblangref-contextvars-inserting], [fblangref-contextvars-updating].

`GDSCODE`

Доступно в

PSQL

Синтаксис

GDSCODE

Тип возвращаемого результата

INTEGER

В блоке обработки ошибок WHEN … DO контекстная переменная GDSCODE содержит числовое представление текущего кода ошибки Firebird.До версии Firebird 2.0 GDSCODE можно было получить только с использованием конструкции WHEN GDSCODE.Теперь эту контекстную переменную можно также использовать в блоках WHEN ANY, WHEN SQLCODE и WHEN EXCEPTION при условии, что код ошибки соответствует коду ошибки Firebird.Вне обработчика ошибок GDSCODE всегда равен 0.Вне PSQL GDSCODE не существует вообще.

Example 1. Использование переменной GDSCODE

...
WHEN GDSCODE GRANT_OBJ_NOTFOUND,
     GDSCODE GRANT_FLD_NOTFOUND,
     GDSCODE GRANT_NOPRIV,
     GDSCODE GRANT_NOPRIV_ON_BASE
DO
BEGIN
  EXECUTE PROCEDURE LOG_GRANT_ERROR(GDSCODE);
  EXIT;
END
...

Note

Обратите внимание, пожалуйста: после, WHEN GDSCODE вы должны использовать символьные имена — такие, как grant_obj_notfound и т.д.Но контекстная переменная GDSCODE — целое число.Для сравнения его с определённой ошибкой вы должны использовать числовое значение, например, 335544551 для grant_obj_notfound.

См. также:

[fblangref-contextvars-sqlcode], [fblangref-contextvars-sqlstate].