Database (DB) Events

As a developer and object designer you define Database Events to monitor and compare two values in the database. If the conditions you define on the Event page are met, the Database Event triggers the actions you coded on its Event Process page. These actions are usually the execution of further objects. Database Events are in Sleeping status as long as the frequency and time conditions are not met and change to Checking when they are.

You can use the following functions of the Automation Engine scripting language to retrieve relevant data for the Event object:

• GET_CONSOLE, GET_EVENT_INFO
• GET_WIN_EVENT

Defining DB Event Objects

Follow these steps:

1. In Database Event define the values to be compared and the operator that compares them.

   Three sources can provide the values:

   • SQL Query

     You can use Object variables within an SQL query. The database event does not abort if the query is incorrect.

     1. In SQL click the file icon to open the Cell Editor, where you can enter the SQL query.

        Click OK.

     2. In Agent do one of the following:

        • Select an entry from the list.
        • Click the folder icon to open the Select Agent dialog and search for the one you need.

        • Either type the name of the Agent or enter a variable that retrieves it name and select the appropriate Agent Type.

          Use this option if the Agent is not assigned to the current Client but to Client 0 and is therefore not listed here.

        For the first two options, the Agent Type is automatically selected and cannot be edited.

        Depending on the Agent you have selected, the rest of the fields in this section vary.

        Maximum length: 4096 characters.

        It is not possible to select Agent Groups in database events.

     3. In Login select the object that contains the credential that the Event needs to log on to the database.

     4. In Server:Port enter the name of the computer on which the database is available, for example PC01:2281.

        The default ports are:

        • MS SQL Server: 1433
        • Oracle: 1521
        • DB2: 50000
        • MySQL: 3306

        Do not complete this field if the query should be made in an Oracle database in RAC. For more information, see Connection to Oracle Databases.

     5. In Database enter the name of the database.
     6. In MS Access Filename enter the path and file name of the MS Access database.

   • Static Value

     Maximum length: 40 characters.

   • Variable

     1. In Variable Object select the name of the Variable object that contains the string to compare.
     2. In Variable key select the entry in the Variable object to be used for the comparison.

     The database event is not activated if the key does not exist in the specified Variable object.

     If the key does not include a value, the result depends on the setting that has been defined on the Attributes Page of the Variable object. The system either logs an error message or uses the initial values. The database event does not abort.

     For more information, see GET_CONSOLE, GET_EVENT_INFO.

2. Select the Operator to use in the comparison.

   You can combine values as necessary. Values are interpreted and compared as string values; if both values can be interpreted as positive integers (>=0), they will be compared as integer values.

   For example:

   5 >  1: Values are interpreted as positive integers -> int 5 > int 1 -> true

   1 > -1: Values are interpreted as strings -> string "1" > string "-1" -> false

   Fractional digits are truncated. To prepare them for comparison first read the values on the Event Process page using the GET_CONSOLE, GET_EVENT_INFO script function and then multiply them with 10n in order to move the commas.

   For example:

   4 * 100 (corresponds to 102) = 12344

   123.5555 * 10000 (corresponds to 104) = 12355555

   Time stamps of SQL queries and Variable objects are converted to "YYYY-MM-DD HH:MM:SS".

3. Define the Time Parameters.

   • Frequency

     How often the Event object will be activated.

   • Check Frequency

     When the Event object will be activated.

   • First Check

     When the intervals should begin.

     • Immediately

       The Event object becomes active for the first time upon its activation, regardless of the specified time interval.

     • After the first interval

       The Event object becomes active for the first time after the expiration of the first time interval.

   • If start time is later

     • Activate immediately

       If the Event object starts after the specified time, it becomes active immediately.

     • Wait for the next valid date

       If the Event object starts after the specified time, it becomes active with the next valid date considering the calendar and time conditions you specify below.

4. Define the Time and Date Conditions.

   These conditions are always checked. An event will only be triggered in one of the following cases:

   • At least one of the conditions is met.
   • No condition has been defined here.

   The Time Zone assigned to the event is considered as well. This means that activating an event and specifying a logical time does not make sense.

   See Tables On Pages.

5. Switch to the Event Process Page to define the actions that the Event will trigger.

   A database event process cannot contain JCL lines.

Activating/Executing and Monitoring the DB Event

Execute the Event object to activate it

The execution of an Event object triggers the execution of other objects, which in turn trigger the execution of further tasks. The tasks resulting from these executions are displayed in the Process Monitoring perspective on the various lists of Executions related to the Event object. They are children of the Event task and are flagged with a special tag type called !EVNT. The tag lets you check which executions were triggered by a specific Event. For more information, see Monitoring Events and Execution Data.

Execute Event objects in the following ways:

• Include Event objects in Schedules (JSCH) to execute them automatically at predefined times and/or intervals.

• Insert Event objects in Workflows (see Workflows (JOBP)).

• Manually execute, restart or stop Event objects. For more information, see Executing Events.

To check the number of times the system checked the Event, go to the Check count section in the Details of the object. For more information, see Viewing Object and Task Details.

Note: If a Time Event is activated outside the Time and Date Conditions, it will be activated immediately after the first time interval has passed.

Monitor the Event

Immediately after executing the object, you can start monitoring the Event. Right-click the object and select Monitoring, Show in Process Monitoring and open the pre-filtered list of tasks to display the task. Follow the progress of the task and access reports and statistical information in the Process Monitoring perspective.

You can stop active Events in the following ways:

• cancel the Event
  Status: Abend/manually canceled
• Quit the Event
  Status: Ended_OK
• Suspend the Event
  Event remains active, but temporarily disabled

For more information, see Working with Tasks, particularly Stopping and Interrupting.