This section documents the installation of Java, BIRT and XMITIP at DTS on z/OS 2.1 zPDT system. All of these products are open source, and many installations may already have one or more of the components installed. While this process is performed on a z/OS system, many programmers may have little experience working with OMVS USS under TSO. If you have any questions, please contact DTS technical support for assistance.
Java has been available on mainframes and most other platforms for many years. The BIRT (Business Intelligence and Reporting Tools) is an open source Java-based application, and is used to create the PDF reports documented in this chapter. In 2007, IBM's Tivoli Division adopted BIRT as the infrastructure for its Tivoli Common Reporting (TCR) product.
The XMITIP open source application is also commonly used by many mainframe installations to create and send email from batch and TSO environments.
Installation The following steps can be used to install and configure Java, BIRT and XMITIP on a z/OS system:
To determine if Java is available:
- Start an OMVS session: If your userid has been set up to use Unix System Services the session should
start with the current directory set to
"/u/userid". - Type the command
echo $PATHto display the PATH environment variable and see if Java is already in the PATH. - If necessary, temporarily add Java to the user PATH. This command
assumes J7.0 is available:
export PATH=/usr/lpp/java/J7.0/bin:$PATH - Type the command
java -version. If Java is not available, mount the Java distribution library on the OMVS file system. - If Java is not available on the system, scan the system volumes for ZFS
and HFS datasets starting with
JVA. The search at DTS showed that Java 7.0 was the latest release available on the DTS development system. The OMVS command interface showed that the/usr/lpp/javadirectory had subdirectories created for multiple versions, but none had been mounted. To mount Java 7.0:
MON-TS7700 REPORTING 5-3
Edit: ADCD.Z21Z.PARMLIB(BPXPRMnn)
Insert:
-
MOUNT FILESYSTEM('JVA700.ZFS') -
TYPE(ZFS) -
MODE(RDWR) -
MOUNTPOINT('/usr/lpp/java/J7.0')
Issue console command:
SET OMVS=nn
Open a browser on a PC and use the following URL to access the download page for the
BIRT distribution libraries. Get the Latest BIRT Runtime
Release Build and save the file to a temporary directory on the PC hard drive.
The installation file downloaded during the DTS install was saved to
d:\birt-runtime-4_4_0-20140611.zip.
Step 3 - Transfer the birt-runtime distribution file to the z/OS USS /usr directory
Open a command prompt on the PC, and use an FTP session to copy the BIRT
installation file to the /usr directory on the z/OS OMVS USS file system.
Any available file transfer application can be used for the transfer, but the goal is to get
a copy of the BIRT runtime installation file in the /usr
directory.
C:\Users\don.DTS>ftp 192.168.0.247
Connected to 192.168.0.247.
220-FTPD1 IBM FTP CS V2R1 at S0W1.DTSSOFTWARE.COM, 19:06:38 on 2014-08-04.
220 Connection will close if idle for more than 1440 minutes.
User (192.168.0.247:(none)): ibmuser
331 Send password please. Password:
230 IBMUSER is logged on. Working directory is "IBMUSER.".
ftp> lcd d:\
Local directory now D:\.
ftp> cd /usr
250 HFS directory /usr is the current working directory
ftp> binary
200 Representation type is Image
ftp> put birt-runtime-4_4_0-20140611.zip
200 Port request OK.
125 Storing data set /usr/birtrt.zip
250 Transfer completed successfully.
ftp: 100665497 bytes sent in 3.04Seconds 33157.28Kbytes/sec.
ftp> bye
221 Quit command received. Goodbye.
Step 4 - Expand the birt-runtime distribution file
Logon as IBMUSER or a userid with a LARGE region size (64MB+). From an
OMVS session running on z/OS enter the following commands:
cd /usr
/usr/lpp/java/J7.0/bin/jar -xvf ./birt-runtime-4_4_0-20140611.zip
Step 5 - Copy the dts-reports.zip file to the OMVS file system (/usr)
The dts-reports.zip file is packaged with the
distribution file downloaded from the company website. The session below
assumes the dts-reports.zip file was located in the
d:\tmp directory on the PC.
From a PC, use FTP to create the /usr/dts-reports folder and transfer
dts-reports.zip to the directory:
C:\Users\don.DTS>ftp 192.168.0.247
Connected to 192.168.0.247.
220-FTPD1 IBM FTP CS V2R1 at S0W1.DTSSOFTWARE.COM, 22:01:07 on 2014-08-04.
220 Connection will close if idle for more than 1440 minutes.
User (192.168.0.247:(none)): ibmuser
331 Send password please. Password:
230 IBMUSER is logged on. Working directory is "IBMUSER.".
ftp> binary
200 Representation type is Image
ftp> cd /usr
250 HFS directory /usr is the current working directory
ftp> lcd d:\tmp
Local directory now D:\tmp.
ftp> put dts-reports.zip
200 Port request OK.
125 Storing data set /usr/dts-reports.zip
250 Transfer completed successfully.
ftp: 617800 bytes sent in 0.05Seconds 12113.73Kbytes/sec.
ftp> bye
221 Quit command received. Goodbye.
Step 6 - Expand the DTS reports distribution file on the OMVS file system
From TSO, open an OMVS session and use the following commands to expand the
dts-reports.zip file to create the /usr/dts-reports
folder.
cd /usr
/usr/lpp/java/J7.0/bin/jar -xvf ./dts-reports.zip
Step 7 - Convert ASCII scripts to EBCDIC for use by OMVS
Three scripts that are used in the report generation process are delivered in ASCII format:
the GenReport.sh script in the BIRT runtime directory
and the GenPDFd.sh and GenPDFh.sh files in the
/usr/dts-reports folder. To be executed by OMVS, these scripts must be
converted to EBCDIC. In an OMVS session, make backups of the files and perform the
conversion using the iconv command. Also, use the chmod
command to ensure the GenPDFd.sh and GenPDFh.sh scripts
are executable.
cd /usr/dts-reports/ts7700
chmod 777 *.sh
cp GenPDFd.sh GenPDFd-bk.sh
cp GenPDFh.sh GenPDFh-bk.sh
iconv -f ISO8859-1 -t IBM-1047 GenPDFd-bk.sh > GenPDFd.sh
iconv -f ISO8859-1 -t IBM-1047 GenPDFh-bk.sh > GenPDFh.sh
cd /usr/birt-runtime-4_4_0
cp GenReport.sh GenReport-bk.sh
iconv -f ISO8859-1 -t IBM-1047 GenReport-bk.sh > GenReport.sh
Step 8 - Edit the GenPDFd.sh and GenPDFh.sh members to fix directory names
From a TSO OMVS session, use the edit command to update the report generation daily script. For example:
Use the editor to open /usr/dts-reports/ts7700/GenPDFd.sh and correct the
directory names on the first two export statements. Save the file. The script should contain
commands similar to the following:
export BIRT_HOME=/usr/birt-runtime-4_4_0
export PATH=/usr/lpp/java/J7.0/bin/:$PATH
cd /usr/dts-reports/ts7700
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf config.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf performance.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf capacity.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf linux.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf replication.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf status.rptdesign
Edit /usr/dts-reports/ts7700/GenPDFh.sh and correct the directory names on
the first two export statements. Save the file. The historical script should contain
commands similar to:
export BIRT_HOME=/usr/birt-runtime-4_4_0
export PATH=/usr/lpp/java/J7.0/bin/:$PATH
cd /usr/dts-reports/ts7700
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf config.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -p "Group=%1" -f pdf performance-h.rptdesign
sh $BIRT_HOME/ReportEngine/genReport.sh -f pdf capacity.rptdesign
Step 9 - Install XMITIP
The batch report generation process creates PDF files in the OMVS USS file system, and the final step of the report generation job emails the PDF reports as file attachments to one or more recipients. Many installations already have a batch email application installed, and the report generation JCL should use an existing email facility available at the customer site. Note: The email application must support binary file attachments.
This step documents the installation of the open source email application XMITIP. To start the install process, download the XMITIP package from the following link to a PC:
http://www.lbdsoftware.com/tcpip.html
Open the ZIP file on the PC to obtain the PDF Installation and User guides. While the product installation guide provides much more detail, the following notes detail the install process used at DTS.
On the PC, extract the file xmitip.xmit from the ZIP distribution file,
and binary transfer the xmitip.xmit file to a mainframe dataset created for
the transfer. For example, on the mainframe create a dataset named
userid.xmit with RECFM(FB) LRECL(80) SPACE(10,10)
CYL.
After the file transfer completes, use TSO and enter the following command to create the
SYSLBD.XMITIP.PDS distribution file on the mainframe:
RECEIVE INDATASET(userid.xmit)
From TSO, issue the following command from ISPF option 6 to run the script that creates the XMITIP production files (this example assumes the SYSLBD high-level qualifier was used):
EX SYSLBD.XMITIP.PDS(RECEIVE)
The following configuration changes were made to XMITIP for the DTS
environment to send email directly to the corporate mail server. Edit the configuration
member SYSLBD.EXEC(XMITIPCU). At DTS, the following parameters were
modified to configure XMITIP to send email to the Microsoft Exchange
email server at DTS (192.168.0.210):
smtp_loadlib = "SYSLBD.LOAD"
smtp_method = "UDSMTP"
smtp_server = 192.168.0.210
T7RUND - Daily reports
The "TS7700 Daily Report" job uses multiple Monitor jobs consolidated into a MONTASK job to extract information from the TS7700 configuration. The TS7700 output data is written to a temporary XML file. The BIRT report generation application then creates TS7700 PDF daily reports which are emailed in the last step.
The following JCL is delivered in the DTS report distribution library:
DTS.R61.SLyyddd.RPTLIB(T7RUND)
During the initial installation, the member will be copied to the
DTS.R61.RPTLIB library. Subsequent SCC installs or maintenance upgrades
will not replace the member to avoid overlaying installation JCL changes.
Edit the DTS.R61.RPTLIB(T7RUND) member and modify the JCL. Text that may
require update depends on the dataset names used in previous installation steps. During
initial testing, DTS recommends running the steps as individual jobs until reports are
successfully created and emailed. The job can then be moved into production, and should be
scheduled to run when the TS7700(s) are not being heavily utilized.
//JOBNAME JOB ...,REGION=0M
//*
//* DLM DAILY REPORT
//*
//* Run Monitor to query the DLM for report data, and create
//* an XML file containing all the record formats.
//*
//STEP1 EXEC PGM=MONTASK
//STEPLIB DD DISP=SHR,DSN=DTS.R61.LOADLIB
//PARMLIB DD DISP=SHR,DSN=DTS.R61.RPTLIB
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//LIST DD SYSOUT=*
//SITE DD DISP=SHR,DSN=DTS.R61.RPTLIB(T7SITE)
//CONFIG DD DISP=SHR,DSN=DTS.R61.RPTLIB(T7CONFIG)
//OLDXML DD PATH='/usr/dts-reports/ts7700/ts7700.xml',
// PATHDISP=(DELETE,DELETE),
// PATHOPTS=(ORDWR,OTRUNC,OCREAT)
//XML DD DISP=(MOD,PASS),DSN=&&XML,
// DCB=LRECL=80,SPACE=(CYL,(5,5)),UNIT=SYSALLDA
//KVSAM1 DD DISP=(NEW,PASS),
// SPACE=(CYL,(1,1)),UNIT=SYSALLDA,
// RECORG=KS,KEYLEN=50,KEYOFF=1,LRECL=500
//SYSIN DD *
OPTION XML(XML) /* Write output to the XML DD statement */ DEFAULT INPUT(CARDS(*)) OUTPUT(SYSPRINT(LIST) SYSOUT(XML)) PARM(""
"INCLUDE(VTE(*))"
)
RUN CONFIG REPORT(DDBLC) /* DLM Configuration Info */
RUN VTECON REPORT(DDBLCF) /* VTE Information */
RUN HOUR REPORT(DDBLV) /* Hourly Data */
RUN LINUX REPORT(DDBLV3) /* Linux Information */
RUN MSG REPORT(DDBLV4) /* MESSAGES */
RUN SPACE REPORT(DDBLF) /* GET Q SPACE */
RUN VNX REPORT(DDBLX) /* VNX information */
RUN DD REPORT(DDBLD) /* Data Domain information */
RUN QMOUNTS REPORT(DDBLM) /* Current Mounts */
RUN MOUNTS REPORT(DDBLV2) /* Get VTE mount data */
/*
/* Delete the old PDF reports, and copy the XML data to USS
/*
//STEP2 EXEC PGM=IKJEFT01
//SYSEXEC DD DISP=SHR,DSN=SYS1.SBPXEXEC
//XML DD DISP=OLD,DSN=&&XML
//OUTDD DD PATH='/usr/dts-reports/ts7700/ts7700.xml',
// PATHDISP=(KEEP,DELETE),
// PATHOPTS=(OCREAT,ORDWR),
// FILEDATA=TEXT
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
oshell rm -f /usr/dts-reports/ts7700/*.pdf
ocopy INDD(XML) OUTDD(OUTDD) TEXT FROM1047 CONVERT((BPXFX311))
//*
//* Execute BIRT to generate the PDF reports using the XML data
//*
//STEP3 EXEC PGM=BPXBATCH,
// PARM='sh /usr/dts-reports/ts7700/GenPDFd.sh'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDENV DD DUMMY
//*
//* Send reports via Email using XMITIP
//*
//STEP4 EXEC PGM=IKJEFT1B
//STEPLIB DD DISP=SHR,DSN=SYSLBD.LOAD
//SYSEXEC DD DISP=SHR,DSN=SYSLBD.EXEC
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
%XMITIP (don@dtssoftware.comtom@dtssoftware.com) -
from ts7700-reports@dtssoftware.com -
subject 'Daily TS-7700 Reports' -
msgt 'Daily report generated by MON-TS7700' -
fileo ( -
'/usr/dts-reports/ts7700/capacity.pdf' -
'/usr/dts-reports/ts7700/config.pdf' -
'/usr/dts-reports/ts7700/performance.pdf' -
'/usr/dts-reports/ts7700/pmounts.pdf' -
'/usr/dts-reports/ts7700/throughput.pdf' -
'/usr/dts-reports/ts7700/vmounts.pdf' -
)
filen ( -
TS7700-Config.pdf -
TS7700-Performance.pdf -
TS7700-Capacity.pdf -
TS7700-Linux.pdf -
TS7700-Replication.pdf -
TS7700-Status.pdf -
) -
format *bin
/*
T7RUNH - Historical reports
The "TS7700 Historical Report" job uses multiple Monitor jobs consolidated into a MONTASK job to extract information from the TS7700 configuration. The output data is written to a temporary XML file. The BIRT report generation application then creates TS7700 PDF historical reports which are emailed in the last step.
By default, the "TS7700 Historical Report" processes historical data from the TS7700 for the past week. The report can be changed to extract TS7700 historical data for a longer or shorter period of time. Two changes are required to modify the report to a different report period:
- Change the
&LDATE:CURDATE{-7}parameter on the PARM statement in STEP1 to include records from a longer period than seven days. - By default, the reporting period is grouped by
WEEKS. The report can be changed to group by one of the following:DAYSWEEKSMONTHSYEARS
GenPDFh.sh WEEKSparameter on STEP3 can be changed to one of the specified reporting periods.
The following JCL is delivered in the DTS report distribution library:
DTS.R61.SLyyddd.RPTLIB(T7RUNH)
During the initial installation, the member will be copied to the
DTS.R61.RPTLIB library. Subsequent SCC installs or maintenance upgrades
will not replace the member to avoid overlaying installation JCL changes.
Edit the DTS.R61.RPTLIB(T7RUNH) member and modify the JCL. Text that may
require update depends on the dataset names used in previous installation steps. During
initial testing, DTS recommends running the steps as individual jobs until reports are
successfully created and emailed. The job can then be moved into production, and should be
scheduled to run when the TS7700(s) are not being heavily utilized.
//JOBNAME JOB ...,REGION=0M
//*
//* DLM HISTORICAL REPORT
//*
//* Run Monitor to query the DLM for report data, and create
//* an XML file containing all the record formats.
//*
//STEP1 EXEC PGM=MONTASK
//STEPLIB DD DISP=SHR,DSN=DTS.R61.LOADLIB
//PARMLIB DD DISP=SHR,DSN=DTS.R61.RPTLIB
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//LIST DD SYSOUT=*
//SITE DD DISP=SHR,DSN=DTS.R61.RPTLIB(DDSITE)
//CONFIG DD DISP=SHR,DSN=DTS.R61.RPTLIB(DDCONFIG)
//OLDXML DD PATH='/usr/dts-reports/ts7700/ts7700.xml',
// PATHDISP=(DELETE,DELETE),
// PATHOPTS=(ORDWR,OTRUNC,OCREAT)
//XML DD DISP=(MOD,PASS),DSN=&&XML,
// DCB=LRECL=80,SPACE=(CYL,(5,5)),UNIT=SYSALLDA
//KVSAM1 DD DISP=(NEW,PASS),
// SPACE=(CYL,(1,1)),UNIT=SYSALLDA,
// RECORG=KS,KEYLEN=50,KEYOFF=1,LRECL=500
//SYSIN DD *
OPTION XML(XML) /* Write output to the XML DD statement */
DEFAULT INPUT(CARDS(*)) OUTPUT(SYSPRINT(LIST) SYSOUT(XML)) PARM("")
MON-TS7700 REPORTING 5-11
"INCLUDE(VTE(*))"
"VAR('PVTE=*','&LDATE:CURDATE{-7}','&LDATE:CURDATE')"
)
RUN CONFIG REPORT(DDBLC) /* DLM Configuration Info */
RUN HOUR REPORT(DDBLV) /* Hourly Data */
RUN SPACE REPORT(DDBLF) /* GET Q SPACE */
/*
/* Delete the old PDF reports, and copy the XML data to USS
/*
//STEP2 EXEC PGM=IKJEFT01
//SYSEXEC DD DISP=SHR,DSN=SYS1.SBPXEXEC
//XML DD DISP=OLD,DSN=&&XML
//OUTDD DD PATH='/usr/dts-reports/ts7700/ts7700.xml',
// PATHDISP=(KEEP,DELETE),
// PATHOPTS=(OCREAT,ORDWR),
// FILEDATA=TEXT
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
oshell rm -f /usr/dts-reports/ts7700/*.pdf
ocopy INDD(XML) OUTDD(OUTDD) TEXT FROM1047 CONVERT((BPXFX311))
/*
//* Execute BIRT to generate the PDF reports using the XML data
//*
//STEP3 EXEC PGM=BPXBATCH,
// PARM='sh /usr/dts-reports/ts7700/GenPDFh.sh WEEKS'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDENV DD DUMMY
//*
//* Send reports via Email using XMITIP
//*
//STEP4 EXEC PGM=IKJEFT1B
//STEPLIB DD DISP=SHR,DSN=SYSLBD.LOAD
//SYSEXEC DD DISP=SHR,DSN=SYSLBD.EXEC
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
%XMITIP (don@dtssoftware.comtom@dtssoftware.com) - from ts7700-reports@dtssoftware.com -
subject 'Weekly TS-7700 Reports' -
msgt 'Daily report generated by MON-TS7700' - fileo ( -
'/usr/dts-reports/ts7700/config.pdf' - '/usr/dts-reports/ts7700/performance-h.pdf' - '/usr/dts-reports/ts7700/capacity.pdf' -
) -
filen ( -
DLM-Config.pdf - DLM-Performance.pdf - DLM-Capacity.pdf -
) -
format *bin
/*
Troubleshooting reports
Verify that the MONTASK step created the ts7700.xml file in the report directory. If the report generation process fails, open an OMVS session and examine the report directory:
cd /usr/dts-reports/ts7700
ls -l *.xml
The
ls command should produce output similar to the
following:
-rw-r----- 1 DON OMVSGRP 6962847 Aug 18 11:27
ts7700.xml
Verify the size and creation date of the data.
Examine the STDOUT and STDERR files created in Step 3 of the report generation job for error messages. Also, examine the report directory for the PDF files created by BIRT. Use an OMVS session to list the files:cd /usr/dts-reports/ts7700
ls -l *.pdf
The
ls command should produce output similar to the
following:
-rw-r--r-- 1 DON OMVSGRP 915202 Aug 18 11:28 capacity.pdf
-rw-r--r-- 1 DON OMVSGRP 11739 Aug 18 11:28 config.pdf
-rw-r--r-- 1 DON OMVSGRP 40543 Aug 18 11:29 linux.pdf
-rw-r--r-- 1 DON OMVSGRP 161848 Aug 18 11:29 replication.pdf
-rw-r--r-- 1 DON OMVSGRP 5982 Aug 18 11:29 status.pdf
Verify
that the XMITIP step successfully created the email with
attachmentsExamine the job output from the XMITIP
step and look for error messages. The most common problem encountered in
the XMITIP step is a D37-04 abend on a temporary
dataset created by XMITIP (for example:
IBMUSER.XMITIP.OMVS.FILE1).
To create the email
attachments, the XMITIP application uses the TSO
OGET command to extract each PDF file from the USS
file system to a temporary sequential dataset using a generated name. If
the dataset doesn't already exist (the normal condition), the
OGET command creates the dataset using the dynamic
allocation system defaults. Unless your installation has overridden the
z/OS defaults, the default allocation will limit an attachment to
approximately 2MB and the attachment data is truncated. The result is a
PDF file attachment in the email which cannot be opened.
To
avoid the problem with large attachments, pre-allocate the dataset
before invoking XMITIP. For example, if the
XMITIP step receives a D37-04 abend on
IBMUSER.XMITIP.OMVS.FILE5, add a TSO
ALLOC command to create the file before the
%XMITIP command. The OGET command in
XMITIP will use the existing file to create the
attachment, and the application will automatically delete the dataset
before terminating. The sample ALLOC command is shown
below:
//STEP4 EXEC PGM=IKJEFT1B
//STEPLIB DD DISP=SHR,DSN=SYSLBD.LOAD
//SYSEXEC DD DISP=SHR,DSN=SYSLBD.EXEC
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
alloc da(XMITIP.OMVS.FILE5) sp(5,5) cyl unit(sysallda) recfm(v,b) lrecl(255) new delete
Then
run the %XMITIP command. Example:
%XMITIP (don@dtssoftware.com tom@dtssoftware.com) - from ts7700-reports@dtssoftware.com -
subject 'Daily DLM Reports' -
msgt 'Daily report generated by the DLM Control Center (ts7700)' -
fileo ( -
'/usr/dts-reports/ts7700/config.pdf' -
'/usr/dts-reports/ts7700/performance.pdf' -
'/usr/dts-reports/ts7700/capacity.pdf' -
'/usr/dts-reports/ts7700/linux.pdf' -
'/usr/dts-reports/ts7700/replication.pdf' -
'/usr/dts-reports/ts7700/status.pdf' -
) -
filen ( -
DLM-Config.pdf - DLM-Performance.pdf - DLM-Capacity.pdf -
DLM-Linux.pdf - DLM-Replication.pdf - DLM-Status.pdf -
) -
format *bin