Programmer Guide/Macro Library/Kernal/StdLib

• File: STDLIB.STX, linked to library STX.LIB
• Title: STx main library

---

Content

Variables and items used by this library

name	type	description

AppLoad

APPLOAD appname [ ; appargs ]

Load and run a registered STx application.

argument	description	default
appname	Name of a registered STx application.
appargs	Arguments for the application.
RESULT	description
void	This macro has no return value.

Examples

• Start the realtime analyser: appload rtanalyse
• Start a script: appload bscript run ; $@root\scripts\myscript.sts ; mymacro ; arg1 arg2

AppMain

This is the STx application main macro. It is called by the application management system to initialize, run and finish STx applications. This macro can not be called from other macros.

To end an application and return directly to APPMAIN the command EXIT -1 can be used.

Note

At the end of an application, the sourcecode is unloaded. To avoid unloading the variable AppNoUnload must be set to 1 before returning to APPMAIN.

AppCleanup

This macro is called by APPMAIN to cleanup shell items. It deletes all shell items created by an application. It can also be called from the application to remove all shell items (APPCLEANUP ALL) or spu-items only (APPCLEANUP SPU).

AppHelp

This macro implements an interface to the online-help for STx. It is currently under development.

PostMessage

POSTMESSAGE shellid msgid [ msgpar ]

Post a message to a shell. The meaning of the message depends on the target shell. The target shell must implement message handling for shell messages.

argument	description	default
shellid	Unique id of the target shell.
msgid	The message id.
msgpar	The optional message parameter(s).
RESULT	description
0	success
1	failed

The following special values can be used for the argument shellid to the specify the target shell(s):

• CALLER → the caller of the application
• MASTER → the STx master shell
• SELF or THIS → the shell itself
• ALL or * → all running shells except the sender

Notes:

• The id of the current shell and the calling shell are stored in the variable SHELL: SHELL = current_shell_id calling_shell_id. The shell id is 8 digit hex number.

See also

command MESSAGE

SetMsgHandler

SETMSGHANDLERtype name handler

Install the message handler handler for messages from type name.

SETMSGHANDLERtype name

Remove the message handler for messages from type name.

argument	description	default
type	A typename of a shell item or the keyword SHELL to install/remove a handler for shell messages (see PostMessage).
name	The name of the shell item or the id of the shell. The character * can be used to catch the messages of all shell items of the specified type or of all shells.
handler	The message handler: macroname → messages are passed to the macro macroname function instance → messages are passed to the memberfunction function of the instance-item instance IGNORE → the messages are ignored (not processed) RETURN → the messages are returned to the message loop KILLSPUONSTOP → the sending spu-item is finished and deleted when the STOP message is received KILLSPUONEXIT → the sending spu-item is deleted when the EXIT message is received
RESULT	description
void	no return value

Notes

• A message handler function receives the whole message type name msgid msgpar as argument string.
• If type equals SPU, the built-in message handler functions KILLSPUONSTOP and KILLSPUONEXIT can be used for argument handler. Both functions delete the spu-item when receiving the STOP/EXIT message from the spu.
• If a message handler is installed for type name the macro GETMESSAGE calls the handler function (via DISPATCHMSG when receiving messages from the sender type name. Messages passed to a handler are not returned to the message loop (except if the keyword RETURN was used as handler argument).
• The message dispatching system is only active while the macro GETMESSAGE is running!
• For message handlers in classes the member functions AttachItem and DetachItem should be used.