<title>Description</title>
<para>
<function>SPI_freeplan</function> releases a prepared statement
previously returned by <function>SPI_prepare</function> or saved by
<function>SPI_keepplan</function> or <function>SPI_saveplan</function>.
</para>
</refsect1>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
<listitem>
<para>
pointer to statement to free
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>
0 on success;
<symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>plan</parameter>
is <symbol>NULL</symbol> or invalid
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="spi-transaction">
<title>Transaction Management</title>
<para>
It is not possible to run transaction control commands such
as <command>COMMIT</command> and <command>ROLLBACK</command> through SPI
functions such as <function>SPI_execute</function>. There are, however,
separate interface functions that allow transaction control through SPI.
</para>
<para>
It is not generally safe and sensible to start and end transactions in
arbitrary user-defined SQL-callable functions without taking into account
the context in which they are called. For example, a transaction boundary
in the middle of a function that is part of a complex SQL expression that
is part of some SQL command will probably result in obscure internal errors
or crashes. The interface functions presented here are primarily intended
to be used by procedural language implementations to support transaction
management in SQL-level procedures that are invoked by the <command>CALL</command>
command, taking the context of the <command>CALL</command> invocation into
account. SPI-using procedures implemented in C can implement the same logic, but
the details of that are beyond the scope of this documentation.
</para>
<!-- *********************************************** -->
<refentry id="spi-spi-commit">
<indexterm><primary>SPI_commit</primary></indexterm>
<indexterm><primary>SPI_commit_and_chain</primary></indexterm>
<refmeta>
<refentrytitle>SPI_commit</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>SPI_commit</refname>
<refname>SPI_commit_and_chain</refname>
<refpurpose>commit the current transaction</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
void SPI_commit(void)
</synopsis>
<synopsis>
void SPI_commit_and_chain(void)
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<function>SPI_commit</function> commits the current transaction. It is
approximately equivalent to running the SQL
command <command>COMMIT</command>. After the transaction is committed, a
new transaction is automatically started using default transaction
characteristics, so that the caller can continue using SPI facilities.
If there is a failure during commit, the current transaction is instead
rolled back and a new transaction is started, after which the error is
thrown in the usual way.
</para>
<para>
<function>SPI_commit_and_chain</function> is the same, but the new
transaction is started with the same transaction
characteristics as the just finished one, like with the SQL command
<command>COMMIT AND CHAIN</command>.
</para>
<para>
These functions can only be executed if the SPI connection has been set as
nonatomic in the call to <function>SPI_connect_ext</function>.
</para>
</refsect1>
</refentry>
<!-- *********************************************** -->
<refentry id="spi-spi-rollback">
<indexterm><primary>SPI_rollback</primary></indexterm>
<indexterm><primary>SPI_rollback_and_chain</primary></indexterm>
<refmeta>
<refentrytitle>SPI_rollback</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>