Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Language Reference
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.
Not applicable.
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.
For more information on events, see the Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Programming Guide.
Allows an event handler to access extra parameters included with a message.
FUNCTION $EventParm(n: INTEGER, type: DATATYPE): DATATYPE;
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. |
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 ...
EVENT MyEvent(REF r: MyRecord); VARIABLES width, height: INTEGER; ACTIONS WHEN $Event IS $MsgSize THEN width:=$EventParm(1,Integer); height:=$EventParm(2,Integer); ...
For more information on events, see the Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Programming Guide.
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.
EVENT MyEvent(REF r: MyData); ACTIONS WHEN $Event IS $MsgCreate THEN WinSetIconBar($Handle,{'CREATE.ICO','DESTROY.ICO'}: LIST OF STRING); ...
Specifies no event processing for a statement that requires an event handler.
EVENT $NullHandler{initializationData}: INTEGER;
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. |
The syntax used for $NullHandler is the same syntax that is used for all dollar values used with event handlers.
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;
Delegates the handling of an event from one event-handling routine to another.
FUNCTION DelegateEvent ( VAL handler: EVENT, [ REF userData: ANY ] ): INTEGER;
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.
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.
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;
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.
Posts a message to a window event handler.
PostMessage( VAL whdl: WINDOW, VAL message: INTEGER, [ VAL msgParm: ANY ... ] ): INTEGER;
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:
|
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. |
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 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 |
Sends a message to a window or dialog box.
SendMessage( VAL whdl: WINDOW, VAL message: INTEGER, [ VAL or REF messageParm: ANY ... ] ): INTEGER;
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. |
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.
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 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 |
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