Programmer Guide/Command Reference/MESSAGE

The MESSAGE command is a low-level means for processing shell messages in STx. There are a number of different sub-commands you may pass to the command (see below). Many of the sub-commands use the variable #msg to return values. The MESSAGE command may be abbreviated to MSG.

If you want to use macro message handlers in an application, you need to call the macro GETMESSAGE to retrieve messages, instead of directly using the MESSAGE command. In conjunction with the macros SETMSGHANDLER and DISPATCHMSG, the GETMESSAGE macro implements the standard STx message handling system.

Note: For message handling in classes, you may use the member functions AttachItem, DetachItem and MsgHandler as an alternative better suited to the object-oriented use-case.

Sub-commands

BEEP, DEBUG, DESKTOP, EXIT, LOGFILE, LOOP, MAIN, MENU, NOMAIN, RUN, QUEUE

The complete set of STx messages is listed under Messages/Communication Messages.

Sub-commands

MESSAGE BEEP

MESSAGE BEEP /Speaker|Asterisk|Exclamation|Hand|Question|Okay
MESSAGE BEEP frequency duration

Play a tone via the PC loudspeaker. A standard windows sound (selected with an option) or a frequency (Hz) and duration (ms) may be specified. No commands are processed while the sound is being played.

MESSAGE DEBUG

The MSG DEBUG command interacts with the STx interactive debugging tool. The command has the following general syntax:

MSG DEBUG cmd [ par ] [ option ]

There are a number of different sub-sub-commands which are described below.

MSG DEBUG INIT [ shell ] [ /Step ]

Initialize the debugger. This must be called exactly once, and it must be called first, i.e., before any other MSG DEBUG commands.

shell

The shell in which to start the debugger (i.e., whose script to debug). If you omit this information, the caller's shell will be debugged.

/Step

If specified, the debugger interrupts execution (like calling MSG DEBUG STEP). It will wait for an interactive command to resume.

MSG DEBUG STEP [ text ]

Open the debugger and interrupt execution. That's just the same like MSG DEBUG INIT /Step.

MSG DEBUG ON [ macroName ]

Open the debugger. If a macro is specified, the debugger will stop execution as soon as the control flow enters the respective macro.

MSG DEBUG OFF

Close the debugger.

MSG DEBUG NO

Close the debugger and disable debugging. If you wish to re-enable the debugger, you must restart STx altogether.

MESSAGE DESKTOP

MESSAGE DESKTOP

The MESSAGE DESKTOP command retrieves the origin, the height and the width of the whole desktop (all monitors), as well as the number of monitors connected to the computer. Furthermore, for each monitor, it will return its virtual coordinates (left, top, right, and bottom, in this order). It returns this information in the #MSG variable in the following format:

desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors
left1 top1 right1 bottom1… leftN topN rightN bottomN

Note that the primary monitor always has an origin of 0/0 (x/y). Therefore, if you have three monitors, and the middle one is the primary monitor, the value desktopXOrigin will be negative.

Code example:

msg desktop
readvar #msg #width #height #x0 #y0 #screencount #

MESSAGE EXIT

MESSAGE EXIT shellid

Terminate a shell shellid immediately. This message is processed by the internal message loop and not by the macros. It can be used to abort shells which are not responding.

MESSAGE LOGFILE

MESSAGE LOGFILE logfilename
MESSAGE LOGFILE *

Redirect all log window output to the specified file. Set logfilename to * to turn redirection off.

MESSAGE LOOP

MESSAGE LOOP [ /Nowait ]

Get the next message from the message queue of the shell. If the message queue is empty, the MESSAGE LOOP command will normally block until there is a message available. For non-blocking operation, use the /Nowait option: With /Nowait supplied, the command will return immediately should the message queue be empty.

The return values of the MESSAGE LOOP command are stored in the #MSG variable in the following format:

sendertype sendername msgid msgparameter1…msgparametern

Code example:

msg loop
readvar #msg #sendertype #sendername #msgid #parms

MESSAGE MAIN

MESSAGE MAIN mode [style xpos ypos width height  title]

Set and/or get the mode of the log window (one out of HIDDEN, VISIBLE, ENABLED, *), its style (one out of MINIMIZED, RESTORED, MAXIMIZED, *), and its position, size and/or caption. The current settings are stored in the message variable #MSG in the following format:

mode style xpos ypos width height title

MESSAGE MENU

MESSAGE MENU /Addpopup name item1 item2…
MESSAGE MENU /Addpopup name table /Table
MESSAGE MENU /Show
MESSAGE MENU /Delete

The MESSAGE MENU command is for handling log window popup menus. Its sub-commands are similar to the corresponding dialog item commands for handling popup menus, ADDPOPUP and DELPOPUP (see there).

MESSAGE NOMAIN

MESSAGE NOMAIN

This will hide the log window and all other STx windows.

MESSAGE RUN

MESSAGE RUN shellid messageid messegaparameters

The MESSAGE RUN command will send a message to the shell shellid. Do not use this command directly! Instead, always call the macro POSTMESSAGE.

If you supply an asterisk, * for the shellid argument (which you won't because you never call this command directly), the message will be sent to all shells except the sending shell. If you supply the character "=" (which you won't either, because you never call this command directly), the message will be sent to the sending shell itself.

Messages sent using the MESSAGE RUN command are pre-processed by the macro GETMESSAGE.

MESSAGE QUEUE

MESSAGE QUEUE [ qtable ]

Empty the internal message queue. If the argument qtable is a simple table, a copy of the internal message queue is stored in the table before actually clearing the message queue.