← Back to branch summary

~ubuntu-branches/debian/sid/postgresql-9.3/sid

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/trigger-interface.html

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2013-05-08 05:39:52 UTC
  • Revision ID: package-import@ubuntu.com-20130508053952-1j7uilp7mjtrvq8q
Tags: upstream-9.3~beta1
Import upstream version 9.3~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/trigger-interface.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
>Writing Trigger Functions in C</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.3beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Triggers"
 
16
HREF="triggers.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Visibility of Data Changes"
 
19
HREF="trigger-datachanges.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="A Complete Trigger Example"
 
22
HREF="trigger-example.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="2013-05-06T21:00:50"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
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.3beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Visibility of Data Changes"
 
57
HREF="trigger-datachanges.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
HREF="triggers.html"
 
67
ACCESSKEY="U"
 
68
>Up</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 36. Triggers</TD
 
75
><TD
 
76
WIDTH="20%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="A Complete Trigger Example"
 
81
HREF="trigger-example.html"
 
82
ACCESSKEY="N"
 
83
>Next</A
 
84
></TD
 
85
></TR
 
86
></TABLE
 
87
><HR
 
88
ALIGN="LEFT"
 
89
WIDTH="100%"></DIV
 
90
><DIV
 
91
CLASS="SECT1"
 
92
><H1
 
93
CLASS="SECT1"
 
94
><A
 
95
NAME="TRIGGER-INTERFACE"
 
96
>36.3. Writing Trigger Functions in C</A
 
97
></H1
 
98
><P
 
99
>    This section describes the low-level details of the interface to a
 
100
    trigger function.  This information is only needed when writing
 
101
    trigger functions in C.  If you are using a higher-level language then
 
102
    these details are handled for you.  In most cases you should consider
 
103
    using a procedural language before writing your triggers in C.  The
 
104
    documentation of each procedural language explains how to write a
 
105
    trigger in that language.
 
106
   </P
 
107
><P
 
108
>    Trigger functions must use the <SPAN
 
109
CLASS="QUOTE"
 
110
>"version 1"</SPAN
 
111
> function manager
 
112
    interface.
 
113
   </P
 
114
><P
 
115
>    When a function is called by the trigger manager, it is not passed
 
116
    any normal arguments, but it is passed a <SPAN
 
117
CLASS="QUOTE"
 
118
>"context"</SPAN
 
119
>
 
120
    pointer pointing to a <TT
 
121
CLASS="STRUCTNAME"
 
122
>TriggerData</TT
 
123
> structure.  C
 
124
    functions can check whether they were called from the trigger
 
125
    manager or not by executing the macro:
 
126
</P><PRE
 
127
CLASS="PROGRAMLISTING"
 
128
>CALLED_AS_TRIGGER(fcinfo)</PRE
 
129
><P>
 
130
    which expands to:
 
131
</P><PRE
 
132
CLASS="PROGRAMLISTING"
 
133
>((fcinfo)-&gt;context != NULL &amp;&amp; IsA((fcinfo)-&gt;context, TriggerData))</PRE
 
134
><P>
 
135
    If this returns true, then it is safe to cast
 
136
    <TT
 
137
CLASS="LITERAL"
 
138
>fcinfo-&gt;context</TT
 
139
> to type <TT
 
140
CLASS="LITERAL"
 
141
>TriggerData
 
142
    *</TT
 
143
> and make use of the pointed-to
 
144
    <TT
 
145
CLASS="STRUCTNAME"
 
146
>TriggerData</TT
 
147
> structure.  The function must
 
148
    <SPAN
 
149
CLASS="emphasis"
 
150
><I
 
151
CLASS="EMPHASIS"
 
152
>not</I
 
153
></SPAN
 
154
> alter the <TT
 
155
CLASS="STRUCTNAME"
 
156
>TriggerData</TT
 
157
>
 
158
    structure or any of the data it points to.
 
159
   </P
 
160
><P
 
161
>    <TT
 
162
CLASS="STRUCTNAME"
 
163
>struct TriggerData</TT
 
164
> is defined in
 
165
    <TT
 
166
CLASS="FILENAME"
 
167
>commands/trigger.h</TT
 
168
>:
 
169
 
 
170
</P><PRE
 
171
CLASS="PROGRAMLISTING"
 
172
>typedef struct TriggerData
 
173
{
 
174
    NodeTag       type;
 
175
    TriggerEvent  tg_event;
 
176
    Relation      tg_relation;
 
177
    HeapTuple     tg_trigtuple;
 
178
    HeapTuple     tg_newtuple;
 
179
    Trigger      *tg_trigger;
 
180
    Buffer        tg_trigtuplebuf;
 
181
    Buffer        tg_newtuplebuf;
 
182
} TriggerData;</PRE
 
183
><P>
 
184
 
 
185
    where the members are defined as follows:
 
186
 
 
187
    <P
 
188
></P
 
189
></P><DIV
 
190
CLASS="VARIABLELIST"
 
191
><DL
 
192
><DT
 
193
><TT
 
194
CLASS="STRUCTFIELD"
 
195
>type</TT
 
196
></DT
 
197
><DD
 
198
><P
 
199
>        Always <TT
 
200
CLASS="LITERAL"
 
201
>T_TriggerData</TT
 
202
>.
 
203
       </P
 
204
></DD
 
205
><DT
 
206
><TT
 
207
CLASS="STRUCTFIELD"
 
208
>tg_event</TT
 
209
></DT
 
210
><DD
 
211
><P
 
212
>        Describes the event for which the function is called. You can use the
 
213
        following macros to examine <TT
 
214
CLASS="LITERAL"
 
215
>tg_event</TT
 
216
>:
 
217
 
 
218
        <P
 
219
></P
 
220
></P><DIV
 
221
CLASS="VARIABLELIST"
 
222
><DL
 
223
><DT
 
224
><TT
 
225
CLASS="LITERAL"
 
226
>TRIGGER_FIRED_BEFORE(tg_event)</TT
 
227
></DT
 
228
><DD
 
229
><P
 
230
>            Returns true if the trigger fired before the operation.
 
231
           </P
 
232
></DD
 
233
><DT
 
234
><TT
 
235
CLASS="LITERAL"
 
236
>TRIGGER_FIRED_AFTER(tg_event)</TT
 
237
></DT
 
238
><DD
 
239
><P
 
240
>            Returns true if the trigger fired after the operation.
 
241
           </P
 
242
></DD
 
243
><DT
 
244
><TT
 
245
CLASS="LITERAL"
 
246
>TRIGGER_FIRED_INSTEAD(tg_event)</TT
 
247
></DT
 
248
><DD
 
249
><P
 
250
>            Returns true if the trigger fired instead of the operation.
 
251
           </P
 
252
></DD
 
253
><DT
 
254
><TT
 
255
CLASS="LITERAL"
 
256
>TRIGGER_FIRED_FOR_ROW(tg_event)</TT
 
257
></DT
 
258
><DD
 
259
><P
 
260
>            Returns true if the trigger fired for a row-level event.
 
261
           </P
 
262
></DD
 
263
><DT
 
264
><TT
 
265
CLASS="LITERAL"
 
266
>TRIGGER_FIRED_FOR_STATEMENT(tg_event)</TT
 
267
></DT
 
268
><DD
 
269
><P
 
270
>            Returns true if the trigger fired for a statement-level event.
 
271
           </P
 
272
></DD
 
273
><DT
 
274
><TT
 
275
CLASS="LITERAL"
 
276
>TRIGGER_FIRED_BY_INSERT(tg_event)</TT
 
277
></DT
 
278
><DD
 
279
><P
 
280
>            Returns true if the trigger was fired by an <TT
 
281
CLASS="COMMAND"
 
282
>INSERT</TT
 
283
> command.
 
284
           </P
 
285
></DD
 
286
><DT
 
287
><TT
 
288
CLASS="LITERAL"
 
289
>TRIGGER_FIRED_BY_UPDATE(tg_event)</TT
 
290
></DT
 
291
><DD
 
292
><P
 
293
>            Returns true if the trigger was fired by an <TT
 
294
CLASS="COMMAND"
 
295
>UPDATE</TT
 
296
> command.
 
297
           </P
 
298
></DD
 
299
><DT
 
300
><TT
 
301
CLASS="LITERAL"
 
302
>TRIGGER_FIRED_BY_DELETE(tg_event)</TT
 
303
></DT
 
304
><DD
 
305
><P
 
306
>            Returns true if the trigger was fired by a <TT
 
307
CLASS="COMMAND"
 
308
>DELETE</TT
 
309
> command.
 
310
           </P
 
311
></DD
 
312
><DT
 
313
><TT
 
314
CLASS="LITERAL"
 
315
>TRIGGER_FIRED_BY_TRUNCATE(tg_event)</TT
 
316
></DT
 
317
><DD
 
318
><P
 
319
>            Returns true if the trigger was fired by a <TT
 
320
CLASS="COMMAND"
 
321
>TRUNCATE</TT
 
322
> command.
 
323
           </P
 
324
></DD
 
325
></DL
 
326
></DIV
 
327
><P>
 
328
       </P
 
329
></DD
 
330
><DT
 
331
><TT
 
332
CLASS="STRUCTFIELD"
 
333
>tg_relation</TT
 
334
></DT
 
335
><DD
 
336
><P
 
337
>        A pointer to a structure describing the relation that the trigger fired for.
 
338
        Look at <TT
 
339
CLASS="FILENAME"
 
340
>utils/rel.h</TT
 
341
> for details about
 
342
        this structure.  The most interesting things are
 
343
        <TT
 
344
CLASS="LITERAL"
 
345
>tg_relation-&gt;rd_att</TT
 
346
> (descriptor of the relation
 
347
        tuples) and <TT
 
348
CLASS="LITERAL"
 
349
>tg_relation-&gt;rd_rel-&gt;relname</TT
 
350
>
 
351
        (relation name; the type is not <TT
 
352
CLASS="TYPE"
 
353
>char*</TT
 
354
> but
 
355
        <TT
 
356
CLASS="TYPE"
 
357
>NameData</TT
 
358
>; use
 
359
        <TT
 
360
CLASS="LITERAL"
 
361
>SPI_getrelname(tg_relation)</TT
 
362
> to get a <TT
 
363
CLASS="TYPE"
 
364
>char*</TT
 
365
> if you
 
366
        need a copy of the name).
 
367
       </P
 
368
></DD
 
369
><DT
 
370
><TT
 
371
CLASS="STRUCTFIELD"
 
372
>tg_trigtuple</TT
 
373
></DT
 
374
><DD
 
375
><P
 
376
>        A pointer to the row for which the trigger was fired. This is
 
377
        the row being inserted, updated, or deleted.  If this trigger
 
378
        was fired for an <TT
 
379
CLASS="COMMAND"
 
380
>INSERT</TT
 
381
> or
 
382
        <TT
 
383
CLASS="COMMAND"
 
384
>DELETE</TT
 
385
> then this is what you should return
 
386
        from the function if you don't want to replace the row with
 
387
        a different one (in the case of <TT
 
388
CLASS="COMMAND"
 
389
>INSERT</TT
 
390
>) or
 
391
        skip the operation.
 
392
       </P
 
393
></DD
 
394
><DT
 
395
><TT
 
396
CLASS="STRUCTFIELD"
 
397
>tg_newtuple</TT
 
398
></DT
 
399
><DD
 
400
><P
 
401
>        A pointer to the new version of the row, if the trigger was
 
402
        fired for an <TT
 
403
CLASS="COMMAND"
 
404
>UPDATE</TT
 
405
>, and <TT
 
406
CLASS="SYMBOL"
 
407
>NULL</TT
 
408
> if
 
409
        it is for an <TT
 
410
CLASS="COMMAND"
 
411
>INSERT</TT
 
412
> or a
 
413
        <TT
 
414
CLASS="COMMAND"
 
415
>DELETE</TT
 
416
>. This is what you have to return
 
417
        from the function if the event is an <TT
 
418
CLASS="COMMAND"
 
419
>UPDATE</TT
 
420
>
 
421
        and you don't want to replace this row by a different one or
 
422
        skip the operation.
 
423
       </P
 
424
></DD
 
425
><DT
 
426
><TT
 
427
CLASS="STRUCTFIELD"
 
428
>tg_trigger</TT
 
429
></DT
 
430
><DD
 
431
><P
 
432
>        A pointer to a structure of type <TT
 
433
CLASS="STRUCTNAME"
 
434
>Trigger</TT
 
435
>,
 
436
        defined in <TT
 
437
CLASS="FILENAME"
 
438
>utils/reltrigger.h</TT
 
439
>:
 
440
 
 
441
</P><PRE
 
442
CLASS="PROGRAMLISTING"
 
443
>typedef struct Trigger
 
444
{
 
445
    Oid         tgoid;
 
446
    char       *tgname;
 
447
    Oid         tgfoid;
 
448
    int16       tgtype;
 
449
    char        tgenabled;
 
450
    bool        tgisinternal;
 
451
    Oid         tgconstrrelid;
 
452
    Oid         tgconstrindid;
 
453
    Oid         tgconstraint;
 
454
    bool        tgdeferrable;
 
455
    bool        tginitdeferred;
 
456
    int16       tgnargs;
 
457
    int16       tgnattr;
 
458
    int16      *tgattr;
 
459
    char      **tgargs;
 
460
    char       *tgqual;
 
461
} Trigger;</PRE
 
462
><P>
 
463
 
 
464
       where <TT
 
465
CLASS="STRUCTFIELD"
 
466
>tgname</TT
 
467
> is the trigger's name,
 
468
       <TT
 
469
CLASS="STRUCTFIELD"
 
470
>tgnargs</TT
 
471
> is the number of arguments in
 
472
       <TT
 
473
CLASS="STRUCTFIELD"
 
474
>tgargs</TT
 
475
>, and <TT
 
476
CLASS="STRUCTFIELD"
 
477
>tgargs</TT
 
478
> is an array of
 
479
       pointers to the arguments specified in the <TT
 
480
CLASS="COMMAND"
 
481
>CREATE
 
482
       TRIGGER</TT
 
483
> statement. The other members are for internal use
 
484
       only.
 
485
       </P
 
486
></DD
 
487
><DT
 
488
><TT
 
489
CLASS="STRUCTFIELD"
 
490
>tg_trigtuplebuf</TT
 
491
></DT
 
492
><DD
 
493
><P
 
494
>        The buffer containing <TT
 
495
CLASS="STRUCTFIELD"
 
496
>tg_trigtuple</TT
 
497
>, or <TT
 
498
CLASS="SYMBOL"
 
499
>InvalidBuffer</TT
 
500
> if there
 
501
        is no such tuple or it is not stored in a disk buffer.
 
502
       </P
 
503
></DD
 
504
><DT
 
505
><TT
 
506
CLASS="STRUCTFIELD"
 
507
>tg_newtuplebuf</TT
 
508
></DT
 
509
><DD
 
510
><P
 
511
>        The buffer containing <TT
 
512
CLASS="STRUCTFIELD"
 
513
>tg_newtuple</TT
 
514
>, or <TT
 
515
CLASS="SYMBOL"
 
516
>InvalidBuffer</TT
 
517
> if there
 
518
        is no such tuple or it is not stored in a disk buffer.
 
519
       </P
 
520
></DD
 
521
></DL
 
522
></DIV
 
523
><P>
 
524
   </P
 
525
><P
 
526
>    A trigger function must return either a
 
527
    <TT
 
528
CLASS="STRUCTNAME"
 
529
>HeapTuple</TT
 
530
> pointer or a <TT
 
531
CLASS="SYMBOL"
 
532
>NULL</TT
 
533
> pointer
 
534
    (<SPAN
 
535
CLASS="emphasis"
 
536
><I
 
537
CLASS="EMPHASIS"
 
538
>not</I
 
539
></SPAN
 
540
> an SQL null value, that is, do not set <TT
 
541
CLASS="PARAMETER"
 
542
>isNull</TT
 
543
> true).
 
544
    Be careful to return either
 
545
    <TT
 
546
CLASS="STRUCTFIELD"
 
547
>tg_trigtuple</TT
 
548
> or <TT
 
549
CLASS="STRUCTFIELD"
 
550
>tg_newtuple</TT
 
551
>,
 
552
    as appropriate, if you don't want to modify the row being operated on.
 
553
   </P
 
554
></DIV
 
555
><DIV
 
556
CLASS="NAVFOOTER"
 
557
><HR
 
558
ALIGN="LEFT"
 
559
WIDTH="100%"><TABLE
 
560
SUMMARY="Footer navigation table"
 
561
WIDTH="100%"
 
562
BORDER="0"
 
563
CELLPADDING="0"
 
564
CELLSPACING="0"
 
565
><TR
 
566
><TD
 
567
WIDTH="33%"
 
568
ALIGN="left"
 
569
VALIGN="top"
 
570
><A
 
571
HREF="trigger-datachanges.html"
 
572
ACCESSKEY="P"
 
573
>Prev</A
 
574
></TD
 
575
><TD
 
576
WIDTH="34%"
 
577
ALIGN="center"
 
578
VALIGN="top"
 
579
><A
 
580
HREF="index.html"
 
581
ACCESSKEY="H"
 
582
>Home</A
 
583
></TD
 
584
><TD
 
585
WIDTH="33%"
 
586
ALIGN="right"
 
587
VALIGN="top"
 
588
><A
 
589
HREF="trigger-example.html"
 
590
ACCESSKEY="N"
 
591
>Next</A
 
592
></TD
 
593
></TR
 
594
><TR
 
595
><TD
 
596
WIDTH="33%"
 
597
ALIGN="left"
 
598
VALIGN="top"
 
599
>Visibility of Data Changes</TD
 
600
><TD
 
601
WIDTH="34%"
 
602
ALIGN="center"
 
603
VALIGN="top"
 
604
><A
 
605
HREF="triggers.html"
 
606
ACCESSKEY="U"
 
607
>Up</A
 
608
></TD
 
609
><TD
 
610
WIDTH="33%"
 
611
ALIGN="right"
 
612
VALIGN="top"
 
613
>A Complete Trigger Example</TD
 
614
></TR
 
615
></TABLE
 
616
></DIV
 
617
></BODY
 
618
></HTML
 
619
>
 
 
b'\\ No newline at end of file'