BATCH2 (TCP/IP)

BATCH2 is a program that allows a stream of commands in a sequential file to be sent to a Model 204 Online, and to save the output from those commands to another sequential 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 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.

Originally, TCP/IP BATCH2 was developed for Unix. As such, it used Unix-style command-line parameters. TCP/IP BATCH2 was then extended for execution on Microsoft Windows and, finally, for IBM mainframe operating systems VM, MVS and, now, 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 is useful to have a BATCH2 program running on one LPAR or machine communicating with a an Online on another. A version of BATCH2 was developed that used a parameter list identical to that used by the CRAM BATCH2.

Requirements

For the TCP/IP BATCH2 program to communicate with an Online, that Online must have a Janus IFDIAL port defined. The Online must be linked with the Sirius Mods and must be authorized for the Janus TCP/IP Base product.

An IFDIAL port is defined with the JANUS DEFINE command:

 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 for all IP addresses on the Online's host machine (more than one IP address is possible if the host is multi-homed).

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

CRAM BATCH2 compatibility

In order to migrate from an environment where all BATCH2 jobs run on the same machine/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 to simply replace 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, with is an 8-byte or shorter CRAM channel name. But the TCP/IP BATCH2 requires either 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.

File DDs

Since the original implementation of BATCH2 was targeted at Unix environments, it did not have a concept of DD cards (or FILEDEFs for CMS) but, simply used file names to indicate the input stream and target for the output strea. The CRAM BATCH2 program, however, was geared around two DDs (or FILEDEFs) being established before BATCH2 was run, so the TCP/IP BATCH2 program now uses those same DDs for its inputs and outputs:

CCAIN

Contains the BATCH2 input stream.

CCAOUT

Contains the BATCH2 output stream.

Sample job

The following is a sample BATCH2 job that should work whether the BATCH2 program is the CRAM BATCH2 or the TCP/IP BATCH2 assuming the CRAM channel name is valid for both and other environmental requirements (such as valid input and output datasets) are met:

 //TEST     JOB  site-specific job card parameters go here
 //BATCH2   EXEC PGM=BATCH2,REGION=4096K,
 //             PARM='IOCALE,OMC=0,URCTYPE=B'
 //STEPLIB  DD  DSN=SIRIUS.LOAD,DISP=SHR
 //SYSPRINT DD  SYSOUT=*
 //CCAIN    DD  *
 LOGON
 SIRIUS
 b
 printText Hello World!
 end
 //CCAOUT   DD  SYSOUT=*
 //

This job issues a SIRIUS command on the target Online and then a simple User Language program that displays “Hello World”. All the output from the SIRIUS command and the User Language program go to the file indicated on the CCAOUT DD card (the job's log).

Installing BATCH2

Step one for installing the TCP/IP BATCH2 is downloading the BATCH2 object code from the Sirius Software web site. This can be done at https://sirius-software.com/maint/download/BATCH2.OBJ. A Sirius web site userid and password are required to download the object code.

Uploading object file to mainframe

Once the object files is downloaded to the workstation it must be uploaded to the z/OS or VM system on the IBM mainframe. Any file transfer mechanism can be used, including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary. That is, no translation from ASCII to EBCDIC must occur as a result of the upload. This is typically done by setting the FTP BINARY switch.

Second, the format and LRECL of the file must be specified during the upload. This is because most workstation systems (including Windows, Mac OSX and Linux) do not have a concept of file formats and LRECLs. This information would be lost if it were not specified during the upload. The format of the uploaded file must be F under VM systems and FB under MVS and VSE systems. The LRECL must be 80 on all systems and, under z/OS, the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands. The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe. In this case the SITE command might have to be sent as a "quote" to the mainframe. How this is done depends on your workstation's FTP client. The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

Under MVS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file. A PDS is recommended as a good way to collect all your Sirius object file uploads in one DSN, using the member name to show the product and version.

Assembling BATCH2CH

As noted above, the mainframe TCP/IP BATCH2 needs to be linked with a file that maps CRAM channel names (real or not) to hosts and port numbers. This file could be written in assembler though little assembler knowledge is needed to build this file. A sample shown above is repeated here:

         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

To customize this file change the lines that have C'IOCALE and C'IOALE to contain the required CRAM channel names and change the lines with C'sirius-software.com 2231 and C'sirijes2.sirius-software.com 2231 to contain the required host name (or IP address) and port number. The first three and last two lines in the above example should be copied exactly.

Once BATCH2CH is customized, it must be assembled into an object deck (file). While, some of the details of how this is done might vary from site to site, the following is one example of how one should be able to assemble BATCH2CH:

//ASMBCH  JOB  site-specific job card parameters go here
//ASMBCH  EXEC PGM=ASMA90,PARM=OBJECT
//SYSIN    DD *
         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
/*
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSNAME=SIRIUS.LIB(BATCH2CH),DISP=OLD
//

Of course, instead of having the BATCH2CH file in-line, it would probably be in a PDS:

//ASMBCH  JOB  job card parameters must be set as appropriate for site
//ASMBCH  EXEC PGM=ASMA90,PARM=OBJECT
//SYSIN    DD  DSN=SIRIUS.ASM(BATCH2CH),DISP=OLD
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSNAME=SIRIUS.LIB(BATCH2CH),DISP=OLD
//

Once the BATCH2CH program is assembled, it is ready to be linked in with the rest of the BATCH2 program.

Linking BATCH2

The last step in creating a runnable BATCH2 load module is linking together the BATCH2 object deck downloaded from Sirius Software with the locally assembled BATCH2CH with the requisite C runtime library routines. The following is sample link job shows how this can be done:

//LINKBAT2 JOB  site-specific job card parameters go here      
//LINK     EXEC PGM=HEWLKED,REGION=0M,
//             PARM='LIST,LET,MAP,SIZE=(2048K,512K)'
//SYSPRINT DD   SYSOUT=*
//SYSUT1   DD   UNIT=VIO,SPACE=(3200,(300,150))
//SYSLMOD  DD   DSN=SIRIUS.LOAD,DISP=SHR
//SIRIUS   DD   DSN=SIRIUS.LIB,DISP=SHR
//SYSLIB   DD   DISP=SHR,DSN=TCPIP.SEZACMTX
//         DD   DISP=SHR,DSN=CEE.SCEELKED
//SYSLIN   DD   *
 INCLUDE SIRIUS(BATCH2)
 INCLUDE SIRIUS(BATCH2CH)

 ENTRY   CEESTART
 NAME    BATCH2(R)

/*
//

The names of the Sirius libraries (SIRIUS.LIB and SIRIUS.LOAD) and the C runtime libraries (TCPIP.SEZACMTX and CEE.SCEELKED) might need to be changed to match the names used locally.