Programmer Guide/Command Reference/SYSTEM: Difference between revisions

From STX Wiki
Jump to navigationJump to search
(initial import)
 
No edit summary
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==SYSTEM==
The {{STX}} <code>SYSTEM</code> family of commands executes Windows system commands. Their <code>SYSTEMCALL</code> variants work like their <code>SYSTEM</code> counterparts, except that they return warnings rather than errors on failure.


The <code>SYSTEM</code> commands allow you to execute Windows system commands. The <code>SYSTEMCALL</code> variants works their <code>SYSTEM</code> counterparts, except that they return warnings rather than errors on failure.
== <code>SYSTEM</code>: Open the Windows command interpreter ==


<code>SYSTEM</code>
SYSTEM


Start the windows command shell.
This will simply start the windows command interpreter.


<code>SYSTEM <var>command arguments</var></code>
== <code>SYSTEM</code>: Open a Windows program or a batch file ==


<code>SYSTEMCALL <var>command arguments</var></code>
SYSTEM <var>command</var> <var>arguments</var>
SYSTEMCALL <var>command</var> <var>arguments</var>


Execute a system command or program, and wait for the process. The (numeric) exit code of the program is stored in the shell variable <code>XRC</code>.
Execute a system command or a program, and wait for the process to finish. The numerical exit code of the program is stored in the shell variable <var>XRC</var>.


<code>SYSTEMX <var>command arguments</var></code>
SYSTEMX <var>command</var> <var>arguments</var>
SYSTEMCALLX <var>command</var> <var>arguments</var>


<code>SYSTEMCALLX <var>command arguments</var></code>
Start a system command or process in the background, without waiting for it to finish. The windows program ID of the started process is stored in the shell variable <var>XRC</var>, and {{STx}} shell execution will continue.


Start a system command or process, and continue shell execution (do not wait for process). The windows program id of the started process is stored in the shell variable <code>XRC</code>.
If the <code>SYSTEM</code> family of commands is applied to an executable(.EXE), the respective program is executed directly, i.e., without involving the Windows command interpreter.


If a program (.EXE) is executed, it is called directly without starting a windows shell. For the identification of the windows shell and for the program file search, the settings of the windows environment are used (COMSPEC, PATH, ...).
For the identification of the Windows command interpreter and for deciding where to look for the programm, the normal settings of the Windows environment are used (<var>COMSPEC</var>, <var>PATH</var>, and so on).


====HELP====
== <code>SYSTEM HELP</code>: Accessing HTML help files ==


<code>SYSTEM HELP <var>chmFile htmlTopic</var></code>
SYSTEM HELP <var>chmFile</var> <var>htmlTopic</var>


Open a topic in an HTML Help file using the Windows HtmlHelp API.
Using the Windows HtmlHelp API, {{Stx}} will open the topic <var>htmlTopic</var> of the HTML help file <var>chmFile</var>.


;<var>chmFile</var>
;<var>chmFile</var>
 
:The compiled HTML file (e.g. "<code>stx help.chm</code>")
:The compiled HTML file (e.g. '<code>stx help.chm</code>')
 
;<var>htmlTopic</var>
;<var>htmlTopic</var>
:The HTML topic to call (e.g. "<code>526.htm</code>").


:The HTML topic to call (e.g. '<code>526.htm</code>').
SYSTEM HELP CLOSE
 
<code>SYSTEM HELP CLOSE</code>


Close the HTML Help file, if it is open.
Close the HTML Help file if it is open.


<code>SYSTEM HELP INDEX <var>searchString</var> [ <var>helpFile</var> ]</code>
SYSTEM HELP INDEX <var>searchString</var> [ <var>helpFile</var> ]


Search the help index. Open up the specified help file, activating the index tab and insert the search string. If no help file is specified, the default S_TOOLS-STx help file is used (stored in <code>@HELPFILE</code>).
Search the help index. Open up the specified help file, activating the index tab and insert the search string. If no help file is specified, the default {{STX}} help file is used (as defined in <var>@HELPFILE</var>).


;<var>searchString</var>
;<var>searchString</var>
:The string to search for.
:The string to search for.
;<var>helpFile</var>
;<var>helpFile</var>
:The help file to search. If no help file is specified, the help file specified by the user in the {{STX}} Configuration Settings Dialog in the user settings is used.


:The help file to search. If no help file is specified, the help file specified by the user in the S_TOOLS-STx Configuration Settings Dialog in the user settings is used.
SYSTEM HELP KEYWORD <var>searchString</var> [ <var>helpFile</var> ]
 
<code>SYSTEM HELP KEYWORD <var>searchString</var> [ <var>helpFile</var> ]</code>
 
Search up the specified help file for a keyword matching the search string. If no help file is specified, the default STx help file is used ($@HELPFILE). You can search for multiple keywords by specifying separating them using a sem-colon (e.g. dataset;edit).


Note that <var>searchString</var> is still one argument (surround in quotes to be safe). Note also that the modular file containing the keyword is opened, rather than the master file.
Search the specified help file for a keyword matching the search string. If no help file is specified, the default {{STx}} help file is used (as defined in <var>@HELPFILE</var>). You may search for multiple keywords by separating them with semicolons (e.g. "<code>dataset;edit</code>"). Note that even in this case, <var>searchString</var> must still be a single argument (use quotation to be safe). Note also that the modular file containing the keyword is opened, rather than the master file.


;<var>searchString</var>
;<var>searchString</var>
:The string to search for.
:The string to search for.


;<var>helpFile</var>
;<var>helpFile</var>
:The help file to search. If no help file is provided, the help file specified by the user in the {{Stx}} "Configuration Settings" dialog in the User settings is used.


:The help file to search. If no help file is specified, the help file specified by the user in the S_TOOLS-STx Configuration Settings Dialog in the user settings is used.
SYSTEM HELP SEARCH <var>searchString</var> [ <var>helpFile</var> ]
 
Open up the specified help file, activating the search tab and inserting the search string. Note that the search does not take place. Press return to search. If no help file is specified, the default {{STX}} help file is used (stored in <var>@HELPFILE</var>).
<code>SYSTEM HELP SEARCH <var>searchString</var> [ <var>helpFile</var> ]</code>
 
Open up the specified help file, activating the search tab and inserting the search string. Note that the search does not take place. Press return to search. If no help file is specified, the default S_TOOLS-STx help file is used (stored in <code>@HELPFILE</code>).


;<var>searchString</var>
;<var>searchString</var>
:The string to search for.
:The string to search for.
;<var>helpFile</var>
;<var>helpFile</var>
:The help file to search. If no help file is specified, the help file specified by the user in the {{STX}} Configuration Settings Dialog in the user settings is used.


:The help file to search. If no help file is specified, the help file specified by the user in the S_TOOLS-STx Configuration Settings Dialog in the user settings is used.
== <code>SYSTEM MKDIR</code>: create a directory ==
 
SYSTEM MKDIR <var>directoryPath</var>
====MKDIR====


<code>SYSTEM MKDIR <var>directoryPath</var></code>
Creates the directory specified by <var>directoryPath</var>. If <var>directoryPath</var> is relative, it is relative to the <var>@WORK</var> directory. If other directories in <var>directoryPath</var> do not exist, they are all created.


Creates the directory specified by <var>directoryPath</var>. If <var>directoryPath</var> is relative, it is relative to the <code>@WORK</code> directory. If multiple directories in <var>directoryPath</var> do not exist, they are all created.
Note that you can use a [[Shell_Items/File_Item/Introducing_File_Items|shell file item]] to check whether a directory exists.


Note that you can use the shell <code>FILE</code> item to check whether a directory exists.
You may retrieve the present working directory with the {{Stx}} command [[Programmer_Guide/Command_Reference/PWD|<code>PWD</code>]].
You can retrieve the present working directory with the command <code>PWD</code>.<pre>
system mkdir '\\server1\public\data\output\$#var'
system mkdir '\\server1\public\data\output\$#var'
system mkdir 'd:\data\output\$#var'
system mkdir 'd:\data\output\$#var'
system mkdir 'output\$#var'
system mkdir 'output\$#var'
</pre>
====OPEN====


<code>SYSTEM OPEN <var>doc</var></code>
== <code>SYSTEM OPEN</code>: Open a document ==
SYSTEM OPEN <var>doc</var>


Use the registered windows application to open the file/document <var>doc</var>. This command is useful to open text document with the right text processor or to display HTML pages with the default browser application.
Use the registered windows application to open the file/document <var>doc</var>. This command is useful to open text document with the right text processor or to display HTML pages with the default browser application.


<code>SYSTEM OPEN <var>app doc</var></code>
SYSTEM OPEN <var>app</var> <var>doc</var>


Use the specified windows application <var>app</var> to open the file/document <var>doc</var>.
Use the specified windows application <var>app</var> to open the file/document <var>doc</var>.


Neither type of <code>OPEN</code> subcommands waits for the Windows application. The macro execution continues after the command has been sent to the Windows system.
Neither type of <code>OPEN</code> subcommands waits for the Windows application to finish. So macro execution continues right after the command has been submitted to the Windows system.
The <code>OPEN</code> subcommand can also be used to send e-mails (SYSTEM OPEN 'MAILTO:.....') or to jump to a bookmark on a HTML page (SYSTEM OPEN 'HTTP:...').
 
If there is an error using the <code>OPEN</code> subcommand (e.g. if no application is registered for the document type), the error is not processed internally and not returned to the macro!====RMDIR====
The <code>OPEN</code> subcommand can also be used to send e-mails (<code>SYSTEM OPEN 'MAILTO:&hellip;'</code>) or to open a bookmark in an HTML page (<code>SYSTEM OPEN 'HTTP:&hellop;'</code>).
 
If there is an error using the <code>OPEN</code> subcommand (e.g. if no application is registered for the document type), the error will ''not'' be reported to {{STX}} nor, in turn, to the macro. This means that it is impossible for an {{Stx}} script to check if the document could be opened.
 
==<code>SYSTEM RMDIR</code>: Remove a directory==


<code>SYSTEM RMDIR <var>directoryPath</var></code>
SYSTEM RMDIR <var>directoryPath</var>


Removes the directory specified by <var>directoryPath</var>. Only the last directory is removed (e.g. if <var>directoryPath</var> is '<code>new1\new2</code>' then only the directory '<code>new2</code>' is removed.
Removes the directory specified by <var>directoryPath</var>. Only the last directory is removed (e.g. if <var>directoryPath</var> is '<code>new1\new2</code>' then only the directory '<code>new2</code>' is removed).

Latest revision as of 09:13, 22 October 2018

The STx SYSTEM family of commands executes Windows system commands. Their SYSTEMCALL variants work like their SYSTEM counterparts, except that they return warnings rather than errors on failure.

SYSTEM: Open the Windows command interpreter

SYSTEM

This will simply start the windows command interpreter.

SYSTEM: Open a Windows program or a batch file

SYSTEM command arguments
SYSTEMCALL command arguments

Execute a system command or a program, and wait for the process to finish. The numerical exit code of the program is stored in the shell variable XRC. 

SYSTEMX command arguments
SYSTEMCALLX command arguments

Start a system command or process in the background, without waiting for it to finish. The windows program ID of the started process is stored in the shell variable XRC, and STx shell execution will continue.

If the SYSTEM family of commands is applied to an executable(.EXE), the respective program is executed directly, i.e., without involving the Windows command interpreter.

For the identification of the Windows command interpreter and for deciding where to look for the programm, the normal settings of the Windows environment are used (COMSPEC, PATH, and so on).

SYSTEM HELP: Accessing HTML help files

SYSTEM HELP chmFile htmlTopic

Using the Windows HtmlHelp API, STx will open the topic htmlTopic of the HTML help file chmFile.

chmFile
The compiled HTML file (e.g. "stx help.chm")
htmlTopic
The HTML topic to call (e.g. "526.htm").
SYSTEM HELP CLOSE

Close the HTML Help file if it is open. 

SYSTEM HELP INDEX searchString [ helpFile ]

Search the help index. Open up the specified help file, activating the index tab and insert the search string. If no help file is specified, the default STx help file is used (as defined in @HELPFILE).

searchString
The string to search for.
helpFile
The help file to search. If no help file is specified, the help file specified by the user in the STx Configuration Settings Dialog in the user settings is used.
SYSTEM HELP KEYWORD searchString [ helpFile ]

Search the specified help file for a keyword matching the search string. If no help file is specified, the default STx help file is used (as defined in @HELPFILE). You may search for multiple keywords by separating them with semicolons (e.g. "dataset;edit"). Note that even in this case, searchString must still be a single argument (use quotation to be safe). Note also that the modular file containing the keyword is opened, rather than the master file.

searchString
The string to search for.
helpFile
The help file to search. If no help file is provided, the help file specified by the user in the STx "Configuration Settings" dialog in the User settings is used.
SYSTEM HELP SEARCH searchString [ helpFile ]

Open up the specified help file, activating the search tab and inserting the search string. Note that the search does not take place. Press return to search. If no help file is specified, the default STx help file is used (stored in @HELPFILE).

searchString
The string to search for.
helpFile
The help file to search. If no help file is specified, the help file specified by the user in the STx Configuration Settings Dialog in the user settings is used.

SYSTEM MKDIR: create a directory

SYSTEM MKDIR directoryPath

Creates the directory specified by directoryPath. If directoryPath is relative, it is relative to the @WORK directory. If other directories in directoryPath do not exist, they are all created.

Note that you can use a shell file item to check whether a directory exists.

You may retrieve the present working directory with the STx command PWD. 

system mkdir '\\server1\public\data\output\$#var'
system mkdir 'd:\data\output\$#var'
system mkdir 'output\$#var'

SYSTEM OPEN: Open a document

SYSTEM OPEN doc

Use the registered windows application to open the file/document doc. This command is useful to open text document with the right text processor or to display HTML pages with the default browser application. 

SYSTEM OPEN app doc

Use the specified windows application app to open the file/document doc.

Neither type of OPEN subcommands waits for the Windows application to finish. So macro execution continues right after the command has been submitted to the Windows system.

The OPEN subcommand can also be used to send e-mails (SYSTEM OPEN 'MAILTO:…') or to open a bookmark in an HTML page (SYSTEM OPEN 'HTTP:&hellop;').

If there is an error using the OPEN subcommand (e.g. if no application is registered for the document type), the error will not be reported to STx nor, in turn, to the macro. This means that it is impossible for an STx script to check if the document could be opened.

SYSTEM RMDIR: Remove a directory

SYSTEM RMDIR directoryPath

Removes the directory specified by directoryPath. Only the last directory is removed (e.g. if directoryPath is 'new1\new2' then only the directory 'new2' is removed).

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Command_Reference/SYSTEM&oldid=10216"

Navigation menu

Personal tools