Installing Other Facilities
This chapter discusses installing other facilities of ChangeMan ZMF.
Installing XMLSERV
XMLSERV is an XML page prototype tool that you can use to experiment with XML Services. It will only return a selection list when the server (ChangeMan ZMF instance) that is selected is running.
This facility is intended for use by your ChangeMan ZMF administrator and others who want to execute ChangeMan ZMF functions from outside the ISPF interface. Most ChangeMan ZMF users will not execute XMLSERV.
Your security system should be used to protect the functionality of XML. SERLCSEC as delivered uses a class of $XMLSERV by default. If you want to use a different class, you will need to alter SERLCSEC, and assemble it, putting the resulting load module in your custom load library, concatenating in front of the supplied module.
Note
You can bring up a test or demonstration instance of ChangeMan ZMF without installing XMLSERV.
See REXX Runtime Environment for system requirements for this facility.
Follow these steps to configure and install the XMLSERV REXX exec.
-
Allocate user input and output XML libraries for XMLSERV.
Input
Recommended last DSN node: XMLINData Set Type:
Record Length:
Record Format:PDS or PDSE
255
VBOutput Recommended last DSN node: XMLOUT Data Set Type:
Record Length:
Record Format:PDS or PDSE
5000
VBNote
Any user who executes XMLSERV must have UPDATE security access to the XML input and output data sets.
-
Copy member XMLSERV from the delivered SERCOMC CLIST library to your custom CLIST library.
-
Edit member XMLSERV in your custom CLIST library. Set the REXX variables in XMLSERV as follows.
Variable Value serparm Code the same library name as you coded in the SERNET started task JCL at DD name SER#PARM if used, or the name of the dataset you are using with manual updates. xmlinds Code the user XML input data set name. Use TSO data-set-name format: enclose the data set name in single quotes if you want it unmodified or leave out the quotes to have the user's TSOID (or ZPREFIX) as the highlevel qualifier. If you have users wiath a TSO profile value of NOPREFIX, you will need to allow for that. xmloutds Code the user XML output data set name. Use TSO data-set-name format: enclose the data set name in single quotes if you want it unmodified or leave out the quotes to have the user's TSOID (or ZPREFIX) as the highlevel qualifier. If you have users wiath a TSO profile value of NOPREFIX, you will need to allow for that. subsys Code the subsystem ID of the ChangeMan ZMF started task where you want to connect. The subsystem ID that you code here is the default when you execute XMLSERV, but you can change the subsystem ID on the panel when XMLSERV is running. If the started task is not running, you will get an empty list. sysout Code the sysout class. somnode Change all dataset names that have somnode to point to your ChangeMan ZMF delivered libraries. xamver Do not change. xmlver Do not change. product Do not change. test Do not change. Use T for test mode only under the direction of Micro Focus Customer Care.
When ChangeMan ZMF is running, you can execute XMLSERV from the ISPF Command Shell. For example, using the name of the custom CLIST library from "Step 1: Allocate CUSTOM Libraries", execute the following command:
EX ’somnode.CMNZMF.VvRrPp.CUSTOM.CLIST(XMLSERV)’
...
Caution
XML services are intended for use by ChangeMan ZMF administrators and by technicians responsible for developing custom uses for ChangeMan ZMF internal functions.
-
Do not put the compiled REXX for XMLSERV in a public CLIST or REXX library or in a library included in the SYSPROC or SYSEXEC concatenations for the general population of TSO users.
-
Do not install XMLSERV for a production instance of ChangeMan ZMF.
-
XMLSERV uses module SERXMLBC. Execution of SERXMLAC, SERXMLBC, SERXMLCC and SERXMLRC now require authorization.
Installing CICS NEWCOPY Support
You must install ChangeMan ZMF components in CICS before you can use options OPS, OPQ, and XCI for NEWCOPY. You must also install CICS components that support the CICS external call interface (ECI) before you can use the XCI method.
Read topic "CMNCICS1 - CICS NEWCOPY" in the ChangeMan ZMF Customization Guide before you execute the procedures in this section.
If the default transaction IDs (SEMT, SEMQ, and SEML) or Transient Data Queue names in the examples below conflict with existing definitions in your CICS environment, you can change the first three characters of these ZMF resources by using the prefix subparameter of the CMMCICS1 PARM= statement, or by using the PREFIX= keyword parameter that is input to the SYSIN DD statement for CMNCICS1. See subtopics "PARM Options" and "SYSIN Parameters" in topic "CMNCICS1 - CICS NEWCOPY" in the ChangeMan ZMF Customization Guide.
Installing NEWCOPY Option OPS
Execute these steps to enable the newcopy option OPS.
-
Define transID SEMT and program CMNEMTP in group ZMFgrp, either manually using CEDA or as input to DFHCSDUP:
DEFINE TRANSACTION(SEMT) GROUP(ZMFgrp) PROGRAM(CMNEMTP) TWASIZE(0) PROFILE(DFHCICST) STATUS(ENABLED) TASKDATALOC(ANY) TASKDATAKEY(USER) STORAGECLEAR(NO) RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO) ROUTABLE(NO) PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES) CONFDATA(NO) OTSTIMEOUT(NO) ACTION(BACKOUT) WAIT(YES) WAITTIME(0,0,0) RESSEC(NO) CMDSEC(NO) DEFINE PROGRAM(CMNEMTP) GROUP(ZMFgrp) LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY) EXECKEY(USER) CONCURRENCY(QUASIRENT) API(CICSAPI) DYNAMIC(NO) EXECUTIONSET(FULLAPI) JVM(NO) JVMPROFILE(DFHJVMPR)
-
Install ZMFgrp using CEDA, or add ZMFgrp to a lists of resource definition groups and ensure that the list is in the GRPLIST CICS startup parameter.
-
Either add the CMNZMF LOAD library to the DFHRPL concatenation for the target CICS region (preferred), or copy load module CMNEMTP from the CMNZMF LOAD library to a library in the DFHRPL concatenation.
Installing NEWCOPY Option OPQ
Execute these steps to enable the NEWCOPY option OPS.
-
Define transID SEMQ and program CMNEMTP in group ZMFgrp, either manually using CEDA or as input to DFHCSDUP:
DEFINE TRANSACTION(SEMQ) GROUP(ZMFgrp) PROGRAM(CMNEMTP) TWASIZE(0) PROFILE(DFHCICST) STATUS(ENABLED) TASKDATALOC(BELOW) TASKDATAKEY(USER) STORAGECLEAR(NO) RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO) ROUTABLE(NO) PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES) CONFDATA(NO) OTSTIMEOUT(NO) ACTION(BACKOUT) WAIT(YES) WAITTIME(0,0,0) RESSEC(NO) CMDSEC(NO) DEFINE PROGRAM(CMNEMTP) GROUP(ZMFgrp) LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY) EXECKEY(USER) CONCURRENCY(QUASIRENT) API(CICSAPI) DYNAMIC(NO) EXECUTIONSET(FULLAPI) JVM(NO) JVMPROFILE(DFHJVMPR)
-
Install ZMFgrp using CEDA, or add ZMFgrp to a lists of resource definition groups and ensure that the list is in the GRPLIST CICS startup parameter.
-
Either add the CMNZMF LOAD library to the DFHRPL concatenation for the target CICS region (preferred), or copy load module CMNEMTP from the CMNZMF LOAD library to a library in the DFHRPL concatenation.
Installing NEWCOPY Option XCI
For information about activating the EXCI CALL interface on your z/OS sysplex, see the CICS Transaction Server for z/OS CICS External Interfaces Guide.
Execute these steps to enable the NEWCOPY option XCI.
-
Define dummy transID SEML, program CMNEMTP, connection SEMC , and session SEMC in group ZMFgrp, either manually using CEDA or as input to DFHCSDUP:
DEFINE TRANSACTION(SEML) GROUP(ZMFgrp) DESCRIPTION(DUMMY TRANID FOR XCI SESSION) PROGRAM(DFHMIRS) TWASIZE(0) PROFILE(DFHCICSA) STATUS(ENABLED) TASKDATALOC(BELOW) TASKDATAKEY(USER) STORAGECLEAR(NO) RUNAWAY(SYSTEM) SHUTDOWN(DISABLED) ISOLATE(YES) DYNAMIC(NO) ROUTABLE(NO) PRIORITY(1) TRANCLASS(DFHTCL00) DTIMOUT(NO) RESTART(NO) SPURGE(NO) TPURGE(NO) DUMP(YES) TRACE(YES) CONFDATA(NO) OTSTIMEOUT(NO) ACTION(BACKOUT) WAIT(YES) WAITTIME(0,0,0) RESSEC(NO) CMDSEC(NO) DEFINE PROGRAM(CMNEMTP) GROUP(ZMFgrp) LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY) EXECKEY(USER) CONCURRENCY(QUASIRENT) API(CICSAPI) DYNAMIC(NO) EXECUTIONSET(FULLAPI) JVM(NO) JVMPROFILE(DFHJVMPR) DEFINE CONNECTION(SEMC) GROUP(ZMFgrp) DESCRIPTION(CONNECTION FOR XCI NEWCOPY FUNCTION) ACCESSMETHOD(IRC) PROTOCOL(EXCI) CONNTYPE(GENERIC) SINGLESESS(NO) DATASTREAM(USER) RECORDFORMAT(U) QUEUELIMIT(NO) MAXQTIME(NO) AUTOCONNECT(NO) INSERVICE(YES) ATTACHSEC(IDENTIFY) BINDSECURITY(NO) USEDFLTUSER(NO) XLNACTION(KEEP) DEFINE SESSIONS(SEMC) GROUP(ZMFgrp) DESCRIPTION(SESSION DEFINITION FOR XCI NEWCOPY FUNCTION) CONNECTION(SEMC) PROTOCOL(EXCI) MAXIMUM(0,0) RECEIVEPFX(RG) RECEIVECOUNT(4) SENDSIZE(4096) RECEIVESIZE(4096) SESSPRIORITY(0) AUTOCONNECT(NO) BUILDCHAIN(YES) USERAREALEN(0) IOAREALEN(4096,4096) RELREQ(NO) DISCREQ(NO) NEPCLASS(0) RECOVOPTION(SYSDEFAULT)
Note
The definition for transaction SEML uses default CICS profile DFHCICSA because that profile includes INBFMH(ALL).
-
Install ZMFgrp using CEDA, or add ZMFgrp to a lists of resource definition groups and ensure that the list is in the GRPLIST CICS startup parameter.
-
If the batch job that executes CMNCICS1 runs on an LPAR that does not have at least one CICS region with IRC=YES specified, you must generate an appropriate EXCI options module (DFHXCOPT) into a data set that is in the CMNCICS1 JOBLIB or STEPLIB concatenation.
//DOIT EXEC PROC=DFHAUPLE,NAME=SDFHEXCI,INDEX='SYS2.CICSTS22.CICS' //ASSEM.SYSUT1 DD * DFHXCO TYPE=CSECT, * TIMEOUT=0, No timeout * TRACE=OFF, Only Exception trace entries * TRACESZE=16, 16K trace table * DURETRY=30, Retry SDUMPS for 30 seconds * TRAP=OFF, DFHXCTRA - OFF * GTF=OFF, GTF - OFF * MSGCASE=MIXED, Mixed case messages * CICSSVC=216, EXCI WILL OBTAIN CICS SVC NUMBER * CONFDATA=SHOW, Show user commarea data in trace * ABENDBKOUT=NO, No global backout @BA17427 * SURROGCHK=YES Perform surrogate-user check @P1C END DFHXCOPT //LNKEDT.SYSLMOD DD DSN=CMNTP.CICSTS22.CICS.SDFHEXCI,DISP=SHR
Important
For critical information about DFHXCOPT, see the chapter titled "Using the EXCI options table, DFHXCOPT" in the CICS Transaction Server for z/OS CICS External Interfaces Guide.
-
Either add the CMNZMF LOAD library to the DFHRPL concatenation for the target CICS region (preferred), or copy load module CMNEMTP from the CMNZMF LOAD library to a library in the DFHRPL concatenation.
-
Include the SDFHEXCI load library in the JOBLIB or STEPLIB concatenation for the CMNCICS1 batch job step.
Installing CICS BUNDLE and PIPELINE Support
As above for NEWCOPY support, BUNDLE support also requires that you install ChangeMan ZMF components in CICS for both XCI and OPx interfaces. You must also install CICS components that support the CICS external call interface (ECI) before you can use the XCI method. CMNBUND is a new program driven by a new transaction code SEMB. Refer to the Customization Guide section on CMNCICS1 for more information.
Configure Automated Operations Tools
Configure your automated operations tools to:
-
Recognize SERNET and ChangeMan ZMF messages written to console log.
-
Issue notifications or execute remedial tasks.
See Console Log Messages for more information.
Configure zMobile
The zmobile application must be configured before it can be used. All ChangeMan Web Applications have been updated to use a common mechanism for parameter values.
Parameters are passed by adding the -DZMFPARMS="filename" parameter to the java startup process. An internal file (servlet.properties) is used by default when the ZMFPARMS is not specified. When running on Z/OS, the DDNAME ZMFPARMS is used as the default.
For zMobile application, the following parameters may be specified in ZMFPARMS:
-
ZMFNAME - Friendly name of ZMF Task
-
ZMFPORT - ZMF Port Number
-
ZMFHOST - ZMF Host Address
See the REST Services Getting Started Guide for details of the way the started task is set up. The parameters required for zmobile that are not listed in the REST Services Getting Started Guide start with ZMFWS.
You must also configure your adminstration options to use these zMobile settings. Refer to the Administrator’s Guide, Chapter 4, Global Parameters part 8 of 8, panel CMNGGP08.
Install and Configure Health Checks
ChangeMan ZMF can now optionally interface to the IBM Health Checker address space (HZSPROC).
It is assumed that the IBM Health Checker facility has already been enabled for the many health checks implemented by IBM over the years.
Deliverable Components
The components executed from within the ZMF started task are delivered with the product executables as normal.
The Health Check REXX execs are compiled and delivered in the CEXECVB distribution library, this library must be made available to the System REXX address spaces (see below).
There is one user modifiable REXX exec (called MFZMFINI) where local environment settings (dataset names) can be made. This is delivered in the ZMF REX distribution library and must be copied into a REXX library known to the System REXX address spaces (again, see below).
There is one 'data only' load module which must be copied to a library to which the IBM Health Checker address space (HZSPROC) has access. This is the message table, CMNHCMSG, which is delivered in the CZMF/LOD distribution library.
Security
The HZSPRINT utility is used to report on health check output stored internally by the HZSPROC address space and the SDSF CK facility is used to access and manipulate health check output and definitions directly. In order to use these facilities, you need to define (and grant access to) the relevant XFACILIT class profiles (for full details see the IBM documentation).
For the ZMF health checks these are (for all LPARs):
-
HZS.*.MICROFOCUS_ZMF.QUERY
-
HZS.*.MICROFOCUS_ZMF.MESSAGES
-
HZS.*.MICROFOCUS_ZMF.ACTIVATE
-
HZS.*.MICROFOCUS_ZMF.REFRESH
-
HZS.*.MICROFOCUS_ZMF.DEACTIVATE
-
HZS.*.MICROFOCUS_ZMF.DELETE
-
HZS.*.MICROFOCUS_ZMF.RUN
-
HZS.*.MICROFOCUS_ZMF.UPDATE
The ZMF health checks, when running, contact the target ZMF subsystem using the userid provided in the MFZMFINI exec variable adminUserid. As the variable name suggests, it should be a global administrator id and it should also be a trusted userid (i.e. eligible for impersonation).
The MFZMFINI exec must be edited further to supply site values for where both
SERHCPOL and SERXMLRC can be found, variable serloadDsn and to supply the relevant SER#PARM dsname, variable serparmDsn. These can be varied by supported ZMF software version (although, right now, there is only one i.e. Version 8.2 Patch 1, i.e. 8201). The most current software level should be represented in the default section of MFZMFINI.
System REXX must be active and the REXXLIB concatenation must include the EXEC library for the member MFZMFINI as well as the CEXECVB library for health check
routines. The parmlib member AXR00 is usually used to define the REXXLIB concatenation. There is only one clear text exec to consider, i.e. MFZMFINI and this could be copied into a pre-existing library (e.g. USER.DEV.SAXREXEC) then only the delivered compiled REXX library needs to be added to the REXXLIB concatenation, e.g.
REXXLIB ADD DSN(somnode.CMNZMF.CEXECVB)
REXXLIB ADD DSN(USER.DEV.SAXREXEC)
REXXLIB ADD DSN(USER.PROD.SAXREXEC)
The CMNHCMSG load module must be copied from the ZMF LOD (somnode.CMNZMF.LOD) distribution library into a library from where it can be loaded by the HZSPROC STC.
Any changes to the delivered health check definitions, for example checks may be inactivated, may be implemented via POLICY statements using the HZSPRMxx parmlib member.
Example of an HZSPRMxx member:
You can inactivate any of the supplied Health Checks by means of Health Checker Policy definition updates made in parmlib. For example, to prevent the primary DB2 check from running a parmlib member (e.g. HZSPRM99) needs to be set up to look like this:
/* ---------------------------------------------------------------- */
/* */
/* MicroFocus Health check Policy updates */
/* */
/* Sample to show how one could disable one of the */
/* supplied health checks. */
/* */
/* ---------------------------------------------------------------- */
ADD POLICY STMT(MFDB2)
UPDATE CHECK(MICROFOCUS_ZMF,PRIMARY_DB2_AVAILABLE)
INACTIVE
DATE(20180821)
REASON('Do not check primary DB2')
...
The date needs to be set to any date later than that specified in the definition of the check. However, as the check definition date was set prior to this level of ZMF being made generally available then today's date will work.
This change can either be incorporated on a permanent basis by adding the suffix (i.e. 99 in this case) to the list of members referenced by HZSPROC when it starts up (e.g. HZS=(00,xx,yy,99)). Or it can be applied dynamically using the modify command:
F HZSPROC,ADD,PARMLIB=(99)
With this policy in place this healthcheck (MICROFOCUS_ZMF,PRIMARY_DB2_AVAILABLE), will not be run when ZMF is started up.
Package Master file conversion
Program CMNCP821 has been created to ensure that the global admin 'Run Health Check' option is set off when customers first convert to 8.2 patch1 (see the ChangeMan ZMF Migration Guide for further details).
Currently supplied health checks in CEXECVB
MFZMF010 - run once for all eligible ZMF subsystems on the local LPAR when any eligible ZMF subsystem starts up. Can also be run on an ad hoc basis using the SDSF CK panel (or equivalent MVS modify command). All health checks are defined in this fashion unless stated otherwise below. This check ensures that, where the DB2 option is licensed, the primary DB2 subsystem is available and that we can access the DB2 option tables.
MFZMF020 - If any HLL exits are active this check ensures that the relevant HLLX started task is active.
MFZMF030 - Checks the TCP/IP environment is correct for use by ZMF and its clients.
MFZMF040 - This check is run every 10 minutes for all eligible ZMF subsystems, it requires a minimum level of SDSF of 2.3. It checks storage usage and flags an exception if either (or both of) the private or extended private area is more than 90% in use.
Activating and Inactivating health checks:
Health checks can be disabled on a ZMF instance by ZMF instance basis by using the XML parameter
<runHealthChecks>N</runHealthChecks>
Alternatively you can also activate and inactivate via the Global Admin panel CMNGGP05 (=A.G.1) thus:
CMNGGP05 Global Parameters - Part 5 of 8
Command ===>
Audit package lock . . . . OPTIONAL (Always/Never/Optional)
Enter "/" to select option
__ Job name increment override
__ Use zprefix in batch jobs
__ Suppress msgs in dis/ins/bas jobs
__ Create component work records
__ Memo delete empty packages only
/ Enable package user variables
/ Enable component user variables
__ Add user variables to package list table
__ Allow component in multiple applications
__ Allow component name in multiple applications
__ Auto scratch load member with source
/ Run health checks
__ Approval Restrictions
__ Package creator cannot approve
__ Package worker cannot approve
__ Only 1 approval per user
The help screen shows this information:
Run health checks
This option indicates whether supplied Health Check routines are eligible to be run against this ZMF subsystem.
Testing
Use ISPF or XML services to enable health checks at your target ZMF subsystems.
Re-start the subsystem(s) and use SDSF CK to view results. Note that 'ONETIME' health checks can be run again any time you like by using the R line action code against the health check as shown in the CK display.
The STC log should show in SERPRINT:
On Startup -
CMNI478I CMNSTART Delay file processing complete CMNI521I CMNHCHEK ZMF Health Check exit CMNHCADD is not present. CMNI525I CMNHCHEK Health Check exit CMNHCADD was added successfully. CMNI526I CMNHCHEK ZMF Health Checks have been scheduled.
On Shutdown -
CMNI483I CMNSTART Termination of HLL exit address space complete. CMNI531I CMNHCHEK Health Check exit CMNHCADD has been removed.
Example of contents of the MFZMFINI file:
BROWSE USER.DEV.SAXREXEC(MFZMFINI) - 01.09 Line 00000000 Col
Command ===> Scroll =
********************************* Top of Data *************************
/**REXX **************************************************************/
/* */
/* Copyright 2018- (C) SERENA Software, Inc. */
/* Licensed material. All rights reserved. */
/* ChangeMan is a registered trademark of SERENA (R) Software Inc. */
/* */
/* Exec name: MFZMFINI */
/* */
/* ZMF Health Check - set local site variable values */
/* */
/* Always set the default variables to represent the latest version */
/* of ZMF you have installed. You can support earlier versions */
/* of ZMF using the conditional sections that follow on. */
/* */
/* Supported versions are: */
/* 8201: v8.2 patch 1 */
/* */
/*********************************************************************/
arg vrmp
Default:
serloadDsn = "USER.PRD.ZMF821.LINKLIB"
serparmDsn = "CMN.CMN821.TCPIPORT"
adminUserId = "USER015"
/* 8.2 patch 1 */
If vrmp = "8201" then
Do
serloadDsn = "USER.PRD.ZMF821.LINKLIB"
serparmDsn = "CMN.CMN821.TCPIPORT"
adminUserId = "USER015"
End
/*********************************************************************/
/* */
/* ==>Do not change the order of the push statements <=== */
/* */
/*********************************************************************/
push serloadDsn
push serparmDsn
push adminUserId
Exit
******************************** Bottom of Data ***********************
Admin Userid (adminUserId above) for ZMF XML
The IBM Health Checker invoked system REXX execs run with the userid of the HZSPROC address space. The ZMF health check execs need to set a genuine userid with the authority to run the XML requests (usually a global administrator id). This userid must be permitted to use the 'user impersonation' facility implemented by Sernet.
ChangeMan ZMF health checks make use of System REXX. The execs run in a system started address space named AXRnn. In this example, AXR00 shows the names of the datasets being retained, which should be the same as defined in the MFZMFINI member:
AXRNN WAS EXPANDED USING SYSTEM LIBRARY SYS1.IBM.BLDJ.PROCLIB
...
IGD103I SMS ALLOCATED TO DDNAME SERLOAD
IGD103I SMS ALLOCATED TO DDNAME SER#PARM
IEF237I JES2 ALLOCATED TO SERPRINT
IGD104I USER.PRD.ZMF821.LINKLIB RETAINED, DDNAME=SERLOAD
IGD104I CMN.CMN821.TCPIPORT RETAINED, DDNAME=SER#PARM
IEF285I HZS.AXR00.S0274088.D0000101.? SYSOUT