ISPW Technical Reference Guide

ISPWTechnical Reference Guide

Release 17.02

ii ISPW Technical Reference Guide

Please direct questions about ISPWor 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 1984 - 2017 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.

ISPW, ISPW Deploy, and FrontLine are trademarks or registered trademarks of Compuware Corporation.

CICS, CICS TS, DB2, IBM, IMS, MVS, MVS/ESA, OS/390, RACF, VTAM, and z/OS are trademarks or registered trademarks of International Business Machines Corporation.

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. OCT2017

September 28, 2017

https://go.compuware.com/

iii

Contents

Chapter 1. ISPW System Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1ISPW System Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1

ISPF/TSO Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1Started Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1DB2-based Meta-data Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2ISPF Data Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2Code Repository Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2Connection Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2External Call Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2ISPW Structure Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

Multiple ISPW Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3Having More Than One ISPW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3Dataset Allocations for ISPW Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4Allocations Definitions Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4Concatenation of Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4Site-Specific Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5Updating the ISPW Base Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5Invocation of ISPW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5

Chapter 2. Terms and Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Organization Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1Work Management Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3Component Type Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3Component Type Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Cycle Component Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5Generate Component Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6Non-Cycle Component Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

ISPW Repository Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Chapter 3. Maintenance Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Introduction to Maintenance Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1Reference Data Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2

Active Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3Reference Data Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5

R – Reference Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5AD – Application Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11AD (S,L) - Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13AD (N) - Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-16AD (F) - Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18AD (P) - Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21AD (T) - Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24AD (A) - Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-27AP – Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-29AR – Approval Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31BC – Base Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33CC – Component Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-35CT – Component Type Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-36EC – Extension Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-40ER – External References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-42M.ER Supplied Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-44

iv ISPW Technical Reference Guide

EX – Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46ST – Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49

Support Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-51AN – Approver Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-51CH – Change Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-52CR – Component Reference Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53ET – Extension Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-54GX - Component Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-55P – Container Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-56SC – Set Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-57SM – Server Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-58SV – Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-59U – User Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-61WH – Warehouses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-63WP – Warehouse Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-66

General Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-68C – Comment File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-68CO/CZ – Commands “O”/ “Z” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-68

Z – Generate Parameters Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-69

Chapter 4. Generate Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Generate Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Generate Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Permanent Generate Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Generate System Customization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Components of the Generation System . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Reference Data Aspects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Customizing Generate Panels and Skeletons . . . . . . . . . . . . . . . . . . . . . . 4-7Parts Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Customizing Generate Parms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12Generate Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14Compile User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Chapter 5. Custom Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Custom Dialog Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Defining ISPW Custom Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Functioning of ISPW Custom Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1ISPF Panels Still Needed—For Now . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Dialog Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Dialog ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Dialog Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Dialog Title. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Dialog Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Field ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Dialog Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Using the Dialog Editor to Create a Custom Dialog . . . . . . . . . . . . . . . . . 5-3

Chapter 6. Exit Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1How Exit Processing works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Chapter 7. Set Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1Set Overview and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

What is a Set? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1Starting Sets on Other LPARs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Approval Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4Change Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5

v

Set Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-5

Chapter 8. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1Preparing for Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2

Defining a SAF Class for ISPW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2Defining Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2

Server Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2Previewing Security Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3

Chapter 9. Extension Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1What is Extension Data? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1

What is an Extension Class? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1Defining Extension Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2

Define the Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2Add extension data to an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2Use Export/Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3

Using Extension Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3Where can it be used? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3How to retrieve it. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3Reference Data Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-4

Chapter 10. Component Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1Component Group Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-1

Defining a Component Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-1Define External Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3

Create the M.EX entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3External Processing Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3

What is an EPR?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3

Chapter 11. Component Warehouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1Component Warehouse Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1Warehouse Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1

Warehouse Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1Warehouse Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-2

What should go into Warehouses? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-2Warehouse Set Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3

Dataset Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3Ongoing Support and Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-4

Chapter 12. Component Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1Component Reference Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-1Installation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-3

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-3Parser User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-4

Chapter 13. ISPW Debug and Trace Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1Debug vs. Trace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-1

Debug. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-1Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-1

Interactive Debug (DBUG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-1Turning Debug on for Set Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-3Tracing Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-4Trace Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-5Trace Output Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-6Turning Trace On/Off. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-7Client/Server Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-8Operator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-9

vi ISPW Technical Reference Guide

Chapter 14. Application Load Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1Why is it required?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

Load Utility Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2Option M.AL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3Step 1 – Define Application Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4Step 2 — Identify Application Components. . . . . . . . . . . . . . . . . . . . . . . . . . 14-6

Objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6Step 3 – Exits and Special Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7

WZUALO – Override Exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-8WZUALX – Load Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-8WZUALG – Generate Parameters Exit . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10

Step 4 – Review Load Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11Step 5 – Load Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12Step 6 – Load Generate Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14Option C – Cleanup Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15

Chapter 15. Setting Up Warehouses for Topaz for Total Test Assets . . . . . . . . . 15-1Topaz for Total Test File Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1Defining a Warehouse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

Chapter 16. Advanced Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1Non-Generating Binary Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1

Accessing Non-Generating Binary Components . . . . . . . . . . . . . . . . . . . 16-1Creating a Non-Generating Binary Component Type . . . . . . . . . . . . . . 16-1

Chapter 17. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1ISPW Support Versus ISPF Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

Things to watch out for: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1Recommendation: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

ISPW Support Versus Other Program Products. . . . . . . . . . . . . . . . . . . . . . . . 17-1Things to watch out for: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1Recommendation: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

Upgrades to Compile Procs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2Recommendation: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2

Multiple Component Types Using the Same Libraries . . . . . . . . . . . . . . . . . . 17-2

Appendix A. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Objects and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Defined Objects and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Variable Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Access Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2SERVER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2ASGNMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2RELEASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3CHGTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4TASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4AG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5REFDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5GENSUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5DPLYREF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6DPLYREQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7Example 1 – No Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7Example 2 – Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8

vii

Appendix B. Reference Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1REXX Call format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-1

Appendix C. Generate Process for Previous Versions . . . . . . . . . . . . . . . . . . . . . . C-1Generate Processing Overview for versions 4.2 and Older . . . . . . . . . . . . . . . C-1Where are Generates Performed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1Generate Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3

Generate Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3

viii ISPW Technical Reference Guide

1-1

Chapter 1.

1ISPW System Description Chap 1

This chapter describes the general underlying structure of the ISPW system, including its components and the data it generates

Topics Covered• ISPW system structure

• How does ISPW relate to your working environment?

• How are the various ISPW components organized?

Prerequisite Knowledge

Since this chapter looks at the general structure that's behind the scenes, it is assumed that you have already read the ISPW User Guide or are familiar with the basic functionality of ISPW and its overall structure. This chapter is important to understanding the rest of the chapters in this reference guide.

ISPW System StructureAn ISPW Environment consists of an unlimited number of client processes communicating with a single server process. It is composed of the following main types of components:

• ISPF/TSO Client

• Started Tasks

• DB2-based Meta-data repository

• ISPF Data Tables

• Connection Definition

• Code

• Repository datasets

• External Call Interface (ECI)

• Web

• Services

The parameters kept in the meta-data repository and data tables control ISPW processing. Some of these parameters are set up at installation time. Other parameters are filled in as Administrators and Users work with ISPW.

ISPF/TSO Client

ISPW utilities ISPF as its dialogue manager. An ISPF dialogue consists of REXX, CLISTs, Panels, Messages, Skeletons and Programs.

Started Tasks

ISPW utilities started tasks to provide:

1-2 ISPW Technical Reference Guide

• Secure server which controls all ISPW processing. This is connected to the DB2-based meta-data repository,

• Secure means of communication across S/390 LPARs to a single server, and

• Controlled and secure component processing.

DB2-based Meta-data Repository

ISPW stores the majority of its reference data and component information in DB2. The Server started task is the only task that connects to this repository.

ISPF Data Tables

ISPW uses two ISPF table libraries defined as follows:

• M Tables library contains models and some reference data. Only ISPW support people require update access to these tables. All other Users require read only access.

• O Tables library contains information which must be updated as Users work in ISPW. Everyone who works in ISPW requires update access to these tables.

Code Repository Datasets

ISPW stores historical versions of components in its own repository datasets. An unlimited number of component versions can be stored.

Connection Definition

A connection definition in the form of a sequential file is used to hold the parameters that an ISPW Client needs to connect to the ISPW Server.

External Call Interface

ISPW has an External Call Interface (ECI) that can be used to perform a limited set of ISPW functions via batch processes.

Web Services

ISPW has a J2EE 1.2 standard interface to enable various functions to be done via a browser (e.g., Approvals).

ISPW Structure Diagram

The Figure 1-1 on page 1-3 shows the overall structure.

ISPW System Description 1-3

Figure 1-1. ISPW Structure Diagram

Multiple ISPW Environments

Having More Than One ISPW

The data repository used to manage ISPW is determined by the option chosen from your ISPF/PDF menu. You could have several sets of data repositories if there is a need to have independent operating environments. For example, every site might have one system for production use where all users would normally work. Other environments could be used for staff training or testing new ISPW versions.

Figure 1-2 on page 1-4 represents multiple ISPW environments.

DeveloperWorkspace

ISPFTables

ComponentRepository

ConnectionDefinition

MetadataRepository

WarehouseDirectory

(DB2)

WarehouseDatasets(PDSE)

WebTSO/ISPFClient

ISPW CTSTC (Component

Transport)

ISPW CMSTC (Server)

ISPW RemoteServer (non-MVS)

Eclipse ClientExternal CallInterface (ECI)

ISPW SX STC(Set Processor)

HTTP/J2EEServer with ISPW

Web Services

ISPW CISTC (Comms)

ISPW 17.02Structure

LU 6.2 or TCP/IP

TCP/IP

TCP/IP

TCP/IP

Communication via Cross Memory Services TCP/IP and HTTP

Read

Interface


Figure 1-2. Multiple ISPW Environments

Dataset Allocations for ISPW Clients

The TSO/ISPF Client consists of site-specific and ISPW base datasets. The site-specific datasets should contain any ISPW component that is modified and any new components created by your site.

The ISPF Skeleton WZU@JOB is an example of an ISPW component that must be modified. Compile Skeletons and special technology CLISTs are components created by each site. Though few ISPW components require modification, they must be copied and modifications made to them in your site-specific datasets so that changes to the ISPW base system can be easily identified.

Allocations Definitions Macro

New with ISPW 4.4 is an Allocations Definition Macro, which contains the different dataset allocations. All ISPW clients now use the load module resulting from the assembly and link of this macro for their dataset allocations. This means that any Set or Deploy process (and even ISPW step in a submitted job) will honor the allocations that the ISPW client was started with.

Concatenation of Datasets

All the site-specific datasets are allocated in front of the ISPW base datasets. The dialogue box can then be split into two adjoining pieces, as shown in Figure 1-3 on page 1-4.

Figure 1-3. Concatenation of Datasets

option W option WToption Wx

ISPW dialogue

Production repository with

Connection Definition for production

Server

Testing Training repository

with Connection

Definition for test server

repository with

Connection Definition for

training Server

option Wsite-specific datasets

ISPW base datasets

ISPW System Description 1-5

Site-Specific Datasets

ISPW is used to maintain the site-specific customization, so a development life cycle is set up for the site modifications. Table 1-1 shows the simplest example of this l i f e c y c l e consists of TEST, HOLD and PROD datasets, which can be concatenated in front of the base datasets for the following reasons:

Updating the ISPW Base Datasets

Each site should have its own procedures for maintaining system software and the ISPW base datasets should be treated as such.

Invocation of ISPW

ISPW is invoked as an option on the ISPF menu. As part of the call to ISPW, a parameter is passed that determines the allocations definition to be used. Different ISPW options can be used to control which allocations definition is passed. The correct connection definition should be allocated for the correct ISPW environment.

Table 1-1. Site-Specific Datasets

Concatenation Reason

PROD SITE ISPW BASE Day-to-day production use of ISPW

HOLD SITEPROD SITE ISPW BASE

Acceptance testing of a new ISPW feature. The updated modules would exist in the HOLD datasets. Users doing acceptance testing would change their allocations so that they may work with the updates

TEST SITE HOLD SITEPROD SITE ISPW BASE

Testing of a new feature or release by the ISPW support person. The updated modules would exist in the TEST datasets so that only ISPW support would be affected by the change


2-1

Chapter 2.

2Terms and Concepts Chap 2

This chapter describes terms and concepts used in defining your environment to ISPW.

Organization TermsApplication

In ISPW terms, an Application is what may sometimes be referred to as a system, though we use Application in the more specific sense. The Application is the fundamental structural unit in ISPW. This term is very important because processing is controlled by Application.

The Application code may be related to specific Assignment Prefixes, which make up the first part of the Assignment number and drive how work is divided into work packages for project control. The Application codes may also form a basis for accounting and charge-back. Application codes may be up to four characters. You may already have these codes defined in your charge-back system, or they may exist in your job JCL accounting information.

Examples of Applications are the Payroll Application, the Accounts Payable Application, and the General Ledger.

Stream

Applications must belong to a Stream. Streams provide the configuration scope for a group of Applications. Streams are necessary, as they tell ISPW which Applications are logically related for configuration management purposes. ISPW’s component reference feature looks at relationships between the different components for all Applications within a Stream. The main constraint when grouping Applications into Streams is that the level structure for each Application must be a subset (it could be identical) of the level structure defined for the Stream.

Some organizations may have just a single Stream into which they define their Applications. Other organizations may need to define more than one Stream as they have different groups of unrelated applications.

Application Level

Levels define the paths-to-production hierarchy for an Application.

A Level is a stage in the development-to-production life cycle and defines the path a component version travels on its way to production.

Different Applications can have different level structures.

Figure 2-1 is an example of a typical Application level structure.


Figure 2-1. Level Structure Example

More paths may be defined by adding additional levels as required. However, only one Production level may exist per Application. Levels acronyms are four-character names that are meaningful to a given Application and may vary between Applications. Levels are a component of an Application Definition (option M.AD). See Chapter 3, “Maintenance Functions” for detailed information.

Throughout this manual, the simple cycle path: TEST/HOLD/PROD will be commonly used in examples.

ISPW Change Cycle

This brief overview describes how to use ISPW to update a module through the Change Cycle. We will use the life cycle structure example shown in Figure 2-1.

This picture shows a typical Application change cycle with Production at the top with Development and Troubleshooting legs both funneling into Production. Applications can have any number of legs, but 1 or 2 are the most common.

Modules are checked out from Production into the Update area (either Dev1, Dev2 or Fix as shown here). They are edited, recompiled, and unit-tested until they work, promoted up to the next levels for further testing and authorization, and then promoted back to Production. Typically, Application teams do most of their work in the Development legs, leaving the Fix cycle clear for emergency updates to the Production code.

In ISPW, you work in Assignments that contain all the modules to be updated for a particular piece of work. The steps you go through to update a module are always the same no matter what type of module it is:

C — Checkout the module from production to a TEST level library.

S — Edit the module (invokes different editors depending on module type).

G — Generate (compile/link/bind) the module to the TEST environment if required for the type of module.

P — Promote the module up one level and automatically generates (G) if required.

The source/load files behind the scenes can be any kind of datasets, like PDSs, VSAM files, HFS files or even PC directory files if you're logged on through the ISPW PC interface. ISPW supports about 22 commands. Some like B (browse), CM (compare) and PR (print) work no matter where the module is in the cycle. Others, like S (edit), work only in the TEST environment and give error messages elsewhere.

Terms and Concepts 2-3

Regardless of what type of module it is or what type of library it cycles through, the process is always the same: C, S, G (if required), P, and others. This applies to old style batch systems, CICS, IMS, DB2, Telon, CSP, QMF, IEF or any other type of tool or language that may be supported at your site.

Work Management Terms

Assignment

Assignments are used to keep related component versions together for working on. Each assignment has (among other things) a unique number, description and owner associated with it. Assignments are often used by developers to group components together based upon some logical reason (for example, all components are being changed as part of a specific business request).

Release

Releases are another way of grouping component versions. A Release would normally contain all the component versions which are to be implemented to production at the same time, and this may contain components from different Assignments.

Set

Sets are used to perform an ISPW operation (for example, Promote) against a group of tasks. Set Processing includes a comprehensive Approvals process, and rules can be pre-defined such that these Approvals must be obtained before the Set can be executed. Sets are executed in the background by a separate started task.

Container

A Container is a generic term for an Assignment, Release or Set. On entering ISPW via option “P”, a user’s “Container List” is presented which contains the Assignment, Releases and Sets they are related to.

Task

Tasks are entries in Assignments, Releases and Sets that almost always correspond to component versions. The Task is a logical concept used to manage operations against component versions and for simplicity’s sake can be thought of in that way. We often refer to “Task Lists” in ISPW, which is a list of Tasks in a Container.

Component Type TermsIdentifying Components

Component versions are identified by the Application to which they belong and the Component Type that classifies them. While the Application code controls the physical processing environment including levels and datasets, the Component Type tells ISPW how to process this type of component (for example, Is it to be generated? What technology is it?)

Defining Component Types

Component Types are first defined globally to ISPW and then to the Applications which will use them.


Initial Component Types

When ISPW is installed, a standard set of Component Types is provided. This set is a sample of commonly used ones. For example, COB, ASM, and so forth can be easily expanded to provide support for different technologies within an organization. More Component Type examples are provided for the special technologies in the ISPW Interfaces Guide.

Relating Component Types to Applications

Each Application in ISPW has its own set of valid Component Types defined to it. Part of the definition includes the physical datasets associated with that Application, Component type relationship. When a user wants to add a new component for an Application, they will only be able to choose component types that have been predefined for that Application.

Component Type Domain

Component Types can be grouped together into a Domain. This allows different Component Types to share the same dataset (e.g. a load library), whilst still maintaining component name uniqueness within ISPW. An example might be that a site wants to maintain name uniqueness across COB, ASM and FORT components but allow the same named components between ISPF Panels and Skeletons.

Component Type Class

It is possible to further define a Component Type by Class. The Class allows the same type to be used for different datasets within a single Application.

An example of this would be to have a single Component Type LOAD but have a class of CICS to define a CICS load library and a class of BTCH to define the batch one. Depending upon the generate parameters (e.g. the target environment for a compile), ISPW would be able to determine which class of component type to use, and subsequently place the load module into the correct library.

Commonly Used Component Types

Table 2-1shows a list of suggested values for commonly used Component Types. Other technology-specific values are documented in the ISPW Interfaces Guide.

Table 2-1. Commonly Used Component Types

Component Type Description

ASM Assembler Source

AMAC Assembler Macro

C C Source

CLST TSO CLIST

COB COBOL Source

COPY Copy books

DOC Documentation

FORT Fortran Source

H C Header

JCL JCL

LIST Program Listing

LOAD Program Load

MAN Manual


Associated Component Types

Associations are Component Types that have some relationship with another base Component Type. They are defined to Source Component types (for example, COB, ASM), and are used by ISPW to understand and manage all of the parts of a Component.

Table 2-2shows the four categories of associated Component Types.

Associations are defined as part of an Application Definition (option M.AD). See “Reference Data Options” on page 3-5 for detailed information.

Component Type Processing

Cycle Component Types

Overview

A Cycle Component Type is a component that is promoted through multiple levels in the change process. The levels fall into one of three module environments, as shown in Table 2-3 on page 2-6.

MSGS ISPF Messages

PANL ISPF Panels

PARM Parmlib member

PROC JCL PROC

REXX REXX exec

SKEL ISPF Skeleton

Table 2-1. Commonly Used Component Types

Table 2-2. Associated Component Types

Association Description

Control InformationThis association defines control information required to generate the source Component Type. Link-edit control cards fall into this category.

Generate

This association defines the types of components that are created when the source Component Type is generated (compiled/linked, etc.). This association category includes load modules, DB2 DBRM modules, and any other source or load modules that are produced when the source Component Type is generated

IncludeThis association defines component types that are input to the generation processing of the source Component Type. Copylibs, DCLGENs, and SYSLIBs fall into this association category.

Related

This association defines Component Types which are added to an Assignment automatically when the source Component Type is added. They have the same Task Name and Application as the source Component Type. Related Module Types are used as reminders. They can be deleted from the Assignment if not required. This association category may include documentation items such as DOC (program documentation) Component Type.


Generate Component Types

Overview

A generate component type is a cycle component type with some extra processing added over the top. The most common examples are programs written in a third-generation language such as COBOL or C. A generate component type should be used if the G operation is required to create associated generated components, such as, load modules in either the TEST or HOLD environments to be moved to the PROD environment.

Generate processing parameters are identified for each component type in M.CT. These parameters can be overridden for an application by component type in M.AD. This allows applications to follow different generate rules without having to use different component types.

Non-Cycle Component Types

Overview

A non-cycle Component Type is a component that is updated directly in production and does not go through the TEST-HOLD-PROD cycle. Also, more than one developer can have it in an assignment at one time. Any component types where ‘update in production’ is allowed can be non-cycle types. Only one dataset level is used.

Example

In each assignment, a NOTES task may be added. These NOTES are never promoted to an acceptance area or a production execution area. They are created, updated, and remain in one dataset at all times in the assignment.

ISPW Repository ComponentsDB2 Repository

The DB2 repository stores information about components, versions, assignments, sets, approvals and other data required for ISPW processing.

Table 2-3. Cycle Component Types

Environment Description

TEST

The TEST Environment describes the bottom levels of a change cycle. These are the levels that a component is checked out to or first created in, and are where the developer makes modifications. The bottom level of each “path” is the TEST level. Modifications may be made only in this environment.

HOLD

All levels between the bottom TEST level and the final PROD level are part of the HOLD environment. These are secure levels that a component is promoted through (multiple “hold” levels are supported). It is a protected area that can only be updated via ISPW functions.

PROD

The final level that components get promoted into and which is your actual production component repository is the PROD environment. It is a protected area that can only be updated via ISPW functions and usually only by your Production Control staff.


M Tables

The M tables contain the setup information required to define/maintain ISPW. The ISPW administrator(s) need update access to maintain the tables. All other users should have only read access. See Chapter 3, “Maintenance Functions” for detailed M tables descriptions.

Most of the M tables now reside in DB2 tables. The remaining ISPF tables are:

$CMDOTBL—contains site commands for operations functions.

$CMDZTBL—contains site commands for user functions.

$WZXGENT—model table for the Generate Information tables.

$ZZCPRM—model table for the Permanent Generate Parameters tables.

O Tables

The O tables contain the dynamic operational information that is generated by the users in the day-to-day use of ISPW. Anyone that uses ISPW requires update access to these tables.

These ISPF tables are maintained and updated internally by ISPW routines:

$COMMENT—Defines all the comment files for every Application Group.

<appl>CMPL—Default generate parameters for each Application. Thus the default generate parameters for Application WXYZ would be in table WXYZCMPL.

<R Compile Table>—Table used to pass generate parameters to the R-Compile job.


3-1

Chapter 3.

3Maintenance Functions Chap 3

This chapter describes the ISPW Maintenance functions (Option M from the ISPW Main menu) that ISPW Administrators use to tailor the ISPW environment.

The ISPW installation and support staff should use this chapter, both during and after the implementation.

Introduction to Maintenance FunctionsMaintenance Functions consist of four types: Reference Data, Support, General, and Special Technologies. See Table 3-1 for more detailed information about each.

Each function described later in this chapter is categorized in this way to help understand its impact.

Who can use these options?

These functions can be protected in the following ways:

• Access to the menu options

• Read/Update access to the Maintenance Data

See Chapter 8, “Security” on how these functions can be secured. It is recommended that only designated ISPW Administrators be given update access to these functions.

Main Menu

Figure 3-1 is the main Maintenance screen. It is displayed by entering M from the main ISPW menu.

Table 3-1. Maintenance Functions

Type of Function Description

Reference Data

These functions maintain versioned data that determines how components are managed in ISPW. Changes to this data affect the way users work with ISPW. Erroneous changes could cause ISPW downtime and so a method of versioning this data for controlled activation is provided. When changes to this type of data are made, the ISPW Server will need to be refreshed and users of ISPW should go completely out of ISPW and back in again to refresh any data they had in their local cache.

Support

These functions refer to data that is not versioned and administrators’ activities that need to be performed from time to time (e.g. Refresh the Server to load in a new copy of the Reference Data).

General This is a general grouping of functions relating to setting up commands, comments and generate parameters.

Special Technologies

This is an area where menu options can be added for technologies that sites may decide to use (e.g. Natural, Telon, etc). See the ISPW Interfaces Guide for details on Special Technologies.


Figure 3-1. ISPW Administrator Maintenance Menu

Command Line Commands

As well as selecting the menu option, Table 3-2 shows the valid Command Line commands.

Reference Data ConceptsThis is section describes the concepts and terminology around managing the Reference Data.

What is reference data?

Some of the Maintenance data in ISPW’s Server is accessed a lot. In fact some data is accessed almost every time a user performs an operation on a Task. ISPW therefore caches the most heavily used Maintenance data. This data is referred to as Reference Data as it is both cached for performance and can be changed by creating new versions of it and having them activated at a point in time. The options to change Reference data are easily identified on the Maintenance Functions screen.

ISPW M ISPW ADMINISTRATOR MAINTENANCE (PROD) Command ===> Reference Data ( R ) Technical Support AD Application Streams AN Approver Names SM Server Maintenance AP Applications CH Change Codes U User List AR Approval Rules CR Component Ref. WH Warehouses BC Base Components ET Extension Tables WP Warehouse Policies CC Component Category SV Servers CT Component Types P Prefix Numbers EC Extension Classes SC Set Class ER External References GX Component groups EX Exits AG Application groups ST Streams General Special Technologies X Utility Functions T1 Technology 1 Z Generate Parms T2 Technology 2 DP Deploy T3 Technology 3 Enter END command to return to the previous menu.

Table 3-2. Command Line commands

Command Description

A,

ADDADD

There are usually two ways to do this:

— Enter the Add command on the command line, or

— Select a similar existing entry and overtype the appropriate information including the key field(s). A new entry will be added.

B,

BROBrowse Mode Toggles into browse mode. Only the browse type

commands are now valid.

L Locate

Type ‘L <entry>’ on the command line, where entry is the name of the first key field. The list of entries will then scroll to the requested one if it can be found. If not, it will scroll to the next entry in the list greater than the one not found.

Maintenance Functions 3-3

What about the other data?

Some Maintenance data is not cached or versioned, and when it is updated using the Maintenance functions, the changes take effect immediately.

Reference Data Cache

When the ISPW server is started or when it is refreshed (option SM), one version of each of the reference data types is loaded into the ISPW cache. The version of each that is loaded is the active version. Table 3-3 shows the Server cache and Client cache descriptions.

Active Versions

The Active flag denotes the active version of each type of reference data. If it is set to Y (yes), it is the currently active version. There can be only one active version for each type of reference data. If a version is active, it doesn’t mean that the data is currently in the cache (that is indicated by the Loaded flag). However, it does mean that the next time the server is restarted or refreshed; the active versions will be loaded into the cache.

Inactive Versions

When a new version is created (either by using the Add, Clone, or Import commands), it is inactive. New versions of other types of reference data can be added, and they can be edited further until they are ready to be made active (using the Activate command).

Activating a Version

When a new version is made active (Activate command), its Active flag is set to Y (yes) and the version that used to be active has its active flag reset to blank. The activated time stamp of the new version is also set. At this point the new active version is not in the cache yet, so the Refresh Required flag is set to Y (yes) to indicate that the cache data needs to be refreshed. Until this is done, all ISPW processing will be using the previous version that is still in the cache.

Note: Do not activate a version until it is ready to be used by ISPW. If there are multiple versions of reference data to be activated for a specific change, they should all be activated at the same time. In the event that the ISPW server is accidentally restarted, the active versions of the reference data will be loaded. Be sure that is what is intended.

Validation

Validation takes place within AD reference data as entries are added, modified and deleted, as all the data is versioned as one unit. Because there is no way of knowing

Table 3-3. Server and Client Cache Descriptions

Cache type Description

Server Cache

This is an in-memory copy of all the active reference data in the Server. Refreshing the Server cache using M.SM replaces all this data in the Server’s address space.

Client Cache

ISPW Users have a local cache, which is updated automatically as they use ISPW. Anytime the ISPW client requires reference data, the user’s local cache is searched and if the required data is not there it is requested from the Server. If the Server is refreshed the user must exit and re-enter ISPW to make sure that the reference data will be the correct version.


which versions of different reference data versions relate to each other, validation between the different types occurs on activation.

The reference data that is being activated is validated against the already active versions of the other types.

Example:

Version 2 of the Component Type data is active and version 2 of the Approval Rules data is active. A new version of the Approval Rules data is being activated, version 3. Validation is performed to check whether version 3 of the Approval Rules includes any reference to a new Component Type that does not exist in version 2 of the Component Type data.

If the validation checks fail, the activate fails. An error message is displayed with the details of which entry the validation failed on.

ISPW Cache Refresh

When the ISPW server is restarted or refreshed, the active version of each type of reference data is loaded into the ISPW cache. Any versions that had the Refresh Required flags set to Y (yes) will be reset back to blank. Any active versions that had the Updated time stamp set will be reset back to blank. All active versions that are loaded will have the refresh time stamp set to the time that the cache was loaded. The Loaded flags will be set to Y (yes) for all active versions that were loaded, and reset to blank for the inactive versions.

Modifying Versions

Active versions as well as inactive versions can be modified. If an active version is modified, the changes also have to be made in the ISPW cache. So the Refresh Required flag is set to Y (yes) and the time that the update was made is recorded in the Updated Time stamp field for the version.

There are two situations where modifying reference data versions is restricted:

Once a new version is made active but has not been refreshed in the cache, the now inactive version that is still in the cache cannot be modified,

An active version cannot be deleted. However, if this is the only version of an application (AD type), it can be deleted even if it is active.


Reference Data List commands

All of the Reference Data options use similar interfaces and therefore similar commands. These common list commands are described in Table 3-4.

Reference Data Options

R – Reference Data

The Reference Data option displays a list of all versions of all reference data types and is available in addition to the regular options for this data (that is, AA, AD, AG, AP, AR, BC, CC, CT, EC, ER, EX, ST plus the Deploy options if installed). It is provided as a central view for all of the reference data versions for ease of management.

Reference Data Maintenance Screen

Figure 3-2 on page 3-6 shows the Reference Data Maintenance screen. It is displayed by entering R from the ISPW Administrator’s menu.

Table 3-4. Reference Data options

Command Description

D

Delete—Deletes the entry. If this entry is related to data in other options, it will either be deleted also, or an error message will be displayed. If the latter is the case, delete the related data and attempt the delete again.

MModify—Displays the details of that entry and allows it to be

SSelect—This selects the reference data version for browse or edit. The screen that follows depends upon the type of reference data selected.

V View—Displays the details of that entry. None of the displayed fields cab be updated for this command.

CClone—Invokes the Clone function. This function allows a new reference data version to be created, based upon another version.

IImport—Invokes the Import function. The Import function is for the loading of a new version of data from an external file.

EExport—Invokes the Export function. The Export function is used to unload a version of reference data to an external file. This can be useful when making mass changes.

A Activate—Activates the version. The data will be validated and if okay it will be made active.


Figure 3-2. Reference Data Maintenance Screen

ISPW M.R REFERENCE DATA MAINTENANCE (INT) Row 1 of 22Command ===> Scroll ===> CSRList Commands: A Add, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete, C Clone, I Import, E Export V View, M Modify, A Activate Code Appl Stream Vers Version Description Active Loaded Refresh Reqd AD SITE BASIC 0001 Base Version Y Y AD TSTI BASIC 0001 Add OBJ Y Y AD TSTI BASIC 0000 Base Version - Clean AD W3 W3 0000 Base Version - Clean Y Y AP 0008 New Appl base Y Y AR 0008 Base Version Y Y BC 0009 New parse exit Y Y BC 0006 TEST BC 0000 Base Version - Clean CC 0001 Base Version Y Y CT 0006 Don's Parse Testing Y Y CT 0000 Base Version OK ER 0015 add qp command Y Y ER 0000 Base Version EX 0007 Add qp command Y Y EX 0006 add fb command EX 0000 Base Version ST BASIC 0001 Base Version Y Y ST W3 0000 Base Version Y Y


Field Descriptions

Table 3-5 describes all of the fields for a reference data version. Most of these fields are displayed on the Main Reference Data screen. However, the remaining fields are displayed by using the View command. The Version Description is the only modifiable field.

Table 3-5. Field Descriptions

Field Description

Code

The type of reference data.

Possible Values:

AA - Application/Application Group Relations

AD - Application Streams

AG - Application Groups

AP – Applications

AR – Approval Rules

BC – Base Components

CC – Component Category

CT – Component Types

EC – Extension Classes

ER – External References

EX – Exits

ST - Streams.

Appl The ApplicationID for the AD reference types.

Stream The Stream Name

Vers The version number. It is incremented by ISPW and starts at version one. Version zero reference data is supplied during the installation.

Version Description The reason for the version.

Active

Whether the version is currently active.

Possible Values:

Y – active version

Blank – inactive version.

Loaded

Whether the version is currently in the ISPW cache.

Possible Values:

Y – in the cache

Blank – not in the cache.


View Command

Enter the V (View) command against a version to see further details, as shown in Figure 3-3.

Figure 3-3. View Command

Add Command

From the Reference Data Maintenance (R) screen, you can enter the A (Add) command to add Streams, Application Definitions, Extension Classes, and Deploy Environments, as shown in Figure 3-4 on page 3-9. In most cases, it is easier to use the Clone function to create this reference data. The other types of Reference Data can only be cloned to create new versions. See “Clone Command” on page 3-9 for details.

See the relevant section for field descriptions and details on adding these types.

Refresh Reqd

Whether a server refresh is required to load updated data. This flag is set when a different version has been activated, or an active version has been modified.

Possible Values:

Y – a server refresh is required

Blank – all cached data is current, no refresh required.

Created The date and time the version was created.

Activated The date and time the version was made active.

Refreshed The date and time the version was loaded into the ISPW cache.

UpdatedIf the data of an active version is modified, this field will be set to the time that the update occurred. In this case, the Refresh Reqd field would also be set to Y. Otherwise, this field will be blank.


ISPW M.R VIEW REFERENCE DATA VERSION DETAIL (INT) Command ===> Scroll ===> CSR Code Appl Vers Description Created AD SITE 0001 Base Version 2000-06-18-14.57.00 Active Activated Loaded Refreshed Y 2001-01-18-06.18.34 Y 2001-04-11-22.00.37 Refresh Reqd? Updated Press ENTER or END to continue.


Figure 3-4. Add Command

Clone Command

A new version of any reference data type can be created using the C (Clone) command. Enter C against the version that is to be used as the base version and the screen in Figure 3-5 is displayed. If the reference data is an AD type, overtype the Application if a new application is to be cloned from an existing application. Type the version description in the Description field and press ENTER to create the new version. A new version number is automatically assigned to the new version.

Figure 3-5. Clone Command

Import Command

Use the I (Import) command to create a new inactive version. The data in the file that the import is using must be in a format created by the Export command. To generate a dataset name with the correct version number in it on the Import screen, enter I next to the version that was imported. Otherwise, enter I next to any version. The screen in Figure 3-6 on page 3-10 is displayed. Enter the version description and overtype the Import Dataset Name with the correct file name (if necessary) and press ENTER. The new version will be created with an automatically assigned version number.

ISPW M.R ADD REFERENCE DATA VERSION (QA) Command ===> Enter required details: Reference Code ==> ( AD ST EC DV ) Version Description ==> Reference Description ==> Application Stream ( AD ) Stream ( ST ) Application ==> Stream ==> Stream ==> Owner ==> Owner ==> Component Ref ==> Component Ref ==> Deploy Domain ==> Extension Class ( EC ) Deploy Environment ( DV ) Class ==> Environment ==> Owner ==> Press ENTER to complete the change or END to terminate

ISPW M.R CLONE REFERENCE DATA (INT) Command ===> Scroll ===> CSR Clone Details: Code Appl Stream Vers Description Active Loaded Refresh Reqd AD SITE BASIC 0001 Base Version Y Y New Version Details: Code Appl Stream Vers Description Active Loaded Refresh Reqd AD ____ BASIC ____________________ Define the required detail for the New (cloned) Reference Data and Press ENTER to continue or END to terminate.


Figure 3-6. Import Command

Export Command

Use the Export (E) command to copy the reference data for that version to an external format. Mass changes and multiple copies can be made from the external file, which can make it easier to transfer reference data between ISPW servers. Multiple versions can also be compared to check any differences by using an appropriate compare facility (for example, ISPF option 3.13).

Type E next to the version that is to be exported and the screen in Figure 3-7 is displayed. Overtype the Export Dataset Name, if necessary, and press ENTER to create and populate the external file with the reference data.

Figure 3-7. Export Command

Delete Command

Use the Delete (D) command to delete a version of reference data. Generally, only inactive versions can be deleted, but if an AD type of reference data has only one version that is active, it can be deleted.

Type D against the version to be deleted. A confirmation screen is displayed like the one in Figure 3-8. Press ENTER to delete the version.

Figure 3-8. Delete Command

ISPW M.R IMPORT AD REFERENCE DATA (INT) Command ===> Scroll ===> CSRDefine details for the requested Application SITE Table Import Version Description ==> Import Dataset Name ==> CRAIG.ISPWREF.AD.SITE.V0001

Press ENTER to continue with the import request or END to terminate.

ISPW M.R EXPORT REFERENCE DATA (INT) Command ===> Scroll ===> CSR The following Reference Data Version will be Exported: Code Appl Vers Description Active Loaded Refresh Reqd AD SITE 0001 Base Version Y Y Export Dataset Name ==> CRAIG.ISPWREF.AD.SITE.V0001 Press ENTER to continue with the export request or END to terminate.

ISPW M.R DELETE REFERENCE DATA VERSION? (INT) Command ===> Scroll ===> CSR WARNING: The following Reference Data Version will be DELETED Code Appl Stream Vers Description Active Loaded Refresh Reqd AD CORE BASIC 0002 Base Version Y Y Press ENTER to confirm the delete request or END to terminate.


Modify Command

Use the Modify (M) command to update the version description of all the Reference types. Only the version description can be updated.

Type M against the version to be updated to display the screen shown in Figure 3-9. After you change the description, press ENTER to complete the change.

Figure 3-9. Modify Command

Activate Command

To make another version the active version, use the Activate (A) command. Validation is performed between the version that is being activated and the currently active versions of the other reference data. If any errors are found, they are displayed and the activation fails. If the activation is successful, the data will not be in the ISPW cache. The ISPW server must be restarted or refreshed (option SM). This situation is indicated on the Reference Data Maintenance screen by the Refresh Required field. It will be set to Y (yes) against the version just activated.

Type A against the version to be activated. The screen in Figure 3-10 is displayed. Press ENTER to confirm, and the version will be activated if there are no validation errors.

Figure 3-10. Activate Command

AD – Application Definition

Defines each application and its components to ISPW.

An application definition consists of the following seven parts:

• Application • Levels• Types• Names (Libraries)• Associations (optional)• Plan Implementations (optional)• Flags

ISPW M.R MODIFY REFERENCE DATA (INT) Command ===> Modify Version Description: Description ==> Base VersionPress ENTER to complete the change or END to terminate

ISPW M.R ACTIVATE REFERENCE DATA VERSION? (INT) Command ===> Scroll ===> CSR WARNING: The following Reference Data Version will be ACTIVATED Code Appl Vers Description Active Loaded Refresh Reqd AD TSTI 0000 Base Version - Clean Press ENTER to confirm the activate request or END to terminate.


AD Selection Screen

The main option AD screen is displayed in Figure 3-11. Note that this is the same screen as described in the previous section on Option R, but with the filter value AD entered under Code. To update any of the Application Definition data, a specific version is selected or a new Application can be created by typing A on the command line.

Figure 3-11. AD Selection Screen

A - Add an Application

When a new application is created using the Add command as shown above, the screen in Figure 3-12 is displayed.

Figure 3-12. Add an Application

ISPW M.R REFERENCE DATA MAINTENANCE (INT) UPDATE MODECommand ===> Scroll ===> CSR List Commands: A Add, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete, C Clone, I Import, E Export V View, M Modify, A Activate Code Appl Stream Vers Version Description Active Loaded Refresh Reqd AD AD CORE BASIC 0002 Base Version Y Y AD DON1 DON1 0001 Parse Testing Y Y AD GUI GUI 0001 New wzzeictg test AD GUI GUI 0000 Base Version Y Y AD PAS1 BASIC 0001 Paul Scott Test Y Y AD P390 BASIC 0000 Base Version Y Y AD QMF QMF 0001 qmf test appl Y Y AD QMF2 QMF 0001 qmf too Y Y AD SITE BASIC 0001 Base Version Y Y AD TSTI BASIC 0001 Add OBJ Y Y AD TSTI BASIC 0000 Base Version - Clean AD W3 W3 0000 Base Version - Clean Y Y ******************************* Bottom of data ********************************

ISPW M.R ADD REFERENCE DATA VERSION (QA) Command ===>Enter required details: Reference Code ==> AD ( AD ST EC DV ) Version Description ==> Reference Description ==>Application Stream ( AD ) Stream ( ST )Application ==> Stream ==> Stream ==> Owner ==> Owner ==> Component Ref ==> Component Ref ==> Deploy Domain ==> Extension Class ( EC ) Deploy Environment ( DV ) Class ==> Environment ==> Owner ==> Press ENTER to complete the change or END to terminate


Field Descriptions

Table 3-6 describes each field required for an application:

After entering the information for the new Application, press ENTER to effect the update.

Selecting an Application Version

The screen in Figure 3-13 is displayed after entering option AD and a version of an application is selected.

Figure 3-13. Selecting an Application Version

Each of the sub-options is described in the following sections.

AD (S,L) - Levels

Levels define the hierarchical promotion structure for an application and correspond one-to-one with the physical libraries. Level names are user-defined names that are meaningful for a given application.

Levels Selection Screen

Figure 3-14 on page 3-14 shows a list of Application Levels. It is the first screen displayed after entering sub-option S or L. This section will only describe the processing when selecting a level for update or adding a new level. The functionality of the commands for


Field Description

Reference Code AD

Version Description A description of the reason for the version.

Reference Description A description of the application.

Application User-defined name for the application (2 to 4 characters).

StreamAll applications must have an associated Stream. Once a stream has been associated with and used by an application, it can't be removed from the application.

Owner The owner of the application. This field is currently used for documentation purposes.

Component RefValues Y or N. This flag indicates whether to use the component reference feature for this application. See Chapter 10 - Component Reference for details.

Deploy Domain Identifies the Deploy Domain. See the ISPW Deploy Reference for information on how this can be used.

ISPW M.AD APPLICATION STREAM DEFINITION - INT UPDATE MODE Command ===> List Commands: B Browse Mode Line Commands: S Select, L Levels, T Types, N Names, A Associations, P Plans M Modify, F Flags, Z Allocate, V Validate Appl Stream Application Stream Description Cref CORE BASIC Base Version of Appl Stream Y ************************** Bottom of data **************************************


Names, Flags and Plans are described in later sections. If these are selected by level, then the scope of these is restricted to that level only.

Figure 3-14. Level Selection Screen

Detail Screen

Figure 3-15 shows the Application Level details displayed when a specific Application Level is selected or a new level is to be added.

Figure 3-15. Detail Screen

ISPW M.AD/L APPLICATION TSTI STREAM BASIC LEVELS UPDATE MODECommand ===> Scroll ===> CSRList Commands: A Add Entry, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete, N Names, F Flags, P Plans, X Extensions Z Allocate Level Next Level FIXH PROD FIXT FIXH HOLD PROD PROD TEST HOLD ******************************* Bottom of data ********************************

ISPW M.AD/L MODIFY APPLICATION ABN STREAM ABN LEVEL (QA)Command ===>Enter required details: Level (KEY) ==> ST Promote Analysis ==> (Y - Yes) Next Level ==> AT Impl Exit? ==> (D - Deploy, Y - External) Warehouse for Sources : Name ==> WZCTW3H Policy ==> KEEP1INASSIGN Gen Types: Name ==> WZCTW3H Policy ==> KEEP1INASSIGN Set Scheduling Information: Set Class ==> A Job Name ==> Queue Name ==> Failure Notify ==> DB2 Information: Impl Name/Rule ==> Name or Rule to determine Plan Implementation DB2 Subsys ==> Sub-system applicable for this Level DBRM Libs ==> XREF Name ==> XREF Lib ==> R - Read only, W - Read/WritePress ENTER to complete the change or END to terminateNote: You can add a new entry by overtyping the Key with a new unique value


Field Descriptions

Table 3-7 describes each field for a level:


Field Name Description

Level The name of the level.

Next Level

The name of the next level in the promotion path. Next Level can be described by the following points:

Each Application may have only one PROD Level (Next Level is blank).

All other levels promote to a valid next level.

TEST environment levels are by definition the bottom levels of the paths. That is, a TEST level is not defined by another level as its next level.

All levels between the TEST and PROD levels in a path are HOLD environment levels.

Each level may have only one next level, but multiple levels may promote to the same next level higher in the chain.

Promote Analysis

This flag indicates whether the Promote Analysis functionality is to be enabled. Promote Analysis looks at the relationships within a Set and helps identify related component versions that may have been missed when promoting.

Valid values: Y – yes

N – no

Impl Exit

This flag indicates what method (if any) is used for performing Implementations at this level.

Valid values:

D – ISPW Deploy

I – Only deploy for an explicit I operation

Y – External Exit

Blank – No Implementation

Source Warehouse Name

This specifies a Warehouse to be used to store the source part of the component if it becomes inactive. This must be defined in M.WH.

Source Warehouse Policy

This specifies the Warehouse Policy that describes the attributes about how the warehouse is to be used (for example, how many versions to keep). This Policy must be defined in M.WP.

Gen Types Warehouse Name

This specifies a Warehouse to be used to store the generated parts of the component if it becomes inactive. This must be defined in M.WH.

Gen Types Warehouse Policy

This specifies the Warehouse Policy that describes the attributes about how the warehouse is to be used (e.g. how many versions to keep). This Policy must be defined in M.WP.

The following fields describe set attributes for running sets containing components at this level.

Set Class The set class must be a valid class as defined in the Set Class table (SC).

Job Name The job name of the set.

Queue Name If non-blank, an identifier to ensure single-threading across set classes.

Failure Notify This field is used as input to the email interface for notification when sets for components at this level fail.

The following DB2 information fields are meaningful at this level and are defined on this screen. They are discussed in more detail in the ISPW Interfaces Guide.


AD (N) - Names

This option is used to enter the physical dataset names associated with the Application Level and Component Type.

Names Screen

Figure 3-16 on page 3-17 is a list of Names. It is the screen displayed after entering option AD, selecting an application version and typing N beside it.

Impl Name/Rule

The Plan Implementation table’s Implementation Name or the Rule to be used to derive the Name for Plan implementation at this Level. Two rules are currently supported:

'APPL', and

·'P1234'.

When 'APPL', the Application code is used as the Implementation name when looking up the Plan Implementation Table. When 'P1234', the first 4 characters of the Plan name are used.

DB2 Subsys DB2 Subsystem name for this level. Should equal the value in the Plan Implementation table.

DBRM Libs

Name(s) of the DBRM libraries (no quotes, separated by blank) for this level to be used in the Bind process. For Plans, libraries at higher levels are concatenated. Up to 9 DSNs are supported. One name must be the DBRM library used by this Application/Level. This is currently the easiest way to provide for PLAN binds where DBRMs may reside in different Application libraries.

The following fields are only used for automated Plan binding for when DBRMs are explicitly defined in Plan Bind statements.

XREF Name

ISPF table name of the PLAN XREF to be used at this Level. If the PLAN XREF feature is used, a different table name should be specified for each level. If automated binding across Applications is desired, then those Applications must use the same set of XREF tables.

XREF Lib

Plan/DBRM cross-reference Library.

Valid values:

R (read-only) for tables at the PROD Level (in dataset &ISPTR),

W (write) for tables at all other Levels (in dataset &ISPTW).



Figure 3-16. Names Screen

VSAM Considerations

Figure 3-17 shows the External Names used for KSDS storage Types, which are defined in the M.AD Table for the Applications that use them. The definition of a KSDS name can include the symbolic variable <MEMBER>, which will be replaced with the ISPW Component Name at run time.

Note: Library type must be KSDS.

If the KSDS datasets are to be deployed, the target names will be defined in the M.DV tables. Refer to the ISPW Deploy Reference for information on how this should be defined.

Figure 3-17. VSAM Considerations


Field Descriptions

Table 3-8 describes each field for a name:

AD (F) - Flags

Flags are used to control ISPW processing for all Component Types within an Application at each level. The setting of these Flags determines the following:

• How the component is promoted (that is, Source only or with all its Associations)

• Is strict version control adhered to

• At what level is the component generated



Type A valid Component Type as defined in option CT.

Class

This further classifies a generated component type. It can be used to specify different dataset names for the same component type, dependent upon the value specified for the Target Environment (in conjunction with the Associations definitions).

Level The name of the level.

Storage Type

The type of dataset for this Component Type.

Valid values:

PDS – A standard TSO partitioned dataset.

HFS – Hierarchical File System files

KSDS – VSAM Keyed Sequential Dataset. For when a component is used to represent the whole KSDS.

An “*” to the left of this field indicates that the Primary Storage for this type is in the ISPW Warehouse (defined in M.ST). If a Dataset Name is specified ISPW will keep a copy of the component externally in that.

Library Name The dataset for this level must be a fully qualified dataset name with no quotes.

Encoding

Defines the Encoding used for the Storage if encoding other than the default is required at this level.

Valid Values:

A – ASCII

E – EBCDIC

U - Unicode

blank – default for type and platform

The default value is determined by the attribute Content Type specified in M.CT and the system type of the server. Example usage would be if HTML needed to be stored in ASCII even though it is being stored in HFS files on USS. In this case, a value of “A” would be required.

Server

Defines the Server where the Storage is located. Valid Values:

Server Name – must be defined in the M.SV table

Blank - used to identify the central MVS server

WORKSTN - used to identify a Workstation Level.


• Is a successful generate required before promotion to the next level

• Is the component implemented

• Is a successful implement required before promotion to the next level

• Is the source packed

• Should the component be retained in the physical library when promoted to the next level

Flags Screen

Figure 3-18 is an example of the Flags Definition screen. It is displayed when the F (Flags) command is entered against an Application Level. The flag option fields can be edited directly from this screen.

Figure 3-18. Flags Screen


Field Descriptions

Table 3-9 describes each field for a name:



Promote Method

The style of promote.

Valid values:

A – ‘P’ style promote. All of the components’ associations are promoted from this level. Any exits for operation P will be performed.

R – ‘R’ style promote. Only the source component will be promoted. Normally the Generate Option flag would be set to R. Any exits for operation R will be performed.

Version Control

Determines whether to perform version checking when a task is set In Process to promote to any HOLD environment level.

Valid values:

Blank or Y – strict version checking – if rVer or bVer is greater than target version, set default warning flag on the SetProc warning screen to N.

A – Assignment – in addition to “strict version checking,” target version can only be replaced by a task in the same assignment.

N – None. Don’t perform version checking and set the default warning flag on the SetProc warning screen to be N.

U – User – in addition to “strict version checking,” target version can only be replaced by the same user, irrespective of rVer.

W – Warning. Do not perform version checking and set the default warning flag on the SetProc warning screen to be Y.

Generate Opt

Specifies the generate option for components at this level.

Valid values:

R – generate is required at this level.

If promoting to a level with this value, a “G” operation will be initiated.

O – generate is optional at this level.

Blank – generate is not allowed.

Implement Opt

Specifies that components at this level are to be Implemented (I operation).

Valid values:

Y – Components can be Implemented. If promoting to a level with this value, an “I” operation will be initiated.

Blank – Components cannot be Implemented.

Check for Implement

Determines whether a Promote operation can be performed, by first checking if a successful Implement operation has completed for the task. Note: this flag is only valid for primary components, not generated parts (load, list, etc.).

Valid values:

Y – The task is checked to ensure that a successful Implement has completed before a Promote is allowed.

Blank – No check is made for a successful Implement of the component on a Promote.


AD (P) - Plans

To define the PLAN/PACKAGE parameters for the Appl/Level/Impl used in conjunction with parameter values specified in the PLAN/PACKAGE definitions to build the BIND statements.

Plans definition screen

Figure 3-19 on page 3-21 is the view of the Plan Implementation entries for an Application Level, displayed by typing P against the application.

Figure 3-19. Plans Definition Screen

Detail Screen

Figure 3-20 is a list of the Application Level Plan Implementation details displayed when a specific Application Level Plan Implementation is selected or when the Add command was entered on the previous screen.

Pack Prod Source

Should be input for PROD source datasets only.

Valid values:

blank or N - Do not do any packing at all.

Y - Pack the new production source

Keep Memb (retain flag)

Should only be used for generated components.

Valid values:

blank or N - Do not retain the module on a promote.

Y - Retain the module when the module is promoted to the next level. Useful for Component Types where you can't concatenate PROD/TEST/HOLD to do testing.

Build Map

This flag specifies whether or not ISPW is to store the build map for a generate at this level.

Valid values:

blank or N - Do not store a build map.

Y – Store a build map





Field Descriptions

Table 3-10 describes each field for a plan implementation:



Level The level name.

Implementation NameThe 4 character implementation name or the name derived from the application of a “rule” as specified in the AD definition for this application level.

Bind Flag

Indicates whether package or plan binds are performed for a level.

Valid values:

Y – Binds are performed.

N – No bind processing is performed.

DB2 SubsystemThe DB2 subsystem name used in the bind process. It must be a valid DB2 subsystem and should match the subsystem entered in option AD for this application level.

Owner

The plan/package owner to be used for this application level implementation.

If this value is left blank on a TEST level, then the value specified on the plan definition or the package generate options will be used. For all other levels, a value must be specified for this field.

Qualifier

The plan/package qualifier to be used for this application level implementation.

If this value is left blank on a TEST level, then the value specified on the plan definition or the package generate options will be used. For all other levels, a value must be specified for this field.

Explain Flag

Indicates whether to perform an EXPLAIN on the bind.

If this value is left blank on a TEST level, then the value specified on the plan definition or the package generate options will be used.

Valid values:

Y – An EXPLAIN will be performed on the bind.

N or blank – No EXPLAIN will be performed on the bind.

Logical CollectionIDsA list of “logical” CollectionID tags specified in plan/package definitions that are translated using a one-to- one mapping to the actual “physical” values for use in the bind processing. There is a maximum of 6 IDs.

Physical CollectionIDsA list of “physical” CollectionID tags specified in plan/package definitions. In the bind process, the “logical” values are replaced with the actual “physical” collection IDs using a one-to-one mapping. There is a maximum of 6 IDs.

Plan Name PrefixThe value specified will replace the equivalent number of characters in the plan name for the bind. This is useful when the same DB2 subsystem must be used for different levels.

Plan Name Suffix The value specified will be appended to the plan name for the bind.

Other Plan Parms Any other plan bind keyword/parameters.


AD (T) - Types

This option is used to define Component Types to individual Applications.

All Types must be valid Component Types as defined in option CT.

Types definition screen

Figure 3-21 is a list of Types. It is the screen displayed after entering option AD, selecting an application version and typing T beside it.

Figure 3-21. Types Definition Screen

Detail Screen

Figure 3-22 on page 3-25 is the Type details displayed when a specific Type is selected.

CollectionThe default logical collection to contain packages bound for the application level implementation. It is overridden by the value specified in package generate options.

Other Package Parms Any other package bind keyword/parameters.




Field Descriptions

Table 3-11describes each field for a type:

ISPW M.AD/T BROWSE APPLICATION SITE STREAM SITE COMPONENT TYPE Command ===> More: + Component Type (KEY) ==> WDLG Component Domain ==> Component Class (KEY) ==> Description ==> *Content Type ==> *Generate Skeleton ==> *Test Gen. Panel ==> *Generate Table ==> *Hold Gen. Panel ==> *Generate Job ==> *Cust Gen. Panel ==> *Prod. Move Job ==> Hold Move Time ==> (HH:MM) Restrict "X"? ==> Plibownr ==> Plibstd ==> Backup Lib Type ==> Backup Lib -1 ==> Backup Lib -2 ==> *Model DSN(MEMBER) ==> Alternate Type ==> Alternate Lib ==>



Component Type A valid Component Type as defined in option CT.

Component ClassUsed for generated component types. It can be used to specify different dataset names for the same component type (in conjunction with the Associations definitions).

Component Domain If a domain rule applies for the naming of this component, the domain name is specified in this field.

Description A short description of the component type.

The following 7 fields are override values for option CT fields. An option CT value may be negated by use of the word 'DUMMY'.

Generate Skeleton See option CT for field description.

Test Gen Panel See option CT for field description.

Generate Table See option CT for field description.

Hold Gen Panel See option CT for field description.

Cust Gen Panel See option CT for field description.

Generate Job See option CT for field description.

Prod Move Job See option CT for field description.

Model DSN(Member) See M.CT for field description.

Hold Move Time This field is not currently used.

Restrict ‘x’ This field is not currently used.


Setting up a Component Domain

A component domain enforces uniqueness of a component name for all component types that have been made a part of the domain. This is useful when shared libraries are being used for more than one component type.

Example:

In application XYZ, the component types COB and COPY are both stored in one set of libraries (as defined in option AD (Names)). This means that a component domain must be set up to ensure that components of these 2 types aren’t created with the same component name (each member must be unique in a dataset). For example, if a component of type COB has been created with a name of TESTPGM1, the component domain will prevent a component of type COPY being created with a name of TESTPGM1.

Plibownr

A way of showing “ownership” of a component in a shared PDS. This option works by controlling the User column in the ISPF PDS member list, and setting it to an appropriate value other than just a standard UserID. Note that this is not a guarantee of security at a member level; it does however give some control.

Valid values:

VIEW – This forces the ISPF statistics to show the View code of the member in the User column of the ISPF statistics for that PDS. This is useful for a PDS which contains members from different Views so that you can tell which View a member belongs to. In order to add a task to Assignments, this value must match the View that you are currently working in.

APPL – This forces the ISPF statistics to show the Application code of the Assignment in the User column of the ISPF statistics for that PDS member. This is useful for a PDS which contains modules from several different Applications (as is usually the case) so that you can tell to which Application each module belongs. In order to add a task to Assignments, the User column value must match the Assignment's Application code.

USER – The UserID of the person who did the last 's' on the task appears in the statistics. The access would be restricted to this User.

BLANK – The UserID of the person who did the last 's' on the task appears in the statistics. In this case no check is made to see whether you can or cannot add the task to this Assignment.



The procedure in Table 3-12 describes how to set up a component domain using the example above:

AD (A) - Associations

Associations are Component Types that have some relationship with another Component Type. There are four categories of Associated Component Types:

• Control Information Types

• Generated Types

• Included Types

• Related Types

Associations Definition Screen

Figure 3-23 on page 3-28 is a list of Associations. It is the screen displayed after entering option AD, selecting an application version and typing A beside it.

Table 3-12. Setting Up a Component Domain

Step Action

1

Identify which application component types are going to be part of the domain.

Example:

COB and COPY component types in application XYZ.

2

Think of a name that suitably describes the component domain. A domain name can be up to 8 characters long.

Example:

COBCOPY

3

Change the component domain field to the domain name identified in step 2 in M.AD, Types. Do this for each application component type identified in step 1.

Example:

Update the component domain field to COBCOPY for Types COB and COPY in application XYZ.

4 Save the changes and refresh the server cache.


Figure 3-23. Associations Definition Screen

Field Descriptions

Table 3-13 describes each field for an association:



Component Type A valid Component Type as defined in M.CT.

Component Class This field is not currently used for Source Types.

Association

A code indicating the type of association the “related” Component Type has to the “base” Component Type.

Valid values:

C - for Control Information types. These are modules containing control information required to process the base Component Type. Linkedit control cards fall into this category.

G - for Generated types. These are components which are created when the base Component Type is generated (compiled/linked, etc.). This association category includes load modules, DB2 DBRM modules and any other source or load modules that are produced when the base Component Type is generated.

I - for Included types. These are Component Types which are input to the generation processing of the base Component Type. COPYLIBs, DCLGENs and SYSLIBs fall into this association category.

R - for Related types. These are Component Types which are added to an Assignment automatically when the base Component Type is added. They have the same Task Name and Application as the base Component Type. Related Component Types are used as reminders. They can be deleted from the Assignment if not required. This association category may include documentation items.

Target Environment Can be used to specify a different class of dataset. This is set in the Generate Process.


AP – Applications

The basic details of all Applications are defined to ISPW using this option, shown in Figure 3-24 and Figure 3-25 on page 3-30.

Figure 3-24. Applications

Set

Set codes further define the Associations.

Valid values:

For Association = C (Control information types):

LKED – defines Linkedit control card modules For Association = G (Generated types):

GMT1 – defines GMT1 source and load



LOAD - defines the generated load module

For Association = I (Included types):

MAC - defines macro (COPYLIB, etc.) datasets to the compile/assemble step

DCL - defines DCLGEN input datasets to pre- compiler step

SYS - defines SYSLIB input datasets to the linkedit step

Sequence

A sequence of 1 for a GMT will refer to a “source” type and a sequence of 2 will refer to a “load” type. This allows up to 6 extra (in addition to the LOAD) generated objects to be associated with a Component Type. See Chapter 6, “Exit Processing” for a description of how these can be used.

For Association “I” the sequence number will determine the order in which libraries will be concatenated for a generate.

Associated Application The application of the association component.

Associated Component Type

The Component Type of the associated component. Must be a valid Type defined for this Application.

Associated Component Class

This classifies the Generated Component Type. It allows for the situation where different target datasets (e.g.LOADs) can be defined which are dependent upon the Target Environment. In the screen shot above, A different Load library is specified (Class of “CICS”) when the Target Environment is “C”.



Figure 3-25. Applications

Applications Definition Screen

A sample list of Applications defined to ISPW is displayed below. Use line command S beside an individual Application to modify its definition, or D to delete. A new Application can be created by typing A on the command line.

Detail screen

Figure 3-26 shows the Application details displayed when a specific Application is selected for modification, or a new Application is to be added.


Add or Modify Application details

Fields are:

• Appl – 2 to 4 character code

• Owner – UserID of the Application Owner

Cross Reference – Defines whether the Cross Reference Facility is enabled for this application. Valid values are:

Y – Enable the Cross Reference for this application.


N – Cross Reference not used.

Owning Appl Grp – Application Group to which this application belongs (must be a valid entry in the M.AG table).

• Sox –

• SAP –

• Description – Brief description of the application.

AR – Approval Rules

Figure 3-27 shows the approval rules that are used to determine a list of approver names in set processing. This places a restriction on the execution of the set until the approvers have authorized it. See Chapter 7, “Set Processing” for details.

Figure 3-27. Approval Rules

Approval Rules Definition Screen

Figure 3-28 is a list of Approval Rules. It is the first screen displayed after entering option AR and a version is selected.

Figure 3-28. Approval Rules Definition Screen

Detail Screen

Figure 3-29 on page 3-32 shows the details displayed when a specific Approval Rule is selected from the Approval Rule List screen.



Field Descriptions

Table 3-14 describes each field for an approval rule definition:



ApplicationID

The Application covered by this approval rule.

Valid values:

* - An asterisk indicates all applications.

An existing ApplicationID.

Stream

The Stream covered by the rule.

Valid values:

* - An asterisk indicates all Streams.

An existing Stream code.

Level

The level to be protected. For a promote operation the target level is used.

Valid values:

* - An asterisk indicates all levels.

An existing level.

Component Type

The component type to be protected.

Valid values:

* - An asterisk indicates all component types.

An existing component type.


How Approval Rules Work

When a Set is Locked, ISPW uses the entries defined here to determine what approvals are required for the Set. ISPW looks at each Task in the Set, and if there is a matching Approval Rule, the Approval is added to the Set.

BC – Base Components

The Base Component table defines the relationships between Component Types (as defined in the M.CT table), and Component Categories (as defined in the M.CC table).

Change Type

The change type of the set.

Valid values:

* - An asterisk indicates all change types.

S – Standard.

E – Emergency.

I – Incidental.

User-defined change type – as defined in M.CH.

Approver Group

The approver name. See Chapter 7, “Set Processing” for details of the approval process.

Valid values:

A value that is defined in M.AN (Approver Names). This name maps to a resource in the external security product.

Criteria This field is available for customized site-specific values.

Approval Required

Indicates whether approval is required before the set can be executed. If approvals are required, the approver has a restrictive role over the change. If approvals are not required, the approver has more of an auditing role over the change.

Valid values:

Y – Approvals are required before the set can be executed.

N – Approvals are not required before the set can be executed.

Quorum

Indicates that multiple UserIDs must grant approval for this approver name.

Valid values:

A number from 1-9.

Usage

The Usage flag can have the following values:

blank - Regular Rule

I - Impact Approvals Only. This rule is to enable approvals of Sets that have components in them affecting this Application. Approvals will not be required if the component is from the same Application Owning Group nor when a version of the component already exists in the level being promoted to. This is based upon both Static and Dynamic relationships found in the Component Reference.

S - SQL Rule. This rule is to enable approvals of Sets that have components with the SQL Flag set to "Y".

A - All Rules. This rule is for all of the above.



Example: Type ASM (Assembler) and Type COB (COBOL) could both be associated with a Component Category of PGM (Program).

Figure 3-30. Base Components

Base Component screen

Figure 3-31 shows an example of a Base Component table. To modify an individual entry, use line command S, or D to delete. A new entry on this table can be created by typing A on the command line.

Figure 3-31. Base Component Screen

Add or Modify screen

Figure 3-2 is the detail screen used to add or modify a Base Component table entry.

Figure 3-32. Add or Modify Screen


Input fields

Fields are:

Component Type — an ISPW type, as defined in table M.CT, e.g., COB.

Description — a brief description of the type.

Category — an ISPW Component Category, as defined in table M.CC, e.g., PGM.

Language — The Language entry defines the programming language used by the associated Component Type. For example, Type COB and Type COPY could both use a programming language of COB (COBOL).

Scanner — The Scanner entry defines the name of the program used to parse the source code for the associated Base Component Type.

User Exit — Defines any user-defined exit that is invoked by the parser.

CC – Component Category

The Component Category table defines the categories that are available.

Categories include high level generic references like programs and include files. These categories are used within the ISPW Component Reference to classify relationships for ISPW Processing. See Chapter 12, “Component Reference” for further information.

Figure 3-33. Component Category

Component Category detail screen

Figure 3-34 on page 3-35 shows a sample of a Component Category table. To modify an individual entry, use line command S, or D to delete. A new entry on this table can be created by typing A on the command line.

Figure 3-34. Component Category Detail Screen

Add or Modify Component Category details

Figure 3-35 is the detail screen used to add or modify a Component Category table entry.


Figure 3-35. Add or Modify Component Category Details

Input fields

Fields are:

Component Category — Defines a high level generic group of Component Types that share similar attributes. PGM (Program), for example, is a Category that is used to define executable code.

Description — Brief description, for example, Programs.

CT – Component Type Definition

Each component type and its attributes are defined. ISPW uses this information to determine how to process each different type of component.

Component Type definition Screen

Figure 3-36 on page 3-36 is a list of Component Types. It is the first screen displayed after entering option CT and a version is selected.

Figure 3-36. Component Type Definition Screen


General Notes

All values set under this option affect all occurrences of the component type across the organization. Some of the values may be overridden by Application Definitions values (option AD) or even negated using the keyword DUMMY. These values are:

• Generate Skeleton

• Generate Table

• Generate Job

• Test Generate Panel

• Hold Generate Panel

• Custom Generate Panel

• Prod Move Job

• Model

This allows default values for a component type to be set and, in exceptional cases, to be overridden for an application.

Example:

If one team needs a special compiler for its COBOL programs, the general skeleton can be identified in option CT and the override skeleton identified in that particular application’s AD entry.

Detail Screen

Figure 3-37 on page 3-37 shows the Component Type details displayed when a specific Component Type is selected from the Component Type List screen.


ISPW M.CT BROWSE COMPONENT TYPE DETAIL (W3IT) Command ===> Component Type (KEY) ==> WDLG Name Length ==> 08 Description ==> Custom Dialog XML Technology ==> ISPW Type ==> Cycle Flag ==> Y Base Component Type ==> Generate Flag ==> Case Sensitive ==> Content Type ==> T Generate Skel ==> Test Gen. Panel ==> Generate Table ==> Hold Gen. Panel ==> Generate Job ==> Cust Gen. Panel ==> Move Job ==> WZPPMOVE Librarian Language ==> DATA ISPW Exit Type ==> Exec. Environment ==> Model ==> File Extension ==> Press END to return


Field Descriptions

Table 3-15 describes each field for a component type definition:



Component Type

User-defined code for the type of component.

Example:

COB for COBOL programs.

Name Length The Maximum length for Component Names of this type.

Description A short description of the component type.

Technology

This field can be used to group together component types that use the same set of ISPW exits throughout the entire production cycle. Then one entry can be used in the exit table (M.EX) instead of one for each component type.

Any values required by standard ISPW processing are identified for the Special Technologies in the ISPW Interfaces Guide.

ISPW Type

The particular ISPW component type which is used to distinguish component types of the same technology. This allows the component types to be any name suited to the organization whilst still allowing ISPW to recognize the component type for its special processing considerations. Any values required by standard ISPW processing are identified for the Special Technologies in the ISPW Interfaces Guide.

Cycle Flag

Indicates whether the component type can move through the application levels or whether the component type exists only at the production level and is edited directly. Valid values:

Y – types that cycle through application levels, and

N or blank – non-cycle types.


Base Component Type

This field is used by the Component Reference system to determine which Component Reference routine to use when scanning the task and is used as an input parameter in the Analysis option. This field must have a related value in the Base Component Type table. The valid values are recognized by the ISPW scan routines.

Valid values:

ASM – all Assembler Component Types. This type is translated internally into PROG.

AMAC – all Assembler macros.

CLST – all CLIST Component Types.

COB – all COBOL Component Types. This type is translated internally into PROG.

COPY – all COBOL Copy Component Types.

INCL – all PL/I Include Types.

JOB – all JCL Component Types (but NOT Procs).

PANL – all ISPF Panels.

PL1 – PL/I Component Types. This type is translated internally into PROG.

PROC – all JCL Proc Component Types.

SKEL – all ISPF Skel Component Types.

blank – no component reference scanning.

Other values may be used for your site’s custom scan routines. These values must exist in the Base Component Type table in the Base Component Type field. See Chapter 12, “Component Reference” and M.XR for more detailed information.

Generate Flag

Indicates whether the component type can be generated.

Valid values:

Y – generate types, and

N or blank – non-generate types.

Case Sensitive

Determines whether the Component Name can be mixed case or just upper case.

Valid values:

Y – Component Name can be mixed case

N – Component Name is upper case

Content Type

Defines the encoding for the component type.

Valid values:

T - Platform Specific Text

U - Unicode Text

B - Binary

Generate Skeleton The name of the ISPF skeleton used to generate the component type. It should be blank if a generate is not required.

Test Generate Panel The name of the panel displayed for generate processing in a TEST environment. If no TEST panel is required, this value can be set to 'DUMMY'.



EC – Extension Classes

Figure 3-38 on page 3-41 shows where Extension Data Classes are defined. An Extension Data Class is a group of user defined attributes that can then be used to extend a particular object of reference data. See Chapter 9, “Extension Data” for further explanation of this capability.

Generate Table

The name of the table used to store processing information when a component is generated. When a HOLD generate is submitted from the user’s address space (as opposed to a generate requested via a set), generate information for the component is looked up from this table. Each generate table is referenced by one specific generate job in its SYSTSIN DD parm information. If no job submission is required for a generated component type, then set this value to 'DUMMY'.

Hold Generate Panel

The name of the panel displayed to verify the processing options and job card information on a generate in a HOLD environment. If no job submission is required for a generate-able Component Type, this value can be set to 'DUMMY'.

Custom Generate Panel The name of the dialog displayed by Topaz Workbench that contains the Generate parameters.

Generate Job

The name of the job that is executed for HOLD generates which are requested from a user’s address space (as opposed to a generate requested via a set). If no job submission is required for a generate-able component type, then set this value to 'DUMMY'.

Move Job Not Used.

Librarian Language Not Used.

ISPW Exit Type Not Used.

Execution Environment

The execution environment of the component type.

Valid values:

REFR – a reference-only Component Type that is used only for other Component Type processing. It cannot be added to Assignments or Releases and will not appear in the Component Type lists in the special browse or Assignment/Release Task Add functions.

I – used for TELON Component Types to indicate an IMS environment for TELON export utility processing.

C – used for TELON Component Types to indicate a CICS environment for TELON export utility processing.

B – used for TELON Component Types to indicate a Batch environment for TELON export utility processing.

Model The skeleton or model which is copied into TEST for a brand new task. Must be a fully qualified dataset and member name, no quotes.

File Extension The Extension to be appended to the Component Name – for distributed and HFS files.



Figure 3-38. Extension Classes

Extension Class Definition Screen

Figure 3-39 is a list of Extension Classes. It is the first screen displayed after entering option EC and a version for a specific Class is selected. From this screen the Description can be modified.

Figure 3-39. Extension Class Definition Screen

Selecting the specific class from this screen takes the user to the following:

Figure 3-40. Extension Attribute Table Screen

This is where the attributes for the Extension Class are defined. Existing attribute definitions can be changed or deleted, and new attributes can be added. Care should be taken when changing or deleting attributes that are currently used.

Adding an Attribute

Entering “A” on the command line to add an attribute results in display of the screen in Figure 3-41:


Figure 3-41. Adding an Attribute

Field Descriptions

Table 3-16 describes each field for a component type definition:

ER – External References

Installation-dependent variables and datasets are defined. These external references can be defined for the entire organization or for specific application groups.

Figure 3-42. External References

External References Definition Screen

Table 3-16 is a list of External References. It is the first screen displayed after entering option ER and a version is selected.



Attribute Name Name of the attribute being added up to a maximum of 8 characters.

Type Specifies whether the attribute is Character or Numeric.

Length

For CHAR types, this can be a value up to 255. For NUM types, two values are possible:

2 – gives a number range between 0 and 32767

4 – gives a number range between 0 and 2147483647

Description Free format field to describe the attribute.


Figure 3-43. External References Definition Screen

General Notes

A blank View code indicates that the entry for this Type Code is for the entire installation. Some entries in this table will not be applicable to all sites. If an entry is not applicable, enter “N/A”. Purchasing a new technology or deciding to use another ISPW feature could make one of these N/A fields required at a later date.

Detail Screen

Figure 3-44 shows the External Reference details displayed when a specific External Reference is selected from the External Reference List screen.



Field Descriptions

Table 3-17 describes each field for an external reference definition:

M.ER Supplied Variables

External Reference Entries

Table 3-18 lists the commonly required entries. New technologies may require other entries, and these will be documented in the ISPW Interfaces Guide.



Type CodeA user-defined variable name that will be known to ISPW. It is used as a cross reference to an area within ISPW which requires an installation-dependent value. This prevents hard coding of this information into ISPW.

View Code This field is currently not used.

Description A description of the External Reference.

Variable/DSN

The installation dependent value required by ISPW to function within the installation.

Example:

It may be a partitioned or sequential dataset name, a UserID, a job class, or a print class.

Table 3-18. Commonly Required Entries

Type Code Description

$COMPANY The company name of the site. This field can be used in any site panels.

$TECHSP1A string used to describe the primary technical support person or action to be taken when there is an ISPW error. This variable is used in ISPW error messages or panels directing users to contact ISPW support staff.

$TECHSP2

A string used to describe the secondary technical support person or action to be taken when there is an ISPW error. This variable is used in ISPW error messages or panels directing users to contact ISPW support staff. It may be left empty to indicate there is no secondary person or action available.

$USER1A String that represents the label for the User_Var_1 that is stored against the User Data. This label is used on the M.U, U.0, and “Join Users” functions. During the Install process it is set to “Department”.

$USER2A String that represents the label for the User_Var_2 that is stored against the User Data. This label is used on the M.U, U.0, and “Join Users” functions. During the Install process it is set to “Function”.

EXRLCRTE

Exit name for the Create Release function. Describes an ISPF invocation, for example:

ISPEXEC SELECT CMD(%WZURLCT)


EXSTLOCK

Exit name for the Set Lock function. Describes an ISPF invocation, for example:

ISPEXEC SELECT CMD(%WZULOCKE)

HEAD2

This 8-character or less value is used in messages and panels to refer to a “work order” or “work request” identifier that may be associated with an assignment. The ISPW standard name is WORKREQ. A site can optionally change the value to something more meaningful for their users.

OVLYSETI

This is used if a customer requires overlay messages displayed on a set (with the + signs next to setid). If the value is YES, when an overlay warning message is issued for a task that is promoted in a Set, a message is added to the Set to notify the approver and/or any interested parties about the overlay condition.

PRNTDSN The ISPF option 3.6 dataset name to be printed. It can be determined by browsing the panel.

PRNTPGM The function invoked to start ISPF option 3.6 print processing. It can be determined by browsing the SEL statements in the ISPF option 3 panel.

RECOVERYA YES/NO flag used to indicate if standard ISPF edit recovery is used at the site. Note that setting this switch to “YES” will not take effect if it has been disabled at the ISPF level.

SMTPHOST Email Interface System Name.

SMTPJOB Email Interface SMTP Job Name.

SMTPNODE Email Interface NJE Node.

SMTPZONE Email Interface Time Zone.

SXDEBUG

Specifies the value for the ISPW Debug variable to be used in Set Processing. This is useful for debugging new exits that are executed in the background during Set Processing. See the chapter in this guide on Tracing and Debug for further information.

SXLOGALC Allocation Parameters for Set Logs. Each time a Set executes a dataset is created where the log information can be written.

SXLOGPFX

Dataset Prefix for Set Log Datasets. The Dataset Name will be of the format:

sxlogpfx.Snnn.#nnnnnnn.LOG

where nnnnnnnn is the Set ID.



EX – Exits

Figure 3-45 defines the execution (processing) exits to ISPW for each operation that can be executed against tasks.

Example:

The command(s) for invoking the edit routine for a task.

Figure 3-45. Exits

Exits Definition Screen

Figure 3-46 on page 3-47 is a list of Exits. It is the first screen displayed after entering option EX and a version is selected.

SXMAILOK

Enable sites to send E-Mail messages if Sets complete normally. The sample WZUSETX Clist provided with the base will send E-Mail messages to designated users - if the value is YES, the last update users and the users defined in the M.AD table SXNOTIFY variable will be notified that the set has completed normally. If the value is NO then only the SXNOTIFY users are notified if a Set fails.

SXPOSTFT

Provided to enable sites to File Tailor batch jobs from the Set Completion User Exit. When a Set has finished processing the local Set Completion Exit WZUSETX is invoked. The sample WZUSETX Clist provided with the base will File Tailor skeleton WZUPOSTX if the variable SXPOSTFT has the value YES.

WIPMSG Indicates whether the email interface is invoked for component overlay conditions.

WVOPALL/ WVOPSOME

These two variable combined contain the list of operations that are valid from the ISPW Task List.

WVOPHISTTask Operations can be included in this entry that require logging to the Task History. ISPW by default logs the major operations (e.g. G, P, X, I, FB, D). If the customer requires further operations to be logged list them here.

WZZLLIB The ISPW program load library. Used in File Tailoring.



Figure 3-46. Exits Definition Screen

Detail Screen

Figure 3-47 shows the Exit details displayed when a specific Exit is selected from the Exit List screen.



Field Descriptions

Table 3-19 describes each field for an external reference definition:



Operation A valid task operation, eg, S, for Select (or edit).

Exit Key

Type of processing exit.

Valid values:

$$$$- Standard ISPW processing,

#### - Global exit processing

@@@@ - Set pre-exit process. (See “Set Exits” on page 7-5 for details of this option.)

Technology code – Any one of the valid technology codes, for example, QM for QMF.

Component type – Any valid component types, for example:

DCLG.

$$EP – External Process

Description A description of the purpose of the exit.

Pre-Op Routine

The invocation of a routine to be run prior to standard ISPW processing. For a ‘$$$$’ exit definition, this is the name of the standard routine. Enter either the invocation of a panel, CLIST or program. The field can be several lines to handle long parameters. For a ‘####’ definition, this routine is called from the standard routine prior to standard processing for all types.

Post-Op Routine

The invocation or a routine to run after standard ISPW processing. For a ‘$$$$’ definition, this value is ignored. Enter either the invocation of a panel, CLIST or program. The field can be several lines long to handle parameters. For a ‘####’ definition, this routine is called from the standard routine after standard processing for all types.

Valid in Environment Fields:

A flag to indicate in which environments this operation is valid. Some operations are only valid when the task is at a specific point in the TEST, HOLD, PROD cycle.

Example:

Operation B is valid at any time, while the S operation can only be used in the TEST environment.

These fields only affect standard processing entries (exit key ‘$$$$’). Other entries are valid in the same environments as the standard exit they affect. A standard exit can be valid in one or more environments. The following is a description of the environments. Each environment requires a Y or N value.

OUTS The task is Outstanding. It has not been checked out and may exist in another assignment.

TEST The task has been checked out into the TEST level. This is where updates and component testing takes place.

HOLD The task is at a HOLD level but has not been promoted to production.

PROD The task has been promoted to the production level.


ST – Streams

Streams define the scope for configuration management for a group of Applications. ISPW’s configuration management feature will look for relationships between components within a Stream. Streams consist of a level structure definition and all Applications defined within a Stream must use a subset (or all) of this structure.

Figure 3-48. Streams

Stream Definition

On selection of a Stream, Figure 3-49 is displayed:

Figure 3-49. Stream Definition

Update Last Operation Code

A flag that indicates whether or not the task status fields LAST OP, LAST OP USER, LAST OP DATE, and LAST

OP TIME should be updated when the operation completes successfully. The status fields are used to show information about the last significant operation for each task.

Example:

The browse operation B is not significant, but the edit operation S is.

Enter Y for all operations that should update the task statistics and N for those that shouldn’t. This field is only used for standard processing entries (exit key $$$$).

Note: Y should not be specified if the operation is valid across several environments as it will then destroy the LAST OP field.

Example:

If the browse operation was specified as Y, the LAST OP would be set to B when a task in production was browsed. This would overlay the LAST OP of P.



Templating

Most of the Stream Definition screens are similar to those described in “AD (S,L) - Levels” on page 3-13. Unless otherwise specified, values that are set against the Stream are used as a template for when the Application is defined within the Stream.

ST(L,S)—Entering L or S will initiate the definition of level information. See “AD (S,L) - Levels” on page 3-13 for a description of the fields.

Note: The Levels defined for the Stream define the level structure limits for any Application defined to that Stream. Applications defined to the Stream do not have to have all of the paths, but each path defined must conform to a path in the Stream definition.

ST(M)—Entering M against the Stream name will initiate Figure 3-50:

Figure 3-50. Templating

This is similar to the Application Definition screen. The Component Reference field is not used.

ST(T)—The Type information specified against the Stream is similar to that defined in M.AD(T), although there are some extra attributes as shown below that apply to all Applications defined to that Stream:

Figure 3-51. Additional Attributes


VSAM Considerations — If component type is for a VSAM (KSDS) file, Warehouse Storage must be set to “Y”.

ST(N) — The Name information specified against the Stream is identical to the way it is defined for M.AD(N) and provides a useful way to template the dataset names. See “AD (N) - Names” on page 3-16 for a description of these fields.

ST(A) — Association information specified against the Stream is identical to the way it is defined for M.AD(A) and provides a useful way to template the dataset names. See “AD (A) - Associations” on page 3-27 for a description of these fields.

ST(P) — The Plans information specified against the Stream is identical to the way it is defined for M.AD(P) and provides a useful way to template the dataset names. See “AD (P) - Plans” on page 3-21for a description of these fields.

Support Data

AN – Approver Names

The definition of Approver Names is required before they can be used on an Approval Rule (M.AR) definition.

Approver Name Definition Screen

Figure 3-52shows Approver Names examples. It is the first screen displayed after entering option AN.

Figure 3-52. Approver Name Definition Screen

Detail Screen

On selecting an Approver Name Figure 3-53 is presented:



Deployment Type If ISPW Deploy is installed and used, this relates the ISPW Type to the Deployment Type

Warehouse Storage

This determines whether the Component or Part is to be primarily stored in the Component Warehouse. If set to “N” then there must be an external dataset defined to store the component. If set to “Y”, then an external copy may still be specified and kept.



Field Descriptions

Table 3-21 describes each field for an Approver Name definition:

CH – Change Types

A change type is an attribute of a set that describes what sort of change the set is being used for.

Change Type definition Screen

Figure 3-54 shows Change Types examples. It is the first screen displayed after entering option CH.

Figure 3-54. Change Type Definition Screen

General Notes

It is useful to group sets by change type, so other settings can be based on it.

Example 1:

Set priorities can be tuned so that an emergency change will be executed before a standard change.

Example 2:

Approval rules can be tuned so that emergency changes don’t need approval but standard changes do (option AP).



ApproverThe Approver Name. This CHAR(10) field relates to a SAF Resource Name that is used to secure who can Approve an Approval of this Name. See Chapter 8, “Security” for further information.

Description Free format description

E-Mail An E-mail address that can be used to send an e-mail when an Approval is required


The use of a certain Change Type can be secured to prevent misuse. See Chapter 8, “Security”.

Detail Screen

Figure 3-55 shows the details displayed when a specific Change Type is selected from the Change Type List screen.


Field Descriptions

Table 3-22 describes each field for a change type definition:

CR – Component Reference Functions

This option is used to load Component Reference data by parsing component source modules. A batch job is submitted to perform the parsing. See Chapter 12, “Component Reference”for more details.

Component Reference Definition Screen

Figure 3-56 shows the main Component Reference screen. It is the first screen displayed after entering option CR.



Change Type

The change type of the set. Three change types are provided by default, but any other user-defined change types can be added.

Valid values:

S – Standard.

E – Emergency.

I – Incidental.

Any user-defined change type.

Set Priority

Relative priority taken into account by the set scheduler during set initialization. The highest number has highest priority.

Valid values:

A number from 1-9.

Description A description of the type of change.


Figure 3-56. Component Reference Definition Screen

Field Descriptions

Table 3-23 describes each selection criteria field:

Note: Each of these fields accept wild card (*) values (i.e. enter A* in the application to process all applications that begin with A).

ET – Extension Tables

This option is display-only that shows which of ISPW’s Maintenance Tables allow user- defined Extension Data. See Chapter 9, “Extension Data” for more information on this capability.

Display Screen

Table 3-23 shows the Extension Tables screen. It is displayed after entering option ET.



Application The application to be searched. This field is mandatory. Only component versions found in this application will be parsed.

Stream The Stream to be searched. This field is mandatory. Only component versions found in this Stream will be parsed.

Component Type The component type to be searched. This field is mandatory. Only component versions found of this type will be parsed.

Level The level to be searched. This field is optional. Only component versions found at this level will be parsed.


Figure 3-57. Display Screen

The values in this table are supplied with ISPW, and cannot be changed. They are for reference use only.

GX - Component Groups

This option is where Component Groups are defined. A Component Group is a general group of components which do not necessarily belong to the same application or stream. For these groups you can run site-defined, server controlled processes upon completion of an operation. See Chapter 10, “Component Groups” for further explanation of this capability.

Display Screen

Figure 3-58 shows the Component Group screen. It is displayed after entering option GX.


Detail Screen

Figure 3-59 shows the Container Prefix details, which are displayed when a specific Container Prefix is selected from the Container Prefix List screen.



Field Descriptions

Table 3-24 describes each selection criteria field:

P – Container Prefixes

Container names consist of a prefix and a sequentially assigned number.

Assignment, Release and Set prefixes can be defined for applications along with the next number to be used with the prefix.

Container Prefixes definition Screen

Figure 3-60 shows a list of Container Prefixes. It is the first screen displayed after entering option P and a version is selected.

Figure 3-60. Container Prefixes Definition Screen

General Notes

The Next Number field should never be decreased once containers for this prefix have been created. This would result in an invalid attempt to create a duplicate container.

Detail Screen

Figure 3-62shows the Container Prefix details displayed when a specific Container Prefix is selected from the Container Prefix List screen.



Group Group Identification Name

Description Short description of the group

Procname External Procedure Name. The name of this procedure will be posted to the external procedure call.



Field Descriptions

Table 3-25 describes each field for a container prefix definition:

SC – Set Classes

Set classes can be used to group sets to describe the scheduling and initialization environment.

Set Classes Definition Screen

The following screen shot is a list of Set Classes. It is the first screen displayed after entering option SC.

Figure 3-62. Set Classes Definition Screen



Container Type

The type of container.

Valid values:

A – Assignment

R – Release

S – Set.

Container Prefix The name of the prefix. It becomes the first few characters of a container name.

ApplicationID A valid application code to be associated with this prefix. This may be blank to share a prefix across multiple containers.

Next Number The next number to be used for a new container. 1 is the usual starting number.


General Notes

A class is assigned to a set when it is created. It is determined by checking the application and level reference data to find the default class. See “AD (S,L) - Levels” on page 3-13 for details.

Sets that are created for an application level that doesn’t have an associated set class, will be assigned the default set class, A (this special class should never be deleted).

Detail Screen

The following screen shot shows the details displayed when a specific Set Class is selected from the Set Class List screen.


Field Descriptions

Table 3-26 describes each field for a set class definition:

SM – Server Maintenance

Maintenance commands can be issued to the ISPW server.



Set Class

The set class identifier. The default set class (A) that is provided should not be deleted. However the parameters for it can be changed.

Valid values:

A – default set class.

Any user-defined character, but most likely a letter.

Max Jobs

The maximum number of concurrent sets allowed to run under this class.

Valid values:

0 (zero) – class is closed; no sets can run under this class.

A number from 1-32000 – this many sets can run under this class.

Retain Days

The number of days that a successfully completed set is kept open before it is automatically closed.

Valid values:

0 (zero) – close set immediately.

A number from 1-32000 – close after this many days.

Class Description A description of the set class.


Server Maintenance Control Screen

The following screen shot is a list of Server Maintenance commands. It is the first screen displayed after entering option SM.

Figure 3-64. Server Maintenance Control Screen

General Notes

The Server Refresh function is the option that will probably be most commonly used by ISPW Administrators. Other options may be used if requested by ISPW Technical Support staff.

See Chapter 13, “ISPW Debug and Trace Facilities” for further details on trace commands.

Command Descriptions

The following table describes each command:

Server Refresh

This function is used to refresh the Server Cache memory. The ISPW Server loads all Reference Data into memory when it is started to ensure good performance. When Reference Data is changed a Server Refresh ensures that the latest versions are loaded into memory.

SV – Servers

This is used to specify the Servers on which ISPW Component Transport (CT) address spaces will reside. All CT address spaces must be defined in this option for the Component Warehousing to successfully work.

Table 3-27. Command Descriptions

Command Name Description

P Stops the server.

R Refreshes the Reference Data in the ISPW server cache.

S Starts the server.

T Turns on ALL Server tracing

X Stops ALL Server tracing

M Modify the current Trace settings by adding a Trace command


Display Screen

The following screen shot is the Hosts screen. It is displayed after entering option SV


Option A,S

These provide the function to Add or Select a server entry for change. The screen shown in Figure 3-66 is displayed. (For the Add it will be empty.)

Figure 3-66. Option A, S

Field Descriptions

Table 3-28 describes each field for a Host definition.

ISPW MODIFY SERVER TABLE DETAIL (INT) Command ===> Enter required details: Server Name (KEY) ==> AIXPROD (For LU6.2 must be VTAM Name) System Type ==> AIX (MVS/WIN/AIX/LINX/SUN/HPUX) Server Type ==> RS (CT/CI/RS/CM) Address ==> AIXPROD.INTRANET (CT/RS Only) Socket ==> 02229 (CT/RS Only. Restart CT/RS if changed) CSS Socket ==> 00000 (CT Only. Restart CT if changed) Deploy ==> Y (Y/N CT/RS Only) Description ==> Prod Websphere Target Remote Status ==> Offline Press ENTER to complete the change or END to terminate Note: You can add a new entry by overtyping the Key with a new unique value



Server Name

The name of an ISPW Server (CM), Communications Interface Server (CI), Component Transport Server (CT), or Remote Server (RS). If LU6.2 communications are being used for the ISPW Messages, this must conform to the VTAM Name that relates to the server name. For TCP/IP message communication, it is a logical name.

System Type The type of platform on which the server resides. Currently MVS, WIN, AIX, LINX, SUN, and HPUX are the supported types.


Further Information

For further description of the different communication methods and options available in ISPW, see the ISPW Remote Server Guide.

Option X

Option X will invoke the standard dialog for the definition of Extension Data. See Chapter 9, “Extension Data” for further information on this feature.

Option R

This option resets the Remote Server Security Token for that Server. It is valid only for non-MVS Remote Servers. See the ISPW Remote Server Guide for further information on its usage and impact.

Options L,T and P

These options display the Remote Server Log, Trace and Parameter files respectively. This is valid for non-MVS remote servers only. See the ISPW Remote Server Guide for further information on its usage and impact.

Option Z

This option is used to display the Remote Server Log, Trace and Parameter files respectively. This is valid for non-MVS remote servers only. See the ISPW Remote Server Guide for further information on its usage and impact.

U – User Table

The user table shows which users are using ISPW and stores contact information for the email interface. It allows administrators and users to update user details and to delete Users no longer needing to use ISPW.

User Definition Screen

The following screen shot is a list of Users. It is the first screen displayed after entering option U.

Server Type The type of server (CT, CI, RS, CM).

AddressThe TCP/IP address of the Server. This is only required if ISPW Deploy is transferring components between CT Servers, or if the Topaz GUI or Web Interface are used to browse files.

Socket The TCP/IP socket that the CT Server listens on for Component Transport Data Transfer requests.

CSS Socket The TCP/IP socket that the CT Server listens on for Topaz GUI and Web Interface browse requests.

Deploy Indicates whether the server is used for the Deploy feature.

Description Free format field to describe the server.

Remote Status Displays the status of the server, either Online or Offline

Table 3-28. Field Descriptions (Continued)



Figure 3-67. User Definition Screen

General Notes

The user table does not store user authorizations. The security function is performed through defining SAF resources. See Chapter 8, “Security” for details.

Users can update their own details and ISPW administrators can update any user’s details.

Detail Screen

The following screen shot shows the details displayed when a specific User is selected from the User List screen.


Defining New Users

If a user doesn’t have a user definition, when they use ISPW a blank user entry is automatically added and a welcome screen displayed, rather than preventing the user starting ISPW (unless they are unauthorized.

To avoid the welcome screen being displayed, add a user definition before the user first starts ISPW.

Welcome Screen

The first time a user starts ISPW, a welcome screen is displayed. The user can then add their own details or choose to leave them blank. If the details aren’t filled in, the welcome screen will be displayed the next time the user starts ISPW.

Welcome Screen

The following screen shot shows the welcome screen:


Figure 3-69. Welcome Screen

Field Descriptions

The following table describes each field for a user definition:

WH – Warehouses

This option is used to define, maintain and view warehouses. Warehouses are used to store component versions and their respective parts.



User The TSO UserID, started task or batch job name.

First Name User’s first name(s).

Last Name User’s last name(s).

Telephone User’s Telephone number

E-mail User’s email address. It’s used to receive notification through the ISPW email interface.

Node The node of the machine that the user is working on. This is used to receive notification through the ISPW email interface.

DepartmentUser defined fields. The label for these is defined in M.ER.

Function

Last Logon The date the user last used ISPW. It is set automatically by ISPW and cannot be changed.


Figure 3-70. Warehouses

Adding and Maintaining Warehouse Definitions

Type A on the command line to add a new entry or S to select an existing one. The following screen is displayed:

Figure 3-71. Adding and Maintaining Warehouse Definitions

Field Descriptions

The following table describes each of the fields that can be entered.



Warehouse The logical name of the Warehouse. This must be a unique name.

CT Server Name The name of the Component Transport Server Name as specified in M.HS.

Allocation Type Currently only Allocation Types of MVS are supported. Future releases of ISPW will support warehouses on other platforms.

Description Descriptive information used to identify the warehouse.

Dataset Prefix

This specifies the HLQ's for the Storage dataset Datasets will be named as follows:

'Thisprefix.Warehousename.StorageID.WPDS'

The StorageID will be determined by ISPW.


Warehouse Datasets

After a Warehouse is defined, no warehouse datasets are created until they are needed. Information about the datasets ISPW has created is available by entering N from the main WH screen.

Figure 3-72. Warehouse Datasets

Storage Names Screen

The following screen is displayed:

Figure 3-73. Storage Names Screen

Management Class

The rest of the parameters are standard allocation parms for MVS datasets. Consider specifying large space to limit the number of datasets that ISPW will create.

Storage Class

Volume Serial

Device Type

Data Class

Space Units

Primary Quantity

Secondary Quantity



Field Descriptions

The following table describes each of the fields on the screen.

WP – Warehouse Policies

This option is used to define, maintain, and view warehouses Policies.

Warehouse Policies are used to create sets of rules about how warehouses are to be used. These Policies can then be used by Applications to suit their requirements. The WP screen looks as follows:

Figure 3-74. Warehouse Policies



Warehouse The logical name of the Warehouse.

StorageID This is ISPW’s logical name for the physical warehouse storage name. ISPW will create these as it needs more space.

Storage Name The physical storage identifier. For a warehouse on MVS it will relate to a PDSE dataset.

Status

This can be Active, Full or Unavailable.

Active indicates that it is available for the storage of software objects.

Full indicates that the physical storage name is full. ISPW will not attempt to store any more software objects in it. If ISPW deletes an object from this storage name it will set the status back to Active.

Unavailable indicates that this storage name is not to be used to store away any more software objects.

Drain is used to empty a warehouse dataset and have the members moved to another. This is sometimes useful if there are many underutilized datasets to consolidate them.

Entering M against the Storage Name will toggle the status between “Unavailable” and “Active”.


Adding and Maintaining Warehouse Policies

Type A on the command line to add a new entry or S to select an existing one. The following screen is displayed:

Figure 3-75. Adding and Maintaining Warehouse Policies

Field Descriptions

The following table describes each of the fields that can be entered.



Policy Name Identifies the Policy. It is a key field and must be unique.

Description Descriptive information used to identify the warehouse.

Method

Can be the following values:

A - relates MAX VERSIONS to Assignment. ISPW will keep at least this number of historical versions of this component version in an Assignment for the level at which the policy is used. This is useful for when a component version supersedes one in another Assignment multiple times. Even if MAX VERSIONS is set to 1, the version in the other Assignment will not be deleted.

L - relates MAX VERSIONS to Level. ISPW will keep at least this number of historical versions of this component version at the level for which the policy is used. This is useful at a PROD level where all versions might be kept.

Maximum versions This is the Maximum number of historical versions kept by ISPW for the method specified.

Compression Type

This indicates the type of compression used. Current options are:

0 - no compression

1 - medium compression

2 - maximum compression

Type 1 provides a good balance for saving disk space and using CPU to compress the objects.


General Data

C – Comment File

This option is used to define the bulletin boards or comment files used by an organization. They may be set up at the corporate or departmental level or even for special interest groups. It is more useful at sites that do not have an electronic mail product as it can provide some of those functions (though not as elegantly).

Main Screen

The following screen shot is the first screen displayed after entering option C.

Figure 3-76. C Main Screen

Field Descriptions

The following table describes each field:

CO/CZ – Commands “O”/ “Z”

This table contains the list of installation specific commands that can be executed by users.

Main Screen

The following screen shot is the first screen displayed after entering option CO or CZ.



View The logical view that the bulletin board is connected to.

Group Name A description of the department or group.

Updated The date the file was last updated.

File Name The fully qualified dataset name (no quotes) which is the sequential file that contains the comments.


Figure 3-77. CO/CZ Main Screen

General Notes

Multiple tables can be created. There are currently two:

Z – user functions,

O – operations functions.

To add to the table or make changes, enter a ‘C’ beside an entry in update mode. If you change the alias, a new command will be added to the table.

Z – Generate Parameters TablesNote: This section is only applicable if the customer is still using the generate process that

was in effect for versions 4.2 and older. ISPW strongly recommends that customer sites convert to the new process as soon as possible. See “Generate System Customization” on page 4-5 for information on adding site-specific parms for the new generate process.

If the format of the Generate Parameters tables ever has to be changed for special user requirements, this option can be used to create the new model that will then be used in all the appropriate functions.

It also allows existing Generate Parameters tables to be converted to use the new structure when the Model table has been changed.

Main Screen

The following screen shot is the first screen displayed after entering option Z:


Figure 3-78. Z Main Screen

Model Tables

The model table names are:

$ZZCPRM in the M Tables dataset is used for Permanent Generate Parameters.

$WZXGENT in the M Tables dataset is used for the work/demanded Generate parameters.

General Notes

Only authorized users (ISPW administrators) can use these functions.

The GC option takes effect immediately. It should NOT be run during prime time to avoid table contention problems. The Generate tables contain valuable control information; they should always be backed-up before any conversion.

Description of Model Tables Options

Options GP and GENT are generally only used during the installation of a new ISPW release requiring changes to tables formats. The installation instructions will identify which models have to be re-created. If a model is generated at any other time, no harm is done as the existing model is replaced with a duplicate.

Adding Variables Procedure

The Permanent Generate Parameters table $ZZCPRM and the $WZXGENT generate table can be modified to support site requirements. If a site decides additional user variables are required on any of the tables, this function can be used to update the vanilla definitions. See procedure below.

Note: After any new release of ISPW that involves changes to the vanilla table formats, the site variables will have to be added again to the table definitions in the model routine(s).

Table 3-34. Adding Variables

Step Action

1 Checkout the routine WZZMZ## in the site “mods” application (or routine WZXGENT to modify the $WZXGENT table)


Description of Conversion Option

Option GC should be executed when the $ZZCPRM model table has been updated to add new site-required variables for Generate processing. Existing <appl>CMPL tables must be converted to pick up any new variables added to the Model table. See Chapter 4, “Generate Processing” for details.

Application tables may be converted individually (in foreground or batch) or ALL tables may be converted in one batch job.

Note: The skeleton WZZMX#GP must be modified to point to the site’s I S P W datasets for the ISPF allocations and the ‘M’ and ‘O’ table dataset allocations before the background job is executed.

2 Update the appropriate model with the site-specific variables.

3 Use the appropriate M.Z option to re-generate the model.

4 Convert “live” tables if necessary, using option GC.

5 Update any ISPW functions that will initialize or use the new variables.

Table 3-34. Adding Variables


4-1

Chapter 4.

4Generate Processing Chap 4

Generate processing refers to all of the processing that occurs as part of the ISPW ‘G’ operation. This is a complex and critical function of ISPW. This chapter gives an overview of this function. It does not address every issue that will arise in customizing ISPW to execute compiles/generates for a site. Each site customizes the Generate to meet their requirements.

For more specific Generate information on other Technologies, See the ISPW Interfaces Guide.

Generate Processing OverviewThe Generate System is an integral part of ISPW. This section gives an overview and describes the components involved. Please be aware that the process described herein is new with release 4.3. For information regarding the previous process, see Appendix C, “Generate Process for Previous Versions”

Where are Generates Performed?

In ISPW, generates are generally only performed in the TEST and HOLD environments. The PROD environment is updated by copying the source and generated components from the HOLD environment to the PROD environment.

The last generate at a HOLD level can be considered to be the “production” generate. The PROD environment then contains what was tested and signed off in the HOLD environment.

TEST versus HOLD generates

ISPW differentiates between generates performed in the TEST environment to generates performed in the HOLD environment. It is possible to have different generate panels and processing. The TEST level generates are normally performed under the requestor’s userID, and HOLD generates are performed under some controlled ID.

Generate processing can be the same or different for both environments and is usually controlled by the code in the Generate Skeletons using MEMBENV=‘TEST’ or MEMBENV=‘HOLD’.

Automatic Generate after Promote

The Promote operation can automatically request a Generate for any “generate” component types depending on the options set in the Reference Data (option AD, Flags). If the Generate Indicator is set to R (Required), a Generate will automatically be performed for that component at that level. If the Generate Indicator is set to O (Optional), an online generate may be performed from the ISPW Task list (a generate will not automatically be done in a Set in this case).

Prevent Promote after Failed Generate

A subsequent promote operation can be prevented if the generate for a component has failed. It depends on the options set in the Reference Data (option AD, Flags). If the Check Generate Flag is set to Y (Yes), any attempt to perform a promote on a component


where the last generate has failed, will be rejected. If the Check Generate Flag is set to N (No) or blank, the promote will be allowed.

Pre-exit and Post-exit processing

As with other ISPW task line commands, the site can specify special processing to occur. This can be before the standard ‘G’ processing as a Pre- exit or after the standard processing as a Post-exit.

Exit Processing Phases

The standard ‘G’ processing calls an internal process with the following events occurring: If a pre-exit is defined for the technology or component type, it is invoked. If no pre-exit was defined or the return code from the pre-exit is 0, then routine WZZEXG# is invoked. If a post-exit is defined and the return code from WZZEXG# is 0 or 2, then it is invoked.

WZZEXG# processing

WZZEXG# is the main processing routine for all generates and controls the display of the generate panel, update of the Permanent Generate Parameters, update of the Generate Extension Classes, WZGPARMS and WZGWORK, and file tailoring and submission of any generate JCL. The basic functions it performs include the following:

• Retrieve the Permanent Generate Parameters from their respective DB2 tables and the WZGPARMS variables. These values are kept and versioned for each component. For new components, new rows are added to the tables and extension classes.

• For a foreground generate, display the appropriate generate panel (TEST or HOLD) as specified in M.CT/M.AD to allow the user to modify generate parameters/variables.

• If it is a TEST generate and the user has changed a parameter value, update the Generate Parameters if indicated by UPDTFLAG=’Y’. Setting of this flag is usually controlled in the TEST panel. Parameters are not normally updated in HOLD, although the jobcard and other information may be input.

• Other processing is performed to validate and set variables used in generate processing and in the file tailoring of the skeletons.

• If this is a foreground generate, values are added to or updated in the Generate Extension Class, WZGWORK. These values contain all of the temporary ISPF variables that would otherwise not be available for the demanded batch job. A foreground generate will also update any indicated parms from the generate panel in the WZGPARMS extension class.

• If this is a demanded background generate, the values previously stored in the WZGWORK extension class are retrieved.

• For compatibility with older versions of ISPW, the Generate User Exit, WZXGEN1U, may still be called if it has been customized by a site, but ISPW now recommends that site-specific generate processing be done in a routine defined to the CMPLEXIT variable. The information on the appropriate Generate Extension Class is retrieved so that all the information for the component is available in either the CMPLEXIT routine or WZXGEN1U. The site code is executed and any generate parms added to the temporary table, $WZXGENX, are retrieved and passed along to the subsequent file tailoring process. If the return code from the Generate User Exit is 0 then the processing continues. If not, the processing is terminated.

• If the generate job is file tailored and submitted in foreground from the user’s TSO session (usually the case in a TEST generate), then the following steps are executed:

• The Generate Skeleton is file tailored.

• The resulting job is submitted using the SUBMIT command.

Generate Processing 4-3

• If this is a demanded background generate, ISPW will submit a job under the Set Processor UserID. This batch job will in turn build and submit any required generate jobs. The following steps are executed:

• The batch job to process the demanded generate is submitted.

• The Generate Skeleton is file tailored

• The resulting job is submitted using the SUBMIT command.

Generate VariablesThere are 2 types of variables used during generate processing:

• Permanent Generate Parameters

• Extension Class Variables

Permanent Generate Parameters

These parameters are stored in several of the ISPW metadata DB2 tables for a component. There are entries for each compilable component defined to ISPW and they are stored in these tables:

WZT_APPL WZT_CMPNT_VERSION WZT_EXTS_DATA

The parameters are permanent because they retain their values between generates unless the user changes them (which is allowed on the TEST level generate panels). Not all parameters are necessarily required in setting up the generate processing for an organization

Table 4-1describes the base fields:

Table 4-1. Permanent Generate Parameters

Field Description

MEMBTYPE Component Type.

MEMBER Component Name.

LOADNAME Load module name.

USERID The UserID of the last person modifying the component.

LASTOPDT Date of the last operation performed on this component.

LLVL Flag to indicate “language level”. Can be (COMMAND/MACRO) to indicate type of CICS pre- compiler.

COMPILER

Indicator for compiler.

Example: MV (COBOL for MVS) for COB Type.

WZZCOPYFlag to indicate if the TEST level copy or include libraries are to be concatenated in the compiler SYSLIB DD. If ‘N’, then only HOLD and PROD level libraries are concatenated.

WZZLINKFlag to indicate if the TEST level Load libraries are to be concatenated in the Linkage Editor SYSLIB DD. If ‘N’, then only HOLD and PROD level libraries are concatenated.


GMT1NAME Name of GMT1 ‘source’ module. Non-blank if module is to be generated. Defaults to source name. This relates to Association GMT1 Sequence 1.

GMT1LNAM Name of GMT1 ‘load’ module. Non-blank if module is to be generated. Defaults to source name. This relates to Association GMT1 Sequence 2.





WZGPROG Flag to indicate whether load module is executable ‘Y’ (program) or non-executable ‘N’ (subroutine).

WZGSQL Flag to indicate SQL statements (pre-processor step required).

WZGBIND Flag to indicate that the DB2 bind process should be invoked.

WZGPKG Flag to indicate a DB2 package exists for the module.

WZGPLNB Flag to indicate that PLANs using DBRM directly of program module being generated should be bound (DBRM updated) in program generate.

WZGDB2DB2 subsystem ID in PROD for a plan/package. This value can be used to override the value specified in M.AD for the application for the PROD bind.

WZGPKG parameters ‘ ’ suffix defines a specific package bind parameter as documented in routine WZZMZ##.

CPARM1 to CPARM5

Compiler parameters. Normally, CPARM1 contains the parameters for the compile step; with other fields containing parameters for pre-processors or other generate steps. The definition and standard for these variables is left the site administrator.

LPARM1 to LPARM5

Linkage Editor parameters. Normally, LPARM1 contains the parameters for the Link Edit step, and the others are used for parameters to any other steps. The definition and standard for these variables is left to the site administrator.

SPARM1 to SPARM3Special parameters. These can be used for any parameters that are not applicable to the CPARMn and LPARMn variables. The definition and standard for these variables is left to the site administrator.

Table 4-1. Permanent Generate Parameters


Where these values are set

In standard ISPW processing, all of the values in the Permanent Generate Parameters Table are set in the TEST level generate panel. The sample generate panel includes references to these variables and this should be kept in mind when customizing it.

HOLD Generate Parameters table

This table is non-persistent in that it is only used to pass generate parameters from the ISPW Client (for example, a user’s address space) to the batch Generate job as defined in M.CT/M.AD (Both the table name and batch job are defined here). This is required so that the job which eventually does the generate is not running under the authority of the user, but under the controlled ID of the Set Processor. The Batch Generate Job deletes the entries off this table after it submits the generate.

The model table is $WZXGENT which is defined in routine WZXGENT.

Generate System CustomizationThis section provides information on the various aspects to do with customization of the Generate processes. The following aspects are discussed:

• Components of the generation system

• Reference Data aspects

• Parts Registration

• Customizing Panels and Skeletons

• Customizing the Generate Parms

• Generate Jobs

• Other Considerations

Components of the Generation System

Generate System Components

The Generate system consists of routines, assembler programs and sample generate panels and skeletons. Since this system is part of the standard ISPW, the base routines required are already in the ISPW system datasets. Table 4-2 describes the components:

Table 4-2. Generate System Components

Component Type Component Name Component Description

CLST WZZPSG# Standard G routine

CLST WZXGEN Main generate routine

CLST WZXGENR Main generate routine for batch generates

CLST WZXGEN1U User generate exit routine

CLST WZXGENT Create generate information table routine

PANL WZUG*

Components starting with WZUG, WZUC and WZU@ in the SAMPLIB dataset are models/samples for the generate

SKEL WZUG*

SKEL WZUC*

SKEL WZU@*

ASM WZZA005 Copies from one PDS to another


Reference Data Aspects

This section describes which Reference data is required to be specified for the generation processes.

Specifying Different Component Types

Component Types that need to be generated need to be specified in the Maintenance Data option CT with the Generate Flag set to “Y”.

It is suggested that different flavors of the same Component Type are handled within Generate processing for that type rather than having a proliferation of types for each flavor.

Different types of COBOL programs may exist:

• Batch COBOL

• Batch COBOL with DB2

• CICS COBOL

• CICS COBOL with DB2

Rather than have a different Component Type for each flavor (e.g. CCOB, DCOB, COB etc.), it is better to have the single component type (e.g. COB) and manage differences in processing via generate options.

Different Target environments

Sometimes the generated objects may need to end up in different libraries depending up the Target Environment. This can be done by the following example definitions in the Reference data:

Define different classes of the target Component Type which will correspond to the different Target Environments (e.g. Have a Component Type of LOAD with a CLASS of <spaces> refer to the target libraries for a batch generate. And have another Component Type of LOAD but with a CLASS of CICS to refer to the target libraries for a CICS generate)

In the Associations definition specify 2 “G” Associations for the LOAD Type but identify one with a Target environment of “B” pointing to the Batch Load type and the other with a Target Environment of “C” pointing to the CICS Load type.

In the Generate panel, allow the user to specify what the Target Environment is for the generate and set the variable WTTENV to this value.

See Chapter 3, “Maintenance Functions” for a fuller description of all the attributes around Associations.

Specifying Generate Attributes in M.CT and M.AD

It is better to rely on the defined values for the generate panel, skeleton and table values in M.CT rather than define them in M.AD unless there is a definite requirement for different versions for a particular application. This makes maintenance easier.

Specifying Flags in M.AD

See “AD (F) - Flags” on page 3-18 for a complete description on what flag values to set to initiate generates.

ASM WZZAD08 Deletes from a PDS

ASM WZZA034 Scans LKED cards for aliases

Table 4-2. Generate System Components


Customizing Generate Panels and Skeletons

This section mentions issues to be considered when customizing the Panels and Skeletons.

Generate Panels and Skeletons

The TEST and HOLD panels and skeletons are tailored at each site. Model and sample panels/skeletons are supplied in the SAMPLIB dataset. Basic generate panels and skeletons will be tailored when going through the ISPW install process. Further site modifications are often made to these panels and skeletons to customize them to site requirements.

Separate panels are required for TEST and HOLD level processing because in TEST variables are modified, while the HOLD environment is “frozen” and the HOLD panel is mainly a “display only” panel except for some fields such as job class, sysout destination, etc.

Help Panels

Basic help panels for the generate are supplied in the ISPW base. It is important that each site update these panels to reflect the site options available and how they are used, since generate panels are frequently used and often require the most explanation.

Processing Variables Available

In general, the variables available for use in the generate panels and skeletons and the Generate User Exit are those variables found on the Generate Tables and those variables described in Chapter 6, “Exit Processing”.

Using Skeletons to generate JCL

The supplied sample skeletons code the generate JCL into separate skeletons and then embed them as needed into a “mainline” skeleton. This allows all generate functions (compiler, pre-processor, linkage editor, etc.) to be coded separately in a modular way. It is useful to study the structure of these supplied skeletons since it is a structure that works and requires minimal maintenance when changes are required.

Useful tips:• Change the default skeleton symbol for the “&” to a character not normally in JCL, e.g.

“~”. Use the skeleton command “)DEFAULT” to change the character.

• Put a minimum amount of JCL in the “mainline” skeletons. Use the processing to embed lower level skeletons using “)IM” skeleton commands.

• Use a variable to hold the name of the dataset or temporary file that is to be used as input, then each embedded skeleton uses and (optionally) modifies the variable as required. See the example below.

• Use “(OLD,PASS)” DCB parameters for temporary files. This allows the temporary files to be reused in a later step if necessary.

• Use a variable to hold the value for COND=JCL statements. This allows a condition code to be set in the “mainline” skeleton rather than hard coded in the JCL. The sample generate skeletons supplied with ISPW are good examples of this method of writing skeletons. They should be carefully studied and understood before the task of writing skeletons is started.

• Use “DBFT” in the command line of the ISPW Generate Panel to help with the debug of ISPF Skeletons.


Parts Registration

This section discusses the concept of Parts and the requirement for their Registration. A Part represents a component that belongs exclusively to a source component. Examples of Parts include DBRM, LOAD, LIST etc.

Parts are usually created during the Generate Process and it is necessary for ISPW to be told what Part is created and when. ISPW stores information in its repository about these parts (e.g. the warehouse key if it is in the warehouse).

For Parts created during a batch generate job there must be a step at the end of the job that registers these Parts to ISPW. There is also a way for Parts to be registered in REXX.

File Tailoring JCL to Register Parts

ISPW Provides sample skeletons that are embedded to correctly register the parts that are created. As the JCL is tailored, each step that creates parts also sets variables that are used in the final Part Register step to create the correct ISPW calls to Register the Parts. For example, the step that does the Linkedit also has an embed to another skeleton as follows:

The WZU@BLDL skeleton is as follows:

Figure 4-1. WZU@BLDL Skeleton

Note that these embeds are used for controlling the file tailoring only, no JCL is output at this point. Output JCL is tailored for the Parts Register step in the skeleton WZU@PART as follows:

Figure 4-2. WZU@PART Skeleton

The sample skeletons can register up to 9 parts within a single job. If more are required the samples will need to be changed.

)CM LINKEDIT PART REGISTRATION)CM ---------------------------------------------------------)IM WZU@BLDL)CM ---------------------------------------------------------

)TB 12)DEFAULT )~?!<|>)CM ----SET VAR FOR LINK EDIT PRIMARY INPUT)SET WZUPART~WZUPRTNO = GMT1LNAM)SET WZUNAME~WZUPRTNO = ~GMT1LNAM)SET WZUGENP~WZUPRTNO = LINK)SET WZUIOUT~WZUPRTNO = I)SET WZUPRTNO = ~WZUPRTNO + 1)CM ----SET VAR FOR LINK EDIT PRIMARY OUTPUT)SET WZUPART~WZUPRTNO = LOADNAME)SET WZUNAME~WZUPRTNO = ~LOADNAME)SET WZUGENP~WZUPRTNO = LINK)SET WZUPRTNO = ~WZUPRTNO + 1


Part Register Step – tailored

The tailored part register step for a typical compile looks like the following:

Figure 4-3. Tailored Part Register Step

Gen Processes

The parts are grouped into Generate Processes. The above example has two processes – CMPL and LINK. Parts must be registered within a Gen Process and each Gen Process must have one input registration and then 1 to 8 output registrations. In the above example, the CMPL process has an input part with the special name of “SOURCE”, which represents the source component. The LINK process has the input part of GMT1LNAM which in this example corresponds to the Object that was created in the compile. There is one output part for the CMPL process (GMT1LNAM – object), and two output parts for the LINK (LOADNAME – load, and GMT3NAME – listing).

Part Register input variables

The input variables to the Part Register are described in the table below:

//*********************************************************************//* DESCRIPTION: REGISTER GENERATED PARTS AT END OF BATCH PROCESSING//*********************************************************************//WZZEND EXEC PGM=WZZBP,COND=(4,LT)//STEPLIB DD DISP=SHR,DSN=ISPW.W30.QA.LOAD//WZZSCD DD DISP=SHR,DSN=ISPW.W3H.WZUSER(WZZSCD) /* A W30D *///WZZBPOUT DD SYSOUT=*//WZZBPIN DD *$DEFINE_PTR TASKIDX=7D42120923E6 PRCTOKEX=7D4330882836E7E7 WTASCVAR=SOURCE WTGENPRC=CMPL WTPNAME=TPROG06 WTINOUT=I$DEFINE_PTR TASKIDX=7D42120923E6 PRCTOKEX=7D4330882836E7E7 WTASCVAR=GMT1LNAM WTGENPRC=CMPL WTPNAME=TPROG06 WTINOUT=O$DEFINE_PTR TASKIDX=7D42120923E6 PRCTOKEX=7D4330882836E7E7 WTASCVAR=GMT1LNA WTGENPRC=LINK WTPNAME=TPROG06 WTINOUT=I$DEFINE_PTR TASKIDX=7D42120923E6 PRCTOKEX=7D4330882836E7E7 WTASCVAR=LOADNAME WTGENPRC=LINK WTPNAME=TPROG06 WTINOUT=O$DEFINE_PTR TASKIDX=7D42120923E6 PRCTOKEX=7D4330882836E7E7 WTASCVAR=GMT3NAME WTGENPRC=LINK WTPNAME=TPROG06 WTINOUT=O$DEFINE_PTLI \ TASKIDX=7D42120923E6 PRCTOKEX=7D4330882836E7E7


Not keeping Object? Use one process

If the customer site is not keeping the Object, it is preferable to change the skeletons such that a single process is used to cover both the compile and link. The WZU@BLDC and WZU@BLDL skels would need to be changed slightly to both use the same value for WZUGENPn. WZUBLDL would need to be changed as below to remove the registration variables for the input (as there is now no separate process for LINK).

Figure 4-4. Remove Registration Variables

Register Additional Generated Parts

Support for the registration of additional parts during the generate process, using the SIMP collection for parts not defined to use the regular GMT or LOAD name variables and datasets, has been added. This feature allows the customer to define additional generated parts beyond the standard LOAD and GMT modules. For example, if a Cobol program needs to linked into batch, IMS and CICS load libraries in the same generate execution, the IMS and CICS load modules can be registered into the SIMP collection with LOD_IMS and LOD_CIC values, respectively, in the WTASCVAR variables during the part registration phase of the generate process.

Table 4-3. Part Register Input Variables

Variable Description

WTASCVAR

This is the Associated Varname, and can be one of the following:

SOURCE – special name corresponding to the source component

LOADNAME – identifies the LOAD

GMT1NAME – identifies the component type that is defined against the association 1 – type 1

GMT2NAME - identifies the component type that is defined against the association 2– type 1

GMT3NAME - identifies the component type that is defined against the association 3– type 1

GMT1LNAM - identifies the component type that is defined against the association 1 – type 2

GMT2LNAM - identifies the component type that is defined against the association 2– type 2

GMT3LNAM - identifies the component type that is defined against the association 3– type 2

WTGENPRC Identifies the Generate Process.

WTPNAME Specifies the Part Name

WTINOUT Specifies whether this is registering the input part or an output part. Valid values are I or O.

TASKIDX and PRCTOKEX Internal IDs that ISPW requires.

)TB 12 )DEFAULT )~?!<|> )CM ----SET VAR FOR LINK EDIT PRIMARY OUTPUT )SET WZUPART~WZUPRTNO = LOADNAME )SET WZUNAME~WZUPRTNO = ~LOADNAME )SET WZUGENP~WZUPRTNO = GEN )SET WZUPRTNO = ~WZUPRTNO + 1


In order to support the extra parts in the Generate Process the dataset names defined for those parts need to be made available as variables to the generate skeletons. Any such variables can be initialized by a Compile Exit and a sample Compile Exit is provided via function WZTSIMPG# which is available in the base Clist library. The choice of variable names is left to individual sites to customize as needed.

The sample WZTSIMPG# Compile Exit defines the following values for variable WTASCVAR and library name variables to be used in skeleton processing to support additional parts.

Installation Considerations

Changes to support the extra parts at part register time are available as sample skeletons WZU@BLD and WZU@PART. These samples should be checked out into the SITE application and used to replace the existing versions. As provided, these samples add 7 extra parts (A through G).

Note: When registering parts in the SIMP collection an input part must also be defined in the collection.

Define pre-exits for the P, X and D operations for any type such as COB that may generate extra parts. The pre-exits should be defined in the M.EX table for each operation as follows:

Operation Pre-Exit------------- ----------- P ISPEXEC SELECT CMD(%WZTSIMP# &DEBUG) X ISPEXEC SELECT CMD(%WZTSIMX# &DEBUG) D ISPEXEC SELECT CMD(%WZTSIMD# &DEBUG)

Figure 4-5. Example: Pre-Exit for Operation P for COB types

Create a Compile Exit to define the dataset names used by the extra parts. Modify the provided sample WZTSIMG# as needed. The Compile Exit is enable by defining the name of the exit in variable CMPLEXIT in the generate panels (WZUGD and WZUGH if using the standard panels).

Table 4-4. Register Additional Generated Parts

WTASCVAR Library Variable

LOD_CIC W$LODCIC (CICS load library)

LOD_IMS W$LODIMS (IMS load library)

LOD_BAT W$LODBAT (Batch load library)

LST_CIC W$LSTCIC (CICS listing PDS)

LST_IMS W$LSTIMS (IMS listing PDS)

LST_BAT W$LSTBAT (Batch listing PDS)

Operation (KEY) ==> P

Exit Key (KEY) ==> COB

Description ==> SIMP COLLECTION PRE-EXIT

Preop Routine ==> ISPEXEC SELECT CMD(%WZTSIMP# &DEBUG)

Postop Routine ==>

Valid In Environment OUTS ==> (Y yes, N no)

TEST ==> (Y yes, N no)

HOLD ==> (Y yes, N no)

PROD ==> (Y yes, N no)

Update Last Operation Code ==> (Y yes, N no)


Figure 4-6. Example: The following panel change defines Compile Exit WZTSIMG#

Change the generate skeletons to create the required objects in the libraries defined by the Compile Exit variables and define the required variables for Part Register. Reference the example skeleton WZU@SIMP# as provided in the base SAMPLIB.

Customizing Generate Parms

New, site-specific generate variables may be added directly to the Extension Class WZGPARMS by using option M.EC, selecting the class and adding new entries to it. See “EC – Extension Classes” on page 3-40 for more details.

Generate Jobs

The standard Generate process invariably uses ISPF File Tailoring to create a job and then needs to submit it for processing. This section describes the different methods of job submission, their uses and how to indicate the preferred method

Generate Process

The Generation process consists of the following 3 steps:

Depending upon how ISPW is set up with regard to Job Submission, steps 2 and 3 can occur completely, partly or not at all within the client address space.

Job Submission Methods

There are 3 possible methods of generate job submission:

• Foreground processing and submit (i.e. steps 1,2 and 3 performed in foreground)

• Foreground processing and Demand of job that does the file tailoring and submission of generates in the background (i.e. steps 1 and 2 in foreground and step 3 in background).

)INIT

.HELP = WZHPSG#

&CMPLEXIT = 'ISPEXEC SELECT CMD(%WZTSIMG# DEBUG )'

Table 4-5. Generate Process

Step Description

1 Client requests a G (or P)

During this step, the ISPW Master Address space validates the request and puts the task(s) in process for a Generate. In the case of a Promote that requires a Generate, the task(s) will be put in process for a P, and once the P has completed, they will then be put in process for a G.

2 Generate Dialogue The Generate process begins and any defined Generate Panels are displayed.

3 File Tailor and submit Generate Job The Batch job is file tailored and submitted for execution.


• Set Execution processor does processing and submits the job (i.e. step 1 in foreground and steps 2 and 3 in background)

The method to use depends on security access considerations. If a single or special UserID is needed to access TEST or HOLD level datasets, then methods 2 or 3 are used. A single or special UserID would be needed in the event that only that UserID has been given access to the datasets. Because the job is submitted under the demanded job’s UserID, dataset access can be restricted only to that UserID.

Foreground Processing

Jobs submitted in this way mean that the UserID tailoring and submitting the JCL needs update access to any target datasets (e.g. load libraries). This is generally okay for the TEST environment, but once the components are “checked in” to a HOLD level it is generally considered poor security to allow the user direct update access to those datasets.

Demanded Job Processing

This is where a job which runs under a special UserID is able to be “demanded” to be submitted by the normal user (ISPW submits it on the user’s behalf). This job does the File Tailoring and submits the job, meaning that even though the ISPW user can have a generate submitted it is not running under their UserID and therefore is secure.

Set Processing

Sets can be used for generates. When a Set does the generate it is running under the UserID of the Set and so this is another secure way by which an ISPW user can request a generate yet not have access to the physical datasets. The important difference between this method and the Demanded Job method is that the generates come under ISPW’s Approval mechanism.

Foreground or Demanded?

For this discussion, having a Set submit the job falls under the arguments for Demanded. Typically, only 3 configurations are used:

Foreground in both TEST and HOLD.

In this configuration, developers will be performing the generate and updates to the source and load datasets. They will require full update access to TEST and HOLD datasets. This configuration is used most often for non-critical applications or applications where the HOLD environment does not need to be “frozen” during the QA or acceptance testing stage.

Foreground in TEST, Demanded in HOLD.

In this configuration, the developers will move the source from TEST to HOLD, but the generates (updates to the load libraries) will be done under the demanded job’s UserID. This configuration is used for critical applications where the HOLD environment is not to be tampered with during QA or acceptance testing. Most sites choose this option because it closes the security exposure of allowing a developer to change a load module after it has been signed off but before it moves to production. The developer only can update the HOLD environment via ISPW and the demanded batch job, thus ensuring that all actions are recorded by ISPW and nothing can slip by.

Using a single batch UserID to access HOLD ensures that the HOLD environment is not tampered with and therefore what was tested in HOLD will be moved into production.

Demanded in both TEST and HOLD.

This configuration is used mainly for special technologies that require batch processing under a single UserID.


Typical Scenario

Typically, the ISPW user will do a foreground generate at a TEST level and a demanded job will be used for all HOLD levels. Demanding a job via ISPW as opposed to using a Set is still useful for those situations where an individual job needs to be submitted or a special generate variable is required for a HOLD Generate (the HOLD Generate panel is not displayed for Set Generates and so this is not possible in Sets)

Setting the RTYP variable to control job submission

The variable RTYP is used to indicate what type of generate job submission is required. It may be set in the TEST/HOLD panels if overriding the default processing for the MEMBENV value.

The following table shows the values that can be set for RTYP:

Considerations for setting up Demanded Processing

The Demanded Jobname is defined in M.CT for the component type or overridden by the application value in M.AD. A value must be specified in M.CT (or overridden in M.AD) for the Generate Table (this table is used to pass the generate parameters from the client to the demanded job).

Other ConsiderationsThis section describes other considerations to keep in mind when customizing the generate processing.

Writing pre- and post- exits

CAUTION:If processing is not valid for both the TEST and HOLD environments, then coding that checks the MEMBENV variable for values ‘TEST’ versus ‘HOLD’, must be used to conditionally control the processing in the generate Pre- and Post- exits.

SYSLIB concatenation issues

SYSLIB concatenations for compiler and linkage editor steps are controlled by application (defined in M.AD) through the setup of the Include Associations.

In the case of installation-wide shared or “common” COPYLIBs or LINKLIBs or those shared across many applications, the simplest way to control inclusion of these “common” libraries in the generate, may be the modification of the following skeletons, rather than use of M.AD definitions:

WZU@IN$D (DCLGENs),

WZU@IN$S (LINKLIBs), and

Table 4-6. Setting the RTYP Variable

Environment RTYP Job Submission

TESTCL (default) Foreground submit.

TG Demanded generate.

HOLDRR (default) Demanded generate.

RO Foreground submit.


WZU@IN$M (MACLIBs).

Compile User ExitThis section describes the sample user exit provided for optional compile processing.

User Exit CMPLEXIT

This User Exit can be used to do any processing that is required prior to File Tailoring the generate JCL. This can include defining extra variables or manipulating the temporary tables $MACINC $SYSINC etc.

A Compile Exit is invoked by initializing the variable CMPLEXIT in a generate panel. The following panel example shows how a compile exit might be defined in the panel INIT section for a COBF member type:

IF (&MEMBTYPE = COBF)&CMPLEXIT = 'ISPEXEC SELECT CMD(%WZUCMPLX &DEBUG )'

A Compile Exit has to create a temporary table named $WZXGENX. This temporary table provides the names and values of any extra variables that are needed by the generate skeletons. All variables in this table are made available via the function pool prior to the FTINCL of the defined driver skeletons.

An example Exit can be found in the SAMPLIB member WZUCMPLX.

Sample Uses

This exit can be used to alter the sort order of the MAC/SYS/DCL tables

• TBSORT $MACINC FIELDS(WLILVLNO,C,D,WLISEQ,C,A)

• TBSORT $SYSINC FIELDS(WLILVLNO,C,D,WLISEQ,C,A)

• TBSORT $DCLINC FIELDS(WLILVLNO,C,D,WLISEQ,C,A)


5-1

Chapter 5.

5Custom Dialogs Chap 5

Custom Dialogs are used to define local customization and extensions to the ISPW product. This chapter gives an overview of this feature and a detailed description of the Dialog Definitions and the Dialog Editor that is used to create and maintain the Custom Dialogs. The exact processing and capabilities of a Custom Dialog will depend on where in the ISPW processing it is used. You may need to refer to other chapters for specific usage considerations.

The following topics are covered in this chapter:

• “Custom Dialog Overview”• “Dialog Definitions”• “Dialog Editor”.

Custom Dialog OverviewISPW Custom Dialogs are a new way to define local customizations and extensions to the ISPW product. This section gives an overview and describes the components involved.

Custom Dialogs can be very useful because local customization of ISPW has, until now, only been possible by the ISPW administrator editing and maintaining ISPF dialog panels. As these panels only operate in the 3270 interface, this new customization solution adds the crucial ability to work across all ISPW clients from the same definition.

Defining ISPW Custom Dialogs

An ISPW Custom Dialog is a new component type in the SITE application. It is managed in a similar way to the ISPF panels by using ISPW tasks, but using a component type of WDLG instead of PANL.

WDLG types are added, checked out, and promoted in the same way as ISPF panels. This is so they can be managed together with related SITE components types such as SKEL (ISPF Skeletons) and CLST (CLIST/REXX). When the ‘S’ operation is used to edit them, an ISPW-provided Dialog Editor is invoked. The Dialog Editor allows the administrator to define the layout and processing of the content to be displayed to the user for that dialog.

New configuration options are provided within the M table administration to specify where a custom dialog should be used. For the Generate Options dialog, a new field of Cust Gen Panel appears on the M.CT definition for a component type and on the Type entry of M.AD definitions.

Functioning of ISPW Custom Dialogs

If a Custom Dialog name has been specified, then at designated points in the ISPW processing, the custom dialog will be processed. In the current release, this is only supported when using the Topaz Workbench client—and only for the Generate Options dialog.

A Custom Dialog definition is stored in a PDS member in an ISPW internal XML format. These are loaded by the central ISPW server started task (CM task) where they can be retrieved by any ISPW client interface. To provide similar characteristics to the current


ISPF panel usage, the appropriate SITE concatenation will be used based on the user’s RTCONFIG setting. This allows for testing of changes on a user-specific basis.

ISPF Panels Still Needed—For Now

The existing local SITE ISPF panels used for the Generate Parm display in 3270 are still required in this release. Such panels typically contain site-specific code in the panel processing section which ensures all the variables needed by the local ISPF skeletons used to create the batch generate jobs are assigned the desired values.

The capabilities of ISPW Custom Dialogs will be expanded in future ISPW releases, with the ultimate goal being to eliminate the need for ISPF panels.

Dialog DefinitionsA Dialog Definition specifies the layout and processing of an ISPW Custom Dialog. The Dialog Definition is created and maintained using the ISPW-supplied Dialog Editor.

The following sections describe some of the key terms and concepts of a Dialog Definition:

• Dialog ID• Dialog Type• Dialog Title• Dialog Entries• Field ID.

Dialog ID

The Dialog ID is the name by which the Dialog is referenced. It must be the same as the component/PDS member name of the WDLG type that holds the definition. This ID is then used in various M table entries to specify where the dialog is to be used.

Dialog Type

The variables and processing available to a Custom Dialog will depend on where in the ISPW processing it is used. A Dialog Definition has a Dialog Type to specify the type of usage. Currently the only supported type is ‘GP’ for the Generate Parm dialog.

Dialog Title

The Dialog Title specifies the main title that will appear at the top of the Dialog display.

Dialog Entries

The Dialog Definition can have one or more entries that specify the content and layout of the display. The display can be organized into ‘Areas’ where each area can be a group of ‘Fields’ with an optional heading and outline. The type of entry is determined by a ‘Tag’ which has a value of ‘Area’ or ‘Fld’. An Area tag is used to define the start of each Area on the display. It can then be followed by one or more Fld entries which define the individual fields to be displayed within that Area.

Field ID

A Fld tag specifies a field to be displayed or used in the dialog, and each field is referenced by a unique Field ID. To be consistent with existing ISPW usage in ISPF panels, a Field ID is an 8-character name that is the same as the current ISPF variable names.

Custom Dialogs 5-3

ISPW customization has always worked with a set of ISPF variables, referred to as PROJVARS, of which a small subset could be updated. In addition to the PROJVARS variables, some other variables have been available for use depending on where in the processing the customization was being applied.

Based on the ID specified, ISPW will determine whether the Field is a known ISPW variable. If unknown, it will be treated as a ‘Local’.

Dialog EditorThe Dialog Editor is a new component of ISPW. The Editor gives administrators a new way to create customization dialogs. In the initial version of this enhancement, the dialogs are only for the Generate processing and are only displayed within the Topaz Workbench.

Using the Dialog Editor to Create a Custom Dialog

This section provides an overview of how you would use the Editor to create a dialog.

Once you are in the Assignment, you issue the Add command. An example is shown in Figure 5-1.

Figure 5-1. Add Command in SITE Assignment

Notice that the WDLG type is shown in the list of available types. You would enter the Type as WDLG and give the dialog a name in the Name field. An assignment with WDLG types is shown in Figure 5-2.

Note: New ISPW installations will already include the configuration of the WDLG type as part of the installation process. For existing ISPW installations where the WDLG type is not already configured, refer to the ISPW Upgrade Guide for details on how to add the WDLG component type to the SITE application.

ISPW ADD TASK TO ASSIGNMENT SITE000006 COMMAND ===> CUSTOM DIALOGS Type (See list of valid types below ) Name Action _ (C-Compile, D-Delete, F=Fallback, H-History ) Application SITE (Default=SITE ) Stream SITE (Default=SITE ) Path TEST (TEST ) Filter ( " PROD HOLD ) Release (Default= ) Import N (Import From External Source Y/N ) C CLST MSGS PANL SKEL WDLGPlus module type DATAPress ENTER to add entry, END to terminate


Figure 5-2. SITE Assignment with WDLG Type

The screen shown in Figure 5-3 is displayed when you select the new entry. You can only update the title in the Dialog Title field.

Figure 5-3. ISPW Dialog Definition Screen - Attributes

When you have updated the title and pressed Enter, the screen shown in Figure 5-4 is displayed.

Figure 5-4. ISPW Dialog Definition Screen - Edit

You would select the Area item to get started creating the dialog. The screen shown in Figure 5-5 is displayed.

ASSIGNMENT SITE000001: IVP1 - FIRST ASSIGNMENT Row 1 of 1Command ===> Scroll ===> PAGE More -->——————————————————————————————————————————————————————————————————————————————| Select(/) Add Approve Close Join Reset Show/Hide Work ++/-- |—————————————————————————————————————————————————————————————————————————————— Type Name Lev Op A User Appl Date MM DD Time Status SKEL WZU@MTYP TEST S ACMJET0 SITE 2017-03-23 09:56 WDLG END2END TEST S ACMJET0 SITE 2017-03-22 09:29 WDLG END2END1 TEST C ACMJET0 SITE 2017-03-22 09:32 WDLG END2END2 TEST S ACMJET0 SITE 2017-03-24 13:53 WDLG GENERATE TEST S ACMJET0 SITE 2017-03-03 13:57 WDLG M0000001 TEST S ISPWCS0 SITE 2017-03-02 10:10 WDLG M0000002 TEST S ICABZS0 SITE 2017-02-15 14:01 WDLG NEWONE TEST S ISPWCS0 SITE 2017-03-08 20:40 WDLG WFFGEN TEST S ISPWCS0 SITE 2017-03-02 10:25 WDLG WZUGD TEST S ISPWCS0 SITE 2017-03-08 18:00 WDLG GENERATE PROD P ICABZS0 SITE 2017-02-23 18:09 WDLG M0000001 PROD P ICABZS0 SITE 2017-02-15 14:00 WDLG M0000002 PROD P ICABZS0 SITE 2017-02-15 14:00 WDLG M0000003 PROD P ICABZS0 SITE 2017-02-15 14:00------------------------------- Bottom of List -------------------------------

ISPW ISPW Dialog Definition - Dialog Attributes TESTDLG Command ===> Confirm and/or Change the Dialog Attributes. Dialog Id ==> TESTDLG Dialog Type ==> (GP) Dialog Title ==> Press Enter to save and continue, or End to cancel

ISPW ISPW Dialog Definition - Edit TESTDLG Row 1 to 1 of 1 Command ===> Scroll ===> CSR Line Commands: I Insert, S Select, D Delete, M Move( A After, B Before) CMD Tag Col Grp ID Label Type Size Area ******************************* Bottom of data *******************************

Custom Dialogs 5-5

Figure 5-5. ISPW Dialog Definition Screen - Editing Area

The ID field is used in a Fld definition that can toggle the Area between being visible and invisible.

• The Label is the dialog title.

• The Cols field is required. It must be a positive integer without a sign.

• Specifying a Y in the Group field cause the Area and its Flds to be enclosed in a box on the dialog.

Figure 5-6 shows an example of a completed entry.

Figure 5-6. ISPW Dialog Definition Screen - Completed Entry

Once you have an Area, you now add Flds to it. You would issue an Insert command on the Area as shown in Figure 5-7.

ISPW ISPW Dialog Definition - Edit Command ===> Enter required details: Area/Fld ==> Area ID ==> Label ==> Area: Cols ==> Group (Y/N) ==> Fld : Type ==> (text, check, list, combo, radio) Size ==> Validator ==> Focus(Y/N) ==> Required(Y/N) ==> ReadOnly(Y/N) ==> Check: True ==> False ==> Toggle Area ==> Radio/Combo/List: Value(Label) ==> Press ENTER to complete the change or END to terminate Note: You can add a new entry by overtyping the Key with a new unique value

ISPW ISPW Dialog Definition - Edit Command ===> Enter required details: Area/Fld ==> Area ID ==> Label ==> Grouped Area Area: Cols ==> 1 Group (Y/N) ==> Y Fld : Type ==> (text, check, list, combo, radio) Size ==> Validator ==> Focus(Y/N) ==> Required(Y/N) ==> ReadOnly(Y/N) ==> Check: True ==> False ==> Toggle Area ==> Radio/Combo/List: Value(Label) ==> Press ENTER to complete the change or END to terminate Note: You can add a new entry by overtyping the Key with a new unique value


Figure 5-7. ISPW Dialog Definition Screen - Insert Command

The screen shown in Figure 5-8 is then displayed. The panel is entirely empty.

Figure 5-8. ISPW Dialog Definition Screen - Empty Panel

You must specify Fld. The ID, Type, and Size fields must be specified as well.

• The ID is the name used to reference the field.

• The Type is one of the values shown in the panel.

• The Size defines the size of a text Type or the number of items in a List type.

• The Validator contains validation functions.

• For a checkbox, the true and false values can be specified.

• The Toggle Area contains an Area ID that can toggle between being visible and invisible based on the state of the checkbox.

• The Radio/Combo/List specifies the list of values to be displayed.

Figure 5-9 shows a completed entry.

ISPW ISPW Dialog Definition - Edit TESTDLG Row 1 to 1 of 1 Command ===> Scroll ===> CSR Line Commands: I Insert, S Select, D Delete, M Move( A After, B Before) CMD Tag Col Grp ID Label Type Size i Area 5 Y Test 001 ******************************* Bottom of data *******************************

ISPW ISPW Dialog Definition - Edit Command ===> Enter required details: Area/Fld ==> ID ==> Label ==> Area: Cols ==> Group (Y/N) ==> Fld : Type ==> (text, check, list, combo, radio) Size ==> Validator ==> Focus(Y/N) ==> Required(Y/N) ==> ReadOnly(Y/N) ==> Check: True ==> False ==> Toggle Area ==> Radio/Combo/List: Value(Label) ==> Press ENTER to complete the change or END to terminate Note: To add a new entry the Key must be unique

Custom Dialogs 5-7

Figure 5-9. ISPW Dialog Definition Screen - Completed Panel

Figure 5-10 shows an example of a completed dialog definition.

Figure 5-10. ISPW Dialog Definition Screen - Completed Dialog Definition

The XML associated with the completed dialog definition is shown in Figure 5-11.

ISPW ISPW Dialog Definition - Edit CMPLEXIT Command ===> Enter required details: Area/Fld ==> Fld ID ==> CMPLEXIT Label ==> Compile Exit Area: Cols ==> Group (Y/N) ==> Fld : Type ==> text (text, check, list, combo, radio) Size ==> 80 Validator ==> Focus(Y/N) ==> N Required(Y/N) ==> N ReadOnly(Y/N) ==> N Check: True ==> False ==> Toggle Area ==> Radio/Combo/List: Value(Label) ==> Press ENTER to complete the change or END to terminate Note: You can add a new entry by overtyping the Key with a new unique value

ISPW ISPW Dialog Definition - Edit END2END1 Row 1 to 14 of 14 Command ===> Scroll ===> CSR Line Commands: I Insert, S Select, D Delete, M Move( A After, B Before) CMD Tag Col Grp ID Label Type Size Area 1 Y Grouped Area Fld CMPLEXIT Compile Exit text 80 WZGWORK Fld CMPLUSER Compile User text 8 WZGWORK Fld DATETIME Date and Time text 8 WZGWORK Area 1 Y Bind Details Fld ACTIAPPL Action Bind Appl text 4 Local Fld ACTICLVL Action Bind Curr Lvl text 4 Local Fld ACTIDBRM Action Bind DBRM Library text 44 Local Fld ACTINAME Action Bind Member Name text 8 Local Area 4 Y Program Details Fld WTGSQL SQL Flag check PROJVARS Fld WTGCICS CICS Flag check PROJVARS Fld WTGPROG Program Flag check PROJVARS Fld WTGIMS IMS Flag check PROJVARS ******************************* Bottom of data *******************************


Figure 5-11. Completed Dialog Definition XML

Once you have completed the dialog, you must issue a dialog refresh command. The dialog will not be available to Topaz Workbench until this done. Figure 5-12 shows what a dialog looks like in Topaz Workbench when you select Generate with Parms on a COBOL program.

Figure 5-12. ISPW Custom Dialog in Topaz Workbench

Menu Utilities Compilers Help-------------------------------------------------------------------------------- BROWSE ISPW.W3I.SITE.TEST.WDLG(END2END1) - 01.00 Line 00000000 Col 001 080 Command ===> Scroll ===> CSR ********************************* Top of Data **********************************<?xml version="1.0" encoding="UTF-8"?><tns:Dialog id="END2END1" label="Dialog Editor test 1" type="GP" xmlns:tns="http://www.compuware.com/ISPWCustomGenerateDialog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.compuware.com/ISPWCustomGenerateDialog ISPWC <tns:area options="group" label="Grouped Area" columnCount="1"> <tns:field id="CMPLEXIT" label="Compile Exit" type="text" size="80" valu <tns:field id="CMPLUSER" label="Compile User" type="text" size="8" value <tns:field id="DATETIME" label="Date and Time" type="text" size="8" valu </tns:area> <tns:area options="group" label="Bind Details" columnCount="1"> <tns:field id="ACTIAPPL" label="Action Bind Appl" type="text" size="4" v <tns:field id="ACTICLVL" label="Action Bind Curr Lvl" type="text" size=" <tns:field id="ACTIDBRM" label="Action Bind DBRM Library" type="text" si <tns:field id="ACTINAME" label="Action Bind Member Name" type="text" siz </tns:area> <tns:area options="group" label="Program Details" columnCount="4"> <tns:field id="WTGSQL" label="SQL Flag" type="check" value="@match(TSGR. <tns:item value="true" return="Y"/>

6-1

Chapter 6.

6Exit Processing Chap 6

This chapter gives an overview of how ISPW handles different processing requirements through the use of Exits.

How Exit Processing worksISPW Exit Processing determines the operations performed against tasks and is key in providing the power whereby users can issue the same operation against any type of object and have the appropriate processing take place.

When does Exit Processing take place?

Any time that an operation is issued against a Task (e.g. “S”, “B”, “G”),

ISPW looks for any exits that exist for that operation code. Both the Standard ISPW processing and other special processing are defined in the Exits Table.

Where are Exits defined?

Exits are defined in option EX as part of the Maintenance Functions. See “EX – Exits” on page 3-46 on defining M.EX data.

What types of Exits are there?

There are two types of Exits defined in M.EX:

• Base processing to define the Operation

• Extended processing in addition to that defined for the base operation

Base Operations

An entry identified with an exit key of ‘$$$$’ is a base operation exit. ISPW looks for the base exit first as it contains information about the type of exit. ISPW then does a lookup for Global exits (those that have an exit key of ‘####’) and lastly looks for exits that may pertain specifically to the Technology or Component Type.

Example:

The standard exit (identified by “$$$$”) for the Select for Edit routine has a pre-op value of “ISPEXEC SELECT CMD(%WZZPSS# &DEBUG)”. This is executed when a user types ‘S’ against a task.

Extended Processing

Special processing requirements may need special exits that are executed for all Technologies and Component Types or are driven off the Technology or Component Type fields. The pre-op and post-op routines specify these special routines. The following screen shot shows an example of a special exit for a QMF Technology type.


Figure 6-1. Extended Processing

For the (C)heckout of a QMF object, ISPW will see that there is an exit specified for the technology QM and if there is a pre-op specified will run this before base checkout processing (subject to the return codes mentioned in the next section). If there is a post-op specified it will be run after standard ISPW processing.

Controlling Processing from within user exits

If a pre-op exit for a Component Type or technology exists, it controls the subsequent processing by passing the following return codes:

For certain technologies or operations, being able to replace standard ISPW processing completely by using the proper return code is sometimes useful.

Example

For Telon, the “S” exit takes the user directly into the TDF facility and so the base exit that takes the user into ISPF Edit is not invoked.

Post-op Exits

If a post-op exit for a Component Type or technology exists, it will be executed only if all the processing to that point has worked. If the post-op encounters a problem, the operation is still processed as successful. This is required because post-ops cannot always back out the

ISPW M.EX PROCESSING EXITS TABLE (QA) BROWSEMODECommand ===> Scroll ===> CSRList Commands: LOC Locate Entry, U Update Mode Line Commands: S Select OP ExitKey Description A $$$$ ISPW STD ADD OPTION A CSP CSP V3 GET RWMSL / ADD PLANS A C4 CSP V4 GET RWMSL / ADD PLANS AL QM ISPW - QM - STANDARD QMF ALLOCATION AX $$$$ ISPW STANDARD AX COMMAND B $$$$ ISPW STANDARD BROWSE OPTION B LC (LOAD CONTROL): LOAD MODULES B PLAN DB2 PLAN PRE-EXIT TO BROWSE PLAN ATTRIBUTE TABLE B QM ISPW - QM - BROWSE QMF FORM IN QMF BL $$$$ ISPW - Browse Listing C $$$$ ISPW STANDARD CHECKOUT OPTION C C4 CSP V4 COPY PROD ESF TO TESTMSL C HFS HFS BYPASS COPY EXIT C LC (LOAD CONTROL): LOAD MODULES C PLAN DB2 PLAN POST-EXIT TO UPDATE PLAN XREF TABLE C QM ISPW - QM - IMPORT PDS MEMBER INTO QMF C VA VAG DUMMY OUT STD COPY CM $$$$ ISPW STANDARD COMPARE OPTION CU $$$$ ISPW STANDARD CLEANUP LINE COMMAND D $$$$ ISPW STANDARD DELETE OPTION D CSP CSP V3 DELETE PANEL DISPLAY D C4 CSP V4 DELETE PANEL DISPLAY

Table 6-1. Controlling Processing

Return Code Description

0 Pre-op worked. Standard processing continues.

2 Pre-op worked. Standard processing is omitted.

Other values Pre-op failed. Standard processing and possible post-op processing is not executed.

Exit Processing 6-3

changes made by standard processing. Therefore, any critical processing should not be in a post-op.

ISPW Task data available within an exit

When an exit is called, certain information for the Task in the way of variables is available to be used. Two categories of data are available:

• Read-only variables

• Update variables (only for Update Operations). See “EX – Exits” on page 3-46 (Reference Data Options) EX - Exits.

Calls to ISPW from within an exit.

It is possible to make calls from within an exit to get further information from the server. The REXX function WZZTSI is used for this, but make sure that only the external calls (starting with “#”) are used, as the other calls may change between ISPW versions. See Appendix B - Reference Data Calls for description about what Reference Data Calls are available and what information is returned in them.

Read-Only Variables

The information below is available to the exit.

Table 6-2. Read-Only Variables

Read-Only variable Description

WTMNAME Component Name

WTAPPLID ApplicationID

WTSTRM Stream Name

WTCLVL Current level

WTMTYPE Component Type

WTCSLIB Source library name for component version

WTCSLIBT Source library type for component version (e.g. PDS)

WTCLLIB Load library name for component version

WTCLRTN Retain Flag for Load

WTCGMTS1 Library name for GMT1 Seq 1 Association

WTCS1RTN Retain Flag for GMT1 Seq 1 Association

WTCGMTL1 Library name for GMT1 Seq 2 Association

WTCL1RTN Retain Flag for GMT1 Seq 2 Association





WTCS3RTN Retain Flag for GMT3 Seq 1 Association



WTTENV Target Environment

WTNLVL Next level


Update Variables

These variables can be set in an exit.

WTPLVL Previous level

WTSLVL Start level

WT0LVL Prod level

WTLVLS String containing levels in the Path

WTPSLIB Source library for previous level

WTPSLBT Source library type for previous level

WTPLLIB Load library for previous level

WTPLLBT Load library type for previous level

WTNSLIB Source library for next level

WTNSLBT Source library type for next level

WTNLLIB Load library for next level

WTNLLBT Load library type for next level

WZVPS01 Extension variable 1 – ISPW use only




WZVPS01U User Extension variable 1




Table 6-2. Read-Only Variables

Table 6-3. Update Variables

Update Variables Description





WTTENV Target Environment

LOADNAME Load name for component version

GMT1NAME Component Name for GMT 1 Seq 1 Association



GMT1LNAM Component Name for GMT 1 Seq 2 Association



Exit Processing 6-5

Why create new Exits?

Exits are generally created for two reasons:

• To extend the processing of a base exit for a specific Component Type or Technology

• Creation of a completely new ISPW Operation

Extend Processing

The following steps should be followed when writing an exit to extend the functionality of an existing operation:

Creating new operations

The M.EX maintenance option is used by ISPW to control its own operations and is also the place where new operations can be defined. The codes used for ISPW’s own operations should not be changed.

The following steps should be followed when creating new ISPW Operations:

Table 6-4. Extend Processing

Step Action

1Write the routine that will be invoked to execute the operation. Have a look at any ISPW standard processing clist or REXX (e.g. WZZPSB#) to see how best to write an exit giving special consideration to the beginning of the exit with respect to tracing in debug mode.

2

Update the exit table under option M.EX to add an exit for the operation but having an “Exit Key” value applicable to the type of exit being created. This “Exit Key” value will either be a Component Type or Technology. See Chapter 3, “Maintenance Functions” (Reference Data Options) M.EX - Exits for a description of the attributes.

Table 6-5. Creating New Operations

Step Action

1Write the routine that will be invoked to execute the operation. Have a look at any ISPW standard processing clist or REXX (e.g. WZZPSB#) to see how best to write an exit giving special consideration to the beginning of the exit with respect to tracing in debug mode.

2

Update the exit table under option M.EX to create the new operation value with an exit key of ‘$$$$’ to establish a ‘standard’ exit. All ISPW exits, whether they are supplied as base ISPW processing or user-written, must have a ‘$$$$’ definition as it describes basic behavior of the exit apart from the routine to call. It is best to select an existing operation whose behavior most resembles the requirements of the new option, and overtype the key value to add the new entry. For standard exits, the routine to be invoked will be coded in the Pre-op Routine field and the Post- Op Routine field is left blank. See Chapter 3 – Maintenance Functions (Reference Data Options) M.EX – Exits for a description of the attributes.

3 In M.ER update the variables WVOPALL (for non-update operations) and WVOPSOME (for update operations) to reflect the new operation.

4 Update the WZZPS## help panel (WZHPS2#) to add the new operation. Create and tie in a help panel for the operation itself.


7-1

Chapter 7.

7Set Processing Chap 7

This chapter describes Sets and their attributes, how the approval process works and the set scheduling system.

Set Overview and Attributes

What is a Set?

Sets are used to group together components for processing and control the approval process. Task operations that need to be approved must be performed using a set. Sets can also be used to carry out task operations asynchronously from the user’s online session. ISPW’s optional Deploy feature also requires that Sets are used for the creation of Deploy Requests.

See the ISPW User Guide for details on creating and using sets.

Set Attributes

Each set has a number of attributes to describe the status of phases of the set processing. The main statuses are:

• Task Status – whether tasks can be altered,

• Approval Status – the state of approval,

• Processing Status – describes the state of execution.

Task Status

This indicates whether the set has been Locked or Unlocked and represents the action that can be taken on tasks that are associated with the set. It can be specified on the set create.

Note: Regardless of what the task status is, only non-update operations can be performed against tasks that are associated with a set.

The Task States are described below:

Table 7-1. Task States

State Description

Unlocked Tasks can be added and removed from the set. No approval processing is possible.

AnalyzePromote Analysis has been performed to check for related components and found that errors prevented the processing from continuing. The Set cannot be locked in this state.

Review Promote Analysis has been carried out and the Set is eligible to be Locked. Any promote analysis messages will be recorded against the Set.

Locked Tasks cannot be added or removed from the set. Approval processing can begin.


Unlock and Lock Commands

It is possible to toggle between the Task states by issuing the Unlock and Lock commands against the Set. See the ISPW User Guide for details.

If an unlocked Set is locked, the approval rules are used to build an approver list, which is attached to the Set. If a locked Set is unlocked, the approver list is discarded and any approvals that have been granted are lost.

Approval Status

The Approval status is maintained by ISPW and indicates the approval state of the Set. It can be one of the following values:

Processing Status

This shows the different states of execution for the Set. The user can specify when the execution will begin by choosing one of the two user-specified states. ISPW maintains the Processing status once Set execution begins. All of the Processing states are described below.

Processing States – User-specified

This indicates how the execution of the set will begin. It can be specified on set creation or the set Modify.

Processing States – ISPW maintained

ISPW maintains this status to show what stage the set execution is in. The states are described below:

Table 7-2. Approval States

State Description

Unknown Set is unlocked.

Required One or more approvals are required before the Set can execute.

Not Required No approvals are required for this set to execute.

Approved All the required approvals have been granted and the set is free to execute.

Denied One or more approvals have been denied. The set cannot be executed.

Table 7-3. Processing States

State Description

Released The set will be executed once the Set is locked, approvals are granted (if required) and no other constraints exist to stop the set executing (e.g. time).

Held The set will not be executed if the Set is locked and approvals are granted. The set has to be manually updated to the Immediate state.

Table 7-4. Processing States - ISPW Maintained

State Description

Set Processing 7-3

Starting Sets on Other LPARs

Overview

By default, Sets are started on the same LPAR as the ISPW CM Task (The CM Task issues the Start Command). ISPW provides the capability to start Sets on other LPARs if this is required.

How it works

Special M.ER variables are recognized to map the Set Class to a SystemID.

If such a variable is defined, the START command for the Set is wrapped in a ROUTE command, targeted at the required system (LPAR).

0.ER VariableThe format of the M.ER variable name is SX$CLS$ followed by the class name,

e.g. SX$CLS$D for Set Class D. The value assigned to this variable must be a valid MVS SystemID.

Example

The following is an example M.ER variable for class D.

Waiting

The Set has now been passed over to the ISPW Set Scheduling system and is waiting to be executed. It may be waiting for a number of reasons:

Time – the implementation date and time hasn’t been reached.

Class – no set classes are currently available.

Queue – the queue already has a Set executing.

Dispatched – when the time, class and queue constraints are removed, the Set is dispatched.

Executing

The Set is now executing under the control of the set execution processor. During execution, the Set may pass through a number of phases:

Executing – the Set is being processed.

Sleeping – Set processing has been suspended for asynchronous events (e.g. waiting for a generate to complete).

Ready – the asynchronous events have completed and the Set is now ready to perform further processing.

Dispatched – the Set is dispatched after any constraints have been removed.

Stopping The Stop command has been entered against an executing Set. At the next available opportunity the Set will be stopped and the Set state will be “Failed”.

FailedSet processing has failed. The Set log can be browsed for more details. If a task operation has failed, the task will be left In Process. The Restart command can be entered against the Set and processing will resume from the point of failure.

CompleteSet processing has successfully completed. All tasks are now available to perform further operations. No further processing can be performed by this Set. It can be closed.

Terminated The Terminate command has been entered against a failed Set. No further processing can be performed by this Set. It can be closed.

Table 7-4. Processing States - ISPW Maintained


Figure 7-1. Example M.ER Variable for Class D

In the above example, Sets that are started with an ISPW Class of “D”, will be routed to the system “S390” for execution.

Approval ProcessTask operations can be controlled through an approval process. The approval process can only be used as part of Set processing.

Approval and Approval Rules

The authorization process is referred to as an approval. The rules that define which authorizations are required are called approval rules.

Approval Rules

These are the rules that control which Approvers must grant their approval before the operation can be processed on the components that are covered by the rule.

Approvers

The user or group of users who can grant approval are called Approvers. This is a 10-character name that is mapped to a resource controlled by the external security system (e.g. RACF, ACF/2, etc.). Therefore, the actual UserIDs who are authorized to grant approvals are controlled by the external security system and not by ISPW. See Chapter 8, “Security” for details.

Is Approval Required?

Each approval in the approval list is marked as Required or Not Required. Required means that approval must be granted before the set can be executed. Not Required means that the set can be executed without the approval being granted, but the set will still be listed as requiring approval. It can be useful where emergency fixes are necessary when some of the normal approvers, such as Audit, are not available to make the approval but want to be able to approve the set after the event.

Quorums

Quorums are supported so that a specified number of distinct UserIDs must grant approval for a given approval rule.

Viewing Approval Information

The container list can be used to view sets and their components. It can also be used to make approvals. The approver group name can be specified so that all the sets that require approval by that approver will be displayed. See the ISPW User Guide for details.

ISPW M.ER BROWSE EXTERNAL REFERENCE DETAIL (FIX)Command ===>Type Code (KEY) ==> SX$CLS$D View Code (KEY) ==> Description ==> Target system ID for sets of class D

Variable/Dsname ==> S390(Fully qualified if data set name, no quotes)Press END to return

Set Processing 7-5

Change TypesChange types relate to the type of change that a Set was created for and provide additional flexibility. They allow Sets to be grouped to specify different:

• approval rules

• scheduling priorities

ISPW places no inherent meaning in these types it merely uses them to determine the processing to use for any given Set.

Default Change Types

ISPW provides 3 default change types:

• Standard – normal changes,

• Emergency – urgent fixes,

• Incidental – a special non-urgent change.

A site may add additional user-defined changed types. See M.CH.

Set ExitsThis section describes the sample set exits provided for optional set processing.

Set Exit PROCEXIT

This Process Exit can be used to do any processing that is required once the set has been created.

A Process Exit is invoked by initializing the variable PROCEXIT in a generate panel. The following panel example shows how a process exit might be defined in the panel )PROC section to implement the exit when variable WSXOPTN is set to DBUG:

IF (&WSXOPTN NE &Z)

&EXTNCLAS = 'WSXEXTN'

&EXTNVARS = 'WSXOPTN' VPUT (EXTNVARS WSXOPTN) IF (&WSXOPTN EQ 'DBUG')

&PROCEXIT = 'WSX@DBUG'

A Process Exit can be used to manipulate the extension variables (EXTNVARS) defined to an extension class (EXTNCLAS). The manipulated values are then passed into the remaining set process.

Example Exits can be found in the CLIST members WSX@DBUG and WSX@DML.

Set Exit OPEREXIT

Similar to the Process Exit, the Operation Exit can be used to do any processing that is required for a specific operation once the set has been created. It is executed immediately following any specified Process Exit.

An Operation Exit is invoked by initializing the variable OPEREXIT in a generate panel. The following panel example shows how a process exit might be defined in the panel )PROC section to implement the exit for operation UD (Update Deploy Component Details):

IF (&OP EQ 'UD')


&OPEREXIT = 'WZU@UDS#'

&EXTNCLAS = 'WSXEXTN'

An Operation Exit can be used to manipulate the variables defined to an extension class (EXTNCLAS). The manipulated values are then passed into the remaining set process.

An example Exit can be found in the CLIST member WZU@UDS#.

Set Pre-exit for Operations

These exits are defined to M.EX (See Chapter 3 –Maintenance Functions: Reference Data: Ex - Exits) to run prior to the Set Create Panel being displayed.

These exits provide support for an Exit Validation point which would enable an interactive dialogue with the user based on the Operation code for which the set is being created. Other operation pre-exits defined in M.EX run in the background as part of the Set Processing so they cannot provide the sort of end user interaction that is sometimes required.

To enable this feature in ISPW, the M.ER (See Chapter 3 –Maintenance Functions: Reference Data: ER – External References) variable WZUOPVER must be set to 'Y'. This just enables support the new exit point and ensures that the appropriate validation exits will be called for any operations that are defined with an exit key of @@@@.

A new Exit is activated to validate the operation if the M.EX table has an entry with an Exit Key of @@@@ for the applicable operation code and Member Environment. If the exit wants to fail the operation then it should return with a code of 4, otherwise it should return with code 0. Note: If the M.ER variable is not defined with a value of 'Y' then these M.EX table definitions will be ignored.

The operation code is presented in the shared pool variable OPCODE. See the sample exit WZUOPVER for a list of the other variables that are available. The Sample Exit provided shows how to limit validation to promote operations from the signout level - The sample will prevent any component with the name STOPME from being promoted.

Set Create Pre- Exit

This exit is similar to the Set Operation Pre-exit in that it is executed prior to the Set Create Panel being displayed, but this exit is executed regardless of the OPCODE being processed by the set and does not require M.EX table entries.

To enable this feature in ISPW, the M.ER (See Chapter 3 –Maintenance Functions: Reference Data: ER – External References) variable WSETCRPX must be added to the table.

Below is a sample definition of this variable which instructs ISPW to execute clist WZUSETPX prior to displaying the Set Create Panel.

Figure 7-2. Set Create Pre-Exit

ISPW M.ER ADD EXTERNAL REFERENCE DETAIL (W3P)Command ===>Enter required details:Type Code (KEY) ==> WSETCRPX View Code (KEY) ==> $TAB Description ==> USER SET CREATE PRE-EXIT

Variable/Dsname ==> ISPEXEC SELECT CMD(%WZUSETPX &DEBUG)(Fully qualified if data set name, no quotes)Press ENTER to complete the change or END to terminate Note: To add a new entry the Keys must be unique

Set Processing 7-7

If the key value, View Code, is set to $TAB, then the selected tasks being passed to the Set Create process will be made available in the table

$WSETCRn, where n=current value assigned to variable ZSCREEN.

Note: If the Table of Tasks is not required then use a blank View Code in the M.ER definition above. Creating a table to show all tasks selected could be an unacceptable overhead for sites with very large (1000+) releases.

Sample Exits can be found in the CLIST members WZUSETPX (uses $TAB) and WZUSETPZ (does not use $TAB).

Set Lock Exit

Set Lock Exits are executed after the user has pressed ENTER on the Set Create Panel or when the user enters the command to Lock the Set from the Modify/Approve Set Panel. See the ISPW User Guide for details.

To enable this feature in ISPW, the M.ER (See Chapter 3 –Maintenance Functions: Reference Data: ER – External References) variable EXSTLOCK must be added to the table.

Below is a sample definition of this variable which instructs ISPW to execute clist WZUAPPR prior to locking the Set.

Figure 7-3. Set Lock Exit

Set Post Exit WZUSETX

This exit is provided with the ISPW base code and is called when all standard set processing has been completed. The provided sample version of this exit sends email messages to the designated addressees for set completion notification and submits a batch job to perform and needed CICS NEWCOPY requests and/or LLA refresh requests via a provided skeleton.

Customer sites can check this sample clist out to their SITE application and modify it to suit their post-set requirements

ISPW M.ER ADD EXTERNAL REFERENCE DETAIL (W3P)Command ===>Enter required details: Type Code (KEY) ==> EXSTLOCK View Code (KEY) ==> Description ==> USER SET LOCK EXIT Variable/Dsname ==> ISPEXEC SELECT CMD(%WZUAPPR &DEBUG) (Fully qualified if data set name, no quotes)Press ENTER to complete the change or END to terminate Note: To add a new entry the Keys must be unique


8-1

Chapter 8.

8Security Chap 8

This chapter describes how ISPW can be secured. ISPW uses standard SAF facilities to secure the functions in ISPW. Functions in ISPW are secured by the use of Objects and Methods. Security Rules can be defined at the Object/Method level to secure these functions. It is possible to install ISPW with no security at first, and then add rules to define security checking later.

How does it work?

Input cards to the ISPW CM started task determine how ISPW is to make SAF checks and for which Objects/Methods these checks are to be made. ISPW will dynamically build the SAF Resource Name to check based upon the rules specified to ISPW. Security profiles/rules need to be defined to the local security product in line with the Security Rules specified to ISPW. Appendix A, “Security” contains the complete list of Objects/Methods and the attributes that can be used in the security checking.

Figure 8-1. ISPW Security

“Statement of Integrity”

ISPW's use of APF authorized code is only for the functionality of ISPW, as described in the product documentation. ISPW has been rigorously tested for security exposures, and any security exposures that came to light in the future would be given Compuware's highest priority.


Preparing for Security

Defining a SAF Class for ISPW

ISPW makes security checks to SAF which require a Class Name (Generic). It is recommended that a separate SAF Class be defined specifically for ISPW as the ISPW CM started task issues (RACROUTE REQUEST=LIST) against the class at start-up to pre-load all of the profiles. By keeping the ISPW profiles separate provides the maximum level of optimization under SAF.

SAF Class Attributes

The following are some suggested attributes used for the SAF Class definition. The RACF definition is shown as an example:

$ISPW ICHERCDE CLASS=$ISPW, ID=128, MAXLNTH=80, FIRST=ALPHANUM, OTHER=ANY, POSIT=25, OPER=NO

Dynamic RACF CDT Class Definition

Customers that are running z/OS 1.5, or later, are now able to dynamically define the SAF Class. An example definition for RACF follows:

Figure 8-2. Dynamic RACF CDT Class Definition

This can be refreshed using the RACF command:

SETROPTS REFR RACLIST(CDT)

Defining Security

Server Definition

Input cards are placed in the dataset allocated to the SDEFxxxx DDName specified for the CM started task. Input cards for security are required for:

• Specification of the SAF Class which ISPW checks for authorities

• Specification of an optional prefix used when building the resource string

• Specification of the Security Rules to define how ISPW functions are to be secured.

Define RACF Class

The format of the input card for the definition of the SAF Class is:

RDEFINE CDT $ISPW OWNER(ISPWADM) CDTINFO(CASE(UPPER) DEFAULTRC(4) + DEFAULTUACC(ACEE) FIRST(ALPHA NATIONAL NUMERIC) GENLIST(DISALLOWED) + KEYQUALIFIERS(0) MACPROCESSING(NORMAL) MAXLENX(80) MAXLENGTH(80) + OPERATIONS(NO) OTHER(ALPHA NATIONAL NUMERIC SPECIAL) POSIT(25) + PROFILESALLOWED(YES) RACLIST(DISALLOWED) SIGNAL(NO) + SECLABELSREQUIRED(NO))

Security 8-3

SECCLASS=xxxxxxxx

where xxxxxxxx is the name of the Class.

If a class is specified which does not exist or no class is specified at all, ISPW will write a message in the log to indicate that it could not load the profiles and internal ISPW security is unavailable.

Define Resource name prefix

The format of the input card for the definition of the SAF Class is:

SECPREFIX=xxxxxxxx

where xxxxxxxx is the text of the prefix. This card is optional and should rarely need to be specified if the ISPW Server variable is used in the definition of the Security Rules.

Define Security Rules

Input cards can be defined for each ISPW Object and Method using the following format:

SECRULE=’Object Method ResourceName Authority’

This is described further in the following table:

Default Security

ISPW comes pre-defined with internal rules to determine which security checks are to be made. This default security is described in Appendix A against each Object and Method. The user-defined Security Rules override these defaults.

Previewing Security RulesThere is an ISPW supplied program which takes as input the defined Security Rules and produces a report detailing all the ISPW Objects and Methods with the Resource Name string

Table 8-1. Define Security Rules

Parameter Description

Object

An ISPW defined Object (e.g. RELEASE). The wildcard symbol “*” can be used to specify all Objects, but only if “*” has also been used for the Method.

See Appendix A for a complete list of Objects.

Method

An ISPW defined Method that is valid for a specific Object (e.g. the Method ADD is valid for Object RELEASE). The wildcard symbol “*” can be used to specify all Methods. The wildcard value for the Method can be specified for both a specific Object and for an Object of “*”.

See Appendix A for a complete list of Methods.

ResourceName

The value here determines what resource string ISPW builds to pass to the security product for the authorization check. For each Object there are a specified number of variables which can be used in the definition of this string (e.g. SERVER, APPL, LEVEL etc). These variables are resolved at security check time to build the actual Resource Name to check against. See Appendix A for a complete list of available variables.

AccessThe SAF authority to be checked for (e.g. does the user have READ authority on the Resource Name). See Appendix A for a complete list of available Access levels.


ISPW and will check against and the authority required. This is a useful report to validate the rules with the definitions in the security product. The JCL for running this report is described below:

Figure 8-3. Previewing Security Rules

Report Layout

See Appendix A for examples of this report.

The report has 3 sections.

• Heading

• Input Cards

• Altered Rules

Heading

WZZACDMP ACCESS CONTROL RESOURCE STRINGS FROM MODULE WZACSPW

AS UPDATED:

Input Cards

The input cards that were input into program are re-printed.

e.g.

SECCLASS=$ISPW SECPREFIX= SECRULE=’* * DUMMY

NONE’

Altered Rules

The security rules are printed out in the format shown in the following block.

Altered Rules

The security rules for the Objects and Methods are printed out in the following format:

//WZCADUMP JOB ,,CLASS=A,MSGCLASS=K,MSGLEVEL=(1,1)//*//*-------------------------------------------------------------------//* EXECUTE THE ROUTINE WZZACDMP TO DUMP OUT SECURITY RULES//*-------------------------------------------------------------------//RUN EXEC PGM=WZZACDMP,PARM=WZACISPW//STEPLIB DD DISP=SHR,DSN=ISPW.W30.PRD.LOAD// DD DISP=SHR,DSN=ISPW.R30B.LOAD//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SDEFISPW DD DSN=ISPW.R30B.SAMPLIB(SDEFISPW),DISP=SHR **Rules//

Table 8-2. Altered Rules

Column Field Description

1 Modify IndicatorThis indicates whether the input cards have altered the default rules defined in ISPW. An “M” identifies it as modified.

Security 8-5

3 Object The ISPW Object

12 Method The ISPW Method for the Object

21 Access The access level that is required for the Object/Method combination

30 Resource String The SAF Resource String which is checked against to see if the user has the required access.

Table 8-2. Altered Rules


9-1

Chapter 9.

9Extension Data Chap 9

This chapter describes how to use the Extension Data feature within ISPW.

What is Extension Data?Extension Data provides the ability to extend the ISPW data model to store and use new attributes against existing ISPW Entities. New attributes are defined to specific classes, and any number of new classes of data can be defined. The attributes can be both character and numeric format.

The attributes that ISPW natively supports for an Application and Level (e.g. Application SITE at level QA) could be extended to include specific data relating to the management of a specific technology that the customer is using (e.g. for J2EE Objects the App Server Name that they are deployed into would need to be stored).

Most of the Application related Reference Data entities have been enabled for Extension Data. The list of supported entities can be viewed via the ISPW Option M.ET. With each new release of ISPW, this list can be added to.

Figure 9-1. Extension Data

What is an Extension Class?

An Extension Class is defined separately in ISPW via option M.EC and describes a set of attributes or variables that can be later used to extend a specific entity. An example of this

ISPW EXTENSION DATA TABLES (INT) Row 1 of 21Command ===> Scroll ===> CSRList Commands: L Locate Entry Table Description APPLCT Application Component Type APPLCTL Application Component Type Level APPLLVL Application Level CMPNTYPE Component Type CMPNVERS Component Version CONTAINR Container DPCATGRY Deploy Category DPDOMAIN Deploy Domain DPENV Deploy Environment DPENVIMP Deploy Environment Implementation DPLSTGRP Deploy Logical Storage Group DPSUBENV Deploy Sub Environment DPSYSTEM Deploy System DPTARGET Deploy Target DPTYPE Deploy Type SERVER Server STRMCT Stream Component Type STRMCTL Stream Component Type Level STRMLVL Stream Level TASK Task USER User******************************* Bottom of data ********************************


might be a class called TELON that can contain all of the variables required for the handling of the TELON language.

Defining Extension Data

Define the Class

An extension Class can be defined in M.EC. See Chapter 3 – Maintenance Data (Reference Data Options) EC – Extension Classes for a description of how to define a class.

Add extension data to an Entity

Select the Entity to which the Class is to be defined. This can be done by using the “X” option in the appropriate Maintenance Screen. Below is an example of the screen for adding extension data to the Component Type Entity.

Figure 9-2. Add Extension Data to an Entity

Entering “X” from this screen against a Component Type will bring up the following screen where a list of extension classes for that type will be displayed, and the option of adding a new Extension Class can be performed:

Figure 9-3. List of Extension Classes for a Type

Entering “A” on the command line will bring up the screen where the new Class Name can be specified:

ISPW M.CT COMPONENT TYPES TABLE (INT) Row 1 of 107Command ===> Scroll ===> CSRList Commands: A Add Entry, L Locate Entry, B Browse Mode Line Commands: S Select, Delete, X Extensions Type Tech Ityp Cyc Gen Description AMAC Y ASSEMBLER MACS TESTING ASM Y Y ASSEMBLER PROGRAM TESTING C XNAM Y Y C Language Programs CCOB CICS Y Y CICS COBOL PROGRAMS CFG HFS WS Y N Eclipse configuration files CHFS HFS Y Y C Language Programs CLAS Y Java class files CLSS Y Java class files CLST Y Standard TSO Clist Code CMAP CICS Y Y CICS MAPSETS CMDS Y ISPF COMMANDS TABLE MODULES CMLD Y ISPW COMMUNICATIONS MGR (CM) LOAD MODULES-NO SRCE COB Y Y COBOL PROGRAM DESCRIPTION. COPY Y COBOL COPYLIB MEMBERSX CSPA Y Y CSP Application CSRC Y C LANGUAGE SOURCE FOR DEBUG TOOL CSS WEB WS Y N cascade style sheet DATA N ATTRIBUTES FOR PERSONAL DATASETS DBRM Y DB2 PRECOMPILE OUTPUT(DATABASE REQUEST MODULE) DBXM WEB WS Y DBXM for WSAD DCCB CICS Y Y DB2 CICS COBOL PROGRAMS DCLG Y Y DB2 DCLGEN MODULES DCOB Y Y DB2 COBOL PROGRAMS

ISPW M.CT-X TYPE:CSPA EXTENSIONS UPDATE MODECommand ===> A Scroll ===> CSR

List Commands: A Add Entry, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete

Extension Description

******************************* Bottom of data ********************************

Extension Data 9-3

Figure 9-4. Specifying New Class Name

In this example we are adding more attributes for the CSPA type. The Class CSP4 must already have been defined in M.EC.

Figure 9-5. Adding Attributes

The above screenshot shows that the values for the two Extension Class attributes have been added. This will now be available in ISPW exits when managing components for the type CSPA.

Use Export/Import

When defining Extension Data to the different Entities, remember that the Reference Data Export and Import feature is available, as this might be an easy way to make mass changes to data and can be used to easily add the classes to multiple Entity instances.

Using Extension Data

Where can it be used?

Extension Data can be used in any ISPW exit using the REXX programming language.

How to retrieve it

An ISPW call of the form:

WZZTSI("#refdataclass","GET","ExtensionClass")

is made to populate ISPF variables that correspond to the Extension Class attributes.

The following REXX code gives an example of how to retrieve the extension data defined in the previous pages (e.g. Class CSP4 for the Component Type CSPA).

ISPW M.CT-X ADD - TYPE:CSPA EXTENSIONSCommand ===>Enter required details:Extension Class ==> CSP4Press ENTER to complete the change or END to terminate

ISPW 3.3 TYPE:CSPA EXTN:CSP4 Row 1 of 2Command ===> Scroll ===> CSR Keyword Value CSPLOAD SYS1.CSPAD MSLC ISPW.COMMON.MSL------------------------------- Bottom of List -------------------------------


Figure 9-6. Retrieving Extension Data

Reference Data Calls

Knowledge of the Reference Data calls is required. These are described in Appendix B.

/* REXX */MEMBTYPE="CSPA" /* key for component type get */ rc = WZZTSI("#CMPNTYP","GET","CSP4") /* call to get extension class */ If rc=0 Then Do Say "CSPLOAD ="CSPLOAD Say "MSLC ="MSLC EndElse Say "Error on Extension Get RC="rcexit

10-1

Chapter 10.

10Component Groups Chap 10

This chapter describes how to use the Component Group feature within ISPW.

Component Group DescriptionWith Component Grouping you can define general groups of components, which do not necessarily belong to the same application or stream. For these groups you can run site-defined, server controlled processes upon completion of an operation. For example, each of the components in a component group when promoted (P) from any TEST level to the first HOLD level, the server will post an External Processing Request (EPR) upon which a Set is started to process the EPR. The processing of the task then finishes and new online processes against the task may be started.

Defining a Component Group

A Component Group can be defined in M.GX. See “GX - Component Groups” on page 3-55 for a description of how to define a group.

Add Extension Data to an Entity

Select the Entity to which the Class is to be defined. This can be done by using the “X” option in the appropriate Maintenance Screen. Figure 10-1 shows an example of the screen for adding extension data to the Component Type Entity.

Updating a Component Group

Select a Component Group for modification by line-command 'S.'

Figure 10-1. Example of the screen for adding extension data to the Component Type Entity

Update the Group Information

Overtype the non-KEY information on the displayed panel to update the Component Group details.

ISPW M.GX Component-Group TABLE (F40) UPDATE MODECommand ===> Scroll ===> CSRList Commands: A Add Entry, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete, C Components, X Extensions Group ExtProc s SENSITIV EMAIL******************************* Bottom of data ********************************


Figure 10-2. Update the Group Information

Adding Components to Component Groups

Select the Component Group's components list using line-command 'C.'

Figure 10-3. Line Command C

From here you can Add a Component to the group using command 'A', or using line-command 'S'.

Figure 10-4. Line Command S

From here you can Add a Component to the group using command 'A', or using line-command 'S'.

ISPW M.GX MODIFY Component-Group DETAIL (F40)Command ===>Enter required details: Group (KEY) ==> SENSITIV Description ==> Sensitive components Procname ==> EMAILPress ENTER to complete the change or END to terminateNote: You can add a new entry by overtyping the keys with new unique value

ISPW M.GX Component-Group TABLE (F40) UPDATE MODECommand ===> Scroll ===> CSRList Commands: A Add Entry, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete, C Components, X Extensions Group ExtProcc SENSITIV EMAIL******************************* Bottom of data ********************************

ISPW M.CX Cmpncgrp Definitions TABLE (F40) UPDATE MODECommand ===> A Scroll ===> CSRList Commands: A Add Entry, L Locate Entry, B Browse Mode Line Commands: S Select, D Delete Group Type Appl Name SENSITIV C FIN PAYROLL Path SENSITIV CSS WWW wFrame.css Path html/ SENSITIV FILE WWW Form1.vb Path VisualBasicPaul/WindowsApplication1/ SENSITIV JOB DEV CLJOBASM Path******************************* Bottom of data ********************************

Component Groups 10-3

Figure 10-5. Line Command A or S

Define External Processing

Create the M.EX entry

In the Processing Exits Table (M.EX) define processing for Exit Key $$EP: You can enter Operation and Environments as required. The Update flag must be set to 'N'. See “EX – Exits” on page 3-46 for more detailed information.

Figure 10-6. Create the M.EX Entry

External Processing Request Example

What is an EPR?

An External Processing Request (EPR) is an ISPW Exit routine which is initiated during Set processing for a component that has been designated as part of the relevant component group.

EPR Example

Using the sample data above, for each of the components in component group 'SENSITIV', when promoted (P) from any TEST level to the first HOLD level, the server will post an EPR,

ISPW M.CX ADD Cmpncgrp Definition DETAIL (F40)Command ===>Enter required details: Group (KEY) ==> SENSITIV Application ==> PLAY Component Type ==> C Component Name ==> CCGTEST Relative Path ==>Press ENTER to complete the change or END to terminateNote: You can add a new entry by overtyping the keys with new unique values

ISPW M.EX ADD PROCESSING EXIT DETAIL (F40)Command ===>Enter required details: Operation (KEY) ==> P Exit Key (KEY) ==> $$EP Description ==> EXTERNAL PROCESS PROMOTE Preop Routine ==> EMAIL Postop Routine ==> Valid In Environment OUTS ==> N (Y yes, N no) TEST ==> Y (Y yes, N no) HOLD ==> N (Y yes, N no) PROD ==> N (Y yes, N no) Update Last Operation Code ==> N (Y yes, N no)Press ENTER to complete the change or END to terminate new entry the Keys must be uniquenew entry the Keys must be unique


upon which a Set is started to process this EPR. The Processing of the task then finishes and new online processes against the task may be started.

The Customer-code started from this Set can retrieve a list of pending EPR's, process them and report the results back to the server. The API consists of a number of calls to WZZTSI from a TSO-ISPW-REXX environment. A sample is provided in CLIST WZZEP##.

API Format

The General format for the API call is:

WZZTSI("EXTPRREQ",<method>)

Each of the methods for this call are described below.

Methods Prerequisite

Set variable EPTABLE to name of the ISPF Table that contains the EPR entries.

LIST

Provide a list of entries in the EPR table.

Input Parms (optional)

Output: ISPF Table

DELETE

Delete entries from the EPR table.

Table 10-1. Input Parms


EPPROC External Procedure Name corresponding to the entry in the Component Group definition.

STATUS P – Pending. See details on Modify.

Table 10-2. Output: ISPF Table

EPPROC External Procedure Name Key

OPID Operation ID (binary) Key

TASKID Task ID Key

CMPNID Component Id

CMPVID Component Version Id

OP

EPR-operation, which can be used to lookup pre- and post-exits (Customer Defined Exits Keys, Two-Byte Operations starting with 'Z'). Initially filled with the Operation by which the External Process was triggered.

STATUS EPR status. See details on Modify. Initially filled with 'P'

Component Groups 10-5

Input

MODIFY

Modify the status code of an entry in the EPR table.

Input

GET

Retrieve an entry from the EPR table.

Input

Output

Table 10-3.


OPID Operation ID (binary)

TASKID Task ID

EPPROC External Procedure Name




TASKID Task ID


STATUS C – Completed E – Executing F - Failed




TASKID Task ID


Table 10-6. Output


WTAPPLID Application

WTSTRM Stream

WTMTYPE Component Type

WTMNAME Component Name

WTVSNO Version Number

CRELPATH Component relative path

POPT Operation (P, G, I, X, D...)

OPLVL Level at which the operation was started

OPTLVL Level at which the operation finished.

OPUSER Userid that performed the operation

OPDATE Operation Date

OPTIME Operation Time

OPSET Operation Set, if applicable


OPRLSE Operation Release, if applicable

LASTOP The (current) Last operation that has occurred against the task.

LASTUSER LastOp userid

LASTDATE LastOp Date

LASTTIME LastOp Time

ACTION Task's action code (blank, D, I)

RLSEID Current Task's Release

WORKREF Current Task's Assignment workref

PRODVER The Production Version at the time of the operation (POPT)

PRODDATE Last operation Date of the ProdVer at time of POPT

PRODTIME Last operation Time of the ProdVer at time of POPT

PRODUSER Last operation Userid of the ProdVer at time of POPT

PRODREF Current Assignment's workref of the ProdVer

Table 10-6. Output

11-1

Chapter 11.

11Component Warehouse Chap 11

This chapter describes the function, set up and maintenance procedures for the ISPW Component Warehouse.

Component Warehouse DescriptionThe Component Warehouse is a facility to retain copies of ISPW managed components such as source, listings or load modules. Each of these components may be saved in one of the warehouse datasets and retrieved at a later time. Components are compressed as they are added to the warehouse and decompressed on the way out.

The warehouse runs as part of the Component Transport (CT) address space.

Warehouse role—The warehouse is fully integrated with the rest of ISPW and is used to retain old versions of components. The warehouse is transparent to the user, and controlled by the ISPW administrator.

Warehouse function—Within the Application Definition option (M.AD, Levels), there is an entry that specifies the warehouse name and policy to be used. The warehouse name and policy can be specified differently for source objects and generated objects.

When a component is promoted and a copy of that component already exists at the target level, then the copy at the target level is pushed into the warehouse (if a warehouse exists for that level). The number of versions of a component that will be retained at a level is determined by the warehouse policy. Any generated objects, such as listings or load modules, may also be pushed into a warehouse based on the definitions for the level.

Components in a warehouse are retrieved as needed by ISPW operations. When components are no longer referenced by ISPW, they are deleted from the warehouse.

Warehouse Elements

Warehouse Manager

Each warehouse consists of one or more datasets. The warehouse manager allocates the datasets and controls access to them.

The warehouse manager runs inside the CT task. It communicates with the CM task to retrieve warehouse definition data and update warehouse storage status information.

Warehouse Datasets

All the warehouse datasets are PDSE’s. The datasets are dynamically defined by the warehouse manager as needed. The dataset names, sizes, and locations are defined with the ISPW administration functions.

Compression

Objects may be compressed as they are added to the warehouse. The compression option is set in the warehouse policy. The higher level of compression will minimize the amount of


disk space used, but require more time and resources to compress. Disabling compression will speed up warehouse operations, but use more disk space.

Storage Policy

Objects are stored in the warehouse as members of PDSE datasets. The number of versions of an object that will be retained in a warehouse is controlled by the warehouse policy defined with the ISPW administration functions.

Warehouse Usage

What should go into Warehouses?

The Component Warehouse allows you to keep backup versions of source and generated objects, such as listings or load modules. The backups can be retained at any level above the bottom test level in the application structure.

The usage of the warehouse facility will depend on your application management structure and backup requirements. At levels where generates can be performed, it may be sufficient to keep backup copies of just the component source. At levels where generates are not permitted, you may want to keep backups of both source and generated objects in the warehouse.

The retention of generated objects in the warehouse will have a significant effect on both warehouse space requirements and the elapse time to perform promotions.

How many versions should be retained?

The number of versions that will be retained in the warehouse is set in the warehouse policy. The policy can be different for each level of an application.

At lower levels, it may be adequate to retain a small number of versions. At the production level, you may want to keep a larger number of versions, or even all versions.

Versions by Assignment or Level?

The maximum number of versions that will be retained can be set by either the level or the assignment.

If the maximum number of versions is by level, then retention is based just on the number of backup versions currently at that level. If the maximum number of versions is by assignment, then retention is based on the number of versions of a component at the level that are part of this assignment.

At the production level, you should normally set the maximum versions by level. At lower levels in the application structure, you may want to consider setting the maximum versions by assignment.

This setting and the value of maximum versions will have a large impact on the size of your warehouses.

How many Warehouses?

You can keep all of your backup copies in one large warehouse or can spread them across multiple warehouses. Warehouses are split up into multiple datasets, with additional datasets added as required.

You can segregate different applications or groups of applications. You can keep source in a different warehouse than generated components. You can use different warehouses for different levels.

Component Warehouse 11-3

The decision may be dependent on charge back considerations or disaster recovery requirements. You can have as many or as few warehouses as you want.

Warehouse Set UpThis procedure assumes that ISPW is already installed and active on your system. The CM and at least one CI and CT task should be running.

Dataset Planning

Before defining any warehouses, you must select a dataset prefix and decide on allocation parameters. All warehouse datasets will be created with the following naming convention:

“Prefix.WarehouseName.StorageID.WPDS”

The warehouse name may be 8 characters. The StorageID is 8 characters. This permits a prefix of up to 21 characters. Since the warehouse datasets will be created and accessed by the CT task, make sure that the UserID assigned to the CT task has alter access to this dataset prefix. Since the warehouse datasets are PDSE’s, they must be SMS managed. Ensure that any SMS definitions required for the warehouse datasets are in place prior to using the warehouse.

Defining a Warehouse

To define a new warehouse, go into the warehouse option in the maintenance panel (M.WH). A list of all existing warehouses will be displayed. If you are not already in update mode, enter “U” to go into update mode. Enter an “A”

to add a new warehouse definition. The warehouse add panel will allow you to enter the name and description of the warehouse, along with a set of values that will be used to create the warehouse datasets. Figure 11-1 shows a sample warehouse definition.

Figure 11-1. Sample Warehouse Definition

Warehouse Policy

To define a new warehouse policy, go into the warehouse policy option in the maintenance panel (M.WP). A list of all existing policies will be displayed. If you are not already in update mode, enter “U” to go into update mode.

ISPW MODIFY WAREHOUSE TABLE DETAIL (DEV)Command ===>Enter required details: Warehouse (KEY) ==> WHOUSE02 CT Server Name ==> WZCTW3T (Component Transport Server Name) Allocation Type ==> MVS Description ==> test warehouse Data Set Prefix . . : TEST.W3T.WH Management class . . . (Blank for default management class ) Storage class . . . . SMS (Blank for default storage class ) Volume serial . . . . * (Blank for system default volume ) Device type . . . . . (Generic unit or device address ) Data class . . . . . . (Blank for default data class ) Space units . . . . . TRACK (BLKS,TRKS,CYLS,MB ) Primary quantity . . 10 (In above units ) Secondary quantity 10 (In above units )Press ENTER to complete the change or END to terminate


Enter an “A” to add a new policy definition. The warehouse add panel will allow you to enter the name and description of the warehouse policy, along with a set of values that will be used to control the versions retained and the compression that will be used.

Figure 11-2 shows a sample warehouse policy definition.

Figure 11-2. Sample Warehouse Policy definition

Setting Warehouse Usage

Once one or more warehouses have been defined along with one or more warehouse policies, you can enable warehouse usage by applications.

The warehouse usage is set in the application definition level panel (M.AD, Levels). The name of the warehouse and the policy name can be specified for both source and generated components. If no warehouse definition is specified for generated components, then only the source will be retained in the warehouse.

The Figure 11-3 shows a sample application level definition.

Figure 11-3. Sample Application Level definition

Ongoing Support and MaintenanceOnce setup, the only real maintenance issues involve the warehouse datasets.

Ensure proper and regular backup of all datasets, and ensure that there is enough DASD space available for warehouse expansion.

ISPW MODIFY WAREHOUSE POLICY DETAIL (DEV)Command ===>Enter required details:Policy Name (KEY) ==> MVSPRODKEEPALL Description ==> Keep all versions no matter what Method ==> L ("A" for Assignment, "L" for Level) Maximum Versions ==> 0000 Compression Type ==> 2 (0 - no compression, 1 - medium, 2 - maximum) Press ENTER to complete the change or END to terminateNote: You can add a new entry by overtyping the Key with a new unique value

ISPW M.AD/LMODIFY APPLICATION CORE STREAM BASIC LEVEL (DEV)Command ===>Enter required details:Level (KEY) ==> PRODNext Level ==>Impl Exit? ==> (Y - Yes)Warehouse for Sources : Name ==> Policy ==> Gen Types: Name ==> Policy ==>Set Scheduling Information: Set Class ==> A Job Name ==> WZPCORE Queue Name ==> Failure Notify ==>DB2 Information: Impl Name/Rule ==> Name or Rule to determine Plan Implementation DB2 Subsys ==> Sub-system applicable for this Level DBRM Libs ==> ISPW.&APPL..&LEVL..DBRMLIB XREF Name ==> XREF Lib ==> R - Read only, W - Read/Write

Press ENTER to complete the change or END to terminateNote: You can add a new entry by overtyping the Key with a new unique value

Component Warehouse 11-5

Make sure that the automatic housekeeping option is enabled in the CT task start parameters. See the Component Transport task installation for a description of the housekeeping option.

HSM Considerations

The CT task does not care when a dataset is migrated or what level it is at. The only issue is the recall time for ML2 vs. ML1. Since the contents of the warehouse datasets are already compressed, migration to level 1 will not save much disk space.

As far as migration times, ISPW suggests that datasets migrate to level 1 after a few days, then go to level 2 not too long after that (assuming the level 2 recall times are not unreasonable).

When a warehouse dataset is needed, the CT task checks for the dataset status. If it has been migrated, then it issues a recall request using the HSM API. When the recall completes, then it allocates and opens the dataset.

If the warehouse dataset contains member(s) that need to be deleted in a housekeeping request, then it will be recalled, as a member cannot be deleted without bringing it back.

A fallback would cause a recall of the dataset if it contains a component required by the fallback.

Recalls will not affect other CT requests. Since ISPW recalls using the HSM API prior to issuing the dynamic allocation of the dataset, the CT task will not get caught in the serialization that MVS allocation does in an address space.

The CT task can also handle multiple concurrent dataset recalls without hanging up.

If a tape is unavailable, the CT task will fail the request back to CM. Once the tape is available, the request can be re-run and everything should work (assuming HSM can recall the dataset). As each HSM request is independent, this would not affect other requests that may be active at the time.


12-1

Chapter 12.

12Component Reference Chap 12

This chapter describes the Component Reference features within ISPW.

Component Reference ConceptsThe Component Reference feature in ISPW encompasses all of the functionality required to gather and store relationships between components. This information is used by:

• Users for documentation, training and impact analysis; and

• ISPW as a basis for configuration management

• Note that the Component Reference contains relationships between components.

How is the relationship information gathered?

The Component Reference information is populated either automatically by ISPW or manually by the customer.

Automatically maintained reference information

ISPW provides parsers to gather this information. When promoting a component to the first controlled level, an appropriate parser for the component is executed to gather relationship information. Execution of the parsers is site configurable. New parsers can be added for special technologies and user exits to cater for site-specific parser complications are supported. During ISPW installation it is possible to parse component in bulk to enable the initial data to be stored.

Manually maintained reference information

By use of ISPW’s External Call Interface, component reference information can be added manually. See the ISPW Interfaces Guide for more information. It is possible to add relationship information once for a component version and have it inherited by all subsequent versions of that component. Alternatively, the user added relationships could be inserted by the ECI for each component version (or it is possible to have a combination of the two).

What information is gathered?

As well as identifying the specific component referred to, ISPW will determine and store the following:

• Component Category of the referenced component (e.g. PGM, INCL etc.)

• Relationship Type (for example: Static, Dynamic or Weak)

• Impact Type (text that further defines the relationship)

• Inheritance information (for manually added relationships)

Data Model

The following diagram depicts the entities surrounding the Component Reference.


Figure 12-1. Data Model

A short description of the entities follows:

Table 12-1. Component Reference Entities

Entity Description

Component Depicts a Component (e.g. Cobol program PROG01 in Application PAYR of Stream MAIN).

Component Version Depicts a version of a component (e.g. version 2 of the above component).

Component Version External Name

Any name that this Component can be referenced by. Normally this is the name of the component itself but it does not necessarily have to be (e.g. aliases).

Component Version Reference A list of components referenced by the component version (e.g. copybooks, other programs etc.).

Component Type

Defines the type of component and can therefore be used to drive process specific to that type (e.g.

COB, ASM, CLST etc.).

Application Component Type Further defines the component type’s behavior down to specific Applications

Base Component Type Provides a way of grouping Component types together for parsing. This is the level at which the parsing routines and exits are defined.

Component Category Used to specify the category of the reference. (e.g. COB, ASM and PLI base component types all have a category of PGM).

Component Reference 12-3

Using the Component Reference information

The Component Reference information can be accessed in the following ways:

• Option A on ISPW’s Main menu

• Operation XR against an ISPW Task

See the ISPW User Guide for information on how to use these functions.

Installation Considerations

Overview

Making the Component Reference functional involves the following:

• Install the ISPF skeleton for batch parsing

• Define Component Categories

• Define Base Component Types

• Update Component Type reference data

• Turn on Component Reference for Applications

Install ISPF Skeleton

Option M.CR file tailors the ISPF skeleton WZZMCR#. This skeleton is found in the base ISPW Samplib dataset and should be installed into the SITE application with any changes being made to it.

Define Component Categories

Component Categories provide the high level definition of component references. Component Categories that are be installed as part of the ISPW Installation process include:

This supplied set of Component Categories supports the standard 3GL relationships most customers need. New categories can be added as necessary.

Define Base Component Types

This is the level at which the parsers are defined. Base component types provide a way of keeping separate the different Component Types that a customer may wish to define in M.CT with the information required for parsing. It is quite possible that a customer may need to define several different Component Types to manage JCL for instance, and all these can be related to a single Base Component Type of JOB.

The M.BC definition screen appears as follows:

Table 12-2. Define Component Categories

CC Description

INCL Copybooks, macros, header files etc.

JOB JCL

PGM Any program (e.g. Cobol, Assembler, PLI etc.)

PROC JCL Procs


Figure 12-2. M.BC Definition screen

The Type column indicates the Base Component Type (not the Component Type). Note that this is where the Base Component Types are related to Component Categories.

The value in the scanner column lists the physical load module that will be called to scan a component related to this Base Component Type. The scanner names listed in the above screenshot are supplied as standard with ISPW.

See “CT – Component Type Definition” on page 3-36 for more detail on this option.

Update Component Type reference data

For each main source component type that is to be parsed, the entry in M.CT must include a reference to a valid Base Component Type. Ensure that the field “Base Component Type” for the component type has a valid value in it.

Turn on Component Reference for Applications

For parsing to be enabled for an Application, the Application’s entry in M.AP needs to be updated such that the field “Component Reference” is set to “Y” (as shown below):

Figure 12-3. M.AP Screen

See “AP – Applications” on page 3-29 for more detail on this option.

Parser User ExitsThe User Exits provide a mechanism to extend ISPW supplied parsers so that component references found by ISPW can be altered or ignored and additional references found by the user exit can be added.

ISPW M.BC BASE COMPONENT TABLE (W3M) BROWSE MODECommand ===> Scroll ===> CSRList Commands: LOC Locate Entry, U Update Mode Line Commands: S Select Type Cat Lang Scanner Description AMAC INCL ASM WZZPPASM Assembler Macros ASM PGM ASM WZZPPASM Assembler Programs C PGM C WZZPPC C Programs COB PGM COB WZZPPCOB Cobol Programs COPY INCL COB WZZPPCOB Cobol Copy members JOB JOB JCL WZZPPJCL JCL Jobs PROC PROC JCL WZZPPJCL JCL Procs******************************* Bottom of data *******************************

ISPW M.AP/S BROWSE APPLICATION (W3M)Command ===> Appl (KEY) ==> DEMO Owner ==> PAUL Cross Reference ==> Y (Y/N) Description ==> DEMO SYSTEM APPLPress END to return

Component Reference 12-5

How are they called?

User exits are called from within ISPW and passed the following parameters:

What language can they be written in?

The exits can be written in any LE language, including Assembler, C and COBOL (390 and COBOL 2), but not OS/VS COBOL.

Samples

The following sample members can be found in the Base Samplib dataset:

How they work

The user exit is called from ISPW and is passed parameters allowing it to interrogate the record containing the source code. It is also passed the current list of External Names for the component and the list of External References to other components. The user exit is

Table 12-3. Parser User Exits


Control block address

An internal ISPW control block. This contains all of the component reference information for the component being parsed, and by using calls to special ISPW functions, the reference information can be manipulated. Reference information consists of:

External Names — this is a list of all names that the component being parsed is known externally as; and

External References — this is a list of all references to other components from the component being parsed.

Record area length Length of the record area that ISPW is passing to the user exit for parsing.

Record area address The record area containing the line of code.

Table 12-4. Sample Base Samplib Dataset Members

Sample Description

WZZPP Cobol copybook for both the user parser and user parser exit. This is used when writing a parser or parser exit in Cobol.

$WZZPP Assembler Macro for both the user parser and user parser exit. This is used when writing a parser or parser exit in Assembler.

Table 12-5. ample Base Samplib Dataset Members

Sample Description

#WZZPP C Header file for both the user parser and user parser exit. This is used when writing a parser or parser exit in C.

WZPEXTCO An example User exit written in COBOL.

WZPEXTCL Linkage statements to link the COBOL example.

WZPEXTAA An example User exit written in Assembler.

WZPEXTAL Linkage statements to link the Assembler example.


coded to analyze the line of code passed and can then add to the list of Names and References using specific ISPW calls. The following calls to ISPW functions are available:

Table 12-6. Available ISPW Function Calls

Function Description

WZZPPEXN

As part of the parsing process, the list of External Names can be added to. This function gets a new External Name list element. The new element is added to the front of the list, pointed to by PPB->extrnams. The user exit will then update that element with the new external name information. On return from this function, the element can be filled in with the external name value.

WZZPPXRF

As part of the parsing process, the list of External References can be added to. This function gets a new External Reference list element. The new element is added to the front of the list, pointed to by PPB->extrefs. The user exit will then update that element with the new external reference information. On return from this function, the element can be filled in with the external reference value.

WZZPPMSG This function writes a message to the ISPW debug output stream.

WZZPPMER This function writes an error message to the ISPW log output stream.

13-1

Chapter 13.

13ISPW Debug and Trace Facilities Chap 13

This chapter describes how to use the ISPW Debug and Trace facilities.

Debug vs. TraceTracing and Debug are facilities within ISPW to aid in troubleshooting problems.

Debug

The Debug facility is targeted at the User exits and ISPF code that runs in the Client address spaces (both the TSO client and Set Processor). The ISPW technical support person at the customer site will find this facility useful when writing exits for special processing.

Trace

The Trace Facility is normally used under the direction of ISPW Support to aid in the solving of problems to do with the base ISPW Server and Client functionality. Most of this is written in program code and the Trace Facility is used to troubleshoot this code.

Interactive Debug (DBUG)The TSO Client is an ISPF Application that consists of Clist, REXX and Program code. Interactive Debug provides the mechanism to interactively trace and debug the Clist or REXX code.

Invoking DBUG

Typing DBUG on the command line from within ISPW displays the following screen:

Figure 13-1. Invoking DBUG

Fields on the screen are described in the table below:


Field Description

ISPW ------------------------- DEBUG FACILITY ------------------------- ISPWCOMMAND ===> Current DEBUG value ... Value to be set? ==> PSG# REXX Trace setting ==> ?R Propagate? ==> N (Y/N) ENTER to change value(s) or END to retain current value(s)


Special Value “W”

If “W” is used as the Value to be set, then this will turn on Debug for all ISPW routines.

Writing your own routines

When writing custom exits it is useful to start the routine with the Debug handling code that is used in the ISPW routines. The following few lines of code are from the ISPW routine WZZPSD#.

Figure 13-2. Writing Routines

Change the highlighted Debug value to something that makes sense for your routine and it will then be able to be traced just as the ISPW routines are traced.

Calling other Routines

If you insert a call to another ISPF routine make sure that the keyword DEBUG is passed as shown in the code snippet below:

"ISPEXEC SELECT CMD(%WZZHFS# "DEBUG" POPT("POPT") "

This will ensure that any Debug values that are set will be passed to the called routine.

Current DEBUG value If a debug value has been previously set then this would appear here. When blank it shows that Debug is turned off.

Value to be set

This determines the level of Debug. All ISPF routines in ISPW have unique Debug values, and when the Debug value set on this screen matches the internal routine value then Debug is turned on for that routine.

REXX Trace settingThis is the REXX Trace option that will be used with the TRACE command. See the REXX Reference for a description of these. For simple tracing, the value “?R” is used.

Propagate

Determines whether Debug is to continue to called routines, irrespective of their internal Debug identifiers. Values can be:

Y – Keep Debug on for called routines

N – Pass only the Debug value to the called routine and only keep Debug on if the internal Debug value matches the current Debug setting.


/* REXX TRACE ?R */ ADDRESS ISPEXEC PARSE UPPER ARG WZ@DBP Z /* <1ST WORD> ... */ IF WZ@DBP = "DEBUG" , THEN DO STRC = "Y" "ISPEXEC VGET (WZ@DBR ZSCREEN ZUSER Z)" END ELSE DO "ISPEXEC VGET (WZ@DBO WZ@DBP WZ@DBR ZSCREEN ZUSER Z)" IF WZ@DBO = "PSD#" , | WZ@DBO = "W" , THEN STRC = "Y" ELSE WZ@DBP = "" END DEBUG = WZ@DBP IF STRC = "Y" & WZ@DBR = "" THEN WZ@DBR = "?R" /* ? TEMP */

ISPW Debug and Trace Facilities 13-3

Invoking ISPW with DEBUG

The initial REXX Exec WZU@PRIM is user-customizable and may need to be traced to troubleshoot a problem. If the Panel that the ISPW Option has been updated as described in the ISPW Installation Guide then tracing can be turned on by appending the option with “.DEBUG”.

e.g. If ISPW is option W then invoke ISPW with the DEBUG option by typing

W.DEBUG

Turning Debug on for Set ProcessingThe Set Processor invokes ISPF processes similarly to the TSO Client, and it is necessary to be able to turn on the Debug facility for the Set Processor.

M.ER variable SXDEBUG

This is used to pass the Debug Value for the Set Processor. On startup, the Set Processor retrieves this and sets the REXX Trace and Debug values accordingly. The format of the variable is:

Debug value,Propagate,REXX Trace value

An example is shown below:

Figure 13-3. M.ER Example

Set Processor Started Task

To trace everything in the Set Processor from start-up make sure that the following DEBUG argument is set correctly in the command invocation in the started task PROC.

Figure 13-4. Set Processor Started Task

No Debug Trace

To remove excess debug trace from the Set Processor simply remove the DEBUG(DEBUG) argument from the started PROC and blank out the value set for the M.ER variable SXDEBUG.

ISPW M.ER BROWSE EXTERNAL REFERENCE DETAIL (W3P)

Command ===>

Type Code (KEY) ==> SXDEBUG View Code(KEY) ==>

Description ==> Batch Trace Values

Variable/Dsname ==> PSG#,Y,R

(Fully qualified if data set name, no quotes)

Press END to return

//WZZSX EXEC PGM=IKJEFT01,REGION=0M,TIME=1440, // PARM='%WZZSX### &SETID &GENTAB DEBUG(DEBUG) SCD(WZZSCD)'

//*


Tracing TerminologyThe different types and levels of trace facility messages are described, as well as the format of the trace output records.

Types of Trace Messages

The trace facility allows the generation of Log and Trace messages. They are divided into different levels as shown in the table below.

Log messages describe error, warning or informational situations that are written to the “log” destination, rather than convey the information through an error message returned to the user. In these situations there may be no actual user.

Trace messages are for internal use only and should only be used in consultation with ISPW Support staff during problem diagnosis. Given the nature of tracing, extremely large volumes of messages could be returned if not used correctly. Trace messages are written to the “trace” destination.

The messages can be routed by level to the various destinations as described in the Trace Destinations block.

Format of Trace Output

The format of the trace output lines is:

PP YYYYMMDDHHMMSS X NNNNNNNN xxxxxxxxxxx….xx Where:

PP is the SP ProcessorID (WPCID). This will be 00 if issued in the client environment or the Set Controller.

YYYYMMDDHHMMSS is the time the message was written.

X is the trace/error type identifier and can have the following values:

D — Debug

T — Trace

I — Informational

W — Warning

E — Error

NNNNNNNN is the internal ISPW module which issued the trace output

xxxxxxxxxxxxxxxxxxxxxxxxx is the message text. The trace output lines are written in chronological order.

Table 13-2. Types of Trace Messages

Type Level

Log Error

Warning

Information

Trace Debug

Trace


Trace Control StatementsThe control statements control the trace facility in all environments.

Control Statements

The control statements are input to the Trace Facility, so it knows where to send trace output for each type and level of message. The following table describes each of the control statements:

Trace Destination Codes

The trace destination codes describe the destinations that the messages should be written to. Multiple destinations can be specified, by separating with commas.

Valid values:

DSA – WZZLOGA or WZZDBGA, depending on the type of message.

DSB – WZZLOGB or WZZDBGB, depending on the type of message.

TPUT – issues the message as TPUT. This only works under TSO.

WTO – issues the message via WTO to ROUTCDE=(11), MCSFLAG=(HRDCPY)

Trace Destinations

Two destinations can be defined for each type of message. That is, destinations A and B can be defined for both log and trace messages.

Valid values:

Fully qualified dataset name — the dataset is dynamically allocated and used. If the allocation fails, an error message will be issued and the destination becomes mute.

Table 13-3. Control Statements

Control Statement Parameter List Description

WZZLOGA= DESTINATION Destination A for Log messages.

WZZLOGB= DESTINATION Destination B for Log messages.

WZZDBGA= DESTINATION Destination A for Trace messages.

WZZDBGB= DESTINATION Destination B for Trace messages.

ERRORM= DESTCODE,DESTCODE,etc Destinations for Error level messages.

WARNM= DESTCODE,DESTCODE,etc Destinations for Warning level messages.

INFOM= DESTCODE,DESTCODE,etc Destinations for Information level messages.

DEBUGM= DESTCODE,DESTCODE,etc Destinations for Debug level messages.

TRACEM= DESTCODE,DESTCODE,etc Destinations for Trace level messages.

DEBUG= CMPNTCODE,CMPNTCODE,etc List of components to enable for Debug level messages.

TRACE= CMPNTCODE,CMPNTCODE,etc List of components to enable for Trace level messages.


SYSOUT=x – a sysout dataset of class x will be allocated and used. If the allocation fails, an error message will be issued and the destination becomes mute.

DD:ddname – will use the indicated DDNAME. It is assumed that the DDNAME has been allocated in the start-up JCL, TSO allocate commands or whatever is appropriate. If the DDNAME fails open, an error message will be issued and the destination becomes mute.

* - a dynamic allocation of TERM=TS is attempted. This is the same as “ALLOC F(xxx) DA(*)” on TSO. If the allocation fails, an error message will be issued and the destination becomes mute.

Blank – a blank operand will set this destination to mute state.

What is a Mute Trace Destination?

When a trace destination is in the mute state, no trace or log output is generated to that destination. This situation does not cause a performance problem or reflect any kind of error to the rest of the ISPW processing.

Component List

The component list should be set to NONE on the DEBUG and TRACE control statements. ISPW Support staff will advise the values to place here for problem diagnosis.

Trace Output DatasetsDetails about how datasets can be used to store output from the trace facility are explained.

Trace Datasets must Exist

The trace datasets are disk datasets that must exist before the trace facility is started. If an attempt is made to use a dataset that doesn’t exist, the trace destination will go into “mute” mode. A message will be issued via WTO to the system log, indicating that the dataset allocation failed. No trace data will be recorded until a dataset is allocated and either the server is stopped and started, or refreshed or a Trace Data Set Switch is issued from M.SM.

Trace Dataset Allocation

The trace datasets are allocated with DISP=SHR to allow it to be browsed while the data is still being generated.

Since the trace facility uses QSAM (which is buffered) the last few trace messages will probably still be in a memory buffer at any given time.

Trace Dataset Attributes

Any trace datasets that are allocated should have the following attributes:

DSORG=PS

LRECL=132

BLKSIZE=8184

RECFM=FB

They will be set when the dataset is used.


Default Trace Dataset Names

The names of the default datasets that ISPW expects to find are:

‘ISPW.ISPW.LOGA’

‘ISPW.ISPW.DEBUGA’.

If this dataset doesn’t exist, a message will be sent to the system log indicating that tracing has not been started.

A different dataset name can be specified on the appropriate trace destination card in the SDEFISPW file or on the M.SM panel for a Data Set Switch.

Turning Trace On/OffWhen a server address space is started, tracing is on by default. The commands to turn tracing on or off in the server are described. There is no way to dynamically alter the trace facility environment in the client environment.

M.SM commands

To temporarily change the tracing, use the following commands. If the server is stopped and started or refreshed, the trace status will remain as it was defined in the SDEFispw file (either on or off).

M.SM Screen Example

The screen below shows an example of the M command to switch the trace dataset for log destination A.

Figure 13-5. M.SM Screen Example

Table 13-4. M.SM Commands

Command Description

T Turns ALL tracing on.

X Turns ALL tracing off (if turned on with option T).

M Modify the current Trace settings by issuing a Trace command.

ISPW M.SM -------- SERVER W3T CONTROL (INT) ---------------------------------COMMAND ===> m The following commands can be disruptive to users and should be used with care. R REFRESH - Refresh ISPW reference/control data P STOP - Stop ISPW request processing S START - Start ISPW request processing The following commands should only be performed under the direction of ISPW Technical Support staff. T TRACE START - Start ALL ISPW Server Tracing X TRACE STOP - Stop ALL ISPWServer Tracing M TRACE MODIFY - Modify Server Trace operation If 'M', New Trace Control Statement ==> WZZLOGA=new.log.dataset END to return to previous menu.


Command Return Codes

The following return codes are issued from the trace commands (see the system log for explanatory messages):

0 — successful,

4 — the command was understood but one or more operands were not.

The operands that were understood were executed.

12 — the command was not understood.

16 — the allocation failed or the dataset failed to open.

Turn off All Tracing

To completely turn off all trace/log messages and suppress all messages, set the trace control statements in the SDEFxxxx input file to:

WZZLOGA=

WZZLOGB=

WZZDBGA=

WZZDBGB=

ERRORM=

WARNM=

INFOM=

DEBUGM=

TRACEM=

DEBUG=NONE

TRACE=NONE

Client/Server TracingThe different defaults and commands for each environment are described.

Server Trace

The trace commands are part of the SDEFispw dataset and are reinterpreted for each start-up of the server. If there are no trace control statements specified, the default is as if the following statements were specified:

WZZLOGA=ISPW.ISPW.LOGA

WZZLOGB=

WZZDBGA=ISPW.ISPW.DEBUGA

WZZDBGB=

ERRORM=DSA,WTO

WARNM=DSA,WTO

INFOM=DSA,WTO

DEBUGM=DSA

TRACEM=DSA

DEBUG=NONE

TRACE=NONE


Server Trace Command Format

The SDEFispw file is formatted by the Parameters Processor when the server starts. This means that all trace commands specified for the server in the SDEFispw file must be formatted in the following way:

TRCMD=’tracecommand’

Example:

In the SDEFispw file, a trace command would appear as:

TRCMD=’WZZLOGA=ISPW.ISPW.LOGA’

Operator CommandsProvide a list of commands that can be entered by the operator to display various sets of information from the ISPW started tasks.

Commands

For the ISPW CM Task:

• F cm task name,D RS — Display Remote Servers

For the ISPW CI Task:

• F ci task name,D RS — Display Remote Servers• F ci task name,D CL — Display Eclipse Clients

For the ISPW CT Task:

• F ct task name,D Q — Display Requests (both active and queued)• F ct task name,D M — Display Active Requests Managers• F ct task name,D W — Display Warehouse Status


14-1

Chapter 14.

14Application Load Utility Chap 14

This chapter describes Application Load Utility that can be used to migrate Applications into ISPW. This utility is used to populate the ISPW repository with the details of all the components and associated Generate Options when bringing an Application under ISPW’s control.

Why is it required?

To properly manage an Application, ISPW needs to know about each of the Application’s components, which includes the following:

• Any Software Parts (e.g. SOURCE, LOAD, DBRM etc.)

• Compile Parameters

This information needs to be loaded into ISPW’s metadata repository before ISPW can be effectively used to start managing the Application’s components.

How it works

The Application Load is accomplished via a series a batch jobs that operate at the ISPW Application/Stream Level. These batch jobs use ISPF File Tailoring services to generate JCL that is required to be executed. Certain sections of the generated JCL are site dependent and some customization of the sample skeletons is therefore required. The process also provides support for User Exits and these may also need to be customized

Overview of the Process

The process of migrating an Application to ISPW will generally include the following steps:

Table 14-1. Steps to migrate an Application ISPW

Step Description

1 Define Application to ISPWThe Application structure is defined to ISPW using the M Functions (M.AP, M.ST, M.AD). The dataset names that the Application uses are defined here.

2 Populate ISPW managed librariesAll the components and associated parts need to be identified and placed in a separate set of libraries (i.e. the one’s identified in M.AD).

3 Cater for any special customizations

Exits are provided that allow for special processing to be invoked to manipulate the Task and Generate Parameter loading.

4 Review ISPW Task Load Report A Report is generated from the Application Load utility that should be reviewed.

5 Load Tasks into ISPW The Application Load utility is used to load the Tasks into ISPW.


Limitations

Currently the Application Load is concerned with active components only. It will not load history. If the loading of historical components is required contact ISPW Support.

Load Utility InstallationThe Application Load Process provides 7 skeletons. These are delivered in the ISPW SKEL Dataset. If a skeleton needs to be customized it should be checked out to the ISPW SITE application skeleton library, changed as required and promoted to the SITE production level.

ISPF Skeletons

Below is a list of the supplied ISPF Skeletons:

WZZAL *Requires Customization WZZALCWZZALDBWZZALGWZZALRWZZALTWZZALO

Skel WZZAL

This ISPF Skeleton initializes various site level variables and embeds the remaining skeletons to generate the required JCL. For example: skeleton "WZZALT" is embedded to generate the JCL for function "T-Task Load". There is a small block of code at the start of this skeleton, which needs to be customized.

Figure 14-1. Skel WZZAL

Note: The three DB2 related variables are only required if the cleanup option is run (Option “C” in M.AL).

REXX Execs

The process makes use of the following User Exits. Samples of these exits are provided in the Base Clist library. These should be checked out to the ISPW SITE application CLIST library, changed as required, and promoted to the SITE production level.

WZUALG* Requires Customization - Generate Parms WZUALX* Requires Customization - Task Selection WZUALO* Requires Customization - Override Table

Customization of these is specific to the Application being loaded and is described in “Step 3 – Exits and Special Customizations” on page 14-7.

6 Load Generate Parameters The Application Load utility is used to load the Generate Parameters into ISPW.

Table 14-1. Steps to migrate an Application ISPW

)CM CUSTOMIZE THE FOLLOWING AS REQUIRED)CM)SET ALLOPRM = UNIT=SYSDA)SET TRACE = NOTYES)SET DB2SSN = DSN1)SET DB2RUN = DSN610.RUNLIB.LOAD)SET WZAUTH = WZZF330

Application Load Utility 14-3

Option M.ALThe Application Load Utility operates at the Application/Stream level and it can be initiated from the ISPW Maintenance Menus (Option M, selection X, selection AL) or simply via "=M.AL".

On entry to the option the following screen is displayed:

Figure 14-2. Option M.AL

Field Descriptions

The following table describes each input field on the Application Load Screen

ISPW INITIAL APPLICATION LOADCommand ===>Application ==> TSTI Level ==> PRODStream ==> BASIC Signout Path ==> TEST Assignment ==> TSTI000003 Release ==>Process Option ==> R (O-Build OverRide Table, R=Task Report ) (T-Task Load, G-Generate Parms Load ) (C-Clean Up/Delete Tasks Testing Only! )Edit Generated JCL ==> Y (Y-Edit JCL before Submit, N-Auto Submit )OverRide DataSet ==>Confirm and/or change the required Selection Criteria and Process Option. Press Enter to continue or END to terminate.JOBCARD Information:==> //CRAIG1 JOB (ACCT#),MSGCLASS=X,CLASS=A,NOTIFY=CRAIG==> //*==> //*==> //*


Step 1 – Define Application Data

Objective

The objective of this step is to have the new Application fully defined in ISPW.

What to Define

The following information needs to be defined as a minimum:

Table 14-2. Field DescriptionsTable 14-3.


Application/ Stream This must be a valid ISPW Application and Stream and represents the Application that the tasks are to be loaded into.

Level This represents the level that the tasks are being loaded. As well as the Production Level, Work-in-progress levels can be loaded.

Signout Path Every Task (even if loaded at PROD) must have the signout Path specified. This is the lowest level in the life- cycle.

Assignment Assignment in ISPW into which the new tasks will be loaded.

Release This is an optional field where the tasks can be associated with a Release.

Process Option Specifies the function to be performed. The individual options are referenced in the following sections.

Edit Generated JCL

Specifies if the JCL is to be presented to the user in ISPF Edit rather than submitted directly.

Valid values:

Y – Edit JCL

N – Submit directly

Override Dataset An optional parameter where the Override dataset is specified if the override facility is being used.

Jobcard JCL Jobcard for batch job that is generated.


It is essential that this data is accurately defined for the Application Load to work correctly.

IMPORTANT:

Component Type Domain—In defining the Application Types in M.AD(T) there is a field for the Component Domain. It is essential that this is correctly defined if there are any Component naming constraints for this and other applications. Following is a discussion on this feature.

Setting up a Component Domain

A component domain enforces uniqueness of a component name for all component types that have been made a part of the domain. This is useful when shared libraries are being used for more than one component type.

Example:

In application XYZ, the component types COB and COPY are both stored in one set of libraries (as defined in option AD (Names)). This means that a component domain must be set up to ensure that components of these 2 types are not created with the same component name (each member must be unique in a dataset). For example, if a component of type COB has been created with a name of TESTPGM1, the component domain will prevent a component of type COPY being created with a name of TESTPGM1.

The procedure below describes how to set up a component domain using the example above:

Table 14-4. Define Application Data

Definition Data Option Description

Application M.AP The new ISPW Application is required to be added to the list of ISPW Applications.

Application/Stream M.AD The Application Definitions are defined to a Stream.

Application Component Types M.AD(T)

Add the Component Types to the Application Definition. The Types must have already been defined to M.CT. Important: See the note below about Component Type Domain.

Application Dataset Names M.AD(N) For each Application Level and Type, the Dataset Names are specified.

Application Component Type Associations M.AD(A)

For each “Generatable” Component Type the associations must be defined (e.g. DBRM, LOAD etc).

Assignment Prefix M.PAn Assignment will need to be created before the Application Load process can be performed. An Assignment Prefix is required for this.


Note: This is just one example of when a Domain is useful. If Applications share libraries (including Load Libraries) then a Domain will need to be defined for all those types across all the applications that share those libraries.

Step 2 — Identify Application Components

Objective

All of the Components for the Application to be loaded into ISPW must be able to be identified for the Application Load to work.

The Problem

It is probable that the datasets that currently contain the Application components are polluted with:

• Components from other Applications• Components that are no longer required• “Junk” Components that should never have been there in the first place

It is essential that the Load utility is able to identify the Application’s components.

The Solution

There are two ways that this problem can be solved:

• Extract all of the Application (source) components into a new set of libraries

• User the Override capability to create a distinct list of all components that the Load utility can drive its processing off.

Each of these solutions is discussed below.

Table 14-5. Setting Up a Component Domain

Step Action

1

Identify which application component types are going to be part of the domain.

Example:

COB and COPY component types in application XYZ.

2

Think of a name that suitably describes the component domain. A domain name can be up to 8 characters long.

Example:

COBCOPY

3

Change the component domain field to the domain name identified in step 2 in M.AD, Types. Do this for each application component type identified in step 1.

Example:

Update the component domain field to COBCOPY for Types COB and COPY in application XYZ.

4 Save the changes and refresh the server cache.


Extract into new libraries

This is the easiest way to identify an Application’s components. Prior to the migration, the Application support group would go through the source datasets and copy over all participating components to completely new datasets. The Load utility can be pointed to look at the new datasets and load only those components.

The Load utility is driven from the source components and so it is only necessary to separate out the source components, however it is probably good practice to separate out the generated parts (LOAD, DBRM etc.) as well.

Use Override Capability

For organizations with some kind of data dictionary or repository that contains the complete list of components, a file can be created listing them all and this can be used to limit the loading of tasks to those specified in the file. This is described further in “Step 3 – Exits and Special Customizations” on page 14-7.

Step 3 – Exits and Special CustomizationsThe purpose of this step is to review the Exits and Special Customizations that are provided and change them as required.

What Exits are available?

The following REXX exits are available:

These exits are described in the following sections.

The Override Capability

The Override facility is a way to include organization specific knowledge into the Application Load and Generate Parameters processes. A flat file can be created to include information about components that may be used in a variety of ways including:

• Limiting the components to be loaded

• Setting the correct Component Type for a component

• Including description data for the Task Load process

• Providing the correct Generate parameters for a component

Table 14-6. Available REXX Exits

Exit Description

WZUALO This exit is used to load the “Override” table from a sequential dataset. The Override table can be used as input to both WZUALX and WZUALG.

WZUALX

This is invoked for each Component to be loaded for the purposes of:

Accepting the Component unchanged;

Rejecting the Component; or

Accepting the Component with new information (e.g. Description).

WZUALG This is invoked for each component to accurately set the ISPW Generate parameters for that component.


A flat file is created with information to be included in the process, which is converted to an ISPF table that is then available to the Task Load and Generate Parameters processes.

WZUALO – Override Exit

This User Exit that can be tailored to load the Override table from the Sequential Override Dataset specified on the M.AL panel. The Override table can make extra variables available to the conversion process - Component Descriptions or special Compile Options could be loaded using this table.

When it is called

This User Exit is called when Process Option 'O' is requested.

What needs to be changed

If the Override feature is used, this exit will need to be changed to match the Override file that is created. The section of code requiring change is shown below:

Figure 14-3. Changing the Override Exit

The above example depicts the situation where the Override file is used to include a component description and a flag that indicates whether SQL is used in the program.

How Override information is used in the other exits

Once the Override table is created, the other exits can simply do a TBGET for the current member name and type to refresh the ISPF variables with the Override information.

WZUALX – Load Exit

This exit extends the Application Load process beyond just the inspection of what components are in the Application Datasets.

This exit is called during the Task Report (option R) and Task Load (option processes.

Upon entry to this exit the details for a component and the associated parts are made available on the REXX stack. This has been gathered during the scanning of the Application datasets. The exit reads details from the stack and it can accept the Task Load unchanged, Reject the Task Load or replace the Task Load with new details which it writes back to the Stack.

Process_F33X:/* | For the Purpose of this Sample Exit, the Sequential Input File | DD ALGXIN has been created with the following structure | | Member Name Col 1-8 | Member Type Col 9-12 | SQL Flag Col 13 | Description Col 14-64 | */ Do k=1 to gx.0 by 1 "TBVCLEAR " overtab member=substr(gx.k,1,8) membtype=substr(gx.k,9,4) wzgsql=substr(gx.k,13,1) cmpndesc=substr(gx.k,14,50) call Update_OverRide_Table End Return


In addition, a simple TBGET for the Override table <APPL>ALGX will make available all variables that were defined for a Component using the Override process (option O).

Stack Variables

There are two Stack variables:

Task – string containing details about the main component

Part.n – an array containing a string for each of the parts associated with the task.

Task

Format of the Task variable:

Part.n

Format of the Part.n variable is:

The number of Part records for the task is stored in the variable “partcnt”

Return Codes

The return code from the exit determines the subsequent processing for the Task Load:

Table 14-7. Task Variable Format

Field Pos Size

Member Type 1 4

Member Name 6 8

Target Env. 24 4

Source DSN 29 44

Application 74 4

Stream 79 8

Level 88 4

Table 14-8. Part.n Variable Format

Field Pos Size

Part Type 1 4

Part Name 6 8

Association 15 4

Sequence 21 1

Target Env. 24 4

Part DSN 29 44

Table 14-9. Return Codes

Return Code Explanation

0 Accept the component details unchanged

2 Update the component details with the updated variables

4 Reject the component for loading


WZUALG – Generate Parameters Exit

This REXX is a User Exit that can be tailored to define the Compile Parameters for a component.

ISPW uses saved parameters against each component to determine it’s generate processing. These are called Compile Parameters and are used to tailor the generate process at generate run time. This exit is used to populate the ISPW Generate Parameters according to the installation requirements.

This User Exit is called for each Component that is defined to ISPW as a Generated Type, when Process Option 'G' is requested.

Interface Variables

On entry to this exit, there are two groups of ISPF variables, which are retrieved using the following ISPF VGET Service calls:

"VGET (WZXVARS WZUVARS)" "VGET ("WZXVARS WZUVARS")"

In addition, a TBGET for the Override table <APPL>ALGX will make available all variables that were defined for a Component using process Option O (if this is used).

WZUVARS

This group of variables become the Compile Table variables for the component, and is derived from the site model Compile Table $ZZCPRM. On entry to this REXX the variables are set to NULL with the exception of GMT1NAME GMT2NAME GMT3NAME GMT1LNAM GMT2LNAM

GMT3LNAM and LOADNAME, which are initialized with the component name if there is a corresponding association for it in M.AD. The variables MEMBER and MEMBTYPE are also initialized with the Component Name and Component Type.

The User Exit should examine the contents of variables defined by WZXVARS and initialize variables defined by WZUVARS and save them in the shared pool, as needed.

WZXVARS

WZXVARS provides a list of variables that are available to the conversion process. These variables can be used to help decide how the Compile Table variables should be initialized

Table 14-10.WZXVARS

Variable Description

MTYPE ISPW Member Type

MNAME ISPW Member Name

WTENV ISPW Target Environment

WAPPL ISPW Application

WSTREAM ISPW Stream

GMT1TYPE

Generate Type (e.g. DBRM, LIST, OBJ etc.) defined for the association.

GMT2TYPE

GMT3TYPE

GMT1LTYP

GMT2LTYP

GMT3LTYP


Step 4 – Review Load ReportThis step is performed to verify that correct Tasks will be loaded (without actually loading them). It uses the same Filtering and User Exits as the Task Load, so it is a useful tool to test any User Exits and to confirm that the Component registration process will work correctly.

How it is called

Option “R” from the M.AL screen invokes this function.

Processing Overview

Producing the Load Report involves the following steps:

Filter List

When option 'R' is selected a list of all the Datasets defined for the Application/Stream and Level is presented, as shown below. This list is derived from the M.AD Tables.

Figure 14-4. List of Datasets Defined for the Application/Stream and Level

In this example, a Member Pattern is selected for the COB Type and the LOAD library is removed. This would reflect an Application that follows a certain naming standard where the modules result in Object code only.

Review the Report

After the job has been submitted the report should be reviewed for completeness, as this is the basis upon which the components will be registered to ISPW as tasks. An example report is shown below.

Table 14-11.Producing the Load Report

Description

1 Select Option “R” and specify Filter selections.

2 Press <PF3> to create initial report based upon just scanning the datasets (<prefix>.WALDSN.<APPL>.<LEVEL>). The JCL is also created to process the exits.

3

Submit the JCL. This process the initial report with the exit WZUALX and produces the final report that corresponds to what will be loaded during the Task Load. The report name is:

<prefix>.WALRPT.<APPL>.<LEVEL>.

ISPW APPLICATION LOAD - DATASETS Row 1 of 5 Command ===> Scroll ===> CSR

Update the Library and Member pattern Name to be used for the generation of the ISPW Repository Data Report. Press <PF3> to process or enter "CANCEL" to abort. Member Library Type Clas Lev Pattern Name__ COB PROD A* TEST.F33X.PROD.COB__ DBRM PROD * TEST.F33X.PROD.DBRMLIB __ LIST PROD * TEST.F33X.PROD.LIST_D LOAD PROD * TEST.F33X.PROD.LOAD__ OBJ PROD * TEST.F33X.PROD.OBJ


Step 5 – Load TasksThis step is run to register the components for the Application to ISPW. It will populate an ISPW Assignment with an ISPW Task for each component.

How it is called

Option “T” from the M.AL screen invokes this function.

Processing Overview

Producing the Task Load involves the following steps. The first three steps are identical to those for Option “R”.

Table 14-12.Review the Report

COB A0000001 TEST.F33X.PROD.COB

DBRM A0000001 GMT1 1 TEST.F33X.PROD.DBRMLIB

OBJ A0000001 GMT1 2 TEST.F33X.PROD.OBJ

LIST A0000001 GMT3 1 TEST.F33X.PROD.LIST





















Table 14-13.Producing the Task Load

Description

1 Select Option “T” and specify Filter selections.

2 Press <PF3> to create initial report based upon just scanning the datasets (<prefix>.WALDSN.<APPL>.<LEVEL>). The JCL is also created to process the exits.


Filter List

When option 'T' is selected a list of all the Datasets defined for the Application/Stream and Level is presented, as shown below. This list is derived from the M.AD Tables.

Figure 14-5. List of Datasets Defined for the Application/Stream and Level

Using the same example as for Option “R”, a Member Pattern is selected for the COB Type and the LOAD library is removed. This would reflect an Application that follows a certain naming standard where the modules result in Object code only.

Pressing <PF3> from this screen will cause all of the datasets to be scanned and the initial report and JCL to be created.

ECI Commands

The ECI Commands are built from the Report file and placed into the dataset


ECI Step

The final step of the Task Load JCL executes ISPW’s External Call Interface.

The ECI communicates with ISPW and processes each ECI command, loading the Tasks and associated Parts. This step should end with a return code of 0. Any errors are reported in the job output.

Assignment Tasklist

After the Task Load has been successfully run, the ISPW Assignment should be populated with the tasks as follows:

3

Submit the JCL. This process the initial report with the exit WZUALX and produces the final report that corresponds to what will be loaded during the Task Load. The report name is:


4

The JCL then builds the ISPW External Call Interface (ECI) commands from the report to load the components into ISPW as Tasks. These will be placed in the dataset The report name is:

<prefix>.WALECI.<APPL>.<LEVEL>.

5 The JCL then runs the ISPW ECI to load the tasks in ISPW.

6 Go into the ISPW Assignment and see the newly loaded Tasks.

Table 14-13.Producing the Task Load

ISPW APPLICATION LOAD - DATASETS Row 1 of 5 Command ===> Scroll ===> CSR

Update the Library and Member pattern Name to be used for the generation of the ISPW Repository Data Report. Press <PF3> to process or enter "CANCEL" to abort. Member Library Type Clas Lev Pattern Name__ COB PROD A* TEST.F33X.PROD.COB__ DBRM PROD * TEST.F33X.PROD.DBRMLIB __ LIST PROD * TEST.F33X.PROD.LIST_D LOAD PROD * TEST.F33X.PROD.LOAD__ OBJ PROD * TEST.F33X.PROD.OBJ


Figure 14-6. Test Application Load

Note the last op of TL. This indicates that the task was loaded with the ECI Task Load call.

Entering the QP (Query Parts) operation will show that the parts have been successfully registered.

Figure 14-7. Query Parts

Step 6 – Load Generate ParametersISPW uses saved parameters against each component to determine it’s generate processing. These are called Compile Parameters and are used to tailor the generate process at generate run time. This step populates the ISPW Generate Parameters according to the installation requirements.

Select this Option “G” to load the Generate Parms for the target ISPW Application and Stream.

The following steps are involved in populating the Generate Parameters.

Job Output

Output from the job displays the processing for each component.

ASSIGNMENT F33X000022: TEST APPLICATION LOAD Row 1 of 10Command ===> Scroll ===> PAGE More -->Esssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss e Select(/) Add Approve Close Join Reset Show/Hide Work ++/-- Dsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss Type Name Lev Op A User Appl Date MM DD Time Status COB A0000001 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000002 PROD TL CRAIG F33X 2003-08-21 00:41QP COB A0000003 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000004 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000005 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000006 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000007 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000008 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000009 PROD TL CRAIG F33X 2003-08-21 00:41 COB A0000010 PROD TL CRAIG F33X 2003-08-21 00:41------------------------------- Bottom of List -------------------------------

********************************* Top of Data *********************************Appl Lev Part Clas PartName Reference Tenv Coll Variable---- ---- ---- ---- -------- --------- ---- ---- -------- F33X PROD DBRM A0000003 Explicit TL GMT1NAME F33X PROD OBJ A0000003 Explicit TL GMT1LNAM F33X PROD LIST A0000003 Explicit TL GMT3NAME******************************** Bottom of Data *******************************

Table 14-14.Populating the Generate Parameters

Description

1 Select Option “G” and JCL will be created.

2 The first step in the JCL communicates with ISPW to create a list of all components for the ISPW Application just loaded.

3The ISPW program WZZALG is executed, which reads in the Task data and for each Task passes control to the User Exit WZUALG for any special processing and then writes the Generate Parameters for the Component


Figure 14-8. Job Output

The variables listed in above are specific to that ISPW Task and are stored in ISPW to be used when a Generate is requested.

Option C – Cleanup TasksOption “C” will delete all ISPW Tasks for an ISPW Application. It is useful during testing or if a conversion needs to be started over after the ISPW Task Load step has been completed.

ISPW’s Data repository is cleared of all Task related detail for the specified Application. SQL is used to perform this task. This function uses Skeleton WZZALCU to generate a batch job that you submit.

CAUTION:It deletes all information from ISPW for an Application.

Processing Compile Table for Type COB Name A0000001 --MEMBTYPE COB --MEMBER A0000001 --LOADNAME A0000001 --WZZCOPY Y --WZZLINK Y --GMT1NAME A0000001 --GMT3NAME A0000001 --WZGPROG N --WZGBIND N --WZGPKG N --WZGPLNB N Compile Table Add Complete for Type COB Member A0000001


15-1

Chapter 15.

15Setting Up Warehouses for Topaz for Total Test AssetsChap 15

Developers using Topaz for Total Test will want to retain and improve their test assets. They can store them in ISPW along with their code and other Tasks in their Assignment.

Test assets stored in ISPW can also be downloaded using a Jenkins plugin and then run in your DevOps toolchain.

Test assets stored at the Prod level can be brought down for your use as you modify your program. You can then promote them up as your changes go through the lifecycle.

This chapter will explain what the ISPW Administrator must do to set up the Folders to store Topaz for Total Test assets.

Topaz for Total Test File ExtensionsTable 15-1lists the file extensions associated with Topaz for Total Test assets.

Defining a WarehouseWhen enabling ISPW to hold Topaz for Total Test assets, observe the following general guidelines:

• To start, you will want to set up warehouses to store the files.• These Windows folders can’t be stored in the same way PDS members are stored.• Make sure you are in Update mode.

Table 15-1. Topaz for Total Test File Extensions

Extension Type Content Type

listructure tlst All T for Text except for FLDR

interface tint

testscenario tscn

testsuite tsui

prefs tprf

result trsl

stub tstb

archive tarc

jcl tjcl Not to be confused with JCL

html html Probably already defined

xml xml Probably already defined

project tprj

folders FLDR B for Binary Probably already defined


1. The Warehouses function is found under option WH of the main ISPW Administrator Maintenance screen (Figure 15-1). Type WH on the Command line and press Enter. The Warehouse Table screen is displayed as shown in Figure 15-2.

Figure 15-1. WH on ISPW Administrator Maintenance Screen

Figure 15-2. Warehouse Table Screen

2. To add a warehouse on the Warehouse Table screen, type A on the Command line and press Enter. The Modify Warehouse Table Detail screen (Figure 15-3) is displayed.

ISPW M ISPW ADMINISTRATOR MAINTENANCE (PROD)Command ===> WH Reference Data ( R ) Technical Support AD Application Streams AN Approver Names SM Server Maintenance AP Applications CH Change Codes U User List AR Approval Rules CR Component Ref. WH Warehouses BC Base Components ET Extension Tables WP Warehouse Policies CC Component Category SV Servers CT Component Types P Prefix Numbers EC Extension Classes SC Set Class ER External References GX Component groups EX Exits AG Application groups ST Streams General Special Technologies X Utility Functions T1 Technology 1 Z Generate Parms T2 Technology 2 DP Deploy T3 Technology 3Enter END command to return to the previous menu.

ISPW WAREHOUSE TABLE (PROD) BROWSE MODECommand ===> A Scroll ===> CSRList Commands: L Locate Entry, U Update ModeLine Commands: S Select, N Storage Names Warehouse Type Description #WHID MVS Production Warehouse ISPWCT MVS Staging WH ISPWPROD MVS PROD Warehouse WHOUSETT MVS Warehouse for TTT assets******************************* Bottom of data ********************************

Setting Up Warehouses for Topaz for Total Test Assets 15-3

Figure 15-3. Modify Warehouse Table Detail Screen

3. On the Modify Warehouse Table Details screen (Figure 15-3), specify the following attributes that are required to define a Warehouse, then press Enter:

Warehouse – A logical name for the warehouse. The warehouse name is a key field, and it must be unique.

Allocation Type – The type of allocation parameters used by this warehouse. For an MVS system, this value would be MVS. For Windows, Linux, or Unix, the value would be WIN.

CT/RS Server Name – The name of the CT or Remote Server that manages this warehouse. This must be defined in the server table in M.SV.

Description – Descriptive information used to identify the warehouse.

4. Return to the ISPW Administrator Maintenance screen, type AD on the Command line as shown in Figure 15-4, and press Enter. The Reference Data Maintenance (M.R) screen is displayed (Figure 15-5).

Figure 15-4. AD on ISPW Administrator Maintenance Screen

ISPW MODIFY WAREHOUSE TABLE DETAIL (PROD)Command ===> Warehouse (KEY) ==> WHOUSETT Allocation Type ==> MVS (MVS or WIN) CT/RS Server Name ==> ISPWCT (Use WIN for all Open Systems) Description ==> Warehouse for TTT assets WIN Path Segment . . : or MVS Dataset Prefix . : ISPW.WHTTT (see PF1 for details of Path Segment and Dataset Prefix) Management class . . . (Blank for default management class ) Storage class . . . . (Blank for default storage class ) Volume serial . . . . NSM004 (Blank for no volume specification ) Device type . . . . . (Generic unit or device address ) Data class . . . . . . (Blank for default data class ) Space units . . . . . TRACK (BLKS,TRKS,CYLS,MB ) Primary quantity . . 25 (In above units ) Secondary quantity 5 (In above units )Press END to return

ISPW M ISPW ADMINISTRATOR MAINTENANCE (PROD)Command ===> AD Reference Data ( R ) Technical Support AD Application Streams AN Approver Names SM Server Maintenance AP Applications CH Change Codes U User List AR Approval Rules CR Component Ref. WH Warehouses BC Base Components ET Extension Tables WP Warehouse Policies CC Component Category SV Servers CT Component Types P Prefix Numbers EC Extension Classes SC Set Class ER External References GX Component groups EX Exits AG Application groups ST Streams General Special Technologies X Utility Functions T1 Technology 1 Z Generate Parms T2 Technology 2 DP Deploy T3 Technology 3Enter END command to return to the previous menu.


Figure 15-5. Reference Data Maintenance Screen

5. Select your Stream and Application on the M.R screen as shown in Figure 15-5 and press Enter. The Application Stream Definition screen is displayed (Figure 15-6).

Figure 15-6. Application Stream Definition Screen

6. On the Application Stream Definition screen (Figure 15-6), type the L line command next to the Application Stream you defined earlier and press Enter. The Application Stream Levels (M.AD/L) screen is displayed as shown in Figure 15-7.

ISPW M.R REFERENCE DATA MAINTENANCE (PROD) Row 16 to 30 of 33Command ===> Scroll ===> CSRList Commands: A Add, L Locate Entry, B Browse ModeLine Commands: S Select, D Delete, C Clone, I Import, E Export V View, M Modify, A Activate Code Appl Stream Vers Version Description Active Loaded Refresh Reqd AD AD NXS1 ITEG 0002 NXS1 Application Y Y AD NXS1 ITEG 0001 NXS1 ApplicationS AD PLAY PLAY 0002 Play Demo Y Y AD PLAY PLAY 0001 reference AD PLAY PLAY 0000 INSTALL VERSION AD SAMP SAMP 0001 sample demo version Y Y AD SCLM ITEG 0002 SCLM Conversion Util Y Y AD SERG ITEG 0001 test AD SITE SITE 0002 17.02.06 maintenance Y Y AD SITE SITE 0001 reference AD SITE SITE 0000 INSTALL VERSION AD TOTO ITEG 0001 test AD TPZC ITEG 0002 TPZC Application Y Y AD UTIL SITE 0002 Utilities Y Y AD VFI VFI 0002 Creation of appl VFI Y Y

ISPW M.AD APPLICATION STREAM DEFINITION - PROD UPDATE MODECommand ===>Line Commands: S Select, L Levels, T Types, N Names, A Associations, P Plans M Modify, F Flags, Z Allocate, V Validate Appl Stream Application Stream Description Cref L PLAY PLAY ISPW Training Application Y******************************* Bottom of data ********************************

Setting Up Warehouses for Topaz for Total Test Assets 15-5

Figure 15-7. Application Stream Levels Screen

7. On the Application Stream Levels screen (Figure 15-7), select each level by typing the S line command next to the Level name, then press Enter. The Modify Application Stream Level screen is displayed (Figure 15-8).

Figure 15-8. Modify Application Stream Level Screen

8. On the Modify Application Stream Level screen (Figure 15-8), define Warehouses for the higher Levels in your development lifecycle. The DEV Level does not require a Warehouse.

9. On the ISPW Administrator Maintenance screen (Figure 15-1), type ER on the Command line and press Enter. The Modify External Reference Detail screen is displayed as shown in Figure 15-9.

ISPW M.AD/L APPLICATION PLAY STREAM PLAY LEVELS UPDATE MODECommand ===> Scroll ===> CSRList Commands: A Add Entry, L Locate Entry, B Browse ModeLine Commands: S Select, D Delete, N Names, F Flags, P Plans, X Extensions Z Allocate Level Next Level DEV1 STG1 DEV2 STG2 FIX HLD HLD PRD PRDS QA PRD STG1 QA STG2 QA******************************* Bottom of data ********************************

ISPW M.AD/L MODIFY APPLICATION PLAY STREAM PLAY LEVEL (PROD)Command ===>Enter required details: Level (KEY) ==> QA Promote Analysis ==> (Y - Yes) Next Level ==> PRD Impact Approvals ==> (Y/S/C see help for details) Impl Exit? ==> (D - Deploy, Y - External) Warehouse for Sources : Name ==> ISPWPROD Policy ==> KEEP3INASSIGN Gen Types: Name ==> ISPWPROD Policy ==> KEEP3INASSIGN Set Scheduling Information: Set Class ==> A Job Name ==> Queue Name ==> Failure Notify ==> DB2 Information: Impl Name/Rule ==> Name or Rule to determine Plan Implementation DB2 Subsys ==> Sub-system applicable for this Level DBRM Libs ==> XREF Name ==> XREF Lib ==> (R or W)Press ENTER to complete the change or END to terminateNote: You can add a new entry by overtyping the Key with a new unique value


Figure 15-9. Modify External Reference Detail Screen

10. An External Reference entry must exist for each application that requires a folder structure to support relative paths. On the Modify External Reference Detail screen (Figure 15-9), in the Type Code (KEY) field, type $REL followed by the key for your application name, for example $RELTTTA. In the Description field, type Relative Path Support - Yes, and in the Variable/Dsname field, type Y. Press Enter.

ISPW M.R REFERENCE DATA MAINTENANCE (PROD) UPDATE MODECommand ===> Scroll ===> CSRList Commands: A Add, L Locate Entry, B Browse ModeLine Commands: S Select, D Delete, C Clone, I Import, E Export V View, M Modify, A Activate Code N/A N/A Vers Version Description Active Loaded Refresh Reqd ERS ER 0001 Reference Y Y ER 0000 INSTALL VERSION******************************* Bottom of data ********************************

IN THE INPUT POWERPOINT, THIS SCREEN (PAGE 24) DID NOT MATCH THE CORRESPONDING BITMAP IT FOLLOWED (PAGE 23). BITMAP HAS THE “MODIFY EXTERNAL REFERENCE DETAIL” SCREEN, BUT TEXT SCREENSHOT HAS “REFERENCE DATA MAINTENANCE” SCREEN.********** NEED CORRECT SCREEN *********

16-1

Chapter 16.

16Advanced Configuration Chap 16

This chapter describes advanced configuration options for ISPW.

Non-Generating Binary ComponentsCreating a non-generating binary component allows ISPW to accept and manage the life-cycle of a non-mainframe type file. For example, ISPW can track the life-cycle of a Word document, a PDF, or even a JPEG image file. This vastly extends the usefulness of ISPW to manage the life-cycle and deployment of applications and associated documentation and data.

CAUTION:Existence of a newly-created component type becomes permanent once a member of that component type is promoted to the PROD level.

Accessing Non-Generating Binary Components

The warehouse datasets that contain the managed files can be accessed through the ISPW Eclipse plugin. The DEV level copy is stored on the workstation at checkout time and is uploaded to the following HOLD levels upon promotion. The files can also be accessed and interacted with using the PHP scripting interface available in the Remote ISPW Server.

Creating a Non-Generating Binary Component Type

There are three key steps to enable the use of this flexible component type:

• Define the component type• Update the stream definition• Update the application definition.

These steps are described in detail in the following three subsections.

Define the Component Type1. Type M (Maintenance) in the OPTION field of the ISPW Main Menu and press Enter.

2. Type CT (Component Type) in the OPTION field and press Enter.

3. Select the Component Type Table for the addition.

4. Type U (Update) in the OPTION field and press Enter to invoke update mode.

5. Type A (Add Entry) in the OPTION field and press Enter.

6. Complete the following for this type:

a. Specify the Component Type (KEY). This is an identifier for the type, and typically the file extension is used. For example, the type for a Word .doc file would be DOC.


b. Specify the Name length. This is the length of the member’s name. The default is 8 bytes, which is useful for mainframe file types. The maximum is 64 bytes, which is useful for open system names.

c. Enter a Description. This should describe what type of “file” this component type will hold as a member.

d. Set the Cycle Flag to Y (Yes) to indicate that ISPW is to manage the life-cycle of this “file” type.

e. Set the Generate Flag to N (No) because this type of component cannot be generated.

f. Set the Case Sensitive flag to Y (Yes) to preserve case.

g. Set Content Type to B (Binary).

h. Set File Extension to the file extension that would be preferred as the appended file extension in the event that the “file” name does not already have one on checkout. Only one extension can be specified. Do not include the leading period (.). For example, .doc should be specified as doc.

i. Submit the Entry to the Component Type Table.

7. Type B in the OPTION field to return to browse mode.

8. Press PF3 as required to return to the ISPW Main Menu.

Update the Stream Definition1. Type M (Maintenance) in the OPTION field of the ISPW Main Menu and press Enter.

2. Type S (Streams) in the OPTION field and press Enter.

3. Select the Stream for the addition.

4. Type U (Update) in the OPTION field and press Enter to enter Update mode.

5. Type T (Types) in the OPTION field and press Enter.

6. Type A (Add entry) in the OPTION field and press Enter.


a. Specify the Component Type (KEY). This is an identifier for the type, and typically the file extension is used. For example, the type for a Word .doc file would be DOC.

b. Enter a Description. This should describe the component type being added to the stream definition.

c. Set the Warehouse Storage flag to Y (Yes).

d. Submit the Entry to the Stream Definition.



Notes:

• An asterisk will be shown on the Names table next the various levels at which the component can exist to denote that the component is warehouse only. No datasets will be allocated on the host (mainframe) for these levels.

• The type should automatically pull from the Component Type definition table entry.

Update the Application Definition1. Type M (Maintenance) in the OPTION field of the ISPW Main Menu and press Enter.

2. Type AD (Application Streams) in the OPTION field and press Enter.

Advanced Configuration 16-3

3. Type U (Update) in the OPTION field and press Enter to enter Update mode.


a. For Reference Code, specify AD (Application Definition).

b. Application Stream will use the previously-created Stream Definition.

c. Enter a Description. This should describe the application being defined.

5. Submit the Entry to the Application Definition Table.



Note: WS will be displayed next to the lowest level of the life-cycle to indicate that anything at the DEV level is held on the local workstation—rather than the ISPW host—when browsing the Application Definition.


17-1

Chapter 17.

17Troubleshooting Chap 17

This chapter describes potential problems that can be avoided and on-going support issues. According to past experiences with various sites running ISPW, a number of situations have been found. They either should be avoided or monitored to reduce the potential number of support problems. These situations are described in this section.

ISPW Support Versus ISPF SupportBecause ISPW is closely linked with ISPF, any changes to ISPF could affect ISPW. If the same person or group is not supporting both products, then there are potential problems if ISPF is upgraded without the corresponding changes to ISPW.

Things to watch out for:

Changes to the ISPF primary option menu or the Printoff or Script invocations. You may need to change:

The ISPW primary menu to pick up the new ISPF invocations.

M.ER options for the Printoff (3.6) calls.

The Z functions list on the main menu if you are using that option, via M.CZ or M.CO.

Recommendation:

ISPW should either be supported by the systems programming group, or the ISPW support staff should be party to regular change control meetings to anticipate any impacts.

ISPW Support Versus Other Program ProductsFurther to the point above, ISPW interfaces to many technologies at any site, which undergo regular upgrades.

Things to watch out for:

Changes to any of these products that are under the ISPW umbrella. Most of the time these changes are transparent to ISPW but you should check with us if unsure of the impacts. See the ISPW Interfaces Guide, the section on new versions and their implications.

Recommendation:

ISPW should either be supported by the systems programming group, or the ISPW support staff should be party to regular change control meetings to anticipate any impacts.


Upgrades to Compile ProcsIn the planning phase we discussed how the compiles are going to be installed and supported, and the “Skels only” versus the “Procs and Skels” approach.

If you have chosen to keep the Compile Procs separate from the Skels then there are potential synchronization problems.

Watch out for – changes to the Compile Procs that may affect the ISPW Skeletons. It is possible that the skeleton itself will need to be changed.

Recommendation:

ISPW should either be supported by the group responsible for the compiler interfaces, or the ISPW support staff should be party to regular change control meetings to anticipate any impacts.

Multiple Component Types Using the Same LibrariesGenerally, one set of libraries can be used for many Component Types if they all have the same dataset format (e.g. 80 bytes, fixed). This works well for such types as COB, JOB, COPY, etc. If this is the case, component domains should be set up to prevent these different component types using the same name. A component name has to be unique across component types because they are sharing the same libraries. See Chapter 3, “Maintenance Functions” on setting up component domains.

Warning:

If a component domain is not set up, ISPW processing may fail on the copy operation when it checks if a component with the same name already exists in the target library. Also, this check is only performed for cycle component types. If shared libraries are used for a mixture of cycle types and non-cycle types, because no check is performed, component data at the TEST level may be deleted!

A-1

Appendix A.Appendix A.

ASecurity App A

Objects and Methods

Defined Objects and Methods

This Appendix describes all of the protected ISPW Objects with details of the Methods, usage, default values and variable usage.

Variable Substitution

Many security checks are dependent upon dynamic information such as the ISPW Application. In the definition of the Security Rules, these are specified as variables. A complete list of available variable names and their meaning is outlined below, and the sections describing each Object specify which of these variables are valid. Variables marked with (*) are available for all Security Rules and are not specified again for each Object/Method.

Table A-1. Variable Substitution

Variable ID Description

Server (*) The ServerID as specified in the SDEFINI file

Object (*) The Object of the Security Rule

Method (*) The Method of the Security Rule

appl ISPW Application

Stream Stream Name

level ISPW Level

slevel Signout level for a Task

tlevel Target level for an operation

membenv Member Environment (for example, OUTS/TEST/HOLD/PROD)

membtype Component Type as defined in M.AD

member Component Name

popt ISPW Operation (for example, G/P, etc.)

apprname Approver Name as defined in the Approval Rules

apprcode “A” for Approve and “D” for Deny

chgtype Set Change Type

owner Container Owner

agrname Application Group Name

A-2 ISPW Technical Reference Guide

Access Levels

Each Rule defines a level of access to be checked. The following table lists the valid levels:

SERVER

The SERVER object protects resources to do with accessing and controlling the ISPW Server.

ASGNMENT

The ASGNMENT object protects actions against ISPW Assignments.

Table A-2. Access Levels

Access Meaning

NONE No access is required. ISPW will not do a security check.

READ Read access

UPDATE Update access

ALTER Alter access

Table A-3. SERVER

Method Usage Default Security Check AvailableVariables

LOGONControls access to the server. All ISPW users must be authorized to this function

<Server>.SERVER.LOGON

Access: READ

ADMINDetermines whether the user is an administrator so that they can see all of the “M” functions

<Server>.SERVER.ADMIN

Access: READ

REFRESH Administrator function to refresh server information

<Server>.SERVER.REFRESH

Access: UPDATE

TRACEON Administrator function to turn server tracing on

<Server>.SERVER.TRACE

Access: UPDATE

TRACEOFF Administrator function to turn server tracing off


Access: UPDATE

TRACESW Administrator function to send Trace Commands to the Server


Access: ALTER

MAINT Controls access to the Component Transport Housekeeping operations

<Server>.SERVER.MAINT

Access: ALTER

CTIDENT Used to identify a Component Transport Address space <Server>.SERVER.CTIDENT.<Systtyp> Systtyp

RTCONFIG Secures the use of a Run Time Config <Server>.SERVER.RTCONFIG.<rtconfig> Rtconfig

Table A-4. ASGNMENT


ADD Controls who can add an Assignment<Server>.ASGNMENT.<Appl>

Access: ALTER

Appl StreamOwner Agrname

Security A-3

RELEASE

The RELEASE object protects actions against ISPW Release.

SET

The SET object protects actions against ISPW Set.

MODIFY Controls who can modify an Assignment<Server>.ASGNMENT.<Appl>

Access: UPDATE


CLOSE Controls who can close an Assignment<Server>.ASGNMENT.<Appl>

Access: UPDATE


JOIN Controls who can join users other than themselves to an Assignment

<Server>.ASGNMENT.<Appl>

Access: UPDATE


Table A-4. ASGNMENT (Continued)


Table A-5. RELEASE


ADD Controls who can add a Release<Server>.RELEASE.<Appl>

Access: ALTER


MODIFY Controls who can modify a Release<Server>.RELEASE.<Appl>

Access: UPDATE


CLOSE Controls who can close a Release<Server>.RELEASE.<Appl>

Access: UPDATE


JOIN Controls who can join users other than themselves to an Release

<Server>.RELEASE.<Appl>

Access: UPDATE


Table A-6. SET


ADD Controls who can create a Set<Server>.SET.<Appl>.<Level>

Access: ALTER

Appl StreamLevel OwnerPopt Agrname

TASKADD Controls who can add Tasks to a Set<Server>.SET.<Appl>.<Level>

Access: UPDATE


LOCK Controls who can Lock a Set<Server>.SET.<Appl>.<Level>

Access: UPDATE


UNLOCK Controls who can Unlock a Set<Server>.SET.<Appl>.<Level>

Access: UPDATE


MODIFY Controls who can modify Set details<Server>.SET.<Appl>.<Level>

Access: UPDATE



CHGTYPE

The CHGTYPE object protects the assigning of specific Change Types with a Set. This is required because a Set’s Change Type is part of the Approval Rules and can determine what Approvals are required.

TASK

The TASK object protects popts against Tasks.

CLOSE Controls who can close a Set<Server>.SET.<Appl>.<Level>

Access: UPDATE


JOIN Controls who can join users other than themselves to a Set

<Server>.SET.<Appl>

Access: UPDATE


APRVLIST Controls who can list the Approvers for a Set<Server>.SET.<Appl>.<Level>

Access: READ


STOP Controls who can issue the STOP command against a Set

<Server>.SET.<Appl>.<Level>

Access: UPDATE


RESTART Controls who can issue the RESTART command against a Set


Access: UPDATE


TERMINAT Controls who can issue the TERMINATE command against a Set


Access: UPDATE


Table A-6. SET (Continued)


Table A-7. CHGTYPE


ASSIGN Controls the use of Change Types with Set creation

<Server>.CHGTYPE.<Chgtype>

Access: READChgtype

Table A-8. TASK


ADD Secures the addition of Tasks to ISPW

<Server>.TASK.<Appl>.<Level>.<Memtype>.<Memname>

Access: ALTER

Appl StreamLevel SlevelMemenv MemtypeMemname Agrname

INSERT

Secures the Insertion of Tasks by the External Call Interface (ECI)


Access: ALTER


SETPROC Secures popts against Tasks

<Server>.TASK.<Appl>.<Level>.<Memtype>.<Memname>.<Popt>

Access: READ

Appl StreamLevel SlevelMemenv MemtypeMemname PoptTlevel Agrname

Security A-5

AG

The AG object protects Approver Groups. When a Set is locked the Approval Rules determine which Approver Groups are required for approval. This object protects who can approve or deny these groups.

REFDATA

The REFDATA object protects ISPW Reference Data. The Reference Data form the basis for how ISPW will work and should be tightly secured.

GENSUB

The GENSUB object protects the submission of the Generate. Controlled generates can be submitted either as part of Set Processing or not. This security check protects who can

LIST Secures the Task List<Server>.TASK.<Appl>.<Level>.<Memtype>.<Memname>

Access: READ


RVERUPD

Secures the UV Operation which updates the “Can Replace” version number


Access: ALTER


Table A-8. TASK (Continued)


Table A-9. AG


APPROVEControls who can signal approval for a specific Approver Group Name

<Server>.AG.<Apprname>.<Appr code>

Access: READ

Note: The value of Apprcode is “A” for Approve

ApprnameApprcode

DENYControls who can signal denial for a specific Approver Group Name

<Server>.AG.<Apprname>.<Appr code>

Access: READ

Note: The value of Apprcode is “D” for Approve

ApprnameApprcode

Table A-10. REFDATA


TECH Secures the “non- application” reference data (e.g. M.ER).

<Server>.REFDATA

Access: UPDATE

APP Secures the application specific data (e.g. M.AD)<Server>.REFDATA.<Appl>

Access: UPDATE

ApplStream


submit the generate jobs not done in a Set (there are other rules around creating and executing sets).

DPLYREF

The DPLYREF Object protects the ISPW-Deploy Reference data.

DPLYREQ

The DPLYREQ Object protects the ISPW-Deploy Deployment Requests.

Table A-11. GENSUB


START Secures whether the user can submit “demanded” generate jobs

<Server>.GENSUB

Access: READ

Table A-12. DPLYREF


SYSTEM Controls who can maintain Deployment Systems

<Server>.SYSTEM.<Systnam>.<Sy sttyp>

Access: UPDATE

SystnamSysttyp

CATEGORY Controls who can maintain Deployment Categories

<Server>.CATEGORY.<Dpcat>

Access: UPDATEDpcat

DOMAIN Controls who can maintain Deployment Domains

<Server>.DOMAIN.<Dpdmn>

Access: UPDATEDpdmn

TYPE Controls who can maintain Deployment Types

<Server>.TYPE.<Dptype>.<Dpcat>

Access: UPDATE

DptypeDpcat

ENV Controls who can maintain Deployment Environments

<Server>.ENV.<Dpenv>.<Owner>

Access: UPDATE

DpenvOwner

Table A-13. DPLYREQ


RESTART Controls who can restart a Deployment Request<Server>.DPLYREQ.<Dpenv>

Access: UPDATEDpenv

CANCEL Controls who can cancel a Deployment Request<Server>.DPLYREQ.<Dpenv>

Access: UPDATEDpenv

TERMINAT Controls who can terminate a Deployment Request

<Server>.DPLYREQ.<Dpenv>

Access: UPDATEDpenv

PKGFAIL Controls who can fail a Package within a Deployment Request


Access: UPDATEDpenv

PKGUPD Controls who can modify Package dates and times within a Deployment Request


Access: UPDATEDpenv

Security A-7

Examples

Example 1 – No Security

Example Input Cards for No Security

The following input cards will cause ISPW to do no security checking:

SECCLASS=$ISPW SECPREFIX=SECRULE=’* * DUMMY ALTER’

The security rule as specified indicates that an authority of ALTER against a Resource Name of DUMMY is required for all Objects and Methods. This in effect turns off security.

Figure A-1. WZACDUMP Report Output

WZZACDMP ACCESS CONTROL RESOURCE STRINGS FROM MODULEWZACSPWAS UPDATED:SECCLASS=$ISPW SECPREFIX=SECRULE=* * DUMMY ALTERM SERVER LOGON ALTER DUMMYM SERVER ADMIN ALTER DUMMYM SERVER START ALTER DUMMYM SERVER STOP ALTER DUMMYM SERVER REFRESH ALTER DUMMYM SERVER TRACEON ALTER DUMMYM SERVER TRACEOF ALTER DUMMYM SERVER TRACESW ALTER DUMMYM ASGNMENT ADD ALTER DUMMYM ASGNMENT MODIFY ALTER DUMMYM ASGNMENT CLOSE ALTER DUMMYM ASGNMENT JOIN ALTER DUMMYM RELEASE ADD ALTER DUMMYM RELEASE MODIFY ALTER DUMMYM RELEASE CLOSE ALTER DUMMYM RELEASE JOIN ALTER DUMMYM SET ADD ALTER DUMMYM SET TASKADD ALTER DUMMYM SET LOCK ALTER DUMMYM SET UNLOCK ALTER DUMMYM SET MODIFY ALTER DUMMYM SET CLOSE ALTER DUMMYM SET JOIN ALTER DUMMYM SET APRVLIST ALTER DUMMYM SET STOP ALTER DUMMYM SET START ALTER DUMMYM SET TERMINAT ALTER DUMMYM CHGTYPE ASSIGN ALTER DUMMYM TASK ADD ALTER DUMMYM TASK INSERT ALTER DUMMYM TASK SETPROC ALTER DUMMYM AG APPROVE ALTER DUMMYM AG DENY ALTER DUMMYM REFDATA TECH ALTER DUMMYM REFDATA APP ALTER DUMMY


Example 2 – Security

The following example input cards will cause ISPW to do security checking and replaces the default security. This example is a good basis for a site’s security setup.

Figure A-2. Example Input Cards with Security

SECRULE=’* * DUMMY ALTER’SECRULE=’SERVER * SPW.SR ALTER’SECRULE=’SERVER LOGON SPW.SR READ’ SECRULE=’ASGNMENT * SPW.AS.APPL UPDATE’ SECRULE=’ASGNMENT ADD SPW.AS.APPL ALTER’ SECRULE=’RELEASE * SPW.RL.APPL UPDATE’ SECRULE=’RELEASE ADD SPW.RL.APPL ALTER’ SECRULE=’SET * SPW.ST.APPL.LEVEL UPDATE’ SECRULE=’SET ADD SPW.ST.APPL.LEVEL ALTER’ SECRULE=’TASK * SPW.TS.APPL.LEVEL.SLEVEL.POPT UPDATE’ SECRULE=’TASK ADD SPW.TS.APPL.LEVEL.SLEVEL.ADD ALTER’ SECRULE=’AG * SPW.AG.APPRNAME READ’ SECRULE=’REFDATA TECH SPW.RD UPDATE’ SECRULE=’REFDATA APP SPW.RD.APPL UPDATE’

Security A-9

Figure A-3. WZACDUMP Report Output

Variable Substitution

Variable substitution for the values in the “angle brackets” above is performed when the security check is to be made.

WZZACDMP ACCESS CONTROL RESOURCE STRINGS FROM MODULE WZACSPWAS UPDATED:SECPREFIX=SECRULE=* * DUMMY ALTERSECRULE=SERVER * SPW.SR ALTERSECRULE=SERVER LOGON SPW.SR READ SECRULE=ASGNMENT * SPW.AS.APPL UPDATE SECRULE=ASGNMENT ADD SPW.AS.APPL ALTER SECRULE=RELEASE * SPW.RL.APPL UPDATE SECRULE=RELEASE ADD SPW.RL.APPL ALTER SECRULE=SET * SPW.ST.APPL.LEVEL UPDATE SECRULE=SET ADD SPW.ST.APPL.LEVEL ALTER SECRULE=SET ADD SPW.ST.APPL.LEVEL ALTER SECRULE=TASK * SPW.TS.APPL.LEVEL.SLEVEL.POPT UPDATE SECRULE=TASK ADD SPW.TS.APPL.LEVEL.SLEVEL.ADD ALTER SECRULE=AG * SPW.AG.APPRNAME READ SECRULE=REFDATA TECH SPW.RD UPDATE SECRULE=REFDATA APP SPW.RD.APPL UPDATEM SERVER LOGON READ SPW.SRM SERVER ADMIN ALTER SPW.SR M SERVER START ALTER SPW.SR M SERVER STOP ALTER SPW.SR M SERVER REFRESH ALTER SPW.SR M SERVER TRACEON ALTER SPW.SR M SERVER TRACEOF ALTER SPW.SR M SERVER TRACESW ALTER SPW.SRM ASGNMENT ADD ALTER SPW.AS.<AP> M ASGNMENT MODIFY UPDATE SPW.AS.<AP> M ASGNMENT CLOSE UPDATE SPW.AS.<AP> M ASGNMENT JOIN UPDATE SPW.AS.<AP> M RELEASE ADD ALTER SPW.RL.<AP> M RELEASE MODIFY UPDATE SPW.RL.<AP> M RELEASE CLOSE UPDATE SPW.RL.<AP>M RELEASE JOIN UPDATE SPW.RL.<AP>M SET ADD ALTER SPW.ST.<AP>.<LV> M SET TASKADD UPDATE SPW.ST.<AP>.<LV> M SET LOCK UPDATE SPW.ST.<AP>.<LV> M SET UNLOCK UPDATE SPW.ST.<AP>.<LV>M SET MODIFY UPDATE SPW.ST.<AP>.<LV> M SET CLOSE UPDATE SPW.ST.<AP>.<LV> M SET JOIN UPDATE SPW.ST.<AP>.<LV> M SET APRVLIST UPDATE SPW.ST.<AP>.<LV> M SET STOP UPDATE SPW.ST.<AP>.<LV> M SET START UPDATE SPW.ST.<AP>.<LV> M SET TERMINAT UPDATE SPW.ST.<AP>.<LV> M CHGTYPE ASSIGN ALTER DUMMYM TASK ADD ALTER SPW.TS.<AP>.<LV>.<SL>.ADD M TASK INSERT UPDATE SPW.TS.<AP>.<LV>.<SL>.<PO> M TASK SETPROC UPDATE SPW.TS.<AP>.<LV>.<SL>.<PO> M AG APPROVE READ SPW.AG.<APPRNAME>M AG DENY READ SPW.AG.<APPRNAME> M REFDATA TECH UPDATE SPW.RDM REFDATA APP UPDATE SPW.RD.<AP>


B-1

Appendix A.Appendix B.

BReference Data App B

ISPW Reference Data is cached both in the ISPW CM task and also in the TSO client. This is done for performance reasons. ISPW exits run in a TSO/ISPF address space (either the User Interface or Set Processor) and these have a requirement to access the Reference Data. The calls to access this Reference Data are documented in this Appendix.

REXX Call format

The Reference Data is accessed by a REXX call of the following type:

WZZTSI("#refdataclass,"GET")

Where refdataclass is the acronym for the ISPW Reference Data Entity for which the data is being retrieved.

A non-zero return code is an error.

#refdataclass

The following table lists the #refdataclass relationship to the various Reference Data Entities and also indicates whether or not Extension Data is valid for that Class.

Table B-1. #refdataclass

Class Entity Ext Data

#CMPNTYP M.CT – Component Type Y

#BCTYPE M.BC – Base Category N

#CMPNCAT M.CC – Component Category N

#EXTREF M.ER – External References N

#EXIT M.EX – Exits N

#APPL M.AP – Applications N

#APPSTRM M.AD – Application Definition N

#STRM M.ST – Streams N

#STRMLVL M.ST(L) – Stream Level Y

#STRMCT M.ST(T) – Stream Type Y

#STRMCTA M.ST(A) – Stream Associations N

#STRMCTL M.ST(N) – Stream Names Y

#APPLLVL M.AD(L) – Application Level Y

#APPLCT M.AD(T) – Application Types Y

#APPLCTL M.AD(N) – Application Names Y

#APPLCTA M.AD(A) – Application Associations N

#PLANIMP M.AD(P) – Application Plan Implementation N

B-2 ISPW Technical Reference Guide

REXX Call Detail

When making a call to retrieve Reference Data, key values for the Entity must be set in ISPF variables prior to the call. The following table describes the ISPF variables for each Class. Variables marked as “KEY” are required to be set before the call is made.

Table B-2. REXX Call Detail

Class Variables

#CMPNTYP

MEMBTYPE,LENGTH=4,TYPE=KEY MEMBDESC,LENGTH=50 TECHNOL,LENGTH=4 LIBRLANG,LENGTH=4 OTABLE,LENGTH=8 XREFTYPE,LENGTH=4 CYCLFLAG,LENGTH=1 CMPLFLAG,LENGTH=1 EXECENV,LENGTH=4 MOPFLAG,LENGTH=1 PMOVJOB,LENGTH=8 MODEL,LENGTH=54 FILEEXT,LENGTH=32 CASESENS,LENGTH=1 SHNAMLEN,FORMAT=SMALLINT EXITTYPE,LENGTH=4 CMPSKEL,LENGTH=8 CMPJOB,LENGTH=12 CMPTAB,LENGTH=8 PANLT,LENGTH=8 PANLH,LENGTH=8 ISPWTYPE,LENGTH=4

#BCTYPE BCTYPE,LENGTH=4,TYPE=KEY CMPNCAT,LENGTH=4 CRLANG,LENGTH=4 CRSCANR,LENGTH=8 USEXITNM,LENGTH=8 BCTDESC,LENGTH=60

#CMPNCAT CMPNCAT,LENGTH=4,TYPE=KEY CCATDESC,LENGTH=60

#EXTREF FILETYPE,LENGTH=8,TYPE=KEY WLOGON,LENGTH=6,TYPE=KEY FILEDESC,LENGTH=55 EXTLFILE,LENGTH=55

#EXIT

POPT,LENGTH=2,TYPE=KEY EXITKEY,LENGTH=4,TYPE=KEY EXITDESC,LENGTH=50 EXITUPDT,LENGTH=1 EXITPRE,LENGTH=215 EXITPOST,LENGTH=215 EXITPROD,LENGTH=1 EXITHOLD,LENGTH=1 EXITTEST,LENGTH=1 EXITOUTS,LENGTH=1

#APPL WLLAPPL,LENGTH=4,TYPE=KEY WLLMODEL,LENGTH=1 WLLOWNER,LENGTH=8 WLLDESC,LENGTH=50

#APPSTRMWAMAPPL,LENGTH=4,TYPE=KEY WAMSTRM,LENGTH=8,TYPE=KEY WAMOWNER,LENGTH=8 WAMDESC,LENGTH=50 WAMDDMN,LENGTH=4 WAMCRUSE,LENGTH=1

#STRM WMSSTRM,LENGTH=8,TYPE=KEY WMSOWNER,LENGTH=8 WMSDESC,LENGTH=50 WMSCRUSE,LENGTH=1

#STRMLVL

WMLSTRM,LENGTH=8,TYPE=KEY WMLLVL,LENGTH=4,TYPE=KEY WMLNLVL,LENGTH=4 WMLIRULE,LENGTH=8 WMLDB2,LENGTH=4 WMLPBDLB,LENGTH=123 WMLPXNM,LENGTH=8 WMLPXLB,LENGTH=1 WMLSETCL,LENGTH=1 WMLSETJB,LENGTH=8 WMLSETQU,LENGTH=8 WMLSETFN,LENGTH=30 WMLSWHID,LENGTH=8 WMLSPOLY,LENGTH=16 WMLGWHID,LENGTH=8 WMLGPOLY,LENGTH=16 WMLPRMAN,LENGTH=1 WMLCTL1,LENGTH=1 WMLCTL2,LENGTH=1 WMLCTL3,LENGTH=1

#STRMCT

WMTSTRM,LENGTH=8,TYPE=KEY

WMTMTYPE,LENGTH=4,TYPE=KEY WMTMCLAS,LENGTH=4,TYPE=KEY MEMBDESC,LENGTH=50 ACMPSKEL,LENGTH=8 ACMPJOB,LENGTH=12 ACMPTAB,LENGTH=8 APANLT,LENGTH=8 APANLH,LENGTH=8 APMOVJOB,LENGTH=8 HOLDTIME,LENGTH=8 PLIBOWNR,LENGTH=4 PLIBSTD,LENGTH=4 AMODEL,LENGTH=54 XOPFLAG,LENGTH=1 BKUPTYPE,LENGTH=4 BKUPLIB1,LENGTH=44 BKUPLIB2,LENGTH=44 SCLMCNTL,LENGTH=8 WMTATYPE,LENGTH=4 WMTALIB,LENGTH=54 CDMNNAME,LENGTH=8 DPTYPE,LENGTH=8 FULPOPWH,LENGTH=1

#STRMCTA

WMASTRM,LENGTH=8,TYPE=KEY WMAMTYPE,LENGTH=4,TYPE=KEY WMAMCLAS,LENGTH=4,TYPE=KEY WMAASSN,LENGTH=1,TYPE=KEY WMATENV,LENGTH=4,TYPE=KEY WMASET,LENGTH=4,TYPE=KEY WMASEQ,LENGTH=1,TYPE=KEY WMAAAPPL,LENGTH=4 WMAAMTYP,LENGTH=4 WMAAMCLA,LENGTH=4

Reference Data B-3

The following REXX code is an example of a call to retrieve M.AD(L) data:

Figure B-1. Example Call

]\

#STRMCTL

WMBSTRM,LENGTH=8,TYPE=KEY WMBMTYPE,LENGTH=4,TYPE=KEY WMBMCLAS,LENGTH=4,TYPE=KEY WMBLVL,LENGTH=4,TYPE=KEY WMBTYPE,LENGTH=4 WMBNAME,LENGTH=44 WMBPACK,LENGTH=1 WMBRTN,LENGTH=1 WMBCKGEN,LENGTH=1 WMBPRM,LENGTH=1 WMBGEN,LENGTH=1 WMBVCTL,LENGTH=1 WMBBMAP,LENGTH=1 WMBCTL1,LENGTH=1 WMBCTL2,LENGTH=1

#APPLLVL

WLLAPPL,LENGTH=4,TYPE=KEY WLLSTRM,LENGTH=8,TYPE=KEY WLLLVL,LENGTH=4,TYPE=KEY WLLNLVL,LENGTH=4 WLLIRULE,LENGTH=8 WLLDB2,LENGTH=4 WLLPBDLB,LENGTH=123 WLLPXNM,LENGTH=8 WLLPXLB,LENGTH=1 WLLSETCL,LENGTH=1 WLLSETJB,LENGTH=8 WLLSETQU,LENGTH=8 WLLSETFN,LENGTH=30 WLLSWHID,LENGTH=8 WLLSPOLY,LENGTH=16 WLLGWHID,LENGTH=8 WLLGPOLY,LENGTH=16 WLLPRMAN,LENGTH=1 WLLCTL1,LENGTH=1 WLLCTL2,LENGTH=1 WLLCTL3,LENGTH=1

#APPLCT

WLTAPPL,LENGTH=4,TYPE=KEY WLTSTRM,LENGTH=8,TYPE=KEY WLTMTYPE,LENGTH=4,TYPE=KEY WLTMCLAS,LENGTH=4,TYPE=KEY MEMBDESC,LENGTH=50 ACMPSKEL,LENGTH=8 ACMPJOB,LENGTH=12 ACMPTAB,LENGTH=8 APANLT,LENGTH=8 APANLH,LENGTH=8 APMOVJOB,LENGTH=8 HOLDTIME,LENGTH=8 PLIBOWNR,LENGTH=4 PLIBSTD,LENGTH=4 AMODEL,LENGTH=54 XOPFLAG,LENGTH=1 BKUPTYPE,LENGTH=4 BKUPLIB1,LENGTH=44 BKUPLIB2,LENGTH=44 SCLMCNTL,LENGTH=8 WLTATYPE,LENGTH=4 WLTALIB,LENGTH=54 CDMNNAME,LENGTH=8

#APPLCTL

WLBAPPL,LENGTH=4,TYPE=KEY WLBSTRM,LENGTH=8,TYPE=KEY WLBMTYPE,LENGTH=4,TYPE=KEY WLBMCLAS,LENGTH=4,TYPE=KEY WLBLVL,LENGTH=4,TYPE=KEY WLBTYPE,LENGTH=4 WLBNAME,LENGTH=44 WLBPACK,LENGTH=1 WLBRTN,LENGTH=1 WLBCKGEN,LENGTH=1 WLBPRM,LENGTH=1 WLBGEN,LENGTH=1 WLBVCTL,LENGTH=1 WLBBMAP,LENGTH=1 WLBCTL1,LENGTH=1 WLBCTL2,LENGTH=1

#APPLCTA

WLAAPPL,LENGTH=4,TYPE=KEY WLASTRM,LENGTH=8,TYPE=KEY WLAMTYPE,LENGTH=4,TYPE=KEY WLAMCLAS,LENGTH=4,TYPE=KEY WLAASSN,LENGTH=1,TYPE=KEY WLATENV,LENGTH=4,TYPE=KEY WLASET,LENGTH=4,TYPE=KEY WLASEQ,LENGTH=1,TYPE=KEY WLAAAPPL,LENGTH=4 WLAAMTYP,LENGTH=4 WLAAMCLA,LENGTH=4

#PLANIMP

WPIAPPL,LENGTH=4,TYPE=KEY WPISTRM,LENGTH=8,TYPE=KEY WPILVL,LENGTH=4,TYPE=KEY WPIIMPL,LENGTH=4 WPIOWNR,LENGTH=8 WPIQUAL,LENGTH=8 WPISSID,LENGTH=4 WPIXPLN,LENGTH=1 WPIPKGC,LENGTH=18 WPIPKGO,LENGTH=123 WPIBIND,LENGTH=1 WPIPFX,LENGTH=4 WPIPLNO,LENGTH=123 WPISFX,LENGTH=4 WPIPKNML,LENGTH=47 WPIPKNMP,LENGTH=47

Table B-2. REXX Call Detail

/* REXX */ WLLSTRM="SITE" WLLAPPL="SITE" WLLLVL ="TEST"rc = WZZTSI("#APPLLVL","GET ")

B-4 ISPW Technical Reference Guide

C-1

Appendix A.Appendix C.

CGenerate Process for Previous Versions App C

Prior to version 4.3, ISPW stored generate variables in ISPF dialog tables.

Each application defined to ISPW had its own separate table which contained one entry per compilable component. The remainder of this section contains a description of the generate process that was in effect in previous versions

Generate Processing Overview for versions 4.2 and Older

The Generate System is an integral part of ISPW. This section gives an overview and describes the components involved.

Where are Generates Performed?In ISPW, generates are generally only performed in the TEST and HOLD environments. The PROD environment is updated by copying the source and generated components from the HOLD environment to the PROD environment.

The last generate at a HOLD level can be considered to be the “production” generate. The PROD environment then contains what was tested and signed off in the HOLD environment.

TEST versus HOLD generates

ISPW differentiates between generates performed in the TEST environment to generates performed in the HOLD environment. It is possible to have different generate panels and processing. The TEST level generates are normally performed under the requestor’s UserID, and HOLD generates are performed under some controlled ID.

Generate processing can be the same or different for both environments and is usually controlled by the code in the Generate Skeletons using MEMBENV=‘TEST’ or MEMBENV=‘HOLD’.

Automatic Generate after Promote

The Promote operation can automatically request a Generate for any “generate” component types depending on the options set in the Reference Data (option AD, Flags). If the Generate Indicator is set to R (Required), a Generate will automatically be performed for that component at that level. If the Generate Indicator is set to O (Optional), an online generate may be performed from the ISPW Task list (a generate will not automatically be done in a Set in this case).

Prevent Promote after Failed Generate

A subsequent promote operation can be prevented if the generate for a component has failed. It depends on the options set in the Reference Data (option AD, Flags). If the Check Generate Flag is set to Y (Yes), any attempt to perform a promote on a component where the

C-2 ISPW Technical Reference Guide

last generate has failed, will be rejected. If the Check Generate Flag is set to N (No) or blank, the promote will be allowed.

Pre-exit and Post-exit processing

As with other ISPW task line commands, the site can specify special processing to occur. This can be before the standard ‘G’ processing as a Pre- exit or after the standard processing as a Post-exit.

Exit Processing Phases

The standard ‘G’ processing calls routine WZZPSG# with the following events occurring:

• If a pre-exit is defined for the technology or component type, it is invoked.

• If no pre-exit was defined or the return code from the pre-exit is 0, then routine WZXGEN is invoked.

• If a post-exit is defined and the return code from WZXGEN is 0 or 2, then it is invoked.

WZXGEN processing

WZXGEN is the main processing routine for all generates and controls the display of the generate panel, update of the Permanent Generate Parameters Table and file tailoring and submission of any generate JCL. The basic functions it performs include the following:

• Open and read the Permanent Generate Parameters Table to retrieve the stored parameters. This table exists for each APPL code and is stored in the ‘O Tables’ dataset with the name <appl>CMPL. If a row is not found for the component, it will be added automatically.

• Display the appropriate generate panel (TEST or HOLD) as specified in M.CT/M.AD to allow the user to modify generate parameters/variables.

• If it is a TEST generate and the user has changed a parameter value, update the Permanent Generate Parameters Table if indicated by UPDTFLAG=’Y’. Setting of this flag is usually controlled in the TEST panel. Parameters are not normally updated in HOLD, although the jobcard and other information may be input.

• Other processing is performed to validate and set variables used in generate processing and in the file tailoring of the skeletons.

• A row for the component is added to the Generate Information Table. This table contains all of the variables that will be available for the Generate User Exit and for the demanded batch job.

• The Generate User Exit, WZXGEN1U is called. It is provided for site- specific use to perform any additional processing needed. The row on the work table ($WZXGENT) is retrieved so that all the information for the component is available in WZXGEN1U. The site code is executed and the work table row is updated. If the return code from the Generate User Exit is 0 then the processing continues. If not, the processing is terminated.

• If the generate job is file tailored and submitted in foreground from the user’s TSO session (usually the case in a TEST generate), then the following steps are executed:

– The Generate Skeleton is file tailored.

– The resulting job is submitted using the SUBMIT command.

• If a generate is a “demanded generate”, ISPW will submit a job under the Set Processor UserID. This batch job will in turn build and submit any required generate jobs. The following steps are executed:

– A row is added to the Generate Table specified in M.CT/M.AD. This Generate Table is necessary because for a demanded background generate, the actual generate job is file tailored and submitted by another batch job. The submitting batch job does

Generate Process for Previous Versions C-3

not have access to the ISPF variable pools normally available to a TSO session, so ISPW puts the variables needed to execute the generate into a row on the specified table which is input to the job that is demanded. The demanded job executes a TSO Batch session which invokes routine WZXGENR to process the Generate Table, set generate variables and file tailor and submit the job. If the table does not exist, it will be created in WZXGEN processing.

– WZXGENR performs the following steps:

• Read Generate Table specified and do the processing required to set variable values. This in essence “recreates” the online environment in the batch job.

• The rest of the processing is similar to the “file tailor and submit” processing as described above.

• The row in the Generate Table is deleted.

Generate TablesThis section describes the types of generate tables.

Generate Tables

There are 2 types of tables used during generate processing:

• Permanent Generate Parameters Tables, and

• Hold Generate Parameters Table

Permanent Generate Parameters Tables

These tables are used to store generate parameters for a component. There is one table for each application and they are stored in the ‘O tables’ dataset with the name:

<appl>CMPL

where: <appl> is the ApplicationID. If this table does not exist, it will be created in WZXGEN processing.

The parameters are permanent because they retain their values between generates unless the user changes them (which is allowed on the TEST level generate panels). Not all parameters are necessarily required in setting up the generate processing for an organization

The base fields are described below:

Table C-1. Base Fields

Field Description

MEMBTYPE Component Type.

MEMBER Component Name.

LOADNAME Load module name.

USERID The UserID of the last person modifying the component.

LASTOPDT Date of the last operation performed on this component.

LLVL Flag to indicate “language level”. Can be (COMMAND/MACRO) to indicate type of CICS pre- compiler.


COMPILER

Indicator for compiler.

Example:

WZZCOPYFlag to indicate if the TEST level copy or include libraries are to be concatenated in the compiler SYSLIB DD. If ‘N’, then only HOLD and PROD level libraries are concatenated.

WZZLINKFlag to indicate if the TEST level Load libraries are to be concatenated in the Linkage Editor SYSLIB DD. If ‘N’, then only HOLD and PROD level libraries are concatenated.







WZGPROG Flag to indicate whether load module is executable ‘Y’ (program) or non-executable ‘N’ (subroutine).

WZGSQL Flag to indicate SQL statements (pre-processor step may be required).

WZGBIND Flag to indicate that the DB2 bind process should be invoked.

WZGPKG Flag to indicate a DB2 package exists for the module.

WZGPLNB Flag to indicate that PLANs using DBRM directly of program module being generated should be bound (DBRM updated) in program generate.

WZGDB2 DB2 subsystem ID in PROD for a plan/package. This value can be used to override the value specified in M.AD for the application for the PROD bind.

WZGPKG

parameters

‘ ’ suffix defines a specific package bind parameter as documented in routine WZZMZ##.


Field Description

Generate Process for Previous Versions C-5

Where these values are set

In standard ISPW processing, all of the values in the Permanent Generate Parameters Table are set in the TEST level generate panel. The sample generate panel includes references to these variables and this should be kept in mind when customizing it.

HOLD Generate Parameters table

This table is non-persistent in that it is only used to pass generate parameters from the ISPW Client (e.g. User’s address space) to the batch Generate job as defined in M.CT/M.AD (Both the table name and batch job are defined here). This is required so that the job which eventually does the generate is not running under the authority of the user, but under the controlled ID of the Set Processor. The Batch Generate Job deletes the entries off this table after it submits the generate.

The model table is $WZXGENT which is defined in routine WZXGENT.

CPARM1 to CPARM5

Compiler parameters. Normally, CPARM1 contains the parameters for the compile step; with other fields containing parameters for pre-processors or other generate steps. The definition and standard for these variables is left the site administrator.

LPARM1 to LPARM5Linkage Editor parameters. Normally, LPARM1 contains the parameters for the Link Edit step, and the others are used for parameters to any other steps. The definition and standard for these variables is left to the site administrator.

SPARM1 to SPARM3Special parameters. These can be used for any parameters that are not applicable to the CPARMn and LPARMn variables. The definition and standard for these variables is left to the site administrator.


Field Description


Documents

ISPW Technical Reference Guide