Installing BMC AMI DevX Workbench Server on z/OS UNIX System Service

This topic contains information to install the BMC AMI DevX Workbench Server on z/OS UNIX System Service (USS).

Important

You need the following expertise to install the Workbench Server on USS:

  • z/OS UNIX system administrator to install Workbench Server.
  • MVS systems programmer to set up the Workbench Server on z/OS, depending on your site standards.
  • Security Administrator

To install BMC AMI DevX Workbench Server on USS

Important

  • If your mainframe supports FTP (not SFTP) to UNIX System Service (USS), then follow steps 1 to 4. Else, use a file transfer mechanism of your choice to transfer the contents of the USS directory from the installation image to a directory of your choice on USS.
  • The install.sh and uninstall.sh scripts have Windows line endings. If you are manually uploading from Linux, you will need to run dos2unix on these scripts before uploading as binary.
  1. Click the Workbench Server tab from the product image.
    Example: <network or hard drive>:\setup.exe
  2. Click Install Workbench Server for z/OS UNIX.
    The Mainframe FTP Information tab appears.
  3. 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 Workbench Server product image to the mainframe. The install.jar and the install.sh are both uploaded as binary. 
  4. Click Upload files to mainframe to begin the upload.

  5. Log in to the mainframe and navigate to an OMVS command prompt or use any SSH client.

    Important

    For 64-bit Java, you might need to specify the region size by logging on with: logon <username> size (<desired region size>).

  6. 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>
  7. Make sure that the install.sh file has to execute authority and execute it. Perform a chmod 755 to set permissions, if necessary.
  8. Execute the install.sh file. For example: ./install.sh
    Some systems might require that you increase the Java HEAP size before running the installer. For example:
    _JAVA_OPTIONS=-Xmx512M
    The Workbench Server installer starts.
  9. 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

  10. Specify Y (Yes) or N (No) for using the system’s /tmp directory as the installation temporary space. If you have specified N, the installation launches. If you have specified Y, then you are prompted to enter an absolute directory path to a designated temporary directory space. Press Enter.

    Important

    The installer requires the use of the system temporary directory and might require up to 1,125,000 1k blocks (1375 cylinders) of pre-allocated space.

  11. The Installer launches. Read the Introduction panel and press Enter. The License Agreement panel is displayed.
  12. Read the BMCWorkbench Server  license agreement. When prompted, type Y and press Enter to accept the terms of the license agreement.
  13. Press Enter. The Choose Install Folder panel appears.
  14. Specify the absolute directory path in which to install Workbench Server, or press Enter to accept the default location (Default: /opt/BMC/WorkbenchServer).
  15. Confirm your selection. If you would like to make changes to your selection, type Back. Otherwise, press Enter.

  16. 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)

    Web Server port

    8089

  17. If you do not want to enable the SSL,  the installer skips the SSL related questions and if you want to enable it, you need to answer the following questions: 
    • Certificate alias: The alias or friendly name of the certificate to be presented to the client by the user when a connection is made (required)
    • The keystore type: We support JKS and PKCS12
      • JKS
        • Keystore location: Full path to the JKS file containing the certificate (required)
        • Keystore password: The password required to read the key store (required if JKS file is password protected)
        • Certificate password: The password for the certificate in the key store (required if the certificate is password protected)
      • PKCS12
        • Keystore location: Full path to the PKCS12 file containing the certificate (required)
        • Keystore password: The password required to read the key store (required if PKCS12 file is password protected)
        • Certificate password: The password for the certificate in the key store (required if the certificate is password protected)
  18. If you want to share the data with BMC for performance and product improvement, specify Y (Yes) else N (No).
  19. Review the installation information you selected in the Pre-installation Summary. If anything is incorrect, type Back and revise the installation settings as required. If the information is correct, press Enter to start the Workbench Server installation. The Installation Complete panel appears when the installation finishes. After exiting the installer, switch to the install directory.  Give the script copyFilestoDataSet.sh execute permissions.
    chmod 755 copyFilestoDataSet.sh    Execute the script copyFilestoDataSet.sh. Enter the High-Level Qualifier for a data set to contain the JCL and parameter files. It will allocate a PDS and copy several JCL and parameter files into members of the 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 PDS allocated will have Tnnnnnn.CNTL added to the High-Level Qualifier specified, where nnnnnn is the time the PDS was allocated.
  20. The Workbench Server installation process is complete. Continue with the next section, Preparing to start https://docs.bmc.com/docs/plugins/servlet/includeplus-macro/image?spaceKey=cwProductRef&scrollEditorDisplayTitle=_BMCAMIDevXWorkbenchServer_short&includedPageId=1122311870.

Preparing to start BMC AMI DevX Workbench Server

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

  • TPZAMN.PARMLIB
  • TPZEMN.PARMLIB
  • TPZBATCH.JCL
  • TPZTASK.JCL
  • JZOSPROC.JCL

The files that end with PARMLIB are input parameter files used to start the appropriate Workbench Server service. The files that are qualified as JCL are the PROC and JOB samples for executing on the z/OS system.

  • TPZEMN
    • 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.
  • TPZBATCH - used to run BMC Compuware Web Products as a batch job.

    • Change the job card to match your system requirements.
    • ARGS=TPZAMN is set by default to start the Workbench Server Manager.
    • Change QUAL=’HLQ1.HLQ2’ such that &QUAL..CNTL matches the name of the PDS containing the TPZBATCH member.
    • 000001 //SAMPLE0I JOB   ('ACCOUNT',78,1,1),'WORKBENCH SERVER',
    • 000002 //      CLASS=L,MSGCLASS=H,NOTIFY=&SYSUID,REGION=0M,JOBRC=LASTRC
    • 000003 //***************************************************                   
    • 000004 //*   Use TPZEMN for the env member for all uses                        
    • 000005 //*   Use ARGS="TPZAMN" to run Workbench Server
    • 000006 //***************************************************                   
    • 000007 //         SET QUAL='HLQ1.HLQ2' < PARMLIB HI-LEVEL QUALIFIER
    • 000008 //* Note: If running Workbench Server 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=&QUAL..CNTL                                 
    • 000012 //TPZSERVR EXEC JZOSPROC,ENV=TPZEMN,ARGS=TPZAMN                         
    • 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       
    • 00016 //* 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(TPZBATCH),DISP=SHR
    • 000020 //SYSUT2   DD  SYSOUT=(,INTRDR)                
    • 000021 //SYSPRINT DD  SYSOUT=*            
    • 000022 //SYSIN    DD  DUMMY
    • As shown in the JCL (TPZBATCH) above, you can insert a JCLLIB statement if you want to invoke the JZOSPROC from the &QUAL..CNTL dataset.
      For example: // JCLLIB ORDER=&QUAL..CNTL
  • TPZTASK - used to run Workbench Server as a started task.

    • Change the job card to match your system requirements.
    • ARGS=TPZAMN is set by default to start the Workbench Server Manager.
    • Change QUAL=’HLQ1.HLQ2’ such that &QUAL..CNTL matches the name of the PDS containing the TPZTASK member.
    • Upon startup, TPZTASK will print the message ‘Workbench Server has started' to both the SYSLOG and the JESMSGLOG.
    • 000001 //*   Example JCL to run TPZ 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 Workbench Server 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 TPZEMN for the env member for all uses                       

    • 000007 //*   Use ARGS="TPZAMN" to run Workbench Server
    • 000008 //***************************************************                  
    • 000009 //JLAUNCH PROC VERSION=76,                                             
    • 000010 //         QUAL='HLQ1.HLQ2', < PARMLIB HI-LEVEL QUALIFIER
    • 000011 //   ENV=TPZEMN,             < Workbench Server ENVIRONMENT INPUT       
    • 000012 //   ARGS=TPZAMN,            < Workbench Server 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

Starting Workbench Server as a batch job

Start Workbench Server using one of the following methods:

  • Batch Method--Submit the JCL from member TPZBATCH
  • Started Task Method--Start the system task (TPZTASK - described below), to start Workbench Server.

Important

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

Starting Workbench Server as a started task

Optionally, you can set up Workbench Server to execute as a started task on your z/OS system by adding the start command to the SYS1.PARMLIB(COMMNDxx) member. Your installation might 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 Workbench Server Manager (for example, TPZTASK) or to match your systems standards.

Important

The started task User must have access to the Workbench Server files and directories. You may encounter errors when starting the Workbench Server if the User ID does not have such authority. Therefore, BMC recommends changing all the Workbench Server directories and files which will be owned by the started task User ID.

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

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

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

START JZOSPROC

or

START TPZTASK

For stopping the Workbench Server, you can cleanly terminate it by using the following console command:

STOP JZOSPROC

or

STOP TPZTASK

Additional (optional) parameters

Changing the following parameters is optional.

Changing the time zone for Workbench Server

The member name TPZEMN 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 Workbench Server, see IBM’s z/OS Information Center.

Modifying Java Heap Size for Workbench Server

The member name TPZEMN defines the startup options. The Workbench 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

  1. Stop the Workbench Server.
  2. Locate the following two lines in member TPZ
  3. # INSTALLER:  Sets java heap allocation if more becomes necessary DEFS="-Xms256m"
  4. Make the appropriate changes to the heap size.
  5. Restart Workbench Server.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*