Step 3 - Defining a trigger to insert data in a database table

This section describes the steps to define and start a trigger that that uses the Transaction action to insert data into a database server table.

You can define a trigger (your application logic) to execute at a known time of day or at a periodic frequency. This type of trigger is a schedule event type trigger.

It is assumed that the Workbench is started and you have logged on.

Example project

This section describes the steps to define a project, which will be where the trigger is defined.

A project is a container item that is used to organize and control triggers.

Follow these steps to create a project.

1. From the Workbench left pane, expand the node where you want to define the project.
   
2. On the Projects icon, right-click to display its pop-up menu.
   
   
3. Select New.
   The Create Project window appears.
   
   
   
4. Enter AcmeProducts_900 as the name for the project, and then select OK.
   A project name can be up to 32 characters in length and can include letters, numbers, and the underscore character. Spaces are allowed.
   The name and new icon is added under the Projects icon (on the Workbench left pane).
   
   

You are now ready to create the trigger.

Example schedule trigger

To define a schedule trigger, follow these steps:

1. From the Workbench left pane, expand the node where you want to define the trigger.
   
2. Select the Projects icon, and then from the right hand pane Projects tab, double click our example project AcmeProducts_900
   The AcmeProducts_900 tab appears as the active tab for the right hand pane.
   
   For this example, the tab is empty. However, typically a project tab contains a list of triggers that belong to the project.
   
3. From the bottom of the project tab, select the New button.
   The Trigger window appears.
   
   
4. In the Name parameter, enter MyFirstTrigger as the name of the trigger. A trigger name can be up to 64 characters and include letters, numbers, and the underscore character. Spaces are allowed.
   
   
5. From the Trigger Event Type drop down-list, click Schedule.
   The Event tab becomes active with input parameters for the default Periodic time of day option.
   
   
6. From the Frequency drop-down list, accept Periodic as the time of day option you want to use. The Periodic option sets a trigger to execute continuously at specific millisecond intervals.
   
7. Under Occurrence, in the Period (milliseconds) parameter, enter a value of 5000. This will set the trigger to execute every 5000 milliseconds, or every 5 seconds.
   
8. Select the Settings tab.
   
   
9. In the Max in Progress box, accept the default value. The default indicates that the trigger must complete its processing before another instance of the trigger is allowed to be executed.
   
10. In the Max Exec Time (ms) parameter, enter a value in milliseconds for the maximum execution time for the trigger. If the trigger exceeds this value, a warning message is logged in the Exceptions Log (even though Reporting might be set to Off). for this example, enter 10000 (10 seconds).
    
11. Leave the Queue Size parameter empty.
    
12. From the Reporting drop-down list accept the default value of Off. A value of off indicates that a trigger report, with the details of the trigger and its actions at execution time, is not generated or written to the Reports Log.
    
13. The Editor mode drop-down list provides the way you create and edit actions for the trigger:
    
    List lets you manually select an action from a list. For each possible output of an action, you select a route.
    Canvas lets you drag and then drop an action on a drawing area. For each possible output of an action, you draw connectors between actions by dragging the mouse.
    User preference remembers the option you used when editing the trigger.
    For this example, List mode was selected and is used for the remaining steps.

Adding the Transaction action

The next step is to select an action for the trigger. This will be a Transaction action that references the transport map that you created in Step 2 - Defining the database insert transport map (MyFirstTransportMap).

1. From the bottom of the New Trigger window, under the Actions pane, select Add.
   
   The New Action window appears.
   
   
2. Expand Enterprise Communication, select Transaction, and then select Add.
   The right pane changes to accommodate the Transaction action.
   
   
3. Use the Transport Map drop-down list to select MyFirstTransportMap.
   The Input tab becomes populated with the names of the map variables from MyFirstTransportMap.
   
4. Notice the names log1, log2, and so forth. These are the map variables you defined when the transport map was defined.

For this example, the next step is to associate device variables with the logical names listed in the table.

Associating device variables with map variables

Follow these steps to associate the device variables to the logical names listed.

1. From the Input tab, select the right side of the Value column for the log1 variable.
   
   A list of device variables, macros, constants, trigger variables and event variables appears.
   
   For this example, a device named Local CPU 1 and its device variables are used.
   You will associate a device variable with the log1 variable in the row.
   
2. Expand Local CPU 1, and then the expand the D to display a list of data registers for that device.
   
   
3. Under D, expand [ 0 - 999 ], and then select [8] as the D data register for the log1 variable.
   
   The log1 variable will be assigned the PLC's device variable's data value at runtime.
   Note that the data will be treated as an INT2 when it is read from the PLC and also as an INT2 when it is delivered to its destination.
   
4. Repeat steps 1 through 4 for log2, log3, and log4, applying the appropriate numeric values for the String.
   The Input tab will be similar to the following:
   
   For the log5 variable, you will assign $$EVENT_TIME which is a trigger macro. The macro will provide the time that the trigger started execution.
   
5. From the Input tab, select the right side of the Value column for the log5 variable.
   A list of variables appears.
   
   
6. Expand Macros, and then select the $EVENT_TIME.
   The completed Input tab on the Transaction action will look similar to this:
   
   Each time the trigger executes, the deice variable and trigger variable data is inserted into the Table01C table.

   PLC device variable	Database table column
   Local CPU 1.D [8]	C01
   Local CPU 1.D [9]	C02
   Local CPU 1.D [14]	C03
   Local CPU 1.D [19]	C04
   $EVENT_TIME	C05

   
   The trigger action also has an Output tab that will contain the resultStatus and resultCount output variables.
   
   When the trigger executes, the resultStatus variable will contain a code indicating whether or not the transaction completed successfully. A zero indicates success. A non zero value translates to the error code returned either by the Transaction Server or by the database vendor. The resultCount is a value returned that indicates the number of rows affected in the database.
   
7. Select the Routing tab.
   
   On Result parameters:
   Success - This is the action to take upon a successful completion of the action.
   Failure - This is the action to take upon a failure completion of the action.
   Store and Forward - This is the action to perform if the result of the Transaction action was the writing of the transaction data to a store and forward queue. The transport associated with the Transaction action's transport map, must have store and forward capabilities and that capability must be enabled.
   When using the Canvas Editor, the Transaction action will have an output port (route) for the Store and Forward result.
   For this example, leave Success and Store and Forward set to Next, and set Failure to ENDERR.
   
8. The trigger is completed, click Validate.
   
9. A message will tell you that the trigger definition was validated. Select OK.
   
10. Click Save.
    The new trigger will be added to node and displayed on the project's tab..
    
    The project tab provides a table format with columns that provide status such as the number of triggers that have successfully completed execution. Typically, you will use the values in the project tab during run time. The project tab also provides a pop-up menu that you can use to start and stop a trigger.
    
    Using the pop-up menu allows you to perform many tasks including creating a new trigger, editing or deleting an existing trigger, and generating a trigger report.

The next step is to start the project and trigger. Go to Step 4 - Starting the trigger to insert data.