RETURN выражение;

RETURN с выражением завершает выполнение функции и возвращает значение выражение вызывающей стороне. Эта форма используется для PL/pgSQL функций, не возвращающих набор данных.

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

Если функция была объявлена с выходными параметрами, следует указать только RETURN без выражения. Будут возвращены текущие значения переменных, соответствующих выходным параметрам.

Если функция была объявлена как возвращающая void, для RETURN досрочного выхода из функции можно использовать инструкцию; но после неё не следует указывать выражение RETURN.

Возвращаемое значение функции не может оставаться неопределённым. Если управление достигает конца блока верхнего уровня функции без выполнения инструкции RETURN инструкции, произойдет ошибка времени выполнения. Данное ограничение не распространяется на функции с выходными параметрами и функции, возвращающие void, однако. В таких случаях инструкция RETURN выполняется автоматически по завершении блока верхнего уровня.

Некоторые примеры:

-- функции, возвращающие скалярный тип
RETURN 1 + 2;
RETURN scalar_var;

-- функции, возвращающие составной тип
RETURN composite_type_var;
RETURN (1, 2, 'three'::text);  -- необходимо привести столбцы к соответствующим типам

RETURN NEXT выражение;
RETURN QUERY запрос;
RETURN QUERY EXECUTE строка-команды [ USING выражение [, ... ] ];

Когда PL/pgSQL функция объявлена как возвращающая тип данных SETOF sometype, процедура выполнения будет несколько иной. В этом случае отдельные элементы для возврата задаются последовательностью команд RETURN NEXT или RETURN QUERY , а затем финальная команда RETURN без аргумента используется для индикации завершения выполнения функции. RETURN NEXT можно использовать как со скалярными, так и с составными типами данных; при использовании составного типа результата будет возвращена вся «таблица» набора результатов. RETURN QUERY добавляет результаты выполнения запроса к результирующему набору функции. RETURN NEXT и RETURN QUERY могут свободно перемешиваться в одной функции, возвращающей набор строк, и в этом случае их результаты будут объединены.

RETURN NEXT и RETURN QUERY на самом деле не вызывают выход из функции — они просто добавляют ноль или более строк в результирующий набор функции. Затем выполнение продолжается со следующего оператора в PL/pgSQL функции. По мере того как выполняются RETURN NEXT или RETURN QUERY последующие команды, формируется результирующий набор. Завершающий оператор RETURN, который не должен иметь аргументов, вызывает выход из функции (также можно просто позволить управлению достичь конца функции).

RETURN QUERY имеет вариант RETURN QUERY EXECUTE, который определяет запрос, подлежащий динамическому выполнению. Выражения параметров могут быть вставлены в вычисляемую строку запроса с помощью USING, точно так же, как в EXECUTE команде.

Если функция была объявлена с выходными параметрами, следует указать только RETURN NEXT без выражения. При каждом выполнении текущие значения переменных выходных параметров будут сохраняться для последующего возврата в виде строки результата. Обратите внимание, что функцию необходимо объявить с типом возвращаемого значения SETOF record при наличии нескольких выходных параметров или SETOF sometype когда имеется только один выходной параметр типа sometype, чтобы создать возвращающую набор функцию с выходными параметрами.

Ниже приведен пример функции, использующей RETURN NEXT:

CREATE TABLE foo (fooid INT, foosubid INT, fooname TEXT);
INSERT INTO foo VALUES (1, 2, 'three');
INSERT INTO foo VALUES (4, 5, 'six');

CREATE OR REPLACE FUNCTION get_all_foo() RETURNS SETOF foo AS
$BODY$
DECLARE
    r foo%rowtype;
BEGIN
    FOR r IN
        SELECT * FROM foo WHERE fooid > 0
    LOOP
        -- здесь можно выполнить некоторую обработку
        RETURN NEXT r; -- возврат текущей строки SELECT
    END LOOP;
    RETURN;
END;
$BODY$
LANGUAGE plpgsql;

SELECT * FROM get_all_foo();

Ниже приведен пример функции, использующей RETURN QUERY:

CREATE FUNCTION get_available_flightid(date) RETURNS SETOF integer AS
$BODY$
BEGIN
    RETURN QUERY SELECT flightid
                   FROM flight
                  WHERE flightdate >= $1
                    AND flightdate < ($1 + 1);

    -- Поскольку выполнение еще не завершено, можно проверить, были ли возвращены строки,
    -- и вызвать исключение, если нет.
    IF NOT FOUND THEN
        RAISE EXCEPTION 'No flight at %.', $1;     END IF;      RETURN;  END; $BODY$ LANGUAGE plpgsql;  -- Возвращает доступные рейсы или вызывает исключение, если доступных рейсов нет. SELECT * FROM get_available_flightid(CURRENT_DATE);

IF boolean-expression THEN
    statements
END IF;

IF-THEN операторы представляют собой простейшую форму IF. Операторы, расположенные между THEN и END IF будут выполнены, если условие истинно. В противном случае они пропускаются.

Пример:

IF v_user_id <> 0 THEN
    UPDATE users SET email = v_email WHERE user_id = v_user_id;
END IF;

IF boolean-expression THEN
    statements
ELSE
    statements
END IF;

IF-THEN-ELSE операторы дополняют конструкцию IF-THEN позволяя указать альтернативный набор операторов, которые должны быть выполнены, если условие ложно. (Следует учесть, что сюда относится и случай, когда условие принимает значение NULL.)

Примеры:

IF parentid IS NULL OR parentid = ''
THEN
    RETURN fullname;
ELSE
    RETURN hp_true_filename(parentid) || '/' || fullname;
END IF;

IF v_count > 0 THEN
    INSERT INTO users_count (count) VALUES (v_count);
    RETURN 't';
ELSE
    RETURN 'f';
END IF;

IF boolean-expression THEN
    statements
[ ELSIF boolean-expression THEN
    statements
[ ELSIF boolean-expression THEN
    statements
    ...
]
]
[ ELSE
    statements ]
END IF;

Иногда количество альтернатив может быть больше двух. IF-THEN-ELSIF предоставляет удобный метод последовательной проверки нескольких альтернатив. IF условия проверяются последовательно до тех пор, пока не будет найдено первое истинное значение. После этого выполняются соответствующие операторы, а управление передается следующему за конструкцией оператору END IF. (Все последующие IF условия не проверяются.) Если ни одно из IF условий не является истинным, тогда выполняется ELSE блок (если он определен).

Ниже приведен пример:

IF number = 0 THEN
    result := 'zero';
ELSIF number > 0 THEN
    result := 'positive';
ELSIF number < 0 THEN
    result := 'negative';
ELSE
    -- хм, единственная оставшаяся возможность — значение number равно null
    result := 'NULL';
END IF;

Ключевое слово ELSIF также может записываться как ELSEIF.

Альтернативным способом решения той же задачи является вложение IF-THEN-ELSE инструкций, как показано в следующем примере:

IF demo_row.sex = 'm' THEN
    pretty_sex := 'man';
ELSE
    IF demo_row.sex = 'f' THEN
        pretty_sex := 'woman';
    END IF;
END IF;

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

CASE search-expression
    WHEN выражение [, выражение [ ... ]] THEN
      statements
  [ WHEN выражение [, выражение [ ... ]] THEN
      statements
    ... ]
  [ ELSE
      statements ]
END CASE;

Простая форма оператора CASE обеспечивает условное выполнение на основе равенства операндов. Выражение search-expression вычисляется (один раз) и последовательно сравнивается с каждым значением выражение в WHEN предложениях. При обнаружении совпадения выполняются соответствующие инструкции, statements после чего управление передается за пределы передается следующему за конструкцией оператору END CASE. (Последующие WHEN выражения не вычисляются.) Если совпадений не найдено, то ELSE statements выполняются; выполняются; но если ELSE отсутствует, то CASE_NOT_FOUND генерируется исключение.

Ниже приведен простой пример:

CASE x
    WHEN 1, 2 THEN
        msg := 'one or two';
    ELSE
        msg := 'other value than one or two';
END CASE;

CASE
    WHEN boolean-expression THEN
      statements
  [ WHEN boolean-expression THEN
      statements
    ... ]
  [ ELSE
      statements ]
END CASE;

Поисковая форма CASE обеспечивает условное выполнение основана на истинности логических выражений. Каждое WHEN предложение boolean-expression вычисляется последовательно, пока не будет найдено то, которое возвращает значение true. Затем соответствующий statements выполняются, и затем управление переходит к следующему оператору после END CASE. (Последующие WHEN выражения не вычисляются.) Если истинный результат не найден, то ELSE statements выполняются; но если ELSE отсутствует, то CASE_NOT_FOUND генерируется исключение.

Ниже приведен пример:

CASE
    WHEN x BETWEEN 0 AND 10 THEN
        msg := 'value is between zero and ten';
    WHEN x BETWEEN 11 AND 20 THEN
        msg := 'value is between eleven and twenty';
END CASE;

Эта форма оператора CASE полностью эквивалентна IF-THEN-ELSIF, за исключением правила, согласно которому достижение пропущенного ELSE предложения приводит к ошибке, а не к отсутствию каких-либо действий.

[ <<label>> ]
LOOP
    statements
END LOOP [ label ];

LOOP определяет безусловный цикл, который повторяется бесконечно до тех пор, пока не будет прерван оператором EXIT или RETURN оператором. Необязательную метку label могут использовать операторы EXIT и CONTINUE во вложенных циклах для указания того, к какому именно циклу они относятся.

EXIT [ label ] [ WHEN boolean-expression ];

Если метка не указана label указана, то самый внутренний цикл завершается, и оператор, следующий за END LOOP выполняется следующим. Если label указана, она должна быть меткой текущего или некоторого внешнего уровня вложенности циклов или блоков. В этом случае именованный цикл или блок завершается, и выполнение продолжается с оператора, следующего после соответствующего конца цикла или блока END.

Если WHEN указано, выход из цикла происходит только в том случае, если выражение boolean-expression истинно. В противном случае управление переходит к оператору, следующему после EXIT.

EXIT можно использовать со всеми типами циклов; этот оператор не ограничивается использованием только в безусловных циклах.

При использовании с BEGIN блоком, EXIT происходит передача управления следующему оператору после завершения блока. Следует отметить, что для этой цели необходимо использовать метку; оператор без метки EXIT никогда не будет считаться соответствующим BEGIN блоку. (Это изменение по сравнению с версиями до 8.4 Digital Q.DataBase, которые позволило бы оператору без метки EXIT соответствовать определённому BEGIN блоку.)

Примеры:

LOOP
    -- некоторые вычисления
    IF count > 0 THEN
        EXIT;  -- выход из цикла
    END IF;
END LOOP;

LOOP
    -- некоторые вычисления
    EXIT WHEN count > 0;  -- тот же результат, что и в предыдущем примере
END LOOP;

<>
BEGIN
    -- некоторые вычисления
    IF stocks > 100000 THEN
        EXIT ablock;  -- вызывает выход из блока BEGIN
    END IF;
    -- вычисления в этой части будут пропущены, если stocks > 100000
END;

CONTINUE [ label ] [ WHEN boolean-expression ];

Если метка не указана label указана, начинается следующая итерация самого внутреннего цикла. То есть все оставшиеся операторы в теле цикла пропускаются, и управление возвращается к выражению управления циклом (при его наличии), чтобы определить, требуется ли выполнение следующей итерации цикла. Если label присутствует, то она определяет метку цикла, выполнение которого будет продолжено.

Если WHEN указано, следующая итерация цикла начинается только в том случае, если выражение boolean-expression принимает значение true. В противном случае управление переходит к оператору, следующему за CONTINUE.

CONTINUE можно использовать со всеми типами циклов; он не ограничивается использованием только в безусловных циклах.

Примеры:

LOOP
    -- some computations
    EXIT WHEN count > 100;
    CONTINUE WHEN count < 50;
    -- some computations for count IN [50 .. 100]
END LOOP;

[ <<label>> ]
WHILE boolean-expression LOOP
    statements
END LOOP [ label ];

WHILE оператор повторяет последовательность операторов до тех пор, пока значение boolean-expression выражения истинно (true). Выражение проверяется непосредственно перед каждым входом в тело цикла.

Например:

WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP
    -- some computations here
END LOOP;

WHILE NOT done LOOP
    -- some computations here
END LOOP;

[ <<label>> ]
FOR имя IN [ REVERSE ] выражение .. выражение [ BY выражение ] LOOP
    statements
END LOOP [ label ];

Эта форма оператора FOR создает цикл для итерации по диапазону целочисленных значений. Переменная имя автоматически определяется как тип данных integer и существует только внутри цикла (любое существующее определение имени переменной внутри этого цикла игнорируется). Два выражения, определяющие нижнюю и верхнюю границы диапазона, вычисляются один раз при входе в цикл. Если BY предложение не указано, то шаг итерации принимается равным 1, в противном случае используется значение, указанное в этом BY предложении, которое также вычисляется один раз при входе в цикл. Если REVERSE указано, то значение шага вычитается, а не прибавляется после каждой итерации.

Некоторые примеры целочисленных FOR циклов:

FOR i IN 1..10 LOOP
    -- i will take on the values 1,2,3,4,5,6,7,8,9,10 within the loop
END LOOP;

FOR i IN REVERSE 10..1 LOOP
    -- i will take on the values 10,9,8,7,6,5,4,3,2,1 within the loop
END LOOP;

FOR i IN REVERSE 10..1 BY 2 LOOP
    -- i will take on the values 10,8,6,4,2 within the loop
END LOOP;

Если нижняя граница превышает верхнюю (или меньше, в REVERSE случае), тело цикла не выполняется. Ошибка при этом не возникает.

Если label метка прикреплена к FOR циклу, то к целочисленной переменной цикла можно обращаться по квалифицированному имени, используя эту метку label.

Обработчикам исключений часто требуется идентифицировать конкретную возникшую ошибку. Существует два способа получения информации о текущем исключении в PL/pgSQL: специальные переменные и GET STACKED DIAGNOSTICS команда.

Внутри обработчика исключений специальная переменная SQLSTATE содержит код ошибки, соответствующий возникшему исключению (см. Таблица 8.1.1 для ознакомления со списком возможных кодов ошибок). Специальная переменная SQLERRM содержит текст сообщения об ошибке, связанного с данным исключением. Эти переменные не определены вне обработчиков исключений.

Внутри обработчика исключения также можно получить информацию о текущем исключении, используя команду GET STACKED DIAGNOSTICS команду следующего формата:

GET STACKED DIAGNOSTICS переменная { = | := } элемент [ , ... ];

Каждый элемент — это ключевое слово, определяющее значение статуса, которое будет присвоено указанному параметру переменная (который должен иметь подходящий тип данных для получения этого значения). Доступные в настоящее время элементы состояния приведены в Таблица 5.6.2.

Если для элемента в исключении не было задано значение, будет возвращена пустая строка.

Ниже приведен пример:

DECLARE
  text_var1 text;
  text_var2 text;
  text_var3 text;
BEGIN
  -- некоторая обработка, которая может вызвать исключение
  ...
EXCEPTION WHEN OTHERS THEN
  GET STACKED DIAGNOSTICS text_var1 = MESSAGE_TEXT,
                          text_var2 = PG_EXCEPTION_DETAIL,
                          text_var3 = PG_EXCEPTION_HINT;
END;