TRIGGER API

Man Page Index

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.

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.

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.

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.

EXAMPLE

TRIGGERS