Hercules: Socket Reader

# Hercules Version 4: Submitting jobs via the socket reader

The "sockdev" option allows you to submit cards directly to a Hercules card reader from outside of Hercules. What you do is define your reader with the "sockdev" keyword and either a TCP/IP port number or the name of a Unix Domain Socket. Then whenever you want to submit a card deck to that particular card reader, you use an external program to connect to the socket and transmit the cards to the reader.

Socket readers were implemented by Fish, based upon code originally contributed by Malcolm Beattie.

Socket readers are defined in the Hercules configuration file like this:

> `devnum devtype sockspec sockdev [option ...]`

The socket specification sockspec can take any of the following formats:

> `ipaddr:port`

>   The reader listens on the specified IP address and port number. ipaddr must be the IP address of an interface on the local system. For example, `127.0.0.1:1234` to accept only jobs submitted locally via the loopback interface.

> `hostname:port`

>   Similar to the previous example, where hostname must resolve to an IP address belonging to the local system. Example: `localhost:1234`.

> `port`

>   The reader listens on the specified port number and accepts jobs submitted to any IP address defined on the local system. Example: `1234`.

> `sockpath/sockname`

>   The reader listens on the specified Unix Domain Socket. Example: `/tmp/hercrdr.00C`.

### Examples

        000A   2501   127.0.0.1:2501    sockdev  ascii  trunc  eof
        000C   3505   localhost:1234    sockdev  ascii  trunc  eof
        0012   3505   3505              sockdev  ascii  trunc  eof
        0014   2501   /tmp/hercrdr.014  sockdev  ascii  trunc  eof

## Submitting jobs from Windows

The "HercRdr" program, distributed as part of Fish's GUI Package, allows you to send jobs to a socket reader via TCP/IP. Simply enter "HercRdr" from the command line to submit your file(s). Here's the "help information" that's displayed whenever you enter "HercRdr" without any parameters:

        C:\WINDOWS>hercrdr
        Submits card file(s) to a Hercules card reader bound to a given socket:port.

        Format:

         HERCRDR [-nnn] [host:port] file [file...]

        Where:

         -nnn timeout value in seconds (1-999; default is 3)
         host:port sock_spec of target reader (if not specified,
         value of HERCRDR environ var is used, if set)
         file file(s) to be submitted

        Examples:

         HERCRDR localhost:1234 fileone.txt filetwo.txt
         set HERCRDR=localhost:1234
         HERCRDR file3.txt file4.txt
         HERCRDR override:5678 filefive.txt
         HERCRDR 192.168.0.1:5678 666.txt 777.txt 888.txt 999.txt

        Returns:

         -1 unclassified error
         0 file(s) successfully submitted
         1 no route to host (bad sock_spec or connection refused)
         2 timeout value exceeded while trying to connect
         3 transmission error (e.g. connection prematurely closed)
         4 file not found (or other file error)

### How to submit jobs directly from SPF/PC

If you are lucky enough to have a copy of SPF/PC Version 4 or SPF/Pro (produced by CTC but unfortunately no longer available), then you can capture the authentic mainframe experience by submitting jobs directly from your edit session. The SUB command can be implemented by means of a REXX macro, such as this one provided by Volker Bandke:

        /* +----------------------------- REXX -----------------------------+ */
        /*                                                                    */
        /*      Name: D:\APPS\SPFPRO\REXX\USER\SUB.SPF                        */
        /*                                                                    */
        /*      Type: SPF edit macro                                          */
        /*                                                                    */
        /*      Desc: submit JCL to MVS 3.8                                   */
        /*                                                                    */
        /*      Creation date: 24 Aug 1999, creation time: 18:49:40           */
        /*                                                                    */
        /*      Author: (c) Volker Bandke                                     */
        /*                                                                    */
        /* +----------------------------------------------------------------+ */
        'isredit macro (p1 p2 p3 p4 p5 p6 p7 p8 p9)'
        "ISREDIT (member) = MEMBER"
        "ISPEXEC CONTROL ERRORS CANCEL"
        parse upper var member file '.' ext
        do
        'ISREDIT REPLACE' $$$$$$$$.SPF '.ZF .ZL'
        ADDRESS "CMD" "HERCRDR 192.168.1.102:3505 $$$$$$$$.SPF"
        zedsmsg = 'File submitted'
        zedlmsg = 'The member '||member||' has been submitted to MVS'
        'ispexec setmsg msg(isrz000)'
        ADDRESS "CMD" "DELETE $$$$$$$$.SPF"
        end
        EXIT 0

## Submitting jobs from Unix

### Using a Perl script

Malcolm Beattie has provided a simple Perl script which can submit jobs using either TCP/IP or Unix Domain Sockets.

The script is invoked using one of the following command formats:

>         hercsub  192.168.1.102:3505  dummy.jcl
>         hercsub  /tmp/hercrdr.00C  dummy jcl

Here is the sample script:

        #!/usr/bin/perl
        use Socket;
        use IO::Socket::UNIX;
        use IO::Socket::INET;

        if (@ARGV < 1) {
          print STDERR "Usage: hercsub socket_spec [job]\n";
          exit 2;
        }

        my $spec = shift @ARGV;
        my $sock;

        if ($spec =~ m{^/}) {
          $sock = IO::Socket::UNIX->new(Peer => $spec);
        } else {
          $sock = IO::Socket::INET->new(PeerAddr => $spec);
        }

        die "Failed to connect to socket $spec: $!\n" unless defined($sock);

        while (<>) {
          print $sock $_;
        }

### Using the netcat program

The netcat (nc) program can also be used to submit files to a Hercules reader via TCP/IP.

Install netcat (which is useful for innumerable other things as well) and use:

> `nc -N localhost 1234 < dummy.jcl`

It is important to use the `-N` option to prevent the Hercules card reader from hanging due to netcat failing to close its connection. The `-N` option tells netcat to close the socket connection once EOF is reached on stdin (i.e. once the entire file has been sent to Hercules).

If your version of netcat does not support the `-N` option, then, as an alternative, the `-q` option should be used. If your version of netcat does not support either option, then you should probably not be using netcat to submit jobs to Hercules.

For more information, type `man nc`.