Contents of Article
Mainframe ISPF users are familiar with using the SUBMIT command to send JCL and data to be executed as a job under DOS/VS, MVS, VM or z/OS. The SPFLite primary command SUBMIT provides the ability to submit an edit file to an external process (which may be an executable program or batch file).
The SUBMIT facility is flexible enough to be usable in a wide variety of applications. Because of this, the notion of a “job” is very flexible, and may be configured as desired using SPFLite's Options GUI. The SUBMIT command may also take optional user parameters that could be used in a submit script if desired. A "job" can be, but need not be, a JCL job stream destined for a mainframe system. Alternatives to using SUBMIT might be RUN or CMD depending on your needs.
It is expected that a principle use of the SUBMIT command will be to submit jobs for execution on mainframe systems operating under control of the Hercules emulator program. More details on this are provided below. See The SPFSUBMIT utility program. SUBMIT can be issued from an Edit, Browse or Clipboard session.
Prior to using SUBMIT, you will need to determine just how you are going to be using it. If you're a Hercules user, skip to The SPFSUBMIT Utility program for details. Otherwise, you will probably be doing a simple invocation of a program or batch script file. So first, figure out exactly what the command should be to perform your desired function. Test the syntax using a normal DOS command window till you have it correct.
Then, set up this command in the SPFLite Submit options. (Enter Options => Submit) and you should see something similar to the following.
Enter your tested command in the Prototype box. Replace the operand containing the filename to process with ~i SPFLite will replace ~i with the temporary filename containing your edit text and invoke the command. The example below shows the prototype setup to use the SPFSUBMIT utility for Hercules users, use whatever command you tested above in the command window.
There are many other codes available in addition to ~I. All submit codes are optional, but it would be unusual to omit the ~I code. See the description of the SUBMIT command for a complete list of submit codes.
If you plan on using the SUBMIT INCLUDE feature, complete the two values to specify the INCLUDE trigger key. See Options => SUBMIT for further details.
Because SPFLite does not know what the user's intent is in “submitting” a “job” it is necessary for you to define this meaning. The sequence of events that occur during a SUBMIT operation is as follows:
SUBMIT allows you to embed / include external files into the jobstream during SUBMIT. To do this, you must define a unique identifier which will be used to trigger INCLUDE processing. This is done on the OPTIONS=>SUBMIT setting panel.
The default values for this trigger is the string #INCLUDE located in Column 1. You may of course set these to whatever you desire. The operand for #INCLUDE is simply the name of the file to be included. This value may be unquoted or quoted (single or double). If a simple filename, it must be located in the same folder as the file being edited. It can also be a fully qualified path / filename. Examples:
You may be using SUBMIT to run local batch files against the text you are editing. An example might be to run the C compiler while editing a C source file. Setting up SUBMIT for this is straightforward, just specify the BAT file for the C compile in the SUBMIT prototype command.
But once you are using multiple languages, you certainly do not want your ASM files passed to the C compiler. What to do?
One of the settings available for a file type Profile is SUBARG, which can be any string you desire. Say you have several BAT files for different languages, such as ASMCOMP for ASM files, CCOMP for C files and BASCOMP for BAS files.
Set the SUBARG value for each of the file types to the appropriate BAT file name. Now you can specify the Prototype as (example):
C:\Users\Me\BatFiles\~Z.BAT ~i (The ~Z variable is replaced by the SUBARG value.)
Now when you issue SUBMIT while editing an ASM file, it will use the ASMCOMP.BAT file. Similarly it will use the BASCOMP.BAT file for BAS files, etc.
Every time SPFLite is started up, it looks in the SUBMIT working directory for any temporary submit files more than 2 days old, and if found, deletes them. This means that you generally will not need to be concerned about these temporary files accumulating. If you wish, you can always manually delete these temporary files more frequently.
If your SUBMIT functions require supporting BAT or script files, this temporary directory is a convenient and relevant place to store them.
If you use the DEBUG option, it causes the SUBMIT prototype command (such as SPFSUBMIT.EXE) to be run in a command window that stays open until you explicitly close it with a Windows EXIT command or by closing the command window by clicking on the X. This allows you to view any generated messages, run additional command-line programs, etc. if the external process launched by SUBMIT is not working properly.
Included in the distribution of SPFLite is the batch utility program SPFSUBMIT.EXE for submitting jobs to the Hercules mainframe emulator. This program has parameters and performs a function comparable to a utility supplied with Hercules, with the following differences:
When the SPFLite primary command SUBMIT is being used for simple job submissions to a single emulated mainframe system, it may be sufficient to call SPFSUBMIT.EXE directly as the prototype command that is defined in the Options - Submit tab of the Global Options dialog. When the submit requirements are more complex, the submit prototype command can launch a batch script that would in turn call SPFSUBMIT.EXE.
For SPFSUBMIT to successfully submit a job to an emulated mainframe system, the Hercules configuration file must have an emulated card reader device configured to read from a socket rather than from a PC disk file. A sample card reader device line in the Hercules configuration file might look like this:
000C 3505 localhost:3505 SOCKDEV ASCII AUTOPAD TRUNC EOF # card reader
In the SPFSUBMIT.EXE command line, the “localhost” name can be specified literally as localhost or as 127.0.0.1.
SPFSUBMIT.EXE can only submit a job when the target system is currently running. (There is no "job queue" in case the target system is not active.)
When SPFSUBMIT is executed with no parameters, a Help screen is displayed as follows, which explains how to use the program:
The SPFSUBMIT program is used to submit a file to a given host:port address.
SPFSUBMIT [-nnn] [host:port] file [file ...]
-nnn Timeout value (1-999) in seconds; default is 5 seconds
host:port Target address to submit to; if not specified, the value
of SPFSUBMIT environment variable is used, if defined
file File being submitted
SPFSUBMIT localhost:3505 job111.txt job222.txt
SPFSUBMIT job333.txt job444.txt
SPFSUBMIT myhost:3505 job555.txt
SPFSUBMIT 192.168.0.1:3505 job6.jcl job7.jcl
SPFSUBMIT -2 127.0.0.1:3505 C:\mypath\myjob.jcl
Return code values:
0 Successfully submitted
1 Cannot connect to host, bad socket address, or connection refused
2 Timeout value exceeded while trying to connect
3 Transmission error, or connection prematurely closed
4 File not found or cannot be opened
5 Submit failed, missing or invalid arguments, or unexpected failure
SPFSUBMIT messages are written on stdout and can be redirected
SPFSUBMIT with no parameters displays this help
The following features of SPFLite will prove useful to users of the SUBMIT command:
Created with the Personal Edition of HelpNDoc: Free help authoring tool