MVsharp Triggers
Details and examples of using Triggers on MVsharp files.
Contents
Introduction
Triggers in MVsharp allow you to define programs that can be called whenever database IO takes place. These triggers can be used to audit database changes, update or delete records in other files or process the data before or after the IO takes place.
The MVsharp trigger implementation has a simple interface of a subroutine without any arguments. The subroutine must be catalogued locally in the account where the file is accessed. The type of IO being passed to the subroutine is defined with @Variables in your session.
There are 2 types of triggers that can be defined on a file.
- BEFORE triggers occur before an IO operation takes place.
- AFTER triggers occur after an IO operation has taken place.
A file can have both a BEFORE and an AFTER trigger defined for the file.
All file types available in MVsharp can have triggers associated with them. This includes Directory, Hashed, SQL Server, MongoDb, Universe, Unidata and D3.
Pre Requisites
Before using the MVsharp Triggers, the following needs to be in place:
- MVsharp# version 3.0.3.0 or above.
Managing Triggers
Creating Triggers
Triggers are added to a file by using the CREATE.TRIGGER command:
CREATE.TRIGGER subroutinename ON filename BEFORE [READ WRITE DELETE OPEN CLOSE CLEAR]
Creates a trigger to be fired BEFORE the IO takes place.
If a trigger routine already exists for that file for BEFORE IO, the trigger is not updated. The READ, WRITE or DELETE parameters are optional but at least one parameter must be specified.
CREATE.TRIGGER subroutinename ON filename AFTER [READ WRITE DELETE OPEN CLOSE CLEAR]
Creates a trigger to be fired AFTER the IO takes place.
If a trigger routine already exists for that file for AFTER IO, the trigger is not updated. The READ, WRITE or DELETE parameters are optional but at least one parameter must be specified.
Both a BEFORE and AFTER trigger can specified for the same file.
To change the READ, WRITE or DELETE flags for an existing trigger, the trigger must first be deleted and the re-created.
Once the trigger has been created, any subsequent access to the file will cause the trigger to be called.
The trigger program should never cause the same IO operation to take place on the same file. This will cause recursive calls to the trigger program and it will be in an infinite loop.
Deleting Triggers
Triggers can be removed from a file by using the DELETE.TRIGGER statement.
DELETE.TRIGGER filename BEFORE - Deletes the BEFORE IO trigger from the file.
DELETE.TRIGGER filename AFTER - Deletes the AFTER IO trigger from the file.
All processes that have the file open will continue to call the trigger until the file is closed and re-opened.
The DELETE.TRIGGER statement does not delete the subroutine, it removes the trigger pointers from the VOC file pointer record.
Listing Triggers
To see what triggers are active on a file, the LIST.TRIGGER statement can be used.
LIST.TRIGGER filename
The output from the LIST.TRIGGER statement is:
BEFORE TRIGGER {subroutine name} FOR [READ WRITE DELETE OPEN CLOSE CLEAR]
AFTER TRIGGER {subroutinename} FOR [READ WRITE DELETE OPEN CLOSE CLEAR]
Writing Trigger Subroutines
The trigger subroutines are not passed any arguments but are controlled by the @Variables in your session. The following @Variables are present when a trigger is called:
| Variable | Description |
|---|---|
| @Id | Contains the key to the record for the current IO operation. |
| @Record | Contains the record for the current IO operations. |
| @FileName | The name of the file that the IO operation is taking place on. |
| @File | The opened file variable of the file that the IO operation is taking place on. |
| @Action | The type of operation taking place: 1. Before a read operation. 2. Before a write operation. 3. Before a delete operation. 4. After a read operation. 5. After a write operation. 6. After a delete operation. 7. Before an open operation. 8. After an open operation. 9. Before a close operation. 10. After a close operation. 11. Before a clearfile operation. 12. After a clearfile operation. |
| @OldRecord | The original record that was read before trigger is called. |
Example Triggers
Assume we want to keep a copy of any changes made to our BP program file in an audit file called BP.AUDIT
PROGRAM AUDIT
*-----
* Program to demonstrate the Trigger Functionality of MVsharp
* Attribute 10 of a file pointer may contain a routine to call Before and the trigger actions to take place
* Attribute 11 of a file pointer may contain a routine to call After and the trigger actions to take place
* e.g.
* >ct VOC BP
* BP
* 0001 File
* 0002 BP
* 0003 D_BP
* 0004 Directory
* 0005
* 0006
* 0007
* 0008
* 0009
* 0010 BEFORETRIGGER,RWD
* 0010 AFTERTRIGGER,RWD
*
* @Action variable contains the following values:
* 1 - Before Read
* 2 - Before Write
* 3 - Before Delete
* 4 - After Read
* 5 - After Write
* 6 - After Delete
*
* @FileName contains the name of the file
* @File contains the file variable for the file
* @Id contains the key to the record
* @Record contains the record
*
*-----
Begin Case
Case @FileName = "BP" ;* @FileName contains the name of the file
Begin Case
Case @Action = 1 ;* Read operation taken place
* no action
Case @Action = 2 ;* Write operation taken place
FileVariable = @File
CheckRec = @OldRecord ;* the original record that was read before updating
If CheckRec # @Record Then ;* keep a copy of the original record
Open "BP.AUDIT" To AuditFile Then
Key = @Id:"!":Oconv(@Date,"D2-"):"!":Change(Oconv(@Time,"MTHS"),":","")
CheckRec<-1> = "* Modified : ":@Who
Write CheckRec on AuditFile , Key
End
End
Case @Action = 3 ;* Delete operation taken place
Read CheckRec From FileVariable , @Id Then
Open "BP.AUDIT" To AuditFile Then
Key = @Id:"!":Oconv(@Date,"D2-"):"!":Change(Oconv(@Time,"MTHS"),":","")
CheckRec<-1> = "* Deleted : ":@Who
Write CheckRec on AuditFile , Key
End
End
End Case
End Case
End
*TEST
Once the program has been compiled and catalogued, the following CREATE.TRIGGER statement will activate the trigger on the out BP file.
CREATE.TRIGGER AUDIT ON BP BEFORE WRITE
Copyright © 2018 Prosol Group
All rights reserved.
Prosol Group make no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Prosol Group or an authorised sub licensor.
Neither Prosol Group nor its employees are responsible for any errors that may appear in this publication. The information in this publication is subject to change without notice.
All other trademarks and service marks are property of their respective holders.