SUBMIT.SBR

Revised/reviewed June 2020

xcall SUBMIT, pid, stdin, stdout, stderr, executable, arg1, arg2 {,...argn}

(UNIX only) SUBMIT.SBR allows you to execute an arbitrary command (executable and arguments) as a child process of the current A-Shell process. It is similar to HOSTEX, but implemented using the lower level fork() / exec() sequence, rather than the higher level system() call used by HOSTEX. The lower level implementation provides some additional flexibility, which is mainly of use to SUBMIT.LIT, and thus is primarily of interest as an internal routine.

Parameters

Parameter	Type	I/O	Description
pid	Num	out	Returns the process id number (pid) of the child process created to run the command. (Note that such pids can be larger than 64K in most modern UNIX implementation, thus B,2 is not a good choice.)
stdin	String	in	Must specify the filespec (AMOS-style or native) of a file containing the input to be forced to the process (aka the "control file"). This is typically similar to a CMD file, but may contain raw keyboard characters as well as commands, and should start with a LOG command.
stdout, stderr	String	in	Must specify the filespecs of files to which the standard and error output of the process will be sent. To mimic the AMOS log file behavior, set them both to the same name (typically with an extension of LOG and a base name either matching the control file or the job name).
executable	String		Filespec of an executable which the child process will be forced to run. (In the case of SUBMIT.LIT, this is always "ashell", but could in theory be anything.) Normal operating system search path rules apply if the filespec doesn't specify a path.
arg1, arg2, ... argn	String	in	Optional arguments used to specify additional switches. Note that each switch must be expressed as two consecutive arguments. The first identifies the switch (see SUBMIT.LIT), except using a leading dash rather than slash, and with the switch identifier in lower case. The second contains the switch value. Use quotes around any switch value containing embedded spaces. See the example below.

Example

xcall SUBMIT, PID, "CMD:TEST.CTL", "TEST.LOG", "TEST.LOG", "ashell", "-i", "/vm/miame/miame.ini", "-j", "TSTJOB"

Comments

SUBMIT.SBR is used by SUBMIT.LIT, but only in the UNIX environment, and only for certain combinations of switches. For example, the /NEXT and /AFTER switches do not result in SUBMIT.SBR calls, and those switches would be invalid arguments to XCALL SUBMIT. Similarly, the SUBMIT.LIT switches used for queries or displays are handled independently within SUBMIT.LIT. To examine the relationship between SUBMIT.LIT and SUBMIT.SBR, you can set the TRACE Option (https://www.microsabio.net/dist/doc/conref/00ashref.htm#!traceoptions.htm) XCALL to log the subroutine operations within SUBMIT.LIT to the ASHLOG file.

Child processes launched via SUBMIt.sbr are generally dependent on the parent process to continue running for the duration of the child process. To launch a child/background process independent of the current process, use SUBMIT.LIT with the /NEXT: or /AFTER: switch, or set the SUBMIT2 system parameter.