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

On the Database Event page that is described here, you define what the DB Event object should check. On its Event Process Page, you define the actions that it will trigger if the conditions are met.

To define DB Event objects, do the following:

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.