User Guide/STX Console

The Console is a command line interface to an STx shell. It can be started from the Script Controller or the menu entry "Run > BScript" of the log window.

The Console can

1. process commands on a line by line basis
2. process multiple commands pasted from the clipboard
3. maintain a command history; you can use the up/down keys to navigate to commands and the tab key for command completion

The Console cannot

1. process STx control commands like IF, FOR, DO, WHILE, BREAK and CONTINUE

Special Commands implemented by the Console Application

CD → Get or Set the current working directory

CD [dir]

Set the current directory to dir and display the full path of the current directory. Without an argument, only the current directory is shown. result: the full path of the selected directory or an empty string if the command fails

CD /diropt

Set the current directory to the path selected by the option diropt:

• /Work : STx working directory
• /Root : STx program or installation directory
• /Script: default STx script directory
• /Dialog: select the current directory in a dialog

result: the full path of the selected directory or an empty string if the command fails or it was canceled

CLEAR → Clear console window or command history

CLEAR WINDOW

Clear the console window.

CLEAR STACK
CLEAR HISTORY

Clear the command history.

Notes

• The command CLS is an alias for CLEAR WINDOW
• The result of the command CLEAR is always an empty string

EXIT → Close the Console window

EXIT

Close the Console window. The command history and the console settings are saved automatically. The Console application is also terminated, if the command window can be closed with the mouse or a hotkey.

LOG → Write text into the console window

LOG textline1 [.. textlineN]

Write the arguments to the console window. If not option is specified, each argument is written to a separate line. The option /Append can be used, to place all arguments in one line.

Notes

• Normally LOG is not often used in the command line, because the result and the output of all commands is written to the console window anyway.

LS → Display a directory listing

LS [path1 [ .. [pathN]] [options]

Display a directory listing using the pathX arguments as a wildcard file/pathname mask.

Options

• /Recursive: recursive listing of all subdirectories
• /Long: use the long listing format to display file details, otherwise only the file name is listed
• /Path: display the full path name of files
• /Directories: list directories only
• /Files: list files only
• /More: stop listing every n and wait for user input (enter or escape)

Notes

• The command DIR is an alias for the LS

SETCON → Display or set Console parameter values

SETCON [parName]

Display all Console parameters (no parName given) or the parameter parName

SETCON parName parValue

Assign parValue to the Console parameter parName.

The following Console parameters are defined:

• stackSize: Set the maximum number of commands to be stored in the history. The parValue must be an integer number greater than 1.
• moreLines: Set the number of lines used as pagesize if the /More option is speciefied in a Console command. The parValue must be an integer number greater than 1.
• font: Assign a new console window font and/or change the fontsize. The parValue can define the new fontname (newname), the fontsize (:newsize) or both (newname:newsize). The fontname must be the name of an installed font and fontsize must be an integer number in the range 6 to 20. The new font is applied to the console window on the next start of the Console application.
• logMsg: Turn extended Console log messages on or off.

SHOW → Display attributes and data of any shell-item or variables

Note: The option /More can be applied to any SHOW command to stop the output after every moreLines lines (see SETCON).

SHOW STACK
SHOW HISTORY

List the command history.

SHOW SHELLS

List the shell-id and application name of all running [[Programmer_Guide/Introduction#Shell|Template:STX shells].

SHOW SOUNDFILES [/Long /Summary]

Display a list of all currently loaded soundfiles.

• /Summary: show only the number of loaded soundfiles
• /Long: display details also, not only the soundfile path

SHOW [itemtype] [/Summary]

Display the names of all shell items (no argument) or of shell items of the specified itemtype.

• /Summary: show only the number of shell items per displayed itemtype

SHOW MACROCODES [mask] [/Summary /Long /Noclass]
SHOW SPUCODES [mask] [/Summary /Long]
SHOW CLASSES [mask] [/Summary /Long]

List the names of all loaded macros, classes or spu's. If the argument mask is specified, only the matching names are listed. In the long list format of classes the class-name and the parent-class is displayed.

• /Summary: display only the number of macros / spu's.
• /Long: use the long list format
• /Noclass: hide macros defining a class

SHOW VARIABLES [mask] [/Global|Shell|User /Invert]

List the names of all variables defined in the selected environment. If the argument mask is specified, only the matching names are listed.

• /Global: global variables (visible anywhere in STx)
• /Shell: shell variables defined and used by the console script
• /User: shell variables defined and used by the user during the console session
• /Invert: inverts the meaning of the argument mask; display not matching variables names.
• Note: use the normal STx syntax $varname to use a variable in a console command.

SHOW pathname /Textfile|Xmlfile [/Dialog]

Write the content of the textfile or xmlfile pathname to the console window or display it in a separate window if the option /Dialog is supplied.

SHOW itemname /Attributes

Display a list of all defined attributes of the item itemname.

SHOW tableitem [/Definitions]

List the defintions of all fields of the table tableitem.

SHOW item [/Dialog]

Display the content (data) or attributes (if no data available) of the specified item. If the option /Dialog is specified, the item data are displayed in a separate window.

Options for differnt item types:

• /Tagged: list tagged entries of table item only
• /Format': set numeric list format (for table and value)
• /NRow=r1,r2: rows to be listed (for table and value)
• /NCol=c1,c2: columns to be listed (for table and value)

STS → Load, run and debug scripts

STS sarg [arguments]

Load the specified script file and run the selected macro. The macro is executed in the script environment of the Console. When the called macro is finished, the script file is unloaded and the return value of the macro is displayed in the Console window and can be assigned to a variable.

STS sarg [arguments] /Run
STS sarg [arguments] /Run=Debug
STS sarg [arguments] /Run=Test

Start a new script runtime environment to load the specified script file and to execute (/Run), debug (/Run=Debug) or test the syntax (/Run=Test) of the selected macro.

STS sarg /List

Display a list of all sections defined in the specified script file.

STX sarg /Load
STX sarg /Unload

Load or unload all source code sections (macros, classes and spu's) defined in the specified script file.

The argument sarg selects the script file and the macro and has the following formats:
# filename → use the script file filename and the macro filename (without directory and extension)
# filename::macroname → use the script file filename and the macro macroname.

Script file search order (filename = the specified script file name)

1. filename and filename.sts
2. stx-working-dir\filename and stx-working-dir\filename.sts
3. stx-script-directory\filename stx-script-directory\filename.sts

• stx-working-dir = the STx working directory; it can be assigned in the workspace and is stored in the global variable @WORK
• stx-script-directory = subdirectory scripts of the STx program directory; the program directory is assigned during the installation and stored in the global variable @ROOT

STX → Start an STx application

STX appname [appargs]

This command is an alias for PostMessage Master AppRun appname [appargs], which is used to start the STx application appname via the STx master shell. Applications must be defined in the configuration file and can only be started via the master shell.

USE → Load a console extension package

USE sarg

Load the specified script package and activate it. The argument sarg has the same format as for the Console command STS.

A script package is normally used to implement a set of console commands for a special application. The source file of a package must define a main macro packmain which is used to activate (packmain begin) and deactivate (packmain end) the package. The activation and deactivation of a package can be used to initialize constants and data structure at the begin and to cleanup items and data structures at the end.

If the package was already activated by a previous USE sarg command, the package is first deactivated (calling macro packmain end) and unloaded, before it is loaded and activated again.

Note: The macro packmain must return 0 for success (USE continous) and any other value to stop the execution of USE.

See also

Programmer_Guide