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

Précédent | Niveau supérieur | Suivant
SPI_execute_plan | Sommaire | SPI_execute_plan_with_paramlist

## SPI_execute_plan_extended

SPI_execute_plan_extended — exécute une requête préparée par `SPI_prepare`

## Synopsis

    int SPI_execute_plan_extended(SPIPlanPtr plan,
                                  const SPIExecuteOptions * options)

## Description

`SPI_execute_plan_extended` exécute une requête préparée par `SPI_prepare` ou une similaire. La fonction est l'équivalent de `SPI_execute_plan`, à l'exception que l'information sur les valeurs des paramètres passées à la requête est présentée différemment, et des options supplémentaires de contrôle d'exécution peuvent être fournies.

Les valeurs des paramètres de requêtes sont représentées par une structure `ParamListInfo`, ce qui est pratique pour fournir les valeurs qui sont déjà disponibles dans ce format. Des ensembles de paramètres dynamiques peuvent aussi être utilisées, à travers des fonctions d'accrochage spécifiées dans `ParamListInfo`.

De plus, au lieu de toujours accumuler les lignes de résultats dans une structure `SPI_tuptable`, les lignes peuvent être passées à un objet `DestReceiver` fourni par l'appelant au fur et à mesure de leur génération par l'exécuteur de requête. Ceci est particulièrement utile pour les requêtes qui peuvent générer de nombreuses lignes, comme les données peuvent être traitées au fur et à mesure au lieu d'être accumulées en mémoire.

## Arguments

`SPIPlanPtr `plan``

  Expression préparée (retournée par `SPI_prepare`)

`const SPIExecuteOptions * `options``

  Structure contenant les arguments optionnels

Les appelants doivent toujours mettre l'entièreté de la structure `options` à zéro, puis remplir les champs nécessaires à affecter. Ceci assure une compatibilité ascendante du code, car tous les champs qui seront ajoutés à la structure dans le futur seront rétro-compatibles s'ils sont mis à zéro. Les champs de `options` actuellement disponbiles sont :

`ParamListInfo `params``

  Structure de données contenant les types et valeurs des paramètres de requêtes ; NULL si aucun

`bool `read_only``

  `true` pour les exécutions en lecture seule

`bool `no_snapshots``

  `true` autorise l'exécution non atomique des instructions CALL et DO (mais ce champ est ignoré jusqu'à ce que le drapeau `SPI_OPT_NONATOMIC` soit passé à `SPI_connect_ext`)

`bool `must_return_tuples``

  si `true`, lève une erreur si la requête n'est pas d'un type qui renvoie des lignes (ceci n'interdit pas le cas où elle pourrait renvoyer zéro ligne)

`uint64 `tcount``

  Nombre maximal de lignes à retourner ou `0` pour illimité

`DestReceiver * `dest``

  L'objet `DestReceiver` qui va recevoir toutes les lignes émises par la requête ; si NULL, les lignes des résultats sont accumulées dans une structure `SPI_tuptable`, comme dans `SPI_execute_plan`

`ResourceOwner `owner``

  Le propriétaire de ressources qui va garder un compteur de référence sur le plan pendant qu'il est exécuté. Si NULL, CurrentResourceOwner est utilisé. Ce champ est ignoré pour les plans non sauvegardés, comme SPI n'acquiert pas de compteur de référence dessus.

## Valeur retournée

La valeur retournée est la même que pour `SPI_execute_plan`.

Quand `options->dest` est NULL, `SPI_processed` et `SPI_tuptable` sont affectés comme dans `SPI_execute_plan`. Quand `options->dest` n'est pas NULL, `SPI_processed` est mis à zéro et `SPI_tuptable` est mis à NULL. Si un comptage de lignes est requis, l'appellant de l'objet `DestReceiver` doit s'en charger.