Description

SPI_prepare crée et retourne un plan d'exécution pour la commande spécifiée mais ne lance pas la commande. Cette fonction ne peut être appelée que depuis une procédure connectée.

Lorsque la même commande ou une commande semblable doit être lancée à plusieurs reprises, il peut être intéressant de ne faire la planification que d'une seule fois. SPI_prepare convertit une chaîne de commande en un plan d'exécution qui peut être lancé plusieurs fois en utilisant SPI_executeplan.

Une commande préparée peut être généralisée en utilisant les paramètres ($1, $2, etc.) en lieu et place de ce qui serait des constantes dans une commande normale. Les valeurs actuelles des paramètres sont alors spécifiées lorsque SPI_executeplan est appelée. Ceci permet à la commande préparée d'être utilisée sur une plage plus grande de situations que cela ne serait possible sans paramètres.

Le plan renvoyé par SPI_prepare ne peut être utilisé que dans l'invocation courante de la procédure puisque SPI_finish libère la mémoire allouée pour le plan. Mais un plan peut être sauvegardé plus longtemps par l'utilisation de la fonction SPI_saveplan.

Arguments

Valeurs de retour

SPI_prepare retourne un pointeur non nul vers un plan d'exécution. En cas d'erreur, NULL sera retourné et SPI_result sera positionnée à un des mêmes codes d'erreur utilisés par SPI_execute sauf qu'il est positionné à SPI_ERROR_ARGUMENT si command est NULL ou si nargs est inférieur à 0 ou si nargs est supérieur à 0 et typesargs est NULL.

Notes

SPIPlanPtr est déclaré comme un pointeur vers un type de structure opaque dans spi.h. Il est déconseillé d'essayer d'accéder à son contenu directement car cela rend votre code plus fragile aux futures versions de PostgreSQL™.

Il y a un inconvénient à utiliser les paramètres : puisque le planificateur ne connaît pas les valeurs qui seront utilisées pour les paramètres, il effectuera des choix pires que ceux qu'il prendrait pour une commande normale avec toutes les constantes visibles.