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. It returns this information in the #msg variable in the following format:

desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors

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. The return values are stored in the variable #msg.

`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

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 shell's message queue. Use /Nowait if you do not want to wait should the message queue be empty. The return values are stored in the variable #MSG.

#MSG = sendertype sendername msgid msgparameter(s)

MESSAGE MAIN

MESSAGE MAIN mode [style xpos ypos width height title]

#MSG = mode style xpos ypos width height title

MESSAGE MENU

MESSAGE MENU /Add name item1 item2 ...

MESSAGE MENU /Add name table /Table

MESSAGE MENU /Show

MESSAGE MENU /Delete

Log window popup-menu handling. All log-window menu commands are similar to the equivalent display/dialog-item commands.

MESSAGE NOMAIN

MESSAGE NOMAIN

Hide the log window and all other STx windows.

MESSAGE RUN

MESSAGE RUN shellid messageid messegaparameters

Send a message to the shell shellid. Do not use this command directly, call the macro POSTMESSAGE instead. The special shellid '*' (all shells, except sender) or '=' (to the sender itself) can be used. Messages sent using this 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 the queue is cleared.