ok
Direktori : /opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/ |
Current File : //opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/trigger-interface.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Writing Trigger Functions in C</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 9.2.24 Documentation" HREF="index.html"><LINK REL="UP" TITLE="Triggers" HREF="triggers.html"><LINK REL="PREVIOUS" TITLE="Visibility of Data Changes" HREF="trigger-datachanges.html"><LINK REL="NEXT" TITLE="A Complete Trigger Example" HREF="trigger-example.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2017-11-06T22:43:11"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" ><A HREF="index.html" >PostgreSQL 9.2.24 Documentation</A ></TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A TITLE="Visibility of Data Changes" HREF="trigger-datachanges.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="triggers.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Chapter 36. Triggers</TD ><TD WIDTH="20%" ALIGN="right" VALIGN="top" ><A TITLE="A Complete Trigger Example" HREF="trigger-example.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="TRIGGER-INTERFACE" >36.3. Writing Trigger Functions in C</A ></H1 ><P > This section describes the low-level details of the interface to a trigger function. This information is only needed when writing trigger functions in C. If you are using a higher-level language then these details are handled for you. In most cases you should consider using a procedural language before writing your triggers in C. The documentation of each procedural language explains how to write a trigger in that language. </P ><P > Trigger functions must use the <SPAN CLASS="QUOTE" >"version 1"</SPAN > function manager interface. </P ><P > When a function is called by the trigger manager, it is not passed any normal arguments, but it is passed a <SPAN CLASS="QUOTE" >"context"</SPAN > pointer pointing to a <TT CLASS="STRUCTNAME" >TriggerData</TT > structure. C functions can check whether they were called from the trigger manager or not by executing the macro: </P><PRE CLASS="PROGRAMLISTING" >CALLED_AS_TRIGGER(fcinfo)</PRE ><P> which expands to: </P><PRE CLASS="PROGRAMLISTING" >((fcinfo)->context != NULL && IsA((fcinfo)->context, TriggerData))</PRE ><P> If this returns true, then it is safe to cast <TT CLASS="LITERAL" >fcinfo->context</TT > to type <TT CLASS="LITERAL" >TriggerData *</TT > and make use of the pointed-to <TT CLASS="STRUCTNAME" >TriggerData</TT > structure. The function must <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >not</I ></SPAN > alter the <TT CLASS="STRUCTNAME" >TriggerData</TT > structure or any of the data it points to. </P ><P > <TT CLASS="STRUCTNAME" >struct TriggerData</TT > is defined in <TT CLASS="FILENAME" >commands/trigger.h</TT >: </P><PRE CLASS="PROGRAMLISTING" >typedef struct TriggerData { NodeTag type; TriggerEvent tg_event; Relation tg_relation; HeapTuple tg_trigtuple; HeapTuple tg_newtuple; Trigger *tg_trigger; Buffer tg_trigtuplebuf; Buffer tg_newtuplebuf; } TriggerData;</PRE ><P> where the members are defined as follows: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="STRUCTFIELD" >type</TT ></DT ><DD ><P > Always <TT CLASS="LITERAL" >T_TriggerData</TT >. </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_event</TT ></DT ><DD ><P > Describes the event for which the function is called. You can use the following macros to examine <TT CLASS="LITERAL" >tg_event</TT >: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_BEFORE(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger fired before the operation. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_AFTER(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger fired after the operation. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_INSTEAD(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger fired instead of the operation. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_FOR_ROW(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger fired for a row-level event. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_FOR_STATEMENT(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger fired for a statement-level event. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_BY_INSERT(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger was fired by an <TT CLASS="COMMAND" >INSERT</TT > command. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_BY_UPDATE(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger was fired by an <TT CLASS="COMMAND" >UPDATE</TT > command. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_BY_DELETE(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger was fired by a <TT CLASS="COMMAND" >DELETE</TT > command. </P ></DD ><DT ><TT CLASS="LITERAL" >TRIGGER_FIRED_BY_TRUNCATE(tg_event)</TT ></DT ><DD ><P > Returns true if the trigger was fired by a <TT CLASS="COMMAND" >TRUNCATE</TT > command. </P ></DD ></DL ></DIV ><P> </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_relation</TT ></DT ><DD ><P > A pointer to a structure describing the relation that the trigger fired for. Look at <TT CLASS="FILENAME" >utils/rel.h</TT > for details about this structure. The most interesting things are <TT CLASS="LITERAL" >tg_relation->rd_att</TT > (descriptor of the relation tuples) and <TT CLASS="LITERAL" >tg_relation->rd_rel->relname</TT > (relation name; the type is not <TT CLASS="TYPE" >char*</TT > but <TT CLASS="TYPE" >NameData</TT >; use <TT CLASS="LITERAL" >SPI_getrelname(tg_relation)</TT > to get a <TT CLASS="TYPE" >char*</TT > if you need a copy of the name). </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_trigtuple</TT ></DT ><DD ><P > A pointer to the row for which the trigger was fired. This is the row being inserted, updated, or deleted. If this trigger was fired for an <TT CLASS="COMMAND" >INSERT</TT > or <TT CLASS="COMMAND" >DELETE</TT > then this is what you should return from the function if you don't want to replace the row with a different one (in the case of <TT CLASS="COMMAND" >INSERT</TT >) or skip the operation. </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_newtuple</TT ></DT ><DD ><P > A pointer to the new version of the row, if the trigger was fired for an <TT CLASS="COMMAND" >UPDATE</TT >, and <TT CLASS="SYMBOL" >NULL</TT > if it is for an <TT CLASS="COMMAND" >INSERT</TT > or a <TT CLASS="COMMAND" >DELETE</TT >. This is what you have to return from the function if the event is an <TT CLASS="COMMAND" >UPDATE</TT > and you don't want to replace this row by a different one or skip the operation. </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_trigger</TT ></DT ><DD ><P > A pointer to a structure of type <TT CLASS="STRUCTNAME" >Trigger</TT >, defined in <TT CLASS="FILENAME" >utils/reltrigger.h</TT >: </P><PRE CLASS="PROGRAMLISTING" >typedef struct Trigger { Oid tgoid; char *tgname; Oid tgfoid; int16 tgtype; char tgenabled; bool tgisinternal; Oid tgconstrrelid; Oid tgconstrindid; Oid tgconstraint; bool tgdeferrable; bool tginitdeferred; int16 tgnargs; int16 tgnattr; int16 *tgattr; char **tgargs; char *tgqual; } Trigger;</PRE ><P> where <TT CLASS="STRUCTFIELD" >tgname</TT > is the trigger's name, <TT CLASS="STRUCTFIELD" >tgnargs</TT > is the number of arguments in <TT CLASS="STRUCTFIELD" >tgargs</TT >, and <TT CLASS="STRUCTFIELD" >tgargs</TT > is an array of pointers to the arguments specified in the <TT CLASS="COMMAND" >CREATE TRIGGER</TT > statement. The other members are for internal use only. </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_trigtuplebuf</TT ></DT ><DD ><P > The buffer containing <TT CLASS="STRUCTFIELD" >tg_trigtuple</TT >, or <TT CLASS="SYMBOL" >InvalidBuffer</TT > if there is no such tuple or it is not stored in a disk buffer. </P ></DD ><DT ><TT CLASS="STRUCTFIELD" >tg_newtuplebuf</TT ></DT ><DD ><P > The buffer containing <TT CLASS="STRUCTFIELD" >tg_newtuple</TT >, or <TT CLASS="SYMBOL" >InvalidBuffer</TT > if there is no such tuple or it is not stored in a disk buffer. </P ></DD ></DL ></DIV ><P> </P ><P > A trigger function must return either a <TT CLASS="STRUCTNAME" >HeapTuple</TT > pointer or a <TT CLASS="SYMBOL" >NULL</TT > pointer (<SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >not</I ></SPAN > an SQL null value, that is, do not set <TT CLASS="PARAMETER" >isNull</TT > true). Be careful to return either <TT CLASS="STRUCTFIELD" >tg_trigtuple</TT > or <TT CLASS="STRUCTFIELD" >tg_newtuple</TT >, as appropriate, if you don't want to modify the row being operated on. </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="trigger-datachanges.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="trigger-example.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Visibility of Data Changes</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="triggers.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >A Complete Trigger Example</TD ></TR ></TABLE ></DIV ></BODY ></HTML >