Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Language Reference

Event Handling

Return to Main Page


$Event

Description

This variable is an implicit parameter that contains an event number to an event handler (for instance, a message number such as $MsgPaint, etc.) for the current invocation of the handler.

Syntax

Not applicable.

Notes

In a windowed TSD TSD Script application, events represent the primary force of the application. These events come from a variety of sources, including the following:

Events are delivered by TSD TSD Script to event handlers. Various TSD TSD Script routines (such as those that create windows or dialogs) allow you to specify a routine to intercept and react to events.

An event handler accesses the built-in $Event parameter. $Event contains either one of the predefined message constants or a message constant defined by the TSD TSD Script programmer. Each message constant indicates the type of event being delivered.

See Also

For more information on events, see the Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Programming Guide.


$EventParm

Description

Allows an event handler to access extra parameters included with a message.

Syntax

FUNCTION $EventParm(n: INTEGER, type: DATATYPE): DATATYPE;

Argument Notes

Argument Name Description
n This argument identifies the event parameter. Event parameters are numbered beginning with 1.
Type This is a data type, either predefined or user-defined, that corresponds to the data type of the referenced parameter. If the data type specified here does not match that of the parameter passed by the sender of the message, a run-time error message is displayed.

Notes

TSD Script event handlers always receive three fixed parameters. The first is a copy of the window instance record. This parameter is explicitly reflected in the event handler declaration. The next two are implicit parameters, $Event and $Handle, which identifies the event to be processed and the window that causes the event, respectively.

An event handler can receive a variable number of additional parameters. Certain system events (such as $MsgSize) are accompanied by additional pieces of information that are passed as additional parameters.

User-defined messages sent by the SendMessage statement can pass additional parameters. The sender and receiver must agree upon the number, types, and meanings of these parameters. An event handler accesses these event parameters via $EventParm.

$EventParm takes two arguments: an integer that identifies which extra parameter is to be retrieved and a valid data type that matches the data type of the parameter sent. Although a variable number of extra parameters can be sent to an event handler, the number and types of parameters must be implied by the event number itself.

For example, a user-defined event might be set up so that any window could ask any other window for its name. Assume that a name field exists in the instance data for every window and is passed in through the initialization data. A user-defined message could be set up by defining a global constant as in:

CONSTANTS
 QUERY_WINDOW_NAME IS $MsgUser+1;

Thereafter, given a window handle, you could obtain the name of that window in the following way:

VARIABLES
window_name: String;
ACTIONS
SendMessage(some_window,QUERY_WINDOW_NAME,window_name);

Each window would have to have the following event handler:

ACTIONS
WHEN $Event IS ...
 ...
ELSWHEN QUERY_WINDOW_NAME THEN
 $EventParm (1,String):=myData.myName;
ELSWHEN ...

Example

EVENT MyEvent(REF r: MyRecord);
VARIABLES
width, height: INTEGER;
ACTIONS
WHEN $Event IS $MsgSize THEN
 width:=$EventParm(1,Integer);
 height:=$EventParm(2,Integer);
 ...

See Also

For more information on events, see the Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Programming Guide.


$Handle

Description

Implicit parameter passed to every event handler that identifies the window receiving the message.

Caution: $Handle always contains the window handle of the window that receives the current event. $Handle only appears within an event handler.

Example

EVENT MyEvent(REF r: MyData);
ACTIONS
WHEN $Event IS $MsgCreate THEN
 WinSetIconBar($Handle,{'CREATE.ICO','DESTROY.ICO'}: LIST
 OF STRING);
...

$NullHandler

Description

Specifies no event processing for a statement that requires an event handler.

Syntax

EVENT $NullHandler{initializationData}: INTEGER;

Argument Notes

Argument Name Description
initilizationData This argument is optional. If present, it causes instance data of the same type as itself to be created. The instance data is initialized to the value of this argument.

Notes

The syntax used for $NullHandler is the same syntax that is used for all dollar values used with event handlers.

Example

KNOWLEDGEBASE Desktop;

ROUTINES
 PROCEDURE Example;

PRIVATE
ROUTINES

 (* Create a scroll window parented by the desktop with
 default event processing *)
 PROCEDURE Example IS
 VARIABLES
 whdl: WINDOW;

 ACTIONS
 WinCreateScrollWindow($Desktop, 
(* Window is a child of
 (*OS/2 desktop *)
 whdl, 
(* return handle of new
 window *)
 $NullHandler,
(* Default event
 processing *)
 5, 5, 80, 20,
(* Window location and
 size *)
 'Example', 
(* Window
 title *)
 '', 
(* Use default
 font *)
 0, 
(* Point size is
 ignored for default *)
 BitOr($WinTitle, $WinBorder,
       $WinSysMenu ));
 WinWait( whdl );
 END;

See Also


DelegateEvent

Description

Delegates the handling of an event from one event-handling routine to another.

Syntax

FUNCTION DelegateEvent ( VAL handler: EVENT,
 [ REF userData: ANY ] ): INTEGER;

Argument Notes

Argument Name Description
handler Name of an event-handling function.
userData Variable passed by reference to the specified event-handling function.

Caution: Calls to the DelegateEvent function must be in the scope of an event-handling routine.

Notes

Often several dialog boxes or other message-handling objects deal with the same types of data and respond to many of the same messages in the same way. The DelegateEvent function can be used to avoid repeating the same code in the message-handling routines for each such object.

DelegateEvent calls the specified event handling routine and passes all of the pseudo parameters from the enclosing handler (i.e., $Event, $Handle and all of the $EventParm parameters). If the specified handler takes an explicit parameter for user data and none is specified in the DelegateEvent call, the user data passed to the enclosing handler is passed by default.

Example

KNOWLEDGEBASE Test;

 ROUTINES
 PROCEDURE Main;

PRIVATE

 TYPES

 BaseData IS RECORD
 f1: INTEGER;
 f2: STRING;
 END;

 DerivedData IS RECORD
 base: BaseData;
 f3: REAL;
 END;

 CONSTANTS

 MSG_ONE IS $MsgUser + 1;
 MSG_TWO IS $MsgUser + 2;
 MSG_THREE IS $MsgUser + 3;

 ROUTINES

 EVENT BaseHandler (REF userData: BaseData) IS
 ACTIONS
 WHEN $Event IS MSG_ONE THEN
 userData.f1 := $EventParm(1, INTEGER);
 WinWriteLn($Handle,
 'f1 set to [' & userData.f1 &']');
 ELSWHEN MSG_TWO THEN
 userData.f2 := $EventParm(1, STRING);
 WinWriteLn($Handle,
 'f2 set to [' & userData.f2 & ']');
 END;
 END;

 EVENT DerivedHandler (REF userData: DerivedData) IS
 ACTIONS
 WHEN $Event IS MSG_THREE THEN
 userData.f3 := $EventParm(1, REAL);
 WinWriteLn($Handle,
 'f3 set to [' & userData.f3 & ']');
 ELSE
 $Result := DelegateEvent(BaseHandler, userData.base);
 END;
 END;

 PROCEDURE Main IS
 VARIABLES
 w: WINDOW;
 ACTIONS
 IF 0 > WinCreateScrollWindow($Desktop,
 w, DerivedHandler,
 10, 10, 80, 25, 'Test',
 $Courier, 8,
 $WinDefaultStyle)
 THEN
 EXIT;
 END;

 WinWriteLn(w, 'Ready to send MSG_ONE.');
 SendMessage(w, MSG_ONE, 37);

 WinWriteLn(w, 'Ready to send MSG_TWO.');
 SendMessage(w, MSG_TWO, 'I''m pink, therefore I''m
 Spam.');

 WinWriteLn(w, 'Ready to send MSG_THREE.');
 SendMessage(w, MSG_THREE, $Pi);

 WinWriteLn(w, 'Test complete.');
 SendMessage(w, $MsgClose);
 END;

END;

Return Codes

The integer value returned from DelegateEvent is the value returned by the called event handler. The semantics of the return value vary with the $Event message.

See Also


PostMessage

Description

Posts a message to a window event handler.

Syntax

PostMessage( VAL whdl: WINDOW, VAL message: INTEGER,
 [ VAL msgParm: ANY ... ] ): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of an event-processing object, such as a window.
message PostMessage posts a message to a window and immediately returns a success or error code without waiting for the message to be sent. The message is added to the target window's process message queue. It is dispatched to the destination window when the application enters an event handler.
Tivoli Service Desk Developer's Toolkit statements that include a message processing loop are:
  • DlgBox
  • WinFileDialog
  • WinMessageBox
  • WinWait
messageParameters Any. It is the responsibility of the poster and the postee to agree on the types, order, and number of message parameters to pass. All parameters are passed by value.

Example

KNOWLEDGEBASE PostMsg;
ROUTINES
 PROCEDURE PostMessageExample;

PRIVATE
CONSTANTS
 menuList IS { 'Options', 'Post message', 'Exit' }:
 LIST OF STRING;

ROUTINES
EVENT PostMessageEvent( REF whdlTarget: WINDOW ) IS

VARIABLES
 i: INTEGER;

ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinSetMenuBar( $Handle, menuList );
 ELSWHEN $MsgMenu THEN
 WHEN $MenuSelection IS 101 THEN
 FOR i := 1 TO 5 DO
 WinWriteLN( $Handle, 'Posting message #' & i );
 PostMessage( whdlTarget, $MsgUser + i );
 END;
 WinWriteLN( $Handle );
 WinWriteLN( $Handle, 'Wait in for 5 seconds' );
 WinWriteLN( $Handle );
 SysDelay( 5000 );
 ELSWHEN 102 THEN
 SendMessage( $Handle, $MsgClose );
 SendMessage( whdlTarget, $MsgClose );
 END;
 ELSE
 IF $Event = $MsgUser THEN
 WinWriteLN( $Handle, 'Received target window handle'
 );
 whdlTarget := $EventParm( 1, WINDOW );
 ELSIF $Event > $MsgUser THEN
 WinWriteLN( $Handle,
 'Received message #' &
 $Event - $MsgUser );
 END;
 END;
 NOTHING;
END;
 PROCEDURE PostMessageExample IS
 VARIABLES
 whdl1: WINDOW;
 whdl2: WINDOW;


ACTIONS
 WinCreateScrollWindow( $Desktop, whdl1,
 PostMessageEvent{whdl1 },
 0, 0, 40, 25,
 'Post message Window 1',
 $TimesRoman, 14,
 BitOr($WinBorder,
 $WinTitle, $WinMenu,
 $WinAutoPos ) );
 WinCreateScrollWindow( $Desktop, whdl2,
 PostMessageEvent{ whdl2 },
 0, 0, 40, 25,
 'Post message Window 1',
 $TimesRoman, 14,
 BitOr( $WinBorder,
 $WinTitle, $WinMenu,
 $WinVScroll, $WinAutoPos ) );
 PostMessage( whdl1, $MsgUser, whdl2 );
 PostMessage( whdl2, $MsgUser, whdl1 );
 WinWait( whdl1 );
END;

Return Codes

Return Code Description
>0 Success
0 The post of the message failed
-1 The window handle does not refer to a valid window. The window may no longer exist or the window may not support the command
-2 Unknown value
-9 Bad syntax
-11 Value out of range

See Also


SendMessage

Description

Sends a message to a window or dialog box.

Syntax

SendMessage( VAL whdl: WINDOW, VAL message: INTEGER,
 [ VAL or REF messageParm: ANY ... ] ): INTEGER;

Argument Notes

Argument Name Description
whdl The handle of an event-processing object such as a window.
Message The message to be sent.
messageParm A variable number of expressions of any type. These expressions are accessible to the receiving event handler via the $EventParm value.

Notes

TSD Script offers a robust message-passing architecture. The most common recipients of messages are event handlers associated with windows or dialog boxes.

SendMessage can initiate an event in an event handler given an object handle (for example, a window handle) that is serviced by that handler. The second argument to SendMessage maps onto the $Event parameter for the event handler. Subsequent arguments map onto the event parameters in the event handler.

The event handler accesses these arguments by calling $EventParm and supplies the argument number (1 through n) and the data type of the argument. If an assignable value (such as a variable) is passed by the sender, it is automatically passed by reference. Otherwise it is passed by value. SendMessage behaves like a function call because control does not return to the statement following the SendMessage call until the event handler has processed the message and returned.

The calling routine pauses until the event handler returns. The return value of the event handler is the value returned by SendMessage.

Example

GLOBALS.KB
----------
 CONSTANTS
 ADD_WINDOW_TO_LIST IS $MsgUser+1;
 REMOVE_WINDOW_FROM_LIST IS $MsgUser+2;
 VARIABLES
 mainWindow: WINDOW;

SENDER.KB
---------
USES
 Globals;
ROUTINES
 EVENT MyEvent(REF r: MyRecord);
 ACTIONS
 WHEN $Event IS $MsgCreate THEN
 SendMessage(mainWindow,ADD_WINDOW_TO_LIST,
 $Handle);
 ELSWHEN $MsgDestroy THEN
 SendMessage(mainWindow,
 REMOVE_WINDOW_FROM_LIST,$Handle);
 ...

MAIN.KB
-------
USES
 Globals;
TYPES
 MainRecord IS RECORD
 ...
 openList: LIST OF WINDOW;
 END;
ROUTINES
 EVENT MainEvent(REF r: MainRecord);
 ACTIONS
 WHEN $Event IS ...
 ...
 ELSWHEN ADD_WINDOW_TO_LIST THEN
 ListInsert(r.openList,$EventParm(1,Window));
 ELSWHEN REMOVE_WINDOW_FROM_LIST THEN
 ListDelete(r.openList,$EventParm(1,Window));

Return Codes

Return Code Description
Event handler return value The return value of the event handler is the value returned by SendMessage
-1 The window handle does not refer to a valid window. The window may no longer exist or the window may not support the command
-2 Unknown value
-9 Bad syntax
-11 Value out of range

See Also

For information on event handlers, see the Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Programming Guide.


Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Language Reference

Return to Main Page

Copyright