HOSTEX

Parameters

cmd  (String)  [in]

valid command line for the current host operating system, with an optional suffix; see Command Modifiers and Launching A-Shell with HOSTEX.

status  (Signed Num)  [out]

is an optional return variable. If specified, it will return the exit value of the command, if any. (Zero generally means success; anything else would be considered an error, but the interpretation of the error is dependent on the command executed.)

stdout  (String)  [out]

an optional parameter, used only with UNIX, that may be specified to receive the stdout of the specified command. For example:

MAP1 STDOUT$,S,2048

MAP1 STS,F

 

xcall HOSTEX,"uname -a",STS,STDOUT

This would capture the output of the "uname -a" command into the variable STDOUT.

It also works with multi-line output, e.g.:

xcall HOSTEX,"ls -l",STS,STDOUT

In this case, the individual lines of output will be delimited within the variable (STDOUT) using the standard UNIX line delimiter (ASCII 10).

Note that this technique is really only reliable with "regular commands", especially shell commands. If you execute an arbitrary executable, there is no telling whether it will generate stdout in a fashion compatible with this scheme.

Note also that dynamic (variable-length) strings are not supported for this parameter. Any output that exceeds the physical length of the parameter will be discarded.

 

Comments

Under UNIX, a new process is forked to execute the command as a child process to the current process, but by default the child process uses the same screen console as the parent. If you do not want the output of the child process to disturb the current screen, you can redirect its output to a file (as in the example above). You may also want to redirect the stderr channel to a file as well, as in this example which searches for the string "abcd" in all the .prt files in the current directory, writing its output and any error messages to grep.lst:

xcall HOSTEX, "grep abcd *.prt > grep.lst 2>&1"

If you want to get the output of the executed command on the current screen, then beware that A-Shell will not know what has been displayed there, and thus the cursor will be out of sync with the display. One way around this is to redirect the output to a file, then read the file back in and use PRINT statements to output it in the context of A-Shell. For example, PWD.LIT uses this technique to print the current working directory:

xcall HOSTEX, "pwd > pwd.lst"

Open #1, "pwd.lst", input

Input line #1, PLINE

Print PLINE

Close #1

 

Another technique which might be appropriate for some kinds of interactive commands would be to save the current screen, clear it, execute the new command, then restore the original screen, for example:

PRINT TAB(-1,202); TAB(-1,0);      ! save screen & clear it

xcall HOSTEX, CMD$

PRINT TAB(-1,0);TAB(-1,203);       ! clear and then restore it

 

For commands that generate simple teletype-style text output, the easiest and cleanest method for capturing the output is to use the stdout parameter which, when specified, automatically captures the stdout output into the specified variable. You can append the 2>&1 redirection modifier to the command to also redirect the stderr output there as well.

Under A-Shell/Windows, HOSTEX executes both Windows and certain DOS-legacy (also known as "console mode") commands (for which an EXE exists). This will create a new Windows process which will run in its own window (without disturbing the current window, other than perhaps to cover it up).

+Note that for later versions of Windows, you can use the CMD.EXE (command executor) to execute any console commands, for example:

 

xcall HOSTEX, "cmd.exe /c pwd > pwd.lst"

Use cmd /? from the Windows command prompt to see all of the switches and options available. See the discussion "Executing Windows command-prompt commands" on the A-Shell forum for related information.

Note that in the ATSD environment, you cannot launch a child session on the server unless it runs only in background—i.e. you must use the "&" Command Modifier. Even then, processes that require a Windows GUI context may fail to execute since ATSD is purely a background session (the GUI is on the ATE client side). In the ATE environment, regardless of the server operating system, you may choose to execute a command on the client computer via one of the following techniques:

•   AG_WINEXEC

•   MX_SHELLEX

•   Call SBX as a Function

See Also

•   HOST.LIT

•   XSHLEX.SBX

 

History

2012 November, A-Shell 6.0.1263:  Remove command line length limit of 512, now unlimited.

2010 May, A-Shell 5.1.1182:  HOSTEX.SBR bug fix: Passing a "-g <icon>" clause on a "$ASHELL" command line (to launch a child session of A-Shell) was not working if the parent was launched with a "-g <icon>" switch. (It was reverting to the default acorn icon.)

2008 September, A-Shell 5.1.1124:  Optional third parameter (stdout) added (UNIX only).

2006 May, A-Shell 4.9.956:  xcall HOSTEX,"$ASHELL..." now replicates more switches from the parent to the child:

•   -o <settings file>

•   -nm

•   -m, -mx (provided no -m or -mx is specified in subroutine command line)

•   -z, -zt, -zi (provided no -z, -zt, or -zi is specified in subroutine command line)