Milestone 2: Installing or upgrading BMC Compuware Web Products on z/OS UNIX

This milestone guides you through the process for installing or upgrading BMC Compuware Web Products (CES, Abend-AID Fault Analytics, Session Monitor, iStrobe,ISPWWeb, BMC ThruPut Manager Web, Topaz for Java Performance, and Topaz for Total Test) on z/OS UNIX.

Important

Roles involved with this milestone:

z/OS UNIX system administrator to install BMC Compuware Web Products.
Database administrator to create the database (if not using Apache Derby). You no longer need to manually create tablespaces, but the database administrator needs the authority to create tablespaces as part of the automated database creation.
IMPORTANT: Without database administrator privilege's you may not be able to complete the product installation or upgrade, which could result in a system outage. Please ensure that you have DBA privilege's available during this process.
MVS systems programmer to set up the CES Manager on JZOS, depending on your site standards.
Security Administrator.

Single user to install or upgrade CES and all web products into CES. This allows CES and those installed web products to run with a single set of permissions.

If multiple users have already installed web products into an installed version of CES, then the permissions must be modified in the install directory of CES to grant both read and write permissions (755) to all users.

Planning

Before beginning the installation, you should verify the following:

Java is installed
Space requirements are adequate
Database is created
Permissions are correct
Ports are opened

Installing

Click the Compuware Web Products tab from the product image.
Ex. <network or hard drive>:\USS\setup.exe
Click Install Compuware Web Products for z/OS UNIX. The Mainframe FTP Information tab appears.
Specify a valid Host, User ID, Password, Port number (default = 21), and finally an existing z/OS UNIX Path in which to upload the install.jar and install.sh files from the CES product image to the mainframe. The install.jar and the install.sh are both uploaded as binary.
Note
The install.sh has Windows line endings. If you are manually uploading from Linux, you will need to run dos2unix on install.sh before uploading as binary.
Click Upload files to mainframe to begin the upload.
Log on to the mainframe and navigate to an OMVS command prompt, or use any SSH client.
Important
For 64-bit Java, you may need to specify the region size by logging on with: logon <username> size (<desired region size>).
If the installer is a different account than the account running CES, and you are either adding products or upgrading an existing install, do the following:
1. Change the owner to the installer with a command line such as the following: Chown -R installerId /ces/install/directory
2. Perform the required upgrades with the installer following the instructions within Upgrading.
3. When the installation is complete, change the owner back to the ID that runs CES with a command line such as the following: Chown -R startedTaskId /ces/install/directory
  For example, the account performing the install and the account running CES will differ when CES runs as a started task.
Change the directory to the location where the install.jar and the install.sh files were transferred. For example:
cd <directory containing the uploaded install.jar and install.sh files>
Be sure that the install.sh file has execute authority and execute it. Perform a chmod 755 to open up permissions, if necessary.
Execute the install.sh file. For example:./install.sh
Some systems may require that you increase the Java HEAP size before running the installer. For example:
_JAVA_OPTIONS=-Xmx512M
The CES installer starts.
Important
You can cancel the installation at any time by typing quit. You can go back in the installation panels at any time by typing back.
Enter the directory path to a supported installation of Java (64-bit Java 1.7 or Java 1.8). For example:
usr/lpp/java/J8.0_64.bld041715
Important
If a valid version of Java is found, it may automatically be used, thereby skipping this step.
Specify Y (Yes) or N (No) for using the system’s /tmp directory as the installation temporary space. If N, the installation launches. If Y, then you are prompted to enter an absolute directory path to a designated temporary directory space. Press Enter.
Important
The installer requires use of the system temporary directory and may require up to 1,125,000 1k blocks (1375 cylinders) of pre-allocated space.
The Installer launches. Read the Introduction panel and press Enter. The License Agreement panel appears.
Read the BMC Compuware Web Products license agreement. When prompted, type Y and press Enter to accept the terms of the license agreement. The Oracle License Agreement panel appears.
Read the Oracle Technology Network Development and Distribution License Agreement. When prompted, type Y and press Enter to accept the terms of the license agreement. The Compuware Web Products panel appears.
Press Enter. The Choose Install Folder panel appears.
Specify the absolute directory path in which to install CES, or press Enter to accept the default location (Default: /opt/Compuware/CES). The Select Products to install panel appears.
Important
If you choose an alternate installation directory instead of the default, the directory (and any parent directories) will be created with privileges of 775. To use CES following installation, be sure that the CES job has write permission to the CES directory created by the installation.
The installer requires use of up to 1,125,000 USS 1k blocks (1375 cylinders HFS/zFS) of pre-allocated space to install properly. You may be prompted to create free space in the specified directory in order to continue with the installation.
Warning
If you are upgrading from a previous release, enter the existing CES installation directory.
Select the BMC Compuware web products to be installed along with CES by entering a comma delimited numbered list corresponding to the products and press Enter.
Confirm your selection. If you would like to make changes to your selection, type Back. Otherwise, press Enter.
CES stores log and configuration data in the /data directory under the installation directory specified in Step 16. Press Enter to accept the default location (<installation_directory>/data) or specify the absolute path to another location.
Specify Y (Yes) or N (No) whether you want to modify the default port numbers. Be sure that the ports you choose are open on your network's firewall.
Port name
Port number (by default)
Strobe Communication port
24354
Web Server port
48226
Internal Messaging port
17667
Derby port
1545
(Fault Analytics only) Abend-AID communication port (default: 48301) Used to transmit messages. Specify a port number between 1024 and 65535. Press Enter.
(iStrobe only) Profile directory (default: <installation_directory>/data/istrobe/profiles)
Used to store measurement data in profiles. Specify the absolute directory path for the Profile directory. Press Enter.
(iStrobe only) Quarantine directory (default: <installation_directory>/data/istrobe/quarantine) Used to store profiles that cannot be read. Specify the absolute directory path for the Profile directory. Press Enter.
(Topaz for Java Performance only) Agent communication port (default: 48128). Topaz for Java Performance requires a port for communication between the mainframe agent and server. Specify a port on which to listen for this communication, or press Enter to accept the default.
(Topaz for Total Test only) MongoDB host (default: localhost) and MongoDB port (default: 27017). Total Test requires this information to configure the MongoDB database. This database is used exclusively with Topaz for Total Test.
Review installation information you selected in the Pre-installation Summary panel. If anything is incorrect, type Back and revise the installation settings as necessary. If the information is correct, press Enter to start the CES installation. The Installation Complete panel appears when the installation finishes.
Important
Before exiting the installer, copy the URL provided in the installer completion page and create a bookmark for quick access. Once the CES service is started, initialization may take several minutes. You may see a 404 page in your web browser during this time.
Warning
After exiting the installer, a script, copyFilestoDataSet.sh, will execute. It will allocate a PDS and copy several JCL files into members of a PDS on your z/OS system. In case it fails, you can re-run it after correcting the errors by issuing the following command: ./copyFilestoDataSet.sh.
The CES installation process is complete. Continue with the next section, Preparing to Start CES. After starting CES, you must still configure CES. See to Milestone-5-Configuring-BMC-Compuware-Enterprise-Services.

Port name	Port number (by default)
Strobe Communication port	24354
Web Server port	48226
Internal Messaging port	17667
Derby port	1545

Preparing to start BMC Compuware Enterprise Services

The copyFilestoDataSet.sh above will copy the following files from the CES installation directory on z/OS UNIX to MVS:

CESAMN.PARMLIB
CESEMN.PARMLIB
- Added _BPX_BATCH_SPAWN = Yes and _BPX_SHAREAS = No variables to the CESEMN parmlib member to control how child processes are spawned.
- Added _BPXK_SETIBMOPT_TRANSPORT variable to the CESEMN parmlib member to control which TCP/IP stack is used by CES.
- Added required JVM options to enable SSL in CES 20.1.
CESBATCH.JCL
CESTASK.JCL
JZOSPROC.JCL

The files that end with PARMLIB are input parameter files used to start the appropriate CES Manager service. These can be shortened to CESxxx member names. The files that are qualified as JCL are the PROC and JOB samples for executing on the z/OS system; these can be shortened by removing the .JCL qualifier.

CESEMN
- BPX_BATCH_SPAWN = Yes causes BPXBATCH to use spawn instead of fork/exec and allows data definitions to be carried over into the spawned process.
- BPX_SHAREAS = No causes the child process created by the spawn to run a different address space from the parent.
- DEFS="$DEFS -Dcom.ibm.jsse2.overrideDefaultTLS=true" was added in release 20.1 to support running CES with SSL. If upgrading from a version of CES prior to 20.1, and using existing JCL, then this line needs to be added below the DEFS="$DEFS -Dfile.encoding=ISO8859-1" line.
  Important
  When upgrading Java or Db2 on z/OS after CES has been installed, the JAVA_HOME variable in the CESEMN member may need to be modified.
CESBATCH - used to run BMC Compuware Web Products as a batch job.
- Change the job card to match your system requirements.
- ARGS=CESAMN is set by default to start the CES Manager.
- Change the HLQ1 and HLQ2 to match the first 2 nodes of the CESBATCH member (e.g. CPWR.CES.CNTL(CESBATCH)…HLQ1=CPWR, HLQ2=CES)
  000001 //SAMPLE0I JOB   ('ACCOUNT',78,1,1),'CES WEB APP SERVER',
  000002 //      CLASS=L,MSGCLASS=H,NOTIFY=&SYSUID,REGION=0M,JOBRC=LASTRC
  000003 //***************************************************
  000004 //*   Use CESEMN for the env member for all uses
  000005 //*   Use ARGS="CESAMN" to run CES Web Application
  000006 //***************************************************
  000007 //         SET QUAL='HLQ1.HLQ2' < PARMLIB HI-LEVEL QUALIFIER
  000008 //* Note: If running CES as a batch job from a dataset which is not
  000009 //* part of the default JCLLIB, uncomment and update the
  000010 //* JCLLIB statement below
  000011 //*PROCLIB JCLLIB ORDER=HLQ1.HLQ2.CNTL
  000012 //CESSERVR EXEC JZOSPROC,ENV=CESEMN,ARGS=CESAMN
  000013 //*
  000014 //* Following step automatically restarts if we get an rc=3 since
  000015 //* Since when applying a patch we shut down with RC=3 so the job
  000016 //* knows we need to start CES due to it being shutdown as part
  000017 //* of the upgrade process
  000018 //RESTART EXEC PGM=IEBGENER,COND=(3,NE)
  000019 //SYSUT1   DD DSN=&QUAL..CNTL(CESBATCH),DISP=SHR
  000020 //SYSUT2   DD SYSOUT=(,INTRDR)
  000021 //SYSPRINT DD SYSOUT=*
  000022 //SYSIN    DD DUMMY
- As shown in the JCL (CESBATCH) above, you can insert a JCLLIB statement if you want to invoke the JZOSPROC from the CPWR.CES.Tnnnnnn.CNTL data set.For example:
  // JCLLIB ORDER=(<USER>.CPWR.CES.Tnnnnnn.CNTL)
CESTASK - used to run BMC Compuware Web Products as a started task.
- Change the job card to match your system requirements.
- ARGS=CESAMN is set by default to start the CES Manager.
- Change the HLQ1 and HLQ2 to match the first 2 nodes of the CESBATCH member (e.g. CPWR.CES.Tnnnnnn.CNTL(CESTASK)…HLQ1=CPWR, HLQ2=CES)
- Upon startup, CESTASK will print the message 'CES has started' to both the SYSLOG and the JESMSGLOG.
  000001 //*   Example JCL to run CES as a started task
  000002 //*   Note use your site's auto opts program to start this started
  000003 //*   task if it exits with return code 3. When CES requires
  000004 //*   a restart it will exit with a return code 3. Anything above
  000005 //*   a return code 3 is an unexpected error.
  000006 //*   Use CESEMN for the env member for all uses
  000007 //*   Use ARGS="CESAMN" to run CES Web Application
  000008 //***************************************************
  000009 //JLAUNCH PROC VERSION=76,
  000010 //         QUAL='HLQ1.HLQ2', < PARMLIB HI-LEVEL QUALIFIER
  000011 //   ENV=CESEMN,                         < CES ENVIRONMENT INPUT
  000012 //   ARGS=CESAMN,                        < CES STARTUP MAIN CLASS
  000013 //   REGSIZE='0M', < EXECUTION REGION SIZE
  000014 //   LOGLVL='+I', < Debug LVL: +I(info) +T(trc)
  000015 //   LEPARM='ENVAR(_EDC_UMASK_DFLT=000)'
  000016 //JZOS     EXEC PGM=JVMLDM&VERSION,REGION=&REGSIZE,
  000017 //   PARM='&LEPARM/&LOGLVL'
  000018 //SYSPRINT DD SYSOUT=*          < System stdout
  000019 //SYSOUT   DD SYSOUT=*          < System stderr
  000020 //STDOUT   DD SYSOUT=*          < Java System.out
  000021 //STDERR   DD SYSOUT=*          < Java System.err
  000022 //STDENV   DD DISP=SHR,DSN=&QUAL..CNTL(&ENV)
  000023 //MAINARGS DD DISP=SHR,DSN=&QUAL..CNTL(&ARGS)
  000024 // PEND
  Important
  Applicable to both CESBATCH and CESTASK:
  The jobname of the parent is propagated to the child and appended with a numeric value in the range of 1-9, if the jobname is 7 characters or less. If the jobname is 8 characters, the jobname is propagated as is. When a jobname is appended with a numeric value, the count wraps back to 1 when it exceeds 9.
  Security must be accounted for when using less than eight characters for TCP/IP port transmissions. This is used for the SMF Manager port and any processes for asynchronous profile processing.

Starting BMC Compuware Enterprise Services as a batch job

Start CES using one of the following methods:

Batch Method--Submit the JCL from member CESBATCH
Started Task Method--Start the system task (CESTASK - described below), to start CES.

Important

CES must be restarted after applying maintenance. The CES web server will exit with a return code 3. You should configure the CES started task to restart when it gets a return code 3 using your site’s standards.

Starting BMC Compuware Enterprise Services as a started task

You can, optionally, set up CES to execute as a started task on your z/OS system by adding the start command to the SYS1.PARMLIB(COMMNDxx) member. Your installation may require special security authorizations for the started task to execute. You can also rename the PROC at your discretion so that the long-running task is identifiable as the CES Manager (for example: CESTASK) or to match your systems standards.

Important

C The started task userid must have access to the CES files and directories. You may encounter errors when starting CES if the userid does not have such authority. We therefore recommend changing all the CES directories and files to be owned by the started task userid.

Execute the following change owner command from a USS command prompt such as OMVS.

cd <top-level-CES-install-directory>
chown -R <started-task-userid> *

In this setup, you would only have to start the CES Manager the first time with a z/OS console command:

START JZOSPROC

START CESTASK

For stopping the CES Manager, you can cleanly terminate it by using the following console command:

STOP JZOSPROC

STOP CESTASK

The started task userid must have access to the CES files and directories. You may encounter errors when starting CES if the userid does not have such authority. We therefore recommend changing all the CES directories and files to be owned by the started task userid.

Execute the following change owner command from a USS command prompt such as OMVS.

cd <top-level-CES-install-directory>
chown -R <started-task-userid> *

Additional (optional) parameters

Changing the following parameters is optional.

Changing the time zone for CES

The member name CESEMN defines the Time Zone variable.

Example

TZ = EST5EDT

EST is Eastern Standard Time
Standard Time is 5 hours west of the universal reference time
EDT is Eastern Daylight Savings Time

For more information on setting time zones in CES, see IBM’s z/OS Information Center on the web.

Modifying Java Heap Size for CES

The member name CESEMN defines the startup options. The CES Server is configured with an initial heap size of 256 MB (java option = '-Xms256M') and a maximum heap size of 1536 MB (java option = '-Xmx1536m').

To modify these parameters:

Stop the CES Server.
Locate the following two lines in member CESEMN.
# INSTALLER: Sets java heap allocation if more becomes necessary
DEFS="-Xms256m"
Make the appropriate changes to the heap size
Restart CES.

Modifying BMC Compuware Enterprise Services to accommodate PassTicket

This member defines the APPLID and the user ID for PassTicket.

To add these parameters:

Stop the CES Server.
Locate the following line in member CESEMN.
#--REQUIRED-- custom CES definitions for the runtime environment
Add the following lines after the line identified above.

The following line is required:
DEFS="$DEFS -Dces.passticket.db2.applid=<PassTicket application id>"

The following line is optional. If not specified, it defaults to the value of the system property “user.name”:
DEFS="$DEFS -Dces.passticket.db2.userid=<PassTicket user id>"
Restart CES.

For more information on setting up PassTickets, see the following two IBM specific documents:

“Defining Profiles in the PTKTDATA Class” in the IBM manual z/OS V1R12.0 Security Server RACF Security Administrator's space
“R_ticketserv (IRRSPK00): Parse or extract” in the IBM manual z/OS V2R1.0 Security Server RACF Callable Services

Upgrading

This guides you through the process for upgrading CES (CES, Abend-AID Fault Analytics, Session Monitor, iStrobe,ISPWWeb, BMC ThruPut Manager Web, Topaz for Java Performance, and Topaz for Total Test).

As of CES 17.2.1, a CES maintenance/update file is available for upgrading CES and installed products.

Roles involved

The following individuals are involved with this milestone:

Systems administrator and possibly a database administrator.
Security administrator, if security is enabled.

Planning

Before beginning the upgrade, you should have the following:

For your environment, you should use the same space allocations as identified in thePlanningsection of this installation space.
When upgrading CES using Update Center (17.2.3 and higher), the CES data folder must be at least 1 GB to accommodate the CES maintenance file. The file will be deleted once the upgrade is complete.
Important
For 18.2.1 or later, security settings that were enabled for iStrobe in the prior release will now be used to access CES after the upgrade. For example, if LDAP security was enabled for iStrobe 17.2.0, the LDAP ID/PW will be required to access CES. All security will now be handled through CES.

Adding new web products to an existing CES Installation

Any BMC Compuware Web products not having been previously installed with the existing CES installation can only be added through a product installation, and not through the CES maintenance/update file.