jBASE Triggers

jBC subroutine defines the action that takes place when a database trigger event occurs. This section shows the subroutine that gets triggered for each of the nine database trigger events.

The name of the subroutine is specified in the create-trigger command. It is convenient to use one subroutine for each file that has a trigger defined. It allows distinguishing the different events in the subroutine.

The subroutine can used to define ancillary updates that need to occur because of the primary update. The seven parameters passed to the subroutine allow interrogation and (where applicable) manipulation of the record being updated.

Subroutine Parameters

This section describes the various parameters available in the jBC subroutine.

Closedfilevar

The file variable associated with the update. For example,

WRITE var ON filevar,"newkey"

However, you must be very careful of calling this subroutine recursively.

ClosedEvent

One of the TRIGGER_TYPE_xxx values to show which of the 9 events is currently about to take place. The TRIGGER_TYPE_xxx values are defined in $JBCRELEASEDIR/include/JBC.h (UNIX) and %JBCRELEASEDIR%\include\JBC.h (Windows).

Type Event

TRIGGER_TYPE_PREWRITE -

Before a WRITE occurred.

TRIGGER_TYPE_POSTWRITE -

After a WRITE occurred.

TRIGGER_TYPE_PREDELETE -

Before a DELETE occurred.

TRIGGER_TYPE_POSTDELETE -

After a DELETE occurred.

TRIGGER_TYPE_PRECLEAR -

Before a CLEARFILE occurred.

TRIGGER_TYPE_POSTCLEAR -

After a CLEARFILE occurred.

TRIGGER_TYPE_PREREAD -

Before a READ occurred.

TRIGGER_TYPE_POSTREAD -

After a READ occurred.

TRIGGER_TYPE_POSTOPEN -

After an OPEN occurred.
Closedprerc

The current return code (status) of the action.

For all the TRIGGER_TYPE_PRExx events, it is 0.

For all the TRIGGER_TYPE_POSTxx events, it shows 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, then it is because the lock table is full, the value in prerc in this case is 1.

Closedflags

Flags to show whether a WRITE or WRITEV was requested.

ClosedRecordKey

The record key (or item-id) of the WRITE or DELETE being performed. For CLEARFILE, this is set to null.

ClosedRecord

For the WRITE actions, this is the record currently being updated. For the DELETE or CLEARFILE actions, this is set to null. This variable can be modified within the subroutine if required. However, the modification will be discarded unless the create-trigger command was executed with the -a option.

Closeduserrc

This variable can be set to a non-zero value for the TRIGGER_TYPE_PRExxx actions in order to abort the current action. Ensure to use the -t option with the create-trigger command.

There are two options to set this value:

  • Any negative value causes the action to be terminated. However, nothing will be flagged to the application.

  • 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 13 (which is the UNIX error number for "Permission denied"), then the application will fall into the jBASE debugger with error code 13.

NOTE: Processing carried out inside a trigger should be as economic as possible. They are not designed to allow copious application logic. Any files opened inside a trigger should be opened once and the file descriptor stored in named common such that files are not opened in every iteration. Care should be taken that logic inside a trigger should not result in overhead or in an infinite loop of trigger calls.

Assigning 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 (pre, post-delete and pre-read). This is for the read event because there is no need to read a record before reading a record, and in 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 should be performed at a higher level.

Trigger Type filevar* event prerc flags recordkey record userrc

Pre-Write

YES

YES

YES

N/A

YES

YES

UD

Post-Write

YES*

YES

YES

N/A

YES

YES

UD

Pre-Delete

YES*

YES

YES

N/A

YES

NULL

UD

Post-Delete

YES*

YES

YES

N/A

YES

NULL

UD

Pre-Clear

YES*

YES

YES

N/A

NULL

NULL

UD

Post-Clear

YES*

YES

YES

N/A

NULL

NULL

UD

Pre-Read

YES*

YES

YES

N/A

YES

NULL

UD

Post-Read

YES*

YES

YES

N/A

YES

YES

UD

Post-Open

YES*

YES

YES

N/A

NULL

NULL

UD

YES means that the variable is assigned in this trigger, UD means that it is user definable, N/A means that the variable is not used and Null means that the variable is assigned a null value.

NOTE: filevar is not the name of the file, but rather the system-level file unit (the 'OPEN' file descriptor). It can be treated as such for file operations within the subroutine, but cannot be treated as a typical variable. For example, it cannot be used with a PRINT or CRT statement.

Creating Trigger

The CREATE-TRIGGER command specifies the database events for which the trigger subroutine is called. The command syntax is:

CREATE-TRIGGER -Options FileName {triggername|*} subroutine

Syntax Elements

  • FileName can reference either a jBASE hashed file or a directory.

  • triggername must be * or one of the nine database events (POSTOPEN, PREREAD, POSTREAD, PREWRITE, POSTWRITE, PREDELETE, POSTDELETE, PRECLEAR, POSTCLEAR). If * is specified, then the trigger subroutine will be called for each of the nine database events.

  • subroutine is the name of a jBC subroutine.

  • Below are the valid options:

    • Option Description

    -a or (A)

    Amend flag subroutine. Amends the record.

    -d or (D)

    Debug flag subroutine. Debugs the record.

    -t or (T)

    Terminate flag subroutine. Terminates update.

    -o or (O)

    Overwrite flag subroutine. Overwrites any existing definitions.

The CREATE-TRIGGER command can be run multiple times for the same file. If a trigger has already been defined for the specified event, then the overwrite flag must be used to effect the change.

Examples 

CREATE-TRIGGER BP POSTOPEN SUBBPOPEN

Immediately calls the SUBBPOPEN subroutine after any jBASE process successfully opens the BP file.

CREATE-TRIGGER -o PAYROLL * SUBBP

Calls the SUBBP subroutine for every database event to the PAYROLL file. Overwrites the existing trigger definitions.


Bookmark Name Actions
BACK

In this topic

Feedback
x

Are you sure you want to log-off?