Trigger API
The mechanism provided to define the action that takes place when a database trigger
event occurs is a jBC subroutine. The name of the subroutine is specified in the
create-trigger command. A different
subroutine can be defined for each of the nine database trigger events, however
it is usually more convenient to use one subroutine for each file that has a
trigger defined, distinguishing between the different events in the subroutine.
The subroutine can used to define ancillary updates that need to occur as a
result of the primary update. The seven parameters passed to the subroutine
allow interrogation and (where applicable) manipulation of the record being updated.
| |
Subroutine
Parameter |
Description |
| 1 |
Filevar |
The file variable associated with the update. For example, you can do:
WRITE var ON filevar,"newkey"
however you must then be very careful of calling this subroutine recursively. |
| 2 |
Event |
One of the TRIGGER_TYPE_xxx values to show which of the 9 events is currently about to
take place. Defined in source $JBCRELEASEDIR/include/JBC.h (Unix) and %JBCRELEASEDIR%\include\JBC.h (Windows).
| Type |
Event |
| TRIGGER_TYPE_PREWRITE |
before a WRITE occured |
| TRIGGER_TYPE_POSTWRITE |
after a WRITE occured |
| TRIGGER_TYPE_PREDELETE |
before a DELETE occured |
| TRIGGER_TYPE_POSTDELETE |
after a DELETE occured |
| TRIGGER_TYPE_PRECLEAR |
before a CLEARFILE occured |
| TRIGGER_TYPE_POSTCLEAR |
after a CLEARFILE occured |
| TRIGGER_TYPE_PREREAD |
before a READ occured |
| TRIGGER_TYPE_POSTREAD |
after a READ occured |
| TRIGGER_TYPE_POSTOPEN |
after an OPEN occured |
|
| 3 |
Prerc |
The current return code (i.e. status) of the action. For all the TRIGGER_TYPE_PRExx
events, it will be 0. For all the TRIGGER_TYPE_POSTxx events, it will show the current
status of the action, with 0 meaning that the action was performed successfully and any other
value showing the update failed. For example, if a WRITE fails because the lock table is
full, the value in prerc is 1. |
| 4 |
Flags |
Various flags to show things like if a WRITE or WRITEV was performed.
Not used yet. |
| 5 |
RecordKey |
The record key (or item-id) of the WRITE or DELETE being performed. For CLEARFILE, this is set to null. |
| 6 |
Record |
For the WRITE actions, this is the record currently being updated. For the DELETE or
CLEARFILE actions, this is set to null. You can modify this variable in your
subroutine if you wish.
However, the modification will be discarded unless the create-trigger
command was executed with the -a option. |
| 7 |
Userrc |
You can set this to a non-zero value for the TRIGGER_TYPE_PRExxx actions so that it
will abort the action. However, unless the -t option was used with the create-trigger command, it will be meaningless.
There are two options to setting this value:
- Any negative value will cause the action to be terminated. However, nothing will be
flagged to the application, and it will appear to all intents and purposes that the action
performed. Any positive value is taken to be the return code for the action.
- For example, when a WRITE completes it will normally give a return code of
0. If this variable is then set to say 13 (which is the Unix error number for
"Permission denied") then the application will fall into the jBASE debugger
with error code 13.
|
Assignment of Trigger Subroutine Arguments
The arguments of a trigger subroutine are generally assigned by the database
management system at the time the subroutine is invoked, but there are
exceptions. The subroutine can in turn assign or reassign argument values
if the trigger was created with the -a option. The table below
summarizes the state of each argument at the time the subroutine is invoked,
according to each trigger type. Note that there are three cases where record is null
even though the record key is assigned, i.e., pre- and post-delete and
pre-read. This is so for the read event because there is no need to read a
record before reading a record, and in the case of the delete events,
because the attempt to delete a non-existent record warrants no further
action. If an application requires a record to be verified prior to deleting it,
then that operation that should be performed at a higher level.
|
Trigger Type
|
filevar |
event |
prerc |
flags |
recordkey |
record |
userrc |
|
Pre-Write |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
ASSIGNED |
ASSIGNED |
USER
DEFINABLE |
|
Post-Write |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
ASSIGNED |
ASSIGNED |
USER
DEFINABLE |
|
Pre-Delete |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
ASSIGNED |
NULL |
USER
DEFINABLE |
|
Post-Delete |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
ASSIGNED |
NULL |
USER
DEFINABLE |
|
Pre-Clear |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
NULL |
NULL |
USER
DEFINABLE |
|
Post-Clear |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
NULL |
NULL |
USER
DEFINABLE |
|
Pre-Read |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
ASSIGNED |
NULL |
USER
DEFINABLE |
|
Post-Read |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
ASSIGNED |
ASSIGNED |
USER
DEFINABLE |
|
Post-Open |
ASSIGNED* |
ASSIGNED |
ASSIGNED |
NOT USED |
NULL |
NULL |
USER
DEFINABLE |
* Note that filevar is not the name of the file, but rather
the system-level file unit. It can be treated as such for file
operations within the subroutine, but cannot be treated as a typical
variable, e.g., it cannot be used with a PRINT or CRT statement.
TRIGGERS
|
