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 — 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 than 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. When this happens, the return code from BATCH2 is set to 300.

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. Return codes from the Online above 99 are converted to BATCH2 return code of 99 to prevent confusion with communication error return code. This is almost never a problem because, generally, even the most severe errors don't set return codes greater than 16. 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.

The following is an example of an EXEC card that invokes BATCH2 for channel IOALE, requesting that a user restart terminate the run (OMC=X'20'), and that batch return codes are to be used to set the BATCH2 return code:

//BATCH2   EXEC PGM=BATCH2,REGION=4096K,
//             PARM='IOALE,OMC=X20,URCTYPE=B'

The single quotes in the OMC values must be doubled because they occur inside single quotes for the job card.

Trusted login

Another compatibility issue with the CRAM BATCH2 is that CRAM BATCH2 job stream is capable of doing a “trusted login” in the server Online. A trusted login logs on to the Online with the same userid as the userid under which BATCH2 is running. This requires that the same userid be able to run batch jobs and to log into Model 204. This is typically not much of a problem at sites where an external authorizer such as RACF, ACF2, and Top Secret (by Computer Associates) because userids for both JES and Model 204 are managed from the same security server.

A trusted login is usually indicated by a “naked” LOGIN, that is a LOGIN command with no userid (or anything else) specified:

 LOGON
 OPEN FILE ALEXPROC
 V
 ...

With CRAM BATCH2 it is relatively easy to securely validate the userid under which the BATCH2 program is running because BATCH2 and Model 204 are running on the same machine or LPAR and so cross-memory services can be used to retrieve and validate the userid. For the TCP/IP BATCH2 the picture is somewhat more complicated. While the TCP/IP BATCH2 always passes the userid under which it is running to the Model 204 server, there is no particular reason for Model 204 to trust that the BATCH2 job should be allowed to run as that userid. This is because that BATCH2 might be running on a different machine from the Online and so could, in theory, be a BATCH2 program or BATCH impostor that is being used by someone trying to breach security.

So, to add a bit of control to TCP/IP BATCH2 trusted login, the userid passed by BATCH2 will only be used for a trusted login if a TRUST clause was specified for the target IFDIAL port, and that TRUST clause indicated an IP address or subnet that matches the BATCH client's IP address. The TRUST keyword on a JANUS DEFINE for an IFDIAL port must be followed by one or more IP addresses or subnets, separated by an AND keyword. Up to 16 IP addresses of subnets are allowed in a TRUST clause.

An IP address must be specified using standard dotted decimal notation as in, for example, 198.242.244.47 (the IP address of Sirius Software's corporate web server).

A subnet can be specified either with an IP address followed by a subnet mask, both using dotted decimal notation and separated by a / character, or an IP address followed by a number of leading bits in the subnet part of the address, separated by a dash. So 198.242.244.0/255.255.255.0 and 198.242.244.0-24 both describe the same class C subnetwork that just happens to be Sirius Software's subnet.

The following is an example of a TRUST clause in a JANUS DEFINE for an IFDIAL port:

 JANUS DEFINE IFDIAL 2231 IFDIAL 5 IBSIZE 4096 OBSIZE 8192 MAXREC 256 -
       TRUST 198.242.244.0-24 AND 208.80.152.2

Generally, a TRUST list should only include specific IP addresses (as opposed to subnets) and should be limited to IP address for hosts that:

1. Are themselves secure
2. Limit outgoing access to the IFDIAL port to an authorized BATCH2 progam.