Contents of Article


Configuring SUBMIT in the Global Options

The SUBMIT process

Including other files in the SUBMIT jobstream

Customizing SUBMIT for different File Types

Managing temporary files

Debugging the SUBMIT process

The SPFSUBMIT utility program

SPFSUBMIT syntax

Complementary Features for Hercules Users


Introduction


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.


Configuring SUBMIT in the Global Options


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.



The SUBMIT process


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:


    1. A file is opened for editing or browsing, or the contents of the Clipboard are opened for editing.
    2. The desired line range is determined. This may be the entire file, or a subset of the file based on a line-label range, a CC block or MM block, or a set of lines defined by an ordinary or relative tag name. The line range may be further limited by excluded or non-excluded lines.The selected group of line is copied to a temporary file having the general form SUBMIT_JOB12345.xxx. (xxx will be the same filetype as that being edited)   This file is written in the SUBMIT Working Directory as defined in the SPFLite Submit Options tab. This file is called the “submit input file”.
    3. A name is created for any messages that the external submit process generates in response to the submit action. If the ~R or ^R submit-codes are coded, SPFLite will create an empty file for it. This file is called the “response file”. Names created as response-file names have the general form SUBRESULTS_JOB12345.TXT.
    4. A 'prototype' command is generated from the information given in the OPTIONS-SUBMIT dialog described above (in the configuration section)  This command may be a script command file like .BAT, or it may be an executable program.
    5. Once the prototype command has been tailored, the command is executed. On the upper-right corner of the edit screen, you will see an initial message like, “40 lines submitted for (JOB12345)”.
    6. If your process utilizes a response file and writes to it during the submit process, SPFLite will detect the file being changed, and will display the first few lines produced by the submit process. e.g If you use SPFSUBMIT as your submit process, and redirect its stdout messages to the response file, you will see a popup message like “SPFSUBMIT: 'ABC.JCL' submitted, 40 lines” if the job submission was successful. Press OK on the popup message to proceed.


Including other files in the SUBMIT jobstream


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:

   #INCLUDE MYFILE.TXT

   #INCLUDE "C:\Users\Documents\Files\AnotherFile.txt".


Customizing SUBMIT for different File Types


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.


Managing temporary files


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.


Debugging the SUBMIT process


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.



The SPFSUBMIT utility program


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:


    • SPFSUBMIT.EXE uses SPFSUBMIT as the name of the environment variable with the host/port address


    • Run-time messages and help are worded differently and include SPFSUBMIT in message text


    • SPFSUBMIT assumes a default timeout interval of 5 seconds


    • The return code values are zero for success and positive values when errors are detected


    • Non-zero return codes are included in error message displays (such as, "RC=3")


    • All run-time messages are written to stdout so that they can be redirected to an output file, such as the Response File represented by the SPFLite submit code ~R or ^R


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:


SPFSUBMIT syntax


The SPFSUBMIT program is used to submit a file to a given host:port address.


Command syntax:


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


Examples:


    SPFSUBMIT localhost:3505 job111.txt job222.txt

    set SPFSUBMIT=localhost:2501

    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



Complementary Features for Hercules Users


The following features of SPFLite will prove useful to users of the SUBMIT command:


    • The profile option EOL AUTO or AUTONL can be used to read SYSOUT files having nonstandard or inconsistent line terminations that include CR, LF and FF in unusual combinations. Hercules is known to create such files, and the EOL AUTO or AUTONL option works well for viewing them. When EOL AUTO or AUTONL is in effect, the first line of the file, and any lines read in that contained a Form Feed character will be marked with =PAGE> in the sequence area. You can use UP PAGE and DOWN PAGE to scroll up and down to the previous or next PAGE boundary. See EOL – Set End-of-Line Handling for more information.


    • The profile option START NEW can be used to automatically set a line label of .START on the last line of the file when the file is closed, and when reopened, SPFLite will automatically position the file to the .START label. This technique allows print spool files to be easily browsed at the point where new print information has been added by an outside process such as Hercules. See the START command for more information.


    • The SPFSUBMIT.EXE program is provided with SPFLite to facilitate the submission of jobs for SPFLite to Hercules. The SPFLite installation will ensure this program is available to execute without requiring a full path, or you may specify a full path for this program if it is located elsewhere.


    • SUBMIT-related commands SUBCMD and XSUBMIT were added to recent versions.




Created with the Personal Edition of HelpNDoc: Make Documentation Review a Breeze with HelpNDoc's Advanced Project Analyzer