Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Chapter 5: Event-Driven Programming

Back to Table of Contents


Introduction

Event-driven programming is used to develop applications for graphical user interface (GUI) platforms and networks. TSD Script's user interface facilities are primarily event-driven. To illustrate the concepts of an event-driven program, review the sequence of events in an interactive program designed to capture information from the user:

  1. Application creates a main window with a menu.
  2. Application waits for a user to make a menu selection.
  3. User selects a command from the menu (an event).
  4. Application responds to the user's request.
  5. Application waits.

Definition

In an event-driven program, an application is a collection of individual windows. Applications are built by assembling individual windows into collections of windows that talk to each other.

Each window has a routine associated with it called an event handler. As a user interacts with a window, its event handler processes the event generated by that interaction. The interaction between user and computer is dynamic. That is, events or processes occur immediately and concurrently, as needed.

Object-oriented influences

Event-driven programs are frequently built using object-based concepts:

Encapsulating objects encourages their reuse because objects do not need to be re-invented every time they are used.

Networking messages can be treated in the same way windows and event handlers are treated. That is, each network message and each network connection can be treated as an encapsulated object. See Chapter 11, Networking Concepts, for information about TSD Script's networking functions.

An event-driven application is constructed by assembling one or more window objects and allowing them to communicate by means of message passing. TSD Script has efficient facilities for creating encapsulated windows and for passing messages.

Event Handlers

Event handlers are used throughout TSD Script and Developer's Toolkit to support an event-driven environment. In an event-driven environment, an event (such as a keystroke or a mouse click) triggers the appropriate response by the application (opening a new dialog box or selecting an entry in a field). To process events, each application uses event handlers designed specifically for them. Event handlers are called by the system when it has an event to deliver to the application. A single object or window can have multiple event handlers.

Defining event handlers

You define an event handler in the routines section of a TSD Script program. To make an event handler activate, it must be associated with an event source such as a window, a dialog box, or a network service.

Event handler features

An Event routine contains the collection of TSD Script statements that makes up an event handler. Like procedures and functions, an event handler is a collection of TSD Script statements enclosed in an ACTIONS...END block. Like other TSD Script blocks, an event handler can also contain:

Special features of event handlers include:

$Handle

Handles are contained in the $Handle parameter and passed to the event window.

$Handle is an implicit parameter that is passed to every event handler that uniquely identifies the window or network connection receiving the message.

Implicit Parameters

Receiving event parameters

Each time an event handler is notified of an event, it receives two important pieces of information:

The handle may be another window handle or a network handle, depending on the way that the event handler is declared.

Event-specific information

In addition to $Handle and $Event, an event handler can receive additional information concerning a specific event.

For example, a $MsgSize event is accompanied by two additional pieces of data:

These extra pieces of information can always be accessed through the $EventParm event. $EventParm takes two arguments:

Therefore, an expression like $EventParm(1,Integer) allows you to obtain the width of a new window during processing of a $MsgSize event

Shortcut functions exist for many of the event parameters of system-defined messages. Other implicit parameters exist for forms

Instance Data

When you work with event handlers, you also work with instance data. This is data that is associated with a particular window or network connection. As shown in the sample application at the end of this chapter, instance data is usually a record. The instance data is owned by the window and exists exactly as long as the window is open.

The contents of the instance data can be initialized in the call to create the window, WinCreate. For example:

WinCreate($Desktop,context.mainWindow,
          MainEvent {context}, 
          1,1,100,30,'Main Window Title', 
          BitOr($WinBorder,$WinResize,
                $WinTitle,$WinSysMenu, 
                $WinMinMax,$WinIconBar,$WinTaskList)); 

Event handlers and instance data

When it processes a statement like the one in the last section, TSD Script looks at the declaration for the indicated event handler, MainEvent. It sees that MainEvent takes as its formal argument a record of type ContextRecord. This tells TSD Script to reserve enough room for a ContextRecord in the new window's instance data.

TSD Script then looks to the right of the event handler name in the WinCreate statement. There, it sees an initialization form - {context}. This initialization form causes the contents of the context record variable to be copied into the window's instance data.

Note: Variables that appear in this form must be of the same type as the formal argument for the event handler.

Each time an event handler is called, it receives a reference to the window instance data. In this way, the event handler can inspect the current contents of the instance data and make changes to it. A similar initialization process is available for other non-windows interface objects that use event handlers (for instance, network connections).

The combination of the window instance data and the event handler make TSD Script windows and network connections behave like encapsulated objects. The practical implications of this are that:

Note: Avoid using global variables in a TSD Script program. Instead, use window instance data and message passing to disseminate information throughout the program.

Maintaining current items

Suppose that you want to maintain a current item. There are at least three ways you can achieve this:

SendMessage(mainWindow,QUERY_CURRENT_ID,current_ID); 

QUERY_CURRENT_ID would need to be a global constant such as:

CONSTANTS 
  QUERY_CURRENT_ID IS $MsgUser+1;

and the main window would need to be able to handle this message as shown below:

EVENT MainEvent(REF context: ContextRecord) IS 
    VARIABLES 
      iconList: List of String; 
    ACTIONS 
      WHEN $Event IS $MsgCreate THEN 
        iconList:={'ADDINV.ICO','SRCHINV.ICO',
                   'REPORTS.ICO'): LIST OF STRING; 
        WinSetIconBar($Handle,iconList); 
      ELSWHEN $MsgSelect THEN 
        WHEN $EventParm(1,Integer) IS 1 THEN 
          CreateAddWindow; 
        ELSWHEN 2 THEN 
          CreateSearchWindow; 
        ELSWHEN 3 THEN 
          CreateReportWindow; 
        END; 
      ELSWHEN QUERY_CURRENT_ID THEN 
        $EventParm(1,String):=context.current_ID; 
      END; 
    END (* Main Event *); 

In this example, MainEvent has been enhanced to add a check for the QUERY_CURRENT_ID event. When it detects such an event, MainEvent copies the value of the current_ID field from the main window's instance data into the string variable passed as the third argument to SendMessage by the caller, which is actually the first event parameter. After the caller ends its SendMessage command, the third argument contains the value assigned to it by MainEvent.


Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Back to Table of Contents

Copyright