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

Précédent | Niveau supérieur | Suivant
SPI_exec | Sommaire | SPI_execute_with_args

## SPI_execute_extended

SPI_execute_extended — Exécute une commande avec des paramètres hors ligne

## Synopsis

    int SPI_execute_extended(const char *command,
                             const SPIExecuteOptions * options)

## Description

`SPI_execute_extended` exécute une commande qui peut inclure des références à des paramètres fournis en externe. Le texte de commande se réfère à un paramètre sous la forme `$`n``, et l'objet `options->params` (si fourni) donne des informations sur les valeurs et le type de chacun des symboles. De nombreuses options d'exécution peuvent aussi être spécifiées dans la structure `options`

L'objet `options->params` doit normalement marquer chaque paramètre avec le drapeau `PARAM_FLAG_CONST`, dès qu'un plan unique est toujours utilisé pour cette requête.

Si `options->dest` n'est pas NULL, alors les lignes de résultats sont passées à cet objet lors de leur génération par l'exécuteur, au lieu d'être accumulées dans `SPI_tuptable`. Employer un objet `DestReceiver` fourni par l'appelant est particulièrement utile pour les requêtes qui peuvent générer de nombreuses lignes, dès lors que les données sont traitées à la volée au lieu de s'accumuler en mémoire.

## Arguments

`const char * `command``

  Chaîne de caractères de la commande

`const SPIExecuteOptions * `options``

  Structure contenant les arguments optionnels

Les codes appelants doivent toujours mettre à zéro l'entièreté de la structure `options`, et ensuite remplir les champs souhaités. Ceci permet d'assurer la compatibilité ascendante du code, car tous les champs ajoutés à la structure dans le futur seront définis comme étant rétrocompatibles s'ils sont mis à zéro. Les champs de `options` actuellement disponibles 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 maximum de lignes à retourner, ou `0` pour aucune limite

`DestReceiver * `dest``

  L'objet `DestReceiver` qui recevra toutes les lignes émises par la requête ; si NULL, les lignes de résultats sont accumulés dans une structure `SPI_tuptable`, comme avec `SPI_execute`

`ResourceOwner `owner``

  Ce champ est présent pour la cohérence avec `SPI_execute_plan_extended`, mais est ignoré, puisque le plan utilisé par `SPI_execute_extended` n'est jamais sauvegardé.

## Valeur de retour

La valeur de retour est la même que pour `SPI_execute`.

Quand `options->dest` est NULL, `SPI_processed` et `SPI_tuptable` sont affectés comme dans `SPI_execute`. 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'objet `DestReceiver` appelant doit s'en occuper.