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 TSO and RPF installed under 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
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:
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.
Directives
The two directives are identified by the character strings:
$INCLUDE
$END
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.
Installation
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:
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.
Using SUBMIT
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:
The console output above is from a test using a small set of test files. The resulting file (hold) contains:
If the second argument is omitted, the assembled jobstream is submitted via HERCRDR:
SPF/PC
The actual environment for which I wrote JCLCAT and SUBMIT is SPF/PC (a product of Command Technology). I know that there is also another version of SPF for DOS, Windows, and OS/2 that was marketed by Tritus and is still used by many. Also there are some Linux versions of SPF and probably other editors for which SUBMIT/JCLCAT could be used. 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:
To activate the script, type the name of the main jobstream file in the primary command area and press Ctrl+F12:
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:
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:
This page was last updated on April 22, 2008 .