# SUBMIT

> [HTML Version](submit_lit.htm)

_Revised and reviewed, July 2020_

To submit a task:

**SUBMIT ctlfile \{do-params\} \{switches\}**

To kill a task:

**SUBMIT /K seqno | pidno | jobno**

To list tasks submitted by this job that are currently running:

**SUBMIT**

SUBMIT accepts the command line argument _++fspec_, for which see History, below.

The A-Shell SUBMIT command causes a new process to be launched, either now or at a specified later time, which executes commands specified in the control file. Under AMOS, this is managed by a background job called the Task Manager. Under A-Shell, there are actually three different possibilities, depending on the operating system and whether the _/after_ and _/next_ switches are used:

**(./images/hmtoggle_plus0.gif)	Windows**

Here, SUBMIT only partially simulates the Task Manager by launching a new instance of A-Shell to run the specified task. This is acceptable for tasks which have explicit outputs or side effects (for example, a report or series of COPY commands), but it does not really run in "background", and there is no log file. In the Windows environment, if you want to schedule a task that is launched by the operating system at the specified time, you should just use the Windows Task Scheduler (Programs...Accessories...System Tools...Scheduled Tasks).



**(./images/hmtoggle_plus0.gif)	UNIX Immediate**

In the case of A-Shell/Unix without the _/after_ or _/next_ switches, A-Shell launches a new process to run the specified task as a child of the current process. However, unlike the Windows case, the new process does run in background, with all of its screen output being written to the log file (e.g. a file with the same name and location as the _ctlfile_, but with a LOG extension.) If the parent exits before the child does, the child task will continue to run but will be marked as a zombie. 

In the above case, if there is an error during the attempt to launch the new instance of A-Shell (perhaps because the ashell executable is not in the PATH or the MIAME environment variable is not defined), then information about the error will be written to the standard A-Shell log file (ashlog.log, in the directory where miame.ini is located).



**(./images/hmtoggle_plus0.gif)	UNIX Via Schedule**

The case of A-Shell/Unix with the _/after_ or _/next_ switches is the most similar to the AMOS Task Manager. The task is submitted to the Unix **at** manager, which, like the AMOS Task Manager, keeps track of it in a queue until it launches it at the specified time. The process will run with the same login identity and environment as the process that submits it, but since it runs as a child to the **at** manager, it is independent of the original submitter and thus not subject to becoming a zombie. As in the prior case, all output that would otherwise have gone to the screen is sent to the log file instead.

The **at** manager is similar to the more familiar **cron** manager, both of which can be found on almost any Unix system. The **cron** manager is more suited to tasks that are to be run at regularly scheduled intervals; you submit jobs to it via the **crontab** command. The** at** manager, on the other hand, is more suited to jobs that are to be run once at a specified time in the (immediate or distant) future. To submit jobs to be run by the** at **manager, you can use the Unix **at** command. SUBMIT.LIT just acts as a front-end to **at **to allow you to use the simpler AMOS command syntax. 



In all cases, SUBMIT requires a control file (typically with a .ctl extension) which functions more or less just like a command or DO file—i.e. containing the commands necessary to run the job, along with any keyboard inputs. Programs running under the control of SUBMIT will automatically take their input from the control file, even if they wouldn’t normally accept input from a command file. The _do file parameters_ are processed in the same way as the argument list to a DO file; see [DO File Arguments](dofilearguments.htm.md) for details. When the control file runs out of input, the process terminates. The preferred way to terminate the process is for the program to cleanly exit back to the control file, and for the control file to end, optionally with a LOGOFF command. See the [SBR option SUBMIT2](submit2.htm.md) for related information.

**Switches**

| **Switch** | **Effect** |
|------|------|
| <no switches> | Display list of jobs launched or scheduled via SUBMIT. |
| Do file parameter | Unlike the AMOS implementation, the A-Shell version of SUBMIT allows DO file parameters to be passed to the control file (which can use the \$0-\$9 syntax, just like normal DO files, to represent the formal parameters). Any space-delimited tokens following the control file name and preceding the first switch (marked by a slash) will be passed to the control file as DO parameters. |
| /AFTER:\{+\}timspc | (Unix only) Causes the control file to be submitted via the Unix ‘at’ background processor, instead of as a child to the current job. (See note above about the ‘at’ processor.) The timspc argument may be specified using the form M-D-Y\{,HH:MM\}. The M-D-Y portion must be specified simply as zero for today. The optional \{+\} makes the time specification relative to now. Examples:<br>     /AFTER:0,23:00  (11 PM tonight)<br>     /AFTER:06-30-20,00:30  (12:30 AM on June 30, 2020)<br>     /AFTER:+1-0-0 (one month from now). |
| /BA buffile | Activates the auto-snapshot feature of INFLD and appends each snapshot to the specified file. The default file extension is BUF, and the default location is MEM0:\[1,1\] (if it exists) or the current login directory where the first snapshot occurs. Works internally by passing the –ba <buffile> switch to the child A-Shell process and by adding the **|S** _type_ code to the INFDEF (default INFLD parameter) string. |
| /BC buffile | Same as the /BA option except creates a new snapshot buffer file (overwriting any existing one). |
| /CU | Will display the group for each job, if applicable. Requires A-Shell 6.4.1540 or greater, and use of group licensing. |
| /I "inifile" | Forces the child process to use a different A-Shell configuration file than the parent process. Note that the inifile name should be a native file specification, and must be enclosed in quotes (to prevent the slashes in the file spec from being confused with switches). |
| /J jobname | Functions just like the -j switch to A-Shell (allows you to give the background process a specific name). Otherwise, a name of the form TASxxx (TASAAA, TASAAB, ...). will be generated automatically. |
| /K seqno|  <br>pidno|job | (Unix only) Kill a process currently running. To identify the process, you may specify either the "sequence number", the "process id (pid) number", or the job name (which you can get by using the SUBMIT display mode, with no arguments). Note that unless you are the superuser, you may not be able to kill any background processes other than those that you have launched. |
| /L logfile | (Unix only) Overrides the default log file name. (Specify an AMOS-type filename.) |
| /LIST:fspec | Output the list of jobs launched or scheduled via SUBMIT to the specified file. |
| /W: # | (Unix only) Wait # minutes for the submitted process to complete, then kill it. If # is omitted, the submitter will wait indefinitely. This may seem to defeat the purpose of running a process in background, but can be useful either when the main objective is to look at the LOG file, or when you want to run processes that otherwise would not accept input from a command file. |
| /NEXT:timspc | (Unix only) Equivalent to /AFTER:+timspc. |
| /? | Writes switch listing and usage info to the screen. |




**Comments**

Note that there are a number of differences between SUBMIT.LIT under A-Shell and submitting a task to the AMOS Task Manager. First, with SUBMIT.LIT, there is no task manager; instead, the process runs as a child to your current process. Second, there is no queue; the task starts executing immediately (and there is no particular limit to how many tasks you can submit this way with overlapping execution). Third, none of the AMOS embedded control file directives (which contain the \$ symbol) are supported under A-Shell. Fourth, although you can use the SUBMIT.LIT program to check on the status of background tasks (and even kill them), under A-Shell, you can only do so for tasks which _you_ have submitted (unless you are the Superuser).

**See Also**

•	[SUBMIT](submit_sbr.htm.md)

**History**

2026 February, A-Shell 7.0.1782, SUBMIT.LIT 4.0(210):  Refinement to the /K (kill) mode to stop prompting when there are no more submitted jobs and minor cleanup of the output

2022 June, A-Shell 6.5.1717, SUBMIT2.LIT 4.0(207):  Updated to fix a very old bug which would result in the directory listing being duplicated if there were consecutive DEVICE statements for the same device—i.e. one normal DEVICE definition and one or more PPN-specific definitions.

2016 December, A-Shell 6.3.1540:  Implement /CU switch to display group.

2014 November, A-Shell 6.1.1398:  Improve granularity and therefore responsiveness of /W (wait) operation. Display wait times in hundredths of seconds.

2011 November, A-Shell 6.0.1240:  Remove the limit on the number of PPNs allowed per device.

2011 August, A-Shell 5.1.1227:  DO.LIT / MDO.LIT 2.1(124) and SUBMIT.LIT 3.1(150) now support file-based variable command line arguments using the ++fspec syntax. 

**Subtopics**

-