A-Shell Reference

Rewritten April 2024

HOST {{switches} cmd {modifier}}

HOST is a special command used to either exit A-Shell entirely (if no arguments specified), or to temporarily reach outside it execute a command or program in the outside world—i.e. the parent shell or native operating system environment.

Parameters

switches

cmd

A command or command line recognizable in the environment that A-Shell was launched from.

HOST /s /o du /vm"

If the command itself starts with "/s" or "/o" then you must quote the first token of the command in order to avoid confusion with the switches, e.g.

HOST /o "/o/mycmd" arg2 arg 2

modifer

An optional single character appended to the end of the command line (separated by a space) which affects the way the command is executed. See Command Modifiers.

Comments

When HOST is used to exit A-Shell entirely (i.e. with no arguments), if the subroutine OPR:HOST.SBX exists, it will be XCALLed prior to the session terminating. (This provides a way for applications to perform cleanup, log statistics, etc.)

Example 1:  interactive host command

The following UNIX example will launch the vi editor to edit the miame.ini file :

.host vi "/vm/miame/miame.ini"

This will take over your terminal until the vi session is exited. At that point control returns back to A-Shell, but you'll need to clear the screen to get rid of the characters left behind by vi (which the A-Shell screen tracking system won't know anything about).

Example 2:  redirecting host command to a file

This UNIX example generates a process list, filters it to just those lines executing ashell, sends the output to the file ps.lst and the uses the A-Shell EZTYP command to display it.

.HOST ps -ef | grep ashell > ps.lst

.eztyp ps.lst

 

Example 2:  launching a command in background

By adding the '&' command modifier (in the UNIX environment), the specified command will run as a child in background, returning control immediately to the A-Shell session, e.g.

.host "rsync -a /opt/filename.zip /tmp/" >x.lst 2>&1 &

Example 3:  launching the Windows Command Prompt

.host "cmd $"

In the above example, the '$' command modifier causes control to return to A-Shell immediately, even though the Windows Command Prompt remains open. This is particularly useful for launching a special Windows program that works in parallel with A-Shell (such as messaging app, stock ticker, etc.)

See Also

 

 

========================

HOST is a special A-Shell command program. It exits the A-Shell command shell and returns to either the host operating system command level or host batch or shell-script file which was used to invoke A-Shell.

Switches

 

The optional modifiers are same as can be used with Xcall HOSTEX.

Comments

If a native OS command sequence is piped into A-Shell (that is if the standard input file has been redirected), for example with the following Unix command:

$ echo "time" | ashell

then the command sequence will be executed automatically, and once the end of the standard input file is reached, control will return automatically to the host command level. In this case, at no point does A-Shell produce a command prompt, though it is possible to use the HOST command from within a command file to terminate the execution of the command sequence prematurely.

The HOST command may also be used to perform a host machine function from within A-Shell without exiting, by specifying the command as a parameter. For example:

.host vi $0

may be used within a .DO file on a Unix machine to invoke the Unix editor vi. (You will then understand why A-Shell contains an implementation of VUE...)

TRACKER (which controls the screen output within A-Shell) is not able to monitor any output that occurs outside of A-Shell and thus it is a good idea to resynchronize the display after using a HOST command (by clearing the screen, for example).

Yet another use for the HOST command is to execute a host operating system function and redirect the output to a file, which is available for access from within A-Shell. For example, the following commands will create a detailed process status list in the file ps.lst, which is then displayed using the A-Shell EZTYP.LIT utility. This technique avoids the terminal handling problems (alluded to above) which are otherwise bothersome when trying to shell out to host operating system functions which do not know anything about the A-Shell display environment.

.host ps –ef > ps.lst

.eztyp ps.lst

 

Notes

.HOST /s "/s/abcd" 

History

2016 November, A-Shell 6.3.1534, HOST.LIT 2.0(106):  reduces minimum partition memory requirement from about 265K to 3K and increases the maximum output capture buffer size (when using /O) from 256K to 512K. Note that the total memory requirement when using /O has actually increased rather than decreased, but it is only required when using /O and in that case it is dynamically allocated outside the memory partition.

2011 August, A-Shell 5.1.1227, HOST.LIT 2.0(105):  expands the maximum size of the buffer available to capture the output of the command from 64K to 256K and now appends a truncation warning message to it if the buffer fills up.

2011 August, A-Shell 5.1.1227, HOST.LIT 2.0(104):  is now smarter about sorting out possible confusion between switches and Unix filespecs, both of which can contain slashes. This allows unquoted commands, such as:

HOST /s/abcd

to continue to be treated as filespecs, as they were before the switches /S and /O were added in 2.0(103).

Note that the preferred way to prevent Unix filespecs or commands from being confused with switches is to enclose them in quotes. For example:

HOST /s "/s/abcd"

In the above command line, the /s following HOST will be treated as a switch, while the "/s/abcd" will be treated as a command to execute.

2011 July, A-Shell 5.1.1222, HOST.LIT 2.0(103):  now supports a help display and two new options. Prior to this change, HOST was used without switches.

2007 April, A-Shell 4.9.986, HOST.LIT 2.0(102):  supports the ability to plug in your own exit subroutine to be called when A-Shell exits via the HOST.LIT command. HOST.LIT now looks for OPR:HOST.SBX, and if it is found, it loads it and calls it before exiting. (Since the OPR: account is not in the normal SBX search path, this feature should not conflict with any existing HOST.SBX routines that may exist.) If the OPR:HOST.SBX is not found, HOST just exits in the normal way.