Submitting Jobstreams from PC Files to Hercules (via Socket Reader)


Even before I discovered Hercules, I had been using SPF/PC (from Command Technology) to edit program code in a number of languages over the years on several computers that have resided on my desktop.  So I rapidly built up a number of jobstreams for Hercules/MVS in a directory on my PC.  Even though I have RPF and RFE installed in TSO on MVS 3.8j, I still prefer to edit the majority of my jobstreams under SPF/PC and submit them through an emulated card reader to JES2.

For a number of years I have been using a program I wrote in BASIC to preprocess the jobstream files and submit them through the socket reader.  Recent discussions about submit scripts on the Hercules' lists have prompted me to revisit my solution, correcting some less than satisfactory functionality I had let creep into my BASIC code and recoding it in what I hope is a more universally portable solution.

My solution involves two pieces of my own making - a C program that preprocesses the jobstream files and a shell script - and will require either the HERCRDR program (written by Fish as a part of his GUI) or the NETCAT program that can be found in several places on the Internet, including the Cygwin site.



JCLCAT is my preprocessor, and the main function it provides is the ability to nest JCL files.  That is, one file containing JCL may utilize a directive to include the contents of a second file (and the second file may include a third, and so on).  The resulting combined records are passed out of JCLCAT as though all the included files were contained in the first file as a single stream.  The main use of this functionality is pulling program source code into place in compile jobstreams following the SYSIN DD card for the compiler, but there have been other circumstances in which I have found it useful.  My inspiration for this was a similar feature I used decades ago in ICCF under DOS/VSE.

The secondary function of JCLCAT is the ability to use a directive to terminate reading of an input file before end-of-file has been reached.  I use this to keep alternate versions of portions of jobstreams (or optional control cards) intact in a file to allow me to quickly tailor JCL for a utility as needed.  An example will illustrate this better than describing it:

//DD1      DD  UNIT=3350,VOL=SER=SMP001,DISP=OLD
//SYSIN     DD  *

When I need to use a particular control card, I copy it from the list beyond the $END directive into the proper place following the SYSIN DD card and submit the job.  Only those card images before the $END directive are actually submitted.



The two directives are identified by the character strings:


at the beginning of a record in the jobstream file.  The definition of these key strings is the first item in the C source and is easily modified if you have a compelling reason to do so.

The specification of the file to be included following the $INCLUDE directive should follow the normal Linux relative path/file formation.  Here is my COBOL compile and link jobstream:


The COBUCL.JCL file resides in my JCL subdirectory (under MVS under Hercules).  My COBOL program source members is at the same level as the JCL subdirectory, so the reference to include the COBOL source is relative to the JCL subdirectory.  Path references are always relative to the location of the main file, the one specified as an argument to JCLCAT.

The C code for JCLCAT is relatively simple and I have heavily commented the code.  If it is executed with no arguments, it will display the syntax and exit.  Attempts to open files that do not exist as specified will result in an error message and an exit with a non-zero return code to the operating system (or shell).  Messages are written to stderr and the concatenated JCL images are written to stdout, so the output from JCLCAT should be piped or redirected to the desired secondary program or file.

Update 2004/11/01 - I found that when editing files that don't contain sequence numbers in columns 73-80, SPF/PC does not replace trailing null characters on the lines with spaces.  On lines with the $INCLUDE directive, this results in the file name to be included being followed by x'0d0a' and my code was expecting a space as a delimiter.  JCLCAT has now been updated to accept any whitespace as the delimiter for the file name.


SUBMIT Shell Script

The shell script that invokes JCLCAT and then passes the output to HERCRDR is also straightforward.  If no command line arguments are given, it will display the syntax and exit.  If a single argument is given, it is assumed to be the main (or only) file to submit.  If the file does not exist as specified an error message is displayed and the script terminates.  If it does exist, it is processed and the output passed on to HERCRDR.

If a second argument is given, instead of passing the assembled jobstream to HERCRDR, the jobstream is written to a file using the second argument as the receiving file.  This provides a means of assembling a jobstream and holding it for later use, perhaps for documentation, rather than submitting it immediately to Hercules' socket reader.

If the first argument contains a path specification, as well as a file name, the script will change to the specified path prior to processing the file.  This assures that $INCLUDE references remain relative to the location of the main file.  If the current working directory is changed by the script, before the script terminates, the original directory will be returned to.

Like the JCLCAT program, the shell script is heavily commented.



Download the archive submit.tgz [MD5: D59B31D121A1791EA2EF01DA587E8500] from my site.  This archive contains the source for the C program JCLCAT and the shell script SUBMIT.  The contents of the archive can be extracted using WinZip (under Windows) or with Cygwin or Linux (tar -xvzf submit.tgz).  

JCLCAT should compile under almost any C compiler.  I initially entered and compiled it under Borland's C IDE, but the version I use was compiled with gcc under the Cygwin environment.  If you look at the code, there is a few lines of code prior to writing the record containing a JCL statement to stdout (line 74) that functions to remove any instance of x'1a' from the record.  I found that when executing the gcc compiled version of the program under the Cygwin environment occasionally a Windows end-of-file marker (x'1a') was passed through and this code was required to eliminate those artifacts.

The executable for JCLCAT and the SUBMIT shell script should be copied to a directory in your execution search path.  On my system, I put them in \cygwin\usr\local\bin which is where the Hercules' executables are installed.

You also need to obtain a copy of either HERCRDR, which is included with Fish' GUI system, or NETCAT, both available from multiple sites on the Internet.  I use HERCRDR and the executable resides in the same directory as the other Hercules' executables.  Note:  If you use NETCAT, you must change the lines in SUBMIT that are set up for HERCRDR in the version downloaded from this site:

hercrdr localhost:3505 temp.$$

Modify your Hercules' configuration file entries to specify the socket reader interface for your defined card reader devices:

# .-----------------------------Device number
# | .-----------------------Device type
# | | .---------------File name
# | | |
# V V V
#--- ---- --------------------
000C 3505 localhost:3505 sockdev autopad trunc ascii eof

The host name and port number (localhost:3505 in the entry above from my configuration file) may be set to different values for your system, but must match the values specified in the SUBMIT shell script.  If you use NETCAT, remember that you must change one line in SUBMIT that is set up to use HERCRDR in the version downloaded from this site.  A further simplification when using NETCAT is that you can pipe the output from JCLCAT directly to NETCAT and eliminate the creation and deletion of a temporary file to hold the assembled jobstream from JCLCAT.



Submit may be used directly from a shell prompt.  If a second argument is given, the assembled jobstream is redirected (written) to a file using that argument as the file name in the current working directory:

$ submit ../../main.jcl hold
Changed directory to /cygdrive/e/Hercules
JCLCAT v1.0 copyright Jay Moseley, CCP 2004.
Processing input from main.jcl.
Processing input from .SUBFILE1.JCL.
Processing input from ..../SUBFILE2.JCL.
Processing input from ...MVS/JCL/SUBFILE3.JCL.
Processing input from ..SUBFILE4.JCL.
Processing input from .SUBFILE5.JCL.
Changed directory to /cygdrive/e/Hercules/mvs/jcl

The console output above is from a test using a small set of test files.  The resulting file (hold) contains:

//******** MAIN.JCL
//******** SUBFILE1.JCL
//******** SUBFILE2.JCL
//*******  SUBFILE3.JCL
//******** SUBFILE4.JCL
//******** SUBFILE5.JCL

If the second argument is omitted, the assembled jobstream is submitted via HERCRDR:

$ submit ../../main.jcl
Changed directory to /cygdrive/e/Hercules
JCLCAT v1.0 copyright Jay Moseley, CCP 2004.
Processing input from main.jcl.
Processing input from .SUBFILE1.JCL.
Processing input from ..../SUBFILE2.JCL.
Processing input from ...MVS/JCL/SUBFILE3.JCL.
Processing input from ..SUBFILE4.JCL.
Processing input from .SUBFILE5.JCL.
"temp.1516" : 7 cards sent.
Changed directory to /cygdrive/e/Hercules/mvs/jcl



The actual environment for which I wrote JCLCAT and SUBMIT is SPF/PC (a product of Command Technology).  I know that there are other versions of SPF for a variety of operating system platforms, but I do not have access to them or experience using them.  In the Command Technology version of SPF/PC, the steps required to use SUBMIT/JCLCAT are:

1. Add the Cygwin paths to the environment path for SPF/PC
2. Under option 0.3, set a PFKEY to call SUBMIT.  I use Ctrl+F12:



PF25 ══ Ctrl F1 ═══► HELP
PF26 ══ Ctrl F2 ═══► SPLIT
PF27 ══ Ctrl F3 ═══► END
PF28 ══ Ctrl F4 ═══► RETURN
PF29 ══ Ctrl F5 ═══► RFIND
PF30 ══ Ctrl F6 ═══► RCHANGE
PF31 ══ Ctrl F7 ═══► UP
PF32 ══ Ctrl F8 ═══► DOWN
PF33 ══ Ctrl F9 ═══► SWAP
PF34 ══ Ctrl F10 ═══► LEFT
PF35 ══ Ctrl F11 ═══► RIGHT
PF36 ══ Ctrl F12 ═══► tso sh e:\cygwin\usr\local\bin\submit

PF25 LABEL ═══► PF26 LABEL ═══► PF27 LABEL ═══►
PF28 LABEL ═══► PF29 LABEL ═══► PF30 LABEL ═══►
PF31 LABEL ═══► PF32 LABEL ═══► PF33 LABEL ═══►
PF34 LABEL ═══► PF35 LABEL ═══► PF36 LABEL ═══►

Press ENTER key to display ALT keys. Enter END command to exit.

To activate the script, type the name of the main jobstream file in the primary command area and press Ctrl+F12:

SPF/PC(1) ───────── EDIT SELECTION LIST ──--------─ ROW 001 OF 021
COMMAND ═══► ../jcl/cobuc.jcl                    SCROLL ═══► CSR
AIXLOAD  CBL    7361  3-26-01 12:26p A...
BATCH1   CBL     903 12-05-01 12:24p A...
BATCH2   CBL     903 12-05-01 12:24p A...
CHISQR   CBL   10296  1-22-02  4:25p A...
CHISQR   RPT     510  1-22-02  3:59p A...
COMBSORT CBL    7909  1-16-02  3:18p A...

The script will run; messages from the script and executed programs will be displayed in the window and when the script terminates a message to PRESS ANY KEY TO CONTINUE will appear: 

sh e:\cygwin\usr\local\bin\submit ../jcl/cobuc.jcl
Changed directory to /cygdrive/e/hercules/mvs/jcl
JCLCAT v1.0 copyright Jay Moseley, CCP 2004.
Processing input from cobuc.jcl.
Processing input from .../COBOL/COMBSORT.CBL.
"temp.2020" : 215 cards sent.
Changed directory to /cygdrive/e/hercules/mvs/cobol


I hope that you have found my instructions useful.  If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me:

Return to Site Home Page Frequently Asked Questions

This page was last updated on January 17, 2015 .