1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter40.Server Programming Interface</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="server-programming.html" title="PartV.Server Programming">
<link rel="prev" href="plpython-database.html" title="39.3.Database Access">
<link rel="next" href="spi-spi-connect.html" title="SPI_connect">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" lang="en" id="spi">
<div class="titlepage"><div><div><h2 class="title">
<a name="spi"></a>Chapter40.Server Programming Interface</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="spi.html#spi-interface">40.1. Interface Functions</a></span></dt>
<dt><span class="sect1"><a href="spi-interface-support.html">40.2. Interface Support Functions</a></span></dt>
<dt><span class="sect1"><a href="spi-memory.html">40.3. Memory Management</a></span></dt>
<dt><span class="sect1"><a href="spi-visibility.html">40.4. Visibility of Data Changes</a></span></dt>
<dt><span class="sect1"><a href="spi-examples.html">40.5. Examples</a></span></dt>
</dl>
</div>
<a name="id733849"></a><p> The <em class="firstterm">Server Programming Interface</em>
(<acronym class="acronym">SPI</acronym>) gives writers of user-defined
<acronym class="acronym">C</acronym> functions the ability to run
<acronym class="acronym">SQL</acronym> commands inside their functions.
<acronym class="acronym">SPI</acronym> is a set of
interface functions to simplify access to the parser, planner,
optimizer, and executor. <acronym class="acronym">SPI</acronym> also does some
memory management.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p> The available procedural languages provide various means to
execute SQL commands from procedures. Most of these facilities are
based on SPI, so this documentation might be of use for users
of those languages as well.
</p>
</div>
<p> To avoid misunderstanding we'll use the term “<span class="quote">function</span>”
when we speak of <acronym class="acronym">SPI</acronym> interface functions and
“<span class="quote">procedure</span>” for a user-defined C-function that is
using <acronym class="acronym">SPI</acronym>.
</p>
<p> Note that if a command invoked via SPI fails, then control will not be
returned to your procedure. Rather, the
transaction or subtransaction in which your procedure executes will be
rolled back. (This may seem surprising given that the SPI functions mostly
have documented error-return conventions. Those conventions only apply
for errors detected within the SPI functions themselves, however.)
It is possible to recover control after an error by establishing your own
subtransaction surrounding SPI calls that might fail. This is not currently
documented because the mechanisms required are still in flux.
</p>
<p> <acronym class="acronym">SPI</acronym> functions return a nonnegative result on
success (either via a returned integer value or in the global
variable <code class="varname">SPI_result</code>, as described below). On
error, a negative result or <code class="symbol">NULL</code> will be returned.
</p>
<p> Source code files that use SPI must include the header file
<code class="filename">executor/spi.h</code>.
</p>
<div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="spi-interface"></a>40.1.Interface Functions</h2></div></div></div></div>
</div></body>
</html>
|
