Programmer Guide/General Descriptions/Shell Environment: Difference between revisions
| (21 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:{{SUBPAGENAME}}}} | {{DISPLAYTITLE:{{SUBPAGENAME}}}} | ||
Variables which do not begin with <code>@</code>, <code>#</code> or <code>&</code> (i.e. all variables beginning with an alphanumeric character) are so-called shell environment variables. | {{Shell}} | ||
Variables which do not begin with <code>@</code>, <code>#</code> or <code>&</code> (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: | |||
== <var>APPMODE</var>, the application run-mode == | == <var>APPMODE</var>, the application run-mode == | ||
| Line 12: | Line 13: | ||
Applications started via <code>APPMAIN</code> must never use <code>EXIT 0</code> to terminate the shell. They must return to <code>APPMAIN</code> (using a normal <code>EXIT 1</code> command from the main macro) which performs some clean-up functions before the shell is terminated. | Applications started via <code>APPMAIN</code> must never use <code>EXIT 0</code> to terminate the shell. They must return to <code>APPMAIN</code> (using a normal <code>EXIT 1</code> command from the main macro) which performs some clean-up functions before the shell is terminated. | ||
== <var>CSF</var>, the name of the current | == <var>CSF</var>, the name of the current sound file == | ||
The name (full path) of the current, i.e. active | The name (full path) of the current, i.e. active sound file is assigned to the variable <var>CSF</var> when a <code>LOAD</code> (open) or <code>UNLOAD</code> (close) command is executed. If <var>CSF</var> is not set (i.e. empty), no sound file is active. | ||
== <var>CSFH</var>, properties of the current | == <var>CSFH</var>, properties of the current sound file == | ||
<var>CSFH</var> = srate</var> <var>channels</var> <var>samples</var> <var>code</var> <var>type</var> <var>mode</var> | <var>CSFH</var> = <var>srate</var> <var>channels</var> <var>samples</var> <var>code</var> <var>type</var> <var>mode</var> | ||
The parameters of the current/active | The parameters of the current/active sound file are assigned to the variable <code>CSFH</code> when a <code>LOAD</code> (open) or <code>UNLOAD</code> (close) command is executed. | ||
== <var>EMSG</var>, the current error message string == | == <var>EMSG</var>, the current error message string == | ||
| Line 47: | Line 48: | ||
The value returned by the previous macro. See [[Programmer_Guide/General_Descriptions/Return_Codes#RESULT|Macro Results]] for details. | The value returned by the previous macro. See [[Programmer_Guide/General_Descriptions/Return_Codes#RESULT|Macro Results]] for details. | ||
== <var>SCRIPTDIRECTORY</var> == | == <var>SCRIPTDIRECTORY</var>, the directory of the running script == | ||
The shell variable < | The shell variable <var>SCRIPTDIRECTORY</var> is available when an {{STX}} script (*.sts) is running. It contains the directory path where the running script file is stored. | ||
== <var>SCRIPTFILEPATH</var> == | == <var>SCRIPTFILEPATH</var>, the filename of the running script == | ||
The shell variable < | The shell variable <var>SCRIPTFILEPATH</var> is available when an {{STX}} script (*.sts) is running. It contains the name of the running script file including the path. | ||
==<var>SCRIPTMAINNAME</var> == | ==<var>SCRIPTMAINNAME</var>, the running macro == | ||
The shell variable < | The shell variable <var>SCRIPTMAINNAME</var> is available when an {{STX}} script (*.sts) is running. It contains the name of the running macro. | ||
== <var>SCRIPTREVISION</var> == | == <var>SCRIPTREVISION</var>, the creating {{STX}} version number == | ||
The shell variable < | The shell variable <var>SCRIPTREVISION</var> 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. | ||
== <var>SHELL</var> == | == <var>SHELL</var>, the executing and the calling shell == | ||
The variable < | The variable <var>SHELL</var> is generated during the startup code execution of the shell called via the command [[Programmer_Guide/Command_Reference/SHELL|<code>SHELL</code>]]. Its format is | ||
<var>thisshellid</var> <var>callershellid</var> | |||
The shell variable < | with <var>callershellid</var> being the ID of the calling shell, and <var>thisshellid</var> 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 <var>SHELL</var>. | ||
== <var>STXREVISION</var>, the executing {{STx}} version == | |||
The shell variable <var>STXREVISION</var> contains the Subversion repository revision number of the running {{STX}} version. This variable is only available in scripts. | |||
== <var>XRC</var>, the system return code == | == <var>XRC</var>, the system return code == | ||
Latest revision as of 12:18, 24 October 2019
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:
Contents
- 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
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
GETMESSAGEinto the messageSHELL 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.
