Updated February 2014; see History
xcall AMOS, cmd {,qflag, pflag, chainto}
AMOS allows a program to execute a command (e.g. DIR, LOG, COPY, etc.) or BASIC program (e.g. RUN XYZ) almost as if it were a subroutine. It is similar to HOSTEX except that instead of executing host operating system commands, which differ from one operating system to the next, it executes AMOS commands, which are emulated by A-Shell and behave identically among A-Shell's different platforms.
Parameters
cmd (String) [in]
A-Shell command to be executed
qflag (Any) [in] (Num)
If non-zero and non-blank (i.e. 1 or "Q"), it causes the subroutine to run "quietly"—i.e., generally invisibly.
pflag (Num) [in]
If 1, forces the subroutine to run as if the AMOSRUNSBR flag had been set. If pflag is 2, it forces the subroutine to run as if AMOS_RUNSBR had NOT been set.
Value (+4) allows the child RUN program to pass its updated command file status to the parent. There are two main consequences. The first is that any command file inputs that were absorbed by the child program will not be available to the parent. (This is almost always preferable.) The second is that any attempt by the child program to CHAIN will effectively pass the chain information back to the parent, so that when the parent ENDS, it will then execute the chain requested by the child. This may or may not be desirable, but it is the only way that an attempted CHAIN by the child will have any effect.
Value (+8) prevents the normal reset of the auto parent setting at the start of the called program. This makes it easier to launch programs designed to operate in the default or main window and instead force them to operate within a dialog created by the calling program.
Any other value causes the normal AMOS_RUNSBR setting as specified in miame.ini or SET.LIT command to prevail.
chainto (String)
May be specified (along with the +4 option in the pflag parameter) to return the command line that the child program attempted to chain to. The CHAIN operation is always trapped by XCALL AMOS, forcing the child to return to the parent; this feature allows the parent to effectively carry out the requested CHAIN operation via a subsequent XCALL AMOS call. Chainto is a string of sufficient length to retrieve the CHAIN statement argument. If the +4 option in pflag is not specified, or if the child program does not CHAIN, chainto will return "". Also note that this is only possible when the child executes in-process, so unless you have that option forced on globally, you should also specify the +1 option in pflag.
Operations
AMOS may work in one of three ways, depending on whether the SBR=AMOS_RUNSBR switch is set, and depending on the command line specified.
| • | If SBR=AMOS_RUNSBR is not set in miame.ini, or if the command does not begin with "RUN" or "ORUN", or the pflag parameter is specified as 2, then unless it is one of the special cases listed below, AMOS will spawn a new instance of A-Shell with the -e (exit-upon-completion) switch, forcing the new instance to execute the specified command. The calling instance of A-Shell is suspended until the second instance completes the command, as you would expect for a subroutine call. This is essentially the same as using HOSTEX and passing it a command line starting with "$ASHELL -e " (see Launching A-Shell with HOSTEX). Note that under Windows, any screen output within the subroutine will not affect the calling process, since they have separate screen windows, but under Unix, even though the subroutine executes as a separate process, it shares the screen device with the caller and thus any output by the subroutine will remain on the caller's screen—although the calling program will not be aware of it and its cursor will not be advanced as you might otherwise expect. |
| • | If the pflag parameter is set to 1, or if SBR=AMOS_RUNSBR is set and the command begins with "RUN" or "ORUN", then the command will be executed as a true subroutine within the current instance of A-Shell. The current program is suspended, as you would expect for a subroutine call, and a new memory partition is allocated for the subroutine, but it shares the calling job's process and job environment. Any screen output, and any changes to the job environment, such as the current ppn, will remain when the command completes and the subroutine returns. See the AMOS_RUNSBR switch for important information on limitations and tricks related to this switch. |
| • | If a second instance is going to be launched, then if the optional second argument is specified, an attempt is made to execute the second instance "quietly." Under A-Shell/Windows, this is accomplished by making the new instance run in minimized mode. Under Unix, it uses the –q startup switch. |
In most cases, the A-Shell implementation of AMOS will achieve the same result as the typical implementation under AMOS. Actually, there are several versions of this subroutine created and distributed by various parties in the AMOS community. But most if not all work by making the child instance run as if it were a subroutine called by the parent. If you do not set the AMOS_RUNSBR switch, or if the command cannot otherwise be run within the current process, then the fact of it running in a separate process can lead to some subtle differences in the outcome which may be significant to some applications. For example, if the purpose of the child process is to make some change to the job status (e.g. via the SET command) then any such change will be discarded when the subroutine returns if the subroutine ran in a separate process. Another example would be where the child process uses its job name to generate a file or key, assuming that its job name is the same as the parent.
To minimize the chance of misunderstanding, the A-Shell implementation of AMOS tries to be smart by looking at the command and deciding if it is possible or more desirable to execute that command in-process (as a true subroutine) rather than by launching a new process. Some examples of this are:
xcall AMOS,"LOG <dev:[p,pn]>"
Since this is clearly a case where the intent is to change the PPN of the calling job, A-Shell intercepts this and turns it into xcall LOG,"<dev:[p,pn]>."
xcall AMOS,"LOOK <fspec>"
This one could be handled as a separate process with little harm, but since the new process would just turn around and use xcall EZTYP,<fspec> (MicroSabio’s EZTYP utility being deemed the appropriate replacement for Micro Concept’s LOOK.LIT), it seems more efficient to just call it directly.
xcall AMOS,"VUE <fspec>"
The reasoning here is similar to that used above. Under A-Shell, VUE.LIT is actually just a front end to the VUE function which is embedded within the A-Shell executable, so it makes just as much sense to call that function within the current instance as it does to start a new one.
Comments
AMOS will launch the new instance of A-Shell (if necessary) using the same initialization file and executable command pathname with which the current instance was launched.
The child job can determine its parent jobname from the jobatt parameter of either GETJTB or PLYJOB.
The configuration file option switch, SBR=AMOSJOB1, will cause JOBNAM to return the name of the parent job rather than the child job.
Despite the name AMOS, you are still limited to executing commands that are recognized by and compatible with A-Shell. You cannot, for example, take AMOS machine language executables and execute them this way; the A-Shell LIT commands have been rewritten to emulate their AMOS counterparts, but have a completely different internal format.
History
2014 February, A-Shell version 6.1.1377: Add chainto
2014 February, A-Shell version 6.1.1374: Add pflag =8.
