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. You can use shell variables yourself when programming. The following shell variables have predefined uses:

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 sound file

The name (full path) of the current, i.e. active sound file 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 sound file is active.

CSFH, properties of the current sound file

CSFH = srate channels samples code type mode

The parameters of the current/active sound file 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.

SCRIPTDIRECTORY, the directory of the running script

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

SCRIPTFILEPATH, the filename of the running script

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

SCRIPTMAINNAME, the running macro

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

SCRIPTREVISION, the creating STx version number

The 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.

SHELL, the executing and the calling shell

The variable SHELL is generated during the startup code execution of the shell called via the command SHELL. Its format is

thisshellid callershellid

with callershellid being the ID of the calling shell, and thisshellid being the ID of the new shell. 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.

STXREVISION, the executing STx version

The shell variable STXREVISION contains the Subversion repository revision number of the running STx version. This variable is only available in scripts.

XRC, the system return code

The value returned by the operating system when the command SYSTEM has been called.