PC SOFT

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Home | Sign in | English US
  • What is a trigger?
  • Definition
  • Available types of triggers
  • Handling the triggers by programming
  • The WLanguage functions
  • Creating a trigger
  • Creating a procedure run by a trigger
  • Automatic tests and triggers
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadApple WatchUniversal Windows 10 AppWindows Mobile
Others
Stored procedures
What is a trigger?

Definition

A trigger is a WLanguage procedure automatically called by the HFSQL engine whenever a modification is performed (addition, deletion, modification, ...) on a record of a data file.
A trigger is used to associate a WLanguage process with one or more HFSQL functions (HAdd, HModify, HDelete, ...) without having to worry about the location of these functions in the source code. The triggers associated with the HFSQL functions used are run even if it is a window or a code created by a wizard.
Note: The triggers also operate with the functions for managing the browsing Table controls: TableAdd, TableAddLine, TableModify, TableModifyLine, TableDelete, ...
Using a trigger allows you to:
  • Reduce the code size. For example, using a trigger allows you to group the processes associated with one or more HFSQL functions (check for duplicates, consistency of data, ...).
  • Make the code easier to read.
  • Simplify the future evolutions of the application.
The triggers can be applied to all types of data files:
  • HFSQL
  • Native accesses (Oracle, AS/400, ...)
  • ODBC
  • OLE DB
Notes:
  • With a HFSQL Client/Server database, you also have the ability to define server triggers. See Server triggers for more details.
  • When modifying data files via a query, only the server triggers can be triggered. The simple triggers or the client triggers are not activated.
Versions 17 and later
iPhone/iPad This feature is now available for the iPhone/iPad applications.
New in version 17
iPhone/iPad This feature is now available for the iPhone/iPad applications.
iPhone/iPad This feature is now available for the iPhone/iPad applications.
Note: From version 19, HFSQL is the new name of HyperFileSQL.
Available types of triggers
Two types of triggers are available:
  • The "BEFORE" triggers:
    A "BEFORE" trigger is called:
    • before running a HFSQL function (HAdd, HModify, HDelete, ...).
    • before running a function for managing the browsing Table controls.
      A "BEFORE" trigger can be used for example to check the consistency of data for the items of a record. With this type of trigger, a HFSQL variable can be initialized in order to cancel the execution of the associated HFSQL function.
  • The "AFTER" triggers:
    An "AFTER" trigger is called:
    • after running a HFSQL function (except if the program was interrupted during the execution of this function).
    • after running a function for managing the browsing Table controls.
      An "AFTER" trigger can be used to manage the process of errors for example.
Handling the triggers by programming

The WLanguage functions

Several WLanguage functions are used to handle the triggers:
Versions 09 and later
HActivateTrigger
New in version 09
HActivateTrigger
HActivateTrigger
Re-enables a trigger that was disabled by HDeactivateTrigger.
Versions 09 and later
HDeactivateTrigger
New in version 09
HDeactivateTrigger
HDeactivateTrigger
Disables a trigger.
Versions 09 and later
HDeleteTrigger
New in version 09
HDeleteTrigger
HDeleteTrigger
Destroys a trigger.
Versions 09 and later
HDescribeTrigger
New in version 09
HDescribeTrigger
HDescribeTrigger
Adds or modifies a trigger on a HFSQL data file.
Versions 09 and later
HListTrigger
New in version 09
HListTrigger
HListTrigger
Returns the list of triggers applied to one or more HFSQL data files.
Versions 09 and later
HSetTrigger
New in version 09
HSetTrigger
HSetTrigger
Enables or disables the management of triggers.

Creating a trigger

To create a "BEFORE" trigger or an "AFTER" trigger, use HDescribeTrigger in the initialization process of the project. The trigger can be created:
The associated WLanguage procedure is run whenever a trigger is run.
Note: A trigger is global to the project.

Creating a procedure run by a trigger

A trigger procedure accepts no parameter. However, some HFSQL state variables are positioned before each call:
H.FileNameCharacter string: Logical name of the file whose trigger is enabled.
H.ActionCharacter initialized to "A" for a Before trigger and to "P" for an After trigger.
H.TriggerFunctionCharacter string: Name of HFSQL function that activated the trigger.
H.ToDoDuring the execution of a before trigger:
  • cancel the execution of the HFSQL function by assigning "A" to the HFSQL state variable: H.ToDo = "A".
    In this case, the action is not performed and the function (HAdd, HModify, ...) returns True (no error).
  • cancel the execution of the current HFSQL function by assigning "E" to the HFSQL state variable: H.ToDo = "E".
    In this case, the action is not performed and the function (HAdd, HModify, ...) returns False. The error message is as follows: "The action on XXX file was interrupted by the trigger".
Note: When a "BEFORE" trigger and an "AFTER" trigger are associated with a HFSQL function, if the "BEFORE" trigger cancels the execution of the HFSQL function (by positioning H.ToDo to "A"), the "AFTER" trigger is not run.
In the procedure code, the MyFile keyword is used to find out and handle the name of the file on which the trigger was activated. For an "AFTER" trigger, if the HFSQL command was not run properly, the procedure associated with the trigger is not run.

Automatic tests and triggers

If the automatic tests activate triggers that use dialog boxes (YesNo, Confirm, ...), these dialog boxes must be disabled when the test is run by InAutomaticTestMode.
Related Examples:
WD Trigger Training (WINDEV): WD Trigger
[ + ] This example explains how to use the triggers with WINDEV.
A trigger is a WLanguage procedure automatically called by the HFSQL engine whenever a HFSQL function is run.

The following topics are presented in this example:
1/ how to branch a trigger on a HFSQL function
2/ the code that must be used in the function called by trigger.

Summary of the example supplied with WINDEV:
This application is used to enter the expenses for the contributors of a company.
Two modes can be used:
- the mode with read/write rights
- the mode with read-only rights.
The triggers will be used to control the access to the files according to the current mode.
In this example, the triggers are also used to write the different events into a log file.
This log file can be directly consulted in the application.
Minimum required version
  • Version 12
This page is also available for…
Comments
Click [Add] to post a comment