BATCH2 (TCP/IP): Difference between revisions
No edit summary |
(It's a take (more or less)) |
||
| Line 78: | Line 78: | ||
#Are themselves secure | #Are themselves secure | ||
#Limit outgoing access to the IFDIAL port to an authorized BATCH2 progam. | #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. | 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: | 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: | ||
| Line 85: | Line 85: | ||
===Sample job=== | ===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: | 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 | //TEST JOB ''site-specific job card parameters go here'' | ||
//BATCH2 EXEC PGM=BATCH2,REGION=4096K, | //BATCH2 EXEC PGM=BATCH2,REGION=4096K, | ||
// PARM='IOCALE,OMC=0,URCTYPE=B' | // PARM='IOCALE,OMC=0,URCTYPE=B' | ||
//STEPLIB DD DSN= | //STEPLIB DD DSN=SIRIUS.LOAD,DISP=SHR | ||
//SYSPRINT DD SYSOUT=* | //SYSPRINT DD SYSOUT=* | ||
//CCAIN DD * | //CCAIN DD * | ||
| Line 99: | Line 98: | ||
//CCAOUT DD SYSOUT=* | //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== | ==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 | 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 | ||
| Line 130: | Line 129: | ||
Once BATCH2CH is customized, it must be assembled into an object deck (file). While, some of the details of how this is done might | 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: | vary from site to site, the following is one example of how one should be able to assemble BATCH2CH: | ||
//ASMBCH JOB | //ASMBCH JOB ''site-specific job card parameters go here'' | ||
//ASMBCH EXEC PGM=ASMA90,PARM=OBJECT | //ASMBCH EXEC PGM=ASMA90,PARM=OBJECT | ||
//SYSIN DD * | //SYSIN DD * | ||
| Line 154: | Line 153: | ||
// | // | ||
Once the BATCH2CH program is assembled, it is ready to be linked in with the rest of the BATCH2 program. | 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. | |||
Revision as of 01:05, 3 September 2010
BATCH2 is the name for a program that allows a stream of Model 204 commands 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:
- 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.
- 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 Online'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:
- Are themselves secure
- 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/ZAP106.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.