← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/spi.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/spi.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Server Programming Interface</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Server Programming"
 
16
HREF="server-programming.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Environment Variables"
 
19
HREF="plpython-envar.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Interface Functions"
 
22
HREF="spi-interface.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="CHAPTER"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Environment Variables"
 
57
HREF="plpython-envar.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="PL/Python - Python Procedural Language"
 
67
HREF="plpython.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
></TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Reference"
 
81
HREF="reference.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="Interface Functions"
 
90
HREF="spi-interface.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><DIV
 
100
CLASS="CHAPTER"
 
101
><H1
 
102
><A
 
103
NAME="SPI"
 
104
></A
 
105
>Chapter 43. Server Programming Interface</H1
 
106
><DIV
 
107
CLASS="TOC"
 
108
><DL
 
109
><DT
 
110
><B
 
111
>Table of Contents</B
 
112
></DT
 
113
><DT
 
114
>43.1. <A
 
115
HREF="spi-interface.html"
 
116
>Interface Functions</A
 
117
></DT
 
118
><DD
 
119
><DL
 
120
><DT
 
121
><A
 
122
HREF="spi-spi-connect.html"
 
123
>SPI_connect</A
 
124
>&nbsp;--&nbsp;connect a procedure to the SPI manager</DT
 
125
><DT
 
126
><A
 
127
HREF="spi-spi-finish.html"
 
128
>SPI_finish</A
 
129
>&nbsp;--&nbsp;disconnect a procedure from the SPI manager</DT
 
130
><DT
 
131
><A
 
132
HREF="spi-spi-push.html"
 
133
>SPI_push</A
 
134
>&nbsp;--&nbsp;push SPI stack to allow recursive SPI usage</DT
 
135
><DT
 
136
><A
 
137
HREF="spi-spi-pop.html"
 
138
>SPI_pop</A
 
139
>&nbsp;--&nbsp;pop SPI stack to return from recursive SPI usage</DT
 
140
><DT
 
141
><A
 
142
HREF="spi-spi-execute.html"
 
143
>SPI_execute</A
 
144
>&nbsp;--&nbsp;execute a command</DT
 
145
><DT
 
146
><A
 
147
HREF="spi-spi-exec.html"
 
148
>SPI_exec</A
 
149
>&nbsp;--&nbsp;execute a read/write command</DT
 
150
><DT
 
151
><A
 
152
HREF="spi-spi-execute-with-args.html"
 
153
>SPI_execute_with_args</A
 
154
>&nbsp;--&nbsp;execute a command with out-of-line parameters</DT
 
155
><DT
 
156
><A
 
157
HREF="spi-spi-prepare.html"
 
158
>SPI_prepare</A
 
159
>&nbsp;--&nbsp;prepare a plan for a command, without executing it yet</DT
 
160
><DT
 
161
><A
 
162
HREF="spi-spi-prepare-cursor.html"
 
163
>SPI_prepare_cursor</A
 
164
>&nbsp;--&nbsp;prepare a plan for a command, without executing it yet</DT
 
165
><DT
 
166
><A
 
167
HREF="spi-spi-prepare-params.html"
 
168
>SPI_prepare_params</A
 
169
>&nbsp;--&nbsp;prepare a plan for a command, without executing it yet</DT
 
170
><DT
 
171
><A
 
172
HREF="spi-spi-getargcount.html"
 
173
>SPI_getargcount</A
 
174
>&nbsp;--&nbsp;return the number of arguments needed by a plan
 
175
  prepared by <CODE
 
176
CLASS="FUNCTION"
 
177
>SPI_prepare</CODE
 
178
></DT
 
179
><DT
 
180
><A
 
181
HREF="spi-spi-getargtypeid.html"
 
182
>SPI_getargtypeid</A
 
183
>&nbsp;--&nbsp;return the data type OID for an argument of
 
184
  a plan prepared by <CODE
 
185
CLASS="FUNCTION"
 
186
>SPI_prepare</CODE
 
187
></DT
 
188
><DT
 
189
><A
 
190
HREF="spi-spi-is-cursor-plan.html"
 
191
>SPI_is_cursor_plan</A
 
192
>&nbsp;--&nbsp;return <TT
 
193
CLASS="SYMBOL"
 
194
>true</TT
 
195
> if a plan
 
196
  prepared by <CODE
 
197
CLASS="FUNCTION"
 
198
>SPI_prepare</CODE
 
199
> can be used with
 
200
  <CODE
 
201
CLASS="FUNCTION"
 
202
>SPI_cursor_open</CODE
 
203
></DT
 
204
><DT
 
205
><A
 
206
HREF="spi-spi-execute-plan.html"
 
207
>SPI_execute_plan</A
 
208
>&nbsp;--&nbsp;execute a plan prepared by <CODE
 
209
CLASS="FUNCTION"
 
210
>SPI_prepare</CODE
 
211
></DT
 
212
><DT
 
213
><A
 
214
HREF="spi-spi-execute-plan-with-paramlist.html"
 
215
>SPI_execute_plan_with_paramlist</A
 
216
>&nbsp;--&nbsp;execute a plan prepared by <CODE
 
217
CLASS="FUNCTION"
 
218
>SPI_prepare</CODE
 
219
></DT
 
220
><DT
 
221
><A
 
222
HREF="spi-spi-execp.html"
 
223
>SPI_execp</A
 
224
>&nbsp;--&nbsp;execute a plan in read/write mode</DT
 
225
><DT
 
226
><A
 
227
HREF="spi-spi-cursor-open.html"
 
228
>SPI_cursor_open</A
 
229
>&nbsp;--&nbsp;set up a cursor using a plan created with <CODE
 
230
CLASS="FUNCTION"
 
231
>SPI_prepare</CODE
 
232
></DT
 
233
><DT
 
234
><A
 
235
HREF="spi-spi-cursor-open-with-args.html"
 
236
>SPI_cursor_open_with_args</A
 
237
>&nbsp;--&nbsp;set up a cursor using a query and parameters</DT
 
238
><DT
 
239
><A
 
240
HREF="spi-spi-cursor-open-with-paramlist.html"
 
241
>SPI_cursor_open_with_paramlist</A
 
242
>&nbsp;--&nbsp;set up a cursor using parameters</DT
 
243
><DT
 
244
><A
 
245
HREF="spi-spi-cursor-find.html"
 
246
>SPI_cursor_find</A
 
247
>&nbsp;--&nbsp;find an existing cursor by name</DT
 
248
><DT
 
249
><A
 
250
HREF="spi-spi-cursor-fetch.html"
 
251
>SPI_cursor_fetch</A
 
252
>&nbsp;--&nbsp;fetch some rows from a cursor</DT
 
253
><DT
 
254
><A
 
255
HREF="spi-spi-cursor-move.html"
 
256
>SPI_cursor_move</A
 
257
>&nbsp;--&nbsp;move a cursor</DT
 
258
><DT
 
259
><A
 
260
HREF="spi-spi-scroll-cursor-fetch.html"
 
261
>SPI_scroll_cursor_fetch</A
 
262
>&nbsp;--&nbsp;fetch some rows from a cursor</DT
 
263
><DT
 
264
><A
 
265
HREF="spi-spi-scroll-cursor-move.html"
 
266
>SPI_scroll_cursor_move</A
 
267
>&nbsp;--&nbsp;move a cursor</DT
 
268
><DT
 
269
><A
 
270
HREF="spi-spi-cursor-close.html"
 
271
>SPI_cursor_close</A
 
272
>&nbsp;--&nbsp;close a cursor</DT
 
273
><DT
 
274
><A
 
275
HREF="spi-spi-saveplan.html"
 
276
>SPI_saveplan</A
 
277
>&nbsp;--&nbsp;save a plan</DT
 
278
></DL
 
279
></DD
 
280
><DT
 
281
>43.2. <A
 
282
HREF="spi-interface-support.html"
 
283
>Interface Support Functions</A
 
284
></DT
 
285
><DD
 
286
><DL
 
287
><DT
 
288
><A
 
289
HREF="spi-spi-fname.html"
 
290
>SPI_fname</A
 
291
>&nbsp;--&nbsp;determine the column name for the specified column number</DT
 
292
><DT
 
293
><A
 
294
HREF="spi-spi-fnumber.html"
 
295
>SPI_fnumber</A
 
296
>&nbsp;--&nbsp;determine the column number for the specified column name</DT
 
297
><DT
 
298
><A
 
299
HREF="spi-spi-getvalue.html"
 
300
>SPI_getvalue</A
 
301
>&nbsp;--&nbsp;return the string value of the specified column</DT
 
302
><DT
 
303
><A
 
304
HREF="spi-spi-getbinval.html"
 
305
>SPI_getbinval</A
 
306
>&nbsp;--&nbsp;return the binary value of the specified column</DT
 
307
><DT
 
308
><A
 
309
HREF="spi-spi-gettype.html"
 
310
>SPI_gettype</A
 
311
>&nbsp;--&nbsp;return the data type name of the specified column</DT
 
312
><DT
 
313
><A
 
314
HREF="spi-spi-gettypeid.html"
 
315
>SPI_gettypeid</A
 
316
>&nbsp;--&nbsp;return the data type <ACRONYM
 
317
CLASS="ACRONYM"
 
318
>OID</ACRONYM
 
319
> of the specified column</DT
 
320
><DT
 
321
><A
 
322
HREF="spi-spi-getrelname.html"
 
323
>SPI_getrelname</A
 
324
>&nbsp;--&nbsp;return the name of the specified relation</DT
 
325
><DT
 
326
><A
 
327
HREF="spi-spi-getnspname.html"
 
328
>SPI_getnspname</A
 
329
>&nbsp;--&nbsp;return the namespace of the specified relation</DT
 
330
></DL
 
331
></DD
 
332
><DT
 
333
>43.3. <A
 
334
HREF="spi-memory.html"
 
335
>Memory Management</A
 
336
></DT
 
337
><DD
 
338
><DL
 
339
><DT
 
340
><A
 
341
HREF="spi-spi-palloc.html"
 
342
>SPI_palloc</A
 
343
>&nbsp;--&nbsp;allocate memory in the upper executor context</DT
 
344
><DT
 
345
><A
 
346
HREF="spi-realloc.html"
 
347
>SPI_repalloc</A
 
348
>&nbsp;--&nbsp;reallocate memory in the upper executor context</DT
 
349
><DT
 
350
><A
 
351
HREF="spi-spi-pfree.html"
 
352
>SPI_pfree</A
 
353
>&nbsp;--&nbsp;free memory in the upper executor context</DT
 
354
><DT
 
355
><A
 
356
HREF="spi-spi-copytuple.html"
 
357
>SPI_copytuple</A
 
358
>&nbsp;--&nbsp;make a copy of a row in the upper executor context</DT
 
359
><DT
 
360
><A
 
361
HREF="spi-spi-returntuple.html"
 
362
>SPI_returntuple</A
 
363
>&nbsp;--&nbsp;prepare to return a tuple as a Datum</DT
 
364
><DT
 
365
><A
 
366
HREF="spi-spi-modifytuple.html"
 
367
>SPI_modifytuple</A
 
368
>&nbsp;--&nbsp;create a row by replacing selected fields of a given row</DT
 
369
><DT
 
370
><A
 
371
HREF="spi-spi-freetuple.html"
 
372
>SPI_freetuple</A
 
373
>&nbsp;--&nbsp;free a row allocated in the upper executor context</DT
 
374
><DT
 
375
><A
 
376
HREF="spi-spi-freetupletable.html"
 
377
>SPI_freetuptable</A
 
378
>&nbsp;--&nbsp;free a row set created by <CODE
 
379
CLASS="FUNCTION"
 
380
>SPI_execute</CODE
 
381
> or a similar
 
382
  function</DT
 
383
><DT
 
384
><A
 
385
HREF="spi-spi-freeplan.html"
 
386
>SPI_freeplan</A
 
387
>&nbsp;--&nbsp;free a previously saved plan</DT
 
388
></DL
 
389
></DD
 
390
><DT
 
391
>43.4. <A
 
392
HREF="spi-visibility.html"
 
393
>Visibility of Data Changes</A
 
394
></DT
 
395
><DT
 
396
>43.5. <A
 
397
HREF="spi-examples.html"
 
398
>Examples</A
 
399
></DT
 
400
></DL
 
401
></DIV
 
402
><P
 
403
>  The <I
 
404
CLASS="FIRSTTERM"
 
405
>Server Programming Interface</I
 
406
>
 
407
  (<ACRONYM
 
408
CLASS="ACRONYM"
 
409
>SPI</ACRONYM
 
410
>) gives writers of user-defined
 
411
  <ACRONYM
 
412
CLASS="ACRONYM"
 
413
>C</ACRONYM
 
414
> functions the ability to run
 
415
  <ACRONYM
 
416
CLASS="ACRONYM"
 
417
>SQL</ACRONYM
 
418
> commands inside their functions.
 
419
  <ACRONYM
 
420
CLASS="ACRONYM"
 
421
>SPI</ACRONYM
 
422
> is a set of
 
423
  interface functions to simplify access to the parser, planner,
 
424
  and executor. <ACRONYM
 
425
CLASS="ACRONYM"
 
426
>SPI</ACRONYM
 
427
> also does some
 
428
  memory management.
 
429
 </P
 
430
><DIV
 
431
CLASS="NOTE"
 
432
><BLOCKQUOTE
 
433
CLASS="NOTE"
 
434
><P
 
435
><B
 
436
>Note: </B
 
437
>   The available procedural languages provide various means to
 
438
   execute SQL commands from procedures.  Most of these facilities are
 
439
   based on SPI, so this documentation might be of use for users
 
440
   of those languages as well.
 
441
  </P
 
442
></BLOCKQUOTE
 
443
></DIV
 
444
><P
 
445
>  To avoid misunderstanding we'll use the term <SPAN
 
446
CLASS="QUOTE"
 
447
>"function"</SPAN
 
448
>
 
449
  when we speak of <ACRONYM
 
450
CLASS="ACRONYM"
 
451
>SPI</ACRONYM
 
452
> interface functions and
 
453
  <SPAN
 
454
CLASS="QUOTE"
 
455
>"procedure"</SPAN
 
456
> for a user-defined C-function that is
 
457
  using <ACRONYM
 
458
CLASS="ACRONYM"
 
459
>SPI</ACRONYM
 
460
>.
 
461
 </P
 
462
><P
 
463
>  Note that if a command invoked via SPI fails, then control will not be
 
464
  returned to your procedure.  Rather, the
 
465
  transaction or subtransaction in which your procedure executes will be
 
466
  rolled back.  (This might seem surprising given that the SPI functions mostly
 
467
  have documented error-return conventions.  Those conventions only apply
 
468
  for errors detected within the SPI functions themselves, however.)
 
469
  It is possible to recover control after an error by establishing your own
 
470
  subtransaction surrounding SPI calls that might fail.  This is not currently
 
471
  documented because the mechanisms required are still in flux.
 
472
 </P
 
473
><P
 
474
>  <ACRONYM
 
475
CLASS="ACRONYM"
 
476
>SPI</ACRONYM
 
477
> functions return a nonnegative result on
 
478
  success (either via a returned integer value or in the global
 
479
  variable <TT
 
480
CLASS="VARNAME"
 
481
>SPI_result</TT
 
482
>, as described below).  On
 
483
  error, a negative result or <TT
 
484
CLASS="SYMBOL"
 
485
>NULL</TT
 
486
> will be returned.
 
487
 </P
 
488
><P
 
489
>  Source code files that use SPI must include the header file
 
490
  <TT
 
491
CLASS="FILENAME"
 
492
>executor/spi.h</TT
 
493
>.
 
494
 </P
 
495
></DIV
 
496
><DIV
 
497
CLASS="NAVFOOTER"
 
498
><HR
 
499
ALIGN="LEFT"
 
500
WIDTH="100%"><TABLE
 
501
SUMMARY="Footer navigation table"
 
502
WIDTH="100%"
 
503
BORDER="0"
 
504
CELLPADDING="0"
 
505
CELLSPACING="0"
 
506
><TR
 
507
><TD
 
508
WIDTH="33%"
 
509
ALIGN="left"
 
510
VALIGN="top"
 
511
><A
 
512
HREF="plpython-envar.html"
 
513
ACCESSKEY="P"
 
514
>Prev</A
 
515
></TD
 
516
><TD
 
517
WIDTH="34%"
 
518
ALIGN="center"
 
519
VALIGN="top"
 
520
><A
 
521
HREF="index.html"
 
522
ACCESSKEY="H"
 
523
>Home</A
 
524
></TD
 
525
><TD
 
526
WIDTH="33%"
 
527
ALIGN="right"
 
528
VALIGN="top"
 
529
><A
 
530
HREF="spi-interface.html"
 
531
ACCESSKEY="N"
 
532
>Next</A
 
533
></TD
 
534
></TR
 
535
><TR
 
536
><TD
 
537
WIDTH="33%"
 
538
ALIGN="left"
 
539
VALIGN="top"
 
540
>Environment Variables</TD
 
541
><TD
 
542
WIDTH="34%"
 
543
ALIGN="center"
 
544
VALIGN="top"
 
545
><A
 
546
HREF="server-programming.html"
 
547
ACCESSKEY="U"
 
548
>Up</A
 
549
></TD
 
550
><TD
 
551
WIDTH="33%"
 
552
ALIGN="right"
 
553
VALIGN="top"
 
554
>Interface Functions</TD
 
555
></TR
 
556
></TABLE
 
557
></DIV
 
558
></BODY
 
559
></HTML
 
560
>
 
 
b'\\ No newline at end of file'