Programmer Guide/Command Reference/MESSAGE

MESSAGE

The MESSAGE command can be called using MESSAGE or the abbreviation MSG. There are a number of different commands you can pass to the command (see below). Many of the sub-commands use and set the variable #msg variable to return values.

If you want to use macro message handlers in an application, you must call the macro GetMessage to retrieve messages instead of using this command directly. This macro implements, in conjunction with the macros SETMSGHANDLER and DISPATCHMSG, the standard S_TOOLS-STx message handling system.

All message handling macros are part of the standard library STDLIB.STX and described in the Macro Library.

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

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) can be specified. No commands are processed while the sound is played.

DEBUG

The MSG DEBUG command has the following general syntax:

MSG DEBUG cmd [ par ] [ option ]

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

MSG DEBUG INIT [ shell ] [ /Step ]

Initialise the debugger. This must be called once, before any other MSG DEBUG commands.

shell

The shell in which to start the debugger. If this is not specified, the caller's shell is debugged.

/Step

If specified, the debugger breaks execution (like calling MSG DEBUG STEP).

MSG DEBUG STEP [ text ]

Open the debugger and break execution.

MSG DEBUG ON [ macroName ]

Open the debugger. If a macro is specified, the debugger will break as soon as this macro is called.

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 S_TOOLS-STx.

DESKTOP

MESSAGE DESKTOP

Get the origin, height and width of the whole desktop (all monitors) and the number of monitors connected to the computer. Note that the primary monitor always has an 0/0 x/y origin. 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.

#msg = desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors

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.

LOGFILE

MESSAGE LOGFILE logfilename

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

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)

MAIN

MESSAGE MAIN mode [style xpos ypos width height title]

Set and/or get the log-window's mode (HIDDEN|VISIBLE|ENABLED|*), style (MINIMIZED|RESTORED|MAXIMIZED|*), position, size and/or caption. The current settings are stored in the message variable #MSG.

#MSG = mode style xpos ypos width height title

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.

NOMAIN

MESSAGE NOMAIN

Hide the log window and all other S_TOOLS-STx windows.

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!