Variables which do not begin with
& (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:
- 1 APPMODE, the application run-mode
- 2 APPNAME, the application name
- 3 CSF, the name of the current sound file
- 4 CSFH, properties of the current sound file
- 5 EMSG, the current error message string
- 6 PARENT, the parent window
- 7 RC, the return code
- 8 RESULT, the macro result
- 9 SCRIPTDIRECTORY, the directory of the running script
- 10 SCRIPTFILEPATH, the filename of the running script
- 11 SCRIPTMAINNAME, the running macro
- 12 SCRIPTREVISION, the creating STx version number
- 13 SHELL, the executing and the calling shell
- 14 STXREVISION, the executing STx version
- 15 XRC, the system return code
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
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
GETMESSAGEinto 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
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.