Skip to content

Installation and Configuration

This chapter presents an overview of steps to install and configure.

Pre-requisites

Important

ChangeMan ZMF 8.2 Patch 4 is a requirement.

Sufficient memory - the Tomcat JVM startup can fail due to a restriction on memory imposed by local exits (e.g. IEFUSI or IEALIMIT etc.). The actual amount of storage needed during initialization varies but is in the region of between 550 and 700 Mb depending on several factors including which version of z/OS you are running. If you do not allow the address space to get the storage it needs then it will fail during initialization, possibly with symptoms including rc=100 and java.lang.OutOfMemoryError: Failed to create a thread.

Note also the external requirements listed at External 3rd Party Dependencies.

Instructional Video Library

You can get further information from the following instructional videos:

  • Introduction to ZMF REST Services (https://youtu.be/4q1b5Ya1Mzs)

  • How to Subscribe to a webhook using ZMF REST Services (https://youtu.be/dU9v7EEKvWQ)

  • An Overview of a Sample Jenkins Process (https://youtu.be/4lEKJimFk9Y)

  • ZMF REST Services Overview (https://youtu.be/gyGk3PCJd-A)

  • How to Store ZMF Credentials for Jenkins (https://youtu.be/ZA5CtfR_IfY)

  • How to Install ZMF REST Server Support (https://youtu.be/mFSU0DYkAdE)

  • How to Activate and Use ZMF REST Server (https://youtu.be/XjNh1SojFcg)

Security set up

You will be creating a Tomcat started task as part of this installation. This started task needs to be assigned a userid with a valid OMVS segment. To allow the file permissions on the Tomcat install directories/files to work best you should ensure that the started task userid is connected to a group that has an OMVS gid associated with it. The userid submitting the install job must also be connected to this group.

Note that neither the started task userid nor the group to which it is connected needs any kind of ZMF authority. The stc userid/group need only have full access to the directories and libraries which are part of the Tomcat installation process.

Run INSTALL Job

Change the job card in the sample JCL INSTALL member to suit your site. Make sure you specify the GROUP parameter to be the common group to which the started task userid and the installer userid are connected.

Set the JCL symbolic parameters to reflect your choice of location for the Tomcat install, e.g.

// SET INSTJCL=<dsnHLQ>.ZMF822TC.CNTL
// SET TCHOME='/usr/tomcat'
// SET SUBDAT='/usr/data'
// SET TDIR='/tmp'

&INSTJCL is the sample install JCL library. This library also contains the ZMFPARMS member which will be referenced by the Tomcat started task. &TCHOME is where the Tomcat executables, and subsequently deployed application archives, will be stored.

The &SUBDAT directory should be specified to be outside of the Tomcat install directory structure (&TCHOME). It will eventually contain your event subscribers data file.

Then run the Install job which should complete with all step return codes=0.

The /usr/tomcat directory should then be populated.

Locate JZOS Batch Loader (JVMLDM86)

Locating JVMLDM86 - JVMLDM86 is an executable module is supplied by IBM as part of their Java implementation and may well have already been copied to a PDSE by your site. If it hasn't then you can do this with the following USS process:

cd /usr/lpp/java/J8.0_64/mvstools cp -X JVMLDM86 "//'CMNTP.JZOS.LOADLIB(JVMLDM86)'"

Create the Started task proc

Update the TCPROC member to set the CNFGLIB and JZOSLIB variables to your libraries. The JZOSLIB is where you have the JVMLDM86 load module, e.g. CMNTP.JZOS.LINKLIB, and then place this member in a system proclib to be run as a started task.

//TCPROC   PROC   CNFGLIB=CMNTP.TOMCAT.ZMF822TC.C7.CNTL,  config XML & env script 
//   TCENV=TCENV,                       < Member of CNFLIB with STDENV script
//   JZOSLIB=CMNTP.JZOS.LOADLIB,        < JZOS launcher PDSE LIB
//   VERSION='86',                      < JZOSVM version: 70,76,80,86

Update Environment settings

Then update the TCENV member with appropriate values, for example: 

export JAVA_HOME=/usr/lpp/java/J8.0_64
CATALINA_HOME=/usr/tomcat
CATALINA_BASE=/usr/tomcat
IJO="-Xms64m -Xmx128m"  # min and max Java heap sizes

Choose the ports on which you want tomcat to listen, and update the SERVVARS member, with those values, for example:

<!ENTITY httpPort "8085">              <!-- the Tomcat HTTP port        -->
<!ENTITY httpPorts "9992">             <!-- the Tomcat HTTP SSL port    -->

Update the ZMFPARMS member - parameters are described within the member including the default values if any.

The Subscribers.dat file will be created by the zmfrest application if it is not there (i.e. on first start up). This is where the event subscriber information is held and there should be a unique location for each REST server application that is deployed (see later for information on deploying multiple applications).

Start Tomcat

When this has been done you can start the TomCat started task to verify success. Look out for security errors which will occur if the permissions are not right:

ICH408I USER(SERT    ) GROUP(CMNTP   ) NAME(CHANGEMAN TECH PUBS ) 457 
  /u/sert/Q001/TomCat/logs/localhost_access_log.2019-09-17.txt        
  CL(DIRACC  ) FID(01E2D9C8C6E2F5000F04000688610000)
  INSUFFICIENT AUTHORITY TO OPEN 
  ACCESS INTENT(-W-)  ACCESS ALLOWED(OTHER      R-X)
  EFFECTIVE UID(0000000586)  EFFECTIVE GID(0000000024)

Issue the STOP command to shutdown Tomcat

Deploy .war files

Edit the DEPLOY member for the zmfrest war file which copies the .war file to the webapps folder.

As soon as TomCat detects the presence of the .war files it starts activating the relevant servlets.

Enable in ZMF Admin

Once TomCat is running and the servlets are ready, Then the next step is to enable the interface in the ZMF Global Administration Options facility (=A.G) panel CMNGAMN1.

CMNGAMN1          Update Global Administration Options                
Option ===>___________________________________________________________
1  Parms          Global parameters                                      
2  Library        Library types                                          
3  Language       Language names                                         
4  Procedures     Compiling procedures                                   
5  Reason Codes   Reason codes for unplanned packages                    
6  Sites          Site information                                       
7  Lock           Application parameter locks                            
8  HLL Exits      High level language exits                              
9  Field Names    User field name substitution                           
C  Component      Component information                                  
D  Dates          Installation calendar                                  
E  REST           REST api server                           
H  Housekeeping   Housekeeping tasks                                     
I  Impact         Impact Analysis                                        
N  Notify         Global notification file                               
O  Options        Selectable options                                     
R  Reports        ChangeMan ZMF batch reports                            
S  Skeletons      Skeleton procedures

Select option E - REST api server and then you will see panel CMNGRS01:

CMNGRS01                 REST api server                                
Command===> ___________________________________                        


       Server procedure . . SERDTCI
                address . . d001.microfocus.com
                   port . . 09992
                context . . zmfrest

    http send time-out . . 0000008    
    http recv time-out . . 0000008

Enter / to select option
    _ Issue start command for procedure?
    _ Server active?
    / Poll for server using http?

    / Apply saved admin settings

This allows you to maintain the values used by the ZMF REST api servers. To save all changes and leave this panel use PF3/end. To discard all changes and leave use the CANCEL primary command. ENTER redisplays the panel with the same values, nothing is saved.

Item Description
**Server procedure The name of the cataloged procedure which is used by ZMF to start the Tomcat started task which will host the REST api server.
**address The DNS name or IP address of the server.
**port The port number on which the server is listening.
**context The context used by the REST api servlet running in the server address space. The default is zmfrest.
**http send time-out The send time out value (in seconds) applied to connections from internal ZMF functions to the REST api server. The range is 1 - 2678400 and the default is 2 seconds.
**http recv time-out The receive time out value (in seconds) applied to connections from internal ZMF functions to the REST api server.

The range is 1 - 2678400 and the default is 2 seconds.
**Issue start command for procedure? Use '/' to have ZMF issue the start command for the Tomcat procedure. If the REST api server is required to be active then ZMF will issue the start command during initialization if it cannot detect the presence of the relevant servlet. The same is true should these admin definitions be applied 'in-flight'. Only select this option if you wish to run your Tomcat started task on the same LPAR as this ZMF instance.
**Server active? Use '/' to activate REST server support within this ZMF instance. Turning this on will prompt ZMF to fill in relevant ISPF skeleton and HLLX REXX variables supporting the event emission processes. It will also cause ZMF to actively look for the presence of the relevant Tomcat hosted REST servlet.
**Poll for server using http? Use '/' to require ZMF to issue http requests to detect the presence of the REST server. The default detection process is via a sysplex wide enqueue mechanism which is more efficient than using http. However, if your Tomcat started task is not running on the local sysplex then the http mechanism must be used.
**Apply saved admin settings Once any updates have been made the dialog will use the REFRESH service to take the actions required to apply the settings, e.g. start the server, as required.

This completes the TomCat install and initial configuration.

Simple Installation Verification Procedure

With your ZMF instance up and running and the tomcat web apps configured correctly in ZMF Global Admin, you should be able to contact your target ZMF with a REST call. Use the / zmfrest/list url to get a list of ZMF REST api's up, an example: http://d001.microfocus.com:8085/zmfrest/list

You can logon to your target ZMF using your TSO userid and password and then try driving one of the apis via the 'prototyping' facility, for example:

Scroll down to find the 'Parms' category, then open up the two apis by clicking the row.

Get the global parameters for your target ZMF subsystem. This API requires no parameters (there is only one set of global parms) so clicking the 'Test' button on the right brings up the next panel where you would normally specify parameters (there are none for this call), then click on the ’Test API’ button on that panel.

You should receive a list of global parameters for your target ZMF subsystem in JSON format looking similar to this:

Running multiple instances of ZMF

The Tomcat started task will support multiple instances of ZMF simultaneously. You need a different 'context' for each ZMF instance you wish to support. In order to do this you must copy the zmfrest.war file to different names within the Tomcat webapps directory, e.g. zmfrestj.war was created to support another instance (subsys=J) separately from an existing instance. Then you add context specific qualifiers to the parameters in ZMFPARMS - an example 

#
# General Parameters
#
ZMFHOST=D001.MICROFOCUS.COM
ZMFRESTHOST=D001.MICROFOCUS.COM
#
# U820ALL Parameters
#
ZMFREST.ZMFSUBSYS=I
ZMFREST.ZMFNAME=U820ALL
ZMFREST.ZMFPORT=6611
ZMFREST.ZMFEVENTFILE=/u/cmndev/tomcati/Subscribers.dat 
#
# U820DP Parameters
#
ZMFRESTJ.ZMFSUBSYS=J
ZMFRESTJ.ZMFNAME=U820DP
ZMFRESTJ.ZMFPORT=6621
ZMFRESTJ.ZMFEVENTFILE=/u/cmndev/tomcatj/Subscribers.dat

You will need to add the relevant 'log' DD name to the tomcat procedure, e.g.

//ZMFREST DD SYSOUT=*

This needs to be added for the context zmfrest, via the A.G.E panel accordingly.

Note

For a complete list of Rest Services startup parameters, see the ZMFPARMS.JCS samples file distributed with ChangeMan ZMF.