3
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4
<title>Chapter�39.�Server Programming Interface</title>
5
<link rel="stylesheet" href="stylesheet.css" type="text/css">
6
<link rev="made" href="pgsql-docs@postgresql.org">
7
<meta name="generator" content="DocBook XSL Stylesheets V1.64.1">
8
<link rel="home" href="index.html" title="PostgreSQL 8.0.0beta5 Documentation">
9
<link rel="up" href="server-programming.html" title="Part�V.�Server Programming">
10
<link rel="previous" href="plpython-database.html" title="38.3.�Database Access">
11
<link rel="next" href="spi-spi-connect.html" title="SPI_connect">
13
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" lang="en" id="spi">
14
<div class="titlepage">
15
<div><div><h2 class="title">
16
<a name="spi"></a>Chapter�39.�Server Programming Interface</h2></div></div>
20
<p><b>Table of Contents</b></p>
22
<dt><span class="sect1"><a href="spi.html#spi-interface">39.1. Interface Functions</a></span></dt>
23
<dt><span class="sect1"><a href="spi-interface-support.html">39.2. Interface Support Functions</a></span></dt>
24
<dt><span class="sect1"><a href="spi-memory.html">39.3. Memory Management</a></span></dt>
25
<dt><span class="sect1"><a href="spi-visibility.html">39.4. Visibility of Data Changes</a></span></dt>
26
<dt><span class="sect1"><a href="spi-examples.html">39.5. Examples</a></span></dt>
29
<a name="id2654568"></a><p> The <i class="firstterm">Server Programming Interface</i>
30
(<span class="acronym">SPI</span>) gives writers of user-defined
31
<span class="acronym">C</span> functions the ability to run
32
<span class="acronym">SQL</span> commands inside their functions.
33
<span class="acronym">SPI</span> is a set of
34
interface functions to simplify access to the parser, planner,
35
optimizer, and executor. <span class="acronym">SPI</span> also does some
38
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
39
<h3 class="title">Note</h3>
40
<p> The available procedural languages provide various means to
41
execute SQL commands from procedures. Some of these are based on or
42
modelled after SPI, so this documentation might be of use for users
43
of those languages as well.
46
<p> To avoid misunderstanding we'll use the term “<span class="quote">function</span>”
47
when we speak of <span class="acronym">SPI</span> interface functions and
48
“<span class="quote">procedure</span>” for a user-defined C-function that is
49
using <span class="acronym">SPI</span>.
51
<p> Note that if during the execution of a procedure the transaction is
52
aborted because of an error in a command, then control will not be
53
returned to your procedure. Rather, all work will be rolled back
54
and the server will wait for the next command from the client. A
55
related restriction is the inability to execute
56
<tt class="command">BEGIN</tt>, <tt class="command">COMMIT</tt>, and
57
<tt class="command">ROLLBACK</tt> (transaction control statements) inside
58
a procedure. Both of these restrictions will probably be changed in
61
<p> <span class="acronym">SPI</span> functions return a nonnegative result on
62
success (either via a returned integer value or in the global
63
variable <tt class="varname">SPI_result</tt>, as described below). On
64
error, a negative result or <tt class="symbol">NULL</tt> will be returned.
66
<p> Source code files that use SPI must include the header file
67
<tt class="filename">executor/spi.h</tt>.
69
<div class="sect1" lang="en"><div class="titlepage">
70
<div><div><h2 class="title" style="clear: both">
71
<a name="spi-interface"></a>39.1.�Interface Functions</h2></div></div>