Programmer Guide/General Descriptions/Shell Environment

Shell Environment (first character not equal to @, # or &)

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

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

APPNAMEAPPNAME = applicationname

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.

CSFCSF = currentsoundfilename

CSFH = srate channels samples code type mode

The name (full path) of the current/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.

CSFHCSFH = 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.

EMSGEMSG = errortext

If an error occurs, the description text 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.

PARENTPARENT = 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.

RCRC = command_return_code

The last command's return code. See Return Codes for details.

RESULTRESULT = macro_result

The value returned by the previous macro. See Return Codes 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.