Documentation PostgreSQL 14.22 » Programmation serveur » Interface de programmation serveur » Fonctions d'interface » SPI_cursor_open

Précédent | Niveau supérieur | Suivant
SPI_execp | Sommaire | SPI_cursor_open_with_args

## SPI_cursor_open

SPI_cursor_open — met en place un curseur en utilisant une requête créée avec `SPI_prepare`

## Synopsis

    Portal SPI_cursor_open(const char * name, SPIPlanPtr plan,
    Datum * values, const char * nulls,
    bool read_only)

## Description

`SPI_cursor_open` met en place un curseur (en interne, un portail) qui lancera une requête préparée par `SPI_prepare`. Les paramètres ont la même signification que les paramètres correspondant à `SPI_execute_plan`.

Utiliser un curseur au lieu de lancer une requête directement à deux avantages. Premièrement, les lignes de résultats peuvent être récupérées un certain nombre à la fois, évitant la saturation de mémoire pour les requêtes qui retournent trop de lignes. Deuxièmement, un portail peut survivre à la fonction C courante (elle peut, en fait, vivre jusqu'à la fin de la transaction courante). Renvoyer le nom du portail à l'appelant de la fonction C donne un moyen de retourner une série de lignes en tant que résultat.

Les données passées seront copiées dans le portail du curseur, donc il peut être libéré alors que le curseur existe toujours.

Cette fonction est maintenant dépréciée en faveur de `SPI_cursor_parse_open`, qui fournit une fonctionnalité équivalente en utilisant une API plus moderne pour gérer les paramètres de requêtes.

## Arguments

`const char * `name``

  nom pour le portail ou `NULL` pour laisser le système choisir un nom

`SPIPlanPtr `plan``

  requête préparée (retournée par `SPI_prepare`)

`Datum * `values``

  Un tableau des valeurs de paramètres actuelles. Doit avoir la même longueur que le nombre d'arguments de la requête.

`const char *`nulls``

  Un tableau décrivant quels paramètres sont NULL. Doit avoir la même longueur que le nombre d'arguments de la requête.

  Si `nulls` vaut `NULL`, alors `SPI_cursor_open` suppose qu'aucun paramètre n'est NULL. Dans le cas contraire, chaque entrée du tableau `nulls` doit valoir `' '` si le paramètre correspondant est non NULL et `'n'` si le paramètre correspondant est NULL (dans ce dernier cas, la valeur réelle de l'entrée `values` correspondante n'a pas d'importance). Notez que `nulls` n'est pas une chaîne de texte. C'est un tableau et, de ce fait, il n'a pas besoin d'un caractère de fin `'\0'`.

`bool `read_only``

  `true` pour les exécutions en lecture seule

## Valeur de retour

Pointeur vers le portail contenant le curseur. Notez qu'il n'y a pas de convention pour le renvoi d'une erreur ; toute erreur sera rapportée via `elog`.