Enterprise Common Components 

Advanced Configuration Guide

Release 17.02
2 Enterprise Common Components Advanced Configuration Guide

Please direct questions about Enterprise Common Components

or comments on this document to:

Compuware Customer Support

https://go.compuware.com/

This document and the product referenced in it are subject to the following legends:

Copyright 2020 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright
Laws of the United States.

U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as
set forth in Compuware Corporation license agreement and as provided in DFARS 227.7202-1(a) and 227.7202-
3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14
(ALT III), as applicable. Compuware Corporation.

This product contains confidential information and trade secrets of Compuware Corporation. Use, disclosure, or
reproduction is prohibited without the prior express written permission of Compuware Corporation. Access is
limited to authorized users. Use of this product is subject to the terms and conditions of the user’s License
Agreement with Compuware Corporation.

Abend-AID, Abend-AID for CICS, Xpediter for TSO and for IMS, Xpediter for CICS, File-AID for MVS, File-
AID/RDX, File-AID/Data Solutions, File-AID/EX, Strobe, iStrobe, Enterprise Common Components, Topaz, Topaz
Workbench, Topaz for Enterprise Data, Topaz Total Test, ThruPut Manager, COPE, and ISPW are trademarks or
registered trademarks of Compuware Corporation.

IBM, CICS, DB2, z/OS and MVS/ESA are trademarks or registered trademarks of International Business Machines
Corp.

Adobe ® Reader® is a trademark of Adobe Systems Incorporated in the United States and/or other countries.

All other company and product names are trademarks or registered trademarks of their respective owners.

Doc. APR2020
December 21, 2020
 3

Contents
ECC Installation Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
ECC Component Prefix and FMID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Distribution and Target Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Compuware Mainframe Services Controller (CMSC) Configuration and Administration . . . . . 11

Configuring Compuware Mainframe Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
General Guidelines for PARMLIB Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
General Guidelines for PARMLIB Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Changing a PARMLIB Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Using a Non-Default CMSC or Parameter Suffix Value . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
CMSC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Other CMSC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Implementing the zIIP Enablement Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Enabling the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Disabling the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Operational Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
PARMLIB Product Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Copy Sample PARMLIB Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Update the CMSC with PARMLIB Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
CMSC Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Validate PARMLIB Member Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
CMSC Start-Up Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Default PARMLIB Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
DDSN Configuration Parameters for Simple Deploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DD_INFO Block Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Compuware Global Configuration Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

License Management System (LMS) Configuration and Administration . . . . . . . . . . . . . . . . . . 31

LMS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
LMS Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Operating Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
License Management Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Information Gathering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
License Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Migration Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Creating a License File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Verify the License File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Define Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Import License Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4 Enterprise Common Components Advanced Configuration Guide

Sample LMS Parameters Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

LMS Installation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Execution Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
The License Management System Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
License Management Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Establishing the Runtime LMS Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Validating Product Access Requests During Product Use . . . . . . . . . . . . . . . . . . . . . . 41
License Management System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
License File Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Certificate Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
LMS Event Exit Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Grace Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Checkpoint File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using LMS Client Parameters to Define the Checkpoint Dataset . . . . . . . . . . . . . . . . 43
Checkpoint Dataset Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Sharing the Checkpoint Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
History File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Grace History File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Batch (Sample Reports) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
License Verification Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Current Cache Contents Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
License File Contents Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
SMF License Records Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Product Activity Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Activity Extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Establishing Multiple LMS Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Considerations for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Establishing a Secondary LMS subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Methods to Enable Disaster Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Method 1: Emergency Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Method 2: DR Mode Batch Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Method 3: LAU ISPF Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Default Member: LMCLALL (client) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
License Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Message Suppression and Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Host Communications Interface (HCI) Configuration and Administration . . . . . . . . . . . . . . . . 67

HCI Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
HCI Installation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
System Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Security Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
For Topaz for Total Test Functional Test Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
For Top Secret Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Configuration Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Preliminary Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
 5

Connection to z/OS Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

HCI Parameter Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Topaz Workbench—CSS TP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
CICS_ENV block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
HCI_ENV block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
ISPW_ENV block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
LOCAL_ENV block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
TPT_COMMAND block parms:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
SYSLOG_IOF block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
SYSCMD_IOF block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
HCI_CONNECTION block parms:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
TSO_ENV block parms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Additional Notes for Strobe and DevEnterprise. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
HCI Operator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Additional Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Operator Commands to Control the SSAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Operator Commands for ENQ Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Setting Up an Additional HCI Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
HCIPlex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Configuring Parameters for HCIPlex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Controlling the HCIPlex With Operator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Using ENF Listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Compuware Shared Services Configuration and Administration . . . . . . . . . . . . . . . . . . . . . . . 107

CSS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
System Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
CSS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Common Files and Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
DDIO Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
CSS Utilities and Batch File Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
CSS Language Processors (LP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Language Processor Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Security Exit Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Executing CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
CSS Installation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
CICS Load Library Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
TSO Logon PROCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Sharing CSS DDIO Files With Multiple CPUs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
CSS Language Processor (LP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Pre-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Post-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Language Processor DD Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Testing and Debugging Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Debugging Production Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
CSS Sample Library Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6 Enterprise Common Components Advanced Configuration Guide

Install Customized Translation Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Prepare the DDIO Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Types of DDIO Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
File Access Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Allocate and Format Abend-AID Report Shared Directories and Databases for
Abend-AID Release 9.4 and Later Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Create the Report Shared Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Create the Report Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Allocate and Format Source Listing Shared Directories and Databases . . . . . . . . . . . . . . 122
Create the Source Listing Shared Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Create the Source Listing Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Allocate and Format Source Listing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Allocate the Source Listing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Format the Source Listing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Allocate and Format Abend-AID for CICS Shared Directories and Transaction
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Create the Abend-AID for CICS Shared Directory (Allocate & Format) . . . . . . . . . . 123
Create the Abend-AID for CICS Transaction Database (Allocate & Format) . . . . . . . 123
Implement the Language Processor JCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Modify the JCL to Run the COBOL Language Processor . . . . . . . . . . . . . . . . . . . . . . . . . 124
Preprocessor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Post-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Modify the JCL to Run the PL/I Language Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Preprocessor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Post-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Modify the JCL to Run the Assembler Language Processor . . . . . . . . . . . . . . . . . . . . . . . 127
Preprocessor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Post-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Modify the JCL to Run the C Language Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Preprocessor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Post-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
On-the-Fly Language Processing Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
CXOTFPRE & CXOTFPST Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Appendix A: Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Security Considerations for Using the JES Explorer View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Option 1: Limit user’s ability to view output using a security product. . . . . . . . . . . . . . . 133
Option 2: Limit user’s ability to cancel jobs or purge output using a security
product.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Option 3: Limit user's ability to view only their own output (no security
product setup required). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Using Conditional Access for Canceling Jobs or Purging Output via JES Explorer . . . . . . 135
Defining a Console to RACF to use Conditional Access . . . . . . . . . . . . . . . . . . . . . . 135
Controlling User Ability to View SYSLOG from JES Explorer . . . . . . . . . . . . . . . . . . . . . . 136
Controlling User Ability to Issue System Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
CXSS0000 Started-task Procedure Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 138
 7

SSAS Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Cross-LPAR Copy Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Controlling User Access to the CSS TP for Topaz Workbench Connection Port. . . . . . . . . . . . 139
Application Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Defining Application Access to your Security Software . . . . . . . . . . . . . . . . . . . . . . . . . . 140
HCI Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Top Secret Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
ACF2 Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
System Security for the HCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Considerations for Using AT-TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
8 Enterprise Common Components Advanced Configuration Guide
 9

ECC Installation Reference 1

ECC Component Prefix and FMID

Compuware has registered the following element prefixes with IBM for the ECC components:

• LCX for ECC, including all of its components

FMID for ECC:

• MLCX170 — ECC base code

• NLCX170 — ECC Japanese support

Distribution and Target Libraries

The chart lists the libraries created during the ECC installation using SMP/E.

DDname Library Type and Content Dataset Name as Distributed

Distribution Libraries
ALCXCNTL ECC Distribution Sample Library CPWR.MLCXnnn.ALCXCNTL
ALCXEXEC ECC Distribution REXX Library CPWR.MLCXnnn.ALCXEXEC
ALCXLOAD ECC Distribution Load Library CPWR.MLCXnnn.ALCXLOAD
ALCXMENU ECC Distribution English Messages CPWR.MLCXnnn.ALCXMENU
1
ALCXMJPN ECC Distribution Japanese Messages CPWR.MLCXnnn.ALCXMJPN
ALCXPENU ECC Distribution English Panels CPWR.MLCXnnn.ALCXPENU
1
ALCXPJPN ECC Distribution Japanese Panels CPWR.MLCXnnn.ALCXPJPN
ALCXSENU ECC Distribution ISPF Skeletons CPWR.MLCXnnn.ALCXSENU
ALCXSJPN ECC Distribution Japanese ISPF Skeletons CPWR.MLCXnnn.ALCXSJPN
ALCXTLIB ECC Distribution Table Library CPWR.MLCXnnn.ALCXTLIB
ALCXUSS ECC Distribution zFS File Library CPWR.MLCXnnn.ALCXUSS
Target Libraries
SLCXAUTH ECC Target APF Authorized Load Library CPWR.MLCXnnn.SLCXAUTH
SLCXCNTL ECC Target Sample Library CPWR.MLCXnnn.SLCXCNTL
SLCXEXEC ECC Target REXX Library CPWR.MLCXnnn.SLCXEXEC
SLCXLOAD ECC Target Load Library CPWR.MLCXnnn.SLCXLOAD
SLCXMENU ECC Target English Messages CPWR.MLCXnnn.SLCXMENU
1
SLCXMJPN ECC Target Japanese Messages CPWR.MLCXnnn.SLCXMJPN
SLCXPENU ECC Target English Panels CPWR.MLCXnnn.SLCXPENU
1
SLCXPJPN ECC Target Japanese Panels CPWR.MLCXnnn.SLCXPJPN
SLCXSENU ECC Target ISPF Skeletons CPWR.MLCXnnn.SLCXSENU
SLCXSJPN ECC Target Japanese ISPF Skeletons CPWR.MLCXnnn.SLCXSJPN
SLCXTLIB ECC Target CSS Utilities Table Library CPWR.MLCXnnn.SLCXTLIB
SLCXUSS ECC Target zFS File Library /usr/lpp/compuware/cx/170200/
1 These datasets are part of the Japanese Language support and are only installed if Japanese Language

support is selected.
10 Enterprise Common Components Advanced Configuration Guide

DDname Library Type and Content Dataset Name as Distributed

Note: MLCXnnn specifies the ECC release, where nnn is the ECC release number. For example,
MLCX170 indicates ECC 17.02.
 11

Compuware Mainframe Services Controller

(CMSC) Configuration and Administration 2

Configuring Compuware Mainframe Products

Once the SMP/E installation of your Compuware mainframe product(s) has completed, this section
can be used to configure and customize them.

The Compuware Mainframe Services Controller (CMSC) provides storage and retrieval functions in
relation to your Compuware mainframe product’s configuration parameters. Compuware
mainframe products are configured using PARMLIB members. Using this method may be
fundamentally different from the way you have configured your Compuware mainframe
products in previous releases. Parameters are modified by editing human-readable PARMLIB
members, then telling CMSC to store those modified PARMLIB members into the Common Memory
Object by issuing a refresh (MODIFY) command. Compuware mainframe products receive parameter
values stored in the Common Memory Object.

The Common Memory Object containing your mainframe product parameters can be accessed
regardless of whether the CMSC is active. When the CMSC is initialized all PARMLIB members are loaded
into a Common Memory Object.

General Guidelines for PARMLIB Members

Parameters used by your Compuware mainframe product or component are read from the common
PARMLIB dataset. Edit the sample parameters to your site’s requirements.

• If the PARMLIB member includes multiple groups of parameters, for example for the definition of
multiple DB2 Subsystem, then only one occurrence of each of the parameters within each group
is allowed.

• An asterisk * in column 1 causes the entire statement to be a comment.

• Line level comments are supported using the /* to start a comment and */ to end the comment.
Embedded comments are supported.

Using System Symbolics

The CMSC resolves system symbolics as product parameters are saved into storage, potentially
allowing a single parameter member to be used across multiple LPARs. These symbols are defined by
your installation in IEASYMxx. Issue the following display command to display the current symbols.

/DISPLAY SYMBOLS

PARMLIB Member Naming Convention

PPPPnnnn

PPPP is the product prefix (see Table 1).

nnnn is the 1 to 4-character PARMLIB suffix, for example 00.

12 Enterprise Common Components Advanced Configuration Guide

The PARMLIB member name for each product or product component must start with the product
prefix, for example FACM for File-AID Common Components. The 1 to 4-character suffixes can be
used to replace the default name (FACM00). If the parameter for a given product is omitted, the
default suffix will be 00.

Changing the Default PARMLIB Member

In the CMSC start-up parameters, specify the product parameter, followed by the equal sign, and the
1 to 4-character suffix (for example: FACM=01, which points to PARMLIB member FACM01. If you
changed your PARMLIB member name from the default FACM00 to, for example FACM0005, update
your CMSC PARMLIB member to point to the new PARMLIB member, FACM=0005.

General Guidelines for PARMLIB Dataset

• The dataset can be blocked.

• The dataset can have multiple extents.

• The dataset must be on a single volume.

• The CMSC must have READ access.

Changing a PARMLIB Member

The flowchart below illustrates how an updated PARMLIB member is processed when a refresh
command is issued.

EDIT
PARMLIB
member

Issue refresh to
CMSC command
(MODIFY or SDSF Oper cmd)

CMSC Common Memory Object

(Storage of Data Structures)

Update
Common Storage Structures

Using a Non-Default CMSC or Parameter Suffix Value

To override the default CMSC or its default PARMLIB member suffix values, specify the following DDs
in a given product’s JCL or started task.
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 13

Used to override the CMSC from which the Compuware

//CWSCssss DD DUMMY product will retrieve parameters, where ssss is the four-
character CMSC_ID specified in the CMSC PARMLIB member.

Optionally, used to override the default PARMLIB member

specified in the CMSC configuration. Where aa is the two
//PMaaNNNN DD DUMMY character product code and NNNN is the PARMLIB member
suffix. The product codes are listed in Table 1 under the
column “Two-Character Product Code Override”.

CMSC Commands
Use the z/OS MODIFY command for the following commands. Note: The verb MODIFY can be
abbreviated, F.

PARMLIB Commands
Use the following commands to control the Parameter Library Service of the CMSC:

Validate a Single Parameter Member:

F cmscname,PARMLIB VERIFY member_name

CMSCxxxx members can be checked for validity using the PARMLIB VERIFY command. The CMSC must
be active in order to issue PARMLIB commands (thus, a valid CMSCxxxx PARMLIB member must already
be present, which allowed the CMSC to initialize). With the PARMLIB VERIFY command, new or modified
CMSCxxxx members can be validated before they are used, ensuring the CMSC initializes successfully.

In addition to the VERIFY command, the PARMLIB REFRESH and DISPLAY commands can be used for
CMSCxxxx members. Remember that any refreshed CMSCxxxx PARMLIB member will not be used until
the CMSC using that member is restarted.

Refreshing All Parameter Members:

F cmscname,PARMLIB REFRESH

Refreshing a Single Parameter Member:

F cmscname,PARMLIB REFRESH member_name

Displaying the Current Parameter Libraries:

F cmscname,PARMLIB DISPLAY

Stopping the Parameter Library Service:

F cmscname,PARMLIB STOP

The PARMLIB STOP command will stop the Compuware Parameter Library Service. All requests for
Parameter Library Services will result in a nonzero return code. It will not shut down the CMSC. In order
to restart the Parameter Library Service the CMSC will have to be restarted. This command should only be
used in emergency situations under direction of Compuware Customer Support.
14 Enterprise Common Components Advanced Configuration Guide

Other CMSC Commands

LMSHUT

Shutting Down the Compuware License Management Client or Server Task in the CMSC:
F cmscname,LMSHUT CLIENT

LMRESTRT

Restarting the Compuware License Management Client or Server Task in the CMSC:
F cmscname,LMRESTRT CLIENT

STARTHCI

Restarting an HCI Address Space Controlled by the CMSC:

F cmscname,STARTHCI hci_procname

This command only applies to HCI address spaces controlled by the CMSC using the HCI_PROC CMSC
startup parameter.

STOPHCI

Shutting Down an HCI Address Space Controlled by the CMSC:

F cmscname,STOPHCI hci_procname

This command only applies to the HCI address spaces controlled by the CMSC using the HCI_PROC
CMSC startup parameter.

SHUTDOWN

Stopping the CMSC:

F cmscname,SHUTDOWN nnnn|IMMEDIATE

nnnn — A timer value that specifies the number of seconds to elapse before CMSC terminates. The
default value is 60 seconds.

IMMEDIATE — A timer value that specifies that the CMSC is to stop immediately.

zIIP Commands

Restart or re-enable zIIP service:

F cmscname,ZIIP INIT

Stop zIIP service:

F cmscname,ZIIP DELETE

List zIIP service blocks:

F cmscname,ZIIP LIST
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 15

Determine if zIIP instance is active:

F cmscname,ZIIP QUERY

The zIIP instance will be the default unless a CXZPxxxx DD card was added to the CMSC procedure.
The zIIP ID will be specified as the response to the command.

Implementing the zIIP Enablement Service

IBM has provided a mechanism for Independent Software Vendors (ISV), such as Compuware, to
execute portions of ISV product code on zIIP processors at your site. Work executed on a zIIP
processor is not charged for usage as with general use processors. As a result, when portions of
Compuware product code are offloaded to execute on a zIIP processor, it can result in reduced costs.

The CSS zIIP Enablement Service provides a common method to enable selected portions of
Compuware product code to be eligible to run on a zIIP processor. If available on your system,
performance of Compuware software products can be enhanced by executing selected portions of the
product on a zIIP processor. Execution on a zIIP processor can result in less billable CPU time used
and significantly fewer I/O operations for normal product operation.

The CSS Cobol, PL/I, and Assembler language processors are particularly well-suited for zIIP
processing. Executing the language processors with zIIP processing enabled can reduce CPU time used
by 35 to 65% depending on the size and nature of the compiler listing being processed.

Enabling the Service

Before the service can be used, it must be started to enable its API for use by other Compuware
products. The service will be started when the CMSC is started, if ZIIP_ENABLEMENT=YES. It remains
active as long as the system remains running. The service can optionally be stopped, if desired.

Upon successful initialization, the following message will appear in the job log:

CXZPIN010I Initialization successful for ID CPWR

Please refer to the Enterprise Common Components Messages and Codes manual for information
regarding return codes.

Disabling the Service

This service can be temporarily disabled on a job-by-job basis, or completely disabled for the entire
system.

Job Disablement
To disable the service for a specific job, use the CXZPIGNR DD statement.

This statement will cause the job to execute without using the service. Note that the portions of the
product that were designated for zIIP processing will still be executed normally, but not on a zIIP
processor.

//CXZPIGNR DD DUMMY

System-wide Disablement
If you want to disable the service for all jobs, issue the MVS command ZIIP DELETE to the CMSC as
shown in the example below.

F cmscname,ZIIP DELETE

After running this command, the service will no longer be active in the system. Refer to the ZIIP
commands above to re-enable the service.
16 Enterprise Common Components Advanced Configuration Guide

Operational Considerations
PARMLIB Product Configuration
Refer to CMSC Administration for additional information on changing a PARMLIB member,
configuring Compuware mainframe products, using a non-default CMSC or parameter suffix value,
and implementing the zIIP Enablement Service.

Copy Sample PARMLIB Members

Copy the provided sample PARMLIB members from your installation sample library to your site’s
common PARMLIB dataset(s) for Compuware.

Any 17.02 or higher release of a Compuware mainframe product requires at minimum the Compuware
Mainframe Services Controller (CMSC) release 16.05 with all current maintenance applied.

Update the CMSC with PARMLIB Information

1. Make your product’s PARMLIB members available in the //CWPARM concatenation of the
Compuware Mainframe Services Controller (CMSC).
2. After making changes to your PARMLIB members, use the z/OS MODIFY command to update the
CMSC with the changes you made to the PARMLIB member.

The MODIFY command requires proper OPERATOR authority.

The verb MODIFY can be abbreviated, F.

Refreshing all PARMLIB Members:

F cmscname,PARMLIB REFRESH

Refreshing a Single Parameter Member:

F cmscname,PARMLIB REFRESH member_name

For example, you updated the parameters in member FACM00:

F cmscname,PARMLIB REFRESH FACM00

3. Specify the name of CMSC PARMLIB member(s) DDSNnnnn (default is DDSN00, or the specified
default in your site’s CMSC start-up) with the DDNAMEs and DATASET NAMEs of all Compuware
products, such as File-AID, Xpediter/TSO, Abend-AID, etc. A sample is located in
hlq.SLCXCNTL(DDSN00). 
DDSNnnnn provides the names of Compuware run-time libraries installed at your site. You will
need the DDSNnnnn name(s) if you wish to use Simple Deploy for configuring your Compuware
mainframe products.

CMSC Administration
Compuware mainframe products use parameter libraries, or PARMLIBs for setting their configuration
and customizations values. Compuware recommends storing your site’s PARMLIB members in a
common library. A copy of your product’s parameter files must reside in the //CWPARM
concatenation of the Compuware Mainframe Services Controller (CMSC).

The CWPARM is the DD from which the CMSC retrieves the parameters. This DD is a concatenated
list of all datasets containing the PARMLIB members for each of the Compuware mainframe products.
The CMSC will only read members into storage that contain the product prefixes specified in Table 1.
Sample parameter files provided in SLCXCNTL may be copied to the desired CWPARM dataset and
then modified to site-specific requirements.
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 17

CMSC start-up parameters (Table 1) specify the default 1 to 4 character suffix for all the Compuware
product PARMLIB members. If the parameter value for a given product is omitted (null or blank), the
default suffix will default to 00.

The product parameter is specified followed by the equal sign, and then the 1 to 4 character suffix
(for example: LMCL=01 points to PARMLIB member LMCL01).
18 Enterprise Common Components Advanced Configuration Guide

Table 1. Compuware Product PARMLIB Member Parameters

Product PARMLIB Two-Character Product Code
Product
Member Parameters Override
AABD AB Abend-AID BDCAS

AADC AD Abend-AID DCAS

AAFA AF Abend-AID Fault Analytics

AATD AT Abend-AID TDCAS

AAVW AV Abend-AID Viewer

CMSC SC Compuware Mainframe Service Controller

CSS CX Compuware Shared Services

CWGL -- Compuware Global Parameters

DDSN DD Simple Deploy

FACM FC File-AID Common Component

FADA DA File-AID/Data Solutions

FADE F1 File-AID DB2 Environment Information

FAMV FA File-AID/MVS

FAFR FR File-AID/RDX

FAFD FD File-AID for DB2

FAIE FE File-AID IMS Environment Information

FAIX FI File-AID for IMS

HCI HC Host Communications Interface

IWCM IW ISPW Server

IWCT IT ISPW Component Transport task

IWCI II ISPW Communications Interface task

HSCM QF Hiperstation

LMCL LM License Management Client

STR SB Strobe

XATZ -- Topaz for Total Test Functional Test

XVGB X1 Xpediter/CICS Code Coverage

XDGB X2 Xpediter/CICS Global

XDDB X3 Xpediter/CICS DBPA

XD$$ X4 Xpediter/CICS Index member

XCHG XG Xpediter/Xchange

XTSO XT Xpediter/TSO

XCOV -- Xpediter/Code Coverage

XVGB -- Xpediter/CICS Code Coverage

XDGB -- Xpediter/CICS Global

XDDB -- Xpediter/CICS DBPA

XCHG -- Xpediter/Xchange

XTSO -- Xpediter/TSO
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 19

Validate PARMLIB Member Contents

Program MSCUPRMD is a PARMLIB utility that employs the current CMSC API to display a PARMLIB
member's contents as they are known to the CMSC. MSCUPRMD is a TSO command processor so it is
recommended that this program reside in the linklist.

If the command is issued from native TSO, the data is displayed to the screen. If the command is
issued in ISPF, the data is displayed in a temporary dataset.

The MSCUPRMD command can display the active Compuware global parameter member by
specifying values of either CWGL or GLOBAL as the name of the PARMLIB member.

Although CMSCxxxx PARMLIB members can be displayed, verified, and refreshed using the
MSCUPRMD command, a refreshed CMSCxxxx PARMLIB member will not be used until the CMSC
using that member is restarted. When a CMSCxxxx PARMLIB is displayed, it may not show the
parameters that are currently being used by an active CMSC, because the member may have been
refreshed after the CMSC was started.

Command syntax
TSO MSCUPRMD MEMB=member_name|CWGL|GLOBAL,CMSC=cmsc_id[,VERIFY|REFRESH]

where,

member_name represents the name of the PARMLIB member you wish to display. It is a required
keyword and its value cannot exceed 8 characters in length.

CWGL is the prefix attributed to the global parameter member.

GLOBAL is the value given to display the global parameter member

cmsc_id is the name of the CMSC that the PARMLIB member is defined to. Its value must be 4
characters in length and will default to a value of 'CMSC', if omitted.

The PARMLIB member specified on the MSCUPRMD command is not displayed if the VERIFY or REFRESH
options are specified.

Both MEMB=CWGL and MEMB=GLOBAL result in the active Compuware global parameter member
being displayed.

The CWGLxxxx member is optional. However, if it does not exist, zAdviser will not be enabled.
20 Enterprise Common Components Advanced Configuration Guide

Configuration Parameters
CMSC Start-Up Parameters
CMSC00 is the default CMSC PARMLIB member. In the CMSC00 PARMLIB member, modify the CMSC
parameters to your site’s requirements before starting the CMSC.

Default member: CMSC00

CMSC_ID
Description: Specifies the name of the CMSC. This parameter must be a 1 to 4-character string. The string
must consist of the letters (A-Z), digits (0-9), or national symbols (@#$). It must begin with a
letter or national symbol. 

CMSC_ID=CMSC must be specified for the primary CMSC.

Use the CMSC_ID start-up parameter when your site requires multiple instances of CMSC.
For example CMSC_ID=TEST identifies a secondary CMSC, with the CMSC_ID of TEST,
dedicated to testing purposes.

Values: 1 to 4 character string.

Default: none

Required: yes

CES_PORT
Description: A decimal number from 1024–65535 that specifies the port number for the Compuware
Enterprise Server (CES) to which the CMSC is to send REST data.

Values: 1024 to 65535

Default: none

Required: no

CES_HOST
Description: Up to 70 characters specifying the hostname or IP address of the Compuware Enterprise
Server (CES) to which the CMSC is to send REST data.

Note: To enable CES support the CES_* parameters are required.

Values: up to 70 characters

Default: none

Required: no

LMS_CLIENT
Description: LMS_CLIENT statement is used to indicate whether the License Management System (LMS)
client should run in the CMSC address space.

Values: YES indicates that the License Management System (LMS) client should run in the
CMSC. This option indicates that LMSINIT — the LMS program that reads the License
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 21

File and constructs the License File cache against which runtime product access
requests are made — is to run in the CMSC address space.

NO indicates that the License Management System (LMS) client should not run in the
CMSC address space.

Default: YES

Required: no

HCI_PROC
Description: Specifies the name of the HCI start-up procedure. The procname specified here will be
started and controlled by CMSC. If you do not want to have CMSC start and control your
HCI Proc, then omit this parameter.

Values: The procedure name of the HCI start-up procedure.

Default: none

Required: no

HCI_PROCn
Description: Specifies the names of additional HCI start-up procedures. Up to 8 HCI address spaces can be
started and controlled by the CMSC.

Values: The name of the HCI start-up procedure for HCI_PROCn, where n is an integer 2 to 8.

Default: none

Required: no

ZIIP_ENABLEMENT
Description: Enables the Compuware zIIP service which other products use with various functionality.

Values: YES indicates that the Compuware Shared Services zIIP Enablement service is to be
started.
NO indicates that the Compuware Shared Services zIIP Enablement service is disabled.
This is the default.

Default: NO

Required: no

ZIIP_REFRESH
Description: This parameter specifies whether the zIIP service should be restarted when the CMSC is
started.

Values: YES indicates that Compuware zIIP service will be re-initialized when the CMSC is
started. ZIIP_ENABLEMENT=YES must be specified for this parameter to take effect. 
NO indicates that if the zIIP service is already enabled, it will not be re-initialized when
the CMSC is started. This is the default.

Default: NO

Required: no
22 Enterprise Common Components Advanced Configuration Guide

CES_SSL_KEYRING
CES_SSL_KEYDB
CES_SSL_KEYSTH
Description: CES_SSL_KEYRING specifies the name of the key ring file. CES_SSL_KEYDB specifies the
name of the key data base file. CES_SSL_KEYSTH is the name of the key data stash file. If
any one of these parameters is specified, the remaining two do not need to be. 

The specification of CES_SSL_KEYRING is required for zAdvisor streaming support.

Values: the maximum supported file name length is 64 characters.

Default: none

Required: no

MESSAGES
Description: Specifies whether all CMSC informational messages are produced. CMSC informational
messages are written to the CMSC log file specified by the //FDBDLOG DD statement in the
CMSC started task or JCL. DBUG

Values: YES enables standard informational messages

NO disables all messages
DBUG enables all messages including diagnostic messages useful for Compuware
support.

Default: NO

Required: no

SERVER_DESCRIPTION
Description: Specifies a 1- to 32-character description of the Compuware Mainframe Service Controller
address space. The description must be enclosed in double quotation marks.

Values: 1- to 32-characters

Default: &LPARNAME

Required: no

Default PARMLIB Suffixes

This is a listing of all PARMLIB suffixes and their defaults. If users desire to use a different PARMLIB
member then it requires changing the 00 to the identifier for their PARMLIB member.

LMCL
Description: License Management Client PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 23

HCI
Description: Host Communications Interface PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

CSS
Description: Compuware Shared Services PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

CWGL
Description: Compuware Global Parameter member

Values: 1 to 4-characters

Default: 00

Required: no

STR
Description: Strobe PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FACM
Description: File-AID/Common Component PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FADA
Description: File-AID/Data Solutions PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no
24 Enterprise Common Components Advanced Configuration Guide

FAMV
Description: File-AID/MVS PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FAFR
Description: File-AID/RDX PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FAFD
Description: File-AID for DB2 PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FAIX
Description: File-AID/IMS PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FADE
Description: File-AID for DB2 Environment Info PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

FAIE
Description: File-AID IMS Environment Info PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 25

FADP
Description: File-AID DPR Environment Info PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

AAVW
Description: Abend-AID Viewer PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

AATD
Description: Abend-AID PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

AABD
Description: Abend-AID PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

AACD
Description: Abend-AID PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

AAFA
Description: Abend-AID PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no
26 Enterprise Common Components Advanced Configuration Guide

XCOV
Description: Xpediter Code Coverage PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

XVGB
Description: Xpediter CICS Code Coverage PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

XDGB
Description: Xpediter CICS PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

XDDB
Description: Xpediter CICS PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

XD$$
Description: Xpediter for CICS PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

XCHG
Description: Xpediter/Xchange PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 27

XTSO
Description: Xpediter for TSO and Xpediter IMS PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

XATZ
Description: Specifies the suffix for the Topaz for Total Test Functional Test PARMLIB member when
overriding the default, 00, for a development environment.

Values: 1 to 4-characters

Default: 00

Required: no

HSCM
Description: Hiperstation PARMLIB Member

Values: 1 to 4-characters

Default: 00

Required: no

DDSN
Description: Simple Deploy DDNAME PARMLIB member

Values: 1 to 4-characters

Values: 00

Default: no

DDSN Configuration Parameters for Simple Deploy

Compuware Simple Deploy uses an API to resolve dataset names while still giving you complete
flexibility of what they are called. In short, it is no longer necessary to manually edit Compuware
install-dataset names in REXX and CLIST when upgrading and deploying certain Compuware
mainframe products.

For product-specific instructions on how configure the DDSNnnnn member, refer to the
comments contained in the CLISTs themselves. Not all Compuware mainframe products have
implement Simple Deploy, see their respective installation and configuration guides.

Member DDSN00 (shipped in the SLCXCNTL dataset) contains DD_INFO entries for all Compuware
product libraries.
28 Enterprise Common Components Advanced Configuration Guide

INCLUDE
Description: The fully qualified name of a member of a partitioned dataset containing additional
DD_INFO block statements to be merged with the parameters in the including DDSNnnnn
member.

Values: A fully qualified partitioned dataset name and member name.

Default: none

Required: no

Consideration for the INCLUDE parameter in DDSNnnnn

If you want to INCLUDE from the Compuware PARMLIB, ensure that the member does not start
with “DDSN”. For example, if INCLUDE = DDSNAA00, and the dataset is the name of a dataset in the
CWPARM DD concatenation, then that member will be loaded into memory twice—once as a
standalone member and once as part of the member with the INCLUDE parameter specified. For this
reason, Compuware recommends that INCLUDE’d members be given names that do not have “DDSN”
(or any 4-character prefixes of Compuware products) as their first four characters.

Example:

In the DDSN00 member:

INCLUDE SYS2.CW.PARMLIB(DDSNAA00) <— INCORRECT and would be loaded twice.

INCLUDE SYS2.CW.PARMLIB(AA00) <— CORRECT

DD_INFO Block Parameters

Member DDSN00 contains DD_INFO entries for all Compuware product libraries. All DD_INFO
entries are commented out. These may be modified and uncommented as required by your
installation.

DDNAME
Description: A Compuware DDNAME

Values: A valid DDNAME for a Compuware product

Default: none

Required: yes

DSNAME
Description: A dataset name for a Compuware product.

Values: A valid dataset name

Default: none

Required: yes
Compuware Mainframe Services Controller (CMSC) Configuration and Administration 29

FMID
Description: (Optional) If a Compuware mainframe product has only one version of that product
installed, then there is not need for a FMID on any DDs.

However, if more than one version is installed, the FMID allows release specificity of that
product. For example, if two Abend-AID releases are being started, then the FMID would
most likely be added to one of the releases. This allows one release to get specific FMID
specified DDs and the other product getting the default DDs (no FMID specified).

Values: A valid Compuware FMID

Default: none

Required: no

TYPE
Description: Any user DD or non-listed IBM DD requires this parameter in order to be verified properly.

Values: USER

Default: none

Required: no

Compuware Global Configuration Parameters

The Compuware Global Parmlib member (CWGL) exists to provide common parameters across
multiple Compuware products. The following parameters are contained in the Compuware Global
Parameter member (CWGLxxxx).

ZADVISER
Description: Controls where zAdviser records are to be written (zAdviser, SMF, or both). Values of YES and
ONLY will enable zAdviser streaming support in the CMSC, where records are automatically
sent to zAdviser.

Values: YES | NO | ONLY


YES writes records to both zAdviser and SMF 
NO writes records to SMF 
ONLY writes records to only zAdviser

Default: YES

Required: no

ZADVISER_QUEUE_ENTRIES
Description: Specifies the maximum number of buffers that are used prior to sending zAdviser data. This
specification determines the frequency in which records are sent to zAdviser.

Values: A decimal number between 5 and 250.

Default: 20 (recommended)

Required: no
30 Enterprise Common Components Advanced Configuration Guide

ZADVISER_SMF_VERSION
Description: A version number that identifies a Compuware-global setting for the version of SMF records
that ALL Compuware products will write. For current zAdviser support this parameter must
be set to 17.02.07 once all Compuware products are current and with all maintenance. This
value must otherwise be set to 17.00.00.

Values: 17.00.00 | 17.02.07

Default: 17.02.07

Required: no

ZADVISER_SMF_BUFF_INT
Description: Is the time interval, in minutes, of the maximum time a Compuware product will wait
before sending records to the zAdviser service.

Values: 1 to 1440 minutes

Default: none

Required: no
 31

License Management System (LMS)

Configuration and Administration 3

LMS Overview
LMS is a feature of the ECC single install image. LMS enables you to manage access to Compuware
products at your site.

Beginning with Release 17.02, LMS executes in the CMSC address space.

LMS Advantages
LMS provides the following advantages:

• Electronically-delivered License Certificates that contain product access parameters in a human-

readable text format.

• Programs and reports to verify the contents of the License File and LMS runtime environment.

• Easy updates to License Certificates and the License File with no disruption to your Compuware
products.

• No production impact from the testing of LMS runtime systems, installation and validation of
new License Certificates, or installation of new or updated LMS software.

• Optional e-mail alerts and SMF logging when licensing events occur.

Operating Environment
LMS operates under IBM MVS/ESA Release 4.3 and more current, and all OS/390 and z/OS releases.

License Management Process

The license management process begins when you acquire a Compuware product through a license
agreement, trial agreement, or beta agreement.

Information Gathering
Compuware obtains the relevant information for license management from you at the time of the
agreement. Your organization supplies information such as name and the sites and CPUs for which
the product is being licensed. Information about the Compuware product licensed, such as product
name, release number, and options licensed, is obtained from your Compuware representative.

License Certificate
Upon the completion of an agreement, Compuware creates a License Certificate representing a
portion of the information in that agreement. The License Certificate is used by LMS to provide
access to Compuware products. The License Certificate is not the same thing as a license agreement.
You are still responsible for abiding by your license agreement, and although not its primary role, you
will find that the LMS can help in that effort.
32 Enterprise Common Components Advanced Configuration Guide

The License Certificate, LMS, and the Compuware product are all delivered to you by Compuware.
Typically, you receive the License Certificate via e-mail, but other methods can be used, if necessary.

Installation
LMS is included as part of the ECC single install image. First, set up your LMS environment, import
your License Certificate into a License File, execute the CMSC address space, and install your
Compuware products. From then on, access to your Compuware mainframe products occurs
transparently.

After you accomplish the initial LMS installation, you would typically only need to import a new
product License Certificate and re-initialize the LMS runtime environment in conjunction with
events such as the following:

• obtaining a new release of a product under the terms of your software maintenance agreement
• adding new products through additional license agreements
• amending your agreement to include new options
• changing the CPUs licensed in your original agreement.

Which tasks you need to perform will depend on whether or which version of LMS has already been
enabled at your site.

The following is a list of items you might want to consider:

• Running more that one license management system

• Managing more than one Compuware customer number

Running More than One License Management System

Under certain circumstances, a site may decide to run more than one instance of LMS. For instance,
you might want both test and production LMS environments on the same system. Compuware
supports the environment of multiple LMS systems on a particular LPAR, though for all but the most
unusual implementations it is not necessary to run more than one LMS subsystem on any particular
LPAR. One possible exception would be the installation of a complete new release of LMS, where it is
desired that existing Compuware products continue to execute normally during the time that the
new release is installed and tested.

Managing More than One Compuware Customer Number

A site that manages multiple Compuware customer numbers, for example a service bureau, will have
a License File for each Compuware customer number.

Migration Considerations
The following items should be considered when upgrading from an earlier release of LMS to LMS
release 17.02 or later:

• Starting with release 17.02, LMS runs under the new Compuware Mainframe Services Controller
(CMSC) address space. The initialization job(s) no longer run independently.Starting with the
January 2019 Release of ECC 17.02, the Central Licensing Facility (CLF) will no longer be
supported.

Creating a License File

If you have previously installed Compuware’s License Management System software, go to “Verify the
License File”.

In this step, you will use the LAU to create a License File.

1. Execute the LMSPREP CLIST to update the CWLMA CLIST.

License Management System (LMS) Configuration and Administration 33

2. Start the LAU by selecting the ISPF menu item that was added by executing the CLIST CWLMA.
The License File Selection screen (Figure 1) will be displayed.

Figure 1. License File Selection Screen

--------------------- Compuware License Management 17.02.00 -- Row 1 to 2 of 2

Command ===> SCROLL ===> PAGE
License File Selection

Current Selection:
Enter New DSN . .
(fully qualified without quotes)
Delete/Define . N (Y|N)

OR select below:- 

Action DSN Added by

******************************* Bottom of data ********************************

3. Type the name you want to use for your License File (fully-qualified, without quotes) in the Enter
New DSN field.
4. Type Y in the Delete/Define field.
5. Press Enter. The Delete/Define and Initialize License File screen (Figure 2) will be displayed, and
the file name you specified above will be shown in the New License File field.

Figure 2. Delete/Define and Initialize License File Screen

--------------------- Compuware License Management 17.02.00 -- Row 1 to 2 of 2

Command ===> SCROLL ===> PAGE
Delete/Define and Initialize License File 

New License File . : TSOID01.License.File.New 

Unit . . . . . . . . _________ (required for JES3 only)
Volume Serial . . . _______ (blank for system determined volume)

Edit JCL . . . . . . Y (Y-Yes,N-No) 

Press END Key to skip this process 

Jobcard:
//Job Card information line 1
//Job Card information line 2
//Job Card information line 3
//Job Card information line 4 

Select Node Description

******************************* Bottom of data ********************************

6. Type Y in the Edit JCL field.

7. Type the information for your jobcard using the four lines of the Jobcard field.

Note: If you are not using all four lines of the job card, comment out the unused lines.

8. Press Enter. The Edit Delete/Define JCL screen (Figure 3) displays.

34 Enterprise Common Components Advanced Configuration Guide

Figure 3. Edit Delete/Define JCL Screen

File Edit Confirm Menu Utilities Compilers Test Help 

-------------------------------------------------------------------------------
EDIT SYS98274.T095731.RA000.TSOID01.R0111344 Columns0000100080
Command ===> Scroll ===>CSR
*************************************** Top of Data ***************************
000001 //Job Card information line 1
000002 //Job Card information line 2
000003 //Job Card information line 3
000004 //Job Card information line 4
000005 //*
000006 //*********************************************************************
000007 //* DELETE/DEFINE COMPUWARE LICENSE FILE
000008 //*
000009 //* JCL GENERATED BY TSOID01 ON 2001-05-17 AT 15:22
000010 //*********************************************************************
000011 //*
000012 //LFDELDEF EXEC PGM=IDCAMS
000013 //*
000014 //SYSPRINT DD SYSOUT=*
000015 //SYSIN DD *
000016 DELETE (TSOID01.License.File.New)
000017 SET MAXCC = 0
000018 DEF CL(NAME(TSOID01.License.File.New)
000019 IXD

9. Make any necessary edits, then enter the END command. A Confirm Submission window will be
displayed over the Delete/Define and Initialize License File screen.
10. Type Y in the Confirm Submission window and press Enter. The JCL to create your License File
will be submitted.
11. Enter the END command. The License File Selection screen (Figure 1) will be displayed.
12. After your job has completed with a good return code, type S in the Action field next to your
new License File and press Enter. Your License File name will appear in the Current Selection field.
13. Enter the END command.

– If you are a first-time user, the main Compuware License Management screen (Figure 6) will
appear.

– If you are an established user, the Parameter Option screen (Figure 7) will appear. To access
the main Compuware License Management screen (Figure 6), enter the END command.

Verify the License File

In this step, you will use the LAU to verify which License File you will be using.

1. Start the LAU by selecting the ISPF menu by executing the CLIST CWLMA. Because the LAU has
been run before and a License File already exists, the main Compuware License Management
screen shown in Figure 6 will be displayed. If the dataset name of the License file that you want
to use is displayed next to the Browse option, go to “Define Nodes”.
2. Type 0 in the Option field and press Enter. The Parameter Option screen (Figure 4) will be
displayed.
License Management System (LMS) Configuration and Administration 35

Figure 4. Parameter Option Screen

--------------------- Compuware License Management 17.02.00 -------------------

Option ===>

1) Select License File - TSOID01.LICENSE.FILE
2) Node Specify System Nodes 





X) Exit Return to previous panel 







(C) Copyright 2017, Compuware Corp. All Rights Reserved.

3. Type 1 in the Option field and press Enter. The License File Selection screen (Figure 5) will be
displayed.

Figure 5. License File Selection Screen

--------------------- Compuware License Management 17.02.00 -- Row 1 to 2 of 2

Command ===> SCROLL ===> PAGE 
License File Selection 

Current Selection: 
Enter New DSN . . 
(fully qualified without quotes) 
Delete/Define . N (Y|N) 

OR select below:- 

Action DSN Added by 
_ LICENSE.FILE1 USERID1 2000-08-07 
_ LICENSE.FILE2 USERID1 2000-08-07 
******************************* Bottom of data ********************************

4. Type S in the Action field next to the file that you want to use and press Enter. Your selected file
should appear in the current selection field.

Define Nodes
If your installation does not consist of multiple nodes in a JES network, or if you do not require the
ability to route License Management work (Import, Export, or Reporting) from one JES node to
another in your network, go to “Import License Certificate”.

In this step, you will use the LAU to define (to LMS) the network nodes on which License
Management maintenance or reporting tasks could be dispatched. If you are unsure of nodes defined
on your system, system PARMLIB member JES2PARM contains NODE statements defined to JES.
36 Enterprise Common Components Advanced Configuration Guide

Figure 6. Main Compuware License Management Screen

--------------------- Compuware License Management 17.02.00 -------------------

Option ===>

0) Parameters Specify System Parameters
1) Browse License File - TSOID01.License.File
2) Update License File
3) IMPORT Import License Certificate
4) EXPORT Export License Certificate
5) Reports Run Reports

6) Disaster Enable Disaster Site
7) Emergency Emergency Password 

X) Exit License Management 




Copyright (c) 2017 Compuware Corporation. All Rights Reserved.
Unpublished rights reserved under the Copyright Laws of the United States.
Enter HELP for Copyright/Trade Secret Notice information.

1. Type 0 in the Option field and press Enter. The Parameter Option screen (Figure 7) will be
displayed.

Figure 7. Parameter Option Screen

--------------------- Compuware License Management 17.02.00 -------------------

Option ===>

1) Select License File - TSOID01.LICENSE.FILE
2) Node Specify System Nodes 





X) Exit Return to previous panel 







(C) Copyright 2017, Compuware Corp. All Rights Reserved.

2. Type 2 in the Option field and press Enter. The Maintain Nodes Table screen (Figure 8) will be
displayed.
License Management System (LMS) Configuration and Administration 37

Figure 8. Maintain Nodes Table Screen

--------------------- Compuware License Management 17.02.00 -- Row 1 to 6 of 6

Command ===> SCROLL ===> PAGE


Maintain Nodes Table 

Enter new node . . . ________
Description . . . . ____________________ 

OR 

(C-Change,D-Delete)
Action Node Description Added by
_ Node1 Production TSOID01 2001-05-06 08:51
_ Node2 MVS Test1 TSOID01 2001-05-05 10:44
_ Node3 QA Test TSOID01 2001-05-22 10:38
******************************* Bottom of data ********************************

3. In the Enter new node field on the Maintain Nodes Table (Figure 8), specify the name of the
network node you want to add to the display list. This name identifies your installation’s local JES
in a network of systems or system complexes being used for network job entry (NJE) tasks. The
node name can be up to eight alphanumeric characters.
4. Describe the new node briefly in the Description field. This description can be up to 20
alphanumeric characters.
5. Press Enter. The screen will be redisplayed with the new node in the selection list at the bottom of
the screen. Repeat tasks step 3 through step 5 until you have defined all of the required nodes.
6. Enter the END command. The Parameter Option screen (Figure 7) will be displayed.
7. Enter the END command again. The main Compuware License Management screen (Figure 6) will
be displayed.

Import License Certificate

In this step the License Certificate for the Compuware product being installed will be imported into
your site’s License File.

1. On the main Compuware License Management screen (Figure 6), type 3 in the Option field and
press Enter. The first of two Import License Certificate screens (Figure 9) will be displayed.

Figure 9. First Import License Certificate Screen

--------------------- Compuware License Management 17.02.00 -------------------

Command ===>

IMPORT License Certificate 

Process DSN . : TSOID01.License.File

IMPORT From . . LICENSE.CERTIF__________________
(fully qualified without quotes)
Preview Only . . N (Y|N)

Reminder . . N (Y|N)

38 Enterprise Common Components Advanced Configuration Guide

2. Type the name of the dataset used for your License Certificate file (fully-qualified, without
quotes) in the IMPORT From field.
3. Type N in the Preview Only field.

Note: If you prefer to generate and review a report detailing the implications of the License
Certificate importation, enter Y in the Preview Only field. You then need to repeat this
step with Preview Only set to N.

4. If you type Y in the Reminder field you will see the message. If you type N, the reminder message
will not appear.
5. Press Enter. The second Import License Certificate screen (Figure 10) displays.

Figure 10. The second Import License Certificate screen

--------------------- Compuware License Management 17.02.00 -- Row 1 to 5 of 6

Command ===> SCROLL ===> PAGE

IMPORT License Certificate 

Process DSN . : TSOID01.License.File
IMPORT From . . LICENSE.CERTIF
Preview Only . . N 
Reminder . . N 

Edit JCL . . . . Y (Y-Yes,N-No) 

Jobcard:
//Job Card information line 1
//Job Card information line 2
//Job Card information line 3
//Job Card information line 4 

Select Node Description
_ Node1 Production
_ Node2 MVS Test1
_ Node3 QA Test
****************************** Bottom of data ***********************

6. Type Y in the Edit JCL field.

7. Type the information for your job card in the four lines of the Jobcard field.

Note: If you are not using all four lines of the job card, comment out the unused lines.

8. Type S next to the nodes on which you want the Import job to run. If no node is selected, the job
is submitted without any specific routing.

Note: If you are running on only one node, do not make a selection here.

9. Press Enter. The Edit JCL screen (Figure 11) will be displayed.
License Management System (LMS) Configuration and Administration 39

Figure 11. Edit JCL Screen

File Edit Confirm Menu Utilities Compilers Test Help 

-------------------------------------------------------------------------------
EDIT SYS98274.T095731.RA000.TSOID01.R0111344 Columns0000100080
Command ===> Scroll ===>CSR
************************************ Top of Data ******************************
000001 //Job Card information line 1
000002 //Job Card information line 2
000003 //Job Card information line 3
000004 //Job Card information line 4
000005//*
000006//*********************************************************************
000007//* IMPORT COMPUWARE LICENSE CERTIFICATE
000008//* 
000009//* JCL GENERATED BY TSOID01 ON 2001-07-08 AT 15:32:17
000010//*********************************************************************
000011//*
000012//IMPORT EXEC PGM=LMALFIM,
000013// PARM=’UPDATE’
000014//STEPLIB DD DSN=LM.DEVL.LOAD,
000015// DISP=SHR
000016//*
000017//CWLF0000 DD DSN=TSOID01.License.File,
000018// DISP=SHR
000019//CWLFIMP DD DSN=LICENSE.CERTIF,

10. Make any necessary edits, then enter the END command. A Confirm Submission window will be
displayed over the second Import License Certificate screen.
11. Type Y in the Confirm Submission window and press Enter. The JCL to create your License File
will be submitted.
12. Enter the END command. The main Compuware License Management screen (Figure 6) will be
displayed.
13. Type X in the Option field and press Enter to exit the LAU.

Sample LMS Parameters Dataset

You will find a sample LMS parameter dataset in the sample dataset shipped to you and installed with
ECC. The member name is LMCL00 and should be used as a skeleton for parameters for you particular
installation. Since this member can change with PTF maintenance, it is not listed here.

In releases of LMS prior to 16.05, the LMINPARM member found in the hlq.SLMSCNTL library was
customized. For current release of ECC, the hlq.SLCXCNTL library contains an additional module,
LMCL00, which needs to be customized. This module reads from the common PARMLIB dataset. If
you are an established user, compare the existing LMINPARM member with the LMCL00. You should
only see one new parm: LICENSE_DSNAME. You may be able to simply copy the previous parm
into the LMCL00 member if they are the same. If you copied your previous release’s LMINPARM
member to LMCL00, add the LICENSE_DSNAME parm, in which you should include the name of
your license file.

If you want to change which license file you are using, change the LICENSE_DSNAME
parameter to reflect that. After the remainder of ECC has been installed and the CMSC started,
you can then run:

F cmscname,PARMLIB REFRESH

After importing a new certificate into a currently active license file, you need to send the
following command to CMSC:

F cmscname,LMRESTRT CLIENT
40 Enterprise Common Components Advanced Configuration Guide

However, please be aware of any additional parms that may be added due to maintenance for ECC
release 17.02.

1. To ensure access to Compuware products is automatically enabled, establish a procedure in your

SYS1.PROCLIB to launch your CMSC as a started task during IPL and IML processing. Consult
your site’s MVS system programmer for details. Edit the sample proc provided in
SLCXCNTL(CMSC). Change the dataset names to match those used at your site, including the
PARMLIB dataset you saved your site specific LMS parameter dataset.
2. Specify the license file dataset name in the LMCL00 member, under the LICENSE_DSNAME
parameter.
3. If you changed your LMS PARMLIB member name from the default LMCL00 (for example:
LMCL0005) update your CMSC PARMLIB member to contain the suffix of the new LMS PARMLIB
member, LMCL=0005. Refer to “CMSC Start-Up Parameters”.

LMS Installation Considerations

This section describes considerations for installing and customizing LMS.

Execution Sequence
In order to ensure availability of Compuware products with LMS-controlled access, the LMS
runtime environment must be established within the CMSC address space prior to any products
being initialized. For this reason, Compuware strongly recommends that you institute an z/OS start-
up procedure based on the sample CMSC procedure provided in SLCXCNTL. It should run
automatically as part of IPL and IML processing prior to any procedures utilized by other Compuware
products. It may be necessary to consult your site’s z/OS system programmer.

The License Management System Functions

The License Management System has three basic functions.

License Management Administration

You will create and maintain your License File using the License Administration Utility (LAU)
installed with your License Management Software. Your License File is used as the source from which
Compuware products will validate access for your site. When you receive License Certificates for
Compuware products, your organization’s License Administrator must use the LAU to import the
License Certificates into the License File. Additional features of the LAU assist in the maintenance of
your License Files.

Establishing the Runtime LMS Environment

You will use the License Files created and maintained by the License Administration Utility as input
to a program that establishes your Compuware LMS runtime environment. LMS, running under the
CMSC, is the License Management System program that reads the License File and constructs the
License Cache and License Management System subsystem against which Compuware product
runtime license access requests are later made.

Important: You must re-establish your runtime License Management System environment at each IPL
via the CMSC, and whenever you have an update to your License File, the update must be made
available to your z/OS systems. At IPL startup, the CMSC must run LMS initialization before starting
up any Compuware product.
License Management System (LMS) Configuration and Administration 41

Validating Product Access Requests During Product Use

Your access to your Compuware products will be validated when you use your Compuware products.
The Compuware product will make a request of the License Management System to determine if your
site has a valid License Certificate for the product release. The given Compuware product will access
the LMS subsystem established, request License File information and act upon the information. Any
abnormal License Management event detected will be reported to the product’s user and may
optionally be reported by e-mail to your organization’s License Administrator..

LMS can read more than one License File, if your organization administers access to Compuware
products for more than one Compuware customer.

License Management System Components

The following components make up the License Management System.

License File Deployment

Depending on your organization’s software administration policies and procedures, you may follow
one of two License File deployment methods.

You may have multiple unique site License Files for your organization. These site License Files may
each be administered individually at each local site. Compuware recommends that a copy of the
License Administration Utility reside at each site since this would facilitate emergency updates to a
file and disaster recovery. In addition, the site’s LAU can be used to create License Management
System reports to facilitate troubleshooting at the site.

Certificate Files
Certificate Files contain one or more License Certificates for Compuware product(s) pending import
into a License File. They are also called Import Files. They may be delivered by Compuware, or they
may have been created by you through a License Administration Utility Export process. Certificate
Files always include a Customer License Certificate Record, one or more unique Site License
Certificate Records, Product, Option, CPU and LPAR License Certificates Records depending on your
license agreements.

You may choose to retain your Certificate Files for your reference after they have been imported with
the LAU. Compuware provides no automated facilities to help you retain your Certificate Files.

LMS Event Exit Facility

LMS establishes with z/OS a request for it to be notified when any one of the following events occur
on the LPAR.

• A change to the CEC size due to an OOCoD, CBU or CUoD

• A change to the LPAR size due to activity on the Hardware Management Console

• When the current date changes

Each of these system events causes LMS to be notified via a standard z/OS Event Manager Exit. This
exit code examines the state of the LPAR and determines whether or not it should invoke the PROC
named in the EXIT_PROC parameter of the LMS client parameters. Some reasons for not invoking the
PROC would be that the CEC model did not change, or the LPAR size did not change even though the
exit was driven (VM will cause this exit to be driven even when one of these events did not alter the
42 Enterprise Common Components Advanced Configuration Guide

CEC or the LPAR). When the exit determines that the PROC should be invoked it issues an internal
START command naming the PROC specified in the EXIT_PROC parameter of the LMS client
PARMLIB member.

You will notice that the EXIT_PROC is invoked once each day, just after midnight (based upon your
installation’s SMF Interval). It is necessary for LMS to update the checkpoint dataset with values
consistent with the change of date. If you do not see the EXIT_PROC being invoked, or if the started
task does not end normally, then review the requirements for coding the procedure and insure you
have followed them correctly.

The START command takes the following form:

START procname.ASSSSNNN,LMSSY=##SSSS

where:

• procname is the name in the EXIT_PROC parm

• A is a constant to allow numeric subsystem ID’s

• SSSS is the LMS subsystem ID

• NNN is a sequential number to provide a unique identifier for the started task

• ## is the two-digit Event Manager Exit number

• SSSS is the LMS subsystem ID

Grace Period
Support is available for a 14-day grace period that allows you to execute any Compuware product for
which you have a valid license on CPUs and LPARs that are not specifically included on any license
certificate that you possess. Six grace periods are supported:

• CEC serial number not specified in a CPU_ID<> parameter of a license certificate. You may have
installed a new computer in your installation, but have not yet received a license certificate that
includes the new serial number. Or you may have received a license certificate that specifies the
wrong serial number. In either case, you will be allowed to run any Compuware product for
which you are licensed on the new serial number for 14 days, starting from the day the CMSC
runs LMS for the first time on the new serial number.

• CEC model name not specified in a CPU_ID<> parameter of a license certificate. You may have
upgraded a computer in your installation (which changes the external model name), but you
have not yet received a license certificate that includes the new model name. Or you may have
received a license certificate that specifies the wrong model name. In either case, you will be
allowed to run any Compuware product for which you are licensed on the new model name for
14 days, starting from the day the CMSC runs LMS for the first time on the new CEC model, or
starting from the day the upgrade occurred if the upgrade was performed dynamically.

• LPAR name not specified in an LPAR NAME<> parameter of a license certificate. You may have
initialized a new LPAR on an existing CEC, but have not yet received a license certificate that
includes the new LPAR name. Or you may have received a license certificate that specifies the
wrong name. In either case, you will be allowed to run any Compuware product for which you
are licensed on the new LPAR for 14 days, starting from the day the CMSC runs LMS for the first
time on the new LPAR.

• LPAR size (MSUS<>) on a license certificate is smaller than the currently defined LPAR limit. You
may have increased the size of the LPAR dynamically, and you will be allowed to run any
Compuware product for which you are licensed on the bigger LPAR for 14 days, starting with
either the CMSC runs LMS for the first time on the larger LPAR, or the time the dynamic upgrade
occurred.
License Management System (LMS) Configuration and Administration 43

• LPAR utilization (MSUS<>) on a license certificate is smaller than the highest rolling 4-hour
average utilization of this LPAR. You should contact Compuware to increase the number specified
on the MSUS<> operand. You will be allowed to run any Compuware product on this LPAR for 14
days starting from the day the LPAR utilization exceeded the specified value.

• LPAR Group (MSUS<>) on a license certificate is smaller than the value you specified on the
Hardware Management Console (HMC) for the Group Capacity Limit for this LPAR. You will be
allowed to run any Compuware product on this LPAR for 14 days starting from the day the Group
Capacity Limit was changed.

Checkpoint File
LMS requires that a VSAM KSDS checkpoint file be available to every operating system image. This
file contains the information needed to support the 14-day grace period. The checkpoint file is
managed locally by each system that uses it. It is allocated automatically, if does not already exist, by
the CMSC and records are added and deleted automatically. The contents of this file do not require
any further editingOne checkpoint file can be used for any number of operating system images, and
for any number of LMS subsystems on these images. Or you can define a different file for each image
and/or subsystem. The DASD on which the checkpoint file resides must be available to LMS at all
times, starting LMS being run under the CMSC throughout the life of the system IPL. This dataset is
accessed by only the CMSC and by LMS exit programs that are invoked by the operating system
whenever a CPU Upgrade on Demand or an LPAR defined capacity change occurs.

Using LMS Client Parameters to Define the Checkpoint Dataset

Use the following parameters to define the checkpoint dataset—only CHKPT_DSNAME is required.

• CHKPT_DSNAME
• CHKPT_VOLSER
• CHKPT_STORCLASS
• CHKPT_MGMTCLASS
• CHKPT_DATACLASS

Checkpoint Dataset Security

You must ensure that the checkpoint dataset is appropriately protected by your installation’s security
system (RACF, ACF/2, and CA-Top Secret).

Because the CMSC and the exit programs that create and update the checkpoint dataset are APF-
authorized routines, they must issue their own calls to the Security Access Facility (SAF) interface to
ensure that the user ID under which they are running has the appropriate access to create and/or
update the checkpoint dataset. The user ID under which the CMSC runs must have ACCESS=ALTER if
the checkpoint dataset does not exist, and it must have ACCESS=CONTROL if the dataset already
exists.

The system exits run under the user ID of the last LMS execution that ran for the subsystem in
question.

Sharing the Checkpoint Dataset

The LMS checkpoint dataset is protected by a QNAME/RNAME combination where QNAME is
CPWRCKPT and RNAME is the 1-38 character dataset name itself. If you are sharing one checkpoint
dataset among multiple systems then this QNAME/RNAME combination must be eligible for cross-
system sharing.

The ENQ for this QNAME/RNAME is issued with SCOPE=SYSTEMS. Therefore you may have to adjust
your GRS RNL (or the MIM equivalent) parameters to support sharing of these names multiple
operating systems.
44 Enterprise Common Components Advanced Configuration Guide

If you have disabled this GRS function for your installation, then you MUST NOT SHARE your
checkpoint datasets.

Although the checkpoint dataset may be shared among multiple LPARS which are running Compuware
products, the restriction exists that the LMS version must be the same.

History File
The History dataset contains the 14-day grace period information about products and options. This
information includes when these products and options were first licensed at your installation and if
they enter any of the 14-day grace period, when they entered the 14-day grace period, and when that
grace period will expire.

You can use the information in this dataset to insure yourself that the products and options you have
purchased are validly licensed.

You must not define this VSAM ESDS yourself. Instead it is automatically allocated based on the
HISTORY_* parameters.

This dataset is a VSAM ESDS and is updated by the LMS task under the LMSC and by LMSENMGR (the
program executed by the EXIT_PROC PROCEDURE. You must insure that the user ID under which the
CMSC runs has ALTER access to this dataset defined in the security system (RACF, ACF/2 or CA-Top
Secret).

Grace History File

An optional facility exists that is the creation of a history dataset containing 14 day grace
information about products and options. This information includes an indication of when these
products were first licensed at your installation, and if they enter any of the 14 day grace periods, and
indication as to when they entered the 14 day grace and an indication as to when that grace will
expire. You can use the information in this dataset to insure yourself that the products and options
you have purchased are validly licensed.

Batch (Sample Reports)

All reports have a common header in addition to another header that is generated by the License
Administration Utility (LAU). All reports can be output to a printer or DASD dataset with printer
attributes. The reports are not formatted for screen output, but may be browsed on screen (if sent to a
dataset) with the normal ISPF browse scrolling features.

License Verification Report

The License Verification Report, as shown in Figure 12, displays the information regarding the
License Management System Runtime Subsystem. The report includes information regarding the LMS
modules loaded in the subsystem, the license availability information, and additional product license
certificate information.

Note: When email verification is turned on, an email is sent to the configured user indicating
that the product named “DUMMY PROD” is not licensed on the LPAR. This email can be
ignored as its use is simply to verify that email messages are being created and delivered
to the intended user.
License Management System (LMS) Configuration and Administration 45

Note: If you have email notification turned on, you will also receive a message for each product
or option that is in a warning or error state. These messages can be used to verify that all
of your Compuware products are properly licensed.

Figure 12. License Verification Report

2000/08/10 COMPUWARE CORPORATION LICENSE MANAGEMENT VER 17.02.00

07:35:37.28 INSTALLATION VERIFICATION PAGE 1
PROCESSING STARTED FOR SUBSYSTEM 6339 
LMSASSYS 00116384 20000414 07.53 VER 01.00.01 
LMSAESTA 00118607 20000630 08.16 VER 01.00.01 
LMSPCRTN 00116384 20000414 07.55 VER 01.00.01 
LMSPCARR 00BASE-- 19990625 11.03 VER 01.00.01 
LMSSDUMP 00112309 19991116 12.33 VER 01.00.01 
LMSTRACE 00109624 19990807 01.23 VER 01.00.01 
LMSGETMS 00113413 20000106 08.48 VER 01.00.01 
LMSMSGEN 00116599 20000522 09.29 VER 01.00.01 
LMSSMF 00113962 20000117 08.20 VER 01.00.01 
LMSSERVR 00116599 20000522 09.34 VER 01.00.01 
LMSRACF 00113774 20000106 13.43 VER 01.00.01 
LMADTCV -BASE--- 19990625 10.25 
LMACG000 06/25/99 10.22 
LMSMSGLT 00116599 20000522 09.32 VER 01.00.01 
LMSEMERP 00113413 20000106 09.05 VER 01.00.01 
LMSSCOMM 00118457 20000626 07.23 VER 01.00.01 
LMSCPUID 00116599 20000524 09.32 VER 01.00.01 
LMSRSMGR 00116384 20000414 07.55 VER 01.00.01 

PRODUCT OSAA VER 09.02 
ABEND-AID FOR OS/390 
STATUS: LIMITED_TERM START: 27-DEC-1999 
END: 17-JAN-2001 
SITENM: FARMINGTON HILLS HEADQUARTERS 
CERTID: 200021600000 SITENUM: 001 
CPU ID: IBM,9672-0C-110269,MVS 
DSNAME: SYS2.DEFAULT.LICENSE.FILE 
CUSTNM: COMPUWARE CORPORATION 
USERID: EFHAWC0 CUSTNUM: 010000 

OPTION ASSEMBLER VER 09.02 
ABEND-AID/ASSEMBLER 
STATUS: LIMITED_TERM START: 27-DEC-1999 
END: 17-JAN-2001 

OPTION DB2 VER 09.02 
ABEND-AID/DB2 
STATUS: LIMITED_TERM START: 27-DEC-1999 
END: 17-JAN-2001 

OPTION IMS VER 09.02 
LMCHKOUT FAILED. R15= 00000008. RETURN-CODE=00000008. REASON-CODE=00000581
WLM001I **************************************************************** 
WLM002I ******* ******* 
WLM003I ******* COMPUWARE CORPORATION ******* 
WLM004I ******* LICENSE MANAGEMENT ******* 
WLM005I ******* COPYRIGHT (C) 1998, 1999 ******* 
WLM006I ******* BY COMPUWARE CORPORATION. ALL RIGHTS RESERVED. ******* 
WLM007I ******* ******* 
WLM581E ******* PRODUCT OPTION NOT LICENSED ON SPECIFIED CPU 
WLM010I ******* OSAA 09.02 IMS 09.02 ,9672-0C-310269, 
WLM011I ******* 
WLM025I ******* CUSTOMER AND SITE INFORMATION FOLLOWS: 
WLM018I ******* COMPUWARE CORPORATION 
WLM019I ******* CUSTOMER NUMBER: 010000 
WLM020I ******* FARMINGTON HILLS HEADQUARTERS 
WLM021I ******* SITE NUMBER: 001 
WLM011I ******* 
WLM026I ******* CURRENT ENVIRONMENTAL INFORMATION FOLLOWS: 
WLM022I ******* SYS2.DEFAULT.LICENSE.FILE 
WLM023I ******* SUBSYSTEM ID: 6339 
WLM024I ******* CERTIFICATE ID: 200021600000 
WLM011I ******* 
WLM012I ******* ******* 
WLM013I ******* COMPUWARE PRODUCT SUPPORT HOTLINE ******* 
WLM014I ******* U.S. AND CANADA....1-800-538-7822 ******* 
WLM015I ******* ALL OTHER..........1-248-737-8423 ******* 
WLM016I ******* ******* 
WLM017I ****************************************************************
46 Enterprise Common Components Advanced Configuration Guide

Current Cache Contents Report

The Current Cache Contents report, as shown in Figure 13, displays the contents of the LMS cache
except for data used for processing, such as key data. This report displays what is actually in the
cache, not what is on the license file. In Summary mode, one line is printed for each license file
record in the cache. Detail mode presents more information, in multiple lines per record. You can
limit the report to licenses that will expire before a specified date.

Figure 13. Current Cache Contents Report

DATE: 08-FEB-2001 COMPUWARE LICENSE MANAGEMENT PAGE: 1

TIME: 10:10:48 CURRENT CACHE CONTENTS 

SUBSYSTEM: xxxx SMF LOGGING: NO ID: xx (999) 
LICENSE FILE DSN: customer dsname 

CUSTOMER: 999999 customer name 
SMF LOGGING: NO SECURITY DSN: customer dsname 

SITE: 999 customer site name 
SMF LOGGING: YES SECURITY DSN: customer dsname 
DISASTER SWITCH ON: NO 
EMERGENCY SWITCH ON: NO 

PRODUCT: CICS/FX 04.02 CICS/ABEND-AID/FX 
SMF LOGGING: PRODUCT WILL BE LOGGED, DUE TO SITE SPECIFICATION 
AUTH CODE: 0123456789ABCDEF CERTIFICATE: 200100199999 VERSION: 03.01.00
STATUS: LONG_TERM START: 14-JUL-1999 

CPU: RB4,9672-5E-001234,*** 
STATUS:

License File Contents Report

The License File Contents report, as shown in Figure 14, displays the contents of a VSAM or
sequential license file. It is similar in format to the Current Cache Contents Report, and like that
report, you can generate it in Summary (S) or Detail (D) mode. You can limit the report to licenses
that will expire before a specified date.

Figure 14. License File Contents Report

DATE: 08-FEB-2001 COMPUWARE LICENSE MANAGEMENT PAGE 1

TIME: 10:10:48 LICENSE FILE CONTENTS 

LICENSE FILE DSN: customer dsname 

CUSTOMER: 999999 customer name 

SITE: 999 customer site name 

PRODUCT: CICS/FX 04.02 CICS/ABEND-AID/FX 
CPU: ***,****-**-001234,*** 
LPAR: LPAR #1 SIZE: 999 MSU'S 
LPAR: LPAR #2 SIZE: 999 MSU'S 
CPU: RB4,9672-5E-005678,*** 
OPTION: COBOL 04.02 CICS/ABEND-AID/FX COBOL OPTION 
CPU: ***,****-**-001234,*** 
LPAR: LPAR #1 SIZE: 999 MSU'S 
LPAR: LPAR #2 SIZE: 999 MSU'S 
CPU: RB4,9672-5E-005678,*** 
OPTION: DB2 04.02 CICS/ABEND-AID/FX DB2 OPTION 
CPU: ***,****-**-001234,*** 
LPAR: LPAR #1 SIZE: 999 MSU'S
License Management System (LMS) Configuration and Administration 47

SMF License Records Report

The SMF License Records report, as shown in Figure 15, displays license records that have been
written to an SMF dataset by LMS. Its primary use is intended as a diagnostic tool. You can use it to
view what was the contents of a license file at some previous time. In format, it is similar to the
License File Report, but prints one additional line per record, showing the last maintenance date and
time for each record. When you select this report, the SMF Report Data Source screen is displayed.
You must enter the SMF record ID that you use for License Management records and the dataset
name(s) of the SMF file(s) to be used as input. Optionally, you can enter a start date and time, and an
end date and time for the report.

Figure 15. SMF License Records Report

DATE: 08-FEB-2001 COMPUWARE LICENSE MANAGEMENT PAGE 1

TIME: 10:10:48 SMF LICENSE RECORDS 

CUSTOMER: 999999 customer name 
SMF LOGGING: NO SECURITY DSN: customer dsname 
LAST MAINTAINED: user 07-FEB-2001 11:48:23 

SITE: 999 customer site name 
SMF LOGGING: YES SECURITY DSN: customer dsname 
DISASTER SWITCH ON: NO 
EMERGENCY SWITCH ON: NO 
LAST MAINTAINED: user 07-FEB-2001 11:48:23 

PRODUCT: CICS/FX 04.02 CICS/ABEND-AID/FX 
SMF LOGGING: PRODUCT WILL BE LOGGED, DUE TO SITE SPECIFICATION 
AUTH CODE: 0123456789ABCDEF CERTIFICATE: 200100199999 02.00.00
VERSION: 03.00.00
STATUS: LONG_TERM START: 14-JUL-1999 
LAST MAINTAINED: user 07-FEB-2001 11:48:23 

CPU: RB4,9672-5E-001234,*** 
STATUS: 
LAST MAINTAINED: user 07-FEB-2001 11:48:23
11:48:23

Product Activity Report

The Product Activity Report, as shown in Figure 16, is a listing of the CHECKIN and CHECKOUT
records. The License Management System writes an SMF record whenever a product or option is used
by an application (a CHECKOUT record), and whenever an application is finished with a product or
option (a CHECKIN record). When you select this report, the SMF Report Data Source screen is
displayed. You must enter the SMF record ID that you use for License Management records and the
dataset name(s) of the SMF file(s) to be used as input. Optionally, you can enter a start date and time,
and an end date and time for the report.
48 Enterprise Common Components Advanced Configuration Guide

Figure 16. Product Activity Report

DATE: 08-FEB-2018 COMPUWARE LICENSE MANAGEMENT PAGE 1

TIME: 12:27:24 PRODUCT ACTIVITY REPORT 

CUSTOMER: 999999 customer name 
SITE: 999 customer site name 
PRODUCT: FILE-AID 08.06 FILE-AID/MVS 
CPU: T26,9672-4E-001234,*** 

CHECKOUT JOB: SY935020 PGM: FILEAID 18-JAN-2018 1:11:22 RETURN: 0000 0000
JOBSTEP: SPLIT PROCSTEP: USERID: userid 
LMS SUBSYS IDS: LOCAL: MLMS SYSPLEX: SYSPLEX MEMBER: 

OPTION: FA/XE 08.06 FILE-AID/MVS/XE 
CPU: T26,9672-4E-001234,*** 

CHECKOUT JOB: SY935020 PGM: FILEAID 18-JAN-2018 1:11:22 RETURN: 0000 0000
JOBSTEP: SPLIT PROCSTEP: USERID: userid 
LMS SUBSYS IDS: LOCAL: MLMS SYSPLEX: SYSPLEX MEMBER: 

CHECKIN JOB: SY935020 PGM: FILEAID 18-JAN-2018 1:12:44 RETURN: 0000 0000
JOBSTEP: SPLIT PROCSTEP: USERID: userid 
LMS SUBSYS IDS: LOCAL: MLMS SYSPLEX: SYSPLEX MEMBER:

Activity Extract
This selection generates a file of the License Management CHECKOUT and CHECKIN records, in
comma-separated variable (CSV) format. You can use this file as input to many spreadsheet, database,
and report-generator programs and thereby generate your own activity reports. When you select this
report, the SMF Report Data Source screen is displayed. You must enter the SMF record ID that you
use for License Management records and the dataset name(s) of the SMF file(s) to be used as input. In
addition, you need to enter a dataset name and disposition for the generated CSV file. Optionally,
you can enter a start date and time, and an end date and time for the report.

Establishing Multiple LMS Subsystems

The following section discusses the considerations for establishing multiple LMS subsystems on one
or more LPARs in your environment.

Considerations for Testing

Typically, the receipt of a license certificate containing a new Compuware product/release or update
to an existing Compuware product would not constitute the necessity to establish a separate LMS
subsystem in which to test the new certificate. In this case, it is sufficient to simply import this new
certificate into your existing license file and run the CMSC. All products on this new certificate will
be available for use immediately upon the successful completion of LMS.

In the situation where there is no testing LPAR available and you are concerned that the maintenance
applied (or the new version of LMS) might negatively affect Compuware product execution, then a
secondary LMS subsystem should be created and tested.

Establishing a Secondary LMS subsystem

IMPORTANT:
Before creating a secondary LMS subsystem, ensure that the primary subsystem contains the
parameter DEFAULT with a value of YES.

Step 1. Choose a 4-character subsystem ID for the new subsystem. This ID must be unique across all
subsystems on the LPAR and must NOT duplicate any other LMS subsystem ID.
Step 2. Copy the existing PARMLIB member to a new member as it can then be modified without
affecting the primary subsystem.
License Management System (LMS) Configuration and Administration 49

Step 3. Change the SUBSYSTEM_ID parameter to be the new one you chose in step 1.
Step 4. Change the DEFAULT=YES parameter to specify NO.
Step 5. Change the CHKPT_DSNAME parameter to specify a new dataset name. This name must not
already exist on the LPAR. LMS will create the dataset for you.
Step 6. If you have a HISTORY_DSNAME parameter, change the dataset name to be different from
the one specified.
Step 7. Change the EXIT_PROC parameter to name the new procedure you copied into your system
PROCLIB. You want the new procedure, which contains a //STEPLIB, to point to the updated
ECC datasets. If you updated the production datasets during the SMP/E process, you will not
need a new EXIT_PROC.
Step 8. Change the //STEPLIB DD in the LMSC started task to point to the updated APF-Authorized
load library.
Step 9. Use the CMSC override DDs to point to the particular PARMLIB member.

Upon successful completion of LMS in the CMSC you will have a second LMS subsystem active on the
LPAR, which can be used to test an updated LMS.

You should invoke the LAU and run the Verification Report and the License Cache Report. You will
see your test subsystem listed in the Verification Report. This will contain a list of all LMS modules
with the date they were last changed. You can manually verify that the correct release of LMS is
executed.

In order to exercise the new subsystem you must add the following DD statement to JCL, which
executes any Compuware product or you must allocate this DD statement under TSO, if the product
runs under TSO.

//CWxxaaaa DD DUMMY

• CW is a required constant

• xx is the two-character product ID naming the Compuware product to be licensed by the test
subsystem (see Table 2).

• aaaa is the 4-character subsystem ID you chose for your test subsystem.

When you are content that the updated LMS is executing correctly you can delete the test subsystem
by running the CMSC with the updated LMS Client PARMLIB member, substituting
FUNCTION=DELETE for FUNCTION=UPDATE

Table 2 List of Product Codes for LM Overrides

Two-character Product
Product Name
Code
AA ABEND-AID
CF ABEND-AID FOR CICS
DA FILE-AID/DATA SOLUTIONS
DB DBA-XPERT FOR DB2
FA FILE-AID/MVS
FB FILE-AID DATA PRIVACY
FD FILE-AID FOR DB2
FE FILE-AID/EX ENTERPRISE EDITION
FR FILE-AID/RDX
FI FILE-AID FOR IMS
IS ISTROBE
IW ISPW (SCM)
50 Enterprise Common Components Advanced Configuration Guide

Table 2 List of Product Codes for LM Overrides

Two-character Product
Product Name
Code
PK FAULT ANALYTICS
SB STROBE MVS SYSPLEX
TO TOPAZ FOR ENTERPRISE DATA
TZ TOPAZ PROGRAM ANALYSIS
XA COMPUWARE PROGRAM ANALYZER
XD XPEDITER/CICS
XE XPEDITER/ECLIPSE
YO XPEDITER/XCHANGE
XT XPEDITER/TSO (& IMS)
XV XPEDITER/CODE COVERAGE

Methods to Enable Disaster Recovery

Method 1: Emergency Password
Emergency passwords are obtained from Compuware whenever a situation precludes normal license
processing. These passwords are supplied for a limited number of days and can be obtained by
logging on to Compuware Support Center and selecting License Management System. An emergency
password obtained via Compuware Support Center remains in effect for a total of seven days starting
from the first full day after the password was obtained. Once expired, the licensing rules will revert to
the licenses contained in the license file.

The eight character emergency password is defined by the EMERGENCY() parameter and specified in
LMCLxxxx

1. Obtain an emergency password from Compuware Support Center.

2. Input the password value into the EMERGENCY() parameter of the corresponding parameter file.
3. Issue the following MVS modify command to refresh the PARMLIB member in the CMSC.

F cmscname,PARMLIB REFRESH member_name

4. Restart the LMS environment by issuing the following MVS modify command

F cmscname,LMRESTRT CLIENT

Method 2: DR Mode Batch Utility

1. Using the LMBDISTR utility, you can update your checkpoint datasets to indicate DR mode is on.
The following skeleton JCL for using the utility:

//DISASTER EXEC PGM=LMBDISTR

//STEPLIB DD DSN=**Your LMS load library dsname **,DISP=SHR 
//LMSCHKPT DD DSN=**2nd client checkpoint dsname **,DISP=SHR
//DISASTER EXEC PGM=LMBDISTR
//STEPLIB DD DSN=**Your LMS load library dsname **,DISP=SHR 
//LMSCHKPT DD DSN=**3rd client checkpoint dsname **,DISP=SHR
//DISASTER EXEC PGM=LMBDISTR
//STEPLIB DD DSN=**Your LMS load library dsname **,DISP=SHR 
//LMSCHKPT DD DSN=**4th client checkpoint dsname **,DISP=SHR
License Management System (LMS) Configuration and Administration 51

//DISASTER EXEC PGM=LMBDISTR

//STEPLIB DD DSN=**Your LMS load library dsname **,DISP=SHR 
//LMSCHKPT DD DSN=**5th client checkpoint dsname **,DISP=SHR
.
.
.
//DISASTER EXEC PGM=LMBDISTR
//STEPLIB DD DSN=**Your LMS load library dsname **,DISP=SHR 
//LMSCHKPT DD DSN=**20th client checkpoint dsname **,DISP=SHR

2. Restart the LMS environment by issuing the following MVS modify command:
F cmscname,LMRESTRT CLIENT

Method 3: LAU ISPF Utility

1. Enter the LAU utility. (If you do not have this set up, please see the instructions on running
LMSPREP found at Creating a License File.)
2. Enter Option 6: Disaster
3. Select the site for which you wish to enable disaster mode.
4. Confirm your choice.
5. Restart the LMS environment by issuing the following MVS modify command

F cmscname,LMRESTRT CLIENT

Default Member: LMCLALL (client)

FUNCTION
Description: FUNCTION is used to define a new, edit, or delete a SUBSYSTEM_ID value.

Values: CREATE is used to define a new SUBSYSTEM_ID value for the first time. CREATE
specifies that this SUBSYSTEM_ID value should be added to the operating system table
of subsystems. LMSINIT will not process a CREATE request if the value specified for
SUBSYSTEM_ID already exists in the subsystem table.

UPDATE is used to define a new SUBSYSTEM_ID value for the first time or to change an
existing SUBSYSTEM_ID value. Therefore, LMSINIT will process the UPDATE request for
both new and existing SUBSYSTEM_ID processing.
DELETE is used to delete an existing SUBSYSTEM_ID value from the table of
subsystems. LMSINIT will process the DELETE request only if the SUBSYSTEM_ID value
names a subsystem already active in the subsystem table.

Default: none

Required: yes

SITE
Description: The specification of a site number is required for LMSINIT execution. This number (or
numbers) tells LMSINIT which site(s) to load from the license file(s) into the license cache.

Values: three-digit number from 001 to 999


When specifying more than one SITE, a DD name must be provided for each SITE using
the SITE_DD parameter. The DD must be CWLFxxxx, where CWLF0000 is the DD name
for the first SITE, CWLF0001 is the DD name for the second SITE, and so on.

52 Enterprise Common Components Advanced Configuration Guide

You must either code a CWLFxxxx DD statement corresponding to the SITE_DD

parameter in the CMSC start-up JCL, or specify a LICENSE_DSNAME parameter in the
LMCLxxxx member. While these parameters do not have to be specified together in a
group, each of these three parameters must be supplied in the same order as the others.
Therefore, the SITE, SITE_DD, and LICENSE_DSNAME parameters for the first SITE
must be specified before the SITE, SITE_DD, and LICENSE_DSNAME parameters for any
other sites. Compuware recommends that you specify the SITE, SITE_ DD, and
LICENSE_DSNAME parameters together. 

If you only have one SITE then the SITE_DD parameter is not required. It will default to
CWLF0000.

Example with one license file: 

SITE=001
LICENSE_DSNAME=COMPWARE.LICENSE.ONE

Example with two license files: 

SITE=001
SITE_DD=CWLF0000
LICENSE_DSNAME=COMPWARE.LICENSE.ONE
SITE=002
SITE_DD=CWLF0001
LICENSE_DSNAME=.COMPWARE.LICENSE.TWO

Default: none

Required: yes

SITE_DD
Description: Specifies the DD name associated with the corresponding SITE and LICENSE_DSNAME
parameters. See the description of the SITE parameter for details.

Values: CWLFxxxx 
where xxxx is a number between 0000 and 9999

Default: CWLF0000

Required: Needed only when more than one set of SITE and LICENSE_DSNAME parameters is specified.

SUBSYSTEM_ID
Description: The value specified on the SUBSYSTEM_ID operand names the subsystem that this
invocation of LMSINIT will process.

Values: This value can contain only uppercase letters and numbers.

Although the operating system allows subsystem names to contain lowercase letters
and special characters, LMS does not because the subsystem name may need to be
included in the DDNAME of a //CWIDSSSS DD DUMMY statement. Therefore, the
value chosen for SUBSYSTEM_ID must also be valid in a DDNAME.
You must coordinate the use of the subsystem identifier, because duplicate names are
not allowed, either within the set of License Management subsystems, or across all
License Management System (LMS) Configuration and Administration 53

subsystems defined. Check with your systems programmer to ensure that the
SUBSYSTEM_ID value you have chosen is not already in use.

Default: none

Required: yes

DEFAULT
Description: This operand defines whether this SUBSYSTEM_ID will be declared the default subsystem.

Values: NO|YES|FORCE.

Default: none

Required: yes

LICENSE_DSNAME
Description: Specifies the license file dataset name to be used. Multiple LICENSE_DSNAME entries may be
specified.

Default: none

Required: yes

EXIT_PROC
Description: Specifies the 1- to 8-character member name in SYS1.PROCLIB (or any appropriate
PROCLIB), of the PROC which LMS automatically starts whenever an event occurs which
drives the event notification exit. The events which will cause this PROC to be started are

•A Dynamic CPU Upgrade (CPU Upgrade on Demand)

•A change to the defined capacity of the LPAR.
•The first SMF interval to expire each midnight.
An example of this PROC is shown below. Code the PROC exactly as shown below,
substituting only the name of the APF-Authorized Load library which contains the LMS
load modules.

//LMSEXIT PROC

//EVENT EXEC PGM=LMSENMGR,PARM=&LMSSYS

//STEPLIB DD DSN=** Your APF Loadlib **,DISP=SHR

In LMS version 2.0 two messages were written to the system console for each
product/option found on the checkpoint dataset.
These messages were “LMG042I Product xx Version xx Updated On Checkpoint File”
and “LM6043I xx the xx Option of the xx Version xx Updated on Checkpoint File.”
These messages have been removed and have been replaced with a single message
“LM5305I all products updated on the LMS checkpoint dataset”.
This change significantly decreases the number of messages written to the system
console each time the EXIT_PROC is invoked.

Required: yes
54 Enterprise Common Components Advanced Configuration Guide

SERVICE_BUREAU
Description: You may specify SERVICE_BUREAU=YES or SERVICE_BUREAU=NO. If omitted, the default is
SERVICE_BUREAU=YES. This operand controls the use of RACF (ACF/2 or CA-Top Secret)
when multiple license files are used as input to LMSINIT. 

If you have only one License File, you may ignore this operand. In a true service bureau
environment [SERVICE_BUREAU=YES], access to a particular license file cache must be
controlled by RACF so that users of Compuware products are restricted to using only the
product set validly licensed for them. 

A non-service bureau customer may want multiple license files but without the associated
RACF security checking that would normally occur. By specifying SERVICE_BUREAU=NO,
you can process multiple license files as if the data in them were all contained in a single file.
That is, the requirement to define the license file names to RACF is eliminated.

Values: NO|YES

Default: YES

Required: no

SMF_ID
Description: The value specified on the SMF_ID operand defines the SMF Record ID number to be used on
all SMF records written by the License Management System. The SMF_ID must be a three-
digit number in the range of 128 through 255.

If SMF_ID is not specified, then SMF recording will not take place regardless of the
specification on any license file concerning this recording. Therefore, this operand is
required before any SMF recording can occur.

You must coordinate the use of SMF identifiers so that no duplicate numbers are defined to
any program or system writing SMF records. Check with your systems programmer to ensure
that the SMF_ID value you have chosen is not already in use.

In the following example, the values allowed for LMS, SMF record IDs 128 through 255, are
included in the value range 100:255 on the SYS option, and therefore are eligible to be written
by LMS.
SYS(TYPE(0:18,20:68,100:255),EXITS(IEFUSI,IEFU84,IEFUJV,IEFACTRT,IEFU83,IEFUJI
,IEFUTL,IEFU29,IEFU85),INTERVAL(SMF,SYNC),DETAIL)

If the value specified on the SMF_ID LMS parameter is not specified on the SYS option in
SMFPRMxx, the following warning message will be issued by LMS during initialization:
LM6095W SMF RECORD nnn IS NOT BEING RECORDED BY SMF. VERIFY IN SMFPRMXX

Where nnn equals the SMF_ID.

Note: Specifying SMF_ID here does not automatically start SMF recording. SMF recording
is performed on a product-by-product basis and is activated via an indicator within the
file itself. This operand and its value only define which SMF_ID will be used when SMF
recording is activated.

Default: 241

Required: no
License Management System (LMS) Configuration and Administration 55

SMF_LOGALL
Description: Specifying YES forces all license check-out and check-in to be logged to the SMF data
sets regardless of the settings of the SMF_LOG parameters within the license file. This
causes SMF logging indicators in the license file to be ignored.

Values: NO | YES

Default: NO

Required: no

SMF_SERVER
Description: When running in CLF (Consolidated License Facility) mode, specifying YES indicates that
SMF data is to be sent to the server, and the server is to write out the SMF records.

Values: NO | YES

Default: none

Required: no

EMERGENCY
Description: LMSINIT has the ability to load an emergency license cache even if the license file is
unavailable or has become corrupted. The value required on the EMERGENCY operand is
obtained by calling Compuware Customer Support to request an emergency password.

Remove all LICENSE_DSNAME statements from the LMS client PARMLIB member and
submit the JCL.
When a legitimate emergency password is present in the LMS client PARMLIB member,
all Compuware products will be allowed to execute on the system.

Default: none

Required: no

CHKPT_DSNAME
Description: Required operand. License Management System requires a checkpoint dataset to be available
LMSINIT and to certain operating system exits at all times. This dataset is created
automatically by LMSINIT if it does not already exist, or it is updated if it does exist. You
must specify the 1- to 38-character name of this dataset, either using the parameters
described here, or by a special DD statement in the LMSINIT JCL. 

The user ID under which LMSINIT is run must have ALTER access to the security
system(RACF, ACF/2, CA-Top Secret) entity named by this dataset name. The IDCAMS utility
is dynamically invoked to define this dataset.

Default: none

Required: yes
56 Enterprise Common Components Advanced Configuration Guide

CHKPT_VOLSER
Description: This parameter specifies the 6-character volume serial of the DASD volume on which the
checkpoint dataset is to reside. If it does not exist, your system installation defaults for VSAM
datasets are used to determine the placement of this dataset. You must ensure that any
VOLSER you specify is consistent with the SMS class definitions that may also exist.

Default: none

Required: no

CHKPT_STORCLASS
CHKPT_DATACLASS
CHKPT_MGMTCLASS
Description: These parameters specify the names your installation has chosen to describe the allocation of
this VSAM checkpoint dataset. If specified, these parameters are used within the IDCAMS
DEFINE control statements when the dataset is created.

Default: none

Required: no

SITE_WARNING
Description: The value specified on the SITE-WARNING parameter specifies whether you want LMSINIT
to complete with a return code of 4 whenever SITE records in a license file are skipped (YES),
or you want LMSINIT to complete with a return code of 0 (NO). LMS 1.0 always completed
with a return code of 4 when LMSINIT detected that there were SITE records in the license
file that were not loaded because their SITE number was not included in the SITE()
parameter. If you omit the SITE_WARNING parameter, this behavior will exist in LMS 4.0 as
well. But, if you know that you are skipping SITE records, and you want a return code of 0 so
that your automated operator program will detect this return code, then include the
SITE_WARNING parameter and specify a value of NO. If this parameter is omitted
SITE_WARNING=YES is used as a default.

Default: YES

Required: no
License Management System (LMS) Configuration and Administration 57

SUCCESS_CMD
WARNING_CMD
ERROR_CMD
Description: These three LMSINIT parameters define master console commands that can automatically be
issued by LMSINIT. LMSINIT can complete with a return code of 0, a return code of 4, or a
return code of 8 or greater. Each of these three conditions can have a unique console
command associated with it. LMSINIT will issue the command that represents the current
return code.

Compuware does not supply any procedures to be started by these commands. It is the
customer’s responsibility to ensure that any PROC specified in a command exists in an
appropriate procedure library.

The examples below issue an Z/OS “START” command. But any valid operator command
could be issued as well.

—If no command is specified for a particular return code value, then no command is issued
when that return code occurs.
—Any, all, or none of the three return code conditions can have a command associated with
it.
—Commands can be the same or different for each of the three return codes.
—The commands will be issued as if they were entered at the Master Console, and the
Security (RACF, ACF/2 or CA-Top Secret) USERID will be the USERID under which LMSINIT is
running. Ensure that this USERID has the appropriate authority to issue Master Console
commands.

Rules for coding these commands follow:
—If the command contains blanks, then enclose the entire command in single (’) or double
(") quotes.
—If the command contains blanks and single quotes, then enclose the entire command in
double (") quotes.
—If the command contains blanks and double quotes, then enclose the entire command in
single (’) quotes.
—The single or double quotes will be removed before the command is issued.

Example:

SUCCESS_CMD("START someproc,PARM=’RC=0’")
WARNING_CMD(’START othrproc,PARM="RC=4"’)

Default: none

Required: no

EMAIL_OPTION
Description: NONE indicates no e-mail messages are generated for any option. WARN indicates that e-
mail messages are generated for options that are allowed to run, but a warning condition
exists (for example, option within 14 days of expiration). FAIL indicates that e-mail messages
are generated only if the option is not allowed to run.

Values: NONE | WARN | FAIL

Default: E-mail messages are generated for option warnings and failures

Required: no
58 Enterprise Common Components Advanced Configuration Guide

EMAIL_PRODUCT
Description: NONE indicates no e-mail messages are generated for any product. WARN indicates that e-
mail messages are generated for products that are allowed to run, but a warning condition
exists (for example, product within 14 days of expiration). FAIL indicates that e-mail
messages are generated only if the product is not allowed to run.

Values: NONE | WARN | FAIL

Default: E-mail messages are generated for product warnings and failures

Required: no

TCPIP_NAME
Description: By including this operand, you indicate that you want to activate the automatic e-mail
notification facility.

TCPIP_NAME specifies the name of the TCP/IP protocol stack that is active on this CPU:

—If you are using IBM’s TCP/IP (release 3.2, 3.4 and above), then this name must match the
name specified as TCPIPJOBNAME in the TCPDATA member of the TCPPARMS dataset used
to initialize TCP/IP. If you do not know what this name is, your mainframe network
administrator will be able to find this name and tell you what it is.

—If you are using the Interlink Corporation’s TCPaccess TCP/IP (release 4.1 and above), then
this name must match the SSN= operand on the EXEC statement in the procedure used to
invoke the TCPaccess TCP/IP. If you do not know what this name is, your mainframe
systems programmer will be able to find the TCPaccess procedure in the system PROCLIB
and tell you what is coded on the SSN= operand.

Default: none

Required: no

MAIL_SERVER_NAME
Description: Although this operand can be named MAIL_SERVER_NAME, the value you specify must be
the name (known to the domain name server for your Z/OS host) of your mail server. The
host, represented by this name, must be the one capable of receiving and forwarding Simple
Mail Transport Protocol (SMTP) mail message for your enterprise. If you include this
operand, do not also specify MAIL_SERVER_ADDR.

Default: none

Required: no
License Management System (LMS) Configuration and Administration 59

MAIL_SERVER_ADDR
Description: Although this operand can be named MAIL_SERVER_ADDR, the value you specify must be
the IP address (in dotted decimal notation) of your mail server. The host represented by this
name must be the one capable of receiving and forwarding Simple Mail Transport Protocol
(SMTP) mail messages for your enterprise. If you include this operand, do not also specify
MAIL_SERVER_NAME.

Note: You cannot specify both MAIL_SERVER_ADDR and MAIL_SERVER_NAME. These
operands are alternate methods for specifying the same resource to LMSINIT. One of these
two methods MUST be chosen, but both of them cannot be.

Default: none

Required: no

MAIL_SERVER_PORT
Description: Although this operand can be named MAIL_SERVER_PORT, the value you specify must be
the port number that your mail server listens on to receive Simple Mail Transport Protocol
(SMTP) mail messages. If you omit this operand, a default value of 25 is used by LMS.

Default: none

Required: no

MAIL_FROM_NAME
Description: Specify the Internet e-mail address (or name) in the form [email protected] of the
individual (or department) designated as the sender of e-mail messages. This name will
appear as the FROM: name on all e-mails automatically generated by the License
Management System and will receive a copy of all e-mail messages generated.

Default: none

Required: yes

MAIL_TO_SEC_NAME
Description: Specify the e-mail address (or name) that will receive all automatically generated e-mail
messages relating to product licensing errors.

This address (or name) can be the name of an individual (or department) within your
organization. Even if this name is of an individual (or department) within your organization,
you must specify this name in the Internet format, not in a format used locally by your
institution.

Default: none

Required: yes
60 Enterprise Common Components Advanced Configuration Guide

MAIL_TO_ABN_NAME
Description: Specify the e-mail address (or name) that will receive all automatically generated e-mail
messages relating to Compuware License Management software errors (program ABENDs).
This address (or name) can be the name of an individual (or department) within your
organization. Even if this name is of an individual (or department) within your organization,
you must specify this name in the Internet format, not in a format used locally by your
institution.

Default: none

Required: yes

IPV6
Description: This specifies that TCP/IP communication using the specified TCP/IP region should attempt
to use the IPv6 protocol.

Values: YES|NO

Default: none

Required: no

License Files
Zero or more license files can be used as input to LMSINIT. Each file is described by a //CWLFnnnn DD
statement, where nnnn are any letters or numbers you choose. The remainder of the DD statement
describes the name and disposition of one license file.

LMSINIT requires at least one license file unless the Emergency() parameter is specified. In this case
only no //CWLFnnnn DD need be supplied.

Message Suppression and Distribution

This section describes the parameters an administrator must specify to activate the LMS Message
Suppression and Distribution feature. The Message Suppression and Distribution (MSD) allows an
administrator to tailor the number, content, and destination of warning and error messages
generated by the License Management System (LMS). It provides a method whereby an administrator
can choose how often certain messages are generated, whether or not these messages should be
surrounded by the messages and codes enclosed in asterisks, and specifies where these messages are to
be sent. In addition, you can specify your own text to replace the LMS text for messages sent to the
Compuware product(s).

Message suppression is performed on a Product/Version or Option/Version basis. That is, each

Product/Option/Version will receive the number of messages specified per day (starting when
LMSINIT is executed, which resets the date value).

Conditions
Two different conditions are handled by these LMSINIT parameters:

License Warning messages are generated when a product is allowed to

Warnings execute on the current CEC/LPAR, but there is some condition that
requires message generation. This condition could be that an
emergency password is in effect, or that a particular product or
option is within 14 days of expiring.
License Management System (LMS) Configuration and Administration 61

License Failure messages are generated when a product is NOT allowed to

Failures execute on the current CEC/LPAR. This condition could be that the
product is not licensed on this LPAR, or that the license has
expired.

WARNMSG_CONTENT
Description: VERBOSE specifies that the prologue and epilogue message and codes enclosed in asterisks
will be generated. TERSE specifies that only the message(s) specific to the event (i.e. no
prologue or epilogue messages) will be generated.

Values: VERBOSE | TERSE

Default: VERBOSE

Required: no

WARNMSG_LIMIT
Description: Specifies how many times per day messages will be generated and distributed for each
warning condition. A value of zero indicates that there is no limit: as many times as the
warning condition occurs messages will be generated and distributed.

Values: A numeric value between 0 and 9999.

Default: 0

Required: no

WARNDEST
Description: Many possible destinations can be specified for the WARNDEST parameter.

Values: The warning message (as modified by the WARNMSG_CONTENT parameter) is sent to
destinations defined as follows:
PRODUCT message is sent to the Compuware product. This is the default. 
CONSOLE message is sent to a system console (see the DEST, DESC, and CONSNAME
operands below). 
FAULTMGR message is sent to Abend-AID Fault Analytics.
E-MAIL message is sent via e-mail to the designated recipient.
TSOUSER message is sent to a TSO user (via TPUT). See the MSG_USERID parameter
below.
SMF a record is written to the SMF dataset regardless of the setting of other LMS SMF
parameters.

Default: none

Required: no

WARNTEXT
Description: WARNTEXT statement contains the message text string to be sent to the Compuware
product destination.

Values: String message to be sent to the Compuware product. Only the product will receive this
message. The other destinations will receive the messages as defined by LMS. If this
operand is specified, then LMS automatically includes PRODUCT in the WARNDEST
62 Enterprise Common Components Advanced Configuration Guide

parameter, even if it was not specified. This text can be from 1 to 56 bytes long and
must be enclosed in double quotes ("").

Default: none

WARNTEXT=“message_text”

Required: no

FAILMSG_CONTENT
Description: VERBOSE specifies that the prologue and epilogue message and codes enclosed in asterisks
will be generated. TERSE specifies that only the message(s) specific to the event (i.e. no
prologue or epilogue messages) will be generated.

Values: VERBOSE | TERSE

Default: VERBOSE

Required: no

FAILMSG_LIMIT
Description: Specifies how many times per day messages will be generated and distributed for each failure
condition. A value of zero indicates that there is no limit: as many times as the failure
condition occurs messages will be generated and distributed.

Values: A numeric value between 0 and 9999.

Default: 0

Required: no

FAILDEST
Description: The failure message (as modified by the FAILMSG parameter) is sent to each specified
destination. Many possible destinations can be specified for the FAILDEST parameter.

Default: PRODUCT

Values: PRODUCT message is sent to the Compuware product. This is the default. 
CONSOLE message is sent to a system console (see the DEST, DESC, and CONSNAME
operands below). 
FAULTMGR message is sent to the Compuware Fault Analytics product.
E-MAIL message is sent via e-mail to the designated recipient.
TSOUSER message is sent to a TSO user (via TPUT). See the MSG_USERID parameter
below.
SMFA a record is written to the SMF dataset regardless of the setting of other LMS SMF
parameters.

Required: no

FAILTEXT
Description: The message text that will be received by only the Compuware product upon a fail
condition.

FAILTEXT(“message_text”)
License Management System (LMS) Configuration and Administration 63

Values: 1 to 56 byte message string enclosed in double-quotes (“”) to be sent to the Compuware
product. Only the Compuware product will receive this message. The other
destinations specified in the FAILDEST statement will receive messages as defined by
LMS. If this parameter is specified, then LMS automatically includes PRODUCT as a
FAILDEST parameter value.

Default: none

Required: no

ROUTCDE
Description: This parameter applies when FAILDEST=CONSOLE or WARNDEST=CONSOLE is specified.
Include the console routing codes to be used for all messages sent to the console. Refer to the
IBM publication IBM Programming - Assembler Services Reference for a description of these
codes and their meanings. If both ROUTCDE and CONSNAME statements are specified, then
the messages will go to all of the consoles specified by both parameters.

Default: 2 and 11

Required: no

DESC
Description: This parameter applies when FAILDEST=(CONSOLE) or WARNDEST=(CONSOLE) is specified.
Specify the console descriptor codes to be used for all messages sent to the console. Refer to
the IBM publication IBM Programming - Assembler Services Reference for a description of these
codes and their meanings. If this parameter is omitted, then no descriptor codes are used.

Default: none

Required: no

CONSNAME
Description: This parameter applies when FAILDEST =CONSOLE or WARNDEST=CONSOLE is specified.
Specify the 1- to 8- character name of the console which is to receive messages from LMS. If
this name is omitted, then messages are sent to consoles using the routing codes specified for
ROUTCDE. If both ROUTCDE and CONSNAME are specified, then the messages will go to all
of the consoles specified by both parameters.

Values: 1- to 8-character name of the console

Default: none

Required: no

MSG_USERID
Description: This parameter applies when FAILDEST =TSOUSER or WARNDEST =TSOUSER is specified. Specify
the 1- to 8-character SAF user ID to which warning and failure messages are sent. If this
parameter is omitted, and TSOUSER is specified, then the user ID under which LMS is
running (i.e. the USERID which invoked the Compuware product) will receive the messages. 

Note: This user ID must be logged on to the same LPAR on which the Compuware product is
running for the distribution to be successful.

Default: none

Required: no
64 Enterprise Common Components Advanced Configuration Guide

HISTORY_FILE
Description: By including this operand you are indicating that you want the history file facility enabled.
Specifying LOCAL indicates that the history file is to be maintained locally on the LPAR.
When this operand is specified, then HISTORY_DSNAME and HISTORY_TRACKS must also
be specified. HISTORY_VOLSER, HISTORY_STORCLASS, HISTORY_DATACLASS and
HISTORY-MGMTCLASS may optionally be specified as well.

Values: LOCAL

Default: none

Required: no

HISTORY_DSNAME
Description: This parameter is required when HISTORY_FILE=LOCAL is specified, otherwise it not used. Specify
the valid 1- to 38-character dataset name for the history file. This name must conform to the
normal requirements for dataset names.

Note: The user ID under which LMSINIT is run must have ALTER access to this dataset
defined in the security system (RACF, ACF/2 OR CA-Top Secret). LMS dynamically invokes
IDCAMS to define this dataset. This dataset must be unique, it must not be the same as the
client history dataset name if history file processing is active in the client LMS subsystem.

Default: none

Required: no

HISTORY_TRACKS
Description: This parameter is required when HISTORY_FILE=LOCAL is specified, otherwise it not used. Specify
the number of tracks to be used as both the primary and secondary extents for the history
dataset. This value must be numeric within the range of 15 to 9999. Compuware
recommends at least 100 tracks be used for this dataset.

Default: none

Required: no

HISTORY_VOLSER
Description: This parameter is required when HISTORY_FILE=LOCAL is specified, otherwise it not used. This
parameter specifies the 6-character volume serial of the DASD on which the history file will
be allocated. LMS automatically defines the history file for you if it does not exist and then
uses this dataset for subsequent processing. Please check with your SMS administrator to
determine if a volume serial number is required or not.

Default: none

Required: no
License Management System (LMS) Configuration and Administration 65

HISTORY_STORCLASS 
HISTORY_DATA_CLASS 
HISTORY_MGMTCLASS
Description: This parameter is required when HISTORY_FILE=LOCAL is specified, otherwise it not used. These
parameters specify the names your installation has chosen to describe the allocation of this
VSAM history dataset. If specified, these parameters are used within the IDCAMS DEFINE
control statements when the dataset is created.

Default: none

Required: no

LPAR_MODE
Description: Specify the mode of sub-capacity licensing you want for this client LMS subsystem. The two
choices are SIZE and UTIL.

Values: SIZE is the default and indicates that the capped size of the LPAR in MSUs is to be used
as the determining factor in license conformance. 

UTIL can be specified to indicate that the current rolling 4-hour average MSU
utilization of the LPAR is to be used as the determining factor in license conformance.

You may specify LPAR_MODE=SIZE or LPAR_MODE=UTIL.

If you wish, you may spell out utilization by specifying LPAR_MODE=UTIL.
If this parameter is omitted, the LPAR_MODE=SIZE is used by default.

Default: SIZE

Required: no
66 Enterprise Common Components Advanced Configuration Guide
 67

Host Communications Interface (HCI)

Configuration and Administration 4

HCI Overview
The Host Communications Interface (HCI) is a facility that provides connectivity between
mainframe-based programmer productivity software and peer-node software running on other
platforms in a network. These communications facilities provide a simple application programming
interface so that Compuware software can be written to communicate with peer programs running on
different platforms. Additionally, the communications system is flexible, simple to operate, and
reliable. It has been designed to support open-ended communications protocols, and it can operate
on older releases of the MVS operating system. It allows application programs to communicate over
any one of several protocols without knowing which protocol is in use at any given time.

The HCI also serves as a server activation facility that is responsible for starting and monitoring
application programs that are using the communications facilities.

And finally, the HCI has been designed with no upper limit on the number of concurrent sessions
supported, nor on throughput rates. The following figure shows how the HCI fits into the scheme of
the TP application and the MVS subsystem components.

Figure 17. TP Subsystem, HCI and Application

Application
TCP/IP
Application
HCI

VTAM
Application

HCI Installation Considerations

This section describes considerations for installing the Host Communications Interface (HCI) which
is a requirement for several Compuware products.

System Security
For the HCI to properly function, it must be permitted access to the following, regardless of whether
it is a started-task or a submitted job:

• All libraries in the STEPLIB concatenation must be Authorized. 1

• HCI PARMLIB dataset containing HCI Server Activation Facility members.

The HCI must be authorized for the following via the MVS system security package:
1. If you are using Topaz for Total Test Functional Test, you will need to add the Language Environment SCEERUN
library to the STEPLIB concatenation in the HCI start-up JCL.
68 Enterprise Common Components Advanced Configuration Guide

• To generate SDUMPs. If DMPPFX=SDUMP has been specified (the SDUMP specification is

recommended by Compuware).
• To output submitted jobs via an internal reader
• For operator commands with update authority:
– START
– STOP
– CANCEL
– MODIFY (if OPCMD=MODIFY has been specified)

Security Settings
HCI can switch ACID (UserID) while processing certain requests. Some security package settings may
then prevent the HCI from writing to JES sysout after this is done. Installation with such strict
security settings will need to allow the HCI task proper access to the JESSPOOL class.

Installations that have such settings—that limit any or all user access to output from other users—can
do so by setting the appropriate profiles for the security class JESSPOOL.

Profiles for JESSPOOL are in the format:

Local-nodename.userid.jobname.jobid.dsnumber.name

Using combinations of userIDs and wildcard characters, output viewing can be limited on a userID or
groupID basis as the installation chooses.

Please consult your installation's security software administration documentation for additional
information. For RACF installations, controlling access to output via the JESSPOOL class is
documented in IBM’s z/OS Security Server RACF Security Administrator's Guide, in the section entitled,
“Controlling Access to Spool Data”.

For Topaz for Total Test Functional Test Users

• For users of Topaz for Total Test, settings should be REGION=0M and Language environment
ALL31(ON) and STACK(,,ANYWHERE).

For example:

Wrong: STACK(131072,131072,BELOW,KEEP,524288,131072)

CORRECT: STACK(131072,131072,ANYWHERE,KEEP,524288,131072)

• Add the DD statements1 (below) to the HCI start-up JCL when running Topaz for Total Test
through HCI.

//SYSOUT DD SYSOUT=*

//CEEDUMP DD DUMMY

//XASYSOUT DD SYSOUT=*

For Top Secret Users

For users of Top Secret for system security, it requires a new facility to be placed in the Facility Matrix
Table. Use the following facility control options:

FACILITY (USER33=NAME=HCI)
1. PTF CXS902A removes the need for //XASYSOUT
Host Communications Interface (HCI) Configuration and Administration 69

FACILITY(HCI=MODE=FAIL)

FACILITY (HCI=NOABEND, ASUBM, NOAUDIT, AUTHINIT, NOINSTDATA)

FACILITY (HCI=MULTIUSER, PGM=HCI, SHRPRF, SIGN(M), NOTSOC)

FACILITY (HCI=RES, KEY=8, NOXDEF, NOLUMSG, NOSTMSG)

Configuration Considerations
In order to facilitate communication with a z/OS LPAR, the communications software Host
Communications Interface (HCI), must be installed and configured on that LPAR. Depending on the
Compuware mainframe applications and functionality you plan to use, additional CSS TP parameters
may need to be specified. Detailed explanations of each CSS TP configuration parameters are
provided in the installation manuals of the Compuware products requiring them.

The ECC media provides an automated mainframe upload and SMP/E installation facility contained
within the media browser. The automated installation facility for ECC, uploads, restores, and
performs an SMP/E installation of the ECC software. During the automated installation process, a
dataset, hlq.CYnnnnnn.SMPE.DATA is created containing the dataset names and other variables related
to your installed ECC software.

The Compuware Shared Services mainframe Transaction Program (CSS TP) serves as the primary
contact point between the mainframe and certain Compuware products, including the Topaz
Workbench. The services provided include job submission, output viewing, dataset retrieval and
update, launching of Xpediter-based debugging sessions, initiating sub-tasks to support File-
AID/Eclipse or File-AID Data Privacy sessions, and many other services.

For Strobe sites that use HCI, use the same port number to configure HCI for the Topaz Workbench.
The HCI you configure for Topaz Workbench will then run instead of the HCI you have set up for
Strobe and it will be transparent to Strobe users.

For DevEnterprise sites that use HCI, you may optionally merge the HCI you configure for Topaz
Workbench with the HCI you have configured for DevEnterprise.

Preliminary Considerations
Compuware’s Host Communication Interface (HCI) and Compuware Shared Services (CSS) are
required in order to communicate with a mainframe host.

You need to know the dataset names of the following SMP/E controlled libraries:

• ECC load library (SLCXLOAD)1

• ECC load library (SLCXAUTH)1

When using the Compuware Installer to generate the JCL to SMPE install ECC, tables are created
containing these dataset names.

SLCXAUTH and SLCXLOAD may be placed in the LINKLIST in either order. 


— For Abend-AID products: BDCAS and TDCAS must still define SLCXAUTH in the STEPLIB.

— SLCXAUTH is also required to be in the STEPLIB for the procs for HCI, SSAS started task, and STASK,
created when running the HCIPROCS job.

1. In previous releases of ECC, SLCXLOAD and SLCXAUTH were associated only with CSS. However, for ECC 16.05 or higher,
those libraries are used by all of ECC product facilities, including HCI, CSS, and LMS.
70 Enterprise Common Components Advanced Configuration Guide

Connection to z/OS Host

Before you configure the Host Communication Interface (HCI) on the z/OS host, you must be able to
run TCP/IP traffic from the workstation to the host.

To avoid any unpredictable connection issues, make sure all current IBM maintenance is applied to
TCP/IP.

Collect TCP/IP Information

• TCP/IP region name
• TCP/IP host name or IP address
• TCP/IP port number

Dispatching Considerations
The HCI is a multiple-user address space. The HCI dispatching priority should be below VTAM and
TCP/IP and similar to other multiple-user address spaces such as CICS, IMS, etc. Setting the HCI
dispatching priority lower than other multiple-user address spaces may lead to TIMEOUTS.

HCI Parameter Customization

Located in SLCXCNTL, the HCI Parameter member (default: HCI00) contains the customization
parameters for HCI, CSS TP and (optionally) DevEnterprise. A copy of this member must reside in
the //CWPARM concatenation of the CMSC (see Compuware Mainframe Services Controller
(CMSC) Configuration and Administration for more information.

Configuration Parameters
SYSID
Description: SYSID is the short form for SUB_SYSTEM_ID. Must be specified either in the XML parameter
document or on the PARM= operand of the EXEC statement that invokes the HCI. If
specified in both places, the EXEC statement PARM overrides the SYSID specified here if they
differ. Must be four characters in length and is used by the HCI initialization routines to
create a z/OS subsystem. Must be unique among all subsystems running on this LPAR. Must
not be defined in SYS1.PARMLIB. The HCI dynamically creates this subsystem. Each HCI to
run on a single LPAR must have its own unique SYSID value.

Default: none

Required: yes

ARMNAME
Description: The Automatic Restart Management (ARM) Facility in the HCI is activated by including this
element and specifying a non-null name. Element names that begin with A through I and
SYS are reserved for use by IBM.

Default: none

Required: no
Host Communications Interface (HCI) Configuration and Administration 71

ARMTYPE
Description: If ARMNAME is specified and if the installation requires that an element type be specified in
the IXCARM TYPE=REGISTER macro, then specify the type here. Element types that start
with A through I and SYS are reserved for use by IBM.

Default: none

Required: no

DAE
Description: The z/OS Dump Analysis and Elimination (DAE) facility can be detrimental in obtaining
dumps of the HCI.

Default: NO

Required: none

Values: NO|YES

NO Causes the HCI to change portions of the summary dump in such a way that DAE
never suppresses an HCI dump.

YES Causes the DAE facility to suppress what it considers duplicate dumps.

DEFAULT_USER
Description: Specifies the name of a valid RACF (ACF/2 or TOPSECRET) user ID to be used by the HCI
when TP jobs are submitted or started and when there is no other user ID available.

The user ID must be assigned within the security system and granted authority to
perform any processing the TP requires until the TP issues one of the set security calls.
Until that time, the new user ID is in effect.
Example: Ensure that the default user ID has either ACCESS(READ) or
ACCESS(EXECUTE) to the //STEPLIB DD used in the TP JCL and that it has appropriate
access to any other datasets that it processes under the default user ID.

Note: Once the TP has issued a security call, the default user ID is no longer used for
access because the TP starts running under the user ID passed in the security call.

Default: HCIUSER

Required: no

DMPCLAS
Description: Specifies a valid JES/n output class to which SNAP dumps are to be directed. If this attribute
is omitted, then the DMPPFX, DMPUNIT and DMPVOL attributes define the output dataset
to contain SNAP dump information.

Default: none

Required: no
72 Enterprise Common Components Advanced Configuration Guide

DMPPFX
Description: The prefix of all dumps taken by the HCI.

Values: SDUMP specifies that all dumps taken by the HCI are system dumps (via SDUMPX) and
are directed to the SYS1.DUMPxx (or customer-defined) dataset. The DMPUNIT,
DMPVOL, and DMPCLASS attributes are ignored. 

prefix causes a dataset to be allocated whose DSNAME is prefixed by this prefix and a
SNAP dump is taken to this dataset. In this case, the DMPUNIT and DMPVOL attributes
further define the location of the dataset. The prefix can be from 1 to 12 valid
characters for a DSNAME prefix. Note that the user ID under which the HCI is
executing must have ACCESS(ALTER) to this DSNAME prefix.

Default: SDUMP

Required: no

DMPUNIT
Description: Specifies the unitname for SNAP dumps allocated by the HCI. If this attribute is omitted,
then the DMPPFX attribute must specify SDUMP.

Values: a valid name for DASD allocation at your installation; for example, DMPUNIT=SYSDA.

Default: SDUMP

Required: no

DMPVOL
Description: Specifies the VOLSER for SNAP dumps allocated by the HCI. If this attribute is omitted, then
the DMPPFX attribute must specify SDUMP. VOLSER must be a valid volume serial number
for DASD allocation at your installation.

Default: none

Required: no

EMCS_CONSOLE_NAME
Description: Provides a mechanism to allow installations to guarantee uniqueness between ports within
an HCI and between LPARs in a SYSPLEX through the use of system symbols. This prevents
an EMCS console from remaining in the system until an IPL occurs.

The use of system symbols in the parameter value will guarantee uniqueness between ports
within an HCI, and between LPARs in a SYSPLEX.

CAUTION: HCIPlex users must use dynamic EMCS console naming

(EMCS_CONSOLE_NAME parameter should not be used).

Values: maximum 8-character name

Default: Current time appended to LPAR or system name

Required: no
Host Communications Interface (HCI) Configuration and Administration 73

HCIPLEX_NAME
Description: Specifies the name of the HCIPlex. By specifying a value for this parameter, the HCIPlex
feature is enabled.

Values: 1 to 8 alphanumeric characters. The first character must be an alphabetic or national

character.

Default: none

Required: no

HCI_PROCNAME
Description: This parameter is only needed when the HCI job name is not the same as the name of the
member containing the PROC

Values:

Default:

Required: no

JESCHAR
Description: Specifies the command character used from the master console or from an SDSF log screen to
issue commands to the JES2 or JES3 subsystem. The value of this attribute is used by the HCI
as the first character of the command used to cancel TP programs that have been started by
the Server Activation Facility, but which have not registered with the HCI within the
allowable time limit.

For example, the command for JES2 using the default dollar sign ($) character:

$CJnnnnn

The same command for JES2 using the forward slash (/):

/CJnnnnn

In this way, multiple JES subsystems can support HCI TP programs.

Default: $ (U.S. dollar sign)

Required: no

JESID
Description: Specifies that either JES2 or JES3 is the primary subsystem for the LPAR on which the HCI is
executing. Various functions within the HCI depend on the correct setting of this attribute.

Values: 2|3

Default: 2

Required: no
74 Enterprise Common Components Advanced Configuration Guide

JESJPRM
Description: A value of YES specifies that HCI should add a /*JOBPARM SYSAFF=* for JES2 systems or a
//*MAIN SYSTEM=xxxxxxxx for JES3 systems to JCL submitted by the HCI to start TP
programs. If your JCL for TP programs is to run on systems other than the one on which the
HCI is executing, then omit this attribute or specify JESJPRM=NO.

Values: NO|YES

Default: NO

Required: no

JOURNALn
Description: Specifying journal datasets allows for logging of HCI activity. The HCI uses the Journaling
Facility to write out diagnostic information that may then be provided to Compuware
developers. Journal datasets cannot be shared across multiple HCI instances. Each HCI
instances requires its own set of journal datasets.

Values: valid dataset name

Default: none

Required: no

JRNMASK
Description: Specifies exactly 16 hexadecimal digits (0-9 and A-F) that are used to control which journal
events are to be collected when journaling is active.

Values: 16 hexadecimals

Default: 0000000000000002

hhhhhhhhhhhhhhhh is the 16-place hexadecimal specifying the number of events to be
written to the HCI journal. For example, sixteen zeros (0000000000000000) causes no
journal events to be written to the HCI journal, where sixteen Fs (FFFFFFFFFFFFFFFFFF)
causes all journal events to be written to the HCI journal.

Required: no

MAXCCBS
Description: Specifies the maximum number of concurrent conversations or connections that the HCI will
support. Setting this attribute to a large number increases private storage usage, but
otherwise does not cause any negative effects.

Values: 128 through 32768. Each CCB is 1376 (decimal) bytes long.

Default: 378

Required: no
Host Communications Interface (HCI) Configuration and Administration 75

MAXDCBS
Description: Specifies the maximum number of concurrent discrete destinations that the HCI will support.
Setting this attribute to a large number increases private storage usage, but otherwise does
not cause any negative effects.

Values: 8 through 32768. Each DCB is 760 (decimal) bytes long.

Default: 378

Required: no

MAXJRES
Description: Specifies the maximum number of concurrent journal requests that the HCI will support.
Setting this attribute to a large number increases private storage usage, but otherwise does
not cause any negative effects. In addition, a large number ensures that no journal records
are lost due to JRE exhaustion.

Values: 512 through 32768. Each DCB is 16 (decimal) bytes long.

Default: 8192

Required: no

MAXLUBS
Description: Specifies the maximum number of SNA LU2 sessions that the HCI will support. If you are not
supporting any LU2 remote partners, then allowing this attribute to use the default is
sufficient.

Values: 1 through 2768. Each LUB is 496 (decimal) bytes long.

Default: 16

Required: no

MAXRCBS
Description: Specifies the maximum number of concurrent TP program address spaces that the HCI will
support. Each address space can be associated with multiple TP users, but in most cases it is a
one-for-one correspondence. Region control blocks (RCBs) are allocated from ECSA (SP=241),
and therefore this number should not be excessively bigger than necessary.

Values: 8 through 32768. Each RCB is 96 (decimal) bytes long.

Default: 378

Required: no

MAXUIBS
Description: Specifies the maximum number of concurrent TP program TPNAMES that the HCI will
support. User interface blocks (UIBs) are allocated from ECSA (SP=241), and therefore this
number should not be excessively bigger than necessary.

Values: 8 through 32768. Each UIB is 1040 (decimal) bytes long.

Default: 378

Required: no
76 Enterprise Common Components Advanced Configuration Guide

MAXWRES
Description: Specifies the maximum number of concurrent work requests that the HCI will support. Work
request elements (WREs) are allocated from ECSA (SP=241), and therefore this number
should not be excessively bigger than you find necessary.

Values: 8 through 32768. Each WRE is 1040 (decimal) bytes long.

Default: 4096

Required: no

OACBINT
Description: Specifies the time in hundredths of a second that the HCI will allow to elapse between
attempts to open a VTAM ACB specified by the ACBNAME attribute of an HCICNAMB
element.

Values: 1 through 360000.

Default: 3000

Required: no

OPCMD
Description: Specifies how operator commands are to be entered into the HCI.

Values: WTOR|MODIFY

WTOR Specifies that a Reply to Operator command (r nn,) is to be used. 

MODIFY Specifies that the z/OS MODIFY (F) command is to be used.

Default: WTOR

Required: no

PREPROC
Description: Specifies the name of a procedure in SYS1.PROCLIB (or an appropriate user procedure
library) that starts the initialization of the secondary HCI on each member of a parallel
sysplex. The main HCI is initialized by the customer via JCL or a started task. The HCI
automatically routes z/OS START commands to each other member of the sysplex indicating
that the PROC named in the PREPROC attribute be started. Name this PROC any maximum
eight-character name, but the PROC must be available to every member of the sysplex. 
If the SYSPLEX attribute is omitted (indicating no sysplex support requested), then the
PREPROC attribute is ignored.

Values: any maximum 8-character name

Default: HCIYPREP

Required: no
Host Communications Interface (HCI) Configuration and Administration 77

ROUTCMD
Description: Specifies whether TP programs that are initiated by START commands are to be routed to the
member of the sysplex indicated on the member in the HCI //PARMLIB DD.

Values: NO|YES

NO specifies that the z/OS START command is to be issued only on the system on
which the primary HCI is running.

YES specifies to route z/OS START commands to each z/OS in the SYSPLEX.

Default: none

Required: no

SECFAC
Description: Specifies the name of a Facility Class entity that is to be checked when a TP program issues a
CWOPER call in order to issue an operator command. The user ID under which the TP is
executing must have ACCESS=UPDATE to the Facility Class entity in order to issue the
CWOPER call.

Default: none

Required: no

SRVRJOB
Description: Specifies a one- to five-character job name prefix that the HCI uses for all TP programs
submitted by the HCI. A 1- to 3-digit numeric suffix is added onto this prefix and
incremented each time the job is submitted in order that the job names will be unique.
When the suffix reaches 9, 99, or 999.

Values: 1- to 3-digit numeric suffix

Default: HCITP

Required: no

SYSPLEX
Description: Specifies a 4-character subsystem ID to be assigned to each of the sysplex HCI members. The
value must be exactly four characters in length and must consist of uppercase letters and
numbers only. Omitting this attribute specifies that you do not want sysplex support to be
activated.

Values: 4-character subsystem ID

Default: none

Required: no
78 Enterprise Common Components Advanced Configuration Guide

TCP_ACEE
Description: Indicates whether the individual user or HCI security environment will be used for cross-
LPAR communications. If TCP_ACEE set to USER, each user needs to have their own fully
defined OMVS segment for any cross-LPAR communications. If TCP_ACEE set to HCI, the
OMVS segment of the HCI user ID will be used. 

This will only affect permissions for the TCP/IP connection and has no effect on dataset
permissions.

Values: USER | HCI

Default: USER

Required: no

TCPAMSG
Description: Specifies whether the TCPACCESS TERROR macro is to be used to display error messages if
your TCP/IP protocol stack is CA's TCPACCESS product.

Values: NO|YES

NO sends TCPACCESS messages to the //HCIPRINT DD.

YES uses the TCPACCESS TERROR macro to display error messages.

Default: NO

Required: no

TPSEC
Description: Specifies whether you want the HCI to ensure that the user ID under which a TP program is
executing has access to the TPNAME that it is connecting to.

Values: NO|YES

NO specifies that no RACF checking of the user ID versus the TPNAME is to occur.

YES specifies that the user ID must have ACCESS(READ) to the FACILITY CLASS entity
in order for the HCI to allow execution of the TP. The FACILITY CLASS entity name is
constructed by prefixing the TPNAME with the four-character subsystem ID of the HCI.

Default: NO

Required: no

TPT_NAME
Description: A TPT name override. (This is optional for DevEnterprise use only)

Default: none

Required: no
Host Communications Interface (HCI) Configuration and Administration 79

Topaz Workbench—CSS TP Parameters

Default member: HCIALL

PORT_CONFIG
Description: The PORT_CONFIG statement defines the start of a CSS TP definition section and denotes
the port number where the TP is to be run.

Default: none

Required: no

AUDIT
Description: The AUDIT statement will provide a means to choose whether security violation messages
will appear in the HCI job log whenever a Topaz Workbench user is denied access to a dataset
resource. Code a Y to cause these messages to be displayed; code N if they are not to be
displayed.

Values: NO|YES

NO does not display security violation messages.
YES displays security violation messages.

Default: NO

Required: no

CREDENTIALS
Description: The optional CREDENTIALS statement is used to enable or disable the ability of Topaz
Workbench users to optionally save their login credentials in a secure cache on their
workstation when connecting to the port defined by this configuration section.

Values: ENABLE|DISABLE

ENABLE allow users to optionally save their credentials. This is the default action if
CREDENTIALS is not coded.

DISABLE disallow the ability for users to save their login credentials on their
workstation. The Save credentials checkbox shown during Topaz Workbench login will
be disabled and no login information will be saved on the workstation hard drive.

Default: ENABLE

Required: no

CXTPMSGS
Description: The CXTPMSGS statement can be used to reduce the number of messages issued to the HCI
job log as a result of actions by Topaz Workbench users. A setting of FULL is recommended.

Values: FULL|QUIET|NONE

FULL All CXTP messages are issued
QUIET The frequently issued user activity messages CXTPMAI013I and CXTPREQ035I
80 Enterprise Common Components Advanced Configuration Guide

are suppressed; all other messages are issued.* 

NONE No CXTP messages are issued.

Default: FULL

Required: no

DISABLE_HLQ_WILDCARD
Description: If disabled, Topaz Workbench users are prevented from creating a filter with a wildcard in the
high-level qualifier.

Values: NO|YES

Default: NO

Required: no

ENDEVOR
Description: The ENDEVOR statement indicates to Host Explorer that CA-ENDEAVOR support is to be
enabled.

Values: NO|YES

YES CA-ENDEVOR is enabled for use by Host Explorer.
NO CA-ENDEVOR is disabled for use by Host Explorer.

Default: NO

Required: no

FILEAID
Description: The FILEAID statement indicates to Host Explorer whether File-AID Data Privacy or File-
AID/Eclipse support is to be enabled.

Values: NO|YES

YES File-AID Data Privacy and/or File-AID/Eclipse support is enabled for use by Host
Explorer.
NO File-AID Data Privacy and/or File-AID/Eclipse support is disabled for use by Host
Explorer.

Default: YES

Required: no

SYSOUT
Description: The SYSOUT statement provides a mechanism to allow installations to impose a “by user ID”
level of security by viewing output in the JES Explorer view of Topaz Workbench. This
optional setting will cause attempts to view output by users to be denied unless they are the
owning user ID. This means that no user can view any other user's output except for their
own.
Host Communications Interface (HCI) Configuration and Administration 81

A setting of USERID does not override any rules enforced by your security software.
Any rules in place that are more restrictive than by-userID security will continue to be
enforced by your security software.

Values: USERID|DEFAULT

USERID enables the by-userID security. 
DEFAULT rules of your installation's security software profiles and the JESSPOOL
resource class will dictate the handling of output. Compuware recommends using the
JESSPOOL resource class and your security software for the best and most flexible
security arrangement that meets your installation's requirements.

Default: DEFAULT

Required: no

UNITNAME
Description: This optional parameter allows the specification of an esoteric unit name if the default name
of VIO is not defined or not desired. Some functions performed by Topaz Workbench require
the CSS TP to allocate a temporary dataset. The allocation requires the specification of a
UNIT esoteric name. Typical esoteric names used by the different versions of MVS are VIO,
SYSDA, and SYSALLDA.

Values: unitname an esoteric unit name defined to the operating system.

Default: VIO

Required: no

NOTIFYONLY
Description: Deprecated. The NOTIFYONLY statement allows an optional reduction of notification
messages that are received by other LPARs in a more tightly coupled shared JES spool
environment. For example, a job executed on one LPAR may have its notification posted to
another LPAR.

In addition, the TSO user ID (the user ID specified in the JOB card NOTIFY=user
parameter ) being logged on to one LPAR or another influences the routing choice made
by the system. Because of these variables, some notification messages may be received
by Topaz Workbench for jobs executed on other LPARs even if LOCAL is specified.
Despite these occasional exceptions, coding this statement allows for a substantial
reduction in notification message traffic sent back to Topaz Workbench users.

Values: ALL|LOCAL

ALL means that notification messages issued by other systems are to be included in the
job notification back to Topaz Workbench. 
LOCAL means that only job notification messages from the LOCAL LPAR where this
configuration is running should be included in the job notifications returned to Topaz
Workbench.

Default: ALL

Required: no

READTIMEOUT
Description: The read timeout value is the number of seconds Topaz Workbench will wait for a response
from the mainframe before terminating the request and notifying the user.
82 Enterprise Common Components Advanced Configuration Guide

READTIMEOUT specifies number of seconds to be used for the read timeout value for
all users connecting to this port. Users will be able to set their read timeout values to a
lower value (shorter time period), but will not be able to exceed the duration value
specified. Values below 30 may cause frequent interruptions to the user's session as
some requests can take longer to execute than others.

Values: 0 to 999 seconds. Coding 0 allows individual users to set the read time out duration
without limitation.

Default: 0

Required: no

APPLICATION
Description: The APPLICATION statement identifies an application profile name also known to the
system security software which can optionally be used to further restrict access to the TP port
to specific users or groups.

User access to this TP port can be restricted by use of an APPL class profile if it is supported
by your security software (such as RACF). To use an APPL class profile to restrict access to
certain users or groups, specify an application name. The name can be any name you choose
to represent the port or system on which this TP is executing, for example WBPROD,
WBTEST, or CXTP01. Then add the chosen name as a profile in the APPL class to your
security software database. 

User access can then be controlled by assigning user IDs or groups to have READ access to
that profile. Users or groups that do not have READ access will not be permitted to use the
port and their Topaz Workbench session will be terminated. 

If the APPLICATION profile name is not specified, then access to the TP port is based on user
ID and password authentication only. This is the default action and is consistent with the
behavior of all prior releases of Topaz Workbench. Therefore, most installations should not
specify an APPLICATION profile name and allow user authentication based on user ID and
password only.

Values: 1 to 8-character application profile name to be assigned to this TP port represented by

this TP Configuration. This same name must be made known to the security software.

Default: none

Required: no

CONSOLEPOE
Description: The CONSOLEPOE statement parameter gives the TP the capability to name a console,
which is also defined to your system security software in the CONSOLE class. This console
name is used to issue JES CANCEL and PURGE commands on behalf of Topaz Workbench as
a security Port of Entry (POE). Use of the CONSOLEPOE statement provides a mechanism for
installations to use conditional security rules to control which users or groups may issue
commands to the system using the WHEN(CONSOLE(console-name)) clause in security
profiles.

Security rules at some installations require a console name as a Port of Entry in order to
validate the authority of the command. At present, Topaz Workbench only issues $CJ
commands (JES2) or *MODIFY J=, C commands (JES3).The console name specified by the
CONSOLEPOE statement may be any name and the console name chosen must be defined
to the system security software as a console in the CONSOLE class. For RACF users, example
statements used to define the console are shown below. The console name may also be a
console already defined to the CONSOLE class, such as SDSF.
Host Communications Interface (HCI) Configuration and Administration 83

The console name chosen should not be the same name an existing hardware console.
There is no physical relationship between the JES Explorer console port of entry name
and a real MCS console.

Values: 2- to 8-character name also defined to the CONSOLE security class. After specifying a
CONSOLEPOE statement, the next time a JES Explorer user wishes to cancel a job or
purge output, the resulting command will be issued under the authority of the named
console as a security port of entry.

This means that security rules in place that specify conditional access, for example the
commonly used WHEN(CONSOLE(SDSF)) syntax, can also be specified with
conditional access using the named console from the CONSOLEPOE statement, for
example WHEN(CONSOLE(CXTP01)).

Note that the use of the CONSOLEPOE statement to establish a security port of entry
for conditional access to the JES2.CANCEL.* or JES3.MODIFY.* security profiles only
allows a user to issue the necessary command into the system. Actual execution of the
command and the authority to do so against the affected job or job output is still
enforced by JES2 or JES3 and is subject to the security profiles of the JESSPOOL class.

Default: none

Required: no

INACTIVITY
Description: The INACTIVITY statement controls whether users connected to Topaz Workbench should
time out due to inactivity. When the INACTIVITY statement is specified with a non-zero
value, users connected but inactive for the specified timeout value, are logged off from HCI,
their TP subtask purged and its resources (including any enqueues) released. When a Topaz
Workbench user is purged due to inactivity, the user will have to reconnect and sign-on
again, when they wish to resume work.

A timeout value of 0 means no inactivity scan is performed and no users are purged due
to inactivity. The INACTIVITY statement must be uncommented (remove the asterisk
from column 1) and a non-zero value specified in order to activate the inactivity scan
feature.

Default: 0

Values: 0 to 32767 representing inactivity timeout specified in minutes.

Required: no

JES3
Description: The JES3 statement is used for installations using a JESPLEX that require a command prefix
to be specified in front of JES3 commands used to cancel or purge jobs and SYSOUT datasets
from the spool. The Topaz Workbench JES Explorer View function can issue these commands
on behalf of a user in order to allow them control of their own output.

If your installation is not using JES3 or does not require a command prefix, do not code
this statement. If you require a command prefix, specify the prefix after the JES3
keyword.

Default: none

Values: 1 to 8-character command prefix appended on the front of any JES3 command sent to
the system.

Required: no
84 Enterprise Common Components Advanced Configuration Guide

CSPF
Description: The CSPF statement identifies the dataset name of the Compuware Shared Profile the
contents of this dataset are used for various Xpediter functionality. The dataset name is not
checked for validity until it is actually used and referenced by a Host Explorer user
session.

Code one CSPF statement along with the appropriate dataset name previously assigned.

Default: none

Values: 1 to 44-character valid dataset name of the Compuware Shared Profile dataset.

Required: no

HPERPLIB
Description: The HPERPLIB is only needed if you are using the Hiperstation/Eclipse plug-in. It is required
for the Hiperstation/Eclipse client to function.

Default: none

Values: The fully qualified dataset name of the Hiperstation panel library. It must be from the
same release as the Hiperstation load library specified in the STEPLIB of the HCI JCL.

Required: no

APPLID
Description: The APPLID statement identifies VTAM applids for the secondary (SLU) side of the TSO
connection for use by Xpediter/Eclipse users engaged in Xpediter/TSO debugging sessions.
One APPLID statement is required for each active debugging session. APPLIDs are freed after
use and can be reused by the same or another Xpediter/Eclipse user when they initiate
subsequent debugging sessions.

The APPLIDs specified can be defined to VTAM in the same domain as the TSO applid, or can
be in another domain if the cross domain resources (CDRSC) are properly configured. 

Up to 100 APPLIDs are supported. You should specify as many unique APPLIDs as you expect
to have concurrent active debugging sessions at one time. In most cases, 30 is more than
enough. Code one APPLID statement per line, with one applid in each statement.

Default: none

Values: The name of a VTAM applid reserved for use by Xpediter/Eclipse users during
Xpediter/TSO based debugging sessions.

Required: no
Host Communications Interface (HCI) Configuration and Administration 85

STASK
Description: The STASK statement is used to indicate the name of the JCL procedure in a system PROCLIB
in case the CSS TP must run as a started-task. You must specify STASK if:

—ENDEVOR is chosen

—File-AID Data Privacy or File-AID/Eclipse plug-ins are implemented

—this HCI will be used to support Strobe Web Services. 

The name of the procedure should be any 4-characters of your choice or that your
installation requires. The last 4-characters should be 0000. The supplied sample procedure
has the name CXSS0000. When the HCI starts a TP using this procedure, the last 4-characters
will be automatically replaced by the TP number. Thus, each TP that starts will have a unique
jobname (for example, CXSS0001, CXSS0002, etc.)

Default: none

Values: 1 to 8-character name of a started-task procedure in a system PROCLIB for use by the
CSS TP. 

This is NOT the same procedure you created for the SSAS_PROC. Do not specify
CXSSAS here.

Required: no

DSNHLQ
Description: During the internal operation of the Compuware mainframe products that are used by Topaz
Workbench, sometimes cataloged datasets are created temporarily and then deleted at the
end of the operation. If your installation requires that cataloged datasets that are created
new must begin with a fixed high level qualifier, you may specify the qualifier using the
DSNHLQ statement. 

If your installation does not require a fixed qualifier, leave the DSNHLQ statement
commented out (leave the asterisk in column 1). Most installations should leave this
statement commented out.

Default: none

Values: The high-level qualifier that should be affixed to the beginning of internally generated
dataset names. The high-level qualifier chosen must meet the rules for all dataset name
qualifiers as required by the operating system.

Required: no
86 Enterprise Common Components Advanced Configuration Guide

EXCLUDE
Description: The optional EXCLUDE statement is used to exclude one or more dataset names from being
presented to Topaz Workbench. Any dataset names specified on an EXCLUDE statement will
not be visible in the dataset tree view of Host Explorer within Topaz Workbench regardless of
the filter mask settings.

While system security profiles would normally be used to limit user access to datasets, there
are instances where it is desirable to restrict Topaz Workbench access to certain datasets (for
example SCLM project datasets), while still allowing users to access those datasets via other
non-Topaz Workbench methods such as TSO/ISPF. The EXCLUDE statement will accomplish
this by causing Topaz Workbench not to “see” the excluded datasets while the users still
retain whatever security access rights they normally have.

Specify one dataset per EXCLUDE statement. A fully qualified dataset name may be specified
or a partial dataset name using a trailing asterisk (*) as a simple wild card (must be the last
character of the name). Enter as many EXCLUDE statements as are needed to specify all of
the datasets to be excluded from Topaz Workbench. Remove the asterisk from column 1 of
an EXCLUDE statement to make it active.

Default: none

Values: The fully qualified dataset name or a partial dataset name with a terminating asterisk
character.

Required: no

JOURNAL
Description: The JOURNAL statement identifies the dataset names of the journal datasets to be used by
the Compuware Shared Services Address Space (SSAS). If the SSAS is not defined (and the
SSAS statement above is not coded), then the JOURNAL statement may be omitted. The
journal datasets contain debugging information to assist in problem determination if
difficulties should occur in using the SSAS. As journal datasets are filled, the SSAS will switch
to the next available journal dataset. If all journals are full, the SSAS will switch to the first
journal specified and repeat the process. This functionality is identical to that of the HCI
journaling feature.

Code one, two, or three JOURNAL statements, along with the dataset name of the journal
dataset to be used. The format of the JOURNAL statement is:

Default: none

Values: 1 to 44-character valid dataset name of a journal dataset created earlier. The name is
not checked for validity until it is actually used and referenced by the SSAS.

Required: no

OIDCARD
Description: The OIDCARD statement can limit Topaz Workbench sign-on access to the HCI port to
accept sign-ons only from operator identification (OID) card holders. This means that a valid
card must be used for Topaz Workbench sign-on. DEFAULT

Default: DEFAULT

Values: ONLY|DEFAULT

ONLY indicates a valid OID card can be used for a sign-on and no user ID/password
Host Communications Interface (HCI) Configuration and Administration 87

entry by Topaz Workbench is accepted. 

DEFAULT indicates that a user ID/password or a valid OID card can be accepted.

Required: no

TSOACCT
Description: Specifies that the CSS TP should not send TSO ACCT(DEFAULT).

Values: NO|BYPASS

Default: none

Required: no

SSAS_PROC
Description: The SSAS_PROC statement identifies the JCL procedure name and SSAS_NAME identifies the
address space name to be used by the Compuware Shared Services Address Space (SSAS).

The SSAS_PROC statement does not need to be coded when DDIO support using Host
Explorer, File-AID Data Privacy z/OS metadata retrieval, or Code Coverage/Eclipse is not
desired, If the SSAS_PROC statement is not coded, and a Host Explorer user attempts to issue
any requests for services, the user will receive return code 1532, indicating that the
SSAS_PROC is not defined. This parameter is paired with SSAS_NAME.

Default: none

Values: 1- to 8-character valid JCL procedure name of the startup JCL for the Compuware
Shared Services Address Space. The procedure specified should have been installed in a
system PROCLIB earlier in the previous installation steps. The name is not checked for
validity until it is actually used and referenced by a Topaz Workbench user session.

Required: no

SSAS_NAME
Description: This name is used by the console operator commands such as STOP and MODIFY in order to
control the address space. The name is not checked for validity until it is actually used and
referenced by a Topaz Workbench user session.

Values: Specifies the name of the SSAS address space.

Default: none

Required: no

SYSCMD
Description: (This statement is reserved for future use) Enable Topaz Workbench users to issue MVS system
commands.

Default: none

Values: SYSTEM|SDSF|NO

SYSTEM specifies that users can only issue system commands if their user ID has valid
security profiles in the OPERCMDS class. The OPERCMDS class contains a large number of
possible profiles, arranged by command type and often by specific operands in the
command. Consult your security software documentation for specifics about specifying
88 Enterprise Common Components Advanced Configuration Guide

command profiles for OPERCMDS. 

SDSF specifies users can issue system commands provided their user ID has read access to
the security profile ISFOPER.SYSTEM in the SDSF security class. SDSF itself uses this class and
profile to determine whether the TSO user should be permitted to issue commands within
SDSF.
NO does not allow Topaz Workbench users to issue system commands.

Required: no

SYSLOG
Description: Enable the ability of Topaz Workbench users to view the system log (SYSLOG) using JES
Explorer through SYSTEM or SDSF security rules. 

Note: Regardless of the rule choice, when a user ID is permitted to view the system log under
that rule, JES enforces validation of viewing authority based on the user ID's profile in the
JESSPOOL class.

Default: none

Values: SYSTEM specifies users can only view the system log provided their user ID has valid
security profiles in the JESSPOOL class. Consult your security software documentation for
information about specifying profiles for JESSPOOL.
SDSF specifies the security rules in the security profile IFSCMD.ODSP.SYSLOG.JESx in the
SDSF class (where x is either 2 or 3 representing JES2 or JES3, respectively) will be used -
provided the user has read access to that security profile. SDSF itself uses this class and profile
to determine whether the TSO user ID should be permitted to view the system log within
SDSF. 
NO does not allow Topaz Workbench users to view the system log.

Required: no

NOTIFY
Description: The NOTIFY statement enables the job notification feature. This feature provides for end-of-
job notifications that are generated by the NOTIFY=userid JCL parameter to be sent to the
user. The NOTIFY=userid JCL parameter is used on JOB statements.

Normally, end-of-job notifications are sent to the TSO user. This remains in effect,
regardless of whether the NOTIFY feature is enabled or disabled. Enabling the feature
allows a copy of the same end-of-job notification to be sent to the user.

Default: NO

Values: NO|YES

YES enables the job notification feature. 
NO disables the job notification feature. Note that when the NOTIFY statement is not
coded, the default value is NO and no job notifications will be sent to the user.

Required: no
Host Communications Interface (HCI) Configuration and Administration 89

NOTIFY_PURGE
Description: The NOTIFY_PURGE feature provides an automatic mechanism to purge messages that
cannot be delivered to a Workstation user after a set number of days. Messages might be
undeliverable because the user ID associated with the message never uses Topaz Workbench,
or the user ID has not used Topaz Workbench for a period longer than the purge duration
period. Purging undeliverable messages reduces overhead and keeps the storage required to
maintain the undelivered messages to a reasonable level. The NOTIFY_PURGE duration
value is in days.

Default: 0

Values: 0 to 999 representing days. Messages placed in storage for delivery will be purged after
the specified number of days elapses without any delivery for that message. A
NOTIFY_PURGE duration value of 0 causes purging to be disabled. Approximately 5900
undelivered messages will consume 1 MB of storage.

Messages are not held across system shutdown or HCI shutdown. When the system or
HCI is restarted, the message queue is emptied and collection of end-of-job
notifications starts anew.

Required: no

HIPERLIB
Description: The HPERPLIB is only needed if you are using the Hiperstation/Eclipse plug-in. It is required
for the Hiperstation/Eclipse client to function.

Values: dataset name

Default: none

Required: no

DISABLE_HLQ_WILDCARD
Description: If disabled, Topaz Workbench users are prevented from creating a filter with a wildcard in the
high-level qualifier.

Values: NO|YES

Default: NO

Required: no

TCP_ACEE
Description: Indicates whether the individual user or HCI security environment will be used for cross-
LPAR communications. If set to USER, each individual user will need to have their own
defined OMVS segment. If set to HCI, the OMVS segment of the HCI userID will be used.

This will only affect permissions for the TCP/IP connection and has no effect on dataset
permissions.

Values: USER|HCI

Default: USER

Required: no
90 Enterprise Common Components Advanced Configuration Guide

CICS_ENV block parms:

SYSNAME
Description: A unique name to identify this connection the Xpediter/Eclipse user. The name should be
descriptive so the user can identify the connection point. Typically, a CICS applid-name or
operating system ID plus other descriptive information is used.

Values: Up to 20-character unique name

Default: none

Required: yes, if the CICS_ENV block is specified

SOCK
Description: The CICS transaction ID of the sockets transaction that was defined when Xpediter/CICS was
installed and configured.

Values: 4-character CICS transaction ID

Default: XSOC

Required: yes, if the CICS_ENV block is specified

PORT
Description: The port number of the CICS region's sockets transaction that was installed with
Xpediter/CICS.

Values: Port number between 1 and 65535

Default: none

Required: yes, if the CICS_ENV block is specified

HOST
Description: CICS host name.

Values: Up to 70-character CICS host name

Default: none

Required: no

HCI_ENV block parms:

PORT
Description: Port number of the CSS TP for this HCI image.

Values: 1 to 65535

Default: none

Required: yes, if the HCI_ENV block is specified

Host Communications Interface (HCI) Configuration and Administration 91

HOST
Description: The location of the operating system image where the HCI executes.

Values: An IPv4 address in the format of nnn.nnn.nnn.nnn where nnn is a decimal number
between 0 and 255 for each of the four sub elements, or a symbolic IP name.

Default: none

Required: yes, if the HCI_ENV block is specified

SYSNAME
Description: User-specified description for the HCI connection point for a given LPAR. Typically, an LPAR
name or operating system ID plus other descriptive information is used.

Values: Up to 20-character unique name

Default: none

Required: yes, if the HCI_ENV block is specified

LPAR
Description: Identifier for the LPAR this HCI instance executes.

Values: 4 to 8-character LPAR name

Default: none

Required: yes, if the HCI_ENV block is specified

ISPW_ENV block parms:

PORT
Description: ISPW server port. This must match the value of WZCMXPRT in the ISPW start parms.

Values: Port number between 1 and 65535

Default: none

Required: yes, if the ISPW_ENV block is specified

HOST
Description: IP address or DNS of ISPW server

Values: An IPv4 address in the format of nnn.nnn.nnn.nnn where nnn is a decimal number
between 0 and 255 for each of the four sub elements, or a symbolic IP name.

Default: none

Required: yes, if the ISPW_ENV block is specified

92 Enterprise Common Components Advanced Configuration Guide

CTNAME
Description: The name of the ISPW/CT server that should be used by Topaz clients connecting through
this HCI to access ISPW life cycle datasets. This only needs to be coded if the CTLOCAL value
defined to ISPW does not have access to the life cycle datasets used by the Topaz clients
connecting through this HCI. This optional parameter is only used in multi-site
implementations of a single ISPW server.

Values: A server name between 1 and 8 characters

Default: none

Required: no

LOCAL_ENV block parms:

PORT
Description: Port number of the HCI that owns this configuration section. This should be the same port
number that is specified on the corresponding PORT_CONFIG statement.

Values: Port number between 1 and 65535

Default: none

Required: yes, if the LOCAL_ENV block is specified

HOST
Values: An IPv4 address in the format of nnn.nnn.nnn.nnn where nnn is a decimal number
between 0 and 255 for each of the four sub elements, or a symbolic IP name.

Default: none

Required: yes, if the LOCAL_ENV block is specified

ZIIP
Description: Enables the zIIP processor of the HCI that owns this configuration section. If enabled, the
CSS TP will execute selected portions of TP activity on an available zIIP processor.

Values: NO|YES

Default: No

Required: no

JRNMASK
Description: Specifies exactly 16 hexadecimal digits (0-9 and A-F) that are used to control

Values: 16-place hexadecimal specifying the number of events to be written to the HCI journal. 

For example, sixteen zeros (0000000000000000) causes no journal events to be written
Host Communications Interface (HCI) Configuration and Administration 93

to the HCI journal, where sixteen Fs (FFFFFFFFFFFFFFFFFF) causes all journal events to
be written to the HCI journal.

Default: 0000000000000002

Required: no

TPT_COMMAND block parms:

TPNAME
Description: Name of a TP where associated LINE parameters will be used as command input.

Values: Up to 64-character name of a TP

Default: none

Required: yes, if the TPT_COMMAND block is specified

LINE
Description: Commands entered on this parameter will be used as input to the HCI coded on the
associated TPNAME parameter.

Values: Line command up to 63 characters

Default: NO

Required: yes, if the TPT_COMMAND block is specified

MAXTPS
Description: Specifies the maximum number of instances of this TP program, which will be initiated
by the HCI and applies to all TP programs whether managing multiple conversations.
When this maximum is reached, subsequent conversation or connection requests are
denied. The minimum number is 1, and the maximum number is not defined.

Values: minimum is 1; maximum is not defined

Default: 999

Required: no (optional for LU6.2 and TCP/IP)

SRVRJOB
Description: Specifies a one- to five-character job name prefix that the HCI uses for all TP

Values: 1 to 5 characters

Default: HCITP

Required: no
94 Enterprise Common Components Advanced Configuration Guide

SYSLOG_IOF block parms:

CLASS
Description: When coded, IOF uses this class and profile to determine whether a TSO user has permission
to view the system log through IOF.

Values: A IOF class name with a maximum of 70 characters

Default: none

Required: yes, if the SYSLOG_IOF block is specified

RULE
Description: When coded, IOF uses this profile and class to determine whether a TSO user has permission
to view the system log through IOF.

The SYSLOG_IOF block is only valid when the SYSLOG parameter is NO

Values: A IOF profile name with a maximum of 70 characters

Default: none

Required: yes, if the SYSLOG_IOF block is specified

SYSCMD_IOF block parms:

CLASS
Description: When coded, IOF uses this class and profile to determine whether a TSO user has permission
to issue commands through IOF.

Values: A IOF class name with a maximum of 70 characters

Default: none

Required: yes, if the SYSCMD_IOF block is specified

RULE
Description: When coded, IOF uses this profile and class to determine whether a TSO user has permission
to issue commands through IOF.

Note: The SYSCMD_IOF block is only valid when the SYSCMD parameter is NO

Values: A IOF profile name with a maximum of 70 characters

Default: No

Required: yes, if the SYSCMD_IOF block is specified

Host Communications Interface (HCI) Configuration and Administration 95

HCI_CONNECTION block parms:

PORT
Description: Specifies a port number in which the HCI listens for incoming connection requests. This
value corresponds to a given PORT_CONFIG entry located under the CSS TP PORT
CUSTOMIZATION section of the HCI parameter file. Check with your network administrator
for available port numbers.

Values: Port number between 1 and 65535

Default: none

Required: yes

DEVENT_GCS_PORT
The DevEnterprise Job Manager port.

Values: Port number between 1 and 65535

Default: none

Required: no

DEVENT_TCP_PORT
Description: The DevEnterprise TCP/IP port.

Values: Port number between 1 and 65535

Default: none

Required: no

TCPNAME
Description: The name of the desired TCP/IP stack.

Values: TCP/IP stack name up to 8 characters.

Default: Default TCP/IP stack

Required: no

IPV6
Description: Specifies if IPv6 is being used for this HCI port.

Values: NO|YES

Default: NO

Required: no
96 Enterprise Common Components Advanced Configuration Guide

DVIPA
Description: Specifies the address (IPv4 or IPv6) from which connections are accepted if TCP/IP
VIPARANGE processing has been defined in the TCP/IP configuration datasets. This address
overrides the IP address of the host on which the HCI is running, thus allowing you to move
the HCI from one LPAR to another while retaining the IP address known to the network
clients.

Values: An IPv4 address in the format of nnn.nnn.nnn.nnn where nnn is a decimal number
between 0 and 255 for each of the four sub elements, or an IPv6 address in the format
of hhhh:hhhh:hhhh:hhhh where hhhh is a hexadecimal number (0-9, A-F) for each one
of the one to eight sub-elements.

Default: none

Required: no

DVIPN
Description: Specifies the 1- to 64-character name, known to your HOSTS file or to your DNS server,
from which connections are accepted for this HCICNPCB element If TCP/IP
VIPARANGE processing has been defined in the TCP/IP configuration datasets. This
name overrides the IP name of the host on which the HCI is running thus allowing you
to move the HCI from one LPAR to another retaining the IP name known to the
network clients.

Values: 1- to 64-character name

Default: none

Required: no

RMT_URL
Description: Remote URL is used only by the zero administration service. When specified, the value is
sent to CES at HCI startup and allows for specification of an external URL that may be used
to connect to the HCI

Default: none

Required: no

LOCAL_URL
Description: The local URL is specified when it is desired to use a different URL/IP address than the
default of the TCP/IP region

Default: none

Required: no

TPNAME
Description: Name of a TP in which this connection should be associated

Values: Name of a TP up to 64 characters

Default: none

Required: no
Host Communications Interface (HCI) Configuration and Administration 97

TSO_ENV block parms:

SYSNAME
Description: A unique name to identify this connection to the Xpediter/Eclipse user. The name should be
descriptive so the user can identify the connection point. Typically, an LPAR name or
operating system ID plus other descriptive information is used.

Values: Unique name up to 20 characters.

Default: none

Required: yes, if the TSO_ENV block is specified

APPLID
Description: VTAM application ID (APPL) that is used for the primary TCAS address space on your system.
This is the same APPL used by typical users logging on to TSO via a 3720 display. Typically,
only one TSO statement is coded, but if your VTAM network is set up with the proper cross-
domain resource definitions (CDRSC), you can specify TSO applids from other systems as
well.

Values: VTAM application ID up to 8 characters

Default: none

Required: yes, if the TSO_ENV block is specified

LOGMODE
Description: Specify the log mode entry name of line-mode bind parameters that will be used by
Xpediter/Eclipse during Xpediter/TSO debugging sessions. This log mode entry is usually
provided by IBM as a part of the default VTAM log mode table, ISTINCLM (source:
SYS1.SAMPLIB member ISTINCLM). Normally, this table is already assembled and linked
into SYS1.VTAMLIB and should be available. The default log mode entry to specify for this
parameter is BATCH. Within the default IBM log mode table, the name of the entry is called
IBM3770, but the log mode name is BATCH as specified by the LOGMODE= parameter
associated with that entry.

Values: Log mode entry name up to 8 characters.

Default: none

Required: yes, if the TSO_ENV block is specified

LPAR
Description: The name of the LPAR that this TSO will be executing. The LPAR name should match the
LPAR name in a HCI_ENV block.

Values: 4- to 8-character LPAR name

Default: none

Required: yes, if the TSO_ENV block is specified

98 Enterprise Common Components Advanced Configuration Guide

Additional Notes for Strobe and DevEnterprise

For Strobe Web Service Users only:
The only required parameters for Strobe are LOCAL_*, STASK, and HCI_*.

For DevEnterprise Users only:

The following parameters are required to run DevEnterprise. These default parameters must be
included in the HCI PARMLIB member’s HCI_CONNECTION block parms: section:

– DEVENT_GCS_PORT

– DEVENT_TCP_PORT

– TCPNAME

for Sysplex Support

SYSPLEX

Four-character subsystem name, which must be different than the HCI SYSID specified. This name
must be unique among all MVS images in the SYSPLEX and must not be specified in the IEFSSNxx
member of SYS1.PARMLIB.

ROUTCMD

YES specifies that the HCI routes z/OS START commands to the active member of the SYSPLEX that
currently has the least number of routes to it. The following example illustrates what changes would
be required to enable XPPJOBM a SYSPLEX routed task.

TPT_NAME

Specifies the TPT name override.

PREPROC

This value specifies the name of the procedure in which the HCI should invoke on each MCS image
in the SYSPLEX to prepare the MVS for HCI communication.

Sample PREPROC procedure that will activate SYSPLEX support in the HCI. No changes are required
below aside from specifying the SLCXAUTH dataset:

//IEFPROC PROC HCISYSP=DUMY,HCITYPE=

//HCIPREP EXEC PGM=HCIYPREP,PARM='&HCISYSP,&HCITYPE'

//STEPLIB DD DISP=SHR,DSN=CPWR.SLCXAUTH
Host Communications Interface (HCI) Configuration and Administration 99

Figure 19. SLCXCNTL member HCIPROCS Startup JCL example

//*HCI JOB 0,HCI 
//* *************************************************************** *// 
//* *// 
//* THIS JCL PERFORMS THE FOLLOWING INSTALLATION PROCESSING: *// 
//* STEP(S) FUNCTION *// 
//* -------- --------------------------------------------- *// 
//* HCPROC CREATE CATALOGED PROCEDURES TO SYSTEM *// 
//* PROCEDURE LIBRARY. *// 
//* *// 
//* NAME(S) FUNCTION *// 
//* -------- --------------------------------------------- *// 
//* HCIPROC HOST COMMUNICATIONS INTERFACE *// 
//* CXSSAS SHARED SERVICES STARTUP PROCEDURE *// 
//* CXSS0000 SHARED SERVICES TP STARTED TASK *// 
//* *// 
//* DATASET(S) DESCRIPTION *// 
//* -------------- --------------------------------------- *// 
//* CPWR.SLCXAUTH ECC AUTHORIZED LIBRARY *// 
//* CPWR.SLCXLOAD ECC LOAD LIBRARY *// 
//* SYS1.PROCLIB PROCEDURES DESTINATION LIBRARY *// 
//* *// 
//* *************************************************************** *// 
//HCPROC EXEC PGM=IEBUPDTE,PARM=NEW 
//SYSPRINT DD SYSOUT=* 
//SYSUT2 DD DISP=SHR,DSN=SYS1.PROCLIB 
//SYSIN DD DATA,DLM=ZZ 
./ ADD NAME=HCIPROC 
//HCI PROC 
//* 
//* HOST COMMUNICATIONS INTERFACE PROCEDURE 
//* 
//STEP1 EXEC PGM=HCIMMAIN,DYNAMNBR=125, 
// REGION=64M 
//STEPLIB DD DISP=SHR,DSN=CPWR.SLCXAUTH 
//HCIJCL DD SYSOUT=(A,INTRDR) 
//HCIPRINT DD SYSOUT=*,FREE=CLOSE,SPIN=UNALLOC 
//SYSPRINT DD SYSOUT=* 
//HCIERR DD SYSOUT=* 
//ABNLIGNR DD DUMMY 
//IDIOFF DD DUMMY 
./ ADD NAME=CXSSAS 
//CXSSAS PROC 
//* 
//* SSAS STARUP PROCEDURE 
//* 
//* - THE HCI AUTOMATICALLY STARTS THIS PROCEDURE AS NEEDED 
//* AND SHOULD NOT BE STARTED MANUALLY. 
//* - FOR CODE COVERAGE SUPPORT UNCOMMENT THE CC LIB DD 
//* 
//IEFPROC EXEC PGM=CXASINIT, 
// PARM=('&TPNAME'), ** DO NOT CHANGE THIS PARM VALUE ** 
// REGION=0M 
//STEPLIB DD DISP=SHR,DSN=CPWR.SLCXLOAD 
//* DD DISP=SHR,DSN=CPWR.SLXVLOAD <== CC LIB 
./ ADD NAME=CXSS0000 
//CXSS0000 PROC PROG=IEFBR14 
//* 
//* CSS TP STARTED TASK 
//* 
//* - ALL STEPLIB LIBRARIES MUST BE APF-AUTHORIZED 
//* - FOR FILE-AID SUPPORT UNCOMMENT THE FA CUST/DIST LIB DDS 
//* - FOR STROBE SUPPORT UNCOMMENT THE SB LIB DDS AND 
//* OPTIONALLY THE DB2 SDSNLOAD LIBRARY 
//* 
//IEFPROC EXEC PGM=&PROG, 
// REGION=0M, 
// PARM=('&TPNAME') 
//STEPLIB DD DISP=SHR,DSN=CPWR.SLCXAUTH 
//* DD DISP=SHR,DSN=CPWR.CXVJLOAD <== FA CUST LIB 
//* DD DISP=SHR,DSN=CPWR.SXVJAUTH <== FA DIST LIB 
//* DD DISP=SHR,DSN=CPWR.SSTRAUTH <== SB LIB 
//* DD DISP=SHR,DSN=DSNA10.SDNSLOAD <== DB2 FOR SB 
./ ENDUP 
ZZ 
100 Enterprise Common Components Advanced Configuration Guide

HCI Operator Commands

DISPLAY

Display status information about an HCI region.

Operands Description

ALL Displays all HCI status fields.

JOURNAL Displays information about the journal.

STOR Displays information about current storage utilization.

Displays information about control block utilization. The CURRENT utilization,

CB HIGHEST utilization, and MAXIMUM allowed as configured in the HCICNFIG file
are displayed.

Displays Topaz Workbench tasks with an ENQ on the dataset specified. For
ENQ example,
/F jobname,DSP ENQ=dataset.name

SHUTDOWN

Terminate the HCI.

Operands Description

For an immediate shutdown. The HCI will not

wait for any user tasks to end prior to
IMMED termination. Consequently, the HCI will end
with a SA03 abend if there are any active users
at shutdown time.

NORMAL For normal shutdown

ABEND For a forced abend situation

Additional Commands
Various commands that may be useful in controlling an HCI.

Commands Description

CLOSE Turn journaling off. Close and deallocate the current journal dataset.

OPEN Allocate and open the next journal dataset.

JMASK [ON/OFF] Turn on/off full journaling. TP activity is the default journal mask.

SWAP Close and deallocate current journal dataset, open the next for journaling.

Operator Commands to Control the SSAS

The following commands control the start and shutdown of SSAS. There may be multiple ports, each
with a TP control task and SSAS. These port numbers are specified on the PORT_CONFIG parameter in
the HCIxxxx parameter member. Be sure to specify the port number whose associated SSAS you wish
to start or shutdown.
Host Communications Interface (HCI) Configuration and Administration 101

Shutdown the SSAS

F hci,SSAS SHUTDOWN ppppp

where,

hci is the job name of the HCI address space.

ppppp is the port number associated with the TP control task that owns the SSAS.

The minimum abbreviation for the SHUTDOWN command is SHUT.

Start the SSAS

F hci,SSAS START PPPPP

where,

hci is the job name of the HCI address space.

ppppp is the port number associated with the TP control task that owns the SSAS.

Operator Commands for ENQ Management

The following commands help manage ENQs within the HCI address space. If an HCI started task is
indicated as holding an ENQ on a dataset, the PURGE command will purge any Topaz Workbench
tasks with an ENQ on the specified dataset. Its syntax is:

F HCIjobname,PURGE ENQ=dataset.name

If this command fails to clear the ENQ, you can also issue the DEALLOC operator command to
clear any SYSDSN ENQs on the dataset. This command’s syntax is:

F HCIjobname,DEALLOC DSN=dataset.name

• If the ENQ remains after issuing these two commands, you will have to recycle your HCI started task
in order to clear it.

• If managing ENQs from the HCI is a continual issue at your site, Compuware recommends using
the INACTIVITY parameter to prevent users from holding datasets that are not in use.
102 Enterprise Common Components Advanced Configuration Guide

Setting Up an Additional HCI Instance

The following procedure describes setting up an additional instance of HCI on an LPAR that already
has a functioning HCI. Adding another HCI instance is often required for testing purposes.

1. You will need to designate and open a new port for your additional instance of HCI.
2. In your CMSC PARMLIB, make a copy of your current HCI parameter member (default is HCI00).
The new member name must begin with “HCI” and appended with 1- to 4-characters of your
choice (HCInnnn).

As an example, these instructions will append “TST1”, and thus use HCITST1 as the new HCI
parameter member.
a. Update the following parameters in HCITST1 parameter member, remembering to specify the
new PORT number (established in step 1.) for the HCI_CONNECTIONS, HCI_ENV, and
LOCAL_ENV block parms sections.

SYSID1

JOURNAL1, JOURNAL2, and JOURNAL3 1

HCI_CONNECTIONS :: PORT

LOCAL_ENV :: PORT

HCI_ENV :: PORT

3. Refresh your CMSC PARMLIB by issuing the following operator command:

F cmscname,PARMLIB REFRESH HCITST1

4. Make a copy of your current HCI PROC

a. Modify the copied HCI PROC to have a different STC name. 
For example: //HCITEST PROC
b. Add the following DD statement, 
For example: // PMHCTST1 DD DUMMY

where the suffix appended to the newly created HCI

parameter member from step 2 (TST1 in our example) is
appended to PMHC.

5. Run SLCXCNTL(HCIJOURN).
a. Specify your new journal files in step ALLOCJH, as specified in your new PARMLIB member
b. Delete step ALLOCJC before submitting.
6. Start your new HCI PROC
7. In Topaz Workbench, define a new host connection using the same host name or IP address as
before, but instead using the new port number specified in step 1.

1. It is recommended that you use the same last four characters of your procname
Host Communications Interface (HCI) Configuration and Administration 103

HCIPlex
HCIPlex enables adminstrators to setup an HCI with an associated port number, then have a large
number of users be able to connect to them, using that same port number, without needing to
consider task or memory constraints within the HCI.

Dynamic Connection Capacity

The total number of connections supported by any single HCI running in the HCIPlex is 400. Thus,
the number of HCIs running on the HCIPlex determines its connection capacity. For example, if five
HCIs are running in a HCIPlex, then the connection capacity is 5x400, or 2000 connections. When
the total number of actual connections reaches 95% of the HCIPlex’s connection capacity, a new HCI
is started, thereby increasing the connection capacity of the HCIPlex by 400. As the number of actual
connections continues to increase, new HCIs will be started such that the connection capacity of the
HCIPlex is never actually reached so long as the total number of HCIs running in the HCIPlex has not
reach the maximum of 39.

When a new HCI is started, a message displays stating a new HCI address space has been started. The
following is an example of that message:

HCIHC0301I NEW HCIPLEX ADDRESS SPACE STARTED. SUBSYSTEM NAME HCI#.

Dynamically Generated Subsystem Names

The 4-character HCI subsystem name, specified with the SYSID HCI parameter in the HCIxxxx
parmlib member, is used to dynamically generate a subsystem name for each HCI running in the
HCIPlex. The dynamically generated subsystem name uses the first 3 characters of the SYSID
parameter appended with an additional character at HCI startup. This additional character gets
appended for each HCI in the following order: $, #, @, A-Z, 0-9. Therefore, the maximum number of
HCI address spaces is 39. When new HCIs are started internally by the HCIPlex, the subsystem name,
as dynamically generated, is used as the identifier for the job. For example, if SYSID=HCI1 is
specified in the HCIxxxx parmlib member, the first HCI in the HCIPlex will have a subsystem name of
HCI$. The second HCI will have a subsystem name of HCI#, and will be started internally with the
identifier of HCI#. It is recommended that the first HCI be started (using the MVS START operator
command) with an identifier of the first 3-characters of the subsystem name appended with a $. For
example, START HCI.HCI$. See Controlling the HCIPlex With Operator Commands for information
on managing the HCIPlex.

Configuring Parameters for HCIPlex

Several parameters have special considerations when involving an HCIPlex.

The HCIPLEX_NAME parameter is used to specify the name of the HCIPlex. When you specify a value
for this parameter, the HCIPlex feature is enabled.

The HCI_PROCNAME parameter is only needed when the HCI job name is not the same as the name
of the member containing the PROC

The EMCS_CONSOLE_NAME parameter is not used when an HCIPlex is enabled. When the HCIPlex is
enabled, the EMCS_CONSOLE_NAME parameter is ignored and the EMCS console name is
dynamically generated.

The dataset name specified for the JOURNALn parameter must have HPLEXSUB as one of the nodes in the
dataset name. HPLEXSUB will be replaced with the actual subsystem name for the HCI job. Because this
subsystem name is generated dynamically at HCI start-up, a system symbol cannot be used to resolve the
name when the HCIxxxx parameter member is validated by the CMSC. 

For example: HCIPlex job HCDEV0 with the subsystem name HCG#:

104 Enterprise Common Components Advanced Configuration Guide

HC.DEV.CW09.HCID0.HPLEXSUB.JOURNAL1 will resolve to

HC.DEV.CW09.HCID0.HCG#.JOURNAL1 during initialization.

Controlling the HCIPlex With Operator Commands

HCI subsystem names used in an HCIPlex consist of the first three characters specified in the SYSID
parameter (found in the HCI PARMLIB member) and a suffix that is appended by the HCI. The first
HCI started in the HCIPlex is given a suffix of $.

For example, if SYSID=HCIP is specified in the HCI PARMLIB member, the first HCI started in the
HCIPlex will have a subsystem name of HCI$. The following discussion assumes that the
OPCMD=MODIFY parameter1 has been specified in the HCI PARMLIB member.

For the purposes of the following examples, the SHUTDOWN command will be used, however, the same
MODIFY command syntax applies to all HCI operator commands.

When the HCIPlex determines that an additional HCI address space is needed, a new HCI is started
with an identifier that is the same as the subsystem name of the new HCI address space. For example,
if the name of the HCI procedure is HCIPROD and the SYSID=HCIP, then a second HCI would started
with an identifier of HCI#, and the new subsystem name will be HCI#. Continuing with this
example, to direct an MODIFY command to this HCI instance, the following MODIFY command
would be used

MODIFY HCIPROD.HCI#,SHUTDOWN IMMED

Compuware recommends that the first HCI in the HCIPlex, started with the START command, be
started with the identifier of the 3-characters of the SYSID and the suffix of $. For example, HCI$.
This will allow the first HCI in the HCIPlex to be controlled using the HCI procedure name and the
identifier of HCI$. For example

MODIFY HCIPROD.HCI$,SHUTDOWN IMMED

The HCI can also be controlled using the identifier only

MODIFY HCI$,SHUTDOWN IMMED

If the first HCI in the HCIPlex is not started with the identifier, the system will use the job name as
the identifier. This HCI will have to be controlled using the job name only. For example,

MODIFY HCIPROD,SHUTDOWN IMMED

or

MODIFY HCIPROD.HCIPROD,SHUTDOWN IMMED

To direct a MODIFY command to all HCIs in the HCIplex, the following command would be used

MODIFY HCIPROD.*,SHUTDOWN IMMED

Below are some examples showing START commands and the various options for controlling the HCIs
in an HCIPlex. These examples assume that the procedure name is HCIPROD, and that SYSID=HCIP
in the HCI PARMLIB member. These examples use the abbreviation, F, for the MODIFY command.

Example 1

START HCIPROD (no identifier)

1. If OPCMD=WTOR had instead been specified, then the individual HCIs in the HCIPlex would be controlled by replying to
the appropriate outstanding HC9999A message (using the reply number) for the HCI subsystem name shown in the
message.
Host Communications Interface (HCI) Configuration and Administration 105

When the number of users in the first HCI reaches 95% of capacity, a second HCI in the HCIPlex will
be started internally, by the primary (first) HCI, as HCIPROD.HCI#.

F HCIPROD,SHUTDOWN IMMED — because the first HCI was started without an identifier, this will bring
down only the first HCI in the HCIPlex.

F HCI#,SHUTDOWN IMMED — shuts down the second HCI in the HCIPlex. This could also be specified as
F HCIPROD.HCI#,SHUTDOWN IMMED

F HCIPROD.*,SHUTDOWN IMMED — will shut down all HCIs in the HCIPlex.

Example 2:

START HCIPROD.HCI$

Compuware recommends that you start the first HCI using the first 3 characters of the SYSID parameter
plus a $ suffix as the identifier.

When the number of users in the first HCI reaches 95% of capacity, a second HCI in the HCIPlex will
be started internally, by the primary (first) HCI, as HCIPROD.HCI#.

F HCI$,SHUTDOWN IMMED — Because the first HCI was started with an identifier of HCI$, only the first
HCI in the HCIPlex will be shut down. This could also be specified as F HCIPROD.HCI$,SHUTDOWN
IMMED

F HCI#,SHUTDOWN IMMED — Shuts down only the second HCI in the HCIPlex. This could also be
specified as F HCIPROD.HCI#,SHUTDOWN IMMED

F HCIPROD.*,SHUTDOWN IMMED — This will shut down all HCIs in the HCIPlex.

Using ENF Listener

To reduce HCI/Topaz system utilization, an ENF Listener for Event 78 or Event 70 has been
implemented to receive ENF events when jobs end and to push NOTIFY messages to Topaz users.
This process reduces CPU utilization in the HCI address space.

The EMCS methodology processes all CONSOLE messages from all Sysplex members, if allowed,
looking for SEND messages generated by a NOTIFY= on the JOB card. This can be a CPU intensive
process depending on the size of the Sysplex. Additionally, CPU processing multiplies when an HCI
has more than one port defined for Topaz.

ENF Listener will then push the notification process to Topaz users when the job is submitted from
Topaz. A utility is supplied to provide notification from other environments.

ENF Event 78 is the preferred event, because it runs only at job termination. This exit is the ENF
event implemented by the HCI for JES2 and JES3 in z/OS V2.2 and higher. ENF Event 70 is
implemented for JES3 in z/OS V2.1 and prior.

ENF does not provide the exact same functionality as EMCS message scanning, with noted differences
for each ENF Event. The EMCS method relies on a NOTIFY= parameter on the JOB card, whereas the
ENF process functions regardless of the presence of a NOTIFY= parameter.

ENF Event 78 provides a notification process based on an available JES symbol, SYS_JOB_NOTIFY, and
the owner of the job. When a job is submitted, the presence of this JES symbol indicates the ENF
Event 78 listener will be driven and the NOTIFY message will be sent to the Topaz user matching the
owner of the job. Jobs submitted by Topaz will have the JES symbol set when the HCI TOPAZ task is
created. All jobs submitted through Topaz, regardless of the presence of a NOTIFY= parameter, will
drive the NOTIFY message to the Topaz user. By default, TSO/ISPF submitted jobs will not drive the
106 Enterprise Common Components Advanced Configuration Guide

NOTIFY message unless the JES symbol is created. The following creates an external JES symbol by
executing CXTRJSYM with a parameter of CREATE.

CALL 'CPWR.SLCXAUTH(CXTRJSYM)' 'CREATE'

This creates the JES symbol for the TSO/ISPF user, all jobs submitted after executing CXTRJSYM will
drive NOTIFY messages to the Topaz owner. If a user creates multiple Topaz connections to the HCI,
upon a Topaz-submitted job termination, a NOTIFY will be created for all Topaz connections that
match the owner of the job ending.

ENF Event 70 provides a notification process based on a match of JOBNAME and JOBID of a
completed job to a Topaz user that submitted the job. When a job is submitted, the JOBNAME and
JOBID are used to track the Topaz user that submitted the job. When a job ends, the ENF event will
search for a match of the JOBNAME and JOBID and drive a NOTIFY message to the Topaz user that
submitted the job. All jobs submitted through Topaz, regardless of the presence of a NOTIFY=
parameter, will drive the NOTIFY message to the Topaz user that submitted the job. If a user creates
multiple Topaz connections to the HCI, upon a Topaz-submitted job termination, a NOTIFY will be
created only for the Topaz user that submitted the job. For ENF Event 70, the Topaz user will not be
notified at job termination for jobs submitted outside of Topaz.
 107

Compuware Shared Services Configuration and

Administration 5

CSS Overview
Compuware Shared Services (CSS) is an integral component of many Compuware products spanning
the Fault Diagnosis, Interactive Analysis and Debugging, File and Data Management, and Application
Performance Measurement products. CSS provides storage, retrieval, and maintenance for Abend-AID
reports, source listings, and transaction dump information in datasets called DDIO files. Shared
directories and their attached databases are also types of DDIO files being utilized for more efficiency
in maintaining information and activity within these files. CSS also provides language processing
support for COBOL, PL/I, Assembler, and C.

The following products currently use CSS:

• Abend-AID
• Abend-AID for CICS
• Topaz Workbench
• Strobe
• Xpediter/CICS
• Xpediter/Code Coverage
• Xpediter/TSO and Xpediter/IMS

System Environment
For System Requirement information, see the Enterprise Common Components Release Notes available
from Compuware Support Center.

CSS Components
CSS consists of the following components:

• Compuware common files and utilities

– DDIO files: Source Listing Files, Report Files, Shared Directories and Associated Report,
Transaction, and Source Listing Databases
– Batch file utilities: CWDDSUTL, CWFXSDUT, CWAASDUT, CWDDLPUT, and CWDDALLU

• Compuware Language Processors (COBOL, Assembler, PL/I, and C)

• Security Exit Program

• Topaz Workbench support

Common Files and Utilities

CSS components include common files and utilities that provide storage, retrieval, and maintenance
functions.

DDIO Files
A generic term used to describe the proprietary file access method that stores Abend-AID reports,
transaction dump information, and source listings for several Compuware products. DDIO files can
108 Enterprise Common Components Advanced Configuration Guide

be allocated as either VSAM or sequential datasets. Different products may require different types of
DDIO files.

CSS Utilities and Batch File Utilities

CSS Utilities walks you step-by-step through CSS language processor functions and DDIO file
manipulation using easy-to-use panels.

The batch file utilities (CWDDSUTL, CWAASDUT, CWDDLPUT, CWFXSDUT and CWDDALLU)
provide the same functions as CSS Utilities in a batch environment.

For information on the available online utility functions refer to the “CSS Utilities” chapter in the
Compuware Shared Services User/Reference Guide. For information on the available batch utility commands
and parameters for CWDDALLU or CWDDSUTL, CWAASDUT, CWFXSDUT and CWDDLPUT refer to
the “Batch File Utility CWDDALLU” chapter in the Compuware Shared Services User/Reference Guide.

CSS Language Processors (LP)

The language processors capture information about a compiler listing and store it in a source listing
DDIO file. The majority of this information is gathered from the compiler listing, but optionally,
SYSIN and SYSLIB are also examined. The source listing DDIO file may be in standard DDIO, shared
directory, or database format.

A language processor can be run using two methods:

• preprocessor
• post-processor

You may use the preprocessor or post-processor (whichever is best for your site as needed.) For
information about the pre- and post-processors, refer to the appropriate language processor chapter
in the Compuware Shared Services User/Reference Guide. See the applicable language processor chapter for
when to use the pre- or post-processor.

Language Processor Types

CSS provides language processing support for the following languages:

• COBOL
• PL/I
• Assembler
• C

The COBOL language processor reads the compiler listing produced by the COBOL compiler and
writes either a compiler listing or an enhanced listing to the DDIO file. The enhanced listing merges
the information normally found in the data division map (DMAP) and the condensed listing (CLIST)
or procedure map (PMAP) into the source statement lines. The COBOL compiler options in effect are
sorted alphabetically and appear at the beginning of the enhanced listing. The enhanced listing
provides you with a condensed hardcopy of the compiler information.

The COBOL and PL/I listings may be used to provide source support using any of the following
products:

• Abend-AID
• Abend-AID for CICS
• Strobe and iStrobe
• Xpediter/CICS
• Xpediter/TSO
• Xpediter/Eclipse

The Assembler listings may be used to provide source support using any of the following products:

• Abend-AID
• Strobe and iStrobe
Compuware Shared Services Configuration and Administration 109

• Xpediter/CICS
• Xpediter/TSO
• Xpediter/Eclipse

The C language processor reads the compiler listing produced by the C compiler and writes the
compiler listing to the DDIO file and SYSCPRT. The source listing in DDIO can then be used to
provide source support when using:

• Xpediter/TSO
• Xpediter/CICS
• Strobe and iStrobe

Security Exit Program

CSS also includes the Compuware Security Exit Program. This is an optional user-written exit for your
Compuware products. It can be used in conjunction with your existing security package to secure
sensitive data used by the following Compuware products:

• Abend-AID
• Abend-AID for CICS
• Xpediter/CICS
• Xpediter/TSO and Xpediter/IMS
• Xpediter/Code Coverage
• Strobe

The Compuware Security Exit enables you to control access to DDIO file members or restrict access to
various commands through a user-written exit program. For the Abend-AID for CICS product, you
can restrict access to some of the CWFXSDUT and CWDDALLU functions for transaction database
and source listing files. For transaction databases, you can use the Security Exit Program to restrict
access to individual dumps within a transaction database.

If you install a Security Exit program, it will be called by all Compuware products installed at your
site. For more information on the Security Exit Program, see the “CSS Security Exit” chapter in the
Compuware Shared Services User/Reference Guide.

Executing CSS
CSS is primarily executed at the following times:

• Abend-AID and Abend-AID for CICS

– at compile time (when source support is used)

– at time of abend or application program failure
– at view time when using the Abend-AID Viewer
– at installation and maintenance time when formatting a DDIO file.
– when a compile listing that has been stored elsewhere is needed for Abend-AID or Abend-AID
for CICS viewing with source support.
– invoking the on-the-fly language processing support

• Xpediter/TSO and Xpediter/CICS

– at compile time (when source support is used)

– at execution time for interactive debugging
– at installation and maintenance time when formatting a DDIO file.

• Strobe

– when indexing is used to analyze measurement data

– to support Web services and SQLAF processing through CSS TP of HCI

• Compuware Workbench/Topaz Workbench

110 Enterprise Common Components Advanced Configuration Guide

– to support Web Services needs through the CSS TP and other HCI related facilities (SSAS and
STASK)

CSS Installation Considerations

This section describes considerations for installing Compuware Shared Services which is part of the
Enterprise Common Components (ECC) libraries.

CICS Load Library Definition

The ECC load library (SLCXLOAD) must be included with Compuware product libraries in the CICS
startup JCL or RDO definitions for the following product:

• Xpediter/CICS (all supported releases)

TSO Logon PROCs

If the ECC load library (SLCXLOAD) is not in the link list and dynamic library allocation is not used,
the ECC load library must be placed before all Compuware product load libraries in the STEPLIB or
ISPLLIB concatenations in the TSO login PROC. The ECC message and panel libraries must be placed
before all Compuware product message and panel libraries in the ISPMLIB and ISPPLIB
concatenations in the TSO login PROC.

Sharing CSS DDIO Files With Multiple CPUs

If you are sharing CSS DDIO files among multiple CPUs, the following qnames must be changed from
LOCAL to GLOBAL enqueues.

• ABENDAID
• ABENDDAM
• ABENDSMF
• CWCATALG

These qnames are needed for all products. Please refer to the individual Compuware product documents
with which CSS was distributed for other product requirements.

For IBM’s GRS (Global Resource Serialization), these qnames must be added to the inclusion RNL.
This RNL is defined in the GRSRNLxx member of SYS1.PARMLIB for MVS/XA and later. For pre-
MVS/XA systems, these qnames are maintained in the ISGSIRNL entry point of ISGGRNLO. Please
consult the IBM product documentation for further details.

The ECC sample library (SLCXCNTL) contains an example of how qnames should be coded in the
GRSRNLxx member of SYS1.PARMLIB. See “CSS Sample Library Members” for more information.

For resource serialization packages other than GRS (for example MIM), consult the product
documentation for changing LOCAL to GLOBAL enqueues.

CSS Language Processor (LP)

The language processor captures information about a compiler listing and stores it in a source listing
DDIO file. The majority of this information is gathered from the compiler listing, but optionally,
SYSIN and SYSLIB are also examined. The source listing DDIO file may be in standard DDIO, shared
directory, or database format.

The language processor can be run using two methods:

Compuware Shared Services Configuration and Administration 111

• pre-processor
• post-processor

You may use the pre-processor or post-processor (whichever is best for your site as needed). This
section discusses the benefits of the preprocessor and the post-processor and describes when to use
them.

Pre-processor
Some information about a program module is not always available from the compiler listing. The pre-
processor, in addition to gathering information from the compiler listing, gathers information from
SYSIN and SYSLIB. The preprocessor provides additional functionality for Xpediter/CICS and
Xpediter/TSO, and is required for PL/I programs that use the %NOPRINT statement.

When setting up the language processors, Compuware recommends that you use the pre-processor
instead of the post-processor. The post-processor should only be used in situations where compiled
source listings have been stored.

Pre-processor Steps
1. Determines the proper compiler options required to process the listing file.
2. Automatically invokes the compiler or assembler to compile or assemble your source program.
3. Writes the listing to the DDIO file. An enhanced listing for COBOL programs can be produced, if
desired. PL/I and Assembler listings are written to SYSPRINT. C listings are written to SYSCPRT.

Pre-processor Benefits
• Better handling of compiler errors. By using the preprocessor, you can avoid the potential
problem of processing a listing with compiler errors. The preprocessor, in conjunction with the
CONDDDIO parameter, internally checks the return code from the compiler and doesn’t write a
DDIO listing that contains errors. For example, if you set the CONDDDIO parameter to 8, the
preprocessor will write the compiler listing to the DDIO file unless the compiler return code
exceeds 8. The preprocessor can process the compiler errors more effectively than the post-
processor. Compuware recommends that you use the preprocessor rather than the post-processor.

• Capturing suppressed source code. When any of the following parameters are used, sections of
source code can be suppressed from the compiler listing:

For COBOL COPY SUPPRESS

For PL/I %NOPRINT
For Assembler PRINT OFF or PRINT NOGEN
For C NOSHOWINC and NOEXPMAC

The preprocessor captures this information from SYSIN and SYSLIB, or by forcing on more
revealing compiler options, then altering the listing to emulate the options you requested.

• Automated compiler options. The post-processor requires that certain compiler options be
specified in order to process all needed sections of the compiler listing. The preprocessor can
automatically pass the required options to the compiler.

• Simplified JCL. While the post-processor requires that the user add a step after the compile step,
the preprocessor requires only that minor modifications be made to your existing compile step.
112 Enterprise Common Components Advanced Configuration Guide

Files Dynamically Allocated

The following files are dynamically allocated by the Compuware preprocessor. The attributes can be
overridden by specifying a DD in the JCL.

Table 3. Files Dynamically Allocated by the Preprocessor

DDname Attributes
CWPWRKn (0-6) BLKSIZE=19000 SPACE(TRK,(100,80)) UNIT=SYSDA
SORTWK01 BLKSIZE=19000 SPACE(TRK,(100,80)) UNIT=SYSDA
TEMPLIN BLKSIZE=3200 SPACE(TRK,(200,100)) UNIT=SYSDA
CWPERRM SYSOUT=*
SYSPRINT SYSOUT=*
SYSOUT SYSOUT=*
CWPPRTI (PL/I) BLKSIZE=19000 SPACE(TRK,(100,200)) UNIT=SYSDA
CWPPRTI (all other languages) BLKSIZE=16093 SPACE(TRK,(100,200)) UNIT=SYSDA DISP=MOD
CWPPDS2 SPACE (TRK,(100,80,80)) UNIT=SYSDA

CWPPRTO is dynamically allocated as a work file (for the preprocessor). SYSPRINT is where the listing
goes.

Post-processor
The postprocessor is executed as a single step and it can be a separate job. It reads in the listing
created from the compiler. Information is gathered from the source listing, XREF, data maps, and
object code sections of the listing. This information is stored in a DDIO file member and is used by
various Compuware products.

While the preprocessor is the preferred method of loading the compiled listing to the DDIO, there are
situations that necessitate the use of the postprocessor as a viable alternative. This is commonly
found in production environments where the listings may be archived. In order for the listings to
populate the DDIO, they must be compiled using the required options specified in the appropriate
language processor chapters in the Compuware Shared Services User/Reference Guide.In order for the
listings to populate the DDIO, they must be compiled using the required options specified in the
appropriate language processor chapter. Note that these are usually the default options at many
shops.

If the programs contain suppressed source code, certain additional control statements must be added
to the language processor. Please view the Language Processor chapters in the Compuware Shared
Services User/Reference Guide for the programming language desired for more details.Please view the
Language Processor chapters for the programming language desired for more details.

If the programs are compiled with OFFSET as well as OPT(imize), certain additional control
statements must be added to the language processor. Please view the Language Processor chapters in
the Compuware Shared Services User/Reference Guide for the programming language desired for more
details.Please view the Language Processor chapters for the programming language desired for more
details.

Postprocessor Benefits
• Exact match of compiled output listings with the executable load module. This is especially
important in production environments where time is critical.

• Eliminates the risk of copybook or source code changes prior to recompiling the code since the
listing reflects the code that is being executed.
Compuware Shared Services Configuration and Administration 113

• Significantly less time is needed to process source listings as opposed to recompiling the source
code.

Language Processor DD Statements

Table 4 lists the DD statements for the Assembler, COBOL, PL/I, and C language processors. Not every
DD Name applies to every language processor.Used in COBOL, PL/I, and Assembler Language
Processor chapters

Table 4. Language Processor DD Statements.

DDname Purpose
CWPWRK (0-6) LP work files
CWPPRMO LP parameter input dataset
CWPDDIO Target source listing DDIO file
CWPPRTI Compiler listing input to postprocessor
CWPPRTO Compiler listing output from postprocessor
CWPLOAD Option LOAD or OBJECT module input to postprocessor
CWPDECK Option DECK module input to postprocessor
CWPERRM LP Error Messages
CWPWBNV Workbench navigation information

CWPLOAD and CWPDECK correspond to the SYSLIN and SYSPUNCH compiler outputs. If you specify
compiler option OBJECT, you should use CWPLOAD in your postprocessor JCL. If you specify compiler
option DECK, you should use CWPDECK in your postprocessor JCL. Do not feed the SYSLIN output into
CWPDECK or the SYSPUNCH output into CWPLOAD. The updated OBJECT contained in CWPLOAD and
CWPDECK should be used in the program’s linkedit step. The preprocessor does not use CWPLOAD and
CWPDECK.

Writing a Listing to a DDIO File

Several options exist to place listings in a DDIO file. Each option requires that some changes be made
to your JCL. The type of changes needed depend on whether you are using the preprocessor or the
post-processor, and the type of debugging session. Refer to “CSS Sample Library Members” for a list of
the sample JCL that can be used for the various options.

Testing and Debugging Programs

The actual method used for handling testing and debugging programs depends on whether you are
preprocessing or postprocessing:

• Preprocessing — Run the preprocessor and link your program.

• Postprocessing — Compile your program, run the post-processor, and then link your program.

With either of these methods, the language processor places a listing in the DDIO file whenever a
program is compiled.

Debugging Production Programs

If the original compiler listing is available in machine-readable format, you can retrieve the listing
and use it as input to the post-processor in order to reprocess the listing and recreate it in the DDIO
file. The post-processor can process listings stored by most products.
114 Enterprise Common Components Advanced Configuration Guide

If the listing you use as input to the post-processor contains any other information (such as translator or
link edit output), in addition to the compiler information, you may not obtain the desired results.

CSS Sample Library Members

The following list describes the CSS members of the ECC sample JCL library that you may work with
during installation (depending on your installation options). Use these members only as needed if
directed to do so by a specific Compuware product installation guide. These members are distributed
and updated via SMP/E. The members will be located in the following files (showing initial default
HLQ) after the SMP/E Apply and Accept steps are complete.

• CPWR.MLCXnnn.SLCXCNTL (target library)

• CPWR.MLCXnnn.ALCXCNTL (distribution library)

where nnn indicates the release number, for example MLCX170.

To print the CSS sample library members, submit the JCL contained in library member CXPRINT after
the distributed media has been unloaded.

CWASSECD Security Exit program DSECT.

CWASSECU Sample Security Exit program.

CWCMTRHE Sample customized horizontal translation table for mixed-case English.

CWCMTRHT Sample customized horizontal translation table for uppercase English.

CWCMTRHU Sample customized horizontal translation table for mixed-case English

with Euro character.

CWCMTRVE Sample customized vertical translation table for mixed-case English.

CWCMTRVT Sample customized vertical translation table for uppercase English.

CWCMTRVU Sample customized vertical translation table for mixed-case English

with Euro character.

The following five members are specific for Abend-AID. They

allow browse access to diagnostic reports and source listings
directly through ROSCOE or print access via a job submitted
from ROSCOE to run in batch. Refer to the members for
additional information.

CWROSBAT ROSCOE sample members.

CWROSBRW ROSCOE sample members.

CWROSCOE ROSCOE sample members.

CWROSDIR ROSCOE sample members.

CWROSPDF ROSCOE sample members.

CWUTCLSE Sample CLIST to invoke CSS online utilities with English messages and
panels.
Compuware Shared Services Configuration and Administration 115

CWUTCLSJ Sample CLIST to invoke CSS online utilities with Japanese messages and
panels.

CWUTREXE Sample REXX EXEC to invoke CSS online utilities with English messages
and panels.

CWUTREXJ Sample REXX EXEC to invoke CSS online utilities with Japanese
messages and panels.

CWVFCLPT CLIST to invoke the language processor debugging aid.

The debugging aid is a diagnostic tool to be used only under

the supervision of Compuware customer support in the event
of a problem related to the language processor.

CWVFRXPT Sample REXX EXEC to invoke the Compuware language processor

debugging aid.

The debugging aid is a diagnostic tool to be used only under

the supervision of Compuware customer support.

CXAADIRX Abend-AID CWAASDUT DIRX sample JCL.

CXAAEXPO Abend-AID CWAASDUT EXPORT command sample JCL.

CXAAIMPO Abend-AID CWAASDUT IMPORT command sample JCL.

CXAAMOVE Abend-AID CWAASDUT MOVE command sample JCL

CXALLBAA JCL for creating sequential Abend-AID database files.

CXALLBLP JCL for creating sequential source listing database files.

CXALLBSD JCL for creating Abend-AID for CICS sequential transaction databases.

CXALLDAA JCL for creating Abend-AID shared directories.

CXALLDLP JCL for creating Source Listing Shared Directories.

CXALLDS JCL to allocate a sequential DDIO file.

CXALLMC JCL for creating Abend-AID for CICS shared directories.

CXALLVAA JCL for creating VSAM Abend-AID database files.

CXALLVLP JCL for creating VSAM Source Listing Database files.

CXALLVS JCL to allocate a standard VSAM Abend-AID report or source listing

DDIO file.

CXALLVSD JCL for creating Abend-AID for CICS VSAM transaction databases.

CXASM JCL for running the Assembler language post-processor.

CXASMPRE JCL for running the Assembler language preprocessor.

CXC Sample JCL for running the C post-processor.

116 Enterprise Common Components Advanced Configuration Guide

CXCAPTUR Sample JCL for creating a tape from the output of the CSS Problem
Documentation Utility.

CXCFGEXT Sample JCL to extract a source file from the configuration module in an
ECC load library.

CXCFGINI Sample source configuration file.

CXCFGSET Sample JCL to build a configuration module in an ECC load library,

from a source configuration file you create.

CXCIREG Sample JCL to register the Contact Information dataset.

CXCIVSAM Sample JCL to create the Contact Information dataset.

CXCOBPRE JCL for running the COBOL language preprocessor.

CXCOB1 JCL for the step to be added after the compile step in your current
COBOL compile and link edit JCL. This is used in order to process the
compiler listing through the Compuware language post-processor.

CXCOB2 JCL to process COBOL compiler listings stored in machine-readable

format.

CXCOB99 Sample JCL for running the COBOL post-processor.

CXCPRE Sample JCL for running the C preprocessor.

CXC2 Sample JCL to postprocess C compiler listings stored in machine-

readable format.

CXDCRADB JCL to allocate and CREATE a multi-volume Abend-AID report database.

CXDCRASD JCL to allocate and CREATE an Abend-AID shared directory and a multi-
volume report database.

CXDCRLDB JCL to allocate and CREATE a multi-volume source listing database.

CXDCRLSD JCL to allocate and CREATE a source shared directory and a multi-
volume Source Listing database.

CXDCRTDB JCL to allocate and CREATE a multi-volume transaction database.

CXDCRTSD JCL to allocate and CREATE an Abend-AID for CICS shared directory
and a multi-volume transaction database.

CXDDSUTL Sample JCL for running the CWDDSUTL batch file utility.

CXDDUNLP Sample JCL to execute the CWDDUNLP source extraction utility.

CXDFMAA JCL to allocate and FORMAT a standard multi-volume Abend-AID report

DDIO file.

CXDFMSL JCL to allocate and FORMAT a standard multi-volume source listing

DDIO file.

CXEXPORT Sample JCL for running the CWDDSUTL EXPORT command.

CXFLAG Sample JCL for the CWDDSUTL utility FLAG command.

CXFMTAA Sample JCL and CWDDSUTL control statement for formatting Abend-
AID report files.
Compuware Shared Services Configuration and Administration 117

CXFMTSL Sample JCL and CWDDSUTL control statement for formatting a source
listing file.

CXCFDIRX Abend-AID for CICS CWFXSDUT DIRX sample JCL.

CXCFEXPO Abend-AID for CICS CWFXSDUT EXPORT command sample JCL.

CXCFEXTL Sample JCL to export a Abend-AID for CICS transaction and a source
listing to a single tape.

CXCFIMPO Abend-AID for CICS CWFXSDUT IMPORT command sample JCL.

CXCFMOVE Abend-AID for CICS CWFXSDUT MOVE command sample JCL.

CXIMPORT Sample JCL for running the CWDDSUTL IMPORT command.

CXJCLSEC JCL to assemble and link edit the Security Exit program.

CXJCLTRT JCL to assemble and link edit the custom translation tables.

CXLPASM Sample Assembler language processor options.

CXLPC Sample C language processor options.

CXLPCOBB Sample COBOL language processor options (batch programs).

CXLPCOBC Sample COBOL language processor options (CICS programs).

CXLPDIRX LP source CWDDLPUT DIRX sample JCL.

CXLPEXPO LP source CWDDLPUT EXPORT command sample JCL.

CXLPIMPO LP source CWDDLPUT IMPORT command sample JCL.

CXLPMOVE LP source CWDDLPUT MOVE command sample JCL.

CXLPPLI Sample PL/I language processor options.

CXLPTFS Sample JCL to run SMPE LIST on ECC Target/Distribution zones.

CXLZAPS Sample JCL to list the PTFs and APARs on an ECC load library

CXMODMAP Sample JCL member to map the CSECTs in a load module.

CXOTFPRE Sample CLIST stub for preprocessing exit for OTF

CXOTFPST Sample CLIST stub for postprocessing exit for OTF

CXPDDSU Sample JCL to print a listing or report from a DDIO file.

CXPLI JCL for running the PL/I language post-processor.

CXPLIPRE JCL for running the PL/I language preprocessor.

CXPLI2 JCL to postprocess PL/I compiler listings stored in machine-readable

format.

CXPRCTL IEBPTPCH control statements for job CXPRINT.

CXPRINT JCL to print the entire ECC sample library SLCXCNTL.

CXRELS PTF/APAR tracking module. Do not modify this member.

118 Enterprise Common Components Advanced Configuration Guide

CXR00003 Sample Tutorial main menu.

CXSPRE01 Sample Skeleton for on-the-fly preprocessing.

CXSPST01 Sample Skeleton for on-the-fly postprocessing.

CXTUTOR Alternate Sample Tutorial main panel.

CXUECEXT Sample CLIST for the Compile Facility JOB card exit

CXUECIN2 REXX EXEC used to invoke the Compile Information installation

screens

DDIODAYS REXX utility to delete DDIO file members by age.

DDIODAYJ Sample JCL for running the DDIODAYS REXX utility. This utility deletes
DDIO file members by age.

FDXTRN01 File-AID DB2 Interface CLIST.

GRSRNLXX Sample GRS qname inclusion RNL.

P@CPRE01 Sample panel for preprocessing exit for on-the-fly.

P@CPST01 Sample panel for postprocessing exit for on-the-fly.

P@HPRE01 Sample Help panel for preprocessing exit for on-the-fly (OTF)
processing.

P@HPST01 Sample Help panel for postprocessing exit for on-the-fly (OTF)
processing.

ATSOECLP Sample TSO logon procedure for Xpediter/TSO via Compuware

Mainframe Eclipse.

CSPFINIT Sample JCL to create and initialize the Compuware Shared Profile
dataset.

CXCFGBLD Sample JCL to create the Compuware Mainframe Eclipse configuration

file dataset.

CXTPDEF Sample HCI configuration parameters to be inserted into an existing

HCI configuration.

HCIPROCS Sample JCL to create HCI and CSS TP procedures.

HCIJOURN Sample JCL to create the HCI journals.

HCITEST Sample JCL to test HCI connectivity.

HCI00 Sample HCI and CSSTP PARMLIB member.

Install Customized Translation Tables

If you omit this step, the default translation tables will be used.

You must perform this step if you are using Japanese language support with Abend-AID.

You may optionally perform this step if you have Abend-AID. When necessary, Abend-AID products
dump storage in both hexadecimal and character representation. These storage areas will appear in
one of two formats:
Compuware Shared Services Configuration and Administration 119

• Horizontal dump
• Vertical dump

The character representation for either format is controlled by a default translation table. The default
character set is mixed-case English. You can override either, or both, of these default translation
tables with customized translation tables. Different customized translation tables can be specified for
either dump format. These customized tables may also allow display of certain otherwise non-
displayable fields.

If you install vertical and/or horizontal customized translation tables, CWCMTRVT must be used as
the load module name for the vertical translation table, and CWCMTRHT must be used as the load
module name for the horizontal translation table. A different internal name can be defined to
identify a table. The internal table name must be eight characters long. The table length, excluding
the table name, must be 256 bytes. Therefore, the total table length is 264 bytes. If an error is made
installing a customized translation table, the Compuware default table is used.

The following SLCXCNTL sample library members contain sample translation tables:

CWCMTRVT Vertical translation table for uppercase English.

CWCMTRHT Horizontal translation table for uppercase English.

CWCMTRVE Vertical translation table for mixed-case English. This is the default
vertical translation table that will be used if you choose not to install
a customized vertical translation table.

CWCMTRHE Horizontal translation table for mixed-case English. This is the

default horizontal translation table that will be used if you choose
not to install a customized horizontal translation table.

CWCMTRVU Vertical translation table for mixed-case English with the Euro
Character X‘9F’ included.

CWCMTRHU Horizontal translation table for mixed-case English with the Euro
character X’9F’ included.

The ECC SLCXCNTL sample library member CXJCLTRT contains the sample JCL to assemble and
link-edit customized translation tables.
120 Enterprise Common Components Advanced Configuration Guide

Prepare the DDIO Files

You must perform this step if you are a new CSS user or have never created DDIO files and now
need to use them. If you are an Abend-AID user you will need to allocate a Report Shared Directory
and one or more Report databases.

CSS DDIO files are used to store Abend-AID reports, transaction dump information, and source
listings. The term DDIO file is a generic term used to refer to the datasets that store the reports and
listings from Compuware Products that use CSS. This step describes the various types of DDIO files
available and who needs to allocate which type.

Types of DDIO Files

There are two main categories of DDIO files: report or source listing files and report or source listing
databases, which are grouped into pools attached to Shared Directories. CSS uses the Shared Directory
architecture to manage the available pool space.

Within these two categories of DDIO files, there are three different types of DDIO files characterized
by the type of information that is stored in them: Abend-AID reports, source listings, and CICS
transaction dump information.

If you use the Shared Directory architecture for your DDIO files,
different database types cannot be attached to the same Shared
Directory (for example, you cannot attach a source listing
database to a report shared directory, and vice versa). You can
attach transaction databases and report databases to the same
Shared Directory.

Non-database report or source listing files cannot be attached

to a Shared Directory until they have been converted using the
batch utility CONVERT command in CWDDALLU, or
CWAASDUT (report only) and CWDDLPUT (source listing only).
See the “Batch File Utility” chapters in the Compuware Shared
Services User/Reference Guide for more information, specifically
Chapter 8 “Batch File Utility CWDDALLU” for detailed
command and parameter descriptions.

1. Abend Reports:
a. Report Shared Directories and Databases. This type of file is used to store abend reports
created by Abend-AID. This Report Shared Directory architecture is only supported for Abend-AID
Release 9.4 and later. Report databases are attached to a report shared directory. The report
databases are managed as a POOL of space belonging to the report shared directory to which
they are attached.
b. Report DDIO files. This type of DDIO file is used to store Abend Reports created by Abend-
AID. Prior to Abend-AID Release 9.4, this was the only type of report file available. For
compatibility purposes, Abend-AID Release 9.4 can also use this type of report file. A
conversion utility is available to run when the user is ready to migrate the report file to the
report database format.

Abend-AID Classic Report files are not supported with Abend-AID Release 12.4 or newer.

2. Source Listings:
a. Source Listing Shared Directories and Databases. This type of DDIO file is used to store
compiler source listings for use by various Compuware Products. Source listing databases are
attached to a source listing shared directory. The source listing databases are managed as a
POOL of space belonging to the source listing shared directory to which they are attached.
The Source Listing Shared Directory architecture can now be used with all supported language compilers.
However, Xpediter users should see notes and exceptions below.
Compuware Shared Services Configuration and Administration 121

b. Source Listing DDIO Files. This type of DDIO file is used to store compiler source listings. A
conversion utility is available to run when the user is ready to migrate the listing file to the
source listing database format.

The same source listing file, database, or source listing member can be used by multiple Compuware Products. It
is not necessary to create duplicate source listing files, databases, or source listing members for
each Compuware Product.

3. Transaction Databases and Shared Directory for Abend-AID for CICS. Transaction databases
are used by Abend-AID for CICS to store CICS transaction dump information. Abend-AID for
CICS catalogs both CICS transaction dumps and imported Region Dumps into the shared
directory.

The following table lists the types of DDIO files created by the CSS utilities and which products
use/require them:

Table 5. DDIO File Formats

Transaction Report Source Source
Report Source Databases & Shared Dir. Listing Listing
Compuware Product File Listing File Shared Dir. & Database Shared Dir. Database
x1
Abend-AID See Note x x x x
Abend-AID for CICS x x x x
2
x
Xpediter/TSO x See Note x
2
x
Xpediter/IMS x See Note x
Xpediter/CICS x See Note x
Xpediter/Eclipse x See Note x
Strobe x x x

1
Abend-AID Classic Report files are not supported with Abend-AID Release 12.4 or newer.
2
If using Xpediter/TSO and /IMS with the C Language Processor, VisualAge PL/I, or Enterprise PL/I, and you use Long
Program Names, the Source Listing Shared Directory must be used.

Refer to the “Source Listing Databases and Shared Directories” section of Chapter 2 in the Compuware
Shared Services User/Reference Guide for more information.

File Access Methods

You may use either sequential or VSAM files for DDIO files. Shared directories must be VSAM files. If
you are using VSAM files for your DDIO files, you can copy them using the IDCAMS REPRO
command. You cannot, however, change any of the file attributes such as CISIZE without reallocating
a DDIO/DB file. Allocation and format requirements, along with the steps for preparing the various
DDIO files, will vary according to the type of file. Source listing files can be shared between all
Compuware products that use CSS, while report files, transaction databases, work files, and profile
files, cannot. Source listing files used by Xpediter/CICS must be VSAM.

CAUTION:

CWDDSUTL, CWFXSDUT, CWAASDUT, CWDDLPUT, and CWDDALLU are the only utilities
recommended for use with Compuware DDIO files.

File-AID/MVS and other VSAM-related vendor products (including vendor packages that compress or
enhance buffer management on VSAM files) should NOT be used against Compuware DDIO files.
Doing so can result in corrupting the contents of the DDIO file. Refer to “Chapter 2. Allocating and
Formatting DDIO Files” in the Compuware Shared Services User/Reference Guide for more information.
122 Enterprise Common Components Advanced Configuration Guide

Allocate and Format Abend-AID Report Shared Directories and Databases for
Abend-AID Release 9.4 and Later Users
This process should only be performed by Abend-AID users who have installed, are installing, or are
migrating to Abend-AID Release 9.4 or later. The purpose of this step is to allocate and format a
Report Shared Directory and one or more Report Databases attached to that Shared Directory. Note
that Abend-AID 9.4 is the minimum release able to use these types of DDIO file.

Typically, this step would be performed during Abend-AID release 9.4 or later installation. For more
information, see the Abend-AID Installation and Customization Guide.

The CSS online utilities can be used to allocate and format Abend-AID report DDIO files. Refer to
“Chapter 3. CSS Utilities” in the Compuware Shared Services User/Reference Guide for more information.

Create the Report Shared Directory

Use the sample JCL in the ECC SLCXCNTL dataset to allocate and format the Report Shared Directory
(member is CXALLDAA). For additional options refer to the “Batch File Utility CWDDALLU” chapter
in the Compuware Shared Services User/Reference Guide. The shared directory CREATE command will both
ALLOCATE and FORMAT the shared directory. If the file currently exists, you must specify parameter
REALLOCATE=YES or the allocate will fail with a duplicate file error.

Create the Report Databases

You must have already created the Report Shared Directory before attempting to create the Report
Database. You can create both in the same job as long as the Report Shared Directory create is done
first. The database CREATE command will both ALLOCATE and FORMAT the database. If the file
currently exists, you must specify parameter REALLOCATE=YES or the allocate will fail with a
duplicate file error.

VSAM Report Databases can be created using the sample JCL in the ECC SLCXCNTL dataset
(member is CXALLVAA). To allocate and create a database that spans multi-volumes, use member
CXDCRADB. To create a report shared directory in the same job, use member CXDCRASD.

Sequential Report Databases can be created using the sample JCL in the ECC SLCXCNTL dataset
(member is CXALLBAA).

Allocate and Format Source Listing Shared Directories and Databases

This process may be performed by all users who use Source Listing support. Source Listing Databases
used by Xpediter/CICS must be VSAM.

The CSS online utilities can be used to allocate and format source listing DDIO files. Refer to
“Chapter 3. CSS Utilities” in the Compuware Shared Services User/Reference Guide for more information.

Create the Source Listing Shared Directory.

Use the sample JCL in the ECC SLCXCNTL dataset to allocate and format the Source Listing Shared
Directory (member is CXALLDLP). For additional options refer to the “Batch File Utility
CWDDALLU” chapter in the Compuware Shared Services User/Reference Guide. The shared directory
CREATE command will both ALLOCATE and FORMAT the shared directory. If the file currently exists,
you must specify parameter REALLOCATE=YES or the allocate will fail with a duplicate file error.

Create the Source Listing Databases

You must have already created the Source Listing Shared Directory before attempting to create the
Source Listing Database. You can create both in the same job as long as the Source Listing Shared
Directory create is done first. The database CREATE command will both ALLOCATE and FORMAT the
database. If the file currently exists, you must specify parameter REALLOCATE=YES or the allocate
will fail with a duplicate file error.
Compuware Shared Services Configuration and Administration 123

VSAM Source Listing Databases can be created using the sample JCL in the ECC SLCXCNTL dataset
(member is CXALLVLP). To allocate and create a database that spans multi-volumes, use member
CXDCRLDB. To create a source shared directory in the same job, use member CXDCRLSD.

Sequential Source Listing Databases can be created using the sample JCL in the ECC SLCXCNTL
dataset (member is CXALLBLP).

Allocate and Format Source Listing Files

You must perform this step if you did not perform “Allocate and Format Source Listing Shared
Directories and Databases” and you do not have an existing source listing file or database. Source
listing files used by Xpediter/CICS must be VSAM.

Allocate the Source Listing Files

VSAM Source Listing files can be allocated using the sample JCL in the ECC SLCXCNTL dataset
member CXALLVS. To allocate and format a source DDIO file that spans multi-volumes, use member
CXDFMSL).

Sequential Source Listing files can be allocated using the sample JCL in the ECC SLCXCNTL dataset
member CXALLDS.

Format the Source Listing Files

After the source listing files have been allocated, they must be formatted before they can be used. The
formatting process initializes the directory structure and specifies the file options.

ECC SLCXCNTL library member CXFMTSL contains sample JCL to format a source listing file with
appropriate defaults for the sample files allocated using members CXALLVS or CXALLDS. Adjust the
formatting parameters to meet your DDIO file needs. Do not execute the CXFMTSL member, if you
have already run the CXDFMSL job.

Allocate and Format Abend-AID for CICS Shared Directories and Transaction
Databases
Normally this would be performed during the Abend-AID for CICS install procedure. For additional
information, see the Abend-AID Installation and Configuration Guide.

Create the Abend-AID for CICS Shared Directory (Allocate & Format)
Use the sample JCL to create the shared directory. ECC SLCXCNTL sample library member CXALLMC
contains the sample JCL for creating a Abend-AID for CICS shared directory.

Create the Abend-AID for CICS Transaction Database (Allocate & Format)
You must create the shared directory before proceeding to this step. Use one of the following two sets
of sample JCL to create each Abend-AID for CICS database as needed:

VSAM Abend-AID for CICS Database: ECC SLCXCNTL sample library member CXALLVSD contains
sample JCL for creating a Abend-AID for CICS VSAM transaction database. To allocate and create a
database that spans multi-volumes, use member CXDCRTDB. To create an Abend-AID for CICS shared
directory in the same job, use member CXDCRTSD.

Sequential Abend-AID for CICS Database: ECC SLCXCNTL sample library member CXALLBSD
contains sample JCL for creating a Abend-AID for CICS sequential transaction database.
124 Enterprise Common Components Advanced Configuration Guide

Implement the Language Processor JCL

See the sub-steps below to determine when you must perform this step.

The language processors support two methods of processing your programs: preprocessing and post-
processing. Both of these choices may involve modifications to your compile JCL.

You may use the preprocessor or post-processor (whichever is best for your site as needed.) This
section discusses the benefits of the preprocessor and the post-processor and describes when to use
them.

To use the language processor, you must have previously completed installation of the ECC load
library and also prepared a DDIO file. For each language you are using, you should modify the
corresponding compiler procedure to provide for the type of processing you will be implementing.

When running the language processor as a preprocessor, you can specify assembler/compiler options
in the CWPPRMO dataset or in the PARM statement passed to the preprocessor. The CWPPRMO is an
input dataset that contains the language processor compiler options. Depending on the method used,
it may be necessary to include the LANGPARM command with these options.

If you are currently using the post-processor, and you will be converting to the preprocessor, you are
not required to spool your SYSPRINT to a temporary dataset.

For each of the following steps, it is possible that you will receive a return code other than
zero. Should this occur, note the accompanying language processor error message and
refer to the Enterprise Common Components Messages and Codes guide for further
information.

Modify the JCL to Run the COBOL Language Processor

You must perform this step if either of the following is true:

• You are installing Xpediter/CICS for the first time.

• You are installing Abend-AID for the first time or you are upgrading a current Abend-AID
installation with Abend-AID source support and you are licensed for the Compuware COBOL
language processor.

You may optionally perform this step if you are installing Xpediter/TSO and you are licensed for the
Compuware COBOL language processor. Xpediter/TSO users can either perform this step now in
batch mode, or online as part of the Xpediter/TSO installation procedure.

This step contains instructions for both the COBOL language preprocessor and post-processor. You
should follow the instructions that apply to the type of processing you will be performing.

Preprocessor
SLCXCNTL sample library member CXCOBPRE contains sample JCL necessary to run the COBOL
language preprocessor.

Modify the compile step of your COBOL JCL:

• On the EXEC statement, change the name of your compiler to CWPCMAIN and add the
following to any existing COBOL compiler options:

LANGUAGE(compiler version)

Notes:
a. The LANGUAGE command may be specified in the CWPPRMO command stream rather than
on the EXEC statement.
Compuware Shared Services Configuration and Administration 125

b. The preprocessor accepts VSCOBOLII, VSCOBOLIIREL3, VSCOBOLIIREL4, COBOL/370,

COBOL/390, COBOL/MVS, and COBOLZ/OS as being equivalent because the program name is
the same. The compiler that is actually executed depends on the library specified in the
STEPLIB, JOBLIB, and/or LINKLIST concatenation.

• Add the ECC SLCXLOAD DSN to the STEPLIB or JOBLIB concatenation if it is not in the link list.

• Add the CWPDDIO DD statement to specify the name of the source listing DDIO file you will be
using. The source listing DDIO file may be in standard DDIO, shared directory, or database
format.

Note: If the source member is to be used by Xpediter/CICS, the source listing file specified here
must be VSAM.

• Determine the language processor options you will use as input and add them to the EXEC
parameter, or add a CWPPRMO DD statement that points to the appropriate options. Sample
options are contained in SLCXCNTL sample library members CXLPCOBB (for batch programs)
and CXLPCOBC (for CICS programs) to provide the smallest output to the source listing file (for
minimizing space) and generate a printout of the COBOL enhanced listing. When using these
options, a printout of the listing from the DDIO file contains only the source statements. The
XREF and other portions of the listing are not written to the DDIO file. If you use the sample
options, note the following:

– If you do not have Xpediter/TSO, remove DDIO(OUTPUT(FIND)).

– If the program will be used by Xpediter/CICS or Abend-AID for CICS, use the options in
sample CXLPCOBC.

• The SYSPRINT file will be LRECL=133, RECFM=FBA.

Post-processor
You can use the post-processor to process compile listings that were previously stored, or you can
modify your COBOL compile JCL to pass the compiler listing to the post-processor as described
below.

• Check the COBOL compiler options.

• Change the COBOL compiler JCL to write the compiler listing (SYSPRINT) to a sequential file that
can be used as input to the COBOL language post-processor. A sample of the necessary JCL is
shown below.

//SYSPRINT DD UNIT=SYSDA,SPACE=(TRK,(25,20)),DCB=BLKSIZE=16093,
// DISP=(MOD,PASS) <===== CA-OPTIMIZER NEEDS 'MOD'

The above example is a temporary file. You can save the JCL as a permanent file to be reused as
shown in the example below:

//SYSPRINT DD DSN=CX,STORED.LISTINGS(MEMBER)

• The SYSPRINT file will be LRECL=133, RECFM=FBA.

• Add SLCXCNTL sample library member CXCOB1 as the post-processor step following your
COBOL compile step.

• Determine the language processor options you will use as input and add them to the EXEC
parameter, or add a CWPPRMO DD statement that points to the appropriate options. Sample
options are contained in SLCXCNTL sample library members CXLPCOBB (for batch programs)
and CXLPCOBC (for CICS programs) to provide the smallest output to the source listing file (for
minimizing space) and generate a printout of the COBOL listing. When using these options, a
printout of the listing from the DDIO file will contain only the source statements. The XREF and
126 Enterprise Common Components Advanced Configuration Guide

other portions of the listing will not be written to the DDIO file. If you use the sample options,
note the following:

– If you do not have Xpediter/TSO, remove DDIO(OUTPUT(FIND)).

– If the program will be used by Xpediter/CICS or Abend-AID for CICS, use the options in
sample CXLPCOBC.

The SLCXCNTL sample library members that are supplied for the COBOL language post-processor
invoke the language processor in different ways:

Table 6. SLCXCNTL Sample Library Members for COBOL Language Processor

Member Purpose
Processes compiler listings through the language post-processor. Add this JCL after your
CXCOB1
COBOL compile step and before your link edit step (if one exists).
Postprocesses compiler listings stored from a previous compile job. Use this JCL to process
CXCOB2
listings that have been previously compiled and stored in machine-readable format.
CXCOB99 Compiles COBOL programs and feeds the compiler output into the COBOL post-processor.

• The CWPPRTO file will be LRECL=133, RECFM=FBA.

• The CWPLOAD file must be allocated using DISP=OLD or DISP=SHR.

• The object module that is processed by the post-processor must be used as input to the linkedit
step.

Modify the JCL to Run the PL/I Language Processor

You must perform this step if the following is true:

• You are installing Xpediter/CICS or Xpediter/TSO and you are licensed for the Compuware PL/I
language processor.

This step contains instructions for both the PL/I language preprocessor and post-processor. You
should follow the instructions that apply to the type of processing you will be performing.

Preprocessor
SLCXCNTL sample library member CXPLIPRE contains sample JCL necessary to run the PL/I language
preprocessor.

Modify the compile step of your PL/I JCL:

• On the EXEC statement, change the name of your compiler to CWPPMAIN and add the following
to any existing PL/I compiler options:

LANGUAGE(compiler version)

Refer to the Compuware Shared Services User/Reference Guide for a list of the compiler versions that can
be specified with the LANGUAGE command. The default compiler for PL/I is the compiler
currently in use on your system.

Note: The LANGUAGE command may be specified in the CWPPRMO command stream rather
than on the EXEC statement.

• Add the ECC SLCXLOAD DSN to the STEPLIB or JOBLIB concatenation if it is not in the link list.

• Add the CWPDDIO DD statement to specify the name of the source listing DDIO file you will be
using. The source listing DDIO file may be in standard DDIO, shared directory, or database
format.
Compuware Shared Services Configuration and Administration 127

Note: If the source member is to be used by Xpediter/CICS, the source listing file specified here
must be VSAM.

• Determine the language processor options you will use as input and add them to the EXEC
parameter, or add a CWPPRMO DD statement that points to the appropriate options. Sample
options are contained in SLCXCNTL sample library member CXLPPLI to provide the smallest
output to the source listing file (for minimizing space). If you use these options, and you will be
using the PL/I language preprocessor, add LANGUAGE(xxx) to the EXEC PARM or to the
CWPPRMO DD statement.

See the Compuware Shared Services User/Reference Guide for more information on this JCL and PL/I
language processor options.

Post-processor
You can use the post-processor to process compile listings that were previously stored, or you can
modify your PL/I compile JCL to pass the compiler listing to the post-processor as described below.

• Check the PL/I compiler options.

• Change the PL/I compile JCL to write the compiler listing (SYSPRINT) to a sequential file for use
as input to the PL/I language post-processor. A sample of the necessary JCL is shown below.

//SYSPRINT DD UNIT=SYSDA,SPACE=(CYL,(100,10)),DCB=BLKSIZE=19069,
// DISP=(MOD,PASS)

The above example is a temporary file. You can save the JCL as a permanent file to be reused as
shown in the example below:

//SYSPRINT DD DSN=CX,STORED.LISTINGS(MEMBER)

• The SYSPRINT file will be LRECL=133, RECFM=FBA.

Table 7. SLCXCNTL Sample Library Members for PL/I Language Processor

Member Purpose
Processes compiler listings through the language post-processor. Add this JCL after your PL/I
CXPLI compile step and before your link edit step (if one exists). CXPLI can be customized to meet
your site’s requirements.
Postprocesses compiler listings stored from a previous compile job. Use this JCL to process
CXPLI2
listings that have been previously compiled and stored in machine-readable format.

• The CWPLOAD file must be allocated using DISP=OLD or DISP=SHR.

• The object module that is processed by the post-processor must be used as input to the linkedit
step.

See the Compuware Shared Services User/Reference Guide for more information on this JCL and PL/I
language processor options.

Modify the JCL to Run the Assembler Language Processor

You must perform this step if you are licensed for the Assembler language processor option for any
product.

You can optionally perform this step if you are installing Xpediter/TSO and you are licensed for the
Compuware Assembler language processor. Xpediter/TSO users can either perform this step now in
batch mode, or online as part of the Xpediter/TSO installation procedure.

This step contains instructions for both the Assembler language preprocessor and post-processor. You
should follow the instructions that apply to the type of processing you will be performing.
128 Enterprise Common Components Advanced Configuration Guide

SLCXCNTL sample library member CXASMPRE contains sample JCL necessary to run the Assembler
language preprocessor.

Preprocessor
Modify the assembly step of your Assembler JCL:

• On the EXEC statement, change the name of your compiler to CWPAMAIN and add the following
to any existing assembler options:

LANGUAGE(assembler version)

Refer to the Compuware Shared Services User/Reference Guide for a list of the assembler versions that
can be specified with the LANGUAGE command. The default assembler is Assembler H.

Note: The LANGUAGE command may be specified in the CWPPRMO command stream rather
than on the EXEC statement.

• Add the ECC SLCXLOAD DSN to the STEPLIB or JOBLIB concatenation if it is not in the link list.

• Add the CWPDDIO DD statement to specify the name of the source listing DDIO file you will be
using. The source listing DDIO file may be in standard DDIO, shared directory, or database
format.

Note: If the source member is to be used by Xpediter/CICS, the source listing file specified here
must be VSAM.

• Determine the language processor options you will use as input and add them to the EXEC
parameter, or add a CWPPRMO DD statement that points to the appropriate options. Sample
options are contained in SLCXCNTL sample library member CXLPASM to provide the smallest
output to the source listing file (for minimizing space). When using these parameters, a printout
of the listing from the DDIO file will contain only the source statements. The XREF will not be
written to the DDIO file. If you use these options and you will use the Assembler language
preprocessor, add LANGUAGE(xxx) to the EXEC PARM or to the CWPPRMO DD statement.

• Specify the compiler (and release) you will use by including it as a parameter of the LANGUAGE
command in your EXECUTE parameter or CWPPRMO DD statement.

Refer to the Compuware Shared Services User/Reference Guide for more information on the LANGUAGE
command, for a list of available compilers, and for more information on this JCL and language
processor options.

Post-processor
You can use the post-processor to process compile listings that were previously stored, or you can
modify your Assembler compile JCL to pass the compiler listing to the post-processor as described
below.

• Check the assembler options.

• Change your assembler JCL to write the compiler listing (SYSPRINT) to a sequential file for use as
input to the Assembler language post-processor. A sample of the necessary JCL is shown below.

//SYSPRINT DD UNIT=SYSDA,SPACE=(TRK,(25,20)),DCB=BLKSIZE=16093,
// DISP=(MOD,PASS)

The above example is a temporary file. You can save the JCL as a permanent file to be reused as
shown in the example below:

//SYSPRINT DD DSN=CX,STORED.LISTINGS(MEMBER)

• The SYSPRINT file will be LRECL=133, RECFM=FBA.

Compuware Shared Services Configuration and Administration 129

• Add SLCXCNTL sample library member CXASM as the post-processor step following your
assembler step. CXASM can be customized to meet your site’s requirements.

Note: The CWPLOAD file must be allocated using DISP=OLD or DISP=SHR.

• The object module that is processed by the post-processor must be used as input to the linkedit
step.

Refer to the Compuware Shared Services User/Reference Guide for more information on this JCL and
language processor options.

Modify the JCL to Run the C Language Processor

You must perform this step if you are installing Xpediter/TSO and you are licensed for the
Compuware C language processor.

This step contains instructions for both the C language preprocessor and post-processor. You should
follow the instructions that apply to the type of processing you will be performing.

Preprocessor
SLCXCNTL sample library member CXCPRE contains sample JCL necessary to run the C language
preprocessor.

Modify the compile step of your C JCL:

• On the EXEC statement, change the name of your compiler to CWPZMAIN and add the following
to any existing C compiler options:

LANGUAGE(compiler version)

Refer to the Compuware Shared Services User/Reference Guide for a list of the compiler versions that can
be specified with the LANGUAGE command. The default compiler for C is the compiler currently
in use on your system.

Note: The LANGUAGE command may be specified in the CWPPRMO command stream rather
than on the EXEC statement.

• Add the ECC SLCXLOAD DSN to the STEPLIB or JOBLIB concatenation if it is not in the link list.

• Add the CWPDDIO DD statement to specify the name of the source listing DDIO file you will be
using. The source listing DDIO file may be in standard DDIO, shared directory, or database
format.

• Determine the language processor options you will use as input and add them to the EXEC
parameter, or add a CWPPRMO DD statement that points to the appropriate options. Sample
options are contained in SLCXCNTL sample library member CXLPC to provide the smallest
output to the source listing file (for minimizing space). If you use these options, and you will be
using the C language preprocessor, add LANGUAGE(xxx) to the EXEC PARM or to the CWPPRMO
DD statement.

Refer to the Compuware Shared Services User/Reference Guide for more information on this JCL and C
language processor options.

Post-processor
You can use the post-processor to process compile listings that were previously stored, or you can
modify your C compile JCL to pass the compiler listing to the post-processor as described below.

• Check the C compiler options.

130 Enterprise Common Components Advanced Configuration Guide

• Change the C compile JCL to write the compiler listing (SYSCPRT) to a sequential file for use as
input to the C language post-processor. A sample of the necessary JCL is shown below.

//SYSCPRT DD UNIT=SYSDA,SPACE=(CYL,(100,10)),
// DCB=(RECFM=VB,BLKSIZE=16096),
// DISP=(MOD,PASS)

For more information on C language processor JCL, see the “C Language Processor” chapter in
the Compuware Shared Services User/Reference Guide.

The above example is a temporary file. You can save the JCL as a permanent file to be reused as
shown in the example below:

//SYSPRINT DD DSN=CX,STORED.LISTINGS(MEMBER)

• The SYSPRINT file will be LRECL=133, RECFM=FBA.

• Add SLCXCNTL sample library member CXC as the post-processor step following your C compile
step. CXC can be customized to meet your site’s requirements.

Note: The CWPLOAD file must be allocated using DISP=OLD or DISP=SHR.

• The object module that is processed by the post-processor must be used as input to the linkedit
step.

See the Compuware Shared Services User/Reference Guide for more information on this JCL and C language
processor options.

Configuration Parameters
Default member: CSSALL

ESS
Description: The ESS, Embedded Source Support, command controls whether the source is embedded in
the program object or not.

Values: NO|YES

NO specifies the source listing to not be embedded in the program object.

YES specifies the source listing to be embedded in the program object.

Default: NO

Required: no

The default parmlib member override DD card must be included in the pre-/post-processor
JCL to access the Embedded Source Support functionality in CSSALL:

//PMCXALL DD DUMMY
Compuware Shared Services Configuration and Administration 131

On-the-Fly Language Processing Support

This section describes CSS support for on-the-fly language processing, invoked by the Abend-AID
Viewing Server.

CXOTFPRE & CXOTFPST Examples

CSS on-the-fly language processing support is performed by calling one of two CLIST members,
CXOTFPST (postprocessing CLIST) or CXOTFPRE (preprocessing CLIST). The Abend-AID Viewing
Server will invoke these from the "Source Support Utilities Menu" panel: selecting option "1" invokes
CXOTFPRE, selecting option "2" invokes CXOTFPST.

To provide a complete demonstration of on-the-fly language processing support, Compuware has

supplied two examples, complete with corresponding members (CLIST, PANEL, HELP, Skeleton). It is
an actual working example that uses CA-Endevor as the source code and/or source listing repository.

Although the supplied sample is specific to CA-Endevor, any user-coded CLIST, REXX and/or program
may be called as long as it conforms to the ISPF rules for program invocation. Refer to the following
IBM ISPF manuals for more information about these APIs:

• SC34-4821-01 — ISPF Dialog Developer's Guide and Reference

• SC34-4819-01 — ISPF Services Guide

Supplied is the following

Table 8.

CLIST name Additional members Use

CXOTFPST P@CPST01 Language Postprocess dialog and panel
P@HPST01 Help Panel
CXSPST01 Skeleton Member
CXOTFPRE P@CPRE01 Language Preprocess dialog and panel
P@HPRE01 Help Panel
CXSPRE01 Skeleton Member

The sample panel below (Figure 20), is a language postprocessing example (CA-Endevor P@CPST01). A
similar panel (not shown) is distributed for language preprocessing (P@CPRE01).
132 Enterprise Common Components Advanced Configuration Guide

Figure 20. Language Postprocessing Example for CA-Endeavor

Sample ----------- Retrieve Compiler Source Listing & Post-Process 


Command ===> 

1. Retrieve a Compiler source listing from Endevor 
2. Generate JCL to Compuware LP Post-Process this Compiler source 
listing into a Compuware Source Listing format 
3. Invoke EDIT to allow changes. Enter SUBMIT in EDIT when complete. 

ENDEVOR Information: 
ENVIRONMENT ===> AA ELEMENT ===> COMP5 
SYSTEM ===> SAMPLE TYPE ===> COBSRC 
SUBSYSTEM ===> COBOL STAGE ===> 1 
DATA SET NAME ===> COMPWARE.AAOTF.COBSRC 

Compuware Post-Process Information: 
STEPLIB ===> COMPWARE.ECC15.LOADLIB 
CWPDDIO ===> COMPWARE.LE.LST 
CWPPRMO ===> COMPWARE.ECC15.SLCXCNTL(CXLPCOBB) 

JOBCARD Information: 
Line 1 ===> //JOBNAME0 JOB ('ACCOUNT,DEPT'),'User name', 
Line 2 ===> // CLASS=L,MSGCLASS=R,NOTIFY=&SYSUID

Method of Operation
Data to be entered on these panels is presented in three parts:

1. CA-Endevor specific. Information is exactly as needed on a foreground execution of CA-Endevor.

2. Compuware Postprocess specific. Information needed to customize execution of a language
postprocess.
3. JOBCARD orjob specific information. Needed to submit JCL to an internal reader.

All input is as-is in this example (that is, all data is taken exactly as entered and formatted for job
execution). Because this is a sample, you can modify any of these CLISTs, panels, etc. (see Figure 20)
to suit your individual needs.

At termination of the panel, the data entered will be:

1. Merged with a JCL skeleton.

An ISPSLIB PDS must be available at viewing time containing the Compuware-supplied skeletons
or those that the user has modified. This PDS can be an existing ISPSLIB used site-wide and
allocated at TSO logon, or it can be one that is allocated dynamically at viewer startup time. Refer
to the previously mentioned ISPF manuals for more details on customizing skeletons.

Note: The CXSPRE01 skeleton supplied must be modified to specify the desired language and compiler
library to be used.

2. ISPF EDIT will be invoked to allow user changes

3. JOB submission, via use of the “SUBMIT” command in ISPF EDIT.

Refer to the documentation in the Compuware-supplied CXOTFPST CLIST for additional technical
details. A similar CLIST, named CXOTFPRE, is also supplied for a language preprocess.
 133

Appendix A: Security Considerations A

Security Considerations for Using the JES Explorer View

The JES Explorer view within the Host Explorer perspective provides a mechanism to view job output,
purge job output, and cancel running jobs. All of these features can be controlled or limited by a
software security product such as RACF or ACF2. In addition, for users that may not have a security
package or are not implementing SYSOUT security rules through their security software, a limited set
of alternative options to control what output can be viewed by Topaz Workbench users are available.

JES Explorer allows for a significant degree of freedom to view any output in the system. This often
occurs when users apply the security settings supplied by the software used to view output on an IBM
3270-type device, such as SDSF or IOF. These security settings apply only to those products and are
not the same as system-wide security settings, which can be implemented using system security
software products, such as RACF, ACF2, or Top Secret. Thus, a setting within SDSF or IOF to limit
allowable viewing only applies to SDSF or IOF, not the system. Alternatively, if the system security
software was used to impose output security, then all attempts to view output are controlled
regardless of the viewing software. Compuware recommends using the available security settings of
the system software security product to impose output security (Options 1 and 2, below).

The next sections discuss the available options for security limitations:

• Option 1: Controlling the ability of users to view output using a security product.

• Option 2: Controlling the ability of users to cancel jobs or output using a security product.

• Option 3: Implementing a basic form of security that limits viewing output when a security
product is not installed or not configured for output control.

Option 1: Limit user’s ability to view output using a security product.

The JES Explorer view allows users to view the output from jobs within the system. Installations
wishing to secure this access and control user access to output can do so by setting the appropriate
profiles for the security class JESSPOOL.

Profiles for JESSPOOL are in the format

Local-nodename.userid.jobname.jobid.dsnumber.name

Using combinations of user IDs and wild card characters, output viewing can be limited on a user ID
or groupid basis as the installation chooses.

For installations that simply wish to invoke basic user-level security for output, where a user is
limited to viewing only their own output, simply activate the JESSPOOL class in their security
software and specify no profiles. User owning-only access is then the default action.

As provided by IBM system action, users are always allowed access to their own jobs or output,
regardless of profiles under JESSPOOL that might seemingly restrict it.

Please consult your installation's appropriate security software administration documentation for
additional information. For RACF installations, controlling access to output via the JESSPOOL class is
documented in the z/OS Security Server RACF Security Administrator's Guide, “Controlling Access to
Spool Data”.
134 Enterprise Common Components Advanced Configuration Guide

Option 2: Limit user’s ability to cancel jobs or purge output using a security
product.
The JES Explorer viewer provides a mechanism for Topaz Workbench users to purge job output as well
as cancel jobs that are in execution. These types of requests cause a JES2 $CJ cancel command or a
JES3 MODIFY command to be issued to the system in order to honor the request. Installations
wishing to secure or limit what can be canceled can do so by setting the appropriate JES2.CANCEL.*
or JES3.MODIFY.* profiles for the security class OPERCMDS using the security software package in use
on their system.

These are the only command types that JES Explorer will issue.

Please note that setting specific OPERCMDS profiles only restricts a user's ability to issue the
command itself (the user is either permitted or denied to issue the command); there is no control for
which jobs can be canceled nor output be purged. In order to control a user's ability to cancel
specific jobs or output, you must use OPERCMDS profiles that allow the commands above to be
issued in conjunction with appropriate JESSPOOL profiles that allow ALTER access to the jobs
identified by the profiles.

As provided by IBM system action, users are always allowed access to their own jobs or output,
regardless of profiles under JESSPOOL that might seemingly restrict it. Further, users are always
permitted to cancel their own jobs or purge their own output (if OPERCMDS profiles allow it) even if
no JESSPOOL profiles exist that would give the user ALTER access to the resource. A JESSPOOL profile
with ALTER access would be required for a user to cancel a job or purge output that he does not own.

Installations that are using output viewing software such as SDSF or IOF probably already have
OPERCMDS properly set to allow JES2 $CJ or JES3 MODIFY commands to be issued by general users,
so that they can purge their own output.

Installation may also choose to use conditional access profiles to control whether JES Explorer users
can issue JES2 $CJ or JES3 MODIFY commands to cancel a job or purge output. Conditional access
may allow for use of some existing security rules already in place — by using the
WHEN(CONSOLE(name)) conditional in your security software in conjunction with the
CONSOLEPOE statement in the CSS TP Configuration section of the HCI00 Parameter member. The
CONSOLEPOE statement allows a pseudo-console to be named that is also defined to the CONSOLE
security class to be designated as a security port-of-entry. The pseudo-console name is tested by the
WHEN conditional clause (if present) in profiles for JES2.CANCEL.* and JES3.MODIFY.* when JES2
$CJ or JES3 MODIFY commands are issued. The console name used in CONSOLEPOE and defined to
the CONSOLE security class can be a new name with new conditional profiles designed solely for that
console, or the name can specify an existing CONSOLE class member, such as SDSF. Installations
desiring to use conditional access should refer to the CONSOLEPOE statement in the TP
configuration section, as well as the section below titled Using Conditional Access for Canceling
Jobs or Purging Output via JES Explorer.

Please consult your installation's appropriate security software administration documentation for
additional information. For RACF installations, controlling access to system operator commands
using the OPERCMDS class is documented in IBM’s z/OS Security Server RACF Security Administrator's
Guide, in the section entitled “Administering the Use of Operator Commands”.

Option 3: Limit user's ability to view only their own output (no security
product setup required).
Within the Compuware Shared Services (CSS) TP Configuration section of the HCI00 Parameter
member, there is a configuration setting that can be used to allow the installer to impose a “by-
userid” level of security when viewing output within the JES Explorer. This setting is the SYSOUT
configuration statement.

This optional setting causes any attempts to view output by users to be denied unless they are the
owning user ID. This means that no user can view any other user's output, except for their own.
Appendix A: Security Considerations 135

To enable the setting, specify the keyword BY-USERID in the SYSOUT statement. This enables the by-
userid security. Otherwise, the setting is set to DEFAULT, which means that the rules of your
installation's security software profiles and the JESSPOOL resource class dictate the handling of
output. Compuware recommends using the JESSPOOL resource class and your security software for
the best and most flexible security arrangement that meets your installation's requirements.

Note that a setting of BY-USERID does not override any rules enforced by your security software. Any
rules in place that are more restrictive than by-userid security will continue to be enforced by your
security software.

Using Conditional Access for Canceling Jobs or Purging Output via JES
Explorer
The TP Configuration section provides an optional statement parameter which gives the TP the
capability to name a console which is also defined to your system security software in the CONSOLE
class. This console name is used to issue JES cancel and purge commands on behalf of Topaz
Workbench as a security port of entry (POE). Use of the CONSOLEPOE statement provides a
mechanism for installations to use conditional security rules to control which users or groups may
issue commands to the system via the WHEN(CONSOLE(console-name)) clause in security profiles.

The HCI Parameter member is pointed to by the //CWPARM DD statement in your HCI start-up JCL.

The CONSOLEPOE statement, if coded, can be used to specify a console name under which system
commands will be issued. These system commands are issued by the JES Explorer for the purposes of
purging job output or canceling active jobs. Security rules at some installations require a console
name as a port of entry in order to validate the authority of the command. At present, Topaz
Workbench only issues $CJ commands (JES2) or *MODIFY J=,C commands (JES3).

The console name specified by the CONSOLEPOE statement may be any name and the console name
chosen must be defined to the system security software as a console in the CONSOLE class. For RACF
users, example statements used to define the console are shown below. The console name may also
be a console already defined to the CONSOLE class, such as SDSF.

The console name chosen should not be the same name an existing hardware console. There is no
physical relationship between the JES Explorer console port of entry name and a real MCS console.

After specifying a CONSOLEPOE statement in your member with an appropriate console name,
restart the HCI. The next time a JES Explorer user wishes to cancel a job or purge output, the
resulting command will be issued under the authority of the named console as a security port of
entry.

This means that security rules in place that specify conditional access, for example the commonly
used WHEN(CONSOLE(SDSF)) syntax, can also be specified with conditional access using the named
console from the CONSOLEPOE statement, for example, WHEN(CONSOLE(CXTP01))

Specifying the CONSOLEPOE SDSF statement in the member would allow Topaz Workbench to issue
commands on behalf of the user with SDSF as the security port of entry, thereby invoking existing
SDSF rules for validating the authority to issue the commands. This means that a duplicative set of
rules similar to those already in place for SDSF need not be created for a console of another name
(such as CXTP01 shown above).

Defining a Console to RACF to use Conditional Access

Defining an SDSF console to RACF is documented in z/OS SDSF Operation and Customization (SA22-
7670), Chapter 6, subsection "Using Conditional Access".

Similarly, to define a console to RACF for the purposes of using a console name such as the CXTP01
example above, your RACF administrator would issue the example commands below. These
commands illustrate how to define a console named CXTP01 to RACF and how to set a rule
permitting a user to issue JES2 Cancel commands via the CXTP01 port of entry.
136 Enterprise Common Components Advanced Configuration Guide

First, activate the CONSOLE class and define the console as a member of the class:

SETROPTS CLASSACT(CONSOLE)

RDEFINE CONSOLE CXTP01 UACC(READ)

SETROPTS RACLIST(CONSOLE) REFRESH

Then, to give conditional access to permit users or groups to issue JES2 Cancel commands only when
using the JES Explorer:

RDEFINE OPERCMDS JES2.CANCEL.* UACC(NONE)

PERMIT JES2.CANCEL.* CLASS(OPERCMDS) ID(userid or groupid) ACCESS(CONTROL)

WHEN(CONSOLE(CXTP01))

SETROPTS RACLIST(OPERCMDS) REFRESH

Please note that the use of the CONSOLEPOE statement in the HCI Parameter member (default is
HCI00) to establish a security port of entry for conditional access to the JES2.CANCEL.* or
JES3.MODIFY.* security profiles only allows a user to issue the necessary command into the system.
Actual execution of the command and the authority to do so against the affected job or job output is
still enforced by JES2 or JES3 and is subject to the security profiles of the JESSPOOL class.

Controlling User Ability to View SYSLOG from JES Explorer

Options are available for controlling access to the system log dataset (SYSLOG) from JES Explorer. The
SYSLOG statement in the TP Configuration File member is used to control this capability for JES
Explorer. The format and options of the SYSLOG statement are detailed in Topaz Workbench—CSS TP
Parameters.

Controlling viewing access of the system log involves security profile rules, which may already exist
on your system. Access to viewing may simply be a matter of using those rules for the JES Explorer to
follow. However, if rules do not exist, they can be created and then specified in the TP Configuration
File member.

The SYSLOG statement can be used to direct JES Explorer to follow SDSF rules or IOF rules. In these
cases, the same rule (used by either SDSF or IOF) is checked by JES Explorer and viewing rights are
permitted (or denied) accordingly. 
For example, if you set the SYSLOG statement to use SDSF rules, and SDSF allows User A to view the
system log dataset, then User A will also be able to view the system log dataset through JES Explorer.
And conversely, if User A does not have viewing rights in SDSF, then the user will also not have them
in JES Explorer. Rules for IOF work similarly.

Whenever an SDSF user attempts to view the system log, SDSF validates the user's access rights
against a profile named ISFCMD.ODSP.SYSLOG.JESx, where x is either 2 or 3 (representing either
JES2 or JES3 systems) in the SDSF security class. If a user or group has READ access to that profile,
SDSF allows viewing rights. JES Explorer follows this same SDSF rule provided you configured a rule
choice of SDSF on the SYSLOG statement. More information about the SDSF profile for system log
access can be found in the IBM publication SDSF Operation and Customization (SA22-7670).

Using IOF is similar to using SDSF as described previously, however the IOF profile name must be
determined by reviewing your IOF installed settings and referring to the IOF TSO Installation Guide,
within the “Access Control Reference” chapter. Once determined, specify the IOF profile name on the
SYSLOG statement in the configuration (along with a rule choice of IOF). Using IOF as the rule also
requires specifying the associated security class name, which can be determined by inspecting IOF's
A60ACF install settings member.

Both the SDSF and IOF rule choices simply determine whether or not a given user has the right to
attempt to access and view the system log. If the attempt is permitted, then JES gets involved and
further checks a user's access authority for the physical system log dataset residing on the spool
Appendix A: Security Considerations 137

before any system log records are returned. This means that the user or group must also be permitted
access via a profile in the JESSPOOL security class. The profile name is defined by IBM to be:

system-name.+MASTER+.SYSLOG.*.*

Regardless of the rule choice chosen in the SYSLOG configuration statement, the JESSPOOL profile
must allow the user or group to have access before they will be permitted to view the system log. In
most cases if a user can view the system log via SDSF or IOF today, then the JESSPOOL profile for
system log access is already set properly and does not need to be adjusted.

More information about protecting the system log dataset (SYSLOG) can be found in the IBM
publication z/OS Security Server RACF Security Administrators Guide (SA22-7683), within the “Providing
Security for JES” chapter. If you are using security software other than RACF should consult the
appropriate documentation pertaining to securing JES.

Controlling User Ability to Issue System Commands

The SYSCMD statement in the TP Configuration File member is used to access and permit users to
issue system commands from Topaz Workbench—including JES commands, MVS operator commands,
or any command that could be issued from a z/OS console. The format and options of the SYSCMD
statement are detailed in Topaz Workbench—CSS TP Parameters.

The SYSCMD statement can be used to disable access entirely, such that Topaz Workbench users
would not be able to issue commands into the system. However, many sites have groups of users
authorized to issue limited system commands from a console that you may wish to extend to Topaz
Workbench.

If command capability is to be permitted, then several choices exist for how you may wish to verify
that a given user has the proper authority to issue commands. All of them involve security profiles
that may already exist on your system, and permitting commands to be issued by Topaz Workbench is
simply a matter of specifying which rules you want Topaz Workbench to follow. If rules do not
currently exist, they can be created and then specified in the TP Configuration File member so that
Topaz Workbench will follow them.

Many z/OS installations use a TSO-based application, such as SDSF or IOF, to permit issuance of some
commands into the system. Both of these applications are capable of validating that a TSO user has
permission to issue commands (or not) by checking a security profile. The SYSCMD statement can
specify which type of rules Topaz Workbench should follow (for example, SDSF, IOF, or system rules).
Regardless of what rule type is configured, the rule itself will be checked by Topaz Workbench and the
command may or may not be issued depending on the result of that check. For example, if you
specify on the SYSCMD statement that you want Topaz Workbench to follow SDSF rules and SDSF
allows User B to issue system commands, then User B will also be able to issue commands using Topaz
Workbench. If User B does not have command authority rights in SDSF then User B will also not have
them in Topaz Workbench. Rules for IOF work similarly. The system's rules refer to the operating
system validation of a profile in the OPERCMDS class prior to executing the command.

Whenever an SDSF user attempts to issue a system command, SDSF validates the user's access rights
against a profile named ISFOPER.SYSTEM in the SDSF security class. If a user or group has READ
access to that profile, SDSF allows the command to be issued into the system. Topaz Workbench will
follow this same SDSF rule if you specify a rule choice of SDSF on the SYSCMD statement in the
configuration. More information about the SDSF profile for system commands can be found in the
IBM publication SDSF Operation and Customization (SA22-7670).

IOF functions the same way, however the profile name is determined by reviewing your IOF installed
settings and referring to the IOF TSO Installation Guide, within the “Access Control Reference”
chapter. Once you determine the correct profile, specify the profile name on the SYSCMD statement
in the configuration along with a rule choice of IOF. Using IOF as the rule choice also requires that
the security class name being used by IOF be specified; this can be determined by inspecting IOF's
A60ACF install settings member.
138 Enterprise Common Components Advanced Configuration Guide

Both the SDSF and IOF rule choices simply determine whether or not a given user has the right to
attempt to issue a command into the system. If the attempt is permitted then the operating system
gets involved and checks a user's access authority for the specific command submitted. This means
that the user or group must also be permitted authority to issue the command via a profile in the
OPERCMDS security class. Typical profile names are defined by IBM to be:

subsystem-name.command.[qualifier]

For example:

MVS.MODIFY.STC.*
JES2.DISPLAY.*

Regardless of the rule choice chosen in the SYSCMD configuration statement, the OPERCMDS profiles
must allow the user or group to have access before the command will be permitted to execute. In
most cases if a user can currently issue the command from SDSF or IOF today, then the OPERCMDS
profile for command issuance is already set properly and does not need to be adjusted.

It is important to understand that the settings on the SYSCMD configuration statement do not affect the
ability of the user to cancel jobs or job output from JES Explorer. The SYSCMD setting only pertains to those
commands that a user can physically type in the actual command text and then attempt to have the
command issued. Cancel commands issued by JES Explorer are generated internally depending on specific
action by the user; the user is not allowed to type the command text or job number for this purpose.
Control of JES Explorer cancel commands is controlled by the options described in Security Considerations
for Using the JES Explorer View and Using Conditional Access for Canceling Jobs or Purging Output via JES
Explorer.

More information about protecting system operator commands can be found in the IBM
publication z/OS Security Server RACF Security Administrators Guide (SA22-7683), within the “Protecting
General Resources” chapter, in subsection “Administering the Use of Operator Commands”. If you are
using security software other than RACF should consult the appropriate documentation pertaining to
securing JES.

CXSS0000 Started-task Procedure Security Considerations

When using the CXSS0000 started-task JCL procedure (used by File-AID/Eclipse, Strobe, and CA-
Endevor support for Topaz Workbench), the system's security software must be set to allow for the
jobname of the CXSS0000 procedure to increment sequentially for each invocation of a new started-
task.

Each time a Topaz Workbench user initiates a new File-AID session or a CA-Endevor session, a started-
task will begin execution. It will be assigned a jobname that corresponds to the task number of the
user's session with HCI. For example, CXSS0001, CXSS0002, CXSS0003,…,CXSSnnnn.

Some installations use physical jobnames in their system security settings to place into effect
restrictions or authorizations based on these jobnames. As a result, the system security settings must
allow for the jobnames of the CXSS0000 started-tasks to range from CXSS0000 - CXSS9999. If your
security requirements enforce the use of jobname restrictions, it is suggested that a wild-card
arrangement be specified, such as CXSS* in the system security settings to allow for the full range of
possible jobnames that could be generated.

When the procedure is started by the HCI, the procedure is assigned to the default security user ID on
the system (for example ++++++++ on RACF systems). The default security user ID may not have
authority to access the datasets specified in the procedure JCL. Therefore, READ access to these
datasets must be provided in order for the procedure to successfully begin execution. The two options
available for establishing sufficient access authority are to either:

• Make all of the datasets specified within the CXSS0000 procedure available for READ access by
specifying UACC=READ for each dataset in the JCL. This includes all datasets in the STEPLIB DD
concatenation. This option allows the system default user ID to have READ access to the
Appendix A: Security Considerations 139

procedure's datasets so that the procedure can start up and the configuration file can be
processed.

or

• Add the name of the start-up procedure to an STCGRP security class as appropriate for your
security software and define all of the datasets specified in the procedure JCL as belonging to the
STGGRP with READ access. This option causes the procedure to start up with the authority of
STCGRP and therefore can read and process the procedure's datasets.

Once the procedure successfully begins execution, the initiating user ID (the user ID associated with
the Topaz Workbench session that caused the procedure to get started) is authenticated and the
procedure will execute under the security rules in place for that user ID and not the rules of the
default system user ID or STCGRP. Providing READ access to the STEPLIB dataset (whether via
UACC=READ or STCGRP) does not allow individual users more or less security than they had before.

SSAS Security Considerations

You may wish to add the name of the start-up procedure to the STCGRP security class as appropriate
for your security software. Otherwise, when the SSAS starts, it uses the default security level on your
system. This does not prevent SSAS from normal operation because each user request for services runs
under the security rules of that user. However, whether you add the procedure name to STCGRP or
not, all the load libraries specified within the procedure must have system-wide read access.

Normally, Compuware recommends that the Shared Services load library not be APF-authorized. The
SSAS is designed to run without any need for APF-authorization. However, if your installation
normally places the Shared Services load library in the system link list, the contents could become
APF-authorized when executed from a link list search. In order to ensure that the SSAS runs non-
authorized, you should specify the Shared Services load library in the start-up procedure’s STEPLIB
DD so that the system link list does not get searched during SSAS start-up. Further, if the Shared
Services load library is APF-authorized for other reasons, the SSAS operates correctly.

Cross-LPAR Copy Security Considerations

Cross-LPAR Copy (the Copy To… feature in Topaz) has some extra security considerations.

• If TCP_ACEE parameter is set to USER, any user seeking to use this functionality will need to
have a fully defined OMVS segment.

• If TCP_ACEE parameter is set to HCI, the HCI's OMVS segment will be used for communications
and users without an OMVS segment will be able to complete cross-LPAR copies.

Controlling User Access to the CSS TP for Topaz Workbench

Connection Port
The CSS TP is the entity and programming logic executing inside the HCI address space that services
requests on behalf of the Topaz Workbench clients for access to z/OS resources. The TP authenticates
user access by requiring that the Topaz Workbench client user provide a user ID and password which
will be validated by the system security software (RACF, ACF2, Top Secret, etc). If authentication is
successful, then the user has the same access rights to z/OS resources as he would have if he had
logged on to TSO on the same z/OS image.

Some installations may wish to limit access for certain users or groups to the CSS TP even though
those users may have TSO access. Installations may have TSO security exits in place that restrict
access to TSO or to resources accessible by TSO, and they find that the CSS TP allows too much
freedom based on user ID and password authentication alone.
140 Enterprise Common Components Advanced Configuration Guide

Installations may choose to optionally invoke application level security support within the CSS TP in
order to limit which users or groups can access the HCI port(s) that invoke the CSS TP when a user
attempts to connect to the port.

Application Level Security

System security software can control access to applications by the use of an application name. The
application name is a one to eight character name that is determined by the installer or security
administrator. The application name is added to the security database as a profile in the APPL security
class. A possible suggested name for the application is the TPNAME, for example "CXTP01".

The security administrator then assigns one or more user IDs and/or groups to have READ access to
the application name profile.

The application name is correspondingly made known to the CSS TP via the TP Configuration File
section, using the APPLICATION statement within the member. This statement allows the CSS TP to
know the application name defined to the security software.

When the APPLICATION statement is specified in the TP Configuration File member, the CSS TP will
request that the system security software validate that the user ID attempting to sign-on to the port
has access to the application name. If the user has access to the application, use of CSS TP services is
permitted and the session continues. If the user does not have access, the CSS TP connection with the
client is terminated.

If multiple HCIs/ports are in use, a unique application name can be assigned to each port, thereby
permitting or restricting access on a port basis and a user ID basis.

If the APPLICATION statement is not specified in the configuration member, then the CSS TP will not
make a request to the security software to validate application access and only the user ID/password
authentication will be used to determine if the connection is permitted.

Defining Application Access to your Security Software

Please consult your installation's appropriate security software administration documentation for
additional information on how to set up application security. For RACF installations, protecting
applications is documented in IBM’s z/OS Security Server RACF Security Administrator's Guide (SA22-
7683), in the chapter entitled "Protecting General Resources" in subsection "Protecting Applications".

As an example of how to define application access to RACF, the following RACF commands are
presented below to illustrate what is necessary to configure this level of access. In this example, an
application name representing Topaz Workbench production users will be created for this purpose.
The name chosen in this example is WBPROD. Only users and groups defined to have access to the
WBPROD profile will be able to successfully use Topaz Workbench to access the HCI port represented
by this application name.

If you have not already done so, activate the APPL class:

SETROPTS CLASSACT(APPL)

Create a profile in the APPL class and give users or groups permission to access that application:

RDEFINE APPL WBPROD UACC(NONE)

PERMIT WBPROD CLASS(APPL) ID(userid or groupid) ACCESS(READ)

In the TP Configuration File section, specify the APPLICATION statement:

APPLICATION=WBPROD

Then refresh the TP Configuration File or recycle the HCI to make application security take effect.
Appendix A: Security Considerations 141

Note: Running multiple HCIs can have a different application name in the TP configuration for each
port, thereby controlling user access on a port-by-port basis, if desired.

HCI Security Considerations

Top Secret Users
For users of Top Secret for system security, it requires a new facility to be placed in the Facility Matrix
Table. Use the following facility control options:

FACILITY (USER33=NAME=HCI)

FACILITY (HCI=NOABEND, ASUBM, NOAUDIT, AUTHINIT, NOINSTDATA)

FACILITY (HCI=MULTIUSER, PGM=HCI, SHRPRF, SIGN(M), NOTSOC)

FACILITY (HCI=RES, KEY=8, NOXDEF, NOLUMSG, NOSTMSG)

ACF2 Users
The CXSSTC Started Task ID needs to have a GSO definition in the STC table to allow it to start jobs
with a dynamic name.

System Security for the HCI

For the HCI to properly function, it must be permitted access to the following, regardless of whether
it is a started-task or a submitted job:

• All libraries in the STEPLIB concatenation must be Authorized

• HCI PARMLIB dataset containing HCI Server Activation Facility members

The HCI must be authorized for the following via the MVS system security package:

• To generate SDUMPs. If DMPPFX=SDUMP has been specified (the SDUMP specification is

recommended by Compuware)

• To output submitted jobs via an internal reader

• For operator commands with update authority:

– START

– STOP

– CANCEL

– MODIFY (if OPCMD=MODIFY has been specified)

Considerations for Using AT-TLS

AT-TLS can provide increased security of data transmissions by encrypting transmissions using
SSL/TLS. This section serves to identify a few considerations when configuring AT-TLS policy. AT-TLS
does not require any changes to HCI or CSS TP. AT-TLS is application transparent, thus Topaz
Workbench can communicate on AT-TLS secured ports.

Using AT-TLS is optional. If a higher level of data security is required by your installation, then you
must configure any AT-TLS policies describing which ports will be secured and specific security
142 Enterprise Common Components Advanced Configuration Guide

information regarding the encryption key. Configuring AT-TLS policies can be complex and beyond
the scope of this manual. Full AT-TLS configuration documentation is supplied by IBM.

When a port is secured using AT-TLS, the port should be secured for inbound and outbound
connections. While a port secured for inbound-only traffic will operate correctly for Topaz
Workbench connections, an outbound definition is also required if you intend to use the Cross-LPAR
Copy feature or for Xpediter debugging over secure ports. These mainframe-based features initiate
outbound connections to the HCI port; hence, the port should be configured for inbound and
outbound.

Figure 21 shows the policy configuration statements in use on Compuware's system. Port 46806 is
defined as a secure port for both inbound and outbound connections. In addition, some screen shots
of the policy agent configuration utility are shown, which may be of assistance. For full AT-TLS
documentation and configuration information, please consult your IBM documentation: z/OS
Communications Server IP Configuration Guide (SC31-8775); refer to the chapter titled “Application
Transparent Transport Layer Security Data Protection”
Appendix A: Security Considerations 143

Figure 21. Policy configuration statements

##
## AT-TLS Policy Agent Configuration file for:
## Image: CW06
## Stack: TCPIP
##
## Created by the IBM Configuration Assistant for z/OS Communications Server
## Version 1 Release 12
## Backing Store = Z:\Configuration Assistant\attls
##
## End of Configuration Assistant information
TTLSRule Topaz_Inbound_46806~1
{
LocalAddr ALL
RemoteAddr ALL
LocalPortRangeRef portR1
RemotePortRangeRef portR2
Direction Inbound
Priority 255
TTLSGroupActionRef gAct1
TTLSEnvironmentActionRef eAct1~Topaz_CW06_Inbound
TTLSConnectionActionRef cAct1~Topaz_CW06_Inbound
} 
TTLSRule Topaz_Outbound_46806~2
{
LocalAddr ALL
RemoteAddr ALL
LocalPortRangeRef portR2
RemotePortRangeRef portR1
Direction Outbound
Priority 254
TTLSGroupActionRef gAct1
TTLSEnvironmentActionRef eAct2~Topaz_Outbound
TTLSConnectionActionRef cAct2~Topaz_Outbound
} 
TTLSGroupAction gAct1
{ 
TTLSEnabled On
Trace 3
} 
TTLSEnvironmentAction eAct1~Topaz_CW06_Inbound
{ 
HandshakeRole Server
EnvironmentUserInstance 0
TTLSKeyringParmsRef keyR1
}
TTLSEnvironmentAction eAct2~Topaz_Outbound
{ 
HandshakeRole Client
EnvironmentUserInstance 0
TTLSKeyringParmsRef keyR~CW06
} 
TTLSConnectionAction cAct1~Topaz_CW06_Inbound
{ 
HandshakeRole Server
TTLSCipherParmsRef cipher1~Default_Ciphers
TTLSConnectionAdvancedParmsRef cAdv1~Topaz_CW06_Inbound
CtraceClearText Off
Trace 3
} 
TTLSConnectionAction cAct2~Topaz_Outbound
{ 
HandshakeRole Client
TTLSCipherParmsRef cipher1~Default_Ciphers
TTLSConnectionAdvancedParmsRef cAdv2~Topaz_Outbound
CtraceClearText Off
Trace 3
} 
TTLSConnectionAdvancedParms cAdv1~Topaz_CW06_Inbound
{
HandshakeTimeout 30
CertificateLabel cw06
SecondaryMap Off
144 Enterprise Common Components Advanced Configuration Guide

}
TTLSConnectionAdvancedParms cAdv2~Topaz_Outbound
{
HandshakeTimeout 30 
SecondaryMap Off 
}
TTLSKeyringParms keyR1
{ 
Keyring /etc/cw06.kdb
KeyringStashFile /etc/cw06.sth
} 
TTLSKeyringParms keyR~CW06
{ 
Keyring /etc/cw06.kdb
KeyringStashFile /etc/cw06.sth
} 
TTLSCipherParms cipher1~Default_Ciphers
{
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA
} 
PortRange portR1
{ 
Port 46806
} 
PortRange portR2
{ 
Port 1024-65535
} 