35.8. Curseurs

35.8.2.1. OPEN FOR SELECT

OPEN curseur_non_li� FOR SELECT ...;

La variable curseur est ouverte et re�oit la requ�te sp�cifi�e � ex�cuter. Le curseur ne peut pas �tre d�j� ouvert, et il doit avoir �t� d�clar� comme curseur non li�. (c'est � dire comme une simple variable refcursor). La requ�te SELECT est trait�e de la m�me fa�on que les autres instructionsSELECT dans PL/pgSQL : les noms de variables PL/pgSQL sont remplac�s, et le plan de requ�te est mis en cache pour une possible r�utilisation.

Exemple :

OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;

35.8.2.2. OPEN FOR EXECUTE

OPEN curseur_non_li� FOR EXECUTE cha�ne_requ�te;

La variable curseur est ouverte et re�oit la requ�te sp�cifi�e � ex�cuter. Le curseur ne peut pas �tre d�j� ouvert et il doit avoir �t� d�clar� comme curseur non-li� (c'est-�-dire comme une simple variable refcursor. La requ�te est sp�cifi�e comme une expression cha�ne de la m�me fa�on que dans une commande EXECUTE. Comme d'habitude, ceci donne assez de flexibilit� pour que la requ�te puisse changer d'une ex�cution � l'autre.

Exemple :

OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident($1);

35.8.2.3. Ouverture d'un curseur li�

OPEN curseur_li� [ ( arguments ) ];

Cette forme d'OPEN est utilis�e pour ouvrir une variable curseur � laquelle la requ�te est li�e au moment de la d�claration. Le curseur ne peut pas �tre d�j� ouvert. Une liste des expressions arguments doit appara�tre si et seulement si le curseur a �t� d�clar� comme acceptant des arguments. Ces valeurs seront remplac�es dans la requ�te. Le plan de requ�te pour un curseur li� est toujours consid�r� comme pouvant �tre mis en cache ; il n'y a pas d'�quivalent de la commande EXECUTE dans ce cas.

Exemples :

OPEN curs2;
OPEN curs3(42);

35.8.3.1. FETCH

FETCH curseur INTO cible;

FETCH rapatrie le rang suivant depuis le curseur dans une cible, qui peut �tre une variable ligne, une variable record ou une liste de simples variables s�par�es d'une virgule, exactement comme SELECT INTO. Comme pour SELECT INTO, la variable sp�ciale FOUND peut �tre v�rifi�e pour voir si une ligne a �t� obtenue ou pas.

Exemple :

FETCH curs1 INTO var_ligne;
FETCH curs2 INTO foo, bar, baz;

35.8.3.2. CLOSE

CLOSE curseur;

CLOSE ferme le portail sous-tendant un curseur ouvert. Ceci peut �tre utilis� pour lib�rer des ressources avant la fin de la transaction ou de lib�rer la variable curseur pour pouvoir la r�ouvrir.

Exemple :

CLOSE curs1;

35.8.3.3. Renvoi de curseurs

Les fonctions PL/pgSQL peuvent renvoyer des curseurs � l'appelant. Ceci est utile pour renvoyer plusieurs lignes ou colonnes, sp�cialement avec des ensembles de r�sultats tr�s grands. Pour cela, la fonction ouvre le curseur et renvoie le nom du curseur � l'appelant (ou simplement ouvre le curseur en utilisant un nom de portail sp�cifi� par ou autrement connu par l'appelant). L'appelant peut alors r�cup�rer les lignes � partir du curseur. Le curseur peut �tre ferm� par l'appelant ou il sera ferm� automatiquement � la fin de la transaction.

Le nom du portail utilis� pour un curseur peut �tre sp�cifi� par le d�veloppeur ou peut �tre g�n�r� automatiquement. Pour sp�cifier un nom de portail, affectez simplement une cha�ne � la variable refcursor avant de l'ouvrir. La valeur de la variable refcursor sera utilis�e par OPEN comme nom du portail sous-jacent. N�anmoins, si la variable refcursor est NULL, OPEN g�n�re automatiquement un nom qui n'entre pas en conflit avec tout portail existant et l'affecte � la variable refcursor.

L'exemple suivant montre une fa�on de fournir un nom de curseur par l'appelant :

CREATE TABLE test (col text);
INSERT INTO test VALUES ('123');

CREATE FUNCTION fonction_reference(refcursor) RETURNS refcursor AS '
BEGIN
    OPEN $1 FOR SELECT col FROM test;
    RETURN $1;
END;
' LANGUAGE plpgsql;

BEGIN;
SELECT fonction_reference('curseur_fonction');
FETCH ALL IN curseur_fonction;
COMMIT;

L'exemple suivant utilise la g�n�ration automatique du nom du curseur :

CREATE FUNCTION fonction_reference2() RETURNS refcursor AS '
DECLARE
    ref refcursor;
BEGIN
    OPEN ref FOR SELECT col FROM test;
    RETURN ref;
END;
' LANGUAGE plpgsql;

BEGIN;
SELECT fonction_reference2();

   fonction_reference2
--------------------------
 <unnamed cursor 1>
(1 row)

FETCH ALL IN "<unnamed cursor 1>";
COMMIT;

L'exemple suivant montre une fa�on de renvoyer plusieurs curseurs � une seule fonction :

CREATE FUNCTION ma_fonction(refcursor, refcursor) RETURNS SETOF refcursor AS $$
BEGIN
    OPEN $1 FOR SELECT * FROM table_1;
    RETURN NEXT $1;
    OPEN $2 FOR SELECT * FROM table_2;
    RETURN NEXT $2;
    RETURN;
END;
$$ LANGUAGE plpgsql;

-- doit �tre dans une transaction pour utiliser les curseurs.
BEGIN;

SELECT * FROM ma_fonction('a', 'b');

FETCH ALL FROM a;
FETCH ALL FROM b;
COMMIT;