Procedury składowane w PostgreSQL/Lista argumentów

Przekazywanie argumentów

W PostgreSQL argumenty funkcji mogą być przekazywane:

1. pozycyjnie,
2. wg nazwy - od wersji 9.0.

W pierwszym przypadku lista argumentów funkcji składa się z wartości oddzielonych przecinkami, a wartości są przekazywane zgodnie z pozycją argumentów w deklaracji funkcji.

W przypadku argumentów nazwanych, jest to lista nazw i powiązanych wartości o składni nazwa_argumentu := wartość, oddzielone przecinkami. Wartości do funkcji są przekazywane zgodnie z nazwami na liście, kolejność nie gra roli.

Można również używać konwencji mieszanej, przy czym najpierw muszą wystąpić argumenty pozycyjne, później ewentualnie nazwane.

Np.

CREATE OR REPLACE FUNCTION zwierzaczek(gatunek text, imie text, waga integer, sprytny boolean) ...

-- argumenty pozycyjne
SELECT zwierzaczek('kot', 'Filemon', 3, true);

-- argumenty nazwane
SELECT zwierzaczek(sprytny := true, gatunek := 'kot', waga := 3, imie := 'Filemon');

-- argumenty mieszane
SELECT zwierzaczek('kot', 'Filemon', sprytny := true, waga := 3);

Deklarowanie argumentów

Elementy listy argumentów są rozdzielone przecinkiem, każdy element składa się z następujących części:

[rodzaj] [nazwa] typ [ { DEFAULT | = } wartość domyślna ]

1. rodzaju argumentu: IN, OUT, INOUT (opcjonalne, patrz niżej)
2. nazwy (opcjonalne)
3. typu
4. wartość domyślna (opcjonalnie)

Ponieważ jedynie typ jest wymagany, więc w najprostszym przypadku funkcja może zostać zadeklarowana jako:

CREATE FUNCTION foo(typ1, typ2, ..., typN) ...

Do argumentu zawsze można się odwołać, podając jego numer porządkowy na liście - elementy numerowane są od jeden. Numer trzeba poprzedzić znakiem dolara. Np.:

CREATE FUNCTION suma_trzech(integer, integer, integer) RETURNS integer AS $$
	BEGIN
		RETURN $1 + $2 + $3;
	END;
$$ LANGUAGE 'plpgsql';

Zwykle przy prostych procedurach odwołania numeryczne nie będą kłopotliwe, jednak w dłuższych, bądź skomplikowanych warto (rozsądnie) nazywać argumenty.

CREATE FUNCTION suma_trzech(a integer, b integer, c integer) RETURNS integer AS $$
	BEGIN
		RETURN a + b + c;
	END;
$$ LANGUAGE 'plpgsql';

Zobacz też: Aliasy

Rodzaje argumentów

Argumenty funkcji mogą być oznaczone na 3 sposoby:

• IN - argumenty wejściowe (domyślnie, jeśli nic nie podano)
• OUT - argumenty wyjściowe (wynikowe)
• INOUT - wejściowo/wyjściowe

Ciąg argumentów IN oraz INOUT jest składową sygnatury funkcji, natomiast ciąg OUT oraz INOUT określa typ zwracany.

Np.

-- sygnatura: integer, integer, text
-- zwraca rekord: real, text
CREATE FUNCTION f1(integer, OUT real, integer, INOUT text) ...

-- sygnatura integer, integer, text
-- zwraca rekord: real, text
CREATE FUNCTION f2(OUT real, integer, integer, INOUT text) ...

--- sygnatura: text
-- zwraca rekord: integer, integer
CREATE FUNCTION f3(OUT integer, OUT integer, text) ...

Domyślne wartości argumentów

Wartości domyślne argumentów są podawane w chwili deklaracji funkcji, mogą to być dowolne wyrażenia stałe.

Ponieważ argumenty są podawane pozycyjnie, argumenty z wartościami domyślnymi muszą zostać zadeklarowane na końcu listy argumentów. Nie można więc napisać np. CREATE FUNCTION foo(integer = 1, boolean). Z tego samego powodu w wywołaniu pomijać można argumenty w kolejności "od końca".

Przykład

CREATE OR REPLACE FUNCTION domyslne(a text, b text = 'DRUGI', c text = 'TRZECI') RETURNS text AS $$
	BEGIN
		RETURN 'domyslne("' || a || '", "' || b || '", "' || c || '")';
	END;
$$ LANGUAGE 'plpgsql';

SELECT domyslne('pierwszy');

                domyslne                 
-----------------------------------------
 domyslne("pierwszy", "DRUGI", "TRZECI")
(1 row)

SELECT domyslne('pierwszy', 'drugi');

                domyslne                 
-----------------------------------------
 domyslne("pierwszy", "drugi", "TRZECI")
(1 row)

SELECT domyslne('pierwszy', 'trzeci');

                 domyslne                 
------------------------------------------
 domyslne("pierwszy", "trzeci", "TRZECI")
(1 row)

Zmienna liczba argumentów

Argument funkcji może być oznaczony specjalnych słówkiem VARIADIC i wówczas jego typ musi być tablicowy. Argument tego rodzaju musi być ostatnim argumentem wejściowym (IN) na liście.

Trzeba podać przynajmniej jeden argument (przypadek 1. w przykładzie).

Można podać istniejącą tablicę tego samego typu, co argument, przy czym wówczas należy poprzedzić jej nazwę słówkiem VARIADIC (bez tego system zwróci błąd, w przykładzie przypadek 4.).

Przykłady

CREATE OR REPLACE FUNCTION ile_argumentow(napis text, VARIADIC argumenty integer[]) RETURNS text AS $$
	BEGIN
		RETURN napis || ': ' || COALESCE(array_length(argumenty, 1), 0);
	END;
$$ LANGUAGE 'plpgsql';

-- 1. Wymagany co najmniej jeden argument:
SELECT ile_argumentow('Liczba argumentów');

ERROR:  function ile_argumentow(unknown) does not exist

-- 2. OK, 1 argument
SELECT ile_argumentow('Liczba argumentów', 1);

    ile_argumentow    
----------------------
 Liczba argumentów: 1
(1 row)

-- 3. OK, kilka argumentów
SELECT ile_argumentow('Liczba argumentów', 1, 12, 51, 31, 111);

    ile_argumentow    
----------------------
 Liczba argumentów: 5
(1 row)

-- 4. tablica nie jest poprawnym typem argumentu
SELECT ile_argumentow('Liczba argumentów', ARRAY[1, 2]);

ERROR:  function ile_argumentow(unknown, integer[]) does not exist

-- 5. tablica poprzedzona słówkiem VARIADIC jest akceptowana
SELECT ile_argumentow('Liczba argumentów', VARIADIC ARRAY[1, 2]);

    ile_argumentow    
----------------------
 Liczba argumentów: 2
(1 row)