Programmer Guide/General Descriptions/Shell Environment

Variables which do not begin with @, # or & (i.e. all variables beginning with an alphanumeric character) are so-called shell environment variables.

APPMODE, the application run-mode

The shell variable APPMODE indicates the current mode the application APPMAIN is in. A value of 0 indicates that APPNAME is inactive or finished; a value of 1 indicates that APPNAME is currently active..

APPNAME, the application name

The shell variable APPNAME is defined in the registration entry in the configuration files. To start the shell application defined and registered in the configuration files, the macro APPMAIN is used. Before calling the application's main macro (called: RUNappname), APPMAIN assigns the application name to the variable APPNAME and sets the application mode APPMODE to active (1). The variable APPMODE is used by the macro GETMESSAGE to check the application mode. If APPMODE is set to 0 (e.g. in a message handler) GETMESSAGE stops receiving messages and returns the value * * * *.

Applications started via APPMAIN must never use EXIT 0 to terminate the shell. They must return to APPMAIN (using a normal EXIT 1 command from the main macro) which performs some clean-up functions before the shell is terminated.

CSF, the name of the current soundfile

The name (full path) of the current, i.e. active soundfile is assigned to the variable CSF when a LOAD (open) or UNLOAD (close) command is executed. If CSF is not set (i.e. empty), no soundfile is active.

CSFH, properties of the current soundfile

CSFH = srate channels samples code type mode

The parameters of the current/active soundfile are assigned to the variable CSFH when a LOAD (open) or UNLOAD (close) command is executed.

EMSG, the current error message string

If an error occurs, the textual description corresponding to the return code RC is stored in EMSG.

Note that you can use the command EMSG to retrieve a description of an error code.

PARENT, the parent window

PARENT = windowitemname

The variable PARENT is used by the window-management functions (e.g. in GETMESSAGE or by DOMODALDIALOG) to identify the parent (main) window of an application. In each application the name of the item (of type display or dialog) used as main window should be assigned to this variable (directly after creation). If PARENT is not set, some functions or user interactions will not work correctly (e.g. minimize/restore).

Special processing applied to the main window:

• The main-window item's close message is translated by GETMESSAGE into the message SHELL thisshell EXIT.
• If the application is minimized, the main window is displayed in the taskbar while all other window are set to invisible. On restore, all windows are restored to their last status/position.

RC, the return code

The return code of the last executed command. See Command Return Codes for details.

RESULT, the macro result

The value returned by the previous macro. See Macro Results for details.

SCRIPTDIRECTORYThe shell variable SCRIPTDIRECTORY is available when an STx script (*.sts) is running. It contains the directory path where the running script file is.

SCRIPTFILEPATHThe shell variable SCRIPTFILEPATH is available when an STx script (*.sts) is running. It contains the name of the name of the running script file including the path.

SCRIPTMAINNAMEThe shell variable SCRIPTMAINNAME is available when an STx script (*.sts) is running. It contains the name of the running macro.

SCRIPTREVISIONThe shell variable SCRIPTREVISION contains the Subversion repository revision number of the STx version used to create the current script. For scripts created before r751, this variable is set to 0.

SHELLSHELL = thisshellid [callershellid]

The variable SHELL is generated during the startup code execution of the shell called via the command SHELL. Both the id of the calling shell (callershellid) and that of new shell (thisshellid) are assigned. The one exception is the master shell (the first one to be started (automatically) during program initialization) which only stores its own id in SHELL.

STXREVISIONThe shell variable STXREVISION contains the Subversion repository revision number of the running STx version.

XRCXRC := system return code

The value returned by the system when the command SYSTEM is called.