35.4. D�clarations

35.4.1. Alias de param�tres de fonctions

Les param�tres pass�s aux fonctions sont nomm�s par les identifiants $1, $2, etc. �ventuellement, des alias peuvent �tre d�clar�s pour les noms de param�tres de type $n afin d'am�liorer la lisibilit�. L'alias ou l'identifiant num�rique peuvent �tre utilis�s indiff�remment pour se r�f�rer � la valeur du param�tre.

Il existe deux fa�ons de cr�er un alias. La fa�on pr�f�r�e est de donner un nom au param�tre dans la commande CREATE FUNCTION, par exemple :

CREATE FUNCTION taxe_ventes(sous_total real) RETURNS real AS $$
BEGIN
    RETURN sous_total * 0.06;
END;

L'autre fa�on, la seule disponible pour les versions ant�rieures de PostgreSQL 8.0, est de d�clarer explicitement un alias en utilisant la syntaxe de d�claration

nom ALIAS FOR $n;

Le m�me exemple dans ce style ressemble �

CREATE FUNCTION taxe_ventes(real) RETURNS real AS $$
DECLARE
    sous_total ALIAS FOR $1;
BEGIN
    RETURN sous_total * 0.06;
END;
$$ LANGUAGE plpgsql;

Quelques exemples de plus :

CREATE FUNCTION instr(varchar, integer) RETURNS integer AS '
DECLARE
    v_string ALIAS FOR $1;
    index ALIAS FOR $2;
BEGIN
    -- quelques traitements
END;
$$ LANGUAGE plpgsql;


CREATE FUNCTION concat_selected_fields(in_t tablename) RETURNS text AS $$
BEGIN
    RETURN in_t.f1 || in_t.f3 || in_t.f5 || in_t.f7;
END;
$$ LANGUAGE plpgsql;

Lorsque le type de retour d'une fonction PL/pgSQL est d�clar� comme type polymorphe (anyelement ou anyarray), un param�tre sp�cial $0 est cr��. Son type de donn�e est le type effectif de retour de la fonction, d�duit d'apr�s les types d'entr�e (voir la Section 31.2.1). Ceci permet � la fonction d'acc�der � son type de retour r�el comme on le voit ici avec la Section 35.4.2. $0 est initialis� � NULL et peut �tre modifi� par la fonction, de sorte qu'il peut �tre utilis� pour contenir la variable de retour si besoin est, bien que cela ne soit pas requis. On peut aussi donner un alias � $0. Par exemple, cette fonction s'ex�cute comme un op�rateur + pour n'importe quel type de donn�es.

CREATE FUNCTION ajoute_trois_valeurs(v1 anyelement, v2 anyelement, v3 anyelement)
RETURNS anyelement AS $$
DECLARE
    resultat ALIAS FOR $0;
BEGIN
    resultat := v1 + v2 + v3;
    RETURN resultat;
END;
$$ LANGUAGE plpgsql;

35.4.2. Copie de types

variable%TYPE

%TYPE fournit le type de donn�es d'une variable ou d'une colonne de table. Vous pouvez l'utiliser pour d�clarer des variables qui contiendront des valeurs de bases de donn�es. Par exemple, disons que vous avez une colonne nomm�e id_utilisateur dans votre table utilisateurs. Pour d�clarer une variable du m�me type de donn�es que utilisateurs.id_utilisateur, vous pouvez �crire :

id_utilisateur utilisateurs.id_utilisateur%TYPE;

En utilisant %TYPE vous n'avez pas besoin de conna�tre le type de donn�es de la structure � laquelle vous faites r�f�rence et, plus important, si le type de donn�es de l'objet r�f�renc� change dans le futur (par exemple : vous changez le type de id_utilisateur de integer � real), vous pouvez ne pas avoir besoin de changer votre d�finition de fonction.

%TYPE est particuli�rement utile dans le cas de fonctions polymorphes puisque les types de donn�es n�cessaires aux variables internes peuvent changer d'un appel � l'autre. Des variables appropri�es peuvent �tre cr��es en appliquant %TYPE aux arguments de la fonction ou � la variable fictive de r�sultat.

35.4.3. Types ligne

name table_name%ROWTYPE;
name composite_type_name;

Une variable de type composite est appel�e variable ligne (ou variable row-type). Une telle variable peut contenir une ligne enti�re de r�sultat de requ�te SELECT ou FOR, du moment que l'ensemble de colonnes de la requ�te correspond au type d�clar� de la variable. Les champs individuels de la valeur row sont accessibles en utilisant la notation point�e, par exemple varligne.champ.

Une variable ligne peut �tre d�clar�e de fa�on � avoir le m�me type que les lignes d'une table ou vue existante, en utilisant la notation nom_table%ROWTYPE ou elle peut �tre d�clar�e en donnant un nom de type composite (chaque table ayant un type de donn�es associ� du m�me nom, il importe peu dans PostgreSQL que vous �criviez %ROWTYPE ou pas. Cependant la forme utilisant %ROWTYPE est plus portable).

Les param�tres d'une fonction peuvent �tre des types composites (lignes compl�tes de tables). En ce cas, l'identifiant correspondant $n sera une variable ligne � partir de laquelle les champs peuvent �tre s�lectionn�s, par exemple $1.id_utilisateur.

Seules les colonnes d�finies par l'utilisateur d'une ligne de table sont accessibles dans une variable de type ligne, et non l'OID ou d'autres colonnes syst�mes (parce que la ligne pourrait �tre issue d'une vue). Les champs du type ligne h�ritent des tailles des champs de la table ou de leur pr�cision pour les types de donn�es tels que char(n).

Voici un exemple d'utilisation des types composites  :

CREATE FUNCTION merge_fields(t_row tablename) RETURNS text AS $$
DECLARE
    t2_row table2name%ROWTYPE;
BEGIN
    SELECT * INTO t2_row FROM table2name WHERE ... ;
    RETURN t_row.f1 || t2_row.f3 || t_row.f5 || t2_row.f7;
END;
$$ LANGUAGE plpgsql;

SELECT merge_fields(t.*) FROM tablename t WHERE ... ;

35.4.4. Types Record

nom RECORD;

Les variables record sont similaires aux variables de type ligne mais n'ont pas de structure pr�d�finie. Elles empruntent la structure effective de type ligne de la ligne � laquelle elles sont assign�es durant une commande SELECT or FOR. La sous-structure d'une variable record peut changer � chaque fois qu'on l'assigne. Une cons�quence de cela est que jusqu'� ce qu'elle ait �t� assign�e, elle n'a pas de sous-structure, et toutes les tentatives pour acc�der � un de ses champs entra�neront une erreur d'ex�cution.

Notez que RECORD n'est pas un vrai type de donn�es mais seulement un param�tre fictif (placeholder). Il faut aussi r�aliser que lorsqu'une fonction PL/pgSQL est d�clar�e renvoyer un type record, il ne s'agit pas tout � fait du m�me concept qu'une variable record, m�me si une telle fonction peut aussi utiliser une variable record pour contenir son r�sultat. Dans les deux cas la structure r�elle de la ligne n'est pas connue quand la fonction est �crite mais, dans le cas d'une fonction renvoyant un type record, la structure r�elle est d�termin�e quand la requ�te appelante est analys�e, alors qu'une variable record peut changer sa structure de ligne � la vol�e.

35.4.5. RENAME

RENAME ancien nom TO nouveau nom;

En utilisant la d�claration RENAME, vous pouvez changer le nom d'une variable, d'un record ou d'un row (ligne). C'est particuli�rement utile si NEW ou OLD doivent �tre r�f�renc�s par un autre nom dans une proc�dure d�clencheur. Voir aussi ALIAS.

Exemples :

RENAME id TO id_utilisateur;
RENAME cette_var TO cette_autre_var;