BATCH2 (TCP/IP)

BATCH2 is the name for a program that allows a stream of Model 204 command in a sequential file to be sent to a Model 204 Online and to have the output from the Online to be saved to another sequential output file. There are basically two BATCH2 programs:

1. A BATCH2 program written in assembler and provided by Rocket Software that uses CRAM as its transport. Because CRAM is an inter-address space transport, this BATCH2 can only work if the BATCH2 program is running on the same machine and LPAR as the target Online.
2. A BATCH2 program written in C provided by Sirius Software that uses TCP/IP as its transport. Because TCP/IP allows communication between two different machines, there are no restrictions on where the BATCH2 program is relative to the target Online. This is the BATCH2 program that is the subject of this page.

The original TCP/IP BATCH2 was expected to be run on Unix. As such, it originally used Unix-style command line parameters. The TCP/IP BATCH2 was then extended to support Microsoft Windows and, finally, was extended to work on IBM mainframe operating systems VM and MVS (now known as z/OS).

The mainframe implementations of the TCP/IP BATCH2 continued to use the Unix-style parameters. Unfortunately, because the CRAM BATCH2 used a totally different parameter list, this made it difficult to easily convert programs that used the CRAM BATCH2 to use the TCP/IP BATCH2. The ability to do this would be useful at a site that had multiple mainframe LPARs or machines &emdash; it can be useful to have a BATCH2 program running on one LPAR or machine communicating with a an Online on another. Because of this, BATCH2 was modified so that there was a version that used a parameter list identical to that used by the CRAM BATCH2.

Requirements

For the TCP/IP BATCH2 program to comunicate with an Online, that Online must have a Janus IFDIAL port defined. For this to be possible, the Online must be linked with the Sirius Mods and must be authorized for the Janus TCP/IP Base product. If an Online is authorized for Janus TCP/IP Base, an IFDIAL port can be defined with the JANUS DEFINE command, as in:

 JANUS DEFINE IFDIAL 2231 IFDIAL 5 IBSIZE 4096 OBSIZE 8192 MAXREC 256

This defines a port that can be accessed via BATCH2 at port number 2231 on all IP addresses (it can be more that one if the host is multi-homed) on the Onine's host machine.

The IBM C run-time libraries must also be available on the host where the z/OS or CMS BATCH2 program is running. Since these are now part of the standard z/OS and CMS distribution, this should only be a problem insofar as locating the libraries.

CRAM BATCH2 compatibility

If one would like to migrate from an environment where all BATCH2 jobs run on the same machine and LPAR as the target Onlines to an environment where the machine or LPAR running the BATCH2 and Online jobs could be mixed and matched, it would be ideal if the change could be made by simply replacing the CRAM BATCH2 load module with the TCP/IP module without any changes to the BATCH2 JCL.

But providing a TCP/IP BATCH2 that is plug compatible with the CRAM BATCH2 presents some special challenges. Most importantly, the target Online for a CRAM BATCH2 program is indicated by the first comma-delimited parameter. This parameter is an 8-byte or shorter CRAM channel name. But the TCP/IP BATCH2 requires a host name (which is often 16 bytes or longer) or IP address, and a port number. So, to provide CRAM BATCH2 compatibility, the mainframe TCP/IP BATCH2 must be linked with an assembler program that maps CRAM channel names to host names and port numbers.

This program is called BATCH2CH (for BATCH2 CHannel) and consists of pairs of null-terminated CRAM channel names, and host names or IP addresses and port numbers. The host name and port number must be separated by the space character. For example:

         ENTRY BATCH2CH
BATCH2CH RMODE ANY
BATCH2CH CSECT
         DC    C'IOCALE',AL1(0)
         DC    C'sirius-software.com 2231',AL1(0)
         DC    C'IOALE',AL1(0)
         DC    C'sirijes2.sirius-software.com 2231',AL1(0)
         DC    AL1(0)
         END

In this example, CRAM channel IOCALE is mapped to host sirius-software.com, port number 2231, and CRAM channel IOALE is mapped to host sirijes2.sirius-software.com, port 2231. The list is terminated with a single null (AL1(0)) after the last host name and port number. This allows the TCP/IP BATCH2 to be invoked with one of the CRAM channel names in BATCH2CH:

//BATCH2   EXEC PGM=BATCH2,REGION=4096K,     
//             PARM='IOCALE'                 

In the above example, if the BATCH2 program was linked with the (assembled) preceding BATCH2CH, it would try to connect to host sirius-software.com port 2231.

Program parameters

To maintain compatibility with the CRAM BATCH, the TCP/IP BATCH2 for z/OS now supports a parameter list identical to that used by the CRAM BATCH2. The format of the parameter list is:

 [channel][,[OMC={X'xx' | num}][,URCTYPE={N | O | B}]]

where

channel

Is the name of the CRAM channel name mapped in IFDIALCH.

OMC value

Is either the hexadecimal or decimal (value must be less than 256) mask to be use to indicate special processing for certain server messages. The default value of OMC is zero (as it is for the CRAM BATCH2) which means that there is no special processing for server messages. The OMC value bit's indicate which messages are to be specially processed:

X'04'

Informational messages are to be suppressed from the output stream.

X'08'

$read prompts are to be suppressed from the output stream.

X'10'

Password prompts are to be suppressed from the output stream.

X'20'

A user restart should immediately terminate the BATCH2 job.

X'40'

New page indicators are to be ignored.

X'80'

Error messages are to be suppressed from the output stream.

URCTYPE value

Indicates whether errors in processing the BATCH2 job stream in the Online are to be reflected in the BATCH2 return code and, if so, which error code is to be used. The default value value of URCTYPE is N (as it is for the CRAM BATCH2) which means that errors in processing the BATCH2 job stream in the Online are not reflected in the BATCH2 return code. Regardless of the setting of URCTYPE, communications errors between BATCH2 and the Online will result in a variety of BATCH2 return codes, depending on the nature of the error. The values of the URCTYPE parameter are:

N

Don't reflect any errors in the job stream in the BATCH2 return code.

B

Set the BATCH2 return code to the value that a BATCH204 job running the identical job stream would return.

O

Set the BATCH2 return code to the value set for Online jobs. Generally, the return code reflected for URCTYPE=O will be less than that for URCTYPE=B — non-severe errors will often return 4 for URCTYPE=B and 0 for URCTYPE=O.