Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page
In a windowed TSD Script application, events are the primary functional elements of the application. Each event represents an action that may result in a reaction. These events can come from a variety of sources, including:
To handle events, you create event handlers. An event handler is a routine that defines the types of events that can occur within a specific area of the application, and the appropriate reactions to those events. The event handler accesses $Event, which is a variable that contains a message constant. This message constant represents the exact type of activity that is occurring. This page provides detailed information about these message constants, or messages as they are referred to here.
Windows and dialog boxes receive instructions from the user and relay information to the TSD Script application. This activity is called message-passing.
You should account for messages you send and receive as you define event handlers.
This page groups messages into the following:
Some calls to TSD Script functions (such as those that affect controls in the user interface) can transmit messages to an event handler. For example, calling DlgSetFieldValue for a dialog box control sends a $MsgSelect to the event handler for the dialog box.
As described at the beginning of this page, events (and their messages) can come from a variety of sources. There are certain TSD Script statements that send messages directly to your application.
These TSD Script statements, and the messages your application can receive, are listed
in the following table.
Each message constant represents a number that is interpreted by a TSD Script application. The message constant $MsgUser, contains the highest value in the range of numbers reserved by Tivoli Systems Inc. for message constant values.
To create a custom message for your application, use $MsgUser+n where n is any number that you assign to the new message constant. As a custom message constant, $MsgUser+n is available as both a transmittable and receivable message. More information on $MsgUser+n can be found later in this page.
This section covers the following topics:
Receivable messages are messages received by an event. The table of receivable messages summarizes all receivable messages in TSD Script.
To help you interpret the table of receivable messages, remember these tips:
Table of Receivable Messages
$Event | Source | Parameters |
$MsgAccept | Dialog box | $FieldId, $FieldName |
$MsgButton | Hypertext window, dialog box | 1=text of button, 2=ID of button |
$MsgCancel | Dialog box | $FieldId, $FieldName |
$MsgChar | Dialog box Others |
$FieldId, $FieldName, 3=KeyCode $KeyCode |
$MsgCreate | Dialog box Others |
$FormFile, $FormName None |
$MsgDDEAcknowledge | Any | $DDEWindow, $DDEStatus (see DDE Synonyms) |
$MsgDDEAdvise | Any | $DDEWindow, $DDETopic |
$MsgDDEData | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEExecute | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEInitAcknowledge | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEInitiate | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEPoke | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDERequest | Any | $DDEWindow, $DDETopic |
$MsgDDETerminate | Any | $DDEWindow |
$MsgDDEUnAdvise | Any | $DDEWindow, $DDETopic |
$MsgDestroy | Any | None from any window |
$MsgEnterField | Dialog box | $FieldId, $FieldName |
$MsgExitField | Dialog box | $FieldId, $FieldName |
$MsgFocus | Any | $EventParm (1, boolean) |
$MsgHelp | Dialog box | $FieldId, $FieldName |
$MsgImage | Parent of image window | 1=Image ID |
$MsgInitialize | Dialog box | $FieldId, $FieldName, 3=old value, 4=new value |
$MsgLabel | Hypertext window, dialog box | 1=button text, 2=button label |
$MsgMandField | Dialog box | $FieldId, $FieldName |
$MsgMouse | Mouse zone | 1=ID, 2=mouse activity, 3=X, 4=Y |
$MsgMenu | Menu bar Toolbar |
$MenuSelection (n*100 + m) or user defined, $MenuId, 2=string $MenuSelection (1-99) or user defined, |
$MsgPaint | Generic | None |
$MsgPaintStatus | Any dialog box or window that contains a status bar. |
None |
$MsgPageChange | Any dialog box that contains a notebook | 1 = the name of the page that was current before the page change occurred
2 = the name of the page that is now current (i.e., the new page) |
$MsgPageChangeRequest | Any dialog box that contains a notebook | 1 = the name of the page that was current before the page change occurred
2 = the name of the page that is now current (i.e., the new page) |
$MsgScroll | Generic window | 1=$WinHScroll/$WinVScroll, 2=thumb location |
$MsgSelect | Dialog box | $FieldId, $FieldName, 3=old value, 4=new value |
$MsgSize | Generic, scrollable window | 1=width of the window, 2=height of the window |
$MsgTimer | Any | 1=timer ID |
$MsgUser+n | Any | Details belong to sender and receiver. |
Each message constant is, in effect, a parameter of the $Event statement. The definition of the message constant, however, includes additional information, or event parameters. For example, if a user chooses a button on a dialog box, your application receives a $MsgButton message constant. The event parameters defined for this message constant are the field name and field ID of the chosen button.
When you receive the $MsgButton message, you can obtain the event parameter values by using the message synonyms. Synonyms provide a shortcut for obtaining values. For example, to obtain the value of the field name, you should use the synonym, $FieldName. For example:
Name of Field: = $FieldName;
If there are no synonyms defined for an event parameter, you can use $EventParm to obtain the value. To use $EventParm, you must specify the number of the event parameter and the data type of the value. For example, for all dialog box receivable messages, the field name is contained in event parameter two. To obtain the value of the field name event parameter, you could use the following notation:
$EventParm (2, string);
An example follows.
EVENT ExampleEvent (REF rec : MyRecord) IS
VARIABLES
width, height : INTEGER;
ACTIONS
WHEN $Event IS $MsgSize THEN
width := $EventParm(1, INTEGER);
height := $EventParm (2, INTEGER);
ELSWHEN...
END;
END;
Wherever possible, you should use synonyms to obtain the event parameter values. The Table of Receivable Messages lists the event parameters and synonyms for each of the receivable messages.
Tip: All dialog box messages have synonyms defined for the same first and second
event parameters: $FieldId (event parameter one) contains the field ID and $FieldName
(event parameter two) contains the field name.
When you transmit a message, the order of the event parameters is significant. See "Transmitting Messages: Posting and Sending"
for more information. Also see the PostMessage and SendMessage statements.
This section covers the messages that can be received by an event handler that originated from a dialog box.
Tip: Receivable messages that originate from a dialog box involved in a DDE
conversation are listed under the topic "DDE
Receivable Messages" in this section.
The following table lists only the messages that originate from a dialog box and can be
received by an event handler.
Table of Receivable Messages (Dialog Box Messages
Only)
$Event | Source | Parameters |
$MsgAccept | Dialog box | $FieldId, $FieldName |
$MsgButton | Dialog box | 1=text of button, 2=button of Id |
$MsgCancel | Dialog box | $FieldId, $FieldName |
$MsgChar | Dialog box
|
$FieldId, $FieldName, 3=KeyCode $KeyCode |
$MsgCreate | Dialog box | $FormFile, $FormName |
$MsgDestroy | Any | None |
MsgDisplayImage | Dialog box | $ButtonText, $FieldId, $FieldName, $FileName,
$ImageFile, $ProgramArguments, $SearchText, $SoundFile, 1=integer, 2=string, 3=string, 4=string |
$MsgEnterField | Dialog box | $FieldId, $FieldName |
$MsgExitField | Dialog box | $FieldId, $FieldName |
$MsgHelp | Dialog box | $FieldId, $FieldName |
$MsgImage | Parent of Image | 1=ID of the image |
$MsgInitialize | Dialog box | $FieldId, $FieldName, 3=oldValue, 4=newValue |
$MsgLabel | Dialog box | 1= button text, 2=button label |
$MsgListboxAccept | Dialog box | $FieldId, $FieldName, 3=string for listboxes, integer for table |
$MsgMandField | Dialog box | $FieldId, $FieldName |
$MsgMouse | Mouse zone | 1=ID, 2=mouse activity, 3=X, 4=Y |
$MsgMenu | Menu bar
|
$MenuSelection (n*100 + m)
|
$MsgOpenFile | Dialog box | $ButtonText, $FieldId, $FieldName, $FileName,
$ImageFile, $ProgramArguments, $SearchText, $SoundFile, 1=integer, 2=string, 3=string, 4=string |
$MsgPlaySound | Dialog box | $ButtonText, $FieldId, $FieldName, $FileName,
$ImageFile, $ProgramArguments, $SearchText, $SoundFile, 1=integer, 2=string, 3=string, 4=string |
$MsgRunProgram | Dialog box | $ButtonText, $FieldId, $FieldName, $FileName,
$ImageFile, $ProgramArguments, $SearchText, $SoundFile, 1=integer, 2=string, 3=string, 4=string |
$MsgSearch | Dialog box | $ButtonText, $FieldId, $FieldName, $FileName,
$ImageFile, $ProgramArguments, $SearchText, $SoundFile, 1=integer, 2=string, 3=string, 4=string |
$MsgSelect | Dialog box | $FieldId, $FieldName, 3=oldValue, 4=newValue |
$MsgTimer | Any | 1=timer ID |
$MsgUser+n | Any | Details belong to sender and receiver |
There are several synonyms that are used with dialog box receivable messages. The synonyms that are used most frequently are $FieldId and $FieldName.
The other synonyms that appear in the table of receivable messages are explained fully with their respective messages. For general information on the use of synonyms, see the topic "Message Parameters and Synonyms" in this page.
The receivable dialog box messages listed in the Table of Receivable Messages are described here.
Received by | Any dialog box that contains the control. |
Description | $MsgAccept is received when an accept event is generated in the dialog box. |
Event parameters | There are two event parameters:
|
Response | The accept action may be canceled by returning 0 from the event group. |
Notes | An accept event may occur in the following ways:
In OS/2, if there is no button defined as the default button, and if the cursor is not
in a field that interprets the Enter key, an accept event is generated when the user
presses the Enter key. |
Received by | Any hypertext viewer window. |
Description | $MsgButton is received when a button of type ID (the default type)
is selected in a hypertext viewer window. Note: A button in a hypertext viewer represents a link to another entity (such as another file, another point in the existing file, an image, a sound file, or executable file). |
Event parameters | There are two event parameters:
|
Received by | The dialog box containing the control. |
Description | $MsgCancel is received when the dialog box generates a cancel event. A cancel event is generated when the user chooses either the Cancel button or presses the Escape key. |
Event parameters | There are two event parameters:
|
Response | The cancel action can be aborted by returning zero from the event group. If the action is not refused, the dialog box closes. |
Received by | Any dialog box. |
Description | $MsgChar is received in a dialog box when the user types a character in a control that cannot be processed by the control. The exact characters passed to the event handler vary by field. In general, Control, Alt, and function keys are received. |
Event parameters | There are three event parameters:
|
Response | The $KeyCode parameter cannot be used with dialog boxes. The character is passed in the third event parameter (integer). |
Notes | The F1 key value is not passed to the dialog box. Instead, the F1 key either generates a $MsgHelp or displays any existing help text. |
Received by | Any dialog box in the process of being created. |
Description | $MsgCreate is one of the first messages a dialog box receives when it is created. |
Event parameters | There are four event parameters
|
Response | Returning zero from the event group aborts dialog box creation. The DlgCreate and the DlgBox statements return a No Create error. |
Notes | At the time $MsgCreate is received, the dialog box has not yet
been displayed. However, the following have already occurred:
See the $MsgInitialize message for more information. |
Received by | Any dialog box. |
Description | This message is generated when a $MsgClose is sent to
the dialog box. The $MsgClose message is generated when the user accepts or closes
the dialog box. When the dialog box receives the $MsgDestroy, its window handle is still valid until the destroy process finishes. The dialog box continues to receive messages until it returns from the $MsgDestroy message. |
Response | Any response is ignored. |
Notes | This message should be received by the dialog box after all its controls and any child windows have been destroyed. |
Received by | Any dialog box. |
Description | $MsgEnterField is generated when a user enters a control (either
by pressing the Tab key or by clicking the mouse in a different control). This is received before the cursor shifts to a new control. The control that has the focus receives the $MsgExitField message. |
Event parameters | There are two event parameters:
|
Response | To prevent the cursor from moving to the new control, return zero from the event group while processing this message. |
Notes | If entry into the new control is refused, the cursor returns to the field
that the user just exited. This results in the generation of another $MsgEnterField
message when the cursor changes. If the return to that control is also refused, the event is canceled; no control has the cursor. |
Received by | Any dialog box. |
Description | $MsgExitField is generated by exiting a control (either by pressing the Tab key or by clicking with the mouse in a different control). This message is received before the cursor leaves a control. |
Event parameters | There are two event parameters:
|
Response | To prevent the cursor from moving, return zero from an event group while processing this message. |
Received by | Any dialog box. |
Description | $MsgFocus is generated when a dialog box loses its keyboard focus. |
Event parameters | $EventParm (1, boolean) identifies whether the dialog box is losing its focus. |
Received by | Any dialog box. |
Description | $MsgHelp is generated when the user chooses a Help button but the system cannot find help for the dialog box or control. |
Event parameters | There are two event parameters:
|
Received by | Any dialog box. |
Description | $MsgInitialize is a special version of $MsgSelect that
occurs only during the creation phase of a dialog box. $MsgInitialize allows you to do special processing on the values of the dialog box controls during creation. After creation, all events for a dialog box control are received as $MsgSelect messages. |
Event parameters | The $MsgInitialize message has four event parameters, like $MsgSelect:
|
Received by | Any dialog box. |
Description | $MsgLabel is generated when the user selects a button of type LABEL in a hypertext viewer window. |
Event parameters | The $MsgLabel message has two event parameters:
|
Received by | Any dialog box |
Description | $MsgListboxAccept reports the double-clicked item in a list box. |
Event parameters | There are three event parameters:
|
Response | Exiting from this message prevents $MsgAccept |
Received by | Any dialog box |
Description | $MsgMandField is received when an accept action is received by the dialog box and a mandatory field does not have a value. |
Event parameters | There are two event parameters:
|
Response | If FALSE is returned, the system cannot process the message. If this message is unprocessed or if the event group returns the default value (1), the system displays a message box that informs the user that a mandatory value is missing and that the accept action is canceled. When the user closes the message box, the cursor is moved to the first empty mandatory control in the dialog box. $MsgExitField, $MsgSelect, and $MsgEnterField messages may be generated by the move. The accept action is aborted. If the event group returns any value other than 1, the system takes no action. The application must position the cursor and refuse the $MsgAccept. |
Received by | Any dialog box. |
Description | $MsgMenu is received when the user makes a selection from a menu bar or a toolbar in the dialog box. |
Event parameters | The pseudo parameter, $MenuSelection, has the index of the selected menu item.
A selection from the toolbar generates a value from 1 to 99, based on the position of the
icon. A selection from the menu bar generates a value based on the formula: n * 100 + m where n is the position of the active selection on the main menu bar and m is the position of the selection on the submenu. |
Notes | There is no current control name or ID with this message. Also, in earlier versions it was possible to simulate a menu selection; this is no longer supported. |
The current text position for the status bar is reset to 1,1 each time a $MsgPaintStatus message is generated.
Received by | Any dialog box that contains a notebook. |
Description | The $MsgPageChange is received by the notebook event handler upon creation of the notebook (setting of the initial page), and whenever the current page is changed. Parameters of the event specify the old page and the new page. |
Event parameters | There are two event parameters:
|
Notes | This message is also received when a notebook is first displayed (after $MsgCreate). In this case, the first parameter is set to $Unknown, and the second parameter is the name of the initial page. |
Received by | Any dialog box that contains a notebook. |
Description | The $MsgPageChangeRequest is delivered before a page is changed. (Exiting with zero prevents a page from changing.) Parameters of the event specify the old page and the new page. |
Event parameters | There are two event parameters:
|
Received by | Any dialog box. |
Description | $MsgSelect is received whenever the value of a control
is changed. Upon receipt of this message, the instance data is updated to reflect the new value of the control. During the processing of $MsgSelect, the actual value of the control cannot be determined. This occurs because, in Windows, the instance data is updated with the actual value of the field before $MsgSelect is called. In OS/2, the instance data is updated with the actual value of the field after $MsgSelect is called. |
Event parameters | The $MsgSelect message has four event parameters:
|
Response | Return the value 1 to allow the new value to remain. The resulting messages are $MsgExitField and $MsgEnterField. |
Notes | A $MsgSelect message can be generated in several ways:
The data type of the value contained in event parameter three is based on the instance
data that is bound to it. If no ID is bound, the data is $Unknown. |
Received by | Any dialog box. |
Description | $MsgTimer is received in response to a timer event. |
Event parameters | The event parameter (integer) contains the ID of the timer as passed via $MsgStartTimer. |
Notes | A window must have a timer set in order to receive $MsgTimer. |
Received by | Any dialog box that has an event handler. |
Description | This is a user-defined message constant. |
Event parameters | Any event parameters can be passed with a user-defined message. If the
additional parameters can be assigned in the SendMessage statement, they can be
assigned in the event handler. The receiving window must know which parameters are valid for the message. |
Notes | All user-defined messages must have a value of $MsgUser+n where n is any number that you choose to assign to the new message constant. |
This section covers receivable messages for windows.
In the Table of Receivable Messages, items listed in the $Event column represent the message constants.
Items listed in the Source column represent the type of application component (dialog box or window) that sent the message.
The entry in this column determines the classification of the message. For example, the message $MsgCreate has the source, dialog box, and is therefore a dialog box receivable message. More information about this message can be found in "Dialog Receivable Messages."
Some items listed in the Source column are abbreviated. For example:
The Parameters column lists the event parameters defined for the message constant. Synonym values begin with a $. (See "Window Synonyms" for more information.)
Table of Receivable Messages (Window Messages Only)
$Event | Source | Parameters |
$MsgActivate | Generic window, scroll window | 1=activation status |
$MsgButton | Hypertext window, dialog box | 1=text of button, 2=ID of button |
$MsgChar | Any window | $KeyCode |
$MsgCreate | Any window | Apply to dialog boxes only |
$MsgDestroy | Any window | None |
$MsgImage | Parent of image | 1=Image ID |
$MsgLabel | Hypertext window, dialog box | 1=button text, 2=button label |
$MsgMouse | Mouse zone | 1=ID, 2=mouse activity, 3=X, 4=Y |
$MsgMenu | Menu bar Toolbar |
$MenuSelection (n*100 + m) $MenuSelection (1-99) |
$MsgPaint | Generic | None |
$MsgPaintStatus | Any window or dialog box with a status bar | None |
$MsgScroll | Generic window | 2=thumb location, 1=$WinHScroll / $WinVScroll |
$MsgSize | Generic, scrollable window | 1=width of the window, 2=height of the window |
$MsgTimer | Any | 1=timer ID |
$MsgUser+n | Any | Details belong to sender and receiver |
The synonyms that appear in the Table of Receivable Messages (Window Messages Only) are explained here with their respective messages. For general information on the use of synonyms, see "Message Parameters and Synonyms."
Received by | A window or scroll window. |
Description | $MsgActivate is received when a window or scroll window is activated or deactivated. |
Event parameters | There is one event parameter:
|
Response | If the window is activated, it receives the focus. If the window is deactivated, the focus moves to the window that becomes activated. The color of the window may change to reflect activation or deactivation, depending on your system configuration. |
Received by | A hypertext viewer window. |
Description | $MsgButton is received when a button of type ID (the default type)
is selected in a hypertext viewer window. Note: a button in a hypertext viewer represents a link to another entity (such as another file, another point in the existing file, an image, a sound file, or executable file). |
Event parameters | There are two event parameters:
|
Response | If the button ID is 0 and the event handler returns 0, the hypertext viewer window modifies the button text and searches the active file for a match. It a match is found, the file is scrolled so the matching line is at the top of the viewer. |
Received by | Any dialog box. |
Description | $MsgChar is received whenever the user enters a character from the keyboard that the active window does not process. |
Event parameters | The parameter $KeyCode may be used to access the character. The character may be a printable character or one of the standard $Key definitions. (See $KeyCode for a complete list of available key codes.) |
Received by | Any window or dialog box. |
Description | This message is received after the controls in a window or dialog box have been initialized. When this message is received, the window or dialog box is painted. |
Received by | Any window. |
Description | $MsgDestroy is the last message a window receives before being destroyed (unless the window is destroyed as part of application termination). |
Notes | When the $MsgDestroy message is received, all child windows may still exist unless they have been explicitly destroyed. |
Received by | Any image window. |
Description | $MsgImage is sent by an image window to notify its parent that the user has clicked the image with the mouse. |
Event parameters | The event parameter (integer) has the ID of the image selected. |
Received by | A hypertext viewer window. |
Description | $MsgLabel is received when a button of type LABEL is selected in a hypertext viewer window. |
Event parameters | There are two event parameters:
|
Received by | Any dialog box with a menu bar or toolbar. |
Description | $MsgMenu is received when a selection is made from a menu bar or a toolbar. |
Event parameters | $MenuSelection contains the ID of the selected menu item. |
Notes | The ID of the selected menu item can be sent to any window with a menu
bar. It simulates that action of a user who selects a menu item with the index that is
contained in the MenuSelection parameter. A selection from the toolbar generates a value from 1 to 99, based on the position of the icon on the toolbar. A selection from the menu bar generates a value based on this formula: n * 100 + m where n is the position of the active selection on the main menu bar and m
is the position of the selection on the submenu. |
Received by | Any window. |
Description | $MsgMouse is received when there is mouse activity in a mouse zone
defined by the WinCreateMouseRect statement. |
Event parameters | $MsgMouse has the following event parameters:
|
Notes | WinSetMousePointer must be called every time $MsgMouse is
processed. The defined mouse activities include:
For more information, see WinCreateMouseRect. |
Received by | Any generic window. |
Description | $MsgPaint is received when all or part of a window must be repainted. |
Received by | Any window. |
Description | $MsgScroll is received when the user moves the scroll box on either the horizontal or the vertical scroll bar. |
Event parameters | There are two event parameters:
|
Received by | Any generic window or window with a scroll bar. |
Description | This sets the size of the window. |
Received by | Any window. |
Description | $MsgTimer is received in response to a timer event. |
Event parameters | The event parameter (integer) contains the ID of the timer as passed in $MsgStartTimer. |
Notes | A window must have a timer set to receive a $MsgTimer. |
Received by | Any window that has an event function. |
Description | This is a user-defined message constant. |
Event parameters | Any event parameters can be passed with a user-defined message. If the additional parameters can be assigned in the SendMessage statement, they can be assigned in the event function. |
Notes | All user-defined messages must have a value of $MsgUser+n where n is any number that you choose to assign to the new message constant. |
This section covers the messages that can be received by an event handler defined for a dialog box or application running in a DDE application.
Items listed in the $Event column represent the message constants.
Items listed in the Source column represent the type of application component (dialog box or window) that sent the message.
The entry in this column determines the classification of the message. For example, the message, $MsgCreate has the source, dialog box, and is therefore a dialog box receivable message. More information about this message can be found in "Dialog Receivable Messages."
In the Source column, the term Any represents any dialog box or window item in any running application.
The Parameters column lists the event parameters defined for the message constant. Synonym values begin with a $. See "DDE Synonyms" for more information.
The following table lists the messages that can be received by an event handler defined for a dialog box or application running in a DDE application.
Table of Receivable Messages (DDE Messages Only)
$Event | Source | Parameters |
$MsgDDEAcknowledge | Any | $DDEWindow, $DDEStatus |
$MsgDDEAdvise | Any | $DDEWindow, $DDETopic |
$MsgDDEData | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEExecute | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEInitAcknowledge | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEInitiate | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDEPoke | Any | $DDEWindow, $DDETopic, $DDEData |
$MsgDDERequest | Any | $DDEWindow, $DDETopic |
$MsgDDETerminate | Any | $DDEWindow |
$MsgDDEUnAdvise | Any | $DDEWindow, $DDETopic |
Tip: Any time a DDE message is received, a $MsgDDEAcknowledge message should
be returned. Failing to return a $MsgDDEAcknowledge may result in a memory loss.
Tip: If you want to send a positive acknowledge when a $MsgDDExxx is
received, simply EXIT ($DDEAck). If you want to send a negative acknowledge, simply
EXIT(0).
There is a special group of synonyms available for DDE messages. These synonyms are:
When using these flags, parse them with the BitAnd statement. For more information, see BitAnd.
The following table shows terms that are used to describe messages passed between DDE
applications.
Term | Definition |
Conversation | The exchange of information between two applications in a DDE session. |
Partner | A member of a DDE conversation. |
Client | The partner who requests information from another application in the conversation. |
Server | The partner who supplies the requested information to the client DDE partner. |
Application/Topic Pair | If you are a DDE client, this is what you pass to your DDE server to
establish a communication link with it. Alternatively, if you are a DDE server, this is the combination of application and topic(s) that you can service. |
Received by | Either DDE partner (client or server). |
Description | This message informs the DDE partner of the success or failure of a
requested action. $MsgDDEAcknowledge should be sent in response to any of the
following messages:
|
Event parameters (Windows) |
The following event parameters are used with the DDEExecute
statement in Windows.
The following event parameters are used with all other DDE messages in Windows.
|
Event parameters (OS/2) | The following event parameters are used with $DDEExecute in OS/2.
The following event parameters are used with all other DDE messages in OS/2.
|
Notes | If $DDEData is the received message, it can be sent instead of the actual message data. |
Received by | Any DDE server. |
Description | Requests continuous updates on the topic contained in $DDETopic. This is a text-only message. |
Event parameters (Windows) | The following event parameters are used with Windows.
|
Event parameters (OS/2) | The following event parameters are used with OS/2.
|
Response | The application should execute a DDEData every time the data changes. |
Received by | Any DDE client. |
Description | This message is sent in two cases:
|
Event parameters | There are several possible event parameters:
|
Exit Value | $DDEAck is returned if the data was used. For example: EXIT ($DDEAck) |
Notes | If the data is sent in response to a DDEAdvise, the $DDEStatus flag may be set to $DDENoData. In this case, the application issues a DDERequest to retrieve the actual data. |
Received by | Any DDE server. |
Description | This message is sent to tell the server to take some action. |
Event parameters (Windows) | The following event parameters are used in Windows.
|
Event parameters (OS/2) | The following event parameters are used with OS/2.
|
Exit Value | $DDEAck should be sent if a command was completed. |
Notes | It is the responsibility of the partners to define the command strings. |
Received by | Any DDE server. |
Description | $MsgDDEInitAcknowledge is received in response to a DDEInitiate
function. Every application that matches the application or topic pair that is passed to DDEInitiate
sends a $MsgDDEInitAcknowledge with the following items:
|
Event parameters | There are two event parameters:
|
Notes | One $MsgDDEInitAcknowledge message is sent for every matching application or topic pair. For example, if the topic string is specified to be blank, the server sends $MsgDDEInitAcknowledge for each topic it supports. |
Received by | Any potential DDE server application. |
Description | $MsgDDEInitiate is received when an application requests that the
receiving application be a DDE server. The receiving application must check the
application name in $DDEData to determine if it is the intended recipient. If the application is the intended recipient, it must check the value of $DDETopic to determine if it can fill the request. Zero-length strings in $DDEData and $DDETopic are accepted as matches for any application and topic. |
Event parameters | There are two event parameters:
|
Response | Call DDERespond. Pass each topic and application name as needed. |
Notes | Do not use DlgBox, WinMessageBox, or WinWait while
you process a $MsgDDEInitiate message. $MsgDDEInitiate broadcasts a message to the applications and locks the message queue until a response is returned. Meanwhile, these statements each initiate an event handler that is also waiting for a reply from the message queue. These statements prevent the other applications from sending messages to the message queue. This results in a deadlock, which effectively locks the user interface. |
Received by | Any DDE server. |
Description | This contains unsolicited data (data that is not sent in response to an advise or request message). |
Event parameters | There are several event parameters:
|
Response | The recipient application must send an acknowledgment ($DDEAck) if the data was used or processed. |
Received by | Any DDE server. |
Description | This is a request for data on a topic. |
Event parameters | There are two event parameters:
|
Response | Call DDEData. Pass in requested information. |
Exit Value | Exit with $DDEAck if the data is being returned. |
Received by | Either DDE partner (client or server). |
Description | Terminates the conversation. Either partner may send $MsgDDETerminate at any time. |
Event parameters | See the topic "DDE Synonyms" for a list of the valid status flags. |
Response | If you called DDETerminate, then you should make no response. If you have not called DDETerminate then it should be called. |
Received by | Any DDE server. |
Description | This cancels an advise request for a given client or topic pair. This is a text-only message. |
Event parameters (Windows) | The following event parameters are used in Windows:
|
Event parameters (OS/2) | The following event parameters are used with OS/2:
|
Notes | If the topic string is blank, all advises for the client must be canceled. |
This section covers the following topics:
TSD Script programs can transmit messages to other parts of the application or to the window system. Any window or dialog box can send or post, as appropriate, any of the transmittable messages.
The table of transmittable messages lists the event messages that can be sent or posted to window handles.
Items listed in the $Event column represent the message constants.
Items listed in the Receiver column represent the type of application component (dialog box or window) that receive the message.
Some items listed in the Receiver column are abbreviated. For example:
The Post/Send column indicates whether the message is sent with the PostMessage or with the SendMessage statement, or both. If an item is sent, it is described more fully under the topic "Sent Messages." If the message is posted, it is described more fully in "Posted Messages."
The Parameters column contains the parameters for the messages.
Tip: The order of the parameters is significant because parameters must be used in
the sequence in which they are listed.
The following table lists the event messages that can be sent (with a SendMessage statement) or posted (with a PostMessage statement) to window handles.
Table of Transmittable Messages
$Event | Receiver | Post/Send | Parameters |
$MsgActivate | Any window with a frame | S, P | none |
$MsgChar | Any dialog box | S, P | 1=field ID, 2=field name, 3=key code |
$MsgClockSet | Clock window | S | Time |
$MsgClose | Any | S | None |
$MsgDisplayImage | Hypertext viewer window | S, P | 1=file name, 2=title, 3=style |
$MsgEnable | Any | S, P | enableState |
$MsgMaximize | Any dialog box or window with a frame | S | none |
$MsgMenu | Any window or dialog box with a menu bar | S, P | menuSelection, 2=string |
$MsgMinimize | Any window or dialog box with a frame | S | none |
$MsgMove | Any window or dialog box with a frame | S | 1=x, 2=y |
$MsgOpenFile | Hypertext viewer window | S, P | 1=file name, 2=title, 3=style |
$MsgPaint | Any | S, P | none |
$MsgPaintStatus | Any window or dialog box with a status bar | P | none |
$MsgPlaySound | Hypertext viewer window | S, P | 1=file name, 2=title, 3=style |
$MsgReadOnly | Dialog box | S | writeState |
$MsgRestore | Any window or dialog box with a frame | S | none |
$MsgSearch | Hypertext viewer window | S, P | searchText |
$MsgSetIcon | Window | S | iconFile |
$MsgSetImage | Image window Dialog box, scrollable window |
S S |
imageFile Window ID |
$MsgSetSize | Any window or dialog box with a frame | S | 1=width, 2=height |
$MsgSetTitle | Any window or dialog box with a frame | S | title |
$MsgShow | Any | S | visibilityState |
$MsgSize | Generic, scrollable window | S | 1=width, 2=height |
$MsgStartTimer | Any window or dialog box with an event handler | S | 1=timer ID, 2=interval Important: Interval cannot exceed 65535. |
$MsgStopTimer | Any window or dialog box with an event handler | S | timer ID |
$MsgTimer | Any dialog box | S, P | timer ID |
$MsgUpdate | Hypertext viewer window | S, P | none |
$MsgUser+n | Any | S, P | Details belong to sender and receiver |
The following table lists the same transmittable event messages and describes the effect of each message.
Definitions of Transmittable
Messages
Event | Description |
$MsgActivate | Activates the receiving window |
$MsgClockSet | Sets a clock to a new time |
$MsgClose | Destroys the window |
$MsgDisplayImage | Creates a new image viewer in a hypertext viewer window |
$MsgEnable | Sets the enable state of the window |
$MsgMaximize | Maximizes the target window |
$MsgMenu | Simulates a user selection of a menu item |
$MsgMinimize | Minimizes the target window to an icon on the desktop |
$MsgMove | Moves the upper left corner of the target window |
$MsgOpenFile | Creates a new hypertext viewer window to display a file |
$MsgPaint | Causes the target window to repaint itself |
$MsgPaintStatus | Causes the target window to repaint its status bar |
$MsgPlaySound | Creates a new hypertext viewer window to play an audio file |
$MsgReadOnly | Tells a dialog box to set certain controls to read-only |
$MsgRestore | Causes a target to restore its size. |
$MsgSearch | Tells the hypertext viewer window to search for a line and move it to the top of the hypertext viewer window |
$MsgSetIcon | Sets the icon for the window when minimized |
$MsgSetImage | Sets the image to be displayed in image windows |
$MsgSetSize | Sets the overall size of the window |
$MsgSetTitle | Sets the contents of the title bar for a window |
$MsgShow | Sets the visibility attribute of the window |
$MsgSize | Sets the size of the work area of the window |
$MsgStartTimer | Starts the timer for the window |
$MsgStopTimer | Stops the timer |
$MsgTimer | Simulates a timer message being sent to the window |
$MsgUpdate | Tells the dialog box to update the displayed values in its controls from
the data in the instance record. This message can only be sent or posted to a dialog box. This message forces the dialog box to update the displayed values in its controls from the data in its instance records. This message is a useful mechanism for changing multiple fields in a dialog box with a single command (as opposed to multiple DlgSetFieldValue function calls). You update the value in the record and send this message to the dialog box. |
$MsgUser+n | Communicates a program-defined message to a window |
TSD Script provides two built-in routines to transmit messages and data: SendMessage and PostMessage. The key difference between sending and posting a message is that SendMessage waits until the called event handler completes processing of the message. PostMessage places the information on an event queue, which allows your posting routine to continue without waiting for message completion.
Certain types of messages cannot be posted to some kinds of windows.
When you transmit a message, you use either the SendMessage or PostMessage statements, as appropriate. The syntax of these statements is basically the same:
SendMessage (VAL whdl: WINDOW,
VAL message: INTEGER,
[VAL or REF messageParm: ANY...]):
INTEGER;
For more information see SendMessage or PostMessage.
The topics that follow on the Transmittable Messages are organized by those that can be sent (transmitted with SendMessage) and those that can be posted (transmitted with PostMessage).
The following messages can be sent to window handles with the SendMessage statement.
Sent to | This can be sent to any window with a frame |
Description | It causes the receiving window to become the active window |
Sent to | This can be sent to any window with a clock |
Description | Sets a clock to a new time |
Event parameters | The event parameter (time) contains the new time of the clock |
Notes | See WinCreateClock |
Sent to | This can be sent to any window |
Description | It destroys the window |
Sent to | This can be sent to a hypertext viewer window |
Description | Creates a new image viewer and displays the specified file |
Event parameters | There are three event parameters: The first event parameter contains the name of the file (string) that appears in the hypertext viewer window The second event parameter contains the title (string) that appears in the title bar The third event parameter three contains the style that is comprised of any combination of the following styles, combined with the BitOr statement:
|
Sent to | This can be sent to any window. |
Description | It sets the enabled state of the window. |
Event parameters | The event parameter contains either TRUE or FALSE, representing the
enabled state of the window.
|
Sent to | This can be sent to any window with a frame |
Description | It maximizes the receiving window to fill the entire screen |
Sent to | This can be sent to any window with a menu bar |
Description | Simulates a user selecting the specified menu option |
Event parameters | The event parameter contains the value of the selected menu item
(integer). This value is calculated using the formula n * 100 + m where n is the position of the active selection on the main menu bar and m is the position of the selection on the submenu. |
Notes | For more information, see WinSetMenuBar. |
Sent to | This can be sent to any window with a frame |
Description | Minimizes the receiving window to an icon |
Sent to | This can be sent to any window |
Description | Moves the upper left corner of the window frame to the specified position |
Event parameters | There are two event parameters:
|
Sent To | This can be sent to a hypertext viewer window |
Description | Creates a new file viewer and displays the specified file |
Event parameters | There are three event parameters:
|
Sent To | This can be sent to a hypertext viewer window. |
Description | Creates a new audio player and plays the specified file. |
Event parameters | There are three event parameters:
|
Sent To | This can be sent to an TSD Script dialog box |
Description | This sets or clears the read-only flag on a dialog box |
Event parameters | The event parameter contains either TRUE or FALSE.
|
Notes | See DlgBox for more information. |
Sent To | This can be sent to any window with a frame |
Description | Restores the receiving window to its original size (before being minimized or maximized) |
Sent to | This can be sent to a hypertext viewer window. |
Description | Searches the active sub-hypertext viewer window for the specified text. If a match is found, the line with the match is positioned at the top of the viewer. |
Event parameters | The event parameter contains the string to search for in the hypertext viewer window. |
Notes | The active sub-hypertext viewer window is expected to be a text viewer.
This is always true if the search message is sent in response to a button message.
User-defined messages can be sent to any window that has an event function. All user-defined messages must have a value of $MsgUser or greater. Any additional parameters can be passed with a user-defined message. It is the responsibility of the receiving window to know which parameters are valid for the message. If the additional parameters can be assigned in the SendMessage statement, then they can be assigned in the event function. |
Sent to | This can be sent to a generic window, scroll window, hypertext viewer window, or a dialog box |
Description | Sets the icon that is displayed when the window is minimized |
Event parameters | The event parameter contains the icon file name to display (string) |
Sent to | This can be sent to an image window. |
Description | Sets the image. |
Event parameters | The event parameter contains the image file name to display (string). The image can be an OS/2 bitmap file, a Windows bitmap, or a .PCX image file. |
Notes | See WinCreateImage for more information. |
Sent to | This can be sent to any window |
Description | Sets the size of the window (including frame, title bar, and other elements) |
Event parameters | There are two event parameters:
|
Sent to | This can be sent to any window with a title bar |
Description | Sets the text of the title bar to the specified text |
Event parameters | The event parameter contains the text (string) to display in the title bar |
Sent to | This can be sent to any window |
Description | Sets the visibility of a window |
Event parameters | The event parameter contains either TRUE or FALSE, indicating whether the window is visible (TRUE) or invisible (FALSE) |
Sent to | This can be sent to a generic window or a scroll window. |
Description | Sets the size of the user area of the window to the specified height and width. Adjusts the size of the window frame accordingly. |
Event parameters | There are two event parameters:
|
Sent to | This can be sent to a generic window or a scroll window. |
Description | Starts a system timer for the window. The timer sends a $MsgTimer message to the window at specified intervals. |
Event parameters | There are two event parameters:
|
Notes | The operating system does not guarantee the accuracy of the interval at
which the $MsgTimer message is sent to the window. There are a limited number of timers available. Always stop a timer when you no longer need it. |
Sent to | This can be sent to a generic or a scroll window |
Description | Stops the timer started with $timerId |
Event parameters | The event parameter contains the ID of the timer (integer) |
Sent to | This can be sent to a generic or a scroll window |
Description | Simulates a timer message being sent to a window |
Event parameters | The event parameter contains the ID of the timer (integer) |
Sent to | Any window or dialog box, as defined by the user. |
Description | This is a user-defined message constant. |
Event parameters | Any parameters can be passed with a user-defined message. If the
additional parameters can be assigned in the SendMessage statement, they can be
assigned in the event function. The receiving window must know which parameters are valid for the message. |
Notes | All user-defined messages must have a value of $MsgUser+n where n is any number that you choose to assign to the new message constant. |
The following messages can be sent to window handles with the PostMessage statement.
Posted to | This can be posted to any window with a menu bar |
Description | Simulates the user selection of a menu item that has the ID specified in the menuSelection argument. |
Event parameters | menuSelection (integer) |
Notes | See WinSetMenuBar for more information |
Posted to | This can be posted to any window |
Description | Moves the upper left corner of the window frame to the specified position |
Event parameters | There are two event parameters:
|
Posted to | This can be posted to any window |
Description | Requests the window to redraw itself |
Posted to | This can be posted to any window with a status bar |
Description | Requests the window to repaint its status bar |
Posted to | User-defined messages can be posted to any window that has an event function. |
Description | All user-defined messages must have a value of $MsgUser or greater. |
Event parameters | Any event parameters may be passed with a user-defined message. It is the responsibility of the receiving window to know which parameters are valid for the message. parameters are always passed by value. |
All outgoing communications from your DDE application should be handled via the appropriate TSD Script statements. See the following statements:
Tip: Each time a DDE message is received, a $MsgDDEAcknowledge message should be returned. Failing to return a $MsgDDEAcknowledge may result in a memory loss.
Tip: If you want to send a positive acknowledge when a $MsgDDExxx is received, simply EXIT($DDEAck). If you want to send a negative acknowledg, simple EXIT(0).
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference