You are on page 1of 340

Version 4 of ISPF and SCLM

An Implementation Guide

Document Number GG24-4407-00


September 1994

International Technical Support Organization


Poughkeepsie Center

Take Note!
Before using this information and the product it supports, be sure to read the general information under
Special Notices on page xxi.

First Edition (September 1994)


This edition applies to Version 4 Release 1 of the licensed program Interactive System Productivity Facility (ISPF)
(5655-042) for MVS.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications
are not stocked at the address given below.
An ITSO Technical Bulletin Evaluation Form for reader's feedback appears facing Chapter 1. If the form has been
removed, comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. H52 Mail Station P099
522 South Road
Poughkeepsie, New York 12601-5400
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 1994. All rights reserved.

Note to U.S. Government Users Documentation related to restricted rights Use, duplication or disclosure is
subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Abstract
This document is unique in its detailed coverage of the new facilities available
with Version 4 Release 1 of ISPF. Part 1 is a short introduction. Part 2 is
devoted to the basics of ISPF. Besides a general description of these facilities, it
provides guidance in implementing the various elements of user interfaces in
different user environments and gives scenarios for installing and starting the
Graphical User Interface (GUI) using APPC or TCP/IP with OS2 and CM/2.
Part 3 is entirely devoted to SCLM in Version 4 Release 1 and offers an in-depth
coverage of the implementation details whereas the use of SCLM in relation to
programming activities and disciplines is not considered relevant within the
framework of this document and is, therefore, not discussed.
A diskette with examples and a set of transparencies for an SCLM workshop is
found in the back of the book.
The document is written for the experienced system programmer, but also less
experienced users may get inspiration to use ISPF Version 4 Release 1 in a
productive manner. Some knowledge of ISPF Version 3 Release 5 is, however,
assumed.
(312 pages)

Copyright IBM Corp. 1994

iii

iv

ISPF/SCLM V4 Guide

Contents
Abstract

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Special Notices

Part 1. Introduction

. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .

xxiii
xxiii
xxv
xxv
xxvi

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Part 2. ISPF Version 4 Basics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1. Technical Overview . . . . . . . . . . . . . .


1.1 New Functions in ISPF Version 4 Release 1 . . . .
1.2 Usability Enhancements . . . . . . . . . . . . . . . .
1.2.1 ISPF Settings . . . . . . . . . . . . . . . . . . . .
1.2.1.1 Settings panel Action bars . . . . . . . . .
1.2.1.2 Jump from Leader Dots . . . . . . . . . . .
1.2.1.3 Edit PRINTDS Command . . . . . . . . . .
1.2.1.4 Action Bar Pull-downs . . . . . . . . . . . .
1.2.1.5 Point & Shoot Fields . . . . . . . . . . . . .
1.2.1.6 Long Message in Pop-Up . . . . . . . . . .
1.2.2 Member Selection List . . . . . . . . . . . . . .
1.2.3 Reflists
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1.2.4 The View Facility
1.2.4.1 Using the Create and Replace Commands
1.2.5 Color Usage . . . . . . . . . . . . . . . . . . . .
1.2.5.1 Edit Hilite
. . . . . . . . . . . . . . . . . . .
1.2.5.2 Language Sensitive Editing
. . . . . . . .
1.2.6 ISPF Command Shell . . . . . . . . . . . . . . .
1.2.7 VSAM Utilities . . . . . . . . . . . . . . . . . . .
1.2.7.1 Building a VSAM Profile Data Set . . . . .
1.2.7.2 Using a VSAM Profile Data Set . . . . . .
1.2.7.3 Changing the VSAM Profile Data Set . . .
1.2.8 Data Set List Utility . . . . . . . . . . . . . . . .
1.2.8.1 Usage of Option 3.4 Data Set List . . . . .
1.2.8.2 Examples of Dsname Levels . . . . . . . .
. . . . . . . . .
1.2.9 Multivolume Data Set Support
. . . . .
1.2.9.1 Usage of Multivolume Data Sets
. . . . . . . . . . . . . . . .
1.2.9.2 Hints and Tips
1.2.10 Display Message ID . . . . . . . . . . . . . . .
1.2.10.1 Usage . . . . . . . . . . . . . . . . . . . . .
1.2.11 Forward Retrieve and Retrieve Pop-up
. . .
1.2.11.1 RETF - Forward Retrieve
. . . . . . . . .
1.2.11.2 RETP - Retrieve Pop-Up . . . . . . . . . .
1.3 LIBDEF Enhancements . . . . . . . . . . . . . . . . .
1.3.1 LIBDEF Stack Facility . . . . . . . . . . . . . . .
1.3.1.1 Command Procedure Format
. . . . . . .
Copyright IBM Corp. 1994

xxi

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Preface
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . .
How This Document is Organized
Related Publications
. . . . . . . . . . . . . . . . . . . . . .
International Technical Support Organization Publications
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . .

iii

. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .

1
3
5
5
5
5
6
7
7
8
9
9
10
10
13
14
15
15
15
19
20
22
23
24
24
24
25
27
28
28
29
30
30
30
31
32
33
33

1.3.1.2 Call Format . . . . . . . . . . . . . . . . . . . .


1.3.1.3 Usage
. . . . . . . . . . . . . . . . . . . . . . .
1.3.1.4 Examples . . . . . . . . . . . . . . . . . . . . .
1.3.2 Dialog Query LIBDEF Facility . . . . . . . . . . . .
1.3.2.1 Command Procedure Format
. . . . . . . . .
1.3.2.2 Call Format . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
1.3.2.3 Usage
1.3.2.4 Hints and Tips
. . . . . . . . . . . . . . . . . .
1.3.3 LIBDEF Display Utility . . . . . . . . . . . . . . . . .
1.3.3.1 Usage
. . . . . . . . . . . . . . . . . . . . . . .
1.3.4 LIBDEF Search Order for ISPLLIB . . . . . . . . .
1.4 Graphical User Interface (GUI) Applications with ISPF
Chapter 2. User Interface . . . . . . . . . . . . . . . . .
2.1 Action Bar . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 How are the Action Bars Constructed? . . . .
2.1.2 Customizing Action Bars . . . . . . . . . . . . .
2.1.2.1 Removing Action Bars
. . . . . . . . . . .
2.1.2.2 Changing Action Bars . . . . . . . . . . . .
2.2 Keylists . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Using Dialog under SETTINGS . . . . . . . . .
2.2.2 Using DTL
. . . . . . . . . . . . . . . . . . . . .
2.2.3 Global Function Keys Setting . . . . . . . . . .
2.2.4 Function Key Display . . . . . . . . . . . . . . .
2.2.4.1 Tailoring Function Key Definition Display
2.2.4.2 Display Function Keys in Different Forms
2.3 Referral Lists . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Creating a Personal Data Set List . . . . . . .
2.3.2 Shared List . . . . . . . . . . . . . . . . . . . . .
2.3.3 Fast Path to the Referral List Function
. . . .
2.3.4 Function Keys for Accessing Referral Lists . .
2.4 Point-and-Shoot Text Fields . . . . . . . . . . . . . .
2.4.1.1 Changing to Noninput Fields . . . . . . . .
2.4.1.2 Changing Colors of Point-and-Shoot Fields
2.5 Color Usage . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
2.5.1 Colors Pull-down
2.5.2 Edit Hilite . . . . . . . . . . . . . . . . . . . . . .
2.5.2.1 Enhanced Edit Coloring . . . . . . . . . . .
2.5.2.2 Language Processing Limitation
. . . . .
2.5.2.3 Turning off the Highlight Features . . . . .
. . . . . . .
2.5.2.4 The HILITE Command/Dialog
2.6 Status Area . . . . . . . . . . . . . . . . . . . . . . .
2.6.1 Session and Function Keys Status . . . . . . .
2.6.2 Calendar . . . . . . . . . . . . . . . . . . . . . .
2.6.3 User Status . . . . . . . . . . . . . . . . . . . . .
2.6.4 User Point-and-Shoot . . . . . . . . . . . . . . .
2.6.5 None . . . . . . . . . . . . . . . . . . . . . . . . .
2.7 Modifications to ISPF Objects
. . . . . . . . . . . .
Chapter 3. 3270 Environment . . .
3.1 IBM 3270 Hardware Terminals
3.1.1 Action Bar Considerations
3.1.1.1 Learn New Habits . .
3.1.1.2 Remove the Action Bar
3.1.1.3 Remove Ability to Tab

vi

ISPF/SCLM V4 Guide

. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .

. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .

33
33
34
35
35
35
36
36
36
37
37
37
39
39
39
41
42
45
48
49
55
58
59
59
60
61
63
65
66
67
69
69
70
71
71
72
72
74
74
74
75
76
77
80
81
83
83
85
85
86
87
87
87

3.1.1.4 Placing Command Line at the Top . . . .


3.1.1.5 Use F24=CRETRIEVE . . . . . . . . . . . .
3.1.1.6 Remove Action Bar from Edit and View .
. . . . . . . . . . . . . . . . . . .
3.1.2 Point & Shoot
3.1.3 PF Keys . . . . . . . . . . . . . . . . . . . . . . .
3.2 IBM 3270 OS/2 - CM/2 Emulated Terminals . . . .
3.2.1 CM Mouse with ISPF 4.1 . . . . . . . . . . . . .
3.2.1.1 Using CM Mouse . . . . . . . . . . . . . . .
3.3 CM Mouse BDF and MMM Files . . . . . . . . . . .
3.3.1.1 Button Definition File, ISPF41.BDF
. . . .
3.3.1.2 General Mouse Menu, ISPF41.MMM . . .
3.3.1.3 Edit and View Mouse Menu, ISPFE41.MMM
Chapter 4. Graphical User Interface (GUI) . . .
4.1.1 How to Use this Chapter . . . . . . . . .
4.1.1.1 Support Software Limitations
. . .
4.2 Getting Ready for GUI . . . . . . . . . . . . .
4.2.1 Some Terminology . . . . . . . . . . . .
4.2.2 Establishing Connectivity
. . . . . . . .
4.2.2.1 For the Experienced User . . . . . .
4.2.3 IBM TCP/IP for OS/2 . . . . . . . . . . .
4.2.4 APPC for IBM CM/2 . . . . . . . . . . . .
4.2.4.1 On the MVS Host Side
. . . . . . .
4.2.4.2 At Your Workstation . . . . . . . . .
4.2.5 IBM TCP/IP for DOS and Windows . . .
4.3 Downloading GUI to Your Workstation . . .
4.3.1 Using TCP/IP File Transfer Protocol . .
4.3.2 Alternative download Methods . . . . .
4.4 Starting the Workstation Server . . . . . . .
4.4.1 OS/2 Environment . . . . . . . . . . . . .
4.4.1.1 Building an Icon for OS/2 . . . . . .
4.4.2 DOS/Windows Environment . . . . . . .
4.5 Connecting the MVS Host in GUI
. . . . . .
4.5.1 From the Ready Prompt . . . . . . . . .
4.5.2 From within ISPF
. . . . . . . . . . . . .
4.5.3 Troubleshooting . . . . . . . . . . . . . .
4.5.3.1 General . . . . . . . . . . . . . . . .
4.5.3.2 TCP/IP . . . . . . . . . . . . . . . . .
4.5.3.3 APPC . . . . . . . . . . . . . . . . . .
4.6 Running GUI . . . . . . . . . . . . . . . . . . .
4.6.1 Interacting with GUI Panels . . . . . . .
4.6.1.1 Host Session Keys Versus PC keys
4.6.1.2 Getting Around . . . . . . . . . . . .
. . . . . . .
4.6.1.3 Residual 3270 Session
4.6.1.4 Split Screen . . . . . . . . . . . . . .
4.6.1.5 TSO Commands . . . . . . . . . . .
4.6.1.6 Workstation Commands . . . . . . .
4.6.1.7 Window Size . . . . . . . . . . . . .
4.6.1.8 GUI Colors
. . . . . . . . . . . . . .
4.7 Performance Issues . . . . . . . . . . . . . .
4.7.1 OS/2 Platform . . . . . . . . . . . . . . .
4.7.2 DOS/Windows Environment . . . . . . .
4.7.3 Network Performance
. . . . . . . . . .
4.8 ISPF GUI Applications . . . . . . . . . . . . .
4.8.1 GUI Applications with ISPF? . . . . . . .

. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . .

88
88
88
88
89
89
90
90
92
92
94
95

. . . . . . . . . . . . . . . . .

97
97
. 97
. 97
. 98
. 98
. 98
. 99
103
103
103
107
110
110
112
112
112
113
114
114
114
115
115
115
116
116
116
117
117
117
118
118
118
118
119
119
120
120
120
120
121
121

Contents

vii

. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .

4.8.2 Why Use ISPF C/S for GUI? . . . . . . . . . . . .


4.8.3 Writing ISPF GUI Applications . . . . . . . . . . .
4.8.3.1 Making an Application Display in GUI Mode
4.8.3.2 Specifying the Title Bar Text . . . . . . . . .
4.8.3.3 GUI Panel Size . . . . . . . . . . . . . . . . .
4.8.3.4 Window Frame . . . . . . . . . . . . . . . . .
4.8.3.5 Function Keys . . . . . . . . . . . . . . . . . .
4.8.3.6 Enter Key . . . . . . . . . . . . . . . . . . . .
4.8.3.7 CUA Attributes . . . . . . . . . . . . . . . . .
4.8.3.8 Action Bars and Pull-down Menus . . . . .
4.8.3.9 Mnemonics . . . . . . . . . . . . . . . . . . .
4.8.3.10 Pop-up Windows . . . . . . . . . . . . . . .
4.8.3.11 Pop-up Messages . . . . . . . . . . . . . . .
4.8.3.12 Push Buttons
. . . . . . . . . . . . . . . . .
4.8.3.13 Checkboxes . . . . . . . . . . . . . . . . . .
4.8.3.14 User-driven Applications
. . . . . . . . . .
. . . . . . . . . .
4.8.3.15 SELECT WSCMD service
4.8.3.16 What is not Supported? . . . . . . . . . . .
4.9 Sample GUI Application - Calculator . . . . . . . . .
4.9.1.1 The CALCDEMO REXX EXEC . . . . . . . . .
4.9.1.2 The CALCD Panel . . . . . . . . . . . . . . .
4.9.1.3 The CALCH Panel . . . . . . . . . . . . . . .
4.9.1.4 The CALCD Panel DTL . . . . . . . . . . . .
4.9.1.5 The CALCH Panel DTL . . . . . . . . . . . .
Chapter 5. Miscellaneous Discussion . . . . . . . .
5.1 Modifying ISPF Configuration Table (ISRCNFIG)
5.2 ISPF and the Future . . . . . . . . . . . . . . . .
5.2.1 From Icon to ISPF . . . . . . . . . . . . . . .
5.2.2 Taming TSO . . . . . . . . . . . . . . . . . .
5.2.3 Splitting Screens
. . . . . . . . . . . . . . .
5.2.4 Expanding Editor
. . . . . . . . . . . . . . .

Part 3. Software Configuration and Library Manager

. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .

. . . . . . . . . . . . . . .

147
147
148
148
148
149
149

. . . . . . . . . . . . . . . . . . . . .

151

Chapter 6. SCLM Concepts and Terminology


6.1.1 Software Configuration . . . . . . . .
6.1.2 Library Management . . . . . . . . .
6.1.3 Project . . . . . . . . . . . . . . . . . .
6.1.4 Project Definintion . . . . . . . . . . .
6.1.5 Project Hierarchy . . . . . . . . . . .
6.1.6 Language Definition . . . . . . . . . .
6.1.7 Architecture Definition . . . . . . . .
6.1.8 Build . . . . . . . . . . . . . . . . . . .
6.1.9 Promote . . . . . . . . . . . . . . . . .
6.1.10 Scope of Processing . . . . . . . . .
6.1.11 Versioning . . . . . . . . . . . . . . .
6.1.12 Component Changes of SCLM 4.1
6.1.13 SCLM Workshop . . . . . . . . . . .

. . . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .

Chapter 7. Install, Implement and Understand SCLM Product Sample


7.1 SCLM Project Manager Scenario . . . . . . . . . . . . . . . . . . .
7.1.1 What the SCLM Project Manager has to Do . . . . . . . . . .
7.1.2 Understand the Sample Environment . . . . . . . . . . . . . .

viii

ISPF/SCLM V4 Guide

121
123
123
124
125
125
126
126
127
128
129
129
129
131
133
134
135
136
136
136
140
142
143
145

. . . .
. . . .
. . . .
. . . .

153
153
153
154
154
154
154
154
155
155
155
155
156
156
157
157
158
159

7.1.3 Prepare Sample Project . . . . . . . . . . . . .


7.1.4 Prepare and Understand the Sample Project
7.1.5 Preparing the Example Project Data . . . . . .
7.2 Development Scenario . . . . . . . . . . . . . . . . .
7.2.1 Sample Seen from a Developer's Point of View

. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . .

Chapter 8. Project Organization


. . . . . . . . . . . . . . . . . . . . . .
8.1.1 Security Scheme for Project Data Sets . . . . . . . . . . . . .
8.1.2 Alternate Definitions . . . . . . . . . . . . . . . . . . . . . . . .
8.1.3 Authorization Codes (AC) . . . . . . . . . . . . . . . . . . . . .
8.1.4 Data Set Management . . . . . . . . . . . . . . . . . . . . . . .
8.1.5 Organization of Production Data Sets . . . . . . . . . . . . . .
8.1.5.1 Solution 1: Enterprise Projects Physically Separated . .
8.1.5.2 Solution 2: Enterprise Projects Concatenated . . . . . . .
8.1.5.3 Solution 3: One Enterprise Project with many Subprojects
8.1.5.4 Solution 4: Many Subprojects under one Roof . . . . . .
8.1.5.5 Solution 5: Combination of Choice . . . . . . . . . . . . .
8.1.6 Combination of Developer Data Sets
. . . . . . . . . . . . . .
8.1.6.1 Solution 1: One Group in many SCLM Projects . . . . . .
8.1.6.2 Solution 2: One or many Developers in one Group
. . .
8.1.7 Hierarchy Organization . . . . . . . . . . . . . . . . . . . . . . .
8.1.8 Implementation
. . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.8.1 Create Project View Prototype . . . . . . . . . . . . . . . .
Chapter 9. Role Management . . .
9.1 Interactive Test - A Must
. . .
9.1.1.1 SCLM Project Manager
9.1.1.2 SW Developer
. . . .
9.1.1.3 SW Team Leader . . .
9.1.1.4 SW Manager . . . . .
9.1.1.5 SW Configurators
. .
Chapter 10. Method Management

. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .

159
160
160
161
161
163
164
165
165
165
166
166
166
167
167
168
168
168
169
169
171
171

. . . . . . . . . . . . . . . . . . . . . . . . .

173
173
174
174
174
174
174

. . . . . . . . . . . . . . . . . . . . . . . . .

179

. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 11. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


11.1.1 RACF Protection . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.1.1 Program Class Protection . . . . . . . . . . . . . . . . . .
11.1.2 Authorization Code (AC) - Protection . . . . . . . . . . . . . .
11.1.3 Backup Concept . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.4 ABARS Implementation . . . . . . . . . . . . . . . . . . . . . .
11.1.5 Backup Execution . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.6 Restore Project Data Sets . . . . . . . . . . . . . . . . . . . .
11.1.7 Prevention Security Concept . . . . . . . . . . . . . . . . . . .
11.1.7.1 Backup when Promoting to Production . . . . . . . . . .
11.1.7.2 Save Previous Release . . . . . . . . . . . . . . . . . . .
11.1.7.3 Recover Previous Release . . . . . . . . . . . . . . . . .
11.1.7.4 Backup of Changes . . . . . . . . . . . . . . . . . . . . . .
11.1.7.5 SCLM Promote-Verify-Exit REXX . . . . . . . . . . . . . .
11.1.7.6 Promote-Verify-Exit MET#P11 . . . . . . . . . . . . . . . .
11.1.7.7 SCLMISP - Interface to ISPF Services . . . . . . . . . . .
11.1.8 Dual Account and Audit Data Sets . . . . . . . . . . . . . . .
11.1.9 Change Control . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.9.1 Non-Key Groups for Staging QA Pull-Up . . . . . . . . .
11.1.9.2 Use of Primary Non-Key Groups in an SCLM Hierarchy
11.1.10 PDF Edit Outside SCLM . . . . . . . . . . . . . . . . . . . . .

. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .

Contents

181
181
181
181
182
183
183
183
184
184
184
185
186
187
187
190
190
190
191
192
192

ix

11.1.10.1 PDF Configuration Table for Edit Control


11.1.10.2 Technical Implementation . . . . . . . .

. . . . . . . . . . . .
. . . . . . . . . . . . .

Chapter 12. Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . .


12.1 Vertical Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.1.1 Development, Maintenance and Fix in Parallel . . . . . . . . . .
12.1.1.1 Fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.1.2 Multiple Releases, Globals, Locals and Maintenance in Parallel
12.1.3 Keep Architecture Definitions Separate . . . . . . . . . . . . . .
12.2 Horizontal Source Versioning . . . . . . . . . . . . . . . . . . . . . . .
12.2.1 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.2 Recording the Versioning . . . . . . . . . . . . . . . . . . . . . . .
12.2.3 Retrieve a Recorded/Versioned Part . . . . . . . . . . . . . . . .
Chapter 13. What is Configuration Management? . . . . . . .
. . . . . . . . . . . . .
13.1 Why Configuration Management?
13.2 Trends Driving Configuration Management . . . . . . . .
13.3 Build Management . . . . . . . . . . . . . . . . . . . . . .
13.4 Change Control . . . . . . . . . . . . . . . . . . . . . . . .
13.5 Version Control . . . . . . . . . . . . . . . . . . . . . . . .
13.6 Imperatives for AD Tools
. . . . . . . . . . . . . . . . . .
13.7 SCLM Identification . . . . . . . . . . . . . . . . . . . . . .
13.8 SCLM Management . . . . . . . . . . . . . . . . . . . . . .
13.9 SCLM Control . . . . . . . . . . . . . . . . . . . . . . . . .
13.9.1 Access Control and Delimitation
. . . . . . . . . . .
13.9.2 Integrity . . . . . . . . . . . . . . . . . . . . . . . . . .
13.9.3 Consistency . . . . . . . . . . . . . . . . . . . . . . . .
13.9.4 User Exits . . . . . . . . . . . . . . . . . . . . . . . . .
13.9.5 Example of a REXX CCV Routine . . . . . . . . . . .
13.9.6 REXX CCV-Routine in FLMCNTRL . . . . . . . . . . .
13.9.7 Example of a REXX BUILD Translator
. . . . . . . .
13.9.8 Invocation REXX Procedure from FLMCNTRL Macro
Chapter 14. Change and Problem Management
14.1.1 Implementation of CCV Example . .
Chapter 15. Delivery

. .
. .
.
. .
. .
. .
. .
. .

. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . .

195
195
195
196
197
198
200
200
200
201
203
203
203
204
205
205
205
205
206
206
206
206
206
206
207
207
207
209
211
211

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

213

Chapter 17. Verification Management .


17.1 Verified by Roles . . . . . . . . . .
17.1.1.1 Promote Report . . . . . .
17.2 Verified by Architecture Definition
17.3 Verified by Include Tracking . . . .
17.4 Non-SCLM-Verified Include Objects

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .

Chapter 18. Meta Project . . . . . . . . . . . . . . . . . . . . . .


18.1 Simple Meta-project Implementation
. . . . . . . . . . .
18.2 Create Complex Documentation with REXX MET#XREF
18.2.1 REXX MET#XREF to Create Bookmaster Index Tags
18.3 Complex Meta-project Implementation . . . . . . . . . .
ISPF/SCLM V4 Guide

. .

. . . . . . . . . . . . . . . . . .

Chapter 16. Communication . . . . . . . . . . . . . . .


16.1 Notification at Promote with TSO Send . . . . .
. . . . . . . . . . . . . . . . . . . .
16.2 SCLM Batch
16.3 Check Predecessor Account Data with MET#PRE

. .

193
193

. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . .
. . . . . . . . .

215
215
216
216
219
219
219
219
219
219
221
221
222
223
227

18.3.1 Language Definition ASMPROJ (Member @ASMPRJ)


. . . .
18.3.2 REXX Program MET#B01 to Pack Compile List Output . . . .
18.3.3 REXX Program MET#B02 to Make Test Project Definition
. .
18.3.4 Language Definition ASMPROJT (Member @ASMPRJT) . . .
18.3.5 Language Definition LKEDPROJ (Member @LKEDPRJ) . . . .
18.3.6 REXX Program MET#P21 (Promote-Copy-Exit) to Copy Project
Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18.3.7 Architecture Definition ASMPROJ - Example . . . . . . . . . .

. . .
. . .
. . .
. . .
. . .
. . .
. . .

Chapter 19. Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


19.1.1 PDS-E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.1.2 Coding with Select Statements . . . . . . . . . . . . . . . . . . .
19.1.3 Submit to Batch
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.1.4 Establish an Own Class for Batch Jobs . . . . . . . . . . . . . .
19.1.5 Output Load Module in Non-SCLM Data Set
. . . . . . . . . . .
19.1.5.1 Reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.1.5.2 Solution 1 - Output Loadmodule with Linkage Editor . . . .
19.1.5.3 Solution 2 - Copy Translator as REXX Procedure . . . . . .
19.1.5.4 Solution 3 - Promote Exit Invocation of IEBCOPY . . . . . .
19.1.6 Link-edit with Parts from Non-SCLM Data Set . . . . . . . . . .
19.1.7 Block Sizes for Link Editor . . . . . . . . . . . . . . . . . . . . . .
19.1.7.1 Block Size Override . . . . . . . . . . . . . . . . . . . . . . .
19.1.8 ISPF Option 3.2, BLKSIZE = 0 . . . . . . . . . . . . . . . . . . . .
19.1.9 DASD Management with DFHSM . . . . . . . . . . . . . . . . . .
19.1.10 Single Archdef
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.1.11 Unwanted Outputs . . . . . . . . . . . . . . . . . . . . . . . . . .
19.1.12 VSAM Maintenance
. . . . . . . . . . . . . . . . . . . . . . . . .
19.1.13 Create Dependencies for Calls . . . . . . . . . . . . . . . . . . .
19.1.13.1 Language Definition @CIC1CPY - Create Copy . . . . . .
. . . . . . . . .
19.1.13.2 Archdef to Create COPY from EXEC CICS
19.1.13.3 Input Part WEFP023P Associated with Language CIC1CPY
19.1.13.4 Output Part WEFP023 from Language CIC1CPY after Build
19.1.13.5 Invocation COPY Member . . . . . . . . . . . . . . . . . . .
19.2 Language with CICS Preprocessor and Compile List Packing
. . .
19.2.1 Architecture Definition Examples . . . . . . . . . . . . . . . . . .
19.2.1.1 HL Part AQQQQQQQ . . . . . . . . . . . . . . . . . . . . . . .
19.2.1.2 LEC Part LQQQQQQQ for Target Environment CICS . . . .
. . . . . .
19.2.1.3 LEC Part MQQQQQQQ for C/370 Prelink (CICS)
19.2.1.4 CC Part QQQQQQQ for Target Environment CICS . . . . .
19.2.2 Language Definition @LKEDC - Binder for CICS . . . . . . . . .
19.2.3 Language Definition @CPRLK - C Prelink . . . . . . . . . . . . .
19.2.4 Language Definition @CCP - C Precompile/CICS
Translate/Compile/Pack . . . . . . . . . . . . . . . . . . . . . . . . . . .

233
236

. .

239
239
239
239
239
239
239
240
242
242
244
244
245
245
245
245
245
246
247
247
247
247
247
248
248
248
248
248
248
248
248
249

. .

249

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

253
253
253
253
254
254
254
254
254

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

257

Chapter 20. Workstation Connection . . . . . . .


20.1 Workstation for OS/2 . . . . . . . . . . . . .
. . . . .
20.2 AD/Cycle WorkStation Platform/2
20.2.1 New Functions with Release 1.2 . . . .
20.2.1.1 Installation and Maintenance Utility
20.2.1.2 Service Manager . . . . . . . . . .
20.2.1.3 Mapping File . . . . . . . . . . . . .
20.3 ISPF Version 4.1 Client/Server Front End .
20.4 LAN Library
. . . . . . . . . . . . . . . . . .
Chapter 21. Diskette Material

228
229
230
231
232

. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
.
.
. .
. .
. .
. .
. .
. .
. .
. .

. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .

Contents

xi

21.1.1
21.1.2
21.1.3
21.1.4
21.1.5
21.1.6
21.1.7

Project Definitions . . . .
Language Definitions . .
REXX Programs
. . . . .
Assembler Programs . .
Job Control . . . . . . . .
Architecture Definitions .
FOILS in LIST3820 Format

Chapter 22. Standards


22.1.1 ANSI/IEEE .
22.1.2 ISO9000 . .

. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 23. SCLM Translator Interfaces


. . . . . . . . .
. . . . . . . . . . . . . .
23.1.1.1 ITIRC KEYWORDS
23.1.2 Before We Begin . . . . . . . . . . . . . . . . . .
23.1.3 Basic Skills . . . . . . . . . . . . . . . . . . . . .
23.1.4 FLMTRNSL Macro . . . . . . . . . . . . . . . . .
23.1.5 Conditional Execution . . . . . . . . . . . . . . .
23.1.6 TSO Address Space . . . . . . . . . . . . . . . .
23.1.7 CALLMETH . . . . . . . . . . . . . . . . . . . . .
23.1.8 FLMALLOC . . . . . . . . . . . . . . . . . . . . .
23.1.9 DDNAME Substitution List . . . . . . . . . . . .
23.1.10 Refer Back without DDNAME Substitution List
23.1.11 Refer Back with DDNAME Substitution List
.
23.1.12 Refer Back with IEBGENER Bridge
. . . . . .
23.1.13 PORDER and Parameter Lists . . . . . . . . .

. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .

Chapter 24. Translator Building Blocks, #LANG, #MACLIB, ...


Chapter 25. SCLM Invocation . . . . . . . . . . . . . .
25.1.1 TSO SCLM Batch Job - An Example . . . .
25.1.2 REXX Program with ISPF Variables Example

ISPF/SCLM V4 Guide

261
261
261
263
263
263
263
263
264
265
265
266
267
268
268
269
270

. . . . . . . .

273

. . . . . . . . . . . . . .

281
281
282

. . . . . . . . . . . . . .

Chapter 26. Workshop Foils . . . . . . . . . . . . . . . .


26.1 Project Organization . . . . . . . . . . . . . . . . .
26.2 Project Description . . . . . . . . . . . . . . . . . .
26.3 SCLM Project Data Sets . . . . . . . . . . . . . . .
26.4 Partitioned Data Sets . . . . . . . . . . . . . . . . .
26.5 Data Base Structure for Project prjid . . . . . . .
26.6 Define Types . . . . . . . . . . . . . . . . . . . . . .
26.7 Define Protection Scheme . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
26.8 Project Views
26.9 Project View for Parallel Maintenance
. . . . . .
26.9.1.1 Concatenation Solution . . . . . . . . . .
26.10 Method PLIO - an Example . . . . . . . . . . . . .
26.11 Method Example PORDER . . . . . . . . . . . . .
26.12 Method Example GOODRC . . . . . . . . . . . . .
26.13 Method Example DD STATEMENTS . . . . . . . .
26.14 Method Example for Translator MBS . . . . . . .
26.15 Method Example for Translator PMO . . . . . . .
26.16 Method Example for Translator BHC . . . . . . .
26.17 Method Example for Multiple Translators . . . .
26.18 Method Example for Translator DEF1 and DEF2
26.19 Method Example for Translator with Parameters
26.20 Method Example for Translator with Option List

xii

257
257
258
258
258
259
259

. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . . .

285
285
286
286
287
287
288
288
289
289
289
290
290
291
291
292
292
293
293
294
294
295

26.21
26.22
26.23
26.24
26.25
26.26
26.27
26.28
26.29
26.30
26.31
26.32
26.33
26.34
26.35
26.36
26.37
26.38
26.39
26.40
26.41
26.42
26.43
26.44
Index

The Promote Process . . . . . . . . . . . . . . . . . . .


Create / Change a Part . . . . . . . . . . . . . . . . . .
SCLM Edit Profile
. . . . . . . . . . . . . . . . . . . . .
Draw Down Part FLM01EQU . . . . . . . . . . . . . . .
Architecture Definitions . . . . . . . . . . . . . . . . . .
Some Archdef Commands . . . . . . . . . . . . . . . .
Archdefs of SCLM Sample . . . . . . . . . . . . . . . .
Build an Application . . . . . . . . . . . . . . . . . . . .
Build of Archdef FLM01SB1 . . . . . . . . . . . . . . .
Build with Plan FLM01AP1 . . . . . . . . . . . . . . . .
Language Definitions Versus Architecture Definitions
PROMOTE an Application
. . . . . . . . . . . . . . . .
PROMOTE with Source Part . . . . . . . . . . . . . . .
PROMOTE with Plan FLM01AP1 . . . . . . . . . . . . .
Multiple Releases in Parallel
. . . . . . . . . . . . . .
Tips and Conclusions . . . . . . . . . . . . . . . . . . .
SCLM Invocation . . . . . . . . . . . . . . . . . . . . . .
SCLM Services . . . . . . . . . . . . . . . . . . . . . . .
Conversion Views . . . . . . . . . . . . . . . . . . . . .
Pilot Project . . . . . . . . . . . . . . . . . . . . . . . . .
Authorization Codes . . . . . . . . . . . . . . . . . . . .
Export / Import . . . . . . . . . . . . . . . . . . . . . . .
SCLM and Test Methods - Scenario . . . . . . . . . .
SCLM and Methods with Test Options . . . . . . . . .

. . . . . . . . . .

295
296
296
297
297
298
298
299
300
300
301
301
302
302
303
303
304
304
305
305
305
306
306
307

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

309

Contents

xiii

. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .

xiv

ISPF/SCLM V4 Guide

Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
Copyright IBM Corp. 1994

ISPF Settings Panel . . . . . . . . . . . . .


Local Print Command Edit . . . . . . . . .
Action Bar Pull-down . . . . . . . . . . . .
Long Message in Pop-Up . . . . . . . . .
Member Selection List . . . . . . . . . . .
RefList Pull-down . . . . . . . . . . . . . .
Reference Data Set List . . . . . . . . . .
Library List . . . . . . . . . . . . . . . . . .
Reference Mode . . . . . . . . . . . . . . .
View Entry Panel . . . . . . . . . . . . . .
View Warning . . . . . . . . . . . . . . . .
Edit COBOL Source . . . . . . . . . . . . .
Edit Color Settings . . . . . . . . . . . . .
Edit Language Selection . . . . . . . . . .
Compilers Pull-down . . . . . . . . . . . .
Foreground Selection Panel . . . . . . . .
ISPF Command Shell . . . . . . . . . . . .
VSAM Utilities . . . . . . . . . . . . . . . .
IDCAMS Statement . . . . . . . . . . . . .
VSAM Panel with Functions Pull-down .
Profile Member Name Panel . . . . . . .
Using a VSAM Profile Data Set . . . . . .
Changing the Name of a Profile Data Set
Catalog Search Warning Panel . . . . . .
Data Set List Color Change Utility . . . .
Data Set List Utility . . . . . . . . . . . . .
Allocate a New Data Set . . . . . . . . . .
Multivolume Allocation . . . . . . . . . . .
Long Message for
. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ISPF Primary Option Menu . . . . . . . . . . . . . . . . . . . . . . . .


ISPF Settings Panel (ISPISMMN) . . . . . . . . . . . . . . . . . . . . .
First ISPDTLC Screen
. . . . . . . . . . . . . . . . . . . . . . . . . . .
Second ISPDTLC Screen . . . . . . . . . . . . . . . . . . . . . . . . . .
Third ISPDTLC Screen . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
ISPF Editor with Action Bars OFF
. . . . . . . . . . . . . . . . . . . . . . . . . . .
First ISPDTLC Screen
Second ISPDTLC Screen . . . . . . . . . . . . . . . . . . . . . . . . . .
Third ISPDTLC Screen . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISPF Settings Panel with Function Keys Pull-down . . . . . . . . . .
Keylist Utility Panel (ISPKLUP) . . . . . . . . . . . . . . . . . . . . . .
Keylist Utility with Function Action Bar Pull-down (ISPKLUP) . . . .
Keylist Create Panel (ISPKLUCR) . . . . . . . . . . . . . . . . . . . .
Default Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keylist Change Panel (ISPKLUCH) . . . . . . . . . . . . . . . . . . . .
Keylist Utility with Delete Keylist Confirmation Pop-Up (ISPKLUP) .
Keylist Utility Browse Panel (ISPKLUB) . . . . . . . . . . . . . . . . .
Keylist Utility with Change Keylist Action Bar Pull-down (ISPKLUP)
ISREDM01 Panel
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PF Key Definitions and Labels Panel . . . . . . . . . . . . . . . . . .

. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .

6
8
9
9
10
11
11
12
13
14
14
16
17
17
18
19
20
21
21
22
23
23
24
25
26
26
27
28
30
31
32
41
42
43
43
44
45
47
47
48
49
50
51
51
52
53
54
54
55
57
58

xv

52.
53.
54.
55.
56.
57.
58.
59.
60.
61.

Tailor Function Key Definition Display Panel (ISPOPFA) . . . . . . . . . . 59


Reflist Pull-down Menu
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Referral List Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Personal Data Set List Panel (ISRPDSNL) . . . . . . . . . . . . . . . . . . 63
Reference Data Set List Panel (ISRDSNL) . . . . . . . . . . . . . . . . . . 64
Reference Data Set List Open Panel (ISRPLTAB) . . . . . . . . . . . . . . 65
Defining Function Key to Issue Referral List Commands
. . . . . . . . . 67
Example of a Personal Data Set List
. . . . . . . . . . . . . . . . . . . . . 68
Defining Function Key to Speed Up Selection Personal List Entry . . . . 69
CUA Attribute Change Utility Panel Positioned on the Point-Shoot Panel
Element (ISPOPT1X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
62. Colors Pull-down on the ISPF Settings Panel Action Bar (ISPISMMN) . . 71
63. Status Pull-down on the ISPF Primary Option Menu . . . . . . . . . . . . 75
64. ISPF Primary Option Menu Status Area - Session View . . . . . . . . . . 76
65. ISPF Primary Option Menu Status Area - Function Keys View . . . . . . 76
66. ISPF Primary Option Menu Status Area - Calendar View . . . . . . . . . 77
67. Option Pull-down on the ISPF Status Pop-Up Window . . . . . . . . . . . 78
68. ISPF Calendar Note Pad panel (ISPCALNP) . . . . . . . . . . . . . . . . . 78
69. Variables Panel (ISPYVPN) . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
70. Calendar Colors Panel (ISPCALGC) . . . . . . . . . . . . . . . . . . . . . . 80
71. User View Customization Panel (ISPSAMUS) . . . . . . . . . . . . . . . . 80
72. ISPF Primary Option Menu Status Area - User Status View . . . . . . . . 81
73. User Point-and-Shoot Customization Panel (ISPSAMUP)
. . . . . . . . . 82
74. ISPF Primary Option Menu Status Area - User Point-and-Shoot View . . 82
75. ISPF 4.1 Primary Option Menu . . . . . . . . . . . . . . . . . . . . . . . . . 86
76. CM Mouse General Use Pop-Up Menu . . . . . . . . . . . . . . . . . . . . 92
77. ISPF Workstation Server Icon . . . . . . . . . . . . . . . . . . . . . . . . . . 97
78. TCP/IP Network Configuration Panel
. . . . . . . . . . . . . . . . . . . . 100
79. TCP/IP Routing Configuration Panel . . . . . . . . . . . . . . . . . . . . . 101
80. TCP/IP AutoStart Configuration Panel . . . . . . . . . . . . . . . . . . . . 101
81. TCP/IP Services FTP User Configuration Panel . . . . . . . . . . . . . . 102
82. Communications Manager Configuration Definition . . . . . . . . . . . . 104
. . . . . . . . . . . . . . . . . . . 105
83. Communications Manager Profile List
84. Communications Manager Local Node Characteristics
. . . . . . . . . 105
. . . . . . . . . . . . . . 106
85. Communications Manager Local LU Definition
86. TCP/IP for DOS CUSTOM.EXE Main Panel . . . . . . . . . . . . . . . . . 107
87. NDIS Interface Configuration Panel . . . . . . . . . . . . . . . . . . . . . 108
88. Routing Information Configuration Panel . . . . . . . . . . . . . . . . . . 108
89. Auto-Start Configuration Panel . . . . . . . . . . . . . . . . . . . . . . . . 109
90. FTP User Data Configuration Panel . . . . . . . . . . . . . . . . . . . . . 109
91. Choosing a download Method (Option 3.7) . . . . . . . . . . . . . . . . . 111
92. Downloading GUI Using FTP . . . . . . . . . . . . . . . . . . . . . . . . . 111
93. ISPF Server Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
94. Settings Window for Workstation Icon . . . . . . . . . . . . . . . . . . . . 113
95. Initiating a GUI Session from Within ISPF . . . . . . . . . . . . . . . . . . 115
96. ISPF Primary Option Menu in GUI . . . . . . . . . . . . . . . . . . . . . . 117
97. ISPF Command Shell GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
98. ISPF Settings Panel in 3270 Mode Displayed on a 327x Emulator . . . 122
99. ISPF Settings Panel in GUI Mode Display Using ISPF C/S . . . . . . . . 123
100. Initiate GUI Session Panel Showing GUI Window Frame Option . . . . 126
101. A Message Generated from a .TYPE=NOTIFY Message Definition
Displayed Using ISPF C/S . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
102. A Message Generated from a .TYPE=WARNING Message Definition
Displayed Using ISPF C/S . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

xvi

ISPF/SCLM V4 Guide

103. A Message Generated from a .TYPE=ACTION Message Definition


Displayed Using ISPF C/S . . . . . . . . . . . . . . . . . . . . . . . . . . .
104. A Message Generated from a .TYPE=CRITICAL Message Definition
Displayed Using ISPF C/S . . . . . . . . . . . . . . . . . . . . . . . . . . .
105. Sample Calculator in Decimal Mode
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
106. Sample Calculator in Hexadecimal Mode
107. Configuration and Change Management (CCM) . . . . . . . . . . . . . .
108. Many Enterprise Projects . . . . . . . . . . . . . . . . . . . . . . . . . . .
109. Load Modules Concatenated for Production . . . . . . . . . . . . . . . .
110. Prjviews Combine Data Sets Physically . . . . . . . . . . . . . . . . . . .
111. Many Separated Projects under one Roof . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
112. Many Subprojects Combined by Choice
113. Private Level - User IDs Defined in Project View . . . . . . . . . . . . .
114. Private Level - User IDs not Defined in Project View . . . . . . . . . . .
115. Backup Scenario - Archive of Four Releases Back . . . . . . . . . . . .
116. Backup Scenario - Inversed Archive Hierarchy to Restore Last Release
117. Backup Scenario - Alternate Project Definition for Backup Group . . .
118. Backup Scenario - REXX Program Call in FLMCNTRL Macro . . . . . .
119. Pull-up for Better Quality Assurance
. . . . . . . . . . . . . . . . . . . .
120. Fixes are Integrated Immediately to PROD . . . . . . . . . . . . . . . . .
121. Fix Load Data Sets, Preconcatenated . . . . . . . . . . . . . . . . . . . .
122. Non-Key Group APPLY Preconcatenate PROD
. . . . . . . . . . . . . .
123. Concatenate Fixes, Integrate Maintenance, Control Development . . .
124. Archdefs must be Fulfilled . . . . . . . . . . . . . . . . . . . . . . . . . . .
125. REXX MET#CCV1 Obliges a CCV Number . . . . . . . . . . . . . . . . .
126. FLMCNTRL Macro Implementation of REXX CCV-Program . . . . . . .
127. REXX BUILDX1 to Demonstrate a REXX Build Translator . . . . . . . .
128. REXX BUILDX1 to Demonstrate a REXX Build Procedure . . . . . . . .
129. Example to Invoke REXX Program through FLMCNTRL Macro . . . . .
130. REXX BUILDX1C to Demonstrate a REXX Build Procedure . . . . . . .
131. SW Delivery - Project View . . . . . . . . . . . . . . . . . . . . . . . . . .
132. Hierarchy SCLM Meta Project
. . . . . . . . . . . . . . . . . . . . . . . .
133. 3 Level Meta Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
134. Hierarchy Complex SCLM Meta Project
. . . . . . . . . . . . . . . . . .
135. Sample SCLM Language with Output Directed To NON-SCLM Data Set
136. Translator Sample Embedding Copy Procedure . . . . . . . . . . . . . .
137. Copy Procedure as Translator . . . . . . . . . . . . . . . . . . . . . . . .
138. Promote Exit MET#P12 for IEBCOPYing PSB and DBD . . . . . . . . . .
139. REXX Promote Exit MET#P12 . . . . . . . . . . . . . . . . . . . . . . . . .
140. IEFBR14 as a Translator . . . . . . . . . . . . . . . . . . . . . . . . . . . .
141. Conditional Translator Execution . . . . . . . . . . . . . . . . . . . . . . .
142. IKJEFTSR Sample Interface . . . . . . . . . . . . . . . . . . . . . . . . . .
143. Refer Back without DDname Substitution List . . . . . . . . . . . . . . .
144. Refer Back with DDname Substitution List . . . . . . . . . . . . . . . . .
145. Refer Back with IEBGENER Bridge . . . . . . . . . . . . . . . . . . . . . .
146. PORDER and the Parameter List . . . . . . . . . . . . . . . . . . . . . . .
147. #LANG Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
148. #MACLIB Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
149. #ASM Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
150. #CICS Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
151. #APPEND Macro
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
152. EXXx SCLMAPND to Concatenate Build Translator Listings . . . . . . .
153. @LANG Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Figures

130
130
140
142
163
166
166
167
167
168
168
169
185
186
187
187
191
196
196
196
197
198
207
207
208
208
209
209
213
221
227
227
241
242
242
242
243
264
265
266
268
269
270
271
273
274
274
275
275
276
278

xvii

xviii

ISPF/SCLM V4 Guide

Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

Copyright IBM Corp. 1994

DTL List of Panels and Imbedded DTL Source Files


Default Key Settings . . . . . . . . . . . . . . . . . .
Valid Point-and-Shoot Change Values . . . . . . . .
DFLTCOLR Settings . . . . . . . . . . . . . . . . . . .
JCL and Definitions of SCLM Sample Project . . .
Architecture Definitions of Sample Project . . . . .
Program Sources of Example Project . . . . . . . .
Questions
. . . . . . . . . . . . . . . . . . . . . . . .
Table of Projects, Views and Roles . . . . . . . . .
Dual Control Data Sets: . . . . . . . . . . . . . . . .

46
52
. 70
148
159
160
160
173
176
190

. . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .

xix

xx

ISPF/SCLM V4 Guide

Special Notices
This publication is intended to help the ISPF system programmer to customize
and implement ISPF Version 4 Release 1 such that the users may get the
maximum benefit of its new functions with as little change as possible. The
information in this publication is not intended as the specification of any
programming interfaces that are provided by Interactive System Productivity
Facility Version 4 Release 1. See the PUBLICATIONS section of the IBM
Programming Announcement for Interactive System Productivity Facility Version
4 Release 1 for more information about what publications are considered to be
product documentation.
References in this publication to IBM products, programs or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program, or service is not intended
to state or imply that only IBM's product, program, or service may be used. Any
functionally equivalent program that does not infringe any of IBM's intellectual
property rights may be used instead of the IBM product, program or service.
Information in this book was developed in conjunction with use of the equipment
specified, and is limited in application to those specific hardware and software
products and levels.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594, USA.
The information contained in this document has not been submitted to any
formal IBM test and is distributed AS IS. The use of this information or the
implementation of any of these techniques is a customer responsibility and
depends on the customer's ability to evaluate and integrate them into the
customer's operational environment. While each item may have been reviewed
by IBM for accuracy in a specific situation, there is no guarantee that the same
or similar results will be obtained elsewhere. Customers attempting to adapt
these techniques to their own environments do so at their own risk.
Reference to PTF numbers that have not been released through the normal
distribution process does not imply general availability. The purpose of
including these reference numbers is to alert IBM customers to specific
information relative to the implementation of the PTF when it becomes available
to each customer according to the normal IBM PTF distribution process.
The following terms, which are denoted by an asterisk (*) in this publication, are
trademarks of the International Business Machines Corporation in the United
States and/or other countries:
Common User Access
IBM
Personal System/2
PS/2

Copyright IBM Corp. 1994

CUA
OS/2
Presentation Manager

xxi

xxii

ISPF/SCLM V4 Guide

Preface
This document discusses the new user interface made available with or widely
implemented in Interactive System Productivity Facility Version 4 Release 1. The
document contains a detailed description of this user interface and of the new
SCLM functions as they are implemented in ISPF Version 4.
The document is intended for system programmers preparing and customizing
ISPF for their users as well as for those users who perform their customization
individually. It the intention of this document to increase the user acceptance of
ISPF Version 4 Release 1 and to assist the users in exploiting the new facilities
to the maximum possible degree.

How This Document is Organized


The document is organized in three parts as follows:
Part 1, Introduction contains a general introduction to the content of the
document
Part 2, ISPF Version 4 Basics discusses the new facilities of ISPF Version 4
excluding SCLM and contains the following chapters:
Chapter 1, Technical Overview
Provides an overview of the various new facilities as well as those facilities
that have been fully implemented in ISPF Version 4
Chapter 2, User Interface
A detailed description of the new user interface in ISPF Version 4
Chapter 3, 3270 Environment
A discussion of the user interface in relation to an IBM 3270 environment
Chapter 4, Graphical User Interface (GUI)
A detailed step-by-step guide in implementing a TCP/IP or APPC connection
between a workstation and the host
Chapter 5, Miscellaneous Discussion
Discusses various miscellaneous topics .
Part 3, Software Configuration and Library Manager discusses SCLM in ISPF
Version 4 exclusively and contains the following chapters:
Chapter 6, SCLM Concepts and Terminology
This chapter explains the concepts of and some specific terms associated
with SCLM
Chapter 7, Install, Implement and Understand SCLM Product Sample
Provides guidance installing the SCLM Product Sample
Chapter 8, Project Organization
Discusses project organization
Chapter 9, Role Management

Copyright IBM Corp. 1994

xxiii

Testing techniques are discussed in this chapter


Chapter 10, Method Management
Discusses methods in an SCLM framework
Chapter 11, Security
This chapter discuses security implementations with SCLM
Chapter 12, Version Control
Discusses version control in SCLM
Chapter 13, What is Configuration Management?
An introduction to configuration management in SCLM
Chapter 14, Change and Problem Management
This chapter introduces change and problem management in an SCLM
framework
Chapter 15, Delivery
Explains software delivery in SCLM
Chapter 16, Communication
This chapter provides an example of how fix notification can be implemented
with SCLM
Chapter 17, Verification Management
Verification techniques are discussed in this chapter
Chapter 18, Meta Project
This chapter discusses a Meta-Project of managing SCLM with SCLM
Chapter 19, Optimization
Various optimization methods are discussed in this chapter
Chapter 20, Workstation Connection
This chapter discussed the use of workstations with SCLM projects
Chapter 21, Diskette Material
Provides a description of the SCLM workshop material that can be found on
the diskette that comes with this book
Chapter 22, Standards
This chapter provides a list of the various standards that exist for software
development
Chapter 23, SCLM Translator Interfaces
Provides a description of the SCLM translator interfaces
Chapter 24, Translator Building Blocks, #LANG, #MACLIB, ...
Provides a description of the SCLM translator building blocks
Chapter 25, SCLM Invocation
This chapter provides an example of SCLM batch invocation and a REXX
exec under ISPF using SCLM variables
Chapter 26, Workshop Foils

xxiv

ISPF/SCLM V4 Guide

Provides a collection of foils to be used with an SCLM implementation


workshop. Fullsize foils are found on the diskette in the back of this book

Related Publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this document.
TCP/IP for MVS V3R1 Performance Tuning Guide, SC31-7188-00
IBM TCP/IP for OS2 V2 Installation and Administration, SC31-6075-04
IBM TCP/IP for DOS V2.1.1 Installation and Administration, SC31-7047-01
Systems Application Architecture, Common User Access, SC26-4583
ISPF Master Index, SC34-4448
ISPF Getting Started, SC34-4440
ISPF Planning and Customizing, SC34-4443
ISPF Examples, SC34-4451
ISPF User's Guide, SC34-4484
ISPF Services Guide, SC34-4485
ISPF Dialog Developer's Guide and Reference, SC34-4486
ISPF Dialog Tag Language Guide and Reference, SC34-4441
ISPF Library Management Facility, SC34-4449
ISPF SCLM Developer's Guide, SC34-4469
ISPF SCLM Project Manager's Guide, SC34-4470
ISPF SCLM Reference, SC34-4471
ISPF Edit and Edit Macros, SC34-4446
ISPF Reference Summary, SC34-4445
ISPF Messages and Codes, SC34-4450
MVS/DFP 3.3: Linkage Editor and Loader, SC26-4564

International Technical Support Organization Publications


SCLM WSP/2 Usage Guide, GG24-3538
A complete list of International Technical Support Organization publications, with
a brief description of each, may be found in:
Bibliography of International Technical Support Organization Technical
Bulletins, GG24-3070.
To get listings of ITSO technical bulletins (redbooks) online, VNET users may
type:

TOOLS SENDTO WTSCPOK TOOLS REDBOOKS GET REDBOOKS CATALOG

Preface

xxv

How to Order ITSO Technical Bulletins (Redbooks)


IBM employees in the USA may order ITSO books and CD-ROMs using
PUBORDER. Customers in the USA may order by calling 1-800-879-2755 or by
faxing 1-800-284-4721. Visa and Master Cards are accepted. Outside the
USA, customers should contact their IBM branch office.
Customers may order hardcopy redbooks individually or in customized sets,
called GBOFs, which relate to specific functions of interest. IBM employees
and customers may also order redbooks in online format on CD-ROM
collections, which contain the redbooks for multiple products.

Acknowledgments
The advisor for this project was:
Erik P. Olsen
International Technical Support Organization, Poughkeepsie Center
The authors of this document are:
Minsani Mariani
Deirdre Errity
Matt Nuttall
Hartmut Singhofen

IBM
IBM
IBM
IBM

Indonesia
UK
Canada
Germany

This publication is the result of a residency conducted at the International


Technical Support Organization, Poughkeepsie Center.
Thanks to the following people for the invaluable advice and guidance provided
in the production of this document:
Dick Bittinger
Edward Chatelain
Andy Gibson
Robin Glisson
Robert Haimowitz
Marvin Knight
Bob Leah
Kit Lo
Kule Manning
Scott McAllister
Doug Nadel
Michael Petersen

xxvi

ISPF/SCLM V4 Guide

IBM, ISPF Development


IBM, ISPF Development
Loral Federal Systems - Air Traffic Control, Maryland
IBM, ISPF Development
IBM, ITSO Poughkeepsie Center
IBM, ISPF Development
IBM, ISPF Development
IBM, ISPF Development
IBM, ISPF Development
IBM, ISPF Development
IBM, ISPF Development
IBM, ISPF Development

Part 1. Introduction
Interactive System Productivity Facility (ISPF) Version 4 Release 1 constitutes a
major enhancement to previous versions of ISPF. Although the packaging, by
and large, is the same as previous versions, ISPF and ISPF/PDF is now one
single product. In this document we will refer to ISPF as the common
denominator for both products and use the term PDF to designate the functions
previously known as ISPF/PDF.
The functional enhancements to ISPF are mainly in the area of useability.
Although keylists were introduced long ago, it was not till ISPF Version 4
Release 1 that they were used all over ISPF. Same can be said about action
bars. Both these elements are required by the Common User Access (CUA)
definitions and since ISPF Version 4 Release 1 were to include a PS/2-based
Graphical User Interface (GUI), CUA was commonly adopted by ISPF.
Part 2 of this document addresses these changes and innovations. Particularly
the users of PDF will experience a change in the way they navigate within PDF
and the way each individual panel is treated. The traditional power users who
have learned to use PDF blindfold, will see their pace reduced for a while until
they learn the new panel structure and find ways to use it to their benefit. Many
a times will they type an ISPF command over the action bar and see a pull down
pop up when they press the Enter key. Hopefully this document will demonstrate
how the workplace can be accommodated to take advantage of several of the
new dialog elements so the user won't feel compelled to try to revert to the
structures of previous ISPF versions.
Chapter 1 will walk you through the innovations and enhancements of the entire
ISPF product.
Chapter 2 will concentrate on the specific enhancements to the user interface,
the human factors, that have been made available with this version. The
functions and features are discussed without regard to useability. The various
ways of working with the functions are explained; command interfaces, dialog
(action bar) interfaces and programming interfaces. Please refer to this section
when reading the following two chapters.
Chapter 3 deals with the particular workplace that the IBM 3270 offers. The
discussion is divided between the nonprogrammable 3270 hardware terminals
and the OS/2 emulated (through CM/2) 3270 terminals. For the
nonprogrammable terminals, only the options available with ISPF may be used.
However, quite a few is available to the user, who also with this workstation will
experience a freedom in choice of ISPF possibilities. The programmable
workstation offers a much larger degree of freedom in that the workstation in
addition to the pure ISPF possibilities also may be programmed to benefit from
the features that ISPF provides. Besides working with CM/2, also the licensed
program CMmouse is discussed, and examples of how to utilize it are given.
Finally Chapter 4 discusses the biggest innovation in ISPF Version 4 Release 1,
namely, GUI. Both the various ways of installing and activating it and the
usability for the user is discussed.

Copyright IBM Corp. 1994

Part 3 deals entirely with the IBM Software Configuration and Library Manager
(SCLM). SCLM is a software complex which aids the development of software
applications, it:
Simplifies and reduces development and maintenance effort
Controls the movement of application components
Maintains complete software configuration
Provides auditability
Can be customized to an organization's culture.
With the appropriate level of ISPF/PDF installed, a customer already has the
capability to use SCLM and its facilities; SCLM is available as an integral part of
ISPF/PDF (from level 3.1).
SCLM has two major functions:
1. Software Configuration
Using SCLM facilities, it is possible to define how the total application can be
built from a number of predefined source libraries. It is possible to:
quantify the impacts of changes to the system
verify the completeness of those changes and
rebuild the system following those changes.
For example, if an include structure is changed currently in a project with no
software configurator facilities, all the source libraries should be scanned to
see where else that structure is used and to remember to rebuild (recompile
or reassemble) all those affected source members. In an SCLM
environment, this could be under SCLM control, so that when the include
structure is changed it will not be possible to handover other source
members using that structure without rebuilding them.
Source modules can be permanently tied to other source modules or
generated outputs and SCLM will ensure that when updates are made to
these components they will always be promoted together.
2. Library Maintenance
In conjunction with controlling how the application is built from the source
created, SCLM will also control how that source is developed. Once the
library structure and development hierarchy have been defined to SCLM, it
will control what happens to the new or updated source code during the
development.
For example, when a module is updated for a particular development, SCLM
will lock that source member so that any other developer will know that it is
being worked upon. This helps to avoid developing conflicting copies of the
same source or losing pieces of simultaneously developed versions.

ISPF/SCLM V4 Guide

Part 2. ISPF Version 4 Basics

Copyright IBM Corp. 1994

ISPF/SCLM V4 Guide

Chapter 1. Technical Overview

1.1 New Functions in ISPF Version 4 Release 1


ISPF Version 4 Release 1 has many of the functions we have become familiar
with in previous versions of the product, but it has a new look and has entered
the Client-Server world. ISPF 4.1 provides a wide range of functions, and this
section will explore and discuss some of the differences between ISPF V3 and
ISPF V4.1.
We can still control and format the information displayed on our terminals, and
we hope to give you some hints and tips to enable you to navigate around ISPF
V4.1 with ease. One of the things that allows ease of use is that ISPF V4.1 now
conforms to Common User Access (CUA) guidelines. We now have Menu,
Utilities and Help available on all panels, thus allowing you to access some of
the basic functions by using the Action bar pull-downs.
The aim of this section of the book is to give you a good understanding of the
major changes in ISPF V4.1.

1.2 Usability Enhancements


It is important to emphasize that all of the modifications to the ISPF/PDF
interface are additions. They do not replace the existing methods of using the
product or navigating through it. You will be able to use the ISPF/PDF product
almost the same as in previous versions. Some changes and additions are
discussed below.

1.2.1 ISPF Settings


In ISPF V4.1 the former ISPF Parms panels have been consolidated into fewer
panels. This enables you to view most of the settings at once rather than
jumping from panel to panel. The ISPF Settings panel, as shown in Figure 1 on
page 6, contains settings from the 0.1 (Terminal Characteristics), 0.4 (Display
Characteristics), 0.6 (Print Graphics Parameters) and 0.9 (Dialog Test Option) as
well as a new display characteristic settings.
By selecting 0 from the Primary Options Menu or using the SETTINGS line
command from any panel, the panel shown in Figure 1 on page 6 will be
displayed. You can also invoke the settings panel from the settings choice on
the Menu pull-down, where it is available.
Note: The default for ISPF V4.1 is to have the command line placement at the
bottom of each logical screen. However, if your current application profile table
specifies ASIS, the ISPF V4.1 default will not override it.

Copyright IBM Corp. 1994

Figure 1. ISPF Settings Panel

In ISPF V4.1 you can select a pull-down choice from the Action bar that appears
at the top of the ISPF Settings Panel. The choices are:

1.2.1.1 Settings panel Action bars


Log/List
1.
2.
3.
4.

Log data set defaults


List data set defaults
List data set characteristics
JCL

Function Keys
1.
2.
3.
4.
5.
6.
7.
8.

Global PF Key settings


Keylist settings
Tailor function key display
Show all function keys
Show partial function keys
Remove function key display
Disable keylists
Enable keylists

Colors
1. Global colors
2. CUA attributes
3. Point-and-Shoot
Environ
1. Environ settings

ISPF/SCLM V4 Guide

GUI
1. Start GUI
2. GUI panel settings
Temporary
1. Message identifier
2. Panel identifier
Help
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

Settings
Options
Terminal characteristics
Print Graphics parameters
General
Log/List action bar
Function keys action bar
Color action bar
Environ action bar
GUI action bar
Temporary action bar

The following features can all be activated from the ISPF Settings Panel.
Jump from leader dots
Edit PRINTDS Command
Tab to Action Bar Pull-downs
Tab to Point & Shoot Fields
Long Message in Pop-Up

1.2.1.2 Jump from Leader Dots


The j u m p function allows you to enter =x (where x is an option number) without
going all the way from the panel you are working in to the Primary Options Menu
to select option x.
You can still j u m p from field prompts that have the ===>, but in ISPF V4.1 there
is also the possibility of jumping from field prompts that have leader dots,
(leader dots are display as . . ., i.e. dots with one intervening blank).
To enable the j u m p function from leader dots, enter a slash in front of the
choice on the Settings panel.

1.2.1.3 Edit PRINTDS Command


By entering a slash in front of the Edit PRINTDS Command choice on the
Settings panel, you will intercept the local print request. It is then possible to
modify the statements before the command is processed. You do this from the
panel shown in Figure 2 on page 8.

Chapter 1. Technical Overview

Figure 2. Local Print Command Edit

1.2.1.4 Action Bar Pull-downs


Perhaps the most obvious change in ISPF V4.1 is your exposure to Action Bar
pull-downs. These pull-downs were available in ISPF V3 but were not widely
used. The pull-downs will vary depending on which panel you are viewing but
allow you to do many of the functions that you previously achieved by issuing
several line commands on several screens. These pull-downs can be activated
by using your keyboard.
The home key can bring the cursor to the first action on the action bar and the
tab-key can move it forward or backward on the action bar. Of course, this is
only true if the action bar choices are tab-able and on top of the screen; they
may be relocated in split-screen mode. In Figure 3 on page 9 you can see an
example of what the Help Action bar pull-down looks like.
By using the Action bar pull-downs, you can perform another function without
having to end the present function. For example, if you are editing a data set
and want to allocate another data set, in ISPF 4.1, from your edit session, select
the option 2 (Data set) from the Utilities pull-down on the Edit panel action bar.
ISPF suspends your edit session and displays the Data Set Utility panel. When
you have allocated the new data set and end the function, ISPF V4.1 takes you
directly back to your edit session.

ISPF/SCLM V4 Guide

Figure 3. Action Bar Pull-down

1.2.1.5 Point & Shoot Fields


Point-and-Shoot fields are cursor sensitive. When you select a field, the action
described in that field is performed. For example, from the Primary Option
Menu, if you place the cursor at the Utilities selection and press Enter, you are
brought to the Utilities Selection Panel. In Version 3 this is not the case. Had
you placed the cursor at the Utilities selection, once you press the Enter button
the cursor is moved back to the command line and a message of ENTER
OPTION is given.
Point-and-Shoot fields allow quick command entry. When you point (by placing
the cursor over the desired area) and shoot (using the Enter key), the field is
activated for selection.
Be careful if you have entered a command on the command line as this
command will be processed before any Point-and-Shoot command.

1.2.1.6 Long Message in Pop-Up


When the HELP command is entered, the long message pop-up displays an
explanation of the error. For short messages, a one-line explanation is
displayed in the top righthand corner of your screen, but by requesting help for a
second time, the explanation is displayed in a pop-up window. You can see this
in Figure 4.

Figure 4. Long Message in Pop-Up

Chapter 1. Technical Overview

1.2.2 Member Selection List


The fields for the member selection are also point-and-shoot enabled. Data
within the columns can be sorted by pointing and shooting on the column
names.

Figure 5. Member Selection List

1. Select a column (such as date changed) by placing the cursor over the
point-and-shoot field and pressing Enter. Then the data sets are sorted in
date changed order with the most recently changed data set at the top of the
list, as you can see in Figure 5.
2. To resort the member list by the Name column, place the cursor over an
entry in the Name column and press Enter.

1.2.3 Reflists
A feature of the View Option allows you to recall data sets and libraries that you
have most recently accessed. In order to add a data set to the list, type the data
set name in the Other Partitioned or Sequential Data Set Name field. To add a
library, enter a library in the Library field. Whenever ISPF references a data set,
such as in a Move/Copy operation, data sets will be added.
1. Select the RefList Action from the Action Bar, as shown in Figure 6 on
page 11.
2. Select 1 from the RefList pull-down.
The Reference Data Set List will display data sets which have been accessed
during this ISPF session. You can see an example of working with this list from
the View function in Figure 7 on page 11. By selecting one of the data sets in
the reference list, you may View it without actually having to type in the data set
name on the View panel.

10

ISPF/SCLM V4 Guide

Figure 6. RefList Pull-down

Figure 7. Reference Data Set List

A library list is a list of libraries that have been accessed during your ISPF
session. Libraries accessed are dynamically appended to the library reference
list for later use.
1. Press PF3 from Reference Data Set List Panel.
2. Move the cursor to the RefList Action Bar options, and press Enter.
3. Select Option 2, Reference Library List, and press Enter.
Chapter 1. Technical Overview

11

You may now view these lists, as shown in Figure 8 on page 12 and make a
selection and either execute or retrieve the data set or library stored.

Figure 8. Library List

As well as the Reference List action there is the Reference Mode action. This
indicates whether you would like to either Execute the View of the reference
entry or Retrieve the data sets or library entries onto the View or Edit Entry
Panel. In Execute mode, the data set or library would be viewed or edited. In
Retrieve mode, the data set or library name entries would be placed into the
appropriate fields on the view or edit screen, where they could be edited if
desired. See Figure 9 on page 13.

12

ISPF/SCLM V4 Guide

Figure 9. Reference Mode

1.2.4 The View Facility


The new View facility from the Primary Option Menu, shown in Figure 10 on
page 14, allows you to view or browse source data or output listings. If you
select the View Option, you can update existing datasets using Edit commands,
but any changes you make to the data are not saved. This safeguards against
unintentional changes being made.
Browse can be enabled from the View Entry Panel, but the View function is much
more powerful. It provides all the facilities you would expect from Edit but
doesn't issue an exclusive enqueue against the dataset, and so allows several
users to process the same data set or member simultaneously.
You can now View, Browse or Edit a dataset without leaving your current
session. View, Browse and Edit are now primary commands. So now if you are
browsing a member and decide you wish to make some changes to this member
after all, you type edit and the member name on the command line, and you are
taken into the Edit panel for this particular member.
If you wish to Edit a member of a different library, type edit on the command line
and press Enter, and the Edit Entry Panel will be brought up.
1. From the Primary Options Menu, select Option 1, and you will be presented
with the View Entry Panel, as shown in Figure 10 on page 14.

Chapter 1. Technical Overview

13

Figure 10. View Entry Panel

1.2.4.1 Using the Create and Replace Commands


If you wish to save the changes you have made, you must create a new member,
in which to save your changes. The End command will terminate the View
function and no changes are saved.

Figure 11. View Warning

Alternatively, you may wish to save your changes to the same member, so in
order to do this, you would use the replace primary command. The panel shown
in Figure 11 will be presented to you when you try to save your changes.
Note
If you submit a job for background execution in browse mode and this data
set is edited and saved by another user, the job submitted will be the
updated data set which will not be what you had intended. You can
safeguard against this happening by submitting the job from view.

14

ISPF/SCLM V4 Guide

1.2.5 Color Usage


1.2.5.1 Edit Hilite
Use of the facilities of the editor is unchanged. However, as part of the support
for language sensitive coloring, a new edit primary and macro command called
hilite has been added. Valid synonyms are hi and hilight. Operands of the
hilite command are:
Reset

Resets defaults (auto, on, find and cursor on)

On

Sets coloring on and turns logic off

Off

Sets coloring off (except cursor highlighting)

Auto

Lets ISPF/PDF determine the language

Default

Highlights the data in one color

Paren

Turns on parenthesis matching. When parenthesis matching is active,


only comments are colored. All other code is shown in the default
color. Note that extra parenthesis highlighting is always active when
highlighting is active.

Logic

Turns on both IF and DO logic matching


DOLOGIC highlights logical blocks (DO/END, {}, etc.)
IFLOGIC highlights IF/ELSE pairs
NOLOGIC is the same as ON
Do is the default. When logic matching is active, only comments are
specially colored. All other code, other than logic keywords, is shown
in the default color.

Find

Toggles highlighting find strings.

Cursor

Toggles highlighting of the phrase with the cursor.

Disabled

Turns off all HILITE features. The disabled status is not stored in your
edit profile, therefore you must re-enter the operand every time you
go into the editor.

Search

Finds the first unmatched END, ELSE, } or ). To use search you must
have had the logic enabled. The search for mismatches only occurs
for lines above the last displayed line, so you may have to scroll to
the bottom of the file before issuing the hi search command.

Other

Highlights the data as a pseudo PLI language - limited CLIST support


is also provided.

1.2.5.2 Language Sensitive Editing


The ISPF editor now actively assists you in analyzing and building syntactically
correct source code through language sensitive highlighting.
Since you can customize the editor to define almost any language construct, the
programming task is a less error-prone one.
You can force the editor to highlight the file according to the rules of the
following languages:

Chapter 1. Technical Overview

15

ASM
BOOK
C
COBOL
DTL
JCL
PANEL
PASCAL
PLI
REXX
1. Select a member from a data set list by placing the cursor over the
point-and-shoot field and pressing Enter.
In living color, you will see several changes that make editing a data set an
easier task.

Figure 12. Edit COBOL Source

From within the View session, you may execute compiles and perform Dialog
Test functions. The Edit action allows you to enable language sensitive editing
specific to the file that is being edited.
1. From the panel shown in Figure 12, select the Edit action from the Action
Bar.
2. Select 3 Hilite. See Figure 13 on page 17.

16

ISPF/SCLM V4 Guide

Figure 13. Edit Color Settings

1. Enter 1 for Automatic Language highlighting, shown in Figure 14.


2. Enter 2 for Coloring.
3. Exit from the Edit Colors screen to return to the View screen.

Figure 14. Edit Language Selection

Notice also that language reserved words, comment lines, literals and matching
parenthesis, operators, and special characters are highlighted and color-coded.
Notice that a string or line being edited is highlighted.
Chapter 1. Technical Overview

17

1. Move the cursor to the edit area of the source file.


2. Place an asterisk on a line of code (any line other than a comment line).
Notice that the newly commented line takes on the highlighting of the other
commented lines.
1. Misspell a COBOL reserved word (XDENTIFICATION DIVISION, for example).
Notice that the highlighted field of the reserved word changes with the
misspelling to a nonhighlighted field. The cursor moves to highlight the first
character string of the following line.
1. Remove a quote from a literal string.
Notice that text following the deleted quote takes on the highlighting of a literal
string.
1. Replace the quote to the literal string.
Notice that regular highlighting has returned.
Menu and Utilities Actions are available from this screen so that you can easily
access these functions while within the edit session. A new action, Compilers,
allows you to perform compile functions while within the View session.
You may execute Compilers to compile this edited and unsaved member without
having made permanent changes to the source file. From within the View or Edit
session, you may also access Dialog Test functions from the Action bar
pull-down. This enables quick testing while modifying a data set.

Figure 15. Compilers Pull-down

1. Begin to tab through the actions on the Action Bar.


2. Select Compilers from the Action Bar, shown in Figure 15.

18

ISPF/SCLM V4 Guide

3. Enter 1 for Foreground Compilers.


Any of the foreground compilers, shown in Figure 16, can be selected.

Figure 16. Foreground Selection Panel

1. Press PF3 to return to the View screen.


2. Press PF3 to end (you will see the view warning screen, an example of which
is shown in Figure 11 on page 14).
While in View mode, you may edit a data set but will be warned when you have
requested END. You may either end the View session without saving changes or
use editing commands to save the changes.
Another improvement to ISPF Version 4.1 is the ability to edit data wider than
255 characters. This allows wide files to be edited in the same manner as other
files.
Also significant is that retrieval times for very large data set name lists from the
Data Set List Utility panel has been greatly improved.

1.2.6 ISPF Command Shell


The TSO command processor has been enhanced to save the ten most recent
TSO commands that you have entered on this panel. These commands can be
selected from ten point-and-shoot fields.
In Figure 17 on page 20, if you place the cursor, for example, at the first
command in the list and press Enter, then that command would be brought to the
command input field and by subsequently pressing Enter once again, the
command is issued (assuming that the default is retrieve, see Mode section
below). This proves very useful for complex TSO commands you issue, as it
saves recoding and reduces the chances of syntax errors.

Chapter 1. Technical Overview

19

Figure 17. ISPF Command Shell

What happens when you select a command depends on the mode you specify
from the Mode pull-down on the action bar. The Mode pull-down offers you
three choices:
Retrieve

Allows you to retrieve commands from the saved command area and
places the command in the TSO Command field so that you can edit it
before the command is executed. This is the default.

Execute

Allows you to retrieve commands from the saved command area and
execute the command in one step.

Delete

Allows you to delete commands from the saved command area


without executing them. Place the cursor on the command to be
deleted and press Enter. The command will be blanked out. This
allows you to delete a command if you are running with Update mode
set off.

The list pull-down offers you two choices:


Update On Allows you to append new commands in the saved command area
automatically.
Update Off New commands are not appended to the list automatically.

1.2.7 VSAM Utilities


The VSAM utility function will enable you to define or delete a VSAM data set or
to issue the listcat command without using the IDCAMS command. The IDCAMS
command is now generated, alleviating the need to know the syntax of it. The
command will process in the foreground. When you build define, delete and
listcat commands, they are saved to a profile data set for later use.

20

ISPF/SCLM V4 Guide

Instructions for Defining a Cluster


1. On the VSAM utilities panel, shown in Figure 18, enter 1 in the Define field
and 3 in the Data Type field.
2. Press the Enter key twice - the generated IDCAMS statements are displayed
as shown in Figure 19.

Figure 18. VSAM Utilities

Figure 19. IDCAMS Statement

To process the command, type EXEC on the command line and press Enter.

Chapter 1. Technical Overview

21

You should get a message in the top righthand corner of your screen saying
Return Code 0. If the command processes with a nonzero return code, you will
be presented with another panel where you can make the necessary changes
and resubmit the command.
Note: You should select the Browse errors only option on the Define Cluster
panel to browse the output from IDCAMS when a nonzero return code is
returned.

1.2.7.1 Building a VSAM Profile Data Set


A Profile Data Set is built to store input fields on a VSAM input panel which you
can retrieve later to the same panel. If you use a profile that was defined for a
different request (eg. GDG), you will receive a type mismatch error.
When you have filled in a VSAM input panel, select the Save to Profile choice
from the Functions pull-down on the input panel action bar as shown in
Figure 20.

Figure 20. VSAM Panel with Functions Pull-down

ISPF displays a panel that allows you to give the profile data set member a
name, as shown in Figure 21 on page 23.
Type in the member name. When you press Enter, the data set will be created
for you.
Note: The Profile data set must be a variable blocked, LRECL 203, PDS.

22

ISPF/SCLM V4 Guide

Figure 21. Profile Member Name Panel

1.2.7.2 Using a VSAM Profile Data Set


When you display a VSAM input panel, select the Get from Profile choice from
the Functions pull-down on the input panel action bar, as shown in Figure 22.

Figure 22. Using a VSAM Profile Data Set

When you select a profile and press Enter, the fields on the entry panel will fill
with the values stored in your profile data set member.

Chapter 1. Technical Overview

23

1.2.7.3 Changing the VSAM Profile Data Set


To change the name of the active VSAM profile data set you have to select the
Change Profile Data Set choice from the Functions pull-down on an input panel
action bar, as shown in Figure 23.

Figure 23. Changing the Name of a Profile Data Set

Here you should type the name of another profile data set, and if it doesn't
already exist, it will be created for you. It then becomes the active profile data
set.

1.2.8 Data Set List Utility


The Option 3.4 Data Set List Utility has been enhanced and uses a new method
of searching for data set names plus improved I/O for member lists which
provides noticeable performance enhancements.

1.2.8.1 Usage of Option 3.4 Data Set List


Alias Names

Name listed is actual alias.


Volume name indicates alias.
In Figure 26 on page 26 there is an example of an alias name and a real
name.

Commands Allowed

All line commands except D, R and U.


Real names are displayed when command is issued.

Dsname Level Qualifiers

24

ISPF/SCLM V4 Guide

Asterisks allowed anywhere in qualifier.


You can use both single and double asterisks as a qualifier.
Use of percent signs as a qualifier is also allowed.

VSAM Clusters

Volume indicator for the catalog entry for a VSAM cluster is VSAM.
The data and index portions have volume names, as shown in Figure 26
on page 26. Delete is only valid for the cluster portions.

1.2.8.2 Examples of Dsname Levels


SYS1.PARMLIB

One data set name.

SYS1.*

All data set names with SYS1 as first qualifier and a least one
more qualifier.

SYS1 or SYS1.**

All data set names with SYS1 as first qualifier.

**.CLIST

All data set names with a qualifier of CLIST.

*.CLIST

All data set names with any first qualifier and CLIST as the
second and final qualifier.

SYS1.A*%%B

All data set names with SYS1 as first qualifier, a second


qualifier that starts with an A, ends with a B and has at least
two other characters.

Note
Use of * or * * as the first qualifier causes all catalogs to be searched,
which requires a lot of time. If you use either of these first level qualifiers,
you will be presented with a warning panel, as shown in Figure 24.

Figure 24. Catalog Search Warning Panel

In ISPF V4.1 there are some additional data set list primary commands. You can
use the following commands from the command line after the data set list is
displayed:
LC

Displays data set list color change utility, as shown in Figure 25 on


page 26.
Note: You can display the data set list color change utility panel by
selecting the Function action bar pull-down from the Data Set List panel,
as shown in Figure 26 on page 26.

VA

Displays data set list attribute view.

VS

Displays data set list space view.

VT

Displays data set list total view.

VV

Displays data set list volume view.


Chapter 1. Technical Overview

25

Note
When you issue the VT command, the response time is extremely low even if
your list of data sets is very large.

Figure 25. Data Set List Color Change Utility

Figure 26. Data Set List Utility

26

ISPF/SCLM V4 Guide

1.2.9 Multivolume Data Set Support


ISPF Version 4.1 supports multivolume data sets with browse, edit and utilities
functions. Multivolume data set support provides data integrity and security
when renaming and deleting. Without this function, when a data set is renamed
or deleted, only the first volume is affected.
1. Enter 3.2 to get to the Data Set Utility screen.
2. Point at the Allocate new data set field.
3. Enter the name of an ISPF Library in the ISPF Library field or another
partitioned or sequential data set name in the Data Set Name field, and
shoot. You will then be presented with the panel shown in Figure 27.
4. Erase the Volume serial field.
5. Record format should be set to FB.
6. The directory blocks field must be 0 as mulitvolume data sets are sequential.
7. Enter / in the Allocate Multiple Volumes field and press Enter. The
panel brought up is shown in Figure 28 on page 28.

Figure 27. Allocate a New Data Set

You can now allocate data sets across multiple volumes - up to 20 volumes
permitted.
Note: Although the volume input fields are numbered consecutively, you can
enter volume names in any field.

Chapter 1. Technical Overview

27

Figure 28. Multivolume Allocation

1.2.9.1 Usage of Multivolume Data Sets


The functions listed below can be used across Multivolume data sets:
Browse
Edit
View
Allocate
Information
Delete
Rename
Print
Move & Copy
VTOC list
SuperC
SearchFor
Restrictions
SCLM does not support multivolume data sets
LMF does not support multivolume data sets
File Tailoring does not support multivolume data sets
ISRLEMX does not support multivolume data sets

1.2.9.2 Hints and Tips


Information
The information panels contain nondisplay fields that will display when the
number of volumes that contain data is two or more for SMS data sets, and
for NON-SMS, all volumes allocated will display.
A plus sign will display beside the volume indicating that the data set
contains data that spans two or more volumes, and a line at the bottom will
inform you that the data set is a multivolume data set.

28

ISPF/SCLM V4 Guide

Non-SMS data sets


All allocated volumes will display when information has been requested.
SMS data sets
All volumes that contain data will display when information has been
requested.
Data set list
A plus sign will display beside the volume name when the data set is
multivolume.
Information is for all spanned volumes.
Space, Attrib and Total views will return information for all spanned volumes.
VTOC list
A plus sign will not display beside the volume name when the data set is
multivolume.
Information is for all spanned volumes.
Space, Attrib and Total views will return information for only the volume
indicated.

1.2.10 Display Message ID


In order to use the ISPF Messages and Codes, SC34-4449-00 manual you need an
easy way to determine the message ID of ISPF error messages.
Prior to ISPF V4.1 the only way to determine the message ID of a message was
through help while running in ISPF TEST mode.
The command MSGID with no parameters will display a message pop-up
indicating the message ID of the last message processed. It will return only the
ID of a message for its own logical screen.

MSGID uses message ISPG056 to display this message. It is never saved as


the last message processed.
MSGID with a parameter of ON or OFF indicates whether you want the message ID
added to the beginning of long message text when the long message is
displayed.
During entry to ISPF, the mode is initialized to OFF.
If the addition of the message ID would cause long message text to be
truncated, the message is displayed in a pop-up window.
The MSGID ON/OFF command affects only the current logical screen, so when
you are running in split screen, one screen can have MSGID ON and the other
MSGID OFF.
Long Message ID
A new option on the LOG Defaults panel allows you to select whether the
message ID is written as part of the long message text.

The initial default is NO.

This setting is saved across sessions.

Chapter 1. Technical Overview

29

Note
Not all lines in the LOG dataset originate from a message member.
Therefore, not every line in the LOG dataset will have a message ID.

1.2.10.1 Usage
MSGID is a new command in the ISPF command table.
After getting an error message, you can enter MSGID, and a message pop-up
will be displayed giving the message ID of the last message, an example of
which is shown in Figure 29.
You can enter MSGID ON to have ISPF display the message ID of the error
message as part of the long message.
The MSGID ON/OFF setting is not saved across sessions. It is initialized to OFF,
and it does not have effect across split screens (like PANELID).
Messages which have the message number included in the long message
text will continue to display the message number, even when MSGID OFF is in
effect. Also, for these messages, the message number will appear twice
when MSGID ON is in effect.
This facility does not affect:

Long message text returned by the GETMSG service

Long message text displayed in the Error Box

Long message text displayed by the TRACEX service

MSGID command with MSGID ON


Figure 29. Long Message for

1.2.11 Forward Retrieve and Retrieve Pop-up


RETF and RETP are new commands in the ISPF Command table.

1.2.11.1 RETF - Forward Retrieve


Retrieves commands from the command stack moving in the direction from
the oldest command in the command stack towards the most recent
commands in the command stack.
Useful after pressing RETRIEVE too many times. RETF will step back to the
command you were trying to retrieve without going through the entire
retrieve stack to get back to it.
Forward Retrieve (RETF) will retrieve the oldest command on the command
stack if RETF is entered immediately after a command is executed (without
doing a RETRIEVE first).

30

ISPF/SCLM V4 Guide

1.2.11.2 RETP - Retrieve Pop-Up


This command displays a pop-up panel with a list of commands to be retrieved,
as shown in Figure 30.
Displays up to 25 commands saved in the retrieve stack.
You can select the command to be retrieved to the command line:

You can select the command by number or point-and-shoot on the field.

You will not be able to change the commands in the retrieve pop-up
before retrieving the command.

For long commands the last visible character of the command will be
displayed as > indicating there are more characters which are not shown.

RETPRetrieve Pop-up Panel


Figure 30.

RETP action bar choice OPTIONS, Figure 31 on page 32 .


Set the minimum number of characters required to save a command in the
retrieve stack.

The default is one character.

Choose whether to position the cursor at the beginning or end of the


retrieved command when the command is retrieved to the command line.

The default is to place the cursor at the end of the retrieved command.

Chapter 1. Technical Overview

31

RETPRetrieve Pop-up Panel with Options Pull-down


Figure 31.

Note:
ISPF V4.1 will save duplicate commands into the retrieve stack if the last
command on the retrieve stack is different from the command being processed.
There may not be room in the retrieve stack for 25 commands.
It may seem that RETP is broken if some large commands are saved in the
retrieve stack. Old commands are removed to make room in the stack for
new commands, so even though over 25 commands may have been entered,
it is possible that not all of them will be displayed by RETP.
Note
The size of the retrieve stack is set during installation by changing the
ISPDFLTS table. The default is 512 bytes.

1.3 LIBDEF Enhancements


There are three new functions to LIBDEF in ISPF V4.1. They are:
LIBDEF stack

Allows LIBDEF definitions to be stacked.

LIBDEF dialog query

Allows dialogs to obtain current LIBDEF definitions.

LIBDEF display utility

Allows you to display the currently active LIBDEF


interactively.

Additional information and examples can be found in the ISPF 4.1 Services
Guide, SC34-4485-00.

32

ISPF/SCLM V4 Guide

1.3.1 LIBDEF Stack Facility


ISPF V4.1 provides a facility that allows a LIBDEF definition to be stacked.
In ISPF V3, a LIBDEF definition established by the current dialog replaced or
overlayed any existing LIBDEF definition while running within the scope of the
same application. A new keyword, STACK, on the LIBDEF service specifies that
the existing LIBDEF definition, if any, is to be saved prior to establishing the
newly defined LIBDEF definition.
The stacked LIBDEF definition will be restored when the new LIBDEF definition is
removed with a LIBDEF reset request.
One LIBDEF stack exists for all selected dialogs running within the scope of a
specific application ID.
A new LIBDEF stack is created for each successful SELECT NEWAPPL
service request. The current LIBDEF stack, if any, is not passed to the
selected dialog when a SELECT NEWAPPL PASSLIB service is requested.
Applications running in split screen under the same application ID will have
unique LIBDEF stacks.
A new interactive utility displays active and stacked LIBDEF definitions for the
current logical screen.

1.3.1.1 Command Procedure Format


ISPEXEC LIBDEF lib-type
[DATASET|EXCLDATA|
LIBRARY|EXCLLIBR]
[ID(dataset-list)ID(libname)]
[COND|UNCOND|STACK]
1.3.1.2 Call Format
CALL ISPEXEC (buf-len, buffer);
CALL ISPLINK ('LIBDEF',lib-type
[,'DATASET'|'EXCLDATA'|'LIBRARY'|'EXCLLIBR']
[,dataset-list|libname]
['COND'|'UNCOND'|'STACK'])

1.3.1.3 Usage
Description of Command Procedure and Call Parameters:
All Parameters except STACK exist in prior releases and are not changed by
the stack capability.
Stacking occurs even when there is no active LIBDEF definition for the
specified lib-type.
A null definition is stacked when there is no active LIBDEF definition.

This allows an application to issue a LIBDEF stack request for a


particular lib-type without knowing if an active LIBDEF definition currently
exists.
For example, it is valid to specify a LIBDEF definition for ISPPLIB and
request that the current ISPPLIB LIBDEF definition be stacked, even
when no current ISPPLIB LIBDEF exists. When the ISPPLIB LIBDEF

Chapter 1. Technical Overview

33

definition that requested stacking is removed, there will be no active


ISPPLIB LIBDEF definition in effect.
It is also valid to request stacking when resetting a particular LIBDEF
definition.
For example, it is valid to specify a reset of the ISPPLIB LIBDEF definition
and request that the current ISPPLIB definition be stacked, even when no
current ISPPLIB LIBDEF definition exists. A subsequent reset request of
the ISPPLIB LIBDEF definition will restore the previously stacked ISPPLIB
LIBDEF definition, including a restoration of a null definition.

The current LIBDEF return codes are:


0

Normal completion.

Application library does not exist for this type (when removing the
application library). This return code is not returned when removing a
null definition that stacked the previous LIBDEF definition. A return
code of 0 is returned in this case.

Application library already exists for this type (if COND is specified).

12

ISPPROF was specified as the lib-type or EXCLDATA or EXCLLIBR was


specified with lib-type other than ISPXLIB or ISPLLIB.

16

A libname was not allocated, or the data set list contains an invalid name.

20

A severe error.
Note

Stacked LIBDEF definitions are not unallocated. Sufficient dynamic ddnames


must be available from TSO for all LIBDEF definitions requiring them,
including those that are stacked.

1.3.1.4 Examples
Four LIBDEF commands are executed in the following example:

ISPEXEC
ISPEXEC
ISPEXEC
ISPEXEC

LIBDEF
LIBDEF
LIBDEF
LIBDEF

ISPPLIB
ISPPLIB STACK
ISPPLIB DATASET ID ('ISPFPROJ.LWG.PANELS') STACK
ISPPLIB DATASET ID ('ISPFPROJ.LWGMVS33.PANELS') STACK

1. The first LIBDEF resets the ISPPLIB LIBDEF definition. This is considered a
null definition for ISPPLIB.
2. The second LIBDEF stacks the previous null definition for ISPPLIB and
resets the ISPPLIB LIBDEF definition. This is the second null definition for
ISPPLIB.
3. The third LIBDEF stacks the previous null definition for ISPPLIB and
establishes the ISPPLIB definition for dataset ISPFPROJ.LWG.PANELS.
4. The fourth LIBDEF stacks the previous ISPPLIB definition for dataset
ISPFPROJ.LWG.PANELS and establishes the ISPPLIB definition for dataset
ISPFPROJ.LWGMVS33.PANELS.
In the following example, assuming the preceding LIBDEF ISPPLIB services have
been issued, the following four LIBDEF service calls have the following results.

34

ISPF/SCLM V4 Guide

ISPEXEC LIBDEF ISPPLIB


(restores ISPFPROJ.LWG.PANELS)
Return Code = 0

ISPEXEC LIBDEF ISPPLIB


(restores stacked null
definition)
Return Code = 0

ISPEXEC LIBDEF ISPPLIB


(restores stacked null
definition)
Return Code = 0

ISPEXEC LIBDEF ISPPLIB


Return Code = 4

1. The first LIBDEF reset restores the ISPPLIB definition for dataset
ISPFPROJ.LWG.PANELS.
2. The second LIBDEF reset restores the stacked null definition for ISPPLIB.
This is the null definition which issued the keyword, STACK.
3. The third LIBDEF restores the stacked null definition. This is the null
definition which did not issue the keyword, STACK.
4. The fourth LIBDEF receives a return code of 4 because there is nothing in the
stack and there is no active ISPPLIB definition.

1.3.2 Dialog Query LIBDEF Facility


In previous versions of ISPF, LIBDEF definitions established by a previous dialog
could have been lost when the current dialog established its LIBDEF definitions.
In ISPF V4.1 a Dialog Query LIBDEF Utility allows LIBDEF definition information to
be queried. This allows LIBDEF definition integrity to be maintained across
independently developed dialogs.
This new dialog service, QLIBDEF, allows an ISPF dialog to obtain the current
LIBDEF definition information. This information can be saved by the dialog and
used later to restore any LIBDEF definitions that may have been overlayed.

1.3.2.1 Command Procedure Format


ISPEXEC QLIBDEF lib-type,
[TYPE(type-var)],
[ID(id-var)]
1.3.2.2 Call Format
CALL ISPEXEC (buf-len, buffer)
CALL ISPLINK ('QLIBDEF',lib-type,
[,type-var],
[,id-var])

Chapter 1. Technical Overview

35

1.3.2.3 Usage
Description of Command Procedure and Call Parameters
lib-type Specifies the LIBDEF lib-type definition that is being queried.
ISPPLIB
ISPMLIB
ISPSLIB
ISPTLIB
ISPLLIB
ISPTABL
ISPFILE
or a generic name
type-var Optional parameter that specifies the name of a dialog variable which is
to contain the type of LIBDEF definition.
The possible values returned are:
DATASET
EXCLDATA
LIBRARY
EXCLLIBR
id-var

Optional parameter that specifies the name of a dialog variable which is


to contain ID information.
It is set to the ddname or data set name that was specified on the last
active LIBDEF service.

1.3.2.4 Hints and Tips


Although not mandatory, it is suggested that the service interface (ISPLINK
or ISPEXEC) used by the QLIBDEF be the same as that used on the LIBDEF
service to restore the definition. This eliminates the need to adjust the
syntax of the information returned by QLIBDEF.
type-var (optional parameter)
The variable is not modified if there is no LIBDEF in effect. It is the
responsibility of the dialog developer to initialize the variable.
id-var (optional parameter)
The variable is not modified if there is no LIBDEF in effect. It is the
responsibility of the dialog developer to initialize this variable.

1.3.3 LIBDEF Display Utility


This utility allows you to display all active and stacked LIBDEF definitions for the
current logical screen in a scrollable list.
For each LIBDEF definition displayed, the following information is provided:
Stack Indicator
An S is displayed to the left of the library name when a stacked LIBDEF
definition is present.
Library
Type
ISPxUSR indicator (for type DATASET only)
Identification

36

ISPF/SCLM V4 Guide

For type DATASET/EXCLDATA, this column contains the data set name. The
associated ISPxUSR data set name is shown when the respective ddname is
allocated.
For type LIBRARY/EXCLLIBR, this column contains the library name
(ddname) followed by the first or only allocated data set name.

1.3.3.1 Usage
A new ISPF command, ISPLIBD, invokes the LIBDEF Display Utility. This
command may be issued from the command line of any panel.
Format
ISPLIBD [ libtype]
libtype

This optional parameter identifies a specific LIBDEF library


definition to be displayed.

Examples
ISPLIBD ISPPLIB Displays the current LIBDEF definition for ISPPLIB.
ISPLIBD

Displays all current LIBDEF definitions for the current


logical screen.

Locate Command

The LIBDEF Display Utility supports the use of a LOCATE command.


It is used to locate a specific LIBDEF library name.
Two command abbreviations, LOC and L, are also supported.
LOCATE ISPPLIB locates the LIBDEF definition for ISPPLIB.

Note
The LIBDEF Display Utility may not be executed recursively within the same
logical screen.

1.3.4 LIBDEF Search Order for ISPLLIB


In ISPF V4.1 the search order has changed for ISPLLIB. The select PGM(xxx)
has been changed to use BLDL to look for a load module prior to issuing the
LINK macro. This will allow modules to be found in STEPLIB or the original
ISPLLIB prior to searching the link pack area or the link list when a LIBDEF for
ISPLLIB is active. This will result in a logical search order of:
1.
2.
3.
4.
5.
6.
7.

Job Pack Area


LIBDEF's ISPPLIB DCB
TASKLIB
STEPLIB
JOBLIB
Link Pack Area
LINKLIST

1.4 Graphical User Interface (GUI) Applications with ISPF


There is a new tool for writing OS/2 Presentation Manager and Windows
applications called ISPF Client/Server, and it is available in ISPF V4.1. ISPF C/S
provides display capability for both OS/2 and Microsoft Windows workstations.
The application runs on the MVS mainframe, but is displayed at the workstation,
using TCP/IP or APPC communications.
Chapter 1. Technical Overview

37

There are new functions in ISPF V4.1 and some already existing functions from
previous releases of ISPF that produce an application that looks more like one
written specifically for the workstation using traditional programming techniques,
such as C programming. The functions and how to apply them to existing
applications are discussed in 4.8, ISPF GUI Applications on page 121.

38

ISPF/SCLM V4 Guide

Chapter 2. User Interface


ISPF Version 4 Release 1 provides an action-bar driven interface that exploits
many of the usability features of Common User Access* (CUA)* interfaces. It is
IBM's commitment to further enhance GUI mode that was the reason behind the
interface.
This chapter discusses all the new user interfaces available or those being
further exploited in ISPF Version 4 Release 1.
Many of the discussed interfaces are not new to ISPF. For example, keylists,
color usage, and action bars with the associated pull-down windows were
already available in Version 3. They were, however, not generally used in ISPF
itself.
In Version 4 these features are the norm, so by being constantly exposed to
them it won't be long before you get accustomed. As a consequence of this, a
discussion about these facilities is warranted for this version of ISPF.
The ISPF client/server interface enables a panel to be displayed at a workstation
using the native display function of the operating system at the workstation. A
detailed discussion about GUI will be covered in Chapter 4, Graphical User
Interface (GUI) on page 97.

2.1 Action Bar


The action bar is the panel element situated at the top of the application panel
which contains action bar choices for that panel. Each action bar choice
represents a group of related choices which appear in the pull-down associated
with the action bar choice. Pull-downs contain choices that, when selected,
perform the actions that apply to the contents of the panel.

2.1.1 How are the Action Bars Constructed?


The Dialog Tag Language (DTL) tag definitions for creating an action bar and its
pull-down menus are :
AB

To start an action bar definition. The required AB end tag ends an


action bar definition.

ABC

To define each of the action bar choices.

PDC

To define the choice on the pull-down associated with an action bar


choice.

ACTION To specify an action to be taken when the pull-down choice is selected.


The ACTION tag is coded within the PDC tag.
M

To specify a mnemonic character for action bar choices or pull-down


menu choice selection.

To code an action bar definition:


The AB start tag is coded immediately after the PANEL start tag and before
any other tags in the panel.

Copyright IBM Corp. 1994

39

Following the AB start tag, the ABC tag is coded for each action bar choice.
The text specified on ABC tag is the text that appears in the action bar as
the action bar choice.
.Within the ABC tags, the associated PDC tag is coded. The text specified on
the PDC tag is the text that appears as the pull-down choice.
Following each PDC tag, the ACTION tag is coded to specify what type of
action occurs when that pull-down choice is selected.
The required AB end tag should be coded to end the action bar definition.
The following example shows the markup for the ISPF Primary Option Menu
action bars shown in Figure 32 on page 41. The detailed markup for the
Menu pull-down is included.

<:-- ISR@PRIM selection menu -->


<panel name=isr@prim help=isr00003 padc=user keylist=isrsab
width=80 depth=24 menu prime window=no>
ISPF Primary Option Menu
<ab mnemgen=yes>
<abc pdcvar=isr@opt>Menu
<pdc unavail=zpm1>Settings
<action run=ISRROUTE parm=SET>
<pdc unavail=zpm2>View
<action run=ISRROUTE parm=BR1>
<pdc unavail=zpm3>Edit
<action run=ISRROUTE parm=ED1>
<pdc unavail=zpm4>ISPF Command Shell
<action run=ISRROUTE parm=C1>
<pdc unavail=zpm5>Dialog Test...
<action run=ISRROUTE parm=DAL>
<pdc unavail=zpm6>Other IBM Products...
<action run=ISRROUTE parm=OIB>
<pdc unavail=zpm7>SCLM
<action run=ISRROUTE parm=SCL>
<pdc unavail=zpmS>Status Area...
<action run=ISRROUTE parm=SAM>
<pdc>Exit
<action run=EXIT>
</abc>
<abc pdcvar=pdfutil>Utilities
..
.
<abc pdcvar=isrlang>Compilers
..
.
<abc pdcvar=pdfoptm>Options
..
.
<abc pdcvar=pdfsta>Status
..
.
<abc pdcvar=primhelp>Help
..
.
</ab>
..
.
</panel>

40

ISPF/SCLM V4 Guide

Notes:
1. The MNEMGEN=YES|NO attribute controls the automatic generation of
mnemonic characters for the entire action bar.
2. The PDCVAR=pdc-variable-name variable attribute provides the name of a
variable to contain the value of the pull-down choice. When a variable name
is provided, it replaces the default ZPDC variable name.
3. The UNAVAIL=unavail-variable-name attribute specifies the name of a
variable that is used by ISPF to determine the availability of the pull-down
choice. When the variable value is 1, the pull-down choice is unavailable.

Figure 32. ISPF Primary Option Menu

2.1.2 Customizing Action Bars


The action bar is always located at the top of the application panel, it is tab-able
and point & shoot-able. We can make them non-tab-able simply by:
Entering command ISPFVAR ABTAB(OFF) on the command line, or
De-select options Tab to action bar choices in ISPF Settings panel as
shown in Figure 33 on page 42.
The ISPF Settings panel can be invoked from any command line with the
SETTINGS command, or from the Settings choice on the Menu pull-down on any
action bar where it is available, or by selecting option 0 on the ISPF Primary
Option Menu.
The consequence of making them non-tabable is that the Home key will not
send the cursor to the action bar. We will have to move it by other means, such
as a function key or the cursor movement keys (see 2.2, Keylists on page 48
for more information on setting the function key) or simply not use action bars at
all.

Chapter 2. User Interface

41

Figure 33. ISPF Settings Panel (ISPISMMN)

2.1.2.1 Removing Action Bars


All ISPF panels that are shipped with the Dialog Tag Language (DTL) source can
be recompiled to remove the action bars. Since the panel, without an action bar,
becomes simpler in structure, it also costs less system resources to process
(that is, display and read at enter). However, the possibility of navigating to
other ISPF functions through the action bar, also has elements of resource
savings; for example, you don't give up the present function to perform another
function for then later to re-enter the aborted function. The net result is probably
even when it comes to system resources; when it comes to human resources,
the more possibilities that exist the easier it will be for the individual to find a
way of working with ISPF that suits him or her the most. There are two ways to
recompile the DTL source:
1. Running the ISPDTLC Conversion Utility Interactively:
Invoke the conversion utility from any command line by entering:

ISPDTLC (NOACTBAR
Note: There is no invocation panel option which is equivalent to the
ACTBAR/NOACTBAR invocation options. ACTBAR is the default. If we
specify as the above, the NOACTBAR option will be active when the
interactive panel is displayed. This option is not saved in your user
profile. It must be specified each time the conversion utility is invoked.
Figure 34 on page 43 shows the first screen of the ISPDTLC invocation
panel with the default data set names and with the required options
selected.
Fill in the member name with ISPFALL which will cause all panels to be
converted. Fill in the name of your input and output files where
indicated. The first DTL source file contains the product panel source.
The second DTL source file contains the conversion list of all panels.

42

ISPF/SCLM V4 Guide

Enter ISR as the Keylist Application ID and select the options as shown
in Figure 35 on page 43 and Figure 36 on page 44.
The converted files will be in your.output.panel.dataset, and the message
generated will be in your.log.dataset.
The log file will report the result of the conversion process. Most of the
messages generated by ISPDTLC are related to ISPF extensions to the
Dialog Tag Language and have been suppressed. The expected message
number from compiling the panel source will appear in a comment near the
top of the DTL source file for that panel source.

Figure 34. First ISPDTLC Screen

Figure 35. Second ISPDTLC Screen

Chapter 2. User Interface

43

Figure 36. Third ISPDTLC Screen

2. Using Conversion Utility Command Syntax:


You can also use the syntax below to recompile all panels :

ISPDTLC ISPFALL (DISK KEYAPPL=ISR MSGSUPP CUAATTR CUASUPP


NOSTATS NOACTBAR PROFILE=your.profile.dataset
ISPFALL is a list of all the panels to converted. It is destributed as a
member of SISPSAMP. When it is concatenated to the DTL input data set, all
panels are converted, when ISPFALL is specified for conversion.
The keyword value your.profile.dataset can specify either a sequential or
partitioned data set, and controls the allocation of input and output data sets
to the conversion utility. It contains a list of keywords and corresponding
data set names. The list is read by the utility and allocation is performed as
indicated by the keywords. For example, the keyword DTLGML (see the list
below) indicate the DTL input data set. Two or more DTLGML definitions
indicate concatenation, som for this type of conversion, where the ISPFALL
list is in SAMPLIB, it is necessary to have two definitions of DTLGML.
If the profile is part of a partitioned data set, then the member name, of
course, must be included. A sample profile member, ISPDTLP, is shipped in
the ISPSLIB skeleton library, and can be used as a model for your own
specifications.
The data set your.profile.dataset should include:
DTLGML
DTLGML
DTLPAN
DTLMSG
DTLTAB
DTLLOG
DTLLIST

ISP.ISPF410.SISPGENU
ISP.ISPF410.SISPSAMP
your.output.panel.dataset
your.output.message.dataset
your.output.table.dataset
your.log.dataset (optional)
your.llist.dataset (optional)

Note: A few of the product panels (e.g. ISPF Settings panel) REQUIRE action
bars for proper operation. The creation of action bars is made even though the
invocation option is NOACTBAR.

44

ISPF/SCLM V4 Guide

You may want to disable the use of action bars only in the editor to provide
more space on the screen. Yo can remove action bars from the editor by
issuing the HILITE DISABLED command. But the consequence is, that it also turns
off the availability of extended color HILITE (see 2.5.2, Edit Hilite on page 72 for
more information).
To accommodate the HILITE features with no action bars, an unsupported load
module called ABAR can be used to turn on/off action bars in the ISPF editor.
ABAR will turn action bars on if they are off, and off if they are on.
To execute ABAR, type TSO ABAR on any ISPF command line, this will affect all
future edit sessions only, or use ABAR as an edit macro by typing !ABAR on any
edit command line, this will affect both the current and all future edit sessions.
Note: If you have already used the value DFLTCOLR=4 in the ISPF/PDF
configuration table, ABAR will not enable action bars. For more information, see
5.1, Modifying ISPF Configuration Table (ISRCNFIG) on page 147.
ABAR is only available from an internal IBM tools disk. Please contact your
local IBM support group for availability of this load module.
Warning: Should this module be made available, please understand, that since it
is not supported, no guarantee is provided that it may work in future releases, or
after applied maintenance. It may even malfunction.

Figure 37. ISPF Editor with Action Bars OFF

2.1.2.2 Changing Action Bars


Many ISPF action bar items are common to multiple panels. These action bar
definitions are coded in separate files which are imbedded into the various
panels. The imbedded DTL source fields are in GML, as part of the DTL panel
source.

Chapter 2. User Interface

45

To change action bar items:


1. Copy action bar file imbed member (as shown in Table 1) to
your.appl.gml.dataset and modify.
2. Reconvert the affected panels by specifying the appropriate list of members
(Table 1).
Invoke the conversion utility either interactively by specifying ISPDTLC or
using the conversion utility syntax :

ISPDTLC ISPxxxx (DISK KEYAPPL=ISR MSGUSPP CUAATTR


CUASUPP NOSTATS NOACTBAR PROFILE=your.profile.dataset
Table 1. DTL List of Panels and Imbedded DTL Source Files
Panel Lists,
SISPSAMP

Imbedded
Source File

Affected Type of Panels

ISPFIL1

ISPDFIL1

File Action Bar Choice

ISPFUNC

ISPDFUNC

Function Action Bar Choice

ISPHUCM

ISPDHUCM

Help Action Bar Choice (opt 3.9)

ISPHYXM

ISPDHYXM

Help Action Bar Choice (opt 7)

ISPJOBC

ISPDJOBC

Jobcard Action Bar Choice

ISPLANG

ISPDLANG

Compilers Action Bar Choice

ISPMENU

ISPDMENU

ISPF Menu Action Bar Choice

ISPMENU1

ISPDMENU

SCLM Menu Action Bar Choice

ISPREFE

ISPDREFE

RefMode Action Bar Choice (Edit)

ISPREFL

ISPDREFL

RefList Action Bar Choice

ISPREFM

ISPDREFM

RefMode Action Bar Choice (Browse)

ISPSAVE

ISPDSAVE

Save Action Bar Choice

ISPTEST

ISPDTEST

Test Action Bar Choice

ISPUTIL

ISPDUTIL

Utilities Action Bar Choice

ISPSCLM

ISPFSCLM

All SCLM panels with Action Bar

The list of panels are shipped in SISPSAMP.


3. Specify your.appl.gml.dataset ahead of product libraries in ISPDTLC DTL
source file on the ISPDTLC Conversion Utility panel.
If you use the conversion utility command syntax, you should specify your
your.profile.dataset in the following way, (for reference see conversion
utility profile for removing action bars on page 44):
DTLGML
DTLGML
DTLGML
DTLPAN
DTLMSG
DTLTAB
DTLLOG
DTLLIST

46

ISPF/SCLM V4 Guide

your.appl.gml.dataset.
ISP.ISPF410.SISPGENU
ISP.ISPF410.SISPSAMP
your.output.panel.dataset
your.output.message.dataset
your.output.table.dataset
your.log.dataset (optional)
your.list.dataset (optional)

If you wish to use the interactive conversion utility, see Figure 38, Figure 39,
and Figure 40 on page 48 for a more detailed specification.

Figure 38. First ISPDTLC Screen

Figure 39. Second ISPDTLC Screen

Chapter 2. User Interface

47

Figure 40. Third ISPDTLC Screen

2.2 Keylists
Key Mapping Lists (keylists) are tables located in the general table libraries of
ISPF. They percolate either into your profile data set or private table libraries.
There are two kinds of keylist tables that both relate to your current
application-ID. If that, for example, is ISP, you may find the following kinds of
keylists on your system:
Keylists as part of a table called ISPKEYS. This name is constructed from
the application-ID with the character string KEYS concatenated to it. Each
line in this table is one keylist, and the keylist name is in a keys variable of
that table.
Keylists as part of the application profile, such as ISPPROF. The structure of
the profile is a normal table. The table, ISPPROF in this case, has neither
keys nor names variables, only extension variables. The first row of the
table consists of the wellknown profile variables. The following rows each
contain a keylist.
Nearly all panels in ISPF 4.1 have associated keylists. There are a total of eight
keylists used across the ISP and ISR panels. The following keylists comprise the
table ISRKEYS, the keylist repository for application-ID ISR, also known as
member ISRKEYS in table library ISPTLIB. Not all these keylists are being used
at the moment.
ISPNAB
ISPTEST
ISPKYLST
ISPSNAB

ISPSAB
ISPHLP2
ISPHLP2
ISPHELP

ISNAB
ISRSPBC
ISRSPEC
ISRHELP

ISRSAB
ISRTEST
ISRSNAB
ISRNSAB

For application-ID ISP the following keylists, this time part of table ISPKEYS in
ISPTLIB, are found similar to ISRKEYS above:

48

ISPF/SCLM V4 Guide

ISPTEST
ISPNAB
ISPHLP2

ISPHELP
ISPSNAB
ISPSAB

There are various ways to modify these keylists, but they are basically saved in
two distinct places:
Using dialog under the SETTINGS command, which saves the modified keylists
in the application profile (for example in ISRPROF).
Using the command KEYLIST that with a few undocumented parameters bring
you directly into the keylist processing panels. As with the SETTINGS
command, the modified keylists are saved in the application profile.
Using DTL, where the modified keylists are saved in application tables (for
example ISRKEYS) in the table library allocated to DDname ISPTABL.

2.2.1 Using Dialog under SETTINGS


This section will describe in detail, how keylists can be modified using the dialog
under the SETTINGS umbrella. A fast path to the keylist utilities panels exists with
a few undocumented parameters to the KEYLIST command. To complete the
discussion about keylists, the self-explanatory syntax for this version of the
KEYLIST command is shown below.

KEYLIST CHANGE <appl-ID> <keylist name>


BROWSE
DELETE
CREATE
Otherwise, to create or change/modify the keylists, select the Keylist settings...
choice from the Function keys pull-down on the ISPF Settings panel action bar
(shown in Figure 41), or enter the KEYLIST command.

Figure 41. ISPF Settings Panel with Function Keys Pull-down

Chapter 2. User Interface

49

Figure 42 displays the first panel of the Keylist Utility.

Figure 42. Keylist Utility Panel (ISPKLUP)

If you are already in a keylist enabled panel, you will get the keylist change
panel for the keylist active on that panel after entering the KEYS command. For
example, if you are in the Edit Entry panel (ISREDM01) which use the ISRSAB
keylist, the change panel for Keylist ISRSAB in application ISR is displayed
immediately after having entered the KEYS command, (see Figure 46 on
page 53).
To create, change, browse, or delete a keylist:
1. Enter the name of the keylist in the input area provided on the Keylist Utility
panel, or use any character in the Select column to select a keylist.
2. Select the appropriate choice from the Functions pull-down as shown in
Figure 43 on page 51.
a. To create a keylist, select option 1 (Create) from the Function pull-down.
The screen shown in Figure 44 on page 51 is displayed.
The Defaults pull-down offers the choice of the five default key settings
described in Figure 45 on page 52 and explained in Table 2 on page 52.
Note: If you are creating a keylist on a terminal defined to have 24
keys, the 13-24 keys are the same as the 1-12 keys.
Save the keylist using the Save and Exit choice, or cancel the creation
using the Cancel choice in File pull-down.

50

ISPF/SCLM V4 Guide

Figure 43. Keylist Utility with Function Action Bar Pull-down (ISPKLUP)

Figure 44. Keylist Create Panel (ISPKLUCR)

Chapter 2. User Interface

51

Figure 45. Default Key Settings


Table 2 (Page 1 of 2). Default Key Settings

52

ISPF/SCLM V4 Guide

Condition

Key Setting

No defaults

No values are filled in.

Nonscrollable, no
action bar

The following values are set:

Scrollable,
no action bar

The following values are set:

Nonscrollable,
with action bar

The following values are set:

F1 HELP
F2 SPLIT
F3 EXIT
F9 SWAP
F12 CANCEL

F1 HELP
F2 SPLIT
F3 EXIT
F7 BACKWARD
F8 FORWARD
F9 SWAP
F12 CANCEL

F1 HELP
F2 SPLIT
F3 EXIT
F9 SWAP
F10 ACTIONS
F12 CANCEL

Table 2 (Page 2 of 2). Default Key Settings


Condition

Key Setting

Scrollable,
with action bar

The following values are set:


F1 HELP
F2 SPLIT
F3 EXIT
F7 BACKWARD
F8 FORWARD
F9 SWAP
F10 ACTIONS
F12 CANCEL

b. To change the key definitions, display formats, and labels for a keylist,
select option 2 (Change) from the Function pull-down. The screen shown
in Figure 46 is displayed, showing the existing values.

Figure 46. Keylist Change Panel (ISPKLUCH)

Row x to x of xx indicates that you must scroll the panel to access the
remaining label definitions.
Keylist Help Panel Name to refer to a help panel from this keylist.
Enter the help panel name in this field. To remove a help panel name
from a keylist, simply replace the help panel name with blanks.
Definition must also be specified if a display format or a label is
specified.
Format only valid in LONG (default), SHORT or NO. If you choose format
NO, the key label will never be displayed.
Label will appear in function keys area. Any label is valid.
Save the keylist using Save and Exit choice or cancel the creation
using Cancel choice in File pull-down.

Chapter 2. User Interface

53

c. To delete a keylist, select option 3 (Delete) from the Function pull-down.


The Delete Keylist Confirmation pop-up shown in Figure 47 on page 54
is displayed.

Figure 47. Keylist Utility with Delete Keylist Confirmation Pop-Up (ISPKLUP)

Note: You cannot delete a shared (S) keylist. Deleting a private copy
(P) keylist is valid only if the keylist is not in a currently active
application. This is done so that a panel will not receive an error
message because the keylist is not found.
d. To browse a keylist, select option 4 (Browse) from the Function
pull-down. The screen shown in Figure 48 is displayed.

Figure 48. Keylist Utility Browse Panel (ISPKLUB)

54

ISPF/SCLM V4 Guide

The help panel name, key definitions, display formats, and labels are
displayed but cannot be changed.
3. To work with another set of keys on the Keylist Utility panel, select Change
Keylist on the action bar. The Change Keylist pull-down is shown in
Figure 49.
The Change Keylists pull-down choices function as follows:
Current panel keylist Display the list of keys related to the current panel
Current dialog keylist Display the list of keys related to the dialog currently
running
Specify keylist

Display the list of keys for another application

Figure 49. Keylist Utility with Change Keylist Action Bar Pull-down (ISPKLUP)

2.2.2 Using DTL


The tags you use to define keylists are:
KEYL

To define a keylist. The required end tag ends the keylist definition.

KEYI

To define a key assignment and specify the command ISPF processes


when you press the key, and specify the label for the key if it is
displayed in the function key area.
You can code multiple KEYI tags within a KEYL definition. You code a
KEYI tag for each key that is defined for the keylist.

The KEYL tag starts a keylist definition and provides the name value (with the
required NAME attribute) that you specify with the KEYLIST attribute of the
PANEL or PANDEF tag.
Each KEYI definition within a keylist maps a key assignment with a command.
The command can be defined in the application command table or it can be one
of the ISPF-provided commands. The required KEY and CMD attributes of the
KEYI tag match the key with the command.

Chapter 2. User Interface

55

While all of the key assignments you define in a keylist are valid for the
application panels that refer to the list, they only appear in the function key area
(FKA) of the panel under the following conditions:
You specify that the key is to be displayed by including FKA=YES in the
KEYI tag, and
You have not turned off display of the function key area
The default of the FKA value is NO, which means that the key will not appear.
You must specify FKA=YES for the key to be displayed in the function key area.
Following is an example of DTL keylist definition. It is keylist ISRSAB found in
member ISRKYLST of the SISPGENU data set.

<!doctype dm system >


..
.
<keyl name=isrsab>
<keyi key=F1 cmd=help
<keyi key=F2 cmd=split
<keyi key=F3 cmd=exit
<keyi key=F7 cmd=backward
<keyi key=F8 cmd=forward
<keyi key=F9 cmd=swap
<keyi key=F10 cmd=actions
<keyi key=F12 cmd=cancel
<keyi key=F13 cmd=help
<keyi key=F14 cmd=split
<keyi key=F15 cmd=end
<keyi key=F16 cmd=return
<keyi key=F17 cmd=rfind
<keyi key=F18 cmd=rchange
<keyi key=F19 cmd=up
<keyi key=F20 cmd=down
<keyi key=F21 cmd=swap
<keyi key=F22 cmd=left
<keyi key=F23 cmd=right
<keyi key=F24 cmd=Cretriev
</keyl>
..
.

fka=yes>Help
fka=long>Split
fka=yes>Exit
fka=long>Backward
fka=long>Forward
fka=long>Swap
fka=yes>Actions
fka=yes>Cancel
fka=yes>Help
fka=long>Split
fka=yes>End
fka=yes>Return
fka=yes>Rfind
fka=yes>Rchange
fka=long>Up
fka=long>Down
fka=long>Swap
fka=yes>Left
fka=yes>Right
fka=yes>Cretriev

In the DTL panel definition of ISREDM01, the KEYLIST attribute is specified, as


follows:

<:-- ISREDM01 panel -->


..
.
<panel name=ISREDM01 keylist=isrsab
help=isr20000 width=80
depth=24 padc=user wintitle = 'Edit' window=no>Edit Entry Panel
..
.
</panel>

56

ISPF/SCLM V4 Guide

After you have finished marking up a source file, use the conversion utility to
convert it. After conversion, the elements you have defined are stored in the
specified ISPF libraries.
The panel display of ISREDM01 is shown in Figure 50.

Figure 50. ISREDM01 Panel

The keylist that will be used for the panel is be specified in the )PANEL section
in the panel definition. It also identifies where the keylist is to be found.
Following is the converted )PANEL statement for ISREDM01.

..
.
)PANEL KEYLIST(ISRSAB,ISR)
..
.
where:
ISRSAB is the keylist name.
ISR

is the keylist applid. This is the application ID used at run time to find
the keylist.

When a keylist is specified without a keylist applid, ISPF searches for the named
keylist in the following sequence:
1. Keylist for the currently executing application ID
2. Keylist for applid ISP
When a KEYLIST keyword is not found through the )PANEL statement, then the
default keylist, ISPKYLST, is used.
The key mappings for ISPKYLST are:

Chapter 2. User Interface

57

Key
F1
F2
F3
F9
F12
F13
F14
F15
F21
F24

Command
HELP
SPLIT
EXIT
SWAP
CANCEL
HELP
SPLIT
EXIT
SWAP
CANCEL

You can override the ISPF default keylist by specifying a KEYLIST attribute in the
panel definition. All keys that you want to be active, including those for
ISPF-provided commands, must be specified in the keylist referred to by the
KEYLIST attribute in )PANEL definition.

2.2.3 Global Function Keys Setting


As mentioned before, keylists are now used on almost all ISPF panels. The
Global Function Keys are not used unless you have issued the KEYLIST OFF
command, or if a panel does not have a )PANEL section. By specifying KEYLIST
OFF, you cause ISPF to ignore the keylist in all logical screens, and use ZPFnn
variables for controlling function keys. KEYLIST OFF is equivalent to the Disable
Keylist choice from the Function Keys pull-down on the ISPF Settings panel.
To change the global function keys, select the Global PF Key settings choice
from the Function keys pull-down on ISPF Settings panel action bar, or enter
the KEYS command after you entered the KEYLIST OFF command. The PF Key
Definitions and Labels panel is shown in Figure 51. It allows you to change the
ZPFnn variable settings, as in previous versions of ISPF.

Figure 51. PF Key Definitions and Labels Panel

58

ISPF/SCLM V4 Guide

You can define or change a function-key function simply by equating the key to a
command. If you enter a blank for any function key definition, the key is restored
to its ISPF default.
The label fields shown in Figure 51 on page 58 allow you to specify user-defined
labels for the displayed representations of function key definitions. If a label is
not assigned, the definitions displayed for that function key consist of the first
eight characters of the function key definition. No function key information
displays if the label value for that key is NOSHOW.

2.2.4 Function Key Display


2.2.4.1 Tailoring Function Key Definition Display
To accommodate both users who require CUA-compliant keylists and those who
prefer to use the traditional ISPF function key assignments, F1-F12 are assigned
CUA-compliant values, and F13-F24 are assigned traditional ISPF values.
Therefore, you can retain the traditional key settings.
Note: Function keys in Edit are not CUA-compliant and are documented in ISPF
Edit and Edit Macros.
The Tailor Function Key Definition Display panel (shown in Figure 52) allows you
to change the format of the function key definition lines that are displayed at the
bottom of the screen. To display this panel, select the Tailor function key
display choice from the Function keys pull-down, or issue the PFSHOW TAILOR
command from any command line.

Figure 52. Tailor Function Key Definition Display Panel (ISPOPFA)

From the Tailor Function Key Definition Display panel, you can set the following
function key parameters:
Number of keys
The number of function keys you specify controls the particular set of
function key definitions currently in use. For more information about
specification of terminal types, refer to ISPF User's Guide.
Chapter 2. User Interface

59

Keys per line


The number of keys per line to be displayed on the function key
definition lines can be altered. Six ensures consistency across all
panels. Maximum possible can save space on crowded panels. The
Maximum possible option is forced when you select the Panel display
CUA mode option on the ISPF Settings panel.
Primary range
The primary key range set to:
Lower

means primary keys are F1-F12 (default)

Upper

means primary keys are F13-F24

Display set
For terminals with 24 function keys, you can choose to display only the
primary keys, the alternate keys, or all 24 keys. Your choice depends
on which range you specify for the Primary range option. For terminals
with 12 function keys, this setting is ignored.

2.2.4.2 Display Function Keys in Different Forms


You can display the function keys in various forms. The forms are:
Long form displays the keys that have a format specified as either long or short
in the keylist. Long form is the default.
Short form displays only the keys that have the short format specified in the
keylist.
No display removes the keys from the display.
The form that you select affects all panels displayed in the session. The DM
component updates the system variable ZFKA to represent the current state of
the function key area form and saves the value in the system profile.
To display in long form, do one of the following:
Select the Show all function keys choice from the Function keys pull-down
on ISPF Settings panel action bar.
Enter the FKA ON command
Enter the PFSHOW ON command
To display in short form, do one of the following:
Select the Show partial function keys choice from the Function keys
pull-down on ISPF Settings panel action bar.
Enter the FKA SHORT command
To remove function keys from the display, do one of the following:
Select the Remove function keys display choice from the Function keys
pull-down on ISPF Settings panel action bar.
Enter the FKA OFF command
Enter the PFSHOW OFF command
Both PFSHOW and FKA commands (without operand) operate as toggles:
First time issued, long form function keys displayed.
Second time issued, short form function keys displayed.

60

ISPF/SCLM V4 Guide

Third time issued, no function keys displayed.


Fourth time issued, the display returns to the long form.
In GUI mode the function key labels are displayed on push buttons. A special
set of arguments, PREFIX/NOPREFIX, to the FKA command controls this push button
display. PREFIX prefixes the label with F = while NOPREFIX removes it.

2.3 Referral Lists


Referral lists (RefLists) are used to hold data set names entered on the various
ISPF panels. You may then subsequently select a data set name or name of a
library combination from the RefLists. Below are the four types of RefLists :
Reference Data Set List
Reference Library List
Personal Data Set List
Personal Library List
The Reference lists dynamically append the last 30 data sets referenced or the
last eight libraries referenced for later use. The Personal lists are named
Reference lists, that the user can create and save for later use. The Data
Set lists contain names of single data sets only and are targeted for the Other
Partitioned or Sequential Data Sets fields, whereas the Library lists contain
sets of library names to be entered into the Library fields.
Since Personal lists are named after the user own liking, multiple such lists
can exist for each user. To control these named lists, two additional lists exist:
Personal Data Set List Open
Personal Library List Open
These lists contain the names of the Personal lists that the user have created.
The idea is that data sets and libraries can be grouped according to the user's
work pattern.
The reflists can be accessed in two ways :
From the Reflist pull-down menu on the action bar of the View Entry, Edit
Entry, and most Utilities panels, as shown in Figure 53 on page 62.
Through the Command Interface (or Fast Path) described in 2.3.3, Fast Path
to the Referral List Function on page 66.
The Reference Data Set List or Reference Library List is automatically updated
whenever a data set or library is referenced, provided the Update On is
selected from the List pull-down menu. However, if it is set to Update off,
system overhead is slightly decreased.
The action taken after you select a data set or library from a list depends on how
you set the Referral List Mode (RefMode).
In List Execute Mode, the data set or library entries will be placed into
appropriate fields, and the Enter key is simulated.

Chapter 2. User Interface

61

Figure 53. Reflist Pull-down Menu

In List Retrieve Mode, the data set or library entries will be placed into
appropriate fields, but the Enter key is not simulated. Here, you can set other
options before you press Enter.
To set RefMode, just simply pull down the RefMode, menu as shown in
Figure 54 and set the mode. List Execute displays in blue (default) with an
asterisk at the first digit of the selection number (if you are running in GUI mode,
the choice will be in grey), which indicates that it is currently set to Execute.

Figure 54. Referral List Mode

62

ISPF/SCLM V4 Guide

2.3.1 Creating a Personal Data Set List


There are several ways to create personal lists:
Use an Empty List
1. Go to the Personal Data Set List panel by selecting Personal Data Set
List from the RefList pull-down menu.
2. Pull down the File menu, and select choice New, as on Figure 55.
Then an empty temporary list will be displayed.
3. Type in the data set names. The volume names are optional, if the data
set is catalogued, don't enter volume name.
4. Select the Save as... choice from the File pull-down menu. Assign a
unique name for this list.

Figure 55. Personal Data Set List Panel (ISRPDSNL)

Use the Reference Data Set List as a starting point:


1. Display the reference data set list by selecting Reference Data Set List
from the Reflist pull-down menu as shown in Figure 56 on page 64.
2. If you want to save the entire data set as a personal data list, select the
Save as... choice from the File pull-down menu, and give the list a
unique name.
3. If you only want to save some of them, modify this list by typing over the
data set names, or adding new ones. Then select the Save as...
choice from the File pull-down menu, and assign a unique name to the
list.

Chapter 2. User Interface

63

Figure 56. Reference Data Set List Panel (ISRDSNL)

Use an Existing List as a starting point.


1. Display an existing list:

Select Personal Data Set List Open from the RefList pull-down
menu. The menu shown on Figure 57 on page 65 will now be
displayed.

Select option Open (by typing 2 in period in the Action column) on


the chosen list.

2. Modify this list by typing over data set names or adding new ones. Do
not select any choices.
3. Save the list by:

Select the Save as... choice from the File pull-down menu and
assign a unique name to the list, if you want to save it under another
name.

Select the Save choice from the File pull-down menu, if you want
to save it under the same name.

Note: Besides using the choices in the File pull-down menu in your Personal
Data Set List or Personal Library panels, you can also work with these options
by selecting the point-and-shoot options or by entering an option number in the
File field and pressing Enter.

64

ISPF/SCLM V4 Guide

Figure 57. Reference Data Set List Open Panel (ISRPLTAB)

2.3.2 Shared List


You can share your list with other users by putting your personal list in DDname
ISPTLIB. It is then potentially a shared list because other users may allocate the
same library concatenated to their ISPTLIB allocation. Private data set lists are
kept in table ISRPLIST. Private library lists are kept in table ISRLLIST. Normally
both reside in the ISPPROF profile data set.
You can create a shared list simply by copying, using option 3.3 move/copy, an
existing personal list table to a data set concatenated to library ISPTLIB. Table
ISRRLIST (reference data set list) and ISRJLIST (reference library list) cannot be
used, since they are not named and are only accessed through the unshared
data set ISPPROF.
You can open a shared list and use it; you cannot update or delete it. You can
save it to a private list using Save As function available from the Personal
Data Set List panel (ISRPLTAB) and the Personal Library List panel (ISRLLTAB).
To use a shared list, set the personal list to system shared entries by selecting
the Toggle to Shared List choice from Option pull-down.
When the list has been toggled to shared lists, the following will occur:
Actions New, Update and Delete will be unavailable (prefixed by an asterisk)
from the main list dialogs.
Actions New, Save, Delete, and Sort (for data sets) action will be unavailable
on any selected list. The Update list description on the Function pull-down
will also be unavailable.
Active list name on the Personal Data Set Lists and Personal Library Lists
panels will be **None**.
If a toggle is attempted to a shared list but none are found, the profile list
(private) will be defaulted.
Chapter 2. User Interface

65

2.3.3 Fast Path to the Referral List Function


The following commands are used to access the referral list function rather than
using the action bar pull-down menu:
REFLISTD xx
Invoke the Reference Data Set List dialog, and retrieve the data set in
position xx on the list. xx is a number from 1-8 for direct entry
selection. For example:

REFLISTD 1
to retrieve the first data set from the data set reflist and place it in the
Other Partitioned or Sequential Data Set field.
REFLISTL xx
Invoke the Reference Library List dialog, and retrieve the library in
position xx of the list. xx is a number from 1-8 for direct entry selection.
For example:

REFLISTL 2
to retrieve the second data set from the library reflist and place it in the
ISPF Library field.
REFACTD nnnnnnnn xx
Invoke the Personal Data Set List dialog, and retrieve the data set in
list named nnnnnnnn in position xx of that list. xx is a number from 1-8
for direct entry selection. For example:

REFACTD MYLIST 2
to retrieve the second data set from the data set reflist and place it in
the Other Partitioned or Sequential Data Set field.
REFACTL nnnnnnnn xx
Invoke the Personal Library List dialog, and retrieve the library in list
named nnnnnnnn in position xx of that list. xx is a number from 1 -8 for
direct entry selection. For example:

REFACTL MYLIB 2
to retrieve the second data set from the library reflist and place it in the
ISPF Library field.
REFOPEND
Invoke the Personal Data Set List Open dialog.
REFOPENL
Invoke the Reference Library List Open dialog.
REFADDD nnnnnnnn
Update the personal data set list named nnnnnnnn with the most
recently referenced data set. For example, enter

REFADDD HERLIST
to add the most recently referenced data set to the personal data list
named HERLIST.
Note: If personal list HERLIST does not exist, it will be created. The list
name must begin with an alphabetic character, followed by any valid
alphanumeric character for a total length of up to eight characters.

66

ISPF/SCLM V4 Guide

REFADDL nnnnnnnn
Update the library list named nnnnnnnn with the most recently
referenced library. For example, enter

REFADDD HERLIB
to add the most recently referenced library to the library list named
HERLIB
Note: If personal list HERLIB does not exist, it will be created. The list
name must begin with an alphabetic character, followed by any valid
alphanumeric character for a total length of up to eight characters.
Type the command from the command line, and make sure you are already in a
reflist enabled panel. If you select a data set using the reflist from a panel that
is not enabled, ISPF will remember the entry selected, and when you enter a
reflist enabled panel, simply press enter, and the remembered entry will be
retrieved.

2.3.4 Function Keys for Accessing Referral Lists


An excellent way to use referral lists is define PF keys to retrieve list entries as
shown in Figure 58, (function keys 4, 5 and 6).

Figure 58. Defining Function Key to Issue Referral List Commands

To define the function key, see 2.2, Keylists on page 48.


If you are using the definition as shown in Figure 58 you could do the following:
Press F4 to place the first data set name on the personal data set list
named MYLIST in the Other Partitioned or Sequential Data Set field.
Press F5 to place the second data set name on the personal library named
MYLIB in the ISPF Library field.
Press F6 to display the personal data set list named MYLIST so that you
can select a data set to be processed. You could also type a number, xx, on
the Command line and press F6 to place the xxth data set name on the

Chapter 2. User Interface

67

personal data set list named MYLIST in the Other Partitioned or Sequential
Data Set field. For example, if you type 5 in the Command line and press
F6 the fifth data set on MYLIST would be retrieved.
If you press the function keys from a panel that is not keylist enabled, ISPF will
remember the entry selected. When you enter a reflist enabled panel, simply
press enter, and the remembered entry will be retrieved.
If you want to select an entry from a panel that is not keylist enabled, you can
use command chaining:

=2;REFACTD MYLIST 1;;;

(for view)

=1;REFACTD MYLIST 1;;;

(for edit)

=3;4;REFACTD MYLIST 2;;;

(for data set list utility)

in the Keylist Change Panel.


The ;;; simulates pressing the ENTER key when the ; is the command delimiter.
For example, to directly edit the member ISPFCH3 of data set LS40.ISPF.SCRIPT:
Make an entry in your personal data set list. In this example, enter 1 in
MYLIST personal data set list (shown in Figure 59) and save it. If it is
already defined in the list, use that existing entry.

Figure 59. Example of a Personal Data Set List

Define the function key as shown in Figure 60 on page 69.


Press F4 to directly edit member ISPFCH3 in data set LS40.ISPF.SCRIPT.
With PF keys set up this way, the use of use of referral lists can be extreemely
smooth.

68

ISPF/SCLM V4 Guide

Figure 60. Defining Function Key to Speed Up Selection Personal List Entry

Note: A word of warning is warranted on this place. Don't overreact when


defining entries in keylists. There aren't that many entries to use and most of
the destributed key definitions should not be removed. But usually the 1-12 and
13-24 ranges of keys definitions are duplicates and a good spot for personal key
definitions is in the range 13-24.

2.4 Point-and-Shoot Text Fields


Point-and-shoot text fields are cursor sensitive. See 1.2.1.5, Point & Shoot
Fields on page 9 for more information.
Basically, you activate a point-and-shoot field by placing the cursor on the field
and pressing the enter key. A point-and-shoot field can be tab-able which
means the tab key may be used to jump to a point-and-shoot field. This feature
is accomplished with the existing 3270 hardware capability by letting the
point-and-shoot fields be input fields.
However, if you are used to using the tab key to navigate through a set of input
fields then it is an added complexity to the panels and you might not like it.
Point-and-shoot fields may, however, be changed to noninput fields, but will then
lose their tabbing capability.
You may want to display these fields in a different color, intensity or highlight so
that they are easily spotted.

2.4.1.1 Changing to Noninput Fields


Change the point-and-shoot-field to noninput fields, simply by:
Enter command ISPFVAR PSTAB(OFF) in the command line, or
Deselect option Tab to point-and-shoot fields in ISPF setting panel as
shown in Figure 33 on page 42.

Chapter 2. User Interface

69

2.4.1.2 Changing Colors of Point-and-Shoot Fields


There are several ways to change attributes of the Point-and-Shoot fields.
However, they all go through the CUA Attribute Change Utility panel (shown in
Figure 61), where the color, intensity and highlighting of point-and-shoot fields
can be adjusted. This panel will be displayed by
Select SETTINGS either with the SETTINGS command, or by selecting the
Settings option on ISPF's primary panel or through the Menu pull-down.
Then pull down the Colors choice on the action bar and select either the
CUA attributes... or the Point-and-Shoot... choice. The only difference of
the two choices is the position of the point-and-shoot line amongst the
various field attribute definitions. Selecting Point-and-Shoot... is the
easiest since the definition is on to of the displayed list (Figure 61).
Navigating to this panel is easiest when the PSCOLOR command is used, it
brings you directly to the right panel. But of course, one has to remember
the command.

Figure 61. CUA Attribute Change Utility Panel Positioned on the Point-Shoot Panel
Element (ISPOPT1X)

Any of the three attributes can now be changed simply by typing over the
existing values. The changes are reflected on the next panel displayed after you
exit this panel. The valid change values are shown in Table 3.
Table 3. Valid Point-and-Shoot Change Values

70

ISPF/SCLM V4 Guide

Color Choices

Intensity Choices

Highlight Choices

RED
PINK
GREEN
YELLOW
BLUE
TURQ
WHITE

HIGH
LOW

NONE
BLINK
REVERSE
USCORE

2.5 Color Usage


Colors are being used extensively throughout ISPF. They can be changed
according to the individual user's liking and often enabled or disabled if so
desired. A new area of usage is entered with ISPF Version 4 Release 1 in that
colors (and other field attributes) are now used in a way to support program
structure and logic. This section discusses this and other use of colors in ISPF.

2.5.1 Colors Pull-down


ISPF Version 4 Release 1 provides the Colors pull-down from the ISPF Settings
panels to access to the Global Color Change Utility, and the ISPF CUA Attribute
Change Utility, formerly options 0.10 and 0.11, respectively, along with the Global
GUI Color Change Utility and Point-and-shoot Color Change panel.
The Global Color Change Utility and ISPF CUA Attribute Change Utility operate
much as they have in previous releases of ISPF. However, there are three new
capabilities in the ISPF CUA Attribute Change Utility:
Point-and-shoot
See 2.4.1.2, Changing Colors of Point-and-Shoot Fields on page 70 for more
information.
Active Window Frame
Identifies the window that is currently active. For example, the box of pull-down
menu on an action bar.
PD Unavailable
Identifies the pull-down choices that are unavailable.
The Global GUI Color Change Utility allows you to globally change the current
colors ISPF uses for display on the workstation. See 4.6.1.8, GUI Colors on
page 119 for more information.
Figure 62 shows the Colors pull-down.

Figure 62. Colors Pull-down on the ISPF Settings Panel Action Bar (ISPISMMN)

Chapter 2. User Interface

71

2.5.2 Edit Hilite


A new edit primary command and macro has been added as a productivity aid
for editing program source. Hilite or hi or highlight provides some coloring
enhancement which is also useful for editing data other than program source.
These enhancements are available for Assembler, PL/I, Pascal, C, COBOL,
BookMaster, ISPF Panels, ISPF Skeletons, REXX, DTL, JCL and others. Coloring
may also be used with languages which are similar to these. The ISPF editor
changes the colors of:
Keywords for each individual language
Comments
Quoted Strings (using both single and double quotes)
Compiler Directives (C, PL/I and Pascal only)
Special Characters which you choose
The default edit color and new characters you type in
Highlighting can be used to match logical blocks (such as DO/END in PL/I style
languages and { } in C). This is very useful for finding matching or mismatched
block delimiters.
Highlighting can also be used to match IF and ELSE statements for C and PL/I
type languages. This is useful for finding matching or mismatched ELSE
statements.
You can also use highlighting to match up parenthesis and find unmatched right
parenthesis.
In addition, you can also highlight the phrase containing the cursor and strings
which match the last FIND or CHANGE command you entered.
Note:
1. Highlighting is not available for edit sessions that involve:
Data sets with record lengths greater than 255
Mixed mode edit sessions (normally used when editing DBCS data)
Formatted data
2. Highlighting feature is an ISPF installation option and may not be available
on your system. For information on enabling this feature, see ISPF Planning
and Customizing.

2.5.2.1 Enhanced Edit Coloring


Language Highlighting: In many cases, the ISPF editor can determine the
language of the file you are editing. If you want to override the automatic
language determination, specify the language you want on the HILITE command.
See 1.2.5, Color Usage on page 15 for more information. You can use the edit
PROFILE command to see the coloring status. If a language was explicitly
selected, the language will be highlighted in RED on profile line 5. Otherwise it
will be WHITE.

72

ISPF/SCLM V4 Guide

HI AUTO selects a language based on the first nonblank line, and in some cases,
the last qualifier of the data set name. For more information on rules for
automatic language recognition, refer to ISPF Edit and Edit Macros.
ISPF also recognizes the comment types for each language. See ISPF Edit and
Edit Macros for comment types supported.
Parenthesis and Logic Highlighting: Parenthesis matching works by showing
matching parenthesis in the same color. Mismatched right parenthesis are
displayed in reverse video pink (to make them stand out). Parenthesis matching
is enabled and disabled with the HI PAREN command.
Logical block matching works by showing the beginning and ending keywords of
a block in matching colors. It is intended to be used with a range of PL/I type
languages such as CLIST, REXX, and Pascal as well as with C, ISPF Skeletons,
BookMaster, and Assembler, to name a few. Logical block matching is enabled
with the HI LOGIC and HI DOLOGIC commands.
IF/ELSE matching shows the word IF and its matching ELSE in the same color. It
is available for C, and the PL/I style languages. IF/ELSE matching is enabled
with the HI LOGIC and HI IFLOGIC commands.
If logical highlighting is not supported for a language, the HILITE LOGIC
command is ignored. The maximum IF/ELSE indentation supported is 255.
Unmatched ENDs or ELSEs are highlighted in reverse video pink to make them
stand out.
To find the first mismatched END or ELSE in the file, enable logic highlighting,
scroll to the bottom of the file and type HI SEARCH on the command line.
FIND and Cursor Highlighting: When FIND highlighting is enabled, any string
which the FIND or CHANGE command would locate is highlighted.
Only the following string qualifiers are recognized by highlighting:
Character strings (C'...' - case insensitive and the default)
Text strings (T'...' - case sensitive)
Hex strings (X'...' - only displayable characters are highlighted)
WORD, PREFIX, and SUFFIX
Boundaries specified on the FIND command
Notes:
1. Picture strings (P'...') are not highlighted.
2. Line labels are ignored when highlighting FIND strings.
Because FIND highlighting is not quite as robust as the FIND command itself, the
editor may highlight more occurrences of the string than FIND would actually
locate.
CURSOR highlighting works by highlighting the phrase that contains the cursor.
Highlighting is done from the previous blank to the following blank (similar to the
way that BROWSE does cursor highlighting).

Chapter 2. User Interface

73

2.5.2.2 Language Processing Limitation


Because the PDF component does not provide true parsing, the built-in language
scanner does not operate as a syntax checker. Keywords or built-in function
names that are used as variables, therefore not used in a language context, will
be highlighted as keywords. For example, in context sensitive languages, such
as REXX, the word WORD may be used as a variable name. It will be treated
as a keyword in all cases, both for highlighting and logic determination.
Special characters can be highlighted for each specific language. Specific
keywords may not be highlighted for each specific language. See ISPF Edit and
Edit Macros for more information.

2.5.2.3 Turning off the Highlight Features


Using highlight features requires an extra amount of CPU time. To minimize this
amount, highlighting attributes are only set for the data that is displayed.
However, before each screen image is being displayed, the entire in-storage
copy of the file is scaned for any structure for which the HILITE command was
issued to highlight. The amount of CPU time required by the highlight facility is
of course larger the larger the file is.
To turn off the highlight functions, enter one of the following commands in the
edit command line:

HI OFF
It will turn off the coloring, but cursor and FIND highlighting will still function.

HI DISABLED
It will turn off all HILITE features and removes all action bars. This benefits
performance at the expense of function. Since disabled status is not
restored in the edit profile, you must re-enter the operand every time you
enter the editor.
Note:
If you want to turn the HILITE features on after entering HI DISABLED, you could
do either of two things; exit from the editor or enter the HI ON command.
Entering HI ON after HI DISABLED may bring a PARAMETER IGNORED message
and the HI ON still remains in the Edit command line. Press ENTER and it will
be back to normal.

2.5.2.4 The HILITE Command/Dialog


HILITE functions can be accessed through dialog or HILITE command. The
HILITE dialog enables you to do the following:
Specify a specific language to be used for coloring or enable automatic
language detection
Assign colors for different language elements on a language-by-language
basis or all languages at once
Enable or disable logic or parenthesis matching
Enable or disable FIND coloring and assign the color for FIND highlighting
Enable or disable cursor coloring and assign the color for cursor phrase
highlighting
Specify special symbols to be highlighted on a language-by-language basis
View keyword lists for each language

74

ISPF/SCLM V4 Guide

Note: Keyword lists and default highlighted symbols for each language are
supplied by IBM. A facility that involves assembly and link editing of an
installation-modified keyword or symbol list does exist to add and remove
keywords. IBM does not supply facilities for adding additional languages.
The keyword and symbol lists and directions for changing them are in
member ISRPXASM in the SAMPLIB library.
The detailed definition of HILITE commands and an example using HILITE dialog
are provided in 1.2.5, Color Usage on page 15.

2.6 Status Area


The status area on ISPF Primary Option Menu (the right-most 21 columns) is now
a dynamic area that allows you to choose what status you want to display.
The options are:
1.
2.
3.
4.
5.
6.

Session
Function keys
Calendar
User Status
User point-and-shoot
None

To display one of the above options, select it from the Status pull-down as shown
in Figure 63.

Figure 63. Status Pull-down on the ISPF Primary Option Menu

Note: The current setting will be shown as an unavailable choice; that is, it will
display in blue (default) with an asterisk as the first digit of the selection number.
If you running in GUI mode, the choice will be in grey.

Chapter 2. User Interface

75

2.6.1 Session and Function Keys Status


Session status and Function Keys status display the system current settings as
shown in Figure 64 and Figure 65, respectively.

Figure 64. ISPF Primary Option Menu Status Area - Session View

MVS Acct and Release are point-and-shoot fields (shown in Figure 64). Select
these fields to display pop-up windows that contain additional information about
the MVS account number and the ISPF environment.

Figure 65. ISPF Primary Option Menu Status Area - Function Keys View

76

ISPF/SCLM V4 Guide

2.6.2 Calendar
The calendar view (shown in Figure 66) displays the current month in the status
area. You can also activate the note-pad facility for the selected date.

Figure 66. ISPF Primary Option Menu Status Area - Calendar View

All the fields on the calendar are point-and-shoot fields that can be used to
define and manipulate the calendar display:
1. To display the year:
Point to the Year field to get the Calendar Year pop-up that allows you
to specify the year to be displayed.
2. To display the months, do one of the following:
Point to the < , Calendar, or > field to display the previous,
current, and next month, respectively.
Point to the Month, and you get the Calendar Month pop-up that allows
you to specify the month to be displayed.
3. To define the start day:
Point to the Day field to get the Calendar Start Day pop-up that allows
you to specify Saturday, Sunday, or Monday as the start day for the
calendar.
You can also display the Calendar Start Day pop-up by:

Selecting the Status Area... from the Menu pull-down to get the
ISPF status pop-up window.

Then select the Calendar start day... from the the Options action
bar choice (shown in Figure 67 on page 78).

Chapter 2. User Interface

77

Figure 67. Option Pull-down on the ISPF Status Pop-Up Window

4. To display the Julian date and a note pad:


Point to the Date field to get the Julian Date pop-up that provides the
Julian date for the date selected. If you activate the note pad, you also
get a to-do list or yellow sticker for the date selected as shown in
Figure 68. Figure 68).

Figure 68. ISPF Calendar Note Pad panel (ISPCALNP)

Note: Once the data has been saved on the note pad, the date will be
displayed in reverse video to indicate that a note-pad entry exists. You

78

ISPF/SCLM V4 Guide

may change or delete the data by selecting an action from the File
action bar choice, or you may change the color by selecting Change
note color... from the Options action bar choice on the Note Pad panel
(displayed on
To activate the note-pad facility, do the following:

Select Dialog test... from Menu pull-down.

Select the Variables option from the Dialog Test panel

Add a variable named ZKIT to be located in the profile variable pool


(P) and give it the value LO (shown in Figure 69).

Figure 69. Variables Panel (ISPYVPN)

5. To define the time format:


Point to the Time field to get the Calendar Time Format pop-up that
allows you to specify a 12-hour or 24-hour time format for the calendar.
6. To display the standard date:
Point to the Day of the year field to get the Standard Date pop-up that
provides you the standard date for the date you specified.
You can change colors on the calendar by:
Selecting the Status Area... from the Menu pull-down to get the ISPF status
pop-up window (shown in Figure 67 on page 78).
Then select Calendar Colors... from the Options action bar choice to get
the Calendar Colors panel as shown in Figure 70 on page 80.

Chapter 2. User Interface

79

Figure 70. Calendar Colors Panel (ISPCALGC)

2.6.3 User Status


You can define which variables should be displayed in the status area by
selecting User status customization... from the Option action bar choice on the
ISPF Status Pop-Up window (see Figure 67 on page 78). The User View
Customization Panel is displayed in Figure 71.

Figure 71. User View Customization Panel (ISPSAMUS)

80

ISPF/SCLM V4 Guide

The status variables, that you have defined on Figure 71, are displayed in the
status area by selecting the User status choice from the Status pull-down
menu, as shown in Figure 72 on page 81.

Figure 72. ISPF Primary Option Menu Status Area - User Status View

2.6.4 User Point-and-Shoot


The status area can also contain your own point-and-shoot field. For example, to
define a point-and-shoot field that invokes the Edit panel:
Select User point-and-shoot customization... from the Option action bar
choice on the ISPF Status Pop-Up window (see Figure 67 on page 78).
Define the point-and-shoot fields as shown in Figure 73 on page 82.
Note: You may define up to nine point-and-shoot fields by associating them
to any valid SELECT service parameter. Refer to ISPF Service Guide for
information on these parameters.
These user definitions are then available to the user through the Status
action bar choice, or through the SAREA command.

Chapter 2. User Interface

81

Figure 73. User Point-and-Shoot Customization Panel (ISPSAMUP)

The Edit point-and-shoot field that you have defined is displayed in the status
area by selecting the User point-and-shoot choice from the Status pull-down, as
shown in Figure 74.

Figure 74. ISPF Primary Option Menu Status Area - User Point-and-Shoot View

82

ISPF/SCLM V4 Guide

2.6.5 None
If you select None from the Status pull-down, nothing will be displayed in the
status area.

2.7 Modifications to ISPF Objects


In previous versions of ISPF, it was not untypical to modify panels and, in
particular, the ISPF Primary panel, ISR@PRIM. In ISPF V4.1 this has now
become rather difficult as ISR@PRIM is no longer an uncomplicated panel; on
the contrary, it has become rather complex. We would advise that you now take
one of the following approaches to convert such modified panels:
Create a new primary panel, XYZ@PRIM, containing your own applications,
and include an option on this panel to access the unmodified ISPF.
Modify the Primary panel ISR@PRIM by adding only one extra option that
points to your installation's applications.
Modify the Primary panel ISR@PRIM by adding only one extra option that
points to your installation's applications.
Note: A full implementation of primary panel, ISR@PRIM, that has been heavily
modified, will probably remove all new items from the front panel, such as action
bar, point&shoot fields, scrollable application list, calendar, status fields and
much more. Consequently, we would not advise you to do this.
If you still plan to modify panels like ISR@PRIM or other elements of ISPF, the
following items should be taken into consideration:
PF-key settings
You should consider how your PF-keys should be arranged: as a keylist,
using default keylist, or as the old PF-key facility. See 2.2, Keylists on
page 48 for more detailed information.
Note: Many of the new panels in ISPF depend on the key definitions that the
panels specify. Removing these keylist specifications or modifying them
drastically can make some functions inoperable or reduced in functional
capabilities.
The use of keylists remove the global status of PF-keys, that has been used
in previous versions of ISPF and with Version 4 the discrete use of keys in
individual panels is implemented throughout ISPF. This is a major
enhancement from previous times rather rigid use of keys to a more flexible
use. The transition period to using keylists is not necessarily easy, because
all users have the old PF-key definitions in their fingertips and it takes
considerable time to adjust to new standards, but the benefit of the keylists
is large enough, that it pays off to get used to them.
Action bar attributes
If substantial additions are made to ISR@PRIM, one might also want to add
those to the action bar Menu pull-downs through out ISPF, so that they are
available in the same manner as ISPF's functions. See 2.1, Action Bar on
page 39.
Panels
If you decide to modify ISPF panels, it can be done in two ways:

By using the compiled output of the panel as a model

Chapter 2. User Interface

83

By using the DTL itself

We strongly suggest that you use the DTL for your modifications, as it
becomes easier to retrofit them to fixes destributed in DTL rather than to the
panel code itself. IBM fixes are made in DTL, even though they may also be
destributed in traditional panel code.
For further information, see Dialog Tag Language Guide and Reference.

84

ISPF/SCLM V4 Guide

Chapter 3. 3270 Environment


ISPF was originally designed for the IBM 3270 Display Systems, and ISPF will
still, for many years to come support you in this environment. In spite of the fact
that much design work is now targeted for programmable workstations, and
more and more users are following the trends of moving as much processing as
possible to such workstations away from the central host, the nonprogrammable
workstation, the o l d VTAM attached 3279 (and sometimes even 3278 and 3277)
will still be used many years ahead.
The graphical user interface, which is completely new with this version of ISPF,
will be discussed in Chapter 4, Graphical User Interface (GUI) on page 97. It
should, however, be noted that many of the new elements in ISPF Version 4
Release 1 (and few from Version 3 that did not become widely used until Version
4) have been implemented due to this workstation interface in order to support
the Common User Access (CUA) interface definitions used with programmable
workstations. The traditional 3270 user will therefore experience an interface to
ISPF that is slightly different from what he or she is used to. The intent of this
chapter is to provide suggestions that an installation or individual user may take
in order to make the learning or adaptation process as smooth and easy as
possible. Further, the section on CM/2 emulated terminals provides
considerable performance enhancing functions with the assistance of the CM
Mouse tool.
The discussion is divided into a two sections: one, that deals strictly with
hardware implemented terminals (i.e. r e a l 3270 terminals), and another, that
deals with 3270 terminals emulated on an OS/2 platform using CM/2. The latter
has been chosen because it provides the possibility of using an attached mouse
as an alternative to the enter key, and also provides an easy user interface for
redefining keyboard definitions.

3.1 IBM 3270 Hardware Terminals


In Chapter 2, User Interface on page 39 the features and interfaces
implemented in ISPF Version 4 Release 1 are discussed in detail. The following
section provides some suggestions for improving the usability of ISPF 4.1.
Emphasis is placed upon ways to make the new interface more compatible for
traditional ISPF users. See Figure 75 on page 86 for an example of the 3270
mode ISPF primary option menu.
In spite of the visual changes, for the most part, traditional ISPF users will still
be able to get around quickly and effectively. The following sections discuss
these differences, and suggest alternatives or changes you can make to improve
usability or to make the new ISPF more compatible with previous releases.

Copyright IBM Corp. 1994

85

Figure 75. ISPF 4.1 Primary Option Menu

3.1.1 Action Bar Considerations


The action bar consists of a set of pull down choices, each of which represents a
menu with various selectable functions. Use of the action bar occurs in two
steps. The first step is to activate the pull-down by placing the cursor on the
item desired and pressing enter. Next you must select the menu item (or
pull-down choice) desired, by either placing the cursor on the choice, or by
entering the choice's number. The tab key is of no use within a pull-down menu.
Hint
Using an action bar item allows you to nest ISPF functions. For example, if
you are in edit and have to look at another data set, pull down the Menu
choice and select View. Once you have found what was desired, press PF3
to exit back to the original Edit session.
Caution: using the jump function, for example = x , from within a nested
session will cause an exit of all nested sessions.

Users with the habit of having a command line at the top of the screen now see
the home key sending the cursor to the action bar rather than to the command
line. Since you should be able to select action bar functions using the tab key,
the entire action bar is implemented as an input field. With the habit of typing
and entering a system command after pressing the home key, it is possible to
type a command across the action bar instead of across the command line. If
you then press enter, a pull-down will be activated, depending upon the length of
the command entered (i.e. the location of the cursor dictates which menu is
pulled down). The command entered is ignored. This is not a severe problem,
because no commands are executed, and pressing function key 12 (F12), Cancel,
removes the pull-down.
It is understood that many users will learn their way around this, perhaps by
pressing the soft enter (new line) key immediately after pressing the home key.

86

ISPF/SCLM V4 Guide

But, for some users, the more often this happens the more time is lost, and the
incentive to do something about it grows.
There are a few changes you can make to either decrease or eliminate these
difficulties:
Leave it as it is and learn new habits.
Remove the action bar entirely.
Remove the ability to tab to action bar functions.
Place the command line at the top.
Use F24=CRETRIEVE.
Remove the action bar from Edit and View.

3.1.1.1 Learn New Habits


There is little to be said on this subject, but the Hint box below gives an example
of what new habits are possible.
Hints
Many users of ISPF have learned the habit of periodically pressing the
< H o m e > key to return to the command line, and then typing save. With
ISPF 4.1, the < H o m e > key places the cursor on the File pull-down choice
and the top choice in this pull-down choice is Save. Consequently, pressing
< H o m e > followed by pressing the < E n t e r > key twice will result in your file
being saved.
All member selection lists in ISPF are point-and-shoot fields. It is no longer
necessary to select by entering an S in that field and pressing Enter. Just
press Enter to select the member or to retrieve a list of possible actions for
that field.
The fields in the header line of a member list are also point-and-shoot fields.
If you place the cursor on one of these fields and press Enter, the member
list is sorted with that field as sort criterion.

3.1.1.2 Remove the Action Bar


In time, most users will agree that the action bar represents an improved way of
navigating to various ISPF functions. With the action bar removed, you can
function in ISPF 4.1 in the exact same fashion as with ISPF 3.5.
It is believed that you are best served by having the action bar present.
Regardless, for information on how to remove the action bar entirely from ISPF,
see 2.1.2.1, Removing Action Bars on page 42.

3.1.1.3 Remove Ability to Tab


If the tab to action bar choices is removed, which you may do under Settings,
the action bar can only be accessed by using the cursor movement (arrow) keys.
This results in an action bar which most users would find difficult to access. But,
in most panels, function key 10 (F10) can be used to jump to the beginning of the
action bar.

Chapter 3. 3270 Environment

87

With tab to action bar disabled, the home key will place the cursor on the
command line, provided the command line has been placed at the top of the
screen. (See 3.1.1.4, Placing Command Line at the Top on page 88)
It is not possible to program the Home key to place the cursor on the command
line if the Action Bar is tab-able. The home key places the cursor at the upper
left of the screen's input area. You can only tab to an input field.

3.1.1.4 Placing Command Line at the Top


The default for command line position follows the CUA recommendation of
having it at the bottom of the screen. Having the command line at the top is
considered to be a clear advantage in ISPF 4.1 in 3270 mode. The command line
can be easily moved to the top by changing the appropriate option in Settings.
With the command line at the top of the screen and the action bar tabbing
disabled, the home key works as it used to do. However, as mentioned in the
previous section, this may prevent you from getting the full benefit from the
action bar choices.
Many users will prefer to have the command line at the top, and there does not
appear to be any drawbacks to changing its location.

3.1.1.5 Use F24=CRETRIEVE


The CRETRIEVE command functions differently depending upon where the cursor
is currently located. When the cursor is on the command line, CRETRIEVE
functions the same as the RETRIEVE command. However, when the cursor is
located anywhere else on the screen, the CRETRIEVE command functions the
same as the CURSOR command, and the cursor is placed on the command line.
The default keylists for ISPF 4.1 have function key 24 already defined as
CRETRIEVE. Accessing F24 can be awkward. A better alternative would be to
program a key, such as the scroll lock key, to function as F24. This provides you
with an easy to implement and easy to use method of getting the cursor to the
command line.
Note
If you are using Global Keylists (see 2.2.3, Global Function Keys Setting on
page 58), function key 24 will be defined as RETRIEVE. Either change this to
CRETRIEVE, or else be certain that you have selected Enable Keylists from
the Function Key pull-down menu in option 0, Settings.

3.1.1.6 Remove Action Bar from Edit and View


By modifying ISRCONFG, it is possible to remove the action bar from Edit and
View panels. See 5.1, Modifying ISPF Configuration Table (ISRCNFIG) on
page 147 for more information.

3.1.2 Point & Shoot


The CUA documentation describes this as point and select and is merely used
for the way action bar choices are selected. ISPF uses the term Point & Shoot
in a broader sense. Most selectable elements can now be selected by merely
placing the cursor on the select field - and often also associated fields - and
pressing the Enter key.

88

ISPF/SCLM V4 Guide

There are many instances where point and select is clearly advantageous. The
best example comes in Edit or View mode. Once you have used the Tab key or
the Cursor Move keys to select the desired member, pressing the Enter key is all
that is necessary. The traditional S is no longer required.
On any selection menu, for example, the Primary Option Menu, point and select
also works. By placing the cursor on the desired choice and pressing Enter, you
can select any option available.
Point and select is also used on the action bar (of course), and the calendar.

3.1.3 PF Keys
Another difference you might notice in Figure 75 on page 86 are the PF key
assignments. The default settings with ISPF 4.1 are in accordance with CUA 89
guidelines. With new functionality added to keylists, some of these key
assignments will change depending upon what function of ISPF is being used.
For more information on altering function keylists, see 2.2, Keylists on
page 48.
The most noticeable key assignment change is undoubtedly function key 12, F12.
More than a few users are going to be surprised when they press a key to
retrieve a command and are promptly cancelled out of whatever they were
doing. Users of Edit do not have to fear! ISPF 4.1 will prompt you to ensure that
you really do want to cancel without saving changes.
Note
ISPF 4.1 features a greatly enhanced retrieve function. See 1.2.11, Forward
Retrieve and Retrieve Pop-up on page 30 for more information.

Before turning to 2.2, Keylists on page 48 to reassign PF12 to Retrieve,


remember that there are situations where a Cancel function key is helpful. This
is particularly true with ISPF 4.1 and the action bar pull-downs. For example,
when you press Home and type TSO RECEIVE across the action bar and then
press Enter, the F12 key will gracefully get you out of the pull down menu you
inadvertently activated.
The F12 key is not the only method of cancelling a pull-down. Moving the cursor
outside the menu and pressing Enter will also clear the selection.
The second key assignment to be changed is the function key 4, F4 Return. The
lack of a Return function shouldn't have a big impact.

3.2 IBM 3270 OS/2 - CM/2 Emulated Terminals


In the CM/2 environment, the use of a 3270 emulator can be enhanced in
numerous ways. Built-in OS/2 functions, like the copy and paste feature, is a
simple example, but many more sophisticated tools exist to improve usability.
This section is focussed entirely upon one of these tools, IBM Communications
Manager Mouse, or CM Mouse (product number 5799-PNJ).

Chapter 3. 3270 Environment

89

3.2.1 CM Mouse with ISPF 4.1


For the purpose of this document, CM Mouse Version 1 Release 4 was only
tested in the OS/2 2.1 environment. CM Mouse can also run on Windows and
DOS platforms.
CM Mouse is a powerful tool. With the advent of select and shoot areas in ISPF
4.1, CM Mouse can be used to considerably enhance productivity. The BDF
(Button Definition File) and MMM (CM Mouse Menu) files found on the included
diskette were designed with the intent of simulating the GUI environment. You
will be surprised at how close a simulation is possible.
See 3.3, CM Mouse BDF and MMM Files on page 92 for source listings of the
BDF and MMM files.
Note
To improve CM Mouse response time, it is recommended that you run as few
BDF files as possible. Ideally, only the ISPF41.BDF file should be used.

3.2.1.1 Using CM Mouse


The BDF file is a close-enough approximation of GUI mode that a user can
interact with ISPF as though he or she where in GUI mode. The following
instructions give exceptions, limitations and improvements that are particular to
the design of the BDF files.
To use the included BDF and MMM files, copy ISPF41.BDF, ISPF41.MMM and
ISPFE41.MMM to your default directory for CM Mouse configuration files.
Limitations and Potential User Modifications: Important: this section must be
read before trying to use the supplied BDF and MMM files.
The BDF file requires the ISPF action bar to be present for proper screen
recognition.
The supplied BDF is configured for only two rows of function keys. To
change this, edit ISPF41.BDF and search for the AREA definitions for PF keys.
Increase or decrease the absolute value of the first coordinate (the ROW
parm) in order to increase or decrease the number of PF key rows your
implementation requires. If desired, you can also make this change under
the Edit panel sections of the BDF file as well.
Button definitions are written for a two-button mouse only.
From a pop-up window, you must use the function keys that are located at
the bottom of the screen. There is no effective way to allow CM Mouse to
recognize all pop-up window function keys.
When in split screen mode, the cursor must always be placed at the very top
of the screen before splitting. The SCREEN definitions expect the split
screen line (. . . .) to be either the first or last row of the screen.
The supplied examples are thoroughly commented, and you are invited to
modify them.
Mouse Functions of ISPF41.BDF, General Mode:

90

ISPF/SCLM V4 Guide

CM Mouse Pop-Up
To access the CM Mouse pop-up menus, press both mouse buttons at
the same time. (Also called a chord.)
Enter at host cursor
Double click the left mouse button anywhere (simulates an enter at
the host cursor position).
Enter at mouse pointer
Click the left mouse button anywhere to simulate an enter at the
mouse pointer's location.
F3=Exit
Single click the right mouse button anywhere to exit.
F12=Cancel
Double click the right mouse button anywhere to cancel.
Note
CM Mouse V1.4 and OS/2 V2.1 have an incompatibility that prevents the
double click function of the mouse from functioning.

Mouse Functions of ISPF41.BDF, Edit or View Mode:


CM Mouse Pop-Up
To access the CM Mouse pop-up menu, press both mouse buttons at
the same time. (Also called a chord.)
I -- Insert Line
Double click the left mouse button anywhere on a line you would like
to begin inserting text after. This option will not work if the keyboard
is in insert mode.
TS -- Text Split
Double click the right mouse button anywhere on a line you would
like to split. This option will not work if the keyboard is in insert
mode.
F3=Exit
Single click the right mouse button anywhere to exit.
Enter at mouse pointer
Single click the left mouse button to simulate an enter at the mouse
cursor location.
CM Mouse Pop-Up Menus: The ISPF41.BDF file uses two CM Mouse menus:
ISPF41.MMM and ISPFE41.MMM. The first is for general use within any ISPF
panel, while the latter is intended for use within Edit or View.
To activate the pop-up, press both mouse buttons at the same time. See
Figure 76 on page 92 for an example of the general usage pop-up menu. The
options are selected by using the left mouse button, and the pop-up can be
cleared from the screen by pressing the right mouse button. The choices

Chapter 3. 3270 Environment

91

provided are self-explanatory, and a dummy example is included for the user to
fill in with a desired function of his or her own.

Figure 76. CM Mouse General Use Pop-Up Menu

3.3 CM Mouse BDF and MMM Files


The following files may also be found on the included diskette. The BDF and
MMM files are distributed as is, and users are encouraged to modify them.

3.3.1.1 Button Definition File, ISPF41.BDF


This file should be placed into your CM Mouse BDF file directory.

***************************************************************
* IBM CM Mouse Support/2 (5799-PNJ): GUI "Simulation" Button Definition
* For ISPF v4.1 in 3270 mode using CM Mouse v1.4
* Written by Matt Nuttall, ITSC, July/August, 1994.
* Distributed as is, users are encouraged to modify.
* Important:
* See ISPF and SCLM Implementation Guide, Version 4
* for information on how to use this BDF file.
***************************************************************
map off
* In case of unrecognized panel....
*
button left
"{seek} enter"Point and select
button right
" pf3"Exit
button left+right "{beep}"
button right+left "{beep}"
button dblleft
"{beep}"
button dblright " pf12"Cancel
***************************************************************
* Edit or View Screen Definitions -- split screen line at top
***************************************************************
screen 1 1 exact * " . . "
and-screen 2 3 exact * " File E"
button left+right "{popup ispfe41}"Popup list of ISPF Edit commands
button right+left "{popup ispfe41}"Popup list of ISPF Edit commands
button left
"{seek} enter"Point and Select
button dblleft
"{seekcol 2}i enter"Insert mode
button dblright
"{seekcol 2}ts{seek} enter"Text split
button right
" pf3"Exit ISPF Edit or View
*************************
* Area Definitions
92

ISPF/SCLM V4 Guide

************************
* Edit and View screen definition
* Only tworows of PF keys allowed. Default -1.
area -1 1 0 0 ---------------- PF Keys
button left "{pfkey}"Execute PF Keys
area 1 1 2 0 ------------- Action Bar
button left "{seek} enter"Point and Select
***************************************************************
* Edit or View Screen Definitions -- split screen line at bottom
***************************************************************
screen 1 3 exact * " File E"
and-screen 0 1 exact * " . . "
button left+right "{popup ispfe41}"Popup list of ISPF Edit commands
button right+left "{popup ispfe41}"Popup list of ISPF Edit commands
button left
"{seek} enter"Point and Select
button dblleft
"{seekcol 2}i enter"Insert Mode
button dblright
"{seekcol 2}ts{seek} enter"Text Split
button right
" pf3"Exit ISPF Edit or View
*************************
* Area Definitions
************************
* Edit and View screen definition
* Only tworows of PF keys allowed. Default -2.
area -2 1 -1 0 ---------------- PF Keys
button left "{pfkey}"Execute PF Keys
area 1 1 1 0 ------------- Action Bar
button left "{seek} enter"Point and Select
***************************************************************
* Edit or View Screen Definitions -- no split
***************************************************************
screen 1 3 exact * " File E"
button left+right "{popup ispfe41}"Popup list of ISPF Edit commands
button right+left "{popup ispfe41}"Popup list of ISPF Edit commands
button left
"{seek} enter"Point and Select
button dblleft
"{seekcol 2}i enter"Insert mode
button dblright
"{seekcol 2}ts{seek} enter"Text split
button right
" pf3"Exit ISPF Edit or View
*************************
* Area Definitions
************************
* Edit and View screen definition
* Only tworows of PF keys allowed. Default -1.
area -1 1 0 0 ---------------- PF Keys
button left "{pfkey}"Execute PF Keys
area 1 1 2 0 ------------- Action Bar
button left "{seek} enter"Point and Select
***************************************************************
* ISPF Generic Screen Definitions -- split screen line bottom
***************************************************************
screen 0 1 exact * " . . "
button left+right "{popup ispf41}"Popup list of ISPF commands
button right+left "{popup ispf41}"Popup list of ISPF commands
button left "{seek} enter"Point and select
button dblleft "{unseek} enter"Enter at cursor position
button right " pf3"Exit ISPF
Chapter 3. 3270 Environment

93

button dblright " pf12"Cancel


*****************
* Area definitions
*****************
* Standard ISPF screen definition
* Only tworows of PF keys allowed. Default -1.
area -2 1 0 0 ---------------- PF Keys
button left "{pfkey}"Execute PF Keys
***************************************************************
* ISPF Generic Screen Definitions -- no split screen or split at top
***************************************************************
screen 2 1 line * " ISPF"
or-screen 1 3 exact * " Menu"
or-screen 1 3 exact * " Log"
or-screen 1 1 exact * " . ."
or-screen 1 1 exact * " TUTORIAL"
button left+right "{popup ispf41}"Popup list of ISPF commands
button right+left "{popup ispf41}"Popup list of ISPF commands
button left "{seek} enter"Point and select
button dblleft "{unseek} enter"Enter at cursor position
button right " pf3"Exit ISPF
button dblright " pf12"Cancel
*****************
* Area definitions
*****************
* Standard ISPF screen definition
* Only tworows of PF keys allowed. Default -1.
area -1 1 0 0 ---------------- PF Keys
button left "{pfkey}"Execute PF Keys

3.3.1.2 General Mouse Menu, ISPF41.MMM


This MMM (CM Mouse Menu) file contains a pop-up menu definition suitable for
most ISPF panels. The ISPF41.BDF requires ISPF41.MMM.

***************************************************************
* IBM CM Mouse Support/2 (5799-PNJ): General Mouse Pop-Up Menu
* For ISPF v4.1 in 3270 mode using CM Mouse v1.4.
* Written by Matt Nuttall, ITSC, July/August, 1994
* Distributed as is, users are encouraged to modify.
* Important:
* See ISPF and SCLM Implementation Guide, Version 4
* for information on how to use this MMM file.
**************************************************************
title red "ISPF Options "
line "Settings"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofsettings enter
line "View"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofview enter
line "Edit"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofedit enter
line "Dummy"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
94

ISPF/SCLM V4 Guide

colnum = &{scol}+5;+
exit colnum;}} eraseeofyour command goes here enter
line "Retrieve Pop-Up"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofretp enter
line "Panel Help"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofexhelp enter
line
line "Exit ISPF"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeof=x enter
line "Here Kitty!"{terminate}

3.3.1.3 Edit and View Mouse Menu, ISPFE41.MMM


This MMM (CM Mouse Menu) file contains a pop-up menu definition suitable for
ISPF Edit and View modes. The ISPF41.BDF requires ISPFE41.MMM.

***************************************************************
* IBM CM Mouse Support/2 (5799-PNJ): Edit and View Mouse Pop-Up Menu
* For ISPF v4.1 in 3270 mode using CM Mouse v1.4.
* Written by Matt Nuttall, ITSC, July/August, 1994
* Distributed as is, users are encouraged to modify.
* Important:
* See ISPF and SCLM Implementation Guide, Version 4
* for information on how to use this MMM file.
**************************************************************
title red "ISPF Options "
line "Save"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofsave enter
line "Submit"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofsubmit enter
line "Undo"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofundo enter
line "Dummy Macro"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofyour macro goes here enter
line "Retrieve"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeofretrieve enter
line
line "Exit ISPF"{search for /===>/ at 1 1 0 30}+
{rowcol &{srow} &{rexx +
colnum = &{scol}+5;+
exit colnum;}} eraseeof=x enter
line "Here Kitty!"{terminate}

Chapter 3. 3270 Environment

95

96

ISPF/SCLM V4 Guide

Chapter 4. Graphical User Interface (GUI)


The intent of the following section is to provide a detailed, environment specific
sequence of steps a user can take to establish ISPF running in Graphical User
Interface mode. It is assumed that the user already has ISPF successfully
installed and running in text (3270) mode.
The user's knowledge level is generally taken as the lowest level practical. It is
possible that a user following the guidelines, at some point needs to consult a
site expert in order to proceed (for example, your local DOS, OS/2, TCP/IP or
APPC guru).
For the experienced TCP/IP or APPC users, there is a brief outline of what is
required in section 4.2.2.1, For the Experienced User on page 98.

Figure 77. ISPF Workstation Server Icon

4.1.1 How to Use this Chapter


The main sections of this chapter are divided according to the communications
software used and the operating system it runs on. For example, IBM TCP/IP for
OS/2.
The configuration guidelines were successful in their specific tested
environments. Be sure to read the details of this environment at the beginning
of each section to be certain that you are using the closest match to your
requirements.

4.1.1.1 Support Software Limitations


There are many different environments available for supporting the
communication connection necessary for ISPF GUI. It is not possible to provide
implementation scenarios for all of them. In addition, different release levels can
cause panels to change or be accessed differently. Since there are only two
different peer communications protocols used by ISPF 4.1 GUI (TCP/IP and
APPC), different vendor implementations and different releases will still use a
common terminology. To decrease cross-release and cross-product
dependencies, the field names you have to update are underlined in the text.
You can use these field names to help you locate the corresponding field in your
release or implementation.

4.2 Getting Ready for GUI


Before proceeding, ensure that the following tasks have all been completed.
This part of the setup should be done by the systems guru.
ISPF Version 4.1 or better has been installed and is functioning.
Development APAR OW03965 has been applied.
Copyright IBM Corp. 1994

97

All necessary maintenance has been installed. Consult your Install Bucket
for a list of PTFs. If you don't have an Install Bucket, contact the IBM
Support Center and get one.
Be careful when applying any maintenance (PTFs) that has a release number
of 104 (or X04 for future releases). This release number applies to the Client
Server portion of ISPF. When maintenance is applied for this component, it
is likely that new code must be downloaded to the workstation. It is
expected that in the future there will be SMP Hold Data recommending this
action. (OW03965 contains no such warning!)
Consult your Program Directory under the section Installation Requirements
and Considerations for further information regarding software requirements.
In particular, have a look at the section titled Software Requirements, ISPF
Client/Server Implementation.

4.2.1 Some Terminology


ISPF 4.1 is the first release of ISPF to allow users to choose a GUI interface. The
GUI interface is made possible by using a Client/Server architecture. Due to the
nature of the ISPF C/S implementation, the MVS host computer running ISPF is
presently considered to be the client, while the workstation is considered to be
the server. An attempt is made in the following document to avoid using these
terms where an ambiguity may result.
In order for ISPF to function in the GUI mode, it is necessary to run a program
(actually a display server) on your workstation that will communicate with the
MVS host and do all necessary processing.

4.2.2 Establishing Connectivity


ISPF 4.1 GUI requires a layer of connectivity in addition to your standard 3270
host-connect session. There are two ways you can provide this extra
connectivity: using TCP/IP or APPC.

4.2.2.1 For the Experienced User


This section is a brief outline of what needs to be done to establish adequate
connectivity for ISPF GUI. See the product specific sections if you require further
details.
TCP/IP: If TCP/IP is already up and running on your workstation, you should not
have to change anything.
To download the client portion of TCP/IP, you must have the FTP daemon
running. Option 3.7 in ISPF manages the download. You must supply the name
and password for an FTP user defined to TCP/IP on the workstation (in the
TRUSERS file in the IBM TCP/IP environment).
After the down load, ISPF acquires a socket like any other TCP/IP based
application. If you are able to PING the MVS host, then you have adequate
connectivity.
APPC: If APPC connectivity is already up and running, you will have to ensure
that the APPC/MVS base application LUname and ACB are defined in the MVS
PARMLIB data set as well as in the VTAM VTAMLST data set.

98

ISPF/SCLM V4 Guide

The VTAM definitions in information APAR II07895 are adequate, but there is
more than one way to define an APPC connection. Definition of each
communication workstation as an SNA type 2.1 node supporting at least one
independent LU, that can be associated with the #INTER logmode table entry, is
necessary. The APPC/MVS ASCH component need not be active if you code the
ACB for the APPC LU as NOSCHED.
The workstation code can be downloaded using any binary download program.
The communications program on your workstation must be configured as an
SAN type 2.1 node supporting LU6.2 communications.

4.2.3 IBM TCP/IP for OS/2


The following section provides specific details of how to configure IBM TCP/IP for
OS/2 Version 2.0 running on IBM OS/2 Version 2.1
Note
For a TCP/IP installation, it is strongly recommended that you read
informational APAR II07897 prior to proceeding.

Here are a couple of hints that you might want to keep in mind as you go:
If you lose your place or become lost/confused while updating the TCP/IP
configuration panels, simply double click on the top left corner to close the
panel, and then choose to DISCARD your changes. You can then restart
configuration with the original settings.
The following guidelines only detail the minimum necessary for ISPF 4.1 to
install and run as designed. It is quite possible that your site would like
more features enabled, or a more robust definition, than what is detailed in
the following.
It is assumed that TCP/IP has already been successfully installed (though not
necessarily configured) on your system.
You'll need the following information from your TCP/IP person. (There might
also be further information that your network specialist would like you to
include):
The IP address of your workstation
Subnet mask
A ROUTER IP address (i.e. a path for TCP/IP to use to get to the MVS host
from your machine.)
It is recommended that you have IBM TCP/IP for OS2 V2 Installation and
Administration handy before starting. Keep in mind that the TCP/IP configuration
panels have field sensitive help. This means you can place the cursor on any
field you're unsure about, and then click on help for more detailed information.
1. Open your TCP/IP folder and double click on the TCP/IP Configuration icon.
You should now be looking at something similar to Figure 78 on page 100.
Place your IP Address and your Subnet Mask in the appropriate fields. Make
sure that you have a check mark for Enable Lan Adapter 0. Try using field
sensitive help for the Maximum Transmission Unit field. (For a token ring
connection, you should be using an MTU size of 4400.)

Chapter 4. Graphical User Interface (GUI)

99

Figure 78. TCP/IP Network Configuration Panel

2. Click on the tab for Routing. You'll have to configure at least one Router IP
Address entry here in order for you to successfully establish your TCP/IP
connection. This router definition provides your workstation with a route (or
path) outward from your machine (and towards the MVS host computer
running ISPF). In the illustrated case, a default entry for a node one hop
away is used. This node has its own path for getting to the host. Using a
default entry here is the simplest, because you only have to hop to a node
that already knows how to get to the host (ISPF) system. See Figure 79 on
page 101.
3. Now select the tab for the Autostart configuration page. You'll find an
example of this panel in Figure 80 on page 101. The FTP (File Transfer
Protocol) daemon must be running for the download of the workstation code.
There are only two options you have to enable. Place a check mark in the
Enable this machine to start the inetd super server. As well, place a check
mark next to Enable others to access your files by using FTP. Don't forget to
select start FTP using inetd.
Note
The FTP daemon (server) is necessary only for the download of the GUI
code to your workstation. Since it is possible to do this download in
other ways (see 4.3, Downloading GUI to Your Workstation on
page 110), it is not critical that you have FTP activated.
4. Next select the tab for Services. On this panel, we have to set up a
TRUSERS file entry that will be used later by ISPF for the download of the
workstation portion of ISPF GUI. Click the mouse in the section called
TRUSERS (FTP Access Protection). Then select ADD. You should see a
panel like that in Figure 81 on page 102. Fill in a Username and a Password
in the appropriate boxes. You'll have to refer to these later, so don't forget
them. Curiously, to exit this panel, you must click on EDIT.

100

ISPF/SCLM V4 Guide

Figure 79. TCP/IP Routing Configuration Panel

Figure 80. TCP/IP AutoStart Configuration Panel

Chapter 4. Graphical User Interface (GUI)

101

Note
The TRUSERS file (short for TRusted USERS) should be found in your
main TCP/IP directory under the subdirectory \ETC. The name of the file
is simply TRUSERS with no suffix. Saving the panel in Figure 81 on
page 102 will result in a TRUSERS file that looks like:

user: matt ******


rd: e:\ispgui e:\
wr: e:\ispgui e:\

Figure 81. TCP/IP Services FTP User Configuration Panel

Under Directory access for write, enter the drive letter and directory name
where you would like to place the ISPF client portion of the code. If you
would like to have FTP create the directory on your hard drive, then you
must also have write access to the directory above the ISPF directory. In the
illustrated case, this would be E:\. In addition, read access is required if you
intend to let FTP create the directory. You'll have to refer to this directory
later too.
Warning
Be certain that there are no checkmarks in either Deny read access to
directories listed or Deny write access to directories listed. A checkmark
in either of these boxes will give other FTP users access to everything on
your machine except for the directory names listed!
5. Double click on the top left corner of the TCP/IP Configuration Window to
save your changes, and you're done.
6. Proceed to the section 4.3, Downloading GUI to Your Workstation on
page 110.

102

ISPF/SCLM V4 Guide

4.2.4 APPC for IBM CM/2


The following section provides specific details for configuring IBM
Communications Manager/2 Version 1.1 on IBM OS/2 Version 2.1.

4.2.4.1 On the MVS Host Side


Note
For an APPC implementation, it is strongly recommended that you read
informational APAR II07895 prior to proceeding.

Configuring a workstation to allow APPC connectivity requires considerable


expertise on the host side. After coding the necessary VTAM configuration
changes, both APPC and ASCH must be activated. (See Note below for an
exception regarding ASCH.) If you don't see message
ATB050I LOGICAL UNIT SCISPF41 FOR TRANSACTION SCHEDULER ASCH HAS
BEEN ADDED TO THE APPC CONFIGURATION
(where SCISPF41 is the ISPF ACB name) then you will not be able to connect.
Make certain that you've seen this message on the master console before
working on your workstation setup.
Note
You can avoid having to start ASCH if you code your ACB definition for the
APPC LU with the NOSCHED parameter. You should get the same message
as above with *NONE* instead of ASCH.

4.2.4.2 At Your Workstation


Before proceeding, please collect the following information:
The name of an independent LU (logical unit) associated with your
workstation (the LU name representing the workstation control point is
generally adequate)
The name (Host-ID name) of the network to which you are attached.
The following is information on configuring the workstation side of the
connection, using Communication Manager/2. It is assumed that CM/2 has
already been successfully configured for 3270 sessions. Depending on how
CM/2 has been configured, it is possible that you will not make any changes in
the following procedures. You may simply be verifying that the definitions are
correct.
APAR II07895 has some information about your workstation configuration.
Again, don't hesitate to use the field sensitive help in CM/2. It is surprisingly
thorough.
1. Double click on the Communications Manager Setup icon.
2. Select Setup. The next panel you see will be called Open Configuration.
Your current configuration name will be listed in the Configuration field. Do
not modify this panel, simply click on OK and continue.

Chapter 4. Graphical User Interface (GUI)

103

Note
It is recommended that you go to an OS/2 session and make copies of
your CM/2 configuration files before proceeding with any modifications.
To find these files, go to the directory listed on your Open Configuration
panel. (Usually this is C:\CMLIB.) List all files in this directory with a
prefix equal to what you see in the Configuration field. You should see
files with suffixes of NDF, CFG and others. Make a copy of all files you
see listed. In the event of a problem while making changes, you can
always go back to using your original configuration. If the files you
copied are kept in \CMLIB, they will be visible as an option the next time
you invoke CM/2 setup.
3. You should now be looking at the panel in Figure 82. For Workstation
Connection Type, select Token-ring or other LAN types and for Feature or
Application, choose APPC APIs. Click on Configure to proceed.

Figure 82. Communications Manager Configuration Definition

4. The next panel you see is illustrated in Figure 83 on page 105. Select SNA
local node characteristics, and click on Configure.
5. The panel your are now viewing (see Figure 84 on page 105) will already
have the Network ID and Local node (i.e. control point) name filled in with
values. Click on Options, and you will then be viewing the Local Node
Options Panel. You must have a check mark beside Activate Attach
Manager at startup.
6. Click on OK to return to Figure 84 on page 105. If the Local node name
matches the LU name given to you by your network administrator, then you
do not have to do any further updates to this panel. Go to step 9 on
page 106.

104

ISPF/SCLM V4 Guide

Figure 83. Communications Manager Profile List

Figure 84. Communications Manager Local Node Characteristics

7. If your LU name did NOT match the Local Node name in the previous step,
then return to the Communications Manager Profile List, and select SNA
features (Figure 83).
8. You should now be viewing the SNA Features List. Click the mouse on Local
LUs and select Create. You should now see the panel in Figure 85 on
page 106. Fill in your Local LU name and an alias. The LU name itself is
forced into capital letters, so I chose for my alias the same name in lower
case. The Independent LU pushbutton should be selected in the NAU
address box. In this example the independent LU name is the same as the
local node (control point) name.

Chapter 4. Graphical User Interface (GUI)

105

9. Select OK when you are done, and start closing the layers of windows.
CM/2 will automatically check your configuration values as you exit. If you
receive a verification error (hopefully not), proceed to the step 10 on
page 106. If everything checks out OK, you will be asked if you would like to
dynamically update your SNA resources. Select Yes and you are done. Go
to 4.3, Downloading GUI to Your Workstation on page 110.

Figure 85. Communications Manager Local LU Definition

Note
After selecting to dynamically update your SNA resources, you may get a
dynamic update error. Select Show Log, and if you see
APN0711E: An error occurred while attempting to update the active
definition of the local LU....
then you must stop and restart communications manager before the
update can take affect.
10. If you have a configuration error, you'll be prompted with a pop-up panel
asking if you'd like to show the error log using FFST/2. Select Show Log.
The top most messages in the list will describe your problem. If the
message makes enough sense for you to take action, do so! Since this is
often not the case, you have two other choices: go back to your backup
configuration and try again, or call your local CM/2 guru and ask for
assistance.
Note
As of this writing, FFST/2 had a problem with eating the mouse pointer
when closing its window. To avoid this problem, place your mouse
outside of the FFST/2 window, and use ALT+F4 to close the application.
If you do lose your mouse, you can reopen FFST/2 by using CTL+ESC to
get your task list and follow the steps to open it again. Your mouse will
reappear when FFST/2 restarts.

106

ISPF/SCLM V4 Guide

4.2.5 IBM TCP/IP for DOS and Windows


The following section provides specific details of how to configure IBM TCP/IP for
DOS V2.1.1 running in a DOS 6.1 and Windows 3.1 environment.
Note
For a TCP/IP installation, it is strongly recommended that you read
informational APAR II07897 prior to proceeding.

It is assumed that TCP/IP has already been successfully installed (though not
necessarily configured) on your machine.
Please, get the following information from your TCP/IP person. (There might
also be further information that your network specialist would like you to
include):
The IP address of your workstation
Your subnet mask
A ROUTER IP address (that is, a path for TCP/IP to use to get to the MVS
host system from you machine.)
The type of token ring adapter used by your workstation
Configuring IBM TCP/IP for DOS 2.1.1 is very similar to configuring IBM TCP/IP
for OS/2. The interface is less friendly, but most users should be able to
configure it without too many difficulties. Follow these steps to configure:
1. The command for configuring DOS TCP/IP is custom. Try typing this
command at the C : \ > prompt. If the command doesn't work, there might be
a problem with your PATH statement. Look for a directory called
TCPDOS\BIN, and try executing the command from there.
2. The main customization panel looks like Figure 86. Pull-down the
CONFIGURE menu, and select the top item, NDIS Interfaces.

Figure 86. TCP/IP for DOS CUSTOM.EXE Main Panel

Chapter 4. Graphical User Interface (GUI)

107

3. Now you should be looking at the panel shown in Figure 87 on page 108.
For ND0, enter you IP Address and Subnet Mask. By clicking on the small
down arrow in the Bound Adapter field, you can get a list of available
adapters. You may have to consult a site expert to determine which adapter
is compatable with yours. Make certain the your have an X in Enable
Interface, and you can click on OK to exit.

Figure 87. NDIS Interface Configuration Panel

4. From the Configure menu, select Routing. You should be looking at the
panel as shown in Figure 88. Use the pull-down arrow to select a DEFAULT
Route Type. Enter the IP Address and the Metric count. Select OK when
you are done.

Figure 88. Routing Information Configuration Panel

5. Select Auto-start from the Configure menu. The only item you want to
enable in this panel is TCP/IP. This differs from the OS/2 environment,
where FTP could be auto-started at boot time. Windows will hang when
invoked if FTP is already running. There is a small note about this in
Appendix F. Using TCP/IP for DOS with Microsoft Windows in the IBM
TCP/IP for DOS V2.1.1 Installation and Administration.)
You must manually start the FTP daemon after you have started windows
and before begining the download.

108

ISPF/SCLM V4 Guide

Figure 89. Auto-Start Configuration Panel

6. Next, select the FTP User List. Choose insert, and you should see something
similar to Figure 90. On this panel, we have to set up a TRUSERS file entry
that will be used later by ISPF for the download of the workstation portion of
ISPF GUI.
Note
The TRUSERS (short for TRusted USERS) file Should be found in your
main TCP/IP directory under the subdirectory \ETC. The name of the file
is simply TRUSERS with no suffix. Saving the panel in Figure 81 on
page 102 will result in a TRUSERS file that looks like:

user: matt ******


rd: e:\ispgui e:\
wr: e:\ispgui e:\
Fill in a Username and a Password in the appropriate boxes. You have to
refer to these later, so don't forget them.

Figure 90. FTP User Data Configuration Panel

Chapter 4. Graphical User Interface (GUI)

109

Under Directories for Write Access, enter the drive letter and directory name
where you would like to place the ISPF client portion of the code. If you
would like to have FTP create the directory on your hard drive, then you
must also have write access to the directory above the ISPF directory. In the
illustrated case, this would be E:\. In addition, Read access is required if you
intend to let FTP create the directory. You have to refer to this directory
later too.
Warning
Be certain that there are no x-marks in either Deny read access to
directories listed or Deny write access to directories listed. An x-mark in
either of these boxes will give other FTP users access to everything on
your machine except for the directory names listed!
Select OK when your are done.
7. Finally, on the Configure Menu, select Windows You will be prompted with a
panel asking if you'd like a TCP/IP group added to the Windows program
manager. Select yes.
8. You should be back at the main customization panel. Select Exit - save
changes and you are done configuring TCP/IP.
9. Continue with 4.3, Downloading GUI to Your Workstation.
Note
If a WINSOCK.DLL file can be located in the default directory search order in
a DOS/Windows environment, then the ISPF workstation agent will assume
that a Winsock-compliant version of TCP/IP is to be used. If a different
vendor implemention such as Novell LAN WorkPlace for DOS that uses the
WLIBSOCK.DLL is to be used, the environement must be adjusted so that
WINSOCK.DLL cannot be located in the default directory search order.

4.3 Downloading GUI to Your Workstation


ISPF 4.1 provides a method for downloading the client portion of the code using
FTP. If things went well in your TCP/IP setup, then this is a convenient way to
transfer the code to your workstation. But, if you are using APPC, or if for any
reason you can't use FTP, then you must find an alternative method. See 4.3.2,
Alternative download Methods on page 112.
Note
In ISPF 4.1 the workstation portion of the code for APPC with OS/2 is identical
to that used for TCP/IP with OS/2. The two sets of downloadable functions
are for the DOS/Windows environment versus the OS/2 environment.

4.3.1 Using TCP/IP File Transfer Protocol


1. You must be connected to a 3270 emulator session and logged on to
TSO/ISPF to accomplish this. From the Primary Option Menu, select option
3.7 ISPF C/S You will be looking at a list of six different options. See
Figure 91 on page 111.

110

ISPF/SCLM V4 Guide

Figure 91. Choosing a download Method (Option 3.7)

2. Select the appropriate option (one with TCP/IP), and then press Enter. You
should now be looking at Figure 92. As of this writing, the Novell TCP/IP
environments did not allow FTP downloads. These options require a manual
download. The User and Password are those that you entered as in
Figure 81 on page 102 when configuring TCP/IP. Be careful of upper/lower
case errors on your password. The error message for an incorrect password
is simply:
530 Login Incorrect.
Note
The FTP daemon (FTPD or FTP server) must be running on the
workstation before starting the download. If you followed the instructions
correctly for configuring TCP/IP for OS/2, then FTPD will already be
running.
If you are using windows, you must start the FTP Server (found in the
TCP/IP Group folder) manually prior to the download.

Figure 92. Downloading GUI Using FTP

Chapter 4. Graphical User Interface (GUI)

111

3. Enter the directory name that you placed in the same panel, and select
Create directory to which files are to be copied if you have not already
created a target directory.
4. When all fields look correct, press Enter to begin the transaction.
5. Examine the FTP output to see if the file transfer was successful. Some FTP
errors can be very difficult to diagnose. If you are unable to successfully
download using FTP, go to 4.3.2, Alternative download Methods.
6. If you have successfully downloaded the code, proceed to 4.4, Starting the
Workstation Server.

4.3.2 Alternative download Methods


There are numerous different ways to download host based files to a
workstation. The only limitation is that the files must be downloaded as BINARY
data. Allowing a download to occur in ASCII format can lead to very
unpredictable error messages.
To determine which files should be downloaded, select option 6 from Figure 91
on page 111.
Once you have successfully downloaded the code, proceed to 4.4, Starting the
Workstation Server.

4.4 Starting the Workstation Server


The first step towards establishing ISPF in GUI mode is to start-up the
workstation server.

4.4.1 OS/2 Environment


For testing purposes, it is best to invoke the code from an OS/2 window initially.
This allows you to see any messages that might appear.
From an OS/2 session, change directories so that you are in the directory
containing the code you downloaded. Enter the DIR command just to have a
look at what is there. You should see an executable file called ISPFCS.EXE.
This is the workstation portion of the code that must be run. Type ISPFCS and
press Enter. You should see a small window appear similar to that in Figure 93.

Figure 93. ISPF Server Window

Note
It is not necessary to have ISPFCS.EXE in the PATH statement, or the *.DLL
file in the LIBPATH statement if you execute from within its own directory.

If you do not see this window start-up, you should see some messages in your
OS/2 window. There is very little to go wrong at this stage. If the server did not
start, there are a few things you might want to check:

112

ISPF/SCLM V4 Guide

Could the download have been in ASCII format?


again.

Try downloading the code

Are you in an OS/2 and not a DOS window?


Are you executing from within the directory that contains both the executable
file and the *.DLL file?
Do you see any *.DLL files in this directory? You should.
This window is not a working (that is, usable) window. It is there to represent
the server task that is running. With this task running, your workstation will be
able to respond to the MVS host when it requests GUI mode. Even after starting
an ISPF GUI session, you will see no changes in this window.
Once you have this window running, you can proceed to 4.5, Connecting the
MVS Host in GUI on page 114.

4.4.1.1 Building an Icon for OS/2


The following steps outline how to create an icon for the ISPF server
(workstation) code:
1. Look in the OS/2 System Folder for an icon called Template. Inside this
folder you will find an icon called Program.
2. Click the left mouse button, and drag the icon to your desktop (or a folder if
you prefer).
3. You will soon be presented with a setting folder similar to what is shown in
Figure 94.

Figure 94. Settings Window for Workstation Icon

4. Fill in the drive letter, directory name and ISPFCS.EXE in the Path and file
name field.
5. You must also set the working directory to the same directory you have the
*.DLL file in. If you don't, ISPFCS.EXE will not be able to locate it.
(Alternatively, you could place the *.DLL in a directory already in the

Chapter 4. Graphical User Interface (GUI)

113

LIBPATH, or you could edit CONFIG.SYS and add your directory to the
existing LIBPATH search argument.)
6. Select the tab for General, and enter the Title you would like to have under
the Icon.
7. Close the settings window. You should see the icon adopt the ISPF logo. It
should appear similar to Figure 77 on page 97. Try double clicking on the
icon to ensure that the server starts.

4.4.2 DOS/Windows Environment


Before making the GUI connection, the Windows user must activate the
workstation server code. The workstaion portion of ISPF runs as a Windows
application, and can be activated in whatever method the user would normally
use in the windows environment. After successfully running this Windows
application, a window similar to that found in Figure 93 on page 112 will appear.
This window is not a working (that is, usable) window. It is there to represent
the server task that is running. With this task running, your workstation will be
able to respond to the MVS host when it requests GUI mode. Even after starting
an ISPF GUI session, you will see no changes in this window.
Once you have this window running, you can proceed to 4.5, Connecting the
MVS Host in GUI.

4.5 Connecting the MVS Host in GUI


There are two different methods for establishing ISPF in GUI mode. The
workstion server program must be up and running prior to attempting to invoke
ISPF in GUI mode.
For the following section, you can be connected to the host using any host 3270
emulator package. For example, you could use TCP/IP to TELNET to the MVS
host, and then use APPC to support the GUI connection.

4.5.1 From the Ready Prompt


For TCP/IP, the command you would use is:
ISPSTART GUI(IP:xxx.xxx.xxx.xxx)
where xxx.xxx.xxx.xxx is your IP address as used in section 4.2.3, IBM TCP/IP
for OS/2 on page 99.
For an APPC connection, the command is:
ISPSTART GUI(LU:NETNAME.LUNAME)
where NETNAME is the network name of the network your workstation is
attatched to, and the LUNAME is the name of an independent (LU6.2 capable)
logical unit at your workstation. These are the same values referred to in 4.2.4,
APPC for IBM CM/2 on page 103.
You can supply your usual ISPSTART parameters (for example, NEWAPPL,
PANEL, etc) as well as some new ones. See 4.8.3.1, Making an Application
Display in GUI Mode on page 123 for more information.

114

ISPF/SCLM V4 Guide

If you are not able to establish ISPF GUI, try the section 4.5.3, Troubleshooting
on page 115 for some hints.

4.5.2 From within ISPF


1. Using either the pull-down menus or from the command line, select Settings.
From within Settings, you should see a new action bar across the top. One
of the options is GUI.
2. Pull down the GUI menu, and then select the first option listed, Start GUI....
You should now be looking at a panel similar to that shown in Figure 95.

Figure 95. Initiating a GUI Session from Within ISPF

Note
You cannot exit from this panel if you have selected Start GUI session.
You must either use the cancel command or else deselect the option
first.
3. Select Start GUI, and enter either your IP address or your APPC
NETWORK.LUNAME. The GUI Title will appear in the window title bar once
ISPF GUI is operating in GUI mode.
4. Press Enter and wait a few seconds for the connection to be established. If
you don't establish the connection, try the section 4.5.3, Troubleshooting
for some hints.

4.5.3 Troubleshooting
4.5.3.1 General
When an attempt is made to start ISPF in GUI mode (using either of the two
methods) and it fails, there is only one message issued. If you enter MSGID on
the command line after receiving this message, you should see the message
number, ISPO906. The text is as follows:
Cannot connect to the workstation. Ensure that the communications from MVS to
the workstation are functioning and that the correct level of the ISPF
Client/Server component is running on the workstation. Also, make sure that you
entered the correct machine address.

Chapter 4. Graphical User Interface (GUI)

115

The workstation server code must be at the same maintenance level as the MVS
host C/S portion of the code. Try downloading a new copy of the workstation
software.

4.5.3.2 TCP/IP
If you can PING the MVS host with TCP/IP, then as far as ISPF is concerned you
have adequate connectivity. With TCP/IP in OS/2, you should be able to go to an
OS/2 session and type PING < h o s t IP address>. If that is successful, then you
can probably look elsewhere for your problem.
With IBM TCP/IP, if you want to verify your TCP/IP settings, type netstat -a at an
OS/2 prompt.
Again, with IBM TCP/IP, you can type netstat -s to verify that your server has
acquired a socket and is listening. The ISPF workstation server uses port 15063.
Just in case, try this command before starting the workstation server, and then
again after starting it. You should see 15063 change to connected on a new
socket.
Note
It is possible to enter another user's TCP/IP or APPC address when starting
GUI, and have ISPF GUI appear successfully on this user's screen.
(Provided, of course, that the other user has already started the workstation
server.) Since ISPF 4.1 provides no message saying GUI successful, your
attempt will appear to have failed, and your 3270 session will appear hung in
x-clock.

4.5.3.3 APPC
If your VTAM guru has seen the ATB050I message, and you're reasonably
certain that you've configured CM/2 correctly, then a likely place to look into is
the path from the MVS host to your workstation. Your problem could be one of
the can't get there from here variety. In particular, it be necessary to have
cross-domain resource definitions for the APPC/MVS base LU on intermediate
VTAM domains.
Cross-domain resource definitions may be required in any intermediate domains
in the SNA network, if the MVS host running ISPF and the LUs do not reside in
the same domain.

4.6 Running GUI


This section deals with some of the notable differences (surprises) that a user
might encounter when running IPSF in GUI mode. Since some of these
differences may cause problems for a user new to the GUI environment, it is
recommended that new users read this section prior to using the ISPF GUI.
The Primary Option Menu for ISPF, when running in GUI mode, will look
something like Figure 96 on page 117

116

ISPF/SCLM V4 Guide

Figure 96. ISPF Primary Option Menu in GUI

4.6.1 Interacting with GUI Panels


The overall feel of using ISPF in GUI mode will take some getting used to if you
are not already familiar with graphical, PC based software. The old style of
using ISPF still works (for example, command prompt commands such as 2 or
=3.4), but this might not be the best way to get around in GUI.
A user familiar with Windows, Macintosh* or OS/2 based environments will find
ISPF GUI quite facile.

4.6.1.1 Host Session Keys Versus PC keys


One of the first things to catch traditional ISPF users is the Enter key. The host
Enter key, located at the bottom right of the main keypad, no longer functions as
a host Enter key. You must use the PC Enter key! This can be particularly
irksome when you are used to using the PC Enter key similar to a tab key: at the
top of a edit list panel, you press the Enter key 8 times to tab down to a member,
only to wait for 8 full enters to be processed at the host!
The PC Enter key as used by ISPF GUI is in accordance with the CUA 89
guidelines.
It is not possible to use the tab key to reach the action bar items in ISPF GUI
mode.

4.6.1.2 Getting Around


Any raised section of a panel is selectable by clicking the mouse. As you can
see from the main panel, all the function keys are mouse selectable. You can
even click on Enter instead of using the Enter key.
In GUI mode, the advantage of having pull-down menus becomes clear. The
Menu pull down is especially effective. With two clicks of the mouse, you can go
from your current panel to any of the primary option functions. And dialogs are

Chapter 4. Graphical User Interface (GUI)

117

nested: if you use the Menu pull-down from Edit to View another member, when
you press F3 to exit, you are returned to your original Edit dialog.
Utilities are also conveniently accessed from a pull-down.
In Figure 96 on page 117, the Status area has been set to Calendar. By
changing a profile variable (see 2.6, Status Area on page 75), you can click on
any date to see a daily memo.

4.6.1.3 Residual 3270 Session


Another thing you will notice is that your original 3270 session remains visible
behind your GUI screen. ISPF GUI uses this session to communicate with the
MVS host. This session is unusable so long as GUI ISPF remains active. Do not
try to enter any commands! The best thing to do is to minimize it.

4.6.1.4 Split Screen


When you split screen in GUI mode, you will get an entirely separate GUI
window created. Testing revealed that these two screens do not have
multitasking capabilities.
It is possible to position the two windows on the screen so that the mouse can
be used instead of the swap key. This allows ISPF GUI to appear more
integrated into the workstation environment.

4.6.1.5 TSO Commands


ISPF GUI is not capable of handling line-mode output. TSO commands all have
line mode output. Consequently, any TSO commands entered on the ISPF GUI
command line will appear to be ignored. If you return to your 3270 session, you
should see the command output. If you see three asterisks, your GUI session
will be frozen until you press Enter on the 3270 session.
Note
There is a variety of ways that the 3270 screen can be placed in an output
wait (that's when you see three asterisks waiting for the Enter key to be
pressed). HSM, abends and messages can all potentially put the screen into
a wait. It is important to keep this in mind if the GUI session ever appears to
be hung.

Line mode output will not disrupt your GUI session beyond this. It is highly
probable that this problem will be corrected in a future release.

4.6.1.6 Workstation Commands


In GUI mode, option 6 allows the user to enter workstation commands. In the
OS/2 environment, the executable functions are limited to EXE, COM and CMD
suffixed commands (ISPF uses the OS/2 DosStartSession call). This means that
OS/2 commands that are part of the OS/2 kernel are not available (for example,
DIR). See Figure 97 on page 119 for an example of the ISPF Command Shell.
To enter a workstation command, a user can either use the WS command prefix,
or pull down the Function menu to set the default command to workstation. TSO
commands can still be entered in this mode by prefixing commands with TS.

118

ISPF/SCLM V4 Guide

Figure 97. ISPF Command Shell GUI

Note that you can use the mouse to retrieve previous commands.
If you're testing this service, your best example would be to try to invoke the E
or EPM editors.

4.6.1.7 Window Size


Depending upon the graphics adapter, the size of your monitor and personal
preference, user may want to change the size of the GUI mode screen. Although
the GUI window cannot yet be sized in by the click and drag method, there are
some things that can be changed to suit individual situations.
Two parms, GUISCRW and GUISCRD, can be used to change the number of
columns and rows displayed by the GUI window. See section 4.8.3.3, GUI Panel
Size on page 125 for more information on these parms.
Further customization can be had by changing workstation font sizes. In OS/2,
clicking and dragging a new font from the Font Palette is all that is required.
The Font Palette is usually found in the System Setup folder, inside the OS/2
System folder.

4.6.1.8 GUI Colors


ISPF 4.1 has a wide array of color customization options. In GUI mode this is no
exception. There are only two areas a user might find surprising.
The first is that ISPF in GUI mode does not yet support character attribute level
color. This limitation reveals itself in a few instances, most notably in the status
area calendar. Both the current date and dates with reminders attached will be
uniform with the color of the entire calendar. In addition, color sensitive editor
functions (edit hilite, see 2.5.2, Edit Hilite on page 72) have no effect in GUI.
Chapter 4. Graphical User Interface (GUI)

119

Unavailable pull-down menu choices are also affected by this. There is little
doubt this limitation will be addressed in a future release.
A second item to watch out for is when making a Global Color change. You will
not be able to view any of your color changes made on this panel unless you
have selected color control option Host colors for non-CUA attributes only.
The Colors pull-down menu can be found in option 0, Settings

4.7 Performance Issues


Performance information in this section is simply as observed. There have been
no attempts to test or evaluate in an empirical fashion.

4.7.1 OS/2 Platform


The documented minimum for ISPF 4.1 is a 386 processor, a megabyte of hard
disk space, and at least 8 meg of RAM. It is apparent that the greatest
performance limitation on the client side of ISPF is the workstation's ability to
translate and display the data sent to it from the MVS host. If a user intends to
use GUI mode on a production (that is, all day) basis, a 386 based system will
not be considered adequate. By contrast, response times on a good 486 based
machine are considerably better.
Graphic drivers are not considered to be a decisive factor in performance.

4.7.2 DOS/Windows Environment


In the DOS/Windows environment, the GUI panels appeared to respond faster
than in the OS/2 environment. But, the 3270 telnet session required to make the
connection was considerable slower than the equivalent session in OS/2. This
meant that the DOS/Windows environment held only a small performance
improvement.

4.7.3 Network Performance


The topic of SNA/APPC performance is a vast topic, and because the workstation
can have little effect upon this performance, it will not be touched upon here.
Many appropriate tuning guides are available.
TCP/IP performance can be greatly influenced by parameters in the TCP/IP
configuration files. An excellent source of information on this subject is the
TCP/IP for MVS V3R1 Performance Tuning Guide.
A common performance limiting parameter in TCP/IP is the Maximum
Transmission Unit size. With IBM TCP/IP for DOS, the parameter to change is
called TCP.MSSDFLT, and its default is only 512! For a token ring, this value
should be 4400. MSSDFLT can be found in the *\ETC\TCPDOS.INI file.
No conclusive performance differences between an APPC and a TCP/IP based
connection were experienced.

120

ISPF/SCLM V4 Guide

4.8 ISPF GUI Applications


Practically any ISPF application can display on the workstation, but existing and
new function allows the application developer to create a workstation application
that looks more like a natively developed application.
This section describes functions and techniques that can be used to create ISPF
dialogs that appear best when displayed on the workstation. Advantages of
using ISPF Version 4.1 for writing workstation applications are also explored. 1

4.8.1 GUI Applications with ISPF?


While any non-GDDM ISPF application will display at the workstation without
change to the dialog from previous versions of ISPF, there are new functions in
ISPF Version 4.1 and existing functions in previous releases of ISPF that, when
used properly, produce an application that looks more like an application written
specifically for the workstation using traditional programming techniques, such
as a C program invoking OS/2 Presentation Manager functions directly.

4.8.2 Why Use ISPF C/S for GUI?


In Version 4.1, ISPF does not provide all of the graphical user interface (GUI)
controls that are currently available at the workstation, so why choose ISPF to
implement GUI applications? There are several reasons:
Easily modify existing applications
Many applications use ISPF services to display information. Frequently
these applications are very large, and rewriting these applications for the
workstation is not practical because of the sheer volume of work required.
By using ISPF C/S to GUIize your application, you will achieve the
workstation look and feel while maintaining much of the investment you have
already made in the legacy application. A facelift using new ISPF function
is much less labor-intensive and disruptive to your application than rewriting
the entire application to run on the workstation.
Use existing skills and tools
Rewriting an application for the workstation requires a new set of skills and
tools for the programmer. This represents a substantial expense both in
money and time. By using ISPF to write GUI applications, experienced
application developers are able to apply existing skills, learning only a
handful of new ISPF services and features. This greatly increases their
productivity and efficiency.
Maintain Central control
Host-based applications allow an installation a large degree of control that
workstation-based applications do not. Central distribution, maintenance,
and security are the undeniable advantages of host-based applications.
Workstations provide a huge challenge for organizations with a large user
base. They have to get the right version (for example, OS/2, Microsoft
Windows, AIX*, and HP/UX*) of a workstation application to the right users
and then make sure that they are kept up-to-date with the latest upgrades.
With host-based applications, such as ISPF, the application is centrally

ISPF GUI Applications is an near exact adaptation of IBM Document Number TR 29.1881, Writing GUI Applications with ISPF
Client/Server written by Scott McAllister and Bob Leah from PDF Development, North Carolina
Chapter 4. Graphical User Interface (GUI)

121

maintained so that distribution is literally instantaneous. Distribution is also


controlled with products, such as RACF, ensuring that access to applications
or data is limited to those who are authorized to it.
Provide one executable for all user interfaces
By using ISPF to write GUI applications, not only one set of source code, but
one set of executables can serve all of an installation's display devices. This
includes OS/2 workstations, DOS workstations running Microsoft Windows**,
and 3270 displays! No other product addresses all environments in their
native display technology with the same executable. This capability allows
for migration from 3270-based applications to workstation-based applications
at the desired rate of the corporation or individual.
The following figures (Figure 98 and Figure 99 on page 123) are the ISPF
Settings panel displayed on a 3270 and then on an OS/2 workstation in GUI
mode. They contrast the display of the same screen by ISPF in the two different
display modes. Notice the GUI (checkboxes, push buttons, mnemonics)
constructs that have automatically been displayed by ISPF.

Figure 98. ISPF Settings Panel in 3270 Mode Displayed on a 327x Emulator

122

ISPF/SCLM V4 Guide

Figure 99. ISPF Settings Panel in GUI Mode Display Using ISPF C/S

4.8.3 Writing ISPF GUI Applications


An ISPF dialog will display in GUI mode without any changes, but applying
certain guidelines to modify existing applications or develop new applications
can result in the application having more of a true workstation look-and-feel.

4.8.3.1 Making an Application Display in GUI Mode


First, an ISPF-based application can be made to display in GUI mode in two
ways. One way is to specify the GUI parameter on the ISPSTART command. This
parameter is added to the existing string of parameters used to start the ISPF
dialog. The GUI parameter requires an IP address (if using TCP/IP for
communicating with the workstation) or an LU (if using APPC for
communications). The format for specifying the GUI parameter is :
GUI(IP:address)

or
GUI(LU:address).

In either case, address is the LU or IP address. See 4.4, Starting the


Workstation Server on page 112 for more information.
The challenge to the application developer is to make the application
user-friendly by not making users specify their own LU or IP address. The
following code segment from a REXX program alleviates this problem by
mapping user IDs to IP addresses. The program allows users to specify their
own IP address if they wish, but defaults the address to a predefined value for
them.

Chapter 4. Graphical User Interface (GUI)

123

id. = ''
id.BOB = '9.67.221.100'
id.SCOTT = '9.67.221.101'
id.MATT = '9.67.221.102'
/* List all userids and IP addresses here as shown in the */
/* three lines above
*/
parse arg ip_addr .
if ip_addr = '' then do
user_id = userid()
interpret 'ip_addr = id.'user_id
end
if ip_addr = '' then do
say 'Your user id is not mapped to an IP address.'
say 'You must specify an IP address.'
end
else do
'ISPSTART PANEL(XXX) NEWAPPL(YYY) GUI(IP:'ip_addr')'
end
It is important to note that ISPF in GUI can be initiated from a 3270 emulator or
from an NPT device. In the case of the latter, the display appears on the
workstation specified by the LU or IP address named.
When a session is in GUI mode, the ZGUI variable is set to the LU or IP address.
When a session is in 3270 mode, the ZGUI variable is blank.

4.8.3.2 Specifying the Title Bar Text


The text that appears in the title bar is controlled in three ways:
ZWINTTL variable
The ZWINTTL variable has existed in ISPF since Version 3.1. It controls the
window title that appears in pop-up windows. The value in this variable, if
defined, appears in the title bar of panels that have had an ADDPOP issued
prior to the display of the panel.
ZAPPTTL variable
The ZAPPTTL variable is new for ISPF Version 4.1. If ZWINTTL has not been
set, then the value in this variable controls the window title. It is intended to
be used by an application to set its default window title. This value is used
even if the panel has not had an ADDPOP issued prior to the display of the
panel.
TITLE parameter on ISPSTART
The TITLE parameter on the ISPSTART command is new for ISPF Version 4.1.
The format is:

ISPSTART ... TITLE(text).

Where text contains the text to appear in the title.


For panels that are displayed after an ADDPOP, and ZAPPTTL and ZWINTTL
have not been set, then the value specified on the TITLE parameter appears
in the title bar. For panels that have not had an ADDPOP issued before the
display of the panel, then only ZAPPTTL is examined. If it has not been set,
then the value specified on the TITLE parameter appears in the title bar. If no

124

ISPF/SCLM V4 Guide

value has been specified on the TITLE parameter, then the default title text is
the user ID from which the ISPSTART command was issued.

4.8.3.3 GUI Panel Size


The maximum size panel that is displayed at the workstation is controlled by the
GUISCRW and GUISCRD parameters on the ISPSTART command. These
parameters allow the user to specify a width from 80 to 160 characters and a
depth from 24 to 62 characters inclusive. For example:

ISPSTART ... GUISCRW(98) GUISCRD(35).


Any combination of these values is accepted. The default value is the actual
screen depth and width of your emulator or NPT device.
The WINDOW parameter on the )BODY statement also controls the size of the GUI
panel. This is only used, however, on the display of a panel that follows an
ADDPOP. When the WINDOW parameter is specified, the panel has the number of
rows and columns specified on the parameter (less the number of action bars
and action bar separator line) displayed in the client area of the GUI display.
Any lines explicitly coded in a panel appear in the GUI panel even if they are
blank. Lines are not, however, automatically added to fill the panel to the screen
depth.

4.8.3.4 Window Frame


Three types of window frames are supported in ISPF V4.1. They are:
standard

a window frame that has the system icon and max/min icons and is
resizable.

fixed

a window frame that has the system icon and a min icon and it is not
resizable.

dialog

a window frame that does not have the system icon or the max/min
icons; it is not, therefore, resizable, but can be minimized by the icon
in the upper left-hand corner.

The type of window frame appearing at the workstation can be controlled by the
FRAME parameter on the ISPSTART command. By specifying FRAME(STD),
FRAME(FIX), or FRAME(DLG), the frame can be set to standard, fixed, or dialog
respectively.
The frame may also be set when entering GUI mode from the Initiate GUI
Session panel from the GUI action bar on the Settings panel, as show in
Figure 100 on page 126.
In either case, there is no way to control window frames once the user has made
this selection.
Panels that appear after an ADDPOP always appear in dialog boxes.

Chapter 4. Graphical User Interface (GUI)

125

Figure 100. Initiate GUI Session Panel Showing GUI Window Frame Option

4.8.3.5 Function Keys


The function key area is displayed as a series of push buttons in GUI mode.
This happens whether the function keys are defined as keylists or as ZPF
variables. This happens automatically without any action by the user or the
application developer. The display of the function keys is controlled by the FKA
command as on the host. If FKA OFF is issued, then no function keys or push
buttons are displayed.
The text on the push button is controlled by the keylist definition or by the ZPFL
and ZPF variables. It always appears centered on the key. This cannot be
changed. The F = or P F = can be removed from the push button by entering the
FKA NOPREFIX command or from an application by issuing the SELECT
PGM(ISPOPF) PARM(FKA NOPREFIX) NOFUNC SUSPEND service. The prefix may be
restored by entering the FKA PREFIX command or from an application by issuing
the SELECT PGM(ISPOPF) PARM(FKA PREFIX) NOFUNC SUSPEND service.
The function keys still perform as always. In addition, the user may press the
push button to invoke the function assigned to the function key or push button.

4.8.3.6 Enter Key


The Enter key appears, by default, as a push button ahead of and in line with the
function keys if the function keys are displayed. If the function keys are not
displayed, it appears alone.
The ZENTKTXT variable can be modified by the application developer to change
the text appearing on the Enter key. By setting &ZENTKTXT = 'OK' in the )INIT
section of a panel, for example, the Enter key text can be changed to OK. If the
ZENTKTXT variable is set to blank, the Enter key is will not displayed.

126

ISPF/SCLM V4 Guide

4.8.3.7 CUA Attributes


The use of ISPF CUA (Common User Access) attribute types is strongly
recommended for developing GUI applications. CUA attribute types can be used
by writing panels in the Dialog Tag Language (DTL) or by writing panels in the
traditional ISPF panel language. The following attribute types are considered
CUA attribute types:
AB

Action bar unselected choices - This attribute must be used to define


action bars. Action bars will appear as native workstation action bars
automatically at the workstation.

ABSL

Action bar separator line - This attribute must be used to define the
separator line between the action bars and the client area of the
panel. Anything on this line will be ignored on the GUI display.

CEF

Choice entry field - This attribute is normally used on single-selection


and multi-selection fields. These fields ask for a numerical selection
or slash (or checkbox in GUI mode) selection respectively.

CH

Column heading - This attribute is normally used for column and


group headings.

CT

Caution text - This attribute is normally used in normal and


descriptive text or panel instructions to warn the user of a potential
hazard.

DT

Descriptive text - This attribute is normally used for free text on a


panel. The differences between descriptive text, normal text, and
panel instructions (PIN type) is up to the application developer. The
DTL uses this type for the DTAFLDD tag descriptors.

EE

Error Emphasis - This attribute is normally used in descriptive text or


panel instructions to indicate that an error has occurred.

ET

Emphasized text - This attribute is normally used in normal and


descriptive text or panel instructions to make text stand out from the
other text.

FP

Field prompt - This attribute is normally used to mark the text and
ellipses that comprise an input field prompt.

LEF

List entry field - This attribute is normally used for table (TBDISPL)
input fields.

LI

List items - This attribute is normally used for table (TBDISPL) output
fields.

LID

List item description - This attribute type is not used by the DTL.

NEF

Normal entry field - This attribute is normally used for input fields that
are not selection fields or list entry fields. For example, any textual
input fields or a command line would typically be normal entry fields.

NT

Normal text - This attribute is normally used for free text on a panel.
The differences between descriptive text, normal text, and panel
instructions (PIN type) is up to the application developer.

PIN

Panel instructions - This attribute is normally used for free text on a


panel. The differences between descriptive text, normal text, and
panel instructions (PIN type) is up to the application developer. The
DTL uses this type for the BOTINST and TOPINST tag text.

Chapter 4. Graphical User Interface (GUI)

127

PS

Point-and-shoot - This attribute is one way of defining point-and-shoot


fields. These are discussed in 4.8.3.12, Push Buttons on page 131
because point-and-shoot fields appear as push buttons on the
workstation.

PT

Panel title - This attribute is normally used to mark the title of the
panel. This is not to be confused with the window title that appears in
the title bar.

RP

Reference phrase - This attribute must be used to define reference


phrases. Reference phrases behave much like hypertext links.

SAC

Select available choices - This attribute is normally used to indicate


an alternative for the user. For example, the text for a multi-selection
or single selection field (CEF type) is typically a SAC type.

SI

Scroll information - This attribute is used for the More: - +


indicator. DTL does not use this attribute type.

SUC

Select unavailable choices - This attribute is normally used to indicate


that a choice that normally would be available as an action by the
user (SAC type) is not available at this time. Unavailable pull-down
choices are automatically made SUC fields by ISPF when they are not
available.

VOI

Variable output information - This attribute is normally used to display


output information on a panel that may change between two displays
of the panel. For example, the date on a panel, where the application
developer does not want to allow a user to change the value, may be
specified with a VOI attribute type. The DTL uses this type for output
fields that contain variables.

WASL

Work area separator line - This attribute is normally used to separate


horizontal or vertical logical areas on the screen. For example, if the
top portion of the panel contains a scrollable list of objects and the
bottom portion contains a list of actions, the two areas would be
delineated by a WASL attribute.

WT

Warning text - This attribute is normally used in normal and


descriptive text or panel instructions to indicate that an error has
occurred or is about to occur.

Using CUA attributes on panels, rather than simple color and highlighting
characteristics, allows ISPF to know what text on a panel portrays, not just its
physical characteristics.
The application developer should specify PADC(USER) on all entry fields. (Use
the padc=user attribute on the PANEL tag in DTL.) The field will have the CUA
default highlighting of USCORE, but will not have underscores in the input fields
when in GUI mode, as is the case when PADC(_) is specified. For the user on a
nonextended data stream 3270 terminal, the pad character can be changed from
N (null) to _ so that input fields appear underscored.

4.8.3.8 Action Bars and Pull-down Menus


Action bars and pull-down menus are displayed at the workstation just like the
action bars of any workstation application. The pull-down menus can be
browsed without any interrupts to the host as happens on 3270-displayed
pull-down menus.

128

ISPF/SCLM V4 Guide

In order to do this, ISPF must process all )ABCINIT sections for all action bars
prior to the display of the panel. For this reason, the application developer
should not code a .RESP=ENTER in the )ABCINIT section. An application might
use this technique to not show a pull-down menu when an action bar is selected.

4.8.3.9 Mnemonics
Mnemonics are represented in GUI displays by an underscore character under a
character in an action bar or pull-down choice. When the ALT key and the
character with the underscore are pressed simultaneously, the action bar is
automatically selected, and the pull-down menu is displayed.
Mnemonics are supported in ISPF Version 4.1 for GUI mode only. An application
developer can define the mnemonics in DTL or in traditional ISPF panel
language.
In DTL, the mnemonics are automatically generated when compiled with the
Version 4.1 DTL Conversion Utility (ISPDTLC). ISPDTLC ensures that there are
no redundant mnemonics. An application developer can manually assign
mnemonics in DTL by specifying < m > before the character in the action bar or
pull-down choice text that is to be the mnemonic. For example, < a b > E < m > x i t
makes x the mnemonic for Exit. An application developer can specify < a b
m n e m g e n = n o > on the ab tag in order to prevent ISPF from generating
mnemonics. The default is to generate mnemonics ( < a b m n e m g e n = y e s > ) .
In traditional ISPF panel language, the mnemonics must be manually assigned.
This is done by specifying MNEM(n ) after the DESC keyword and value on the
)ABC or PDC statements. The character n indicates that the mnemonic is the nth
character in the description text.

4.8.3.10 Pop-up Windows


Pop-up windows (for example, panels that are displayed after an ADDPOP
service) are automatically displayed in a dialog box when running in GUI mode.
The user or the application developer does not have to take any action to make
this happen. The dialog is modal; meaning that the user cannot return the focus
to the panel below until dismissing the panel on top.
For information on modeless dialog boxes, refer to 4.8.3.14, User-driven
Applications on page 134.

4.8.3.11 Pop-up Messages


Messages that appear in pop-up windows on a 3270 display also appear in
message boxes on the workstation in GUI mode. If the message is defined with
the CUA severity .TYPE= parameter, then a corresponding icon for that severity
appears automatically in the message box. The .TYPE= parameter was
introduced in ISPF Version 3.1. Valid values are NOTIFY, WARNING, ACTION, and
CRITICAL in order of severity, lowest to highest. Figure 101 on page 130,
Figure 102 on page 130, Figure 103 on page 130, and Figure 104 on page 130
show message boxes with their respective icons. If the .TYPE= parameter is not
used, then the severity is assumed to be NOTIFY if .ALARM=NO and WARNING if
.ALARM=YES .

Chapter 4. Graphical User Interface (GUI)

129

Figure 101. A Message Generated from a .TYPE=NOTIFY Message Definition Displayed


Using ISPF C/S

Figure 102. A Message Generated from a .TYPE=WARNING Message Definition


Displayed Using ISPF C/S

Figure 103. A Message Generated from a .TYPE=ACTION Message Definition Displayed


Using ISPF C/S

Figure 104. A Message Generated from a .TYPE=CRITICAL Message Definition


Displayed Using ISPF C/S

The application developer can control whether or not a message appears in a


pop-up window (or message box in GUI mode) by setting the .WINDOW=
parameter on the message. The .WINDOW= parameter can be set to any of the
following values:
RESP

Specifies that the short and long messages appear in a pop-up and
that they are modal.

NORESP

Specifies that the short and long messages appear in a pop-up and
that they are modeless.

LRESP

Specifies that only the long message appear in a pop-up and that it
be modal.

LNORESP

Specifies that only the long message appear in a pop-up and that it
be modeless.

LRESP and LNORESP are new for ISPF Version 4.1.

130

ISPF/SCLM V4 Guide

Messages can also be defined using DTL. The < m s g > tag is used to define a
message. The msgtype parameter on the < m s g > tag defines the severity of
the message. The following is an example of the definition of two messages in
the ORDA00 message member.

<msgmbr name=orda00>
<msg suffix=0 location=modal>Your order is being processed.
<msg suffix-1 msgtype=warning>Your request for the engraving
option is not valid.
Please check your request, and correct it if necessary.
</msgmbr>
The msgtype parameter can be set to INFO, WARNING, ACTION, or CRITICAL.
These correspond to the .TYPE values of NOTIFY, WARNING, ACTION, and CRITICAL
respectively.
The location parameter specifies whether the message should appear in a
pop-up window or not. Valid values are:
MODAL

Specifies that the short and long messages appear in a pop-up and
that they are modal. This is equivalent to specifying .WINDOW=RESP
in an ISPF message member.

MODELESS Specifies that the short and long messages appear in a pop-up and
they are modeless. This is equivalent to specifying .WINDOW=NORESP

in an ISPF message member.


MODAL(L) Specifies that only the long message appears in a pop-up and that it
is modal. This is equivalent to specifying .WINDOW=LRESP in an ISPF

message member.
MODELESS(L) Specifies that only the long message appears in a pop-up and that
it is modeless. This is equivalent to specifying .WINDOW=LNORESP in

an ISPF message member.


AREA

Specifies that neither the short nor the long message appears in a
pop-up. This is equivalent to not specifying the .WINDOW= parameter
in an ISPF message member.

A user can force long messages into pop-up windows even if the application did
not specify that they appear in pop-ups. This is done on the ISPF Settings panel
by selecting the Long messages in pop-ups option.

4.8.3.12 Push Buttons


Push buttons appear in a GUI display in three ways:
Function keys in the function key area display as push buttons.
The Enter key displays as a push button if text is defined for the Enter key in
the ZENTKTXT variable.
Point-and-shoot fields display as push buttons.
The display of function keys is discussed in 4.8.3.5, Function Keys on
page 126. The display of the Enter key is discussed in 4.8.3.6, Enter Key on
page 126.
Point-and-shoot fields are new to ISPF Version 4.1. In 3270 mode,
point-and-shoot fields are fields on a panel that have a variable automatically set
to a value if the Enter key is pressed when the cursor is on the point-and-shoot

Chapter 4. Graphical User Interface (GUI)

131

field. The application is then able to take a specific action based on that value.
This interaction is analogous to push buttons on a GUI display and, therefore, is
represented as such automatically by ISPF.
In order to define point-and-shoot fields in traditional ISPF panel language, three
steps must be taken:
1. The attribute of the field must be defined as a point-and-shoot field. This can
be done in two ways:
PAS(ON) is specified for input and output fields, or
TYPE(PS) is specified for protected text fields.

2. A )PNTS section must be defined immediately before the )END statement.


3. The dialog should take an action based on the value set in the variable.
Each panel field specified as a point-and-shoot field must have a corresponding
entry in the )PNTS section. If a field specified as a point-and-shoot field has no
corresponding entry in the )PNTS section, no action is taken if the point-and-shoot
field is selected.
An entry requires each of the following keywords and values specified in the
following order:
FIELD(field_name| ZPS xxyyy )

The name of the field on the panel that the statement controls. For
point-and-shoot input and output fields, a field name is specified. For
point-and-shoot text fields, ISPF generates a field name starting with the
characters ZPS. The xx characters are 00 if the field is in the )BODY section or
01 to 99 indicating the relative location of a scrollable area to the upper-left
corner of the panel scanning from left to right and top to bottom. The yyy
characters are the relative number of the point-and-shoot field within the panel
body or scrollable area.
VAR( variable )

The name of the variable to be set when the field named in this statement is
selected.
VAL( value )

The value assigned to the variable named in this statement.


Point-and-shoot fields can also be defined in DTL. The < p s > tag defines a text
string that is a point-and-shoot field. The variable and value are defined within
this tag:

<ps var=variable value=value>text


</ps>
variable

The name of the variable to be set when the field named in this
statement is selected.

value

The value assigned to the variable named in this statement.

text

The text to appear on the panel.

The < p s > tag is valid as part of the text of the following information tags:
CAUTION, DD, DDHD, DT DTHD, FIG, FIGCAP, H2, H3, H4, LI, LINES, LP, NOTE, NT, P, PD,

132

ISPF/SCLM V4 Guide

PT, WARNING, and XMP; and on the following panel tags: BOTINST, CHOICE, DTAFLD,
DTAFLDD, GRPHDR, LSTCOL, LSTGRP, SELFLD, and TOPINST.

The following is an example of a portion of a DTL-defined panel that defines a


choice field as point-and-shoot text:

<region dir=vert indent=3>


<selfld type=menu selwidth=67 entwidth=5
choicecols=2 choicedepth=2 verify=no>
<choice selchar=S> <ps var=zcmd value=S>
Send PDS
</ps>
<choice selchar=P> <ps var=zcmd value=P>
Print PDS
</ps>
<choice selchar=M> <ps var=zcmd value=M>
Send message </ps>
</selfld>
</region>

4.8.3.13 Checkboxes
Multi-selection fields (slash entry fields) can be defined by the application
developer to automatically appear as checkboxes when displayed in GUI mode.
The prompt can even be changed dynamically to instruct the user to enter a
slash to select a field if in 3270 mode or select a checkbox if in GUI mode.
Using the traditional ISPF panel language, a single character input field can be
changed to a checkbox by specifying .ATTR(field_name)='CKBOX(ON)' in the )INIT
section of the panel. Alternately, an attribute can be specified with the
CKBOX(ON) value in conjunction with an input type (for example, CEF, NEF, or
INPUT) to make that attribute a checkbox. By testing the ZGUI variable in the
)INIT section, the application developer can define different prompt text for the
multi-selection fields as shown in the following example:

IF (&ZGUI = ' ')


&MULTIPMT='Enter "/" to select option'
ELSE
&MULTIPMT='Check box to select option'
This is the technique used by the DTL Conversion utility.
When defining a panel using DTL, the application developer need only specify a
field-prompt-text of &multipmt; to have ISPDTLC generate the code to support
checkboxes. The following is an example of DTL that defines checkboxes for
multi-selection fields:

<selfld type=multi selwidth=38 pmtwidth=36>&multipmt;


<choice name=zpl help=ispop41
>Command line at bottom

Chapter 4. Graphical User Interface (GUI)

133

4.8.3.14 User-driven Applications


One of the requirements for a CUA dialog is that the dialog be a user-driven
application. This means that users can select one subfunction of an application
and, without exiting that subfunction, select another subfunction. These
sub-functions might each originate from the same panel so that users do not
have to back out of the application; users can go where they wish in the
application. In order to achieve this, ISPF has added the START service. For GUI
mode, split screen results in two independent workstation windows, not one
window split in half as on a 3270 display.
Users see the two independent workstation windows automatically without any
action on the part of the application developer or users. The two windows are
synchronously multitasking. Either can receive focus, but in order for processing
to occur, the other must be in a wait state.
ISPF-based applications historically have not been written in a user-driven way.
The START service was created in ISPF Version 4.1 to help the application
developer write user-driven applications. When the START service or ISPSTRT
program is invoked, ISPF starts a new logical screen (GUI window) invoking the
SELECT service or command passed to it.
With ISPF Version 4.1, there is still a limitation of only two logical screens. If two
logical screens already exist, ISPF starts the application in the opposite logical
screen from which it was invoked. The following are examples of how to invoke
the START service:
To invoke a dialog in another screen from a pull-down choice, the application
developer can code:

ACTION RUN(START) PARM(<some_dialog>)


on a PDC statement in the )ABC section.
To invoke a dialog or command in another screen from a selection panel, the
application developer can code:

&ZSEL = TRANS(&ZQ
0,'PGM(ISPSTRT)
1,'PGM(ISPSTRT)
2,'PGM(ISPSTRT)
3,'PGM(ISPSTRT)

PARM(PGM(ISPISM))'
PARM(PGM(ISPBRO) PARM(ISRBRO01))'
PARM(ROUTE ED1)'
PARM(PANEL(ISRUTIL))'

To invoke a dialog or command in another screen from an application, the


application developer can code:

ISPEXEC SELECT PGM(ISPSTRT) PARM(<some_dialog>)

<some_dialog> can be any of the following:


A command from the command table; for example KEYLIST
A command with parameters (must be in quotes); for example, 'ISRROUTE
BR1'

A dialog invocation; for example, PANEL(ISRUTIL) or 'PGM(ISREDIT)


PARM(P,ISREDM01)'

<some_dialog> cannot exceed 249 characters.


134

ISPF/SCLM V4 Guide

4.8.3.15 SELECT WSCMD service


The SELECT WSCMD service allows an application to modelessly invoke a
workstation command from the host dialog. The application must be running in
GUI mode in order for this service to function. The format for the service is:

SELECT WSCMD(<ws_command>)
where <ws_command> is any workstation command as it is entered at the
workstation, fully qualified or not.
Since the command is modelessly invoked, focus can be returned to the host
application at any time.
An interesting application of this function is on a selection menu. Adding
11,'WSCMD(WP)' to a selection menu makes option 11 seamlessly invoke
WordPerfect** from the host. The user does not need to know that the
application is a workstation application; it is just option 11.
The following is a portion of a panel definition that has a point-and-shoot field on
a selection panel that invokes WordPerfect at the workstation.

)ATTR
# TYPE(SAC)
! TYPE(NT)
$ TYPE(PS)
.
.
.
)BODY
.
.
.
# 0 $Settings
!Terminal and user parameters
# 1 $View
!Display source data or listings
# 2 $Edit
!Create or change source data
# 3 $Utilities
!Perform utility functions
.
.
.
#11 $WordPerfect !Workstation word processor
.
.
.
)PROC
.
.
.
&ZSEL = TRANS ( TRUNC (&ZCMD,'.')
0,'PGM(ISPISM)'
1,'PGM(ISRBRO) PARM(ISRBRO01)'
2,'PGM(ISREDIT) PARM(P,ISREDM01)'
3,'PANEL(ISRUTIL)'
.
.
.
11,'WSCMD(WP)'
Chapter 4. Graphical User Interface (GUI)

135

X,EXIT
' ',' '
*,'?' )
.
.
.
)PNTS
.
.
.
FIELD(ZPS01001)
FIELD(ZPS01002)
FIELD(ZPS01003)
.
.
.
FIELD(ZPS01012)
)END

VAR(ZCMD) VAL(0)
VAR(ZCMD) VAL(1)
VAR(ZCMD) VAL(2)

VAR(ZCMD) VAL(11)

4.8.3.16 What is not Supported?


ISPF C/S does not support panels that have GDDM display requests. In such
cases, the user can direct the display back to a 3270 display. This is the only
way the user can change from a GUI display back to a 3270 display.
Character attribute override is also not supported in ISPF C/S. This is the ability
to change the color of every character, without using the usual intervening
attribute character.
Line-mode output is still displayed on a 3270 display. This data is not captured
in any way by ISPF and subsequently displayed at the workstation.

4.9 Sample GUI Application - Calculator


The following is a sample ISPF application written specifically for GUI mode. It is
a calculator that has an action bar controlling the mode (decimal or
hexadecimal). The keys appear as push buttons as the user would expect of a
GUI application.

4.9.1.1 The CALCDEMO REXX EXEC


The following is the program that drives the application. It is invoked from the
ISPF command line by entering TSO CALCDEMO.

/* REXX */
address 'ISPEXEC'
a=0; b=''; m=0; cp=0; sav_op='+'
'ADDPOP'
'SELECT PGM(ISPOPF) PARM(OFF)'
'SELECT PGM(ISPOPF) PARM(FKA NOPREFIX)
zero_divide = 'CALC001'
overflow
= 'CALC002'
opp = 0
mode = 'Dec'
do while key = 'X'
if (m = 0) then mtxt = 'Memory =' m
else mtxt = ''
136

ISPF/SCLM V4 Guide

/* init vars
*/
/* Place in dialog frame */
NOFUNC SUSPEND'
/* Set message constants */
/* init mode
/* loop until off hit
/* set memory display

*/
*/
*/

key = ' '


/* init key hit
*/
if mode = 'Dec' then 'DISPLAY PANEL(CALCD)'
else 'DISPLAY PANEL(CALCH)'
/* display right panel
*/
if b = 'Error' then b = '0'
/* convert error to 0
*/
select
when (key = 'MH') then
/* change to hex mode
*/
do
if b = '' then b = '0'
i = index(m,'.')
if i > 1 then m = substr(m,1,i-1)
if i = 1 then m = 0
m = d2x(m)
i = index(b,'.')
if i > 1 then b = substr(b,1,i-1)
if i = 1 then b = 0
b = d2x(b)
end
when(key = 'MD') then
/* change to decimal mode */
do
m = x2d(m)
b = x2d(b)
end
when(index('+-*/',key) = 0 & mode = 'Dec') then
do
/* operator & in dec mode */
if sav_op = '/' then
do
if b = 0 then
do
b = 'Error'
'SETMSG MSG('zero_divide')'
end
else
do
a = a / b
sav_op = key
b = a
end
end
else
do
interpret 'A='||a sav_op b
sav_op = key
b = a
end
opp = 1
end
when(index('+-*/',key) = 0 & mode = 'Hex') then
do
/* operator & in hedec mode */
if sav_op = '/' then
do
if b = 0 then
do
b = 'Error'
'SETMSG MSG('zero_divide')'
end
else
do
a = a / x2d(b)
sav_op = key
Chapter 4. Graphical User Interface (GUI)

137

i = index(a,'.')
if i > 1 then a = substr(a,1,i-1)
if i = 1 then a = 0
b = d2x(a)
end
end
else
do
interpret 'A='||a sav_op 'x2d('||b||')'
sav_op = key
b = d2x(a)
end
opp = 1
end
when(index('.0123456789',key) = 0 & mode = 'Dec') then
do
/* digit & in decimal mode */
if length(b) > 15 then
do
'SETMSG MSG('overflow')'
end
else
do
if opp then b = key
else b = b||key
opp = 0
end
end
when(index('0123456789ABCDEF',key) = 0 & mode = 'Hex') then
do
/* digit & in hex mode
*/
if length(b) > 15 then
do
'SETMSG MSG('overflow')'
end
else
do
if opp then b = key
else b = b||key
opp = 0
end
end
when(key = '=' & mode = 'Dec') then /* = sign in decimal mode */
do
if sav_op = '/' then
do
if b = 0 then
do
b = 'Error'
'SETMSG MSG('zero_divide')'
end
else
do
a = a / b
sav_op = key
b = a
end
end
else
do
interpret 'A='||a sav_op b
138

ISPF/SCLM V4 Guide

sav_op = key
b = a
end
sav_op = '+'
a = 0
opp = 1
end
when(key = '=' & mode = 'Hex') then /* = sign in hex mode
do
if sav_op = '/' then
do
if b = 0 then
do
b = 'Error'
'SETMSG MSG('zero_divide')'
end
else
do
a = a / x2d(b)
sav_op = key
i = index(a,'.')
if i > 1 then a = substr(a,1,i-1)
if i = 1 then a = 0
b = d2x(a)
end
end
else
do
interpret 'A='||a sav_op 'x2d('||b||')'
sav_op = key
b = d2x(a)
end
sav_op = '+'
a = 0
opp = 1
end
when(key = 'MC') then
/* clear memory
do
m = 0
end
when(key = 'MR') then
/* recall memory
do
b = m
opp = 0
end
when(key = 'M-') then
do
/* subtract from memory
if mode = 'Dec' then m = m - b
else
do
n = x2d(m) - x2d(b)
m = d2x(n)
end
end
when(key = 'M+') then
/* add to memory
do
if mode = 'Dec' then m = m + b
else
do

*/

*/

*/

*/

*/

Chapter 4. Graphical User Interface (GUI)

139

n = x2d(m) + x2d(b)
m = d2x(n)
end
end
when(key = 'Z') then
do
if cp = 0 then
b = ''
else
do
a = 0
b = ''
sav_op = '+'
opp = 0
end
end
otherwise nop
end
end
'REMPOP'
'SELECT PGM(ISPOPF) PARM(ON)'
'SELECT PGM(ISPOPF)'
exit 4

/* clear

*/

/* all clear

*/

/* remove pop-up
/* fka short

*/
*/

4.9.1.2 The CALCD Panel


The following is the traditional ISPF panel language definition of the decimal
mode panel. Figure 105 shows the panel displayed in GUI mode.

Figure 105. Sample Calculator in Decimal Mode

)PANEL KEYLIST(ISRSAB,ISR)
)ATTR DEFAULT([]?)
@ TYPE(PS)
$ TYPE(FP)
! TYPE(NEF) JUST(RIGHT) PADC(NULLS)
TYPE(VOI)
( TYPE(AB)
) TYPE(ABSL)
)ABC DESC('Modes')
PDC DESC('Decimal') UNAVAIL(ABD)
ACTION RUN(DEC)
PDC DESC('Hexadecimal')
ACTION RUN(HEX)
)ABCINIT
140

ISPF/SCLM V4 Guide

.ZVARS=CALCPDC
)BODY WINDOW(25,14) CMD()
$( Modes $
$
)-----------------------$
$
$
!B
$
$ Mode:MODE
$
$ @ 1 $@ 2 $@ 3 $ @ + $ $
$ @ 4 $@ 5 $@ 6 $ @ - $ $
$ @ 7 $@ 8 $@ 9 $ @ * $ $
$ @ 0 $@ . $@ = $ @ / $ $
$
$
$ @ C/CE $@ Off $ $
$
$
$ @M+ $@M- $@MR $ @MC $ $
$ MTXT
$
)INIT
.CURSOR = &ZPS00017
&ABD = '1'
&CP = 0
&ZWINTTL = 'Calculator Sample'
&ZENTKTXT = ' '
)REINIT
&KEY = ' '
REFRESH(*)
)PROC
IF (&ZCMD='DEC')
&MODE = 'Dec'
&KEY = 'MD'
&ZCMD = ' '
IF (&ZCMD='HEX')
&MODE = 'Hex'
&KEY = 'MH'
&ZCMD = ' '
)PNTS
FIELD(ZPS00001) VAR(KEY) VAL(1)
FIELD(ZPS00002) VAR(KEY) VAL(2)
FIELD(ZPS00003) VAR(KEY) VAL(3)
FIELD(ZPS00004) VAR(KEY) VAL('+')
FIELD(ZPS00005) VAR(KEY) VAL(4)
FIELD(ZPS00006) VAR(KEY) VAL(5)
FIELD(ZPS00007) VAR(KEY) VAL(6)
FIELD(ZPS00008) VAR(KEY) VAL('-')
FIELD(ZPS00009) VAR(KEY) VAL(7)
FIELD(ZPS00010) VAR(KEY) VAL(8)
FIELD(ZPS00011) VAR(KEY) VAL(9)
FIELD(ZPS00012) VAR(KEY) VAL('*')
FIELD(ZPS00013) VAR(KEY) VAL(0)
FIELD(ZPS00014) VAR(KEY) VAL('.')
FIELD(ZPS00015) VAR(KEY) VAL('=')
FIELD(ZPS00016) VAR(KEY) VAL('/')
FIELD(ZPS00017) VAR(KEY) VAL('Z')
FIELD(ZPS00018) VAR(KEY) VAL('X')
FIELD(ZPS00019) VAR(KEY) VAL('M+')
FIELD(ZPS00020) VAR(KEY) VAL('M-')
FIELD(ZPS00021) VAR(KEY) VAL('MR')
FIELD(ZPS00022) VAR(KEY) VAL('MC')
)END

Chapter 4. Graphical User Interface (GUI)

141

4.9.1.3 The CALCH Panel


The following is the traditional ISPF panel language definition of the hexadecimal
mode panel. Figure 106 shows the panel displayed in GUI mode.

Figure 106. Sample Calculator in Hexadecimal Mode

)PANEL KEYLIST(ISRSAB,ISR)
)ATTR DEFAULT([]?)
@ TYPE(PS)
$ TYPE(FP)
! TYPE(NEF) JUST(RIGHT) PADC(NULLS)
TYPE(VOI)
( TYPE(AB)
) TYPE(ABSL)
)ABC DESC('Modes')
PDC DESC('Decimal')
ACTION RUN(DEC)
PDC DESC('Hexadecimal') UNAVAIL(ABH)
ACTION RUN(HEX)
)ABCINIT
.ZVARS=CALCPDC
)BODY WINDOW(25,16) CMD()
$( Modes $
$
)-----------------------$
$
$
!B
$
$ Mode:MODE
$
$ @ 1 $@ 2 $@ 3 $ @ + $ $
$ @ 4 $@ 5 $@ 6 $ @ - $ $
$ @ 7 $@ 8 $@ 9 $ @ * $ $
$ @ A $@ B $@ C $ @ / $ $
$ @ D $@ E $@ F $
$
$ @
0 $@ = $
$
$
$
$ @ C/CE $@ Off $ $
$
$
$ @M+ $@M- $@MR $ @MC $ $
$ MTXT
$
)INIT
.CURSOR = &ZPS00022
&ABH = 1
&CP = 0
&ZWINTTL = 'Calculator Sample'
142

ISPF/SCLM V4 Guide

&ZENTKTXT = ' '


)REINIT
&KEY = ' '
REFRESH(*)
)PROC
IF (&ZCMD='DEC')
&MODE = 'Dec'
&KEY = 'MD'
&ZCMD = ' '
IF (&ZCMD='HEX')
&MODE = 'Hex'
&KEY = 'MH'
&ZCMD = ' '
)PNTS
FIELD(ZPS00001) VAR(KEY)
FIELD(ZPS00002) VAR(KEY)
FIELD(ZPS00003) VAR(KEY)
FIELD(ZPS00004) VAR(KEY)
FIELD(ZPS00005) VAR(KEY)
FIELD(ZPS00006) VAR(KEY)
FIELD(ZPS00007) VAR(KEY)
FIELD(ZPS00008) VAR(KEY)
FIELD(ZPS00009) VAR(KEY)
FIELD(ZPS00010) VAR(KEY)
FIELD(ZPS00011) VAR(KEY)
FIELD(ZPS00012) VAR(KEY)
FIELD(ZPS00013) VAR(KEY)
FIELD(ZPS00014) VAR(KEY)
FIELD(ZPS00015) VAR(KEY)
FIELD(ZPS00016) VAR(KEY)
FIELD(ZPS00017) VAR(KEY)
FIELD(ZPS00018) VAR(KEY)
FIELD(ZPS00019) VAR(KEY)
FIELD(ZPS00020) VAR(KEY)
FIELD(ZPS00021) VAR(KEY)
FIELD(ZPS00022) VAR(KEY)
FIELD(ZPS00023) VAR(KEY)
FIELD(ZPS00024) VAR(KEY)
FIELD(ZPS00025) VAR(KEY)
FIELD(ZPS00026) VAR(KEY)
FIELD(ZPS00027) VAR(KEY)
)END

VAL(1)
VAL(2)
VAL(3)
VAL('+')
VAL(4)
VAL(5)
VAL(6)
VAL('-')
VAL(7)
VAL(8)
VAL(9)
VAL('*')
VAL('A')
VAL('B')
VAL('C')
VAL('/')
VAL('D')
VAL('E')
VAL('F')
VAL(0)
VAL('=')
VAL('Z')
VAL('X')
VAL('M+')
VAL('M-')
VAL('MR')
VAL('MC')

4.9.1.4 The CALCD Panel DTL


The following is the same panel as in 4.9.1.2, The CALCD Panel on page 140
written in DTL.

<:-- CALCD panel -->


<:doctype dm system(
)>
<panel name=CALCD keylist=isrsab width=24 depth=14
actbar window=yes msgline=no>
<ab mnemgen=yes>
Chapter 4. Graphical User Interface (GUI)

143

<abc pdcvar=calcpdc>Modes
<pdc unavail=abd>Decimal
<action run=DEC>
<pdc>Hexadecimal
<action run=HEX>
</abc>
</ab>
<region dir=vert>
<dtafld datavar=b entwidth=22 pmtwidth=0 align=end usage=both padc=' '>
<dtafld datavar=mode entwidth=14 pmtwidth=5 usage=out>Mode:
</region>
<region dir=vert indent=2>
<info>
<p compact>&rbl;<ps var=key value=1>&rbl;1&rbl;</ps>&rbl;
<ps var=key value=2>&rbl;2&rbl;</ps>&rbl;
<ps var=key value=3>&rbl;3&rbl;</ps>&rbl;
<ps var=key value=+>&rbl;+&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=4>&rbl;4&rbl;</ps>&rbl;
<ps var=key value=5>&rbl;5&rbl;</ps>&rbl;
<ps var=key value=6>&rbl;6&rbl;</ps>&rbl;
<ps var=key value=->&rbl;-&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=7>&rbl;7&rbl;</ps>&rbl;
<ps var=key value=8>&rbl;8&rbl;</ps>&rbl;
<ps var=key value=9>&rbl;9&rbl;</ps>&rbl;
<ps var=key value=*>&rbl;*&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=0>&rbl;0&rbl;</ps>&rbl;
<ps var=key value=.>&rbl;.&rbl;</ps>&rbl;
<ps var=key value==>&rbl;=&rbl;</ps>&rbl;
<ps var=key value=/>&rbl;/&rbl;</ps>
</info>
<divider>
<info>
<p compact>&rbl;<ps var=key value=Z>&rbl;&rbl;C/CE&rbl;&rbl;</ps>&rbl;
<ps var=key value=X>&rbl;&rbl;Off&rbl;&rbl;&rbl;</ps>
</info>
<divider>
<info>
<p compact>&rbl;<ps var=key value=M+>&rbl;M+</ps>&rbl;
<ps var=key value=M->&rbl;M-</ps>&rbl;
<ps var=key value=MR>&rbl;MR</ps>&rbl;
<ps var=key value=MC>&rbl;MC</ps>
</info>
<dtafld datavar=mtxt entwidth=14 usage=out>
</region>
<dtacol>
<source type=init>
.CURSOR = &ZPS00017
&ABD = '1'
&CP = 0
&ZWINTTL = 'Calculator Sample'
&ZENTKTXT = ' '
</source>
<source type=reinit>
144

ISPF/SCLM V4 Guide

&KEY = ' '


REFRESH(*)
</source>
<source type=proc>
IF (&ZCMD='DEC')
&MODE = 'Dec'
&KEY = 'MD'
&ZCMD = ' '
IF (&ZCMD='HEX')
&MODE = 'Hex'
&KEY = 'MH'
&ZCMD = ' '
</source>
</dtacol>
</panel>

4.9.1.5 The CALCH Panel DTL


The following is the same panel as in 4.9.1.3, The CALCH Panel on page 142
written in DTL.

<:-- CALCH panel -->


<:doctype dm system(
)>
<panel name=CALCH keylist=isrsab width=24 depth=16
actbar window=yes msgline=no>
<ab mnemgen=yes>
<abc pdcvar=calcpdc>Modes
<pdc>Decimal
<action run=DEC>
<pdc unavail=abh>Hexadecimal
<action run=HEX>
</abc>
</ab>
<region dir=vert>
<dtafld datavar=b entwidth=22 pmtwidth=0 usage=both align=end padc=' '>
<dtafld datavar=mode entwidth=14 pmtwidth=5 usage=out>Mode:
</region>
<region dir=vert indent=2>
<info>
<p compact>&rbl;<ps var=key value=1>&rbl;1&rbl;</ps>&rbl;
<ps var=key value=2>&rbl;2&rbl;</ps>&rbl;
<ps var=key value=3>&rbl;3&rbl;</ps>&rbl;
<ps var=key value=+>&rbl;+&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=4>&rbl;4&rbl;</ps>&rbl;
<ps var=key value=5>&rbl;5&rbl;</ps>&rbl;
<ps var=key value=6>&rbl;6&rbl;</ps>&rbl;
<ps var=key value=->&rbl;-&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=7>&rbl;7&rbl;</ps>&rbl;
Chapter 4. Graphical User Interface (GUI)

145

<ps var=key value=8>&rbl;8&rbl;</ps>&rbl;


<ps var=key value=9>&rbl;9&rbl;</ps>&rbl;
<ps var=key value=*>&rbl;*&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=A>&rbl;A&rbl;</ps>&rbl;
<ps var=key value=B>&rbl;B&rbl;</ps>&rbl;
<ps var=key value=C>&rbl;C&rbl;</ps>&rbl;
<ps var=key value=/>&rbl;/&rbl;</ps>
</info>
<info>
<p compact>&rbl;<ps var=key value=D>&rbl;D&rbl;</ps>&rbl;
<ps var=key value=E>&rbl;E&rbl;</ps>&rbl;
<ps var=key value=F>&rbl;F&rbl;</ps>&rbl;
</info>
<info>
<p compact>&rbl;<ps var=key value=0>&rbl;&rbl;&rbl;
0&rbl;&rbl;&rbl;</ps>&rbl;
<ps var=key value==>&rbl;=&rbl;</ps>&rbl;
</info>
<divider>
<info>
<p compact>&rbl;<ps var=key value=Z>&rbl;&rbl;C/CE&rbl;&rbl;</ps>&rbl;
<ps var=key value=X>&rbl;&rbl;Off&rbl;&rbl;&rbl;</ps>
</info>
<divider>
<info>
<p compact>&rbl;<ps var=key value=M+>&rbl;M+</ps>&rbl;
<ps var=key value=M->&rbl;M-</ps>&rbl;
<ps var=key value=MR>&rbl;MR</ps>&rbl;
<ps var=key value=MC>&rbl;MC</ps>
</info>
<dtafld datavar=mtxt entwidth=14 usage=out>
</region>
<dtacol>
<source type=init>
.CURSOR = &ZPS00022
&ABH = 1
&CP = 0
&ZWINTTL = 'Calculator Sample'
&ZENTKTXT = ' '
</source>
<source type=reinit>
&KEY = ' '
REFRESH(*)
</source>
<source type=proc>
IF (&ZCMD='DEC')
&MODE = 'Dec'
&KEY = 'MD'
&ZCMD = ' '
IF (&ZCMD='HEX')
&MODE = 'Hex'
&KEY = 'MH'
&ZCMD = ' '
</source>
</dtacol>
</panel>

146

ISPF/SCLM V4 Guide

Chapter 5. Miscellaneous Discussion


The discussion in this chapter is a collection of thoughts and topics that did not
fit into any of the preceding chapters, but were significant enough to be included.
The general configuration table is mentioned for the changes that have been
introduced in this version, and also discussed is a probable view into what future
ISPF might bring. This is of course not a preannouncement, it is merely a
reflection over the possibilities that ISPF envisions. GUI is clearly a first step on
a long journey, the question is where may it take us. This document doesn't
promise anything, it merely points in a foreseeable direction.

5.1 Modifying ISPF Configuration Table (ISRCNFIG)


The ISPF Configuration file, ISRCNFIG, has only a few changes from prior
versions. There are three new entries in the ISPF 4.1 configuration table:
ANYCOLOR
DFLTCOLR
LOCALPRT
These entries are the last three found in ISRCNFIG.
ISRCNFIG source is located in SISPSAMP. The assembled configuration file is
named ISRCONFG, and is located in SISPLOAD.
The following section provides some information on what changes may be useful
in customization of the product.
ANYCOLOR
This entry can be set to either YES or NO.
Edit highlighting can have a considerable impact on edit performance.
By setting this entry to NO, an installation can disable highlighting
for all users. For more information on edit highlighting, see 2.5.2,
Edit Hilite on page 72.
DFLTCOLR
This entry can be set to 1, 2, 3 or 4.
The greatest advantage of this entry is the ability to remove the
action bar while in edit. Setting DFLTCOLR to a value of 2 still allows
edit highlighting, but the action bar will no longer be present. For
many users, this may be the solution which allows the home key to
place the cursor on the command line instead of the action bar. See
3.1.1, Action Bar Considerations on page 86 for information on
using the home key with the action bar.
Note
If ANYCOLOR has been set to No, edit highlighting will be
disabled regardless of the option chosen for DFLTCOLR.
See Table 4 on page 148 for DFLTCOLR settings and their effects.

Copyright IBM Corp. 1994

147

Table 4. DFLTCOLR Settings


DFLTCOLR Highlight

Act. Bar

Effect of Setting

NO

NO

No highlighting, no action bars

NO

YES

Action bars without highlighting

YES

NO

Highlighting without action bars

YES

YES

Highlighting with action bars

LOCALPRT
Contents of this field are appended as parameters on the ISPF PRINT
command.
ISPF uses TSO PRINTDS for the local print command. The contents of
the LOCALPRT field are appended to the PRINTDS command. The
default is NONUM. If LOCALPRT is set to blank, then local print via
PRINTDS is disabled. In ISPF settings, option 0, the Edit PRINTDS
Command option can be selected. Enabling this option allows users
to alter the PRINTDS command before it is submitted. The contents of
LOCALPRT can be overridden at this time.
ISRCNFIG allows an installation to override use of the TSO PRINTDS
command. If PRTCLIST is coded, the local print command will run the
named CLIST instead. Or, if PRTPGM has been coded, the local print
command will run the named program. When both PRTCLIST and
PRTPGM have been coded, the program will take precedence.

5.2 ISPF and the Future


ISPF 4.1 has various major improvements over any previous versions of the
product. Standing at the forefront of these improvements is the ability to use
ISPF in GUI mode. ISPF is among the very first of the mainframe products to
provide a true graphical user interface. This new interface opens an incredible
amount of functionality that version 4.1 does not even begin to exploit. The
future looks bright.
The following section gives a peek at what might be expected from ISPF in the
future. The features and functions that are outlined below may not ever become
part of the product, and may not appear in the way described. There is also no
guarantee of when, if ever, a new release will be written.

5.2.1 From Icon to ISPF


It does not take much to imagine a smoother way to get ISPF running in GUI
mode. There are no insurmountable barriers to prevent ISPF from being
launched from the workstation via an Icon.

5.2.2 Taming TSO


The ISPF Version 4.1 GUI mode has rightfully been received with positive
curiosity. It is apparent that many applications will be able to benefit from GUI
mode control. However, many users have expressed an interest in having TSO
line-mode input/output also handled by the GUI interface. The possibilities are
only a matter of programming time. So, if the potential is large enough, TSO
line-mode input/output could easily have a window unto itself.

148

ISPF/SCLM V4 Guide

5.2.3 Splitting Screens


For years, ISPF has been capable of handling up to four sessions on a 3279
terminal. On small, text based terminals, more than two sessions were
cumbersome. In GUI mode, having dozens of sessions becomes a practical
possibility with many productivity advantages.
With numerous GUI windows available, a user can set individual windows as
dedicated to certain functions. One session could be an SDSF one, another
could be an EDIT session and still another could be in SCLM. A few more
windows could be running custom written ISPF GUI applications. The possibility
of having individual window titles makes this even more advantageous.

5.2.4 Expanding Editor


Now that ISPF is running in the GUI environment, the next logical extension is to
take advantage of functions already available on the workstation. It is quite
possible for ISPF to allow any editor to be invoked in lieu of the regular ISPF
one. This suggests that a user could use a third party PC based word processor
to edit host data. Downloading and uploading would be transparent.

Chapter 5. Miscellaneous Discussion

149

150

ISPF/SCLM V4 Guide

Part 3. Software Configuration and Library Manager

Copyright IBM Corp. 1994

151

152

ISPF/SCLM V4 Guide

Chapter 6. SCLM Concepts and Terminology


This section explains the concepts of and some specific terms associated with
SCLM.
The intent of this section is to provide the SCLM information required to
understand the use of SCLM throughout our project. The section does not
duplicate the information presented in the product manuals. For a more detailed
discussion of SCLM, refer to ISPF/SCLM Project Manager's Guide, and
ISPF/SCLM Developer's Guide.

6.1.1 Software Configuration


SCLM introduces an object-oriented approach (not to be confused with
object-oriented programming) to software development. The objects SCLM can
control are members in partitioned data sets. SCLM keeps track of its objects by
means of multiple distinct VSAM files containing the accounting information of a
member for a specific group.
SCLM can control every object that resides in partitioned data sets.
Through configuration management functions SCLM:
Controls and enforces the integrity of an object and its associates.
Object modules, load modules, and script files containing, for example, the
prolog of an associated program source member are examples of
associates.
Provides object versioning capabilities.
Note: Versioning is only implemented for editable members. (Noneditable
members can be recreated using the retrieved editable members
given the original compiler/translator is available.)
Facilitates the accountability of an object and the changes applied to it.
Facilitates a controlled development environment (for example, preventing
concurrent updates).
SCLM functions like promote and build (see below) are, in a way, method
implementations. By method we mean applying a predefined action to an
object. For example, EDIT is a method of applying changes to an object.
Some of the terms associated with SCLM are defined below.

6.1.2 Library Management


The library management functions of SCLM are intertwined with the
configuration management functions.
The movements from and to the various partitioned data sets are examples of
library management.
The control over movements from and to the various partitioned data sets are
examples of configuration management.

Copyright IBM Corp. 1994

153

Note: It should be noted that there is no consensus in the literature on the


meaning of the terms library management and configuration
management.

6.1.3 Project
A project in SCLM is a collection of partitioned data sets with one or more high
level qualifiers formed to a common project name. This collection of partitioned
data sets is often referred to as the project database. A project is said to be
under SCLM control if there is a project.PROJDEFS.LOAD data set containing a
load module whose name equals the project name. The existence of at least
one VSAM file is essential for SCLM to keep (accounting) information about its
objects.

6.1.4 Project Definintion


The load module project.PROJDEFS.LOAD(project) is referred to as the SCLM
project's main project definition. A project definition represents a view of a
project, also referred to as alternate definition. Project definitions are set up
using a special set of assembler macros. The project definition has to be
assembled using Assembler H and linked into this load module.

6.1.5 Project Hierarchy


SCLM uses hierarchies of groups to control its objects. The hierarchies are
defined in the project definition and may conform to an enterprise's naming
convention and Time Sharing Option (TSO) standards.
A group is a collection of partitioned data sets with the same group qualifier.
The last qualifier of the partitioned data sets distinguishes the object types used
within a project. (COBOL, LOAD, and COBCOPY are examples of types.)

6.1.6 Language Definition


A language in SCLM is the property of an object (member). Languages have to
be defined in the project definition. SCLM keeps track of the language of a
member by checking its accounting record. Several language definitions
together could be thought of as forming a class within the translate method.

6.1.7 Architecture Definition


SCLM uses Architecture Definitions (ARCHDEFS) to relate dependent modules to
each other. There is a special language for Architecture Definitions, describing
an application's configuration.
There are four different Architecture Definitions:
Linkedit Control (LEC)
Architecture Definition to control the link edit process
Compilation control (CC)
Architecture Definition to control the compile or translate process
High-Level Control (HL)
Architecture Definition that includes other Architecture Definitions
Generic

154

ISPF/SCLM V4 Guide

Generic Architecture Definition to control noncompile, nontranslate


processors, like a Program Specification Block (PSB).

6.1.8 Build
To Build an object means to apply the member associated language. Thus, to
build a member that has COBOL as its language, SCLM compiles the member
producing an object module. The SCLM build is smart enough to know
whether or not a component needs to be reprocessed during a build, thus
preventing unnecessary processing. (Many organizations build on Architecture
Definitions only.)

6.1.9 Promote
Promote is the SCLM term for moving an object to the next higher level in the
hierarchy. Usually, during a promote the object's occurrence at the lower level
is purged. If a member is promoted, all the associated members are promoted
as well (physical promote).

6.1.10 Scope of Processing


Understanding how SCLM determines its processing scope is important. If the
processing scope is too narrow, out of sync (out of synchronization) situations
can occur.
During development, applications can become out of sync because several
individual developers may work with one application. At some point during the
development life cycle, all applications should be in sync.
To enforce synchronization, an HL Architecture Definition spanning all
applications should be developed. This definition should be used to build and
promote all changes into the group level used for the system test and then into
the group level used for production. (The promote will fail if there is an out of
sync situation, thus preventing the propagation of this situation to a higher level
in the hierarchy.)
The scope of processing is determined by the scope of the Architecture
Definition that is passed to such SCLM functions as build and promote.
Note: It is possible to build and promote an individual object by passing the
object to the various SCLM functions. Because language definitions exist,
processing can be done without having Architecture Definitions that
define or reference the object.

6.1.11 Versioning
With ISPF/PDF Release 3.3, versioning was introduced for SCLM. Versioning can
be specified for all editable types on all levels in the hierarchy. In addition to a
copy of the last version of a member, the versioning PDS for a
versioning-enabled type holds incremental changes called deltas. A
member's version can be recreated by starting with the last version and
applying the appropriate deltas to that version. (Version 1 is the last version
with last delta applied to it; version 2 is the last version with last delta and
delta 1 applied to it, and so forth). With versioning, when a member is
promoted, all the associated members are promoted as well. An ISPF/PDF
panel interface is available to retrieve the various versions.

Chapter 6. SCLM Concepts and Terminology

155

6.1.12 Component Changes of SCLM 4.1


The ISPF SCLM component contains the following new functions and
enhancements:
SCLM extended extends support
The include search capabilities of SCLM have been enhanced to allow more than
two types to be searched when finding parsed include dependencies. The types
to be searched are determined by the language of the object being processed
rather than the type of the object.
Allocation of FLMSYSLB data sets can be done automatically by Build using the
ALCSYSLB parameter on the FLMLANGL macro. This removes the need to
specify the FLMSYSLB data sets using the FLMCPYLB macro.
SCLM can now check for includes in FLMSYSLB data sets at Parse or Build time.
Doing the check at Build time allows for movement of the includes in and out of
the FLMSYSLB data sets without having to reparse all objects that reference the
includes.
SCLM enhanced member list
Option 3.1 of SCLM has been enhanced to support View, Edit, and Build through
member list. The member list can be for a single group or the entire hierarchy
view. The objects on the member list can be selected and ranked by the
availability of their accounting and build map record.
SCLM multiple output support Build has been enhanced to support
translators that generate multiple output objects in a partitioned data set.
The architecture language has been enhanced for LEC archdefs to support
referencing output keywords other than OBJ and LOAD. LEC archdefs can also
include SINC statements to include outputs that are under SCLM control, but
generated outside of SCLM.

6.1.13 SCLM Workshop


We will guide you through the features of SCLM by using a workshop-style
manner, where we start off with implementing the product's sample and continue
to commonly build up an SCLM prototype.
ISPF Version 4.1 split up SCLM manuals. We used:
ISPF/SCLM Project Manager's Guide
ISPF/SCLM Developer's Guide
ISPF/SCLM Reference
ISPF Messages and Codes.

156

ISPF/SCLM V4 Guide

Chapter 7. Install, Implement and Understand SCLM Product Sample


Developers have often requested to have more than four groups visible on an
edit screen for editing. In fact, this is not needed if you introduce role
management and as a result would be able to draw down members beyond the
4th level. SCLM 4.1 has considerably enhanced the library utility including the
possibility of drawing down from any hierarchical level that is included in the
project definition.
This new facility and role management really gives a new sight of working with
SCLM projects - bottom up instead of top down, and was a good reason to pull
material that has been acquired in practice 2 to give some indications to the
SCLM Project manager trying to set up an SCLM environment.
The material in this chapter is being used to teach a four day on-site workshop,
and for your convenience, we will guide you through it.
1. At this point an introduction to SCLM and configuration management concept
is mandatory.
Material
Made available on the enclosed diskette is:
Foils for teaching workshop
All samples described in this part
2. We shall use the SCLM sample in this workshop. The SCLM manuals
ISPF/SCLM Project Manager's Guide
ISPF/SCLM Developer's Guide.
contain descriptions of the project manager's and the developer's tasks. So,
let us implement the sample first.
SCLM sample guidance
starts with 7.1, SCLM Project Manager Scenario on page 157.
After implementation of the SCLM product's sample, we will enhance that
sample to an enterprise prototype project.

7.1 SCLM Project Manager Scenario


Have you ever shown interest for option 10 (SCLM), and selected option 10
consequently? And then you have fallen into a black hole? This is because an
SCLM project manager has to first define the project environment.
I have often heard from customers that it is difficult for them to understand
where to start. This is a shortcut you may want to follow.
ISPF/SCLM Project Manager's Guide, Chapter 1, gives a detailed discussion of
what has to be done. We will proceed directly to the installation of the sample

Special thanks are due for their contributions to Bruno Bickel, Dan Douglas, Dr. Walther Fitz, Frank Gerz, Dietmar Krick, Mike
Petersen, and Mike Ramsey.

Copyright IBM Corp. 1994

157

starting at section Project Manager Scenario, and read chapter 1 at a later


time.
Anything you should do, will be shown in a box, something like this:
Define prjid
The sample project will be our project prototype for the following discussions.
For the setup, a hlq must be defined, which at the moment could be best a
personal TSO user ID.
Select a user ID now; user ID=________= prjid (=PROJ1, and also = hlq)

7.1.1 What the SCLM Project Manager has to Do


The SCLM project manager must:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

Determine the project hierarchy


Identify the types of data to be supported
Establish authorization codes
Create project control
Allocate control data sets
Implement security
Specify project definitions
Modify control options
Define the language definitions
Assemble and link edit the project definitions

No doubt, an SCLM project manager is mandatory to implement the customer's


SCLM environment and provide support to the developers. This person must be
a system programmer and at the same time an application minded, supportive
type. Although, when starting to implement SCLM, this is a full-time job, after a
few months, depending on how many subsystems must be integrated, the efforts
needed decrease sharply.
Project Manager Scenario
Read section Project Manager Scenario, Chapter 1 of ISPF/SCLM Project
Manager's Guide, and understand:
1. Section Prerequisites for Defining an SCLM Project and
2. Section Example Project Overview

158

ISPF/SCLM V4 Guide

7.1.2 Understand the Sample Environment


TSO logon
1. You decided which user ID you would use. Logon with this user ID now.
2. = = = > TSO LISTA ST H and press Enter
3. What is the hlq of your ISPF product data sets? ________
(ddname ISPPLIB, for example, shows the DSNs of concatenated ISPF
panel libraries).
4. Option = 3 . 4 and press Enter
5. Enter dsname level, for example hlq.V4R1M0.* , and press Enter
6. DSN of data set ispf...SISPSAMP ? = ________.________.________
7. DSN of data set ispf...SISPMACS ? = ________.________.________
8. Follow step 1 through step 6 of the section Preparing the Example
Project Hierarchy.

Data set ispf...SISPSAMP contains the SCLM sample, consisting of FLM01* and
FLM02* parts.
Fill in from ispf...SISPSAMP
Table 5. JCL and Definitions of SCLM Sample Project
Member

What it does?

FLM01ASM

Assembler language definition

FLM01PLI

FLM01PRJ

FLM01SCR

FLM01370

FLM02ACT

FLM02ALL

FLM02PRJ

FLM02VER

FLM02VSM

7.1.3 Prepare Sample Project


Allocate data sets, and copy sample parts
Execute steps 1 through step 6 of section Preparing the Example Project
Hierarchy, Chapter 1 of ISPF/SCLM Project Manager's Guide.
Are all data sets present? Select PDF Option 3.4 and check confirmation for:
prjid.account.file (check 19.1.12, VSAM Maintenance on page 246)
prjid.PROJDEFS.*
prjid.RELEASE.*
prjid.TEST.*
prjid.DEV1.*
prjid.DEV2.*

Chapter 7. Install, Implement and Understand SCLM Product Sample

159

7.1.4 Prepare and Understand the Sample Project


Build SCLM product sample
1. Execute steps 9 through 17 of section Preparing the Example Project
Hierarchy, Chapter 1, ISPF/SCLM Project Manager's Guide.
2. Read through steps 1 and 2 of Understanding the Sample Project
Definition, and
3. Put a short descrption in the table below for later reference.

Table 6. Architecture Definitions of Sample Project


Archdef

What it does?

FLM01AP1
FLM01ARH
FLM01CMD
FLM01LD1
FLM01LD2
FLM01LD3
FLM01LD4
FLM01SB1
FLM01SB2

Table 7. Program Sources of Example Project


Program

What it does? / Which dependancies exist?

FLM01EQU
FLM01MD1
FLM01MD2
FLM01MD3
FLM01MD4
FLM01MD5
FLM01MD6

7.1.5 Preparing the Example Project Data


SCLM project manager must check for correct preparation
Execute steps 1 through 10 of Preparing the Example Project Data, Chapter
1, ISPF/SCLM Project Manager's Guide.

160

ISPF/SCLM V4 Guide

7.2 Development Scenario


In 7.1, SCLM Project Manager Scenario on page 157, the scenario was
installed.

7.2.1 Sample Seen from a Developer's Point of View


We now want to understand the project from a developer's point of view.
Understanding the sample project
Execute Chapter 4, ISPF/SCLM Developer's Guide, step by step.

This concludes the introductory part, on which we will base discussion and
implemention of the following topics:
Project organization
Role management
Method management
Security
Version control
Configuration management
Change & problem tracking
Delivery
Communication
Verification
Meta project (administer SCLM through SCLM)
Optimization
Workstation connection.

Chapter 7. Install, Implement and Understand SCLM Product Sample

161

162

ISPF/SCLM V4 Guide

Chapter 8. Project Organization


SCLM is based on physical and hierarchical data management. All
organizations must bear that in mind.

PRODUCTION
P
R

O
DELIVERY
B
L

E
PRODUCTION
Hot Fix
M
(shadow)
I
/
C

H
Systemtest
Delta

A
I

N
G

E
Integration Development

M
A

N
Staging

G
E

M
Team

N
T

Rx.3 Rx.2 Rx.1

Development

PC
PC

R O L E S

source history
may be aquired
additionally

for defined
groups
and types

C
O
N
F
I
G
U
R
A
T
O
M R
A
N
A
G
E
R

D
E
V
E
L
O
P
E
R

Figure 107. Configuration and Change Management (CCM)

The term SCLM project is artificial. It may be a product, an area, applications, a


special field of interest, - whatever you like. Let's assume the following:
An SCLM project is - Agreement
1. An enterprise project
2. Areas (or other differentiators) are sclm subprojects
You choose your name for subprojects _______________ ;

this documentation will use the term sclm project (sclm = small letters) or
prjid.

Copyright IBM Corp. 1994

163

Now define the hlq for the SCLM enterprise project


1. hlq = ________
Note: Implicitly you now have defined these (meta) data sets:
________.PROJDEFS.METHODS
________.PROJDEFS.PROJECTS
________.PROJDEFS.REXX
________.PROJDEFS.JCL
________.PROJDEFS.OBJ
________.PROJDEFS.LOAD

(ex
(ex
(ex
(ex

SOURCE)
SOURCE)
SOURCE)
SOURCE)

Project organization or project control are synonyms. Project control really


means everything, since everything an SCLM project manager does has to be
constructed (or reconstructed) through SCLM macros.
SCLM Project Manager's Basic Rules
1. Any changes for an SCLM project must be done using SCLM macros.
Any such set of macros is called a project definition.
2. Any changes applied to these macros necessitates a compilation with the
assembler and a link edit into the data set
prjid.PROJDEFS.LOAD(prjview).
3. A prjview is an alternate definition of an sclm project. There can be
many prjviews in one sclm project, and many sclm projects in one SCLM
enterprise project.
4. Changes to a prjview require you to enter or reenter option 10, since
prjview then will be reloaded.
5. The base infrastructure (PDS and VSAM data sets) must always exist
prior to any activity.

8.1.1 Security Scheme for Project Data Sets


Let's assume from now on, that all data sets required (and to be required) have
been created. A security scheme through RACF (or an equal product) is
obvious, and the following may only be seen as an example.
Data Set

Developer

SCLM Project
Manager

Project Definition (prjviews)


'prjid.PROJDEFS.LOAD'

READ

CONTROL

Project Data Sets


'prjid.group.type'

UPDATE READ

CONTROL

Account File
VSAM Account File

UPDATE

CONTROL

Version Data Set


'prjid.group.type.version'

UPDATE READ

CONTROL

Audit control
VSAM Audit File

UPDATE

CONTROL

Since ISPF/SCLM 3.4, more than one account data set is allowed. For a secure
project design, it is mandatory to organize account data sets to roles (see
Chapter 9, Role Management on page 173), and protect them accordingly.

164

ISPF/SCLM V4 Guide

8.1.2 Alternate Definitions


The name alternate definition may mislead you, as all project definitions in an
enterprise project may be alternate definitions.
Alternate Definitions - Agreement
Are different navigations through a prjid and present a view.
Select option 10 with these parameters:
SCLM Project Control Information:
Project
(prjid (=hlq of PROJDEFS.* - Data Sets) )
Alternate
(prjview (member of hlq.PROJDEFS.LOAD)
)
Group
(Lowest Level of Hierarchy = Edit Level
)

YOU choose this name: _____________________________


I shall write Projectview.

Project control is primarily executed through project views. You may have as
many views as needed.

8.1.3 Authorization Codes (AC)


The AC can be used to delimit project areas. One must carefully choose what to
do with AC's. Let us agree on this:
AC - Agreement
One AC for all prjviews of an sclm project
AC is identical to the sclm project's name
for example: My sclm project name is FLM (FLM is the component name
for SCLM), this defines A C = F L M also.
Additionally we will add A C = T for the development level. This will
enable a developer to acquire modules from other developers for testing
SCLM allows (Option 10.3.1.U) updating of the AC. This can be made
obsolete by having more than one account data set, and setup a
protection scheme against update through developers.

8.1.4 Data Set Management


Projects could basically have their own data sets or could combine these. Let's
assume we had 50 projects; then we could have 50 PRODUCTION, 50
SYSTEMTEST, 50 INTEGRATION and (50 DEVELOPMENT * user ID) - data sets,
this adds up, for example, for two user IDs like:
50+50+50+100=250 data sets times applicable data set types

This, indeed, is a lot of data sets, and we may think of a means to combine some
of these in order to reduce their number.

Chapter 8. Project Organization

165

8.1.5 Organization of Production Data Sets


8.1.5.1 Solution 1: Enterprise Projects Physically Separated

prjid1


prod

qa

developer

prjid2


prod Two projects, each with its
own set of data sets

qa
Quality Assurance Function

developer

Figure 108. Many Enterprise Projects

This makes a lot of sense because now a project is an entity all by itself. For
reasons of simplicity we will not discuss the account data file nor the
hierarchical levels at the moment.

8.1.5.2 Solution 2: Enterprise Projects Concatenated


If, however, one sclm project should profit from another project's code, it must
be combined in some acceptable form.
prjid1
prjid2



prod prod

qa

qa

developer
developer

Combined thru Concatenation


in JCLStream
Eventually pre-concatenated
Eventually pre-pre-concatenated
for Test-System

Figure 109. Load Modules Concatenated for Production

This project organization concatenates load libraries of two or more projects.


Each prjid may have a different design.

166

ISPF/SCLM V4 Guide

8.1.5.3 Solution 3: One Enterprise Project with many Subprojects


This may be considered the most common design. An enterprise normally has
many different areas or products, or other differentiators. Each differentiator
may be considered a subproject with many prjviews in the enterprise's SCLM
project. Any desirable combination can be achieved through the FLMALTC
macro.

prjid1
prjid2


prod
prod

qa

qa

developer
developer

This model, although two logical views,


combine their data sets through
physical definition by the
FLMALTC macro.

Figure 110. Prjviews Combine Data Sets Physically

It's easy to see that all prjid1-prod data is shared by prjid2 and vice versa. This
sharing can include editing and/or building. In this example, setup I advise
sharing for building only.

8.1.5.4 Solution 4: Many Subprojects under one Roof


If we do not want to share the complete code from one sclm project with other
projects (BUILD is still possible with all such organized projects) automatically,
we can build a roof, and may call it COMMON. The prjview defines which code
may be promoted to COMMON.

prjid1
prjid2
prjid3 (global code prj)


c o m m o n


prod
prod

qa

qa

qa

developer
developer
developer

Figure 111. Many Separated Projects under one Roof

Chapter 8. Project Organization

167

8.1.5.5 Solution 5: Combination of Choice


prjid1

prjid2

prjid3

(global code prj)

c o m m o n

prod
prod

qa

qa

qa

developer
developer
developer

Figure 112. Many Subprojects Combined by Choice

Using this project design, COMMON is defined to particular projects.


Define Your Production Data Sets Organization Now
Your solution? 1, 2, 3, 4 or 5 ? ______________.

8.1.6 Combination of Developer Data Sets


This is very much the same discussion we just had with the combination of
production data sets.

8.1.6.1 Solution 1: One Group in many SCLM Projects


While a vertical, concatenated PROD level data set organization (see 8.1.5,
Organization of Production Data Sets on page 166) may be sensible, it is
different for the developer level because of the horizontal amount of the same
data set types.
prjid1
prjid2

qa

qa





uid1 uid2
uid1 uid2

TSOuid is identical to uid


Defined through project view
FLMGROUP
= uids = groups
Amount type = uids x type

Figure 113. Private Level - User IDs Defined in Project View

The development level group is identical to TSO user ID.


Data belonging to prjid1 or prjid2 reside in the same private data sets, thereby
drastically reducing the amount of data sets.
Note: Parts residing in the same data set does not necessarily imply access to
the parts.

168

ISPF/SCLM V4 Guide

8.1.6.2 Solution 2: One or many Developers in one Group


prjid1
prjid2

qa

qa





D01 D02
D01 D03

uid1

uid2

NOTE:
One group per user:
- secure lock mechanism
- private interactive test environment
RACF permits userids to development group

Figure 114. Private Level - User IDs not Defined in Project View

A development group may now consist of one or many developers.


RACF permits access to the development group.
Note: Having more than one developer working through the same development
group lifts the LOCK security mechanism SCLM provides to those working
through that group.
Define Data Set Organization For Development Level
1. Not combined at all: Y/ N? _____________________
2. Privately combined : Y/N? _____________________
3. Solution 1, 2 ?
_____________________
4. PDS Name = ?
________________________________________
that is, with variables (such as: userid.@@FLMGRP.@@FLMTYP).
One could think to have the variable userid set up as @@FLMUID, but this
(unfortunately) is not accepted (see DSNAME parameter of FLMCNTRL or
FLMALTC macro).
To avoid making mistakes in copying project views, it is advisable to work
with SCLM variables, which may finally lead to a PDS name such as:
PDS Name = @@FLMPRJ.@@FLMGRP.@@FLMTYP
Note: Often a DFSMS setup scheme exists, and the PDS names have to
follow-up on it. Names like @@FLMPRJ.XYZ@@FLMGRP.@@FLMTYP
are acceptable (@@FLMGRP must not be greater than 5 digits in this
example).

8.1.7 Hierarchy Organization


How many levels should or must our enterprise project embrace? We are talking
about a behavior of developing / testing / integrating / delivering parts. This
depends very much to our enterprise's organization and the applications that
make up the product.
Figure 107 on page 163 employs 5 key levels, and this can be considered a
normal setup (which imposed the problem, we started off at the beginning).
Beyond the fourth level, the edit screen will not indicate those levels above, and
no implicit drawdown could be made.

Chapter 8. Project Organization

169

Only Four Levels shown of a 5 Level Hierarchy

Menu RefList RefMode SCLM Utilities Help


-----------------------------------------------------------------------SCLM Edit - Entry Panel
Command ===>
SCLM Library:
Project . .
Group . . .
Type . . .
Member . .

: SCLM41
Alternate - FLM
: HASINGH . . . TEAM
. . . INTE
. . . TEST
. SOURCE
.
(Blank or pattern for member selection

SCLM 4.1 library utility may select the whole hierarchy, and allows us to edit and
drawdown parts. Parts may additionally be selected and ranked, and nonaccount
record parts may be suppressed by selecting AM.
Option 10.3.1 with Select Data Set A M and Edit Selection

Menu SCLM Utilities Help


----------------------------------------------------------------------SCLM41.HASINGH.SOURCE - HIERARCHY VIEW Row 1 to 7 of 7
Command ===>
Scroll ===> PAGE
Member
Status
-------- ----------FLM01EQU
FLM01MD1
FLM01MD2
FLM01MD3
FLM01MD4
FLM01MD5
FLM01MD6

Account
-------PROD
PROD
PROD
PROD
PROD
PROD
PROD

Chg Date
-------94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22

Chg Time
-------13:09:00
13:09:00
13:09:00
13:09:00
13:09:00
13:09:00
13:09:00

Language
-------ASMH
ASMH
PLIO
ASMH
ASMH
ASMH
ASMH

Bld Map
------PROD
PROD
PROD
PROD
PROD

Option 10.3.1 with Select Data Set A and Build Selection

SCLM41.HASINGH.ARCHDEF - HIERARCHY VIEW Command ===>

170

ISPF/SCLM V4 Guide

Member
Status
-------- ----------FLM01AP
FLM01AP1
FLM01ARH
FLM01CMD
FLM01LD1
FLM01LD2
FLM01LD3
FLM01LD4
FLM01SB1
FLM01SB2

Account
-------INTE
PROD
PROD
PROD
PROD
PROD
PROD
PROD
PROD
PROD

Chg Date
-------94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22

Chg Time
-------13:04:00
12:34:00
12:34:00
12:58:00
12:34:00
12:34:00
12:34:00
12:34:00
12:34:00
12:34:00

Row 1 to 1
Scroll ==
Language
-------ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF

Auth
---FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3

Define Your Levels of Hierarchy

How many levels

? ___
(for example 5 key groups)

Name of levels

? ________ ________ ________ ________ ________


(PRIV
TEAM
INTE
TEST
PROD

Account file name ? ________ ________ ________ ________ ________


(sclm41.
team.
team
inte
test
prod
acctfile
(TSO max. 44 digits))

8.1.8 Implementation
Later in this discussion (see Chapter 18, Meta Project on page 221), we will
manage our project creating/manipulating parts using SCLM. In preparation, let
us now split up prjid.PROJDEFS.SOURCE into its different types, such as:
prjid.PROJDEFS.PROJECTS

(Project views)

prjid.PROJDEFS.METHODS

(Language definitions)

prjid.PROJDEFS.JCL

(Job control)

prjid.PROJDEFS.REXX

(REXX programs)

etc.

Split up PROJDEFS parts


1. Allocate prjid.PROJDEFS.* data sets as described above.
The DCB must be carefully chosen and provide enough space (see
ISPF/SCLM Project Manager's Guide, Data Set Physical Attributes, page
20 .
2. Copy parts from uid.PROJDEFS.SOURCE(*) to prjid.PROJDEFS.type(*)
accordingly.

8.1.8.1 Create Project View Prototype


Now we are ready to implement our decisions. We use the SCLM sample
project we have implemented in 7.1, SCLM Project Manager Scenario on
page 157 as a guide.
Define project view prototype
1. Enhance sample project definition to sample below accordingly.
2. Our enterprise project will now contain one subproject called FLM.
3. Define the prjview as part prjid.PROJDEFS.PROJECTS(FLM).
4. Associate with translator ASMH GOODRC=4 ( A C = , returns RC=4).
5. Compile/link edit as part prjid.PROJDEFS.LOAD(FLM).

Chapter 8. Project Organization

171

*********************************************************************
TITLE '*** SCLM Sample Project - Our Prototype
***'
*
*
* ==> prjid must be same for all views of enterprise project*
*
*
(for example SCLM41)
*
prjid
FLMABEG
*
**************************************************************
*
* DEFINE THE Authorization Groups
*
*
*
+ keep it simple, although delimit subprojects *
*
*************!************************************************
*
v
PRJAC
FLMAGRP AC=(FLM)
-- ONE AC for all prjviews of
*
ONE sclm subproject.
*
**************************************************************
*
* DEFINE THE Groups
*
*
*
+ freeze promote (returns RC=4 = ok)
*
*****************!********************************************
*
v
PROD
FLMGROUP KEY=Y,AC=,
TEST
FLMGROUP KEY=Y,PROMOTE=PROD,AC=,
STG2
FLMGROUP KEY=N,PROMOTE=TEST,AC=(PRJAC)
INTE
FLMGROUP KEY=Y,PROMOTE=STG2,AC=(PRJAC)
STG1
FLMGROUP KEY=N,PROMOTE=INTE,AC=(PRJAC)
TEAM
FLMGROUP KEY=Y,PROMOTE=STG1,AC=(PRJAC)
uid1
FLMGROUP KEY=Y,PROMOTE=TEAM,AC=(PRJAC,T)
uid2
FLMGROUP KEY=Y,PROMOTE=TEAM,AC=(PRJAC,T)
*
*
**************************************************************
*
* DEFINE General Parameters AND PROD level
*
*
**************************************************************
FLMCNTRL
C
ACCT=SCLM41.PROD.ACCTFILE
C
,DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP
C
,MAXVIO=5000
C
,MAXLINE=75
C
,OPTOVER=Y
*
*
**************************************************************
*
* DEFINE Language Definitions
*
*
**************************************************************
COPY FLM@ARCD
ARCHDEF
COPY FLM@BOOK
BOOK
COPY FLM@ASMH
ASMH
COPY FLM@COB2
COB2
COPY FLM@L370
L370
FLMAEND

ATTENTION: Assembler Restrictions


Column 72 is reserved for statement continuation flag.
A continued statement must start in column 16.
Empty lines are not allowed.
Comments start with an asterisk in column 1.

172

ISPF/SCLM V4 Guide

Chapter 9. Role Management


Unfortunately, a roleplay is underdeveloped in many enterprises. Some
developers feel drawbacks if a promote up to production is not allowed. This is
mainly due to a nonestablished quality assurance (QA) function. QA, however,
requires successful acceptance of interactive debugging techniques.
A developer looking into and manipulating running code (white box testing
techniques) will have a much greater code knowledge than another one testing
in batch. A batchtest does not reflect the reality of the code, but its
interpretation (for example desktop tests, listings, and reports).
An interactive test also permits few driving test records, which can be versioned
together with the other parts, forming a testbed, and at the same time the base
for regression test, such as tests with Workstation Interactive Test Tool (WITT black box testing techniques). A WITT (regression) test enables QA to
independently play back the developer-recorded function test after it's promote.
At the end of the interactive testing, a batch test is needed to proof the
correctness of the developed function to QA.

9.1 Interactive Test - A Must


Below is an outline of the superior advantages of interactive testing techniques.
Interactive versus Batch Test
Table 8. Questions
Questions

Interactive

Batch

Knowledge of code equality

High

Low

Unnecessary code

None

High

Quality prediction

YES

NO

QA preparation

YES

NO

Readiness to take responsibility

YES

Low

Keep date predictions

High

Low

Smaller test efforts / fewer test data

YES

NO

Satisfaction/motivation

High

Low

Maintenance

Low

High

Reusability

High

Low

Early design proof possible

YES

NO

Include unproofed reused code

YES

NO

Use of complex constructs

YES

NO

QA demands a participative type of developer who previews quality assurance.


This participative developer may be acquired through the usage of white-box
testing techniques, such as the usage of CODE/370, an interactive debugger.
Then, QA is not considered a point of control, but a necessary amendment of the
work to be done.

Copyright IBM Corp. 1994

173

In Figure 107 on page 163 a roleplay is sketched. The more important roles can
be defined as:

9.1.1.1 SCLM Project Manager


This person rules the system and represents the enterprise's view supporting all
other roles.

9.1.1.2 SW Developer
develop and test (debug) in their private group (development level).
SW developers share their results (which may also be partially ready) with their
team members by promoting to a team group (TEAM level).

9.1.1.3 SW Team Leader


Provides the enterprises's view of a project and may write architecture
definitions SW developers have to go by.

9.1.1.4 SW Manager
Examine developer promoted parts and integrate those into components, before
they promote for further examination and system integration. SW managers may
not be allowed to edit, says the SCLM project manager

9.1.1.5 SW Configurators
Examine SW manager promoted parts and integrate those into systems, before
they promote to production. SW configurators may not be allowed to edit, says
the SCLM project manager
To fully implement these roles, a minimum hierarchy of four key and two non-key
groups is needed, whereas the non-key staging groups might be also designed
as key.
Partitioned data sets and their applicable account data sets should be clustered
by role for better:
Security
Backup/restore
Delivery
SCLM Edit - Agreement
Edit only possible on lowest level of prjview
A C = , disallows edit, and freezes promote
A C = , results in Assembler R C = 4 = o k at assembly

174

ISPF/SCLM V4 Guide

Define Roleplay
Now define the roles in *your* enterprise.

Role
Role
Role
More

SW Developer
SW Manager
SW Configurator
Roles?
Impact?

Y/N
Y/N
Y/N
Y/N

?
?
?
?

___
___
___
___ Which? _____________________________
____________________________________

Assign data sets to roles


Groups already
defined before
Now assign roles

_______ ________ ________ ________ ________


(private TEAM K STG1 NK INTE K ....
? ________ ________ ________ ________ ________
(SW-DEV SW-DEV
SW-DEV
SW-MGR
SW-MGR
SW-MGR
SW-CFG
SW-CFG

And account files ? ________ ________ ________ ________ ________


(TEAM
TEAM
TEAM
INTE
....
And ACCTFILE names ? ________ ________ ________ ________ ________
hlq.TEAM. hlq.TEAM. hlq.TEAM. hlq.INTE. ....
ACCTFILE
The roleplay is implemented through project views. This is, where the music
plays. We will have many project views. The easiest way to think of it, is to
have a jigsaw puzzle of 1000 pieces, and each piece would be a project view,
which means a project is not defined top-down in one big project definition but
bottom-up in a granulated way, where every project definition (prjview) is a piece
of our enterprise puzzle. This requires that the names of the puzzle pieces are
carefully choosen so they are quickly remembered (like driving on the highway).
Developed from our prototype, the developer's view, which is one of many of a
given subproject could be named FLM1, whereas the AC's stick to the name of
the subproject, for example in this case FLM.

Chapter 9. Role Management

175

Role = project view =

Alternate (Option 10.x) Entry

SCLM Main Menu


Option ===>
Enter one of the following options:
1
2
3
4
5
6
X

View
Edit
Utilities
Build
Promote
Command
Exit

SCLM Project
Project .
Alternate
Group . .

ISPF View or Browse data


Create or change source data in SCLM databases
Perform SCLM database utility/reporting functions
Construct SCLM-controlled components
Move components into SCLM hierarchy
Enter TSO or SCLM Commands
Terminate SCLM

Control Information:
. . . SCLM41
(Project high-level qualifier)
. . . FLM
(Project definition: defaults to project)
. . . HASINGH (Defaults to TSO prefix)

Define roleplay nomenclature for sclm projects


Table 9. Table of Projects, Views and Roles
Project

View

Role

Meta Project

#SCLM

SCLM Project manager

sclm Sample

FLM

SW Developer with
TEST-Option Languages (*1)

FLM1

SW Developer with
PROD-Option Languages

FLM8

SW Manager

FLM9

SW Configurator
SW Developer with
TEST-Option Languages
SW Developer with
PROD-Option Languages
SW Manager
SW Configurator

(*1) SCLM 3.4 New Functions Usage Guide contains a discussion for the
implementation. The next release of SCLM (4.2) plans to provide translator
options per group.

Note: At this point in time, the prototypes contained on the enclosed diskette
might be helpful.

176

ISPF/SCLM V4 Guide

Implement Developer's Role (FLM) from Prototype


*********************************************************************
*
* AC is used to cut role (prjviews)
*
* ===> Developers Window
*
* View < - PRIV - TEAM - (STG1) - INTE - (STG2) - TEST - PROD
*
* Edit < - PRIV - TEAM
(STG1) - INTE
(STG2) - TEST - PROD
*
* Promote PRIV -> TEAM -> STG1 / INTE
STG2
TEST
PROD
*
*********************************************************************
*********************************************************************
TITLE '*** Developer's Project View
***'
*
*
**************************************************************
*
* DEFINE THE VIEW
*
* +------ this name stays unchanged (for example SCLM41)
*
* v
**************************************************************
prjid
FLMABEG
*
*
**************************************************************
*
* DEFINE THE Authorization Groups
*
*
*
+ keep it simple, although delimit subprojects *
*
*************!************************************************
*
v
PRJAC
FLMAGRP AC=(FLM)
-- ONE AC all prjviews / subprj
*
*
**************************************************************
*
* DEFINE THE Groups
*
*
**************************************************************
*
PROD
FLMGROUP KEY=Y,AC=,
TEST
FLMGROUP KEY=Y,AC=,PROMOTE=PROD,ALTC=CFGDB
STG2
FLMGROUP KEY=N,AC=,PROMOTE=TEST,ALTC=MGRDB
INTE
FLMGROUP KEY=Y,AC=,PROMOTE=STG2,ALTC=MGRDB
<== (*1)
STG1
FLMGROUP KEY=N,AC=(PRJAC),PROMOTE=INTE,ALTC=DEVDB
TEAM
FLMGROUP KEY=Y,AC=(PRJAC),PROMOTE=STG1,ALTC=DEVDB
HASINGH FLMGROUP KEY=Y,AC=(PRJAC,T),PROMOTE=TEAM,ALTC=DEVDB
DUMMY
FLMGROUP KEY=Y,AC=(PRJAC,T),PROMOTE=TEAM,ALTC=DEVDB
*
*
**************************************************************
*
* DEFINE General Parameters AND PROD level
*
*
**************************************************************
*
FLMCNTRL
C
ACCT=SCLM41.PROD.ACCTFILE
C
,DSNAME=SCLM41.@@FLMGRP.@@FLMTYP
C
,MAXVIO=5000
C
,MAXLINE=75
C
,OPTOVER=Y
*
*
**************************************************************
*
* DEFINE alternate infrastructure
*
*
**************************************************************
*
DEVDB FLMALTC ACCT=SCLM41.TEAM.ACCTFILE,
C
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP
<== (*2)
MGRDB FLMALTC ACCT=SCLM41.INTE.ACCTFILE,
C
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP
<== (*2)
CFGDB FLMALTC ACCT=SCLM41.TEST.ACCTFILE,
C
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP
<== (*2)
*

.....

<== (*3)

Note:
1. The account data set must change with a rolechange.
A promote cannot be executed due to A C = ,
2. Each role has it's own set of data sets
3. Languages in this view may contain TEST OPTION Parameters

Chapter 9. Role Management

177

Implement SW Manager's Project View (FLM8) from Prototype


*********************************************************************
*
* ===> SW Manager prjview of FLM subproject
*
* View only
< TEAM - (STG1) - INTE - (STG2) - TEST - PROD
*
* Promote
TEAM + STG1 -> INTE -> STG2 / TEST
PROD
*
*********************************************************************
TITLE '*** SW Managers Project View of Project FLM ***'
*
*
**************************************************************
*
* DEFINE THE VIEW
*
* +------ this name stays unchanged (for example SCLM41)
*
* v
**************************************************************
prjid
FLMABEG
*
*
**************************************************************
*
* DEFINE THE Authorization Groups
*
*
**************************************************************
*
PRJAC
FLMAGRP AC=(FLM)
-- ONE AC for all prjviews/same prj
*
*
**************************************************************
*
* DEFINE THE Groups
*
*
**************************************************************
*
PROD
FLMGROUP KEY=Y,AC=,
TEST
FLMGROUP KEY=Y,AC=,PROMOTE=PROD,ALTC=CFGDB
STG2
FLMGROUP KEY=N,AC=(PRQAC),PROMOTE=TEST,ALTC=MGRDB
INTE
FLMGROUP KEY=Y,AC=(PRQAC),PROMOTE=STG2,ALTC=MGRDB
STG1
FLMGROUP KEY=N,AC=(PRJAC),PROMOTE=INTE,ALTC=DEVDB
TEAM
FLMGROUP KEY=Y,AC=(PRJAC),PROMOTE=STG1,ALTC=DEVDB
<== (*1)
DUMMY
FLMGROUP KEY=Y,AC=,PROMOTE=TEAM,ALTC=DEVDB
<== (*2)
*
.....
Note:
1. TEAM must be included being the last key group
2. dummy must be included for nonedit view (AC=,), and since no
data sets will exist for this group, RACF will shout immediately

Implement SW Configurators Project View (FLM9)


TWOBACK
ONEBACK
PROD
TEST
STG2
INTE
DUMMY
*

FLMGROUP
FLMGROUP
FLMGROUP
FLMGROUP
FLMGROUP
FLMGROUP
FLMGROUP
.....

KEY=N,AC=(PRQAC),ALTC=BACKDB
KEY=N,AC=(PRQAC),PROMOTE=TWOBACK,ALTC=BACKDB
KEY=Y,AC=(PRQAC),PROMOTE=ONEBACK
KEY=Y,AC=(PRQAC),PROMOTE=PROD,ALTC=CFGDB
KEY=N,AC=(PRQAC),PROMOTE=TEST,ALTC=MGRDB
KEY=Y,AC=(PRQAC),PROMOTE=STG2,ALTC=MGRDB
<== (*1)
KEY=Y,AC=,PROMOTE=INTE,ALTC=MGRDB

Note:
1. INTE must be included being the last key group
2. DUMMY must be included for nonedit view ( A C = , )

All project views available?


Define all remaining views of the FLM project now, for example
developer's view (FLM1) with PROD OPTION parameter translators, or
teamleader's view (FLM3) (see 12.1.3, Keep Architecture Definitions
Separate on page 198).
Assemble and link edit all project views.
Check the assembled output and scroll through it for your understanding.
Bring your FLM01* source and archdef parts under control of these
project views, build and promote them according to the defined roles.

178

ISPF/SCLM V4 Guide

Chapter 10. Method Management


Methods are work behaviors or, SCLM-specific, Language Definitions.
Methods have steps, like a job control stream may consist of steps. SCLM calls
a step a Translator. For an in-depth discussion, refer to Chapter 23, SCLM
Translator Interfaces on page 263.
Methods correlate with data set types, but are nevertheless completely
independent, because each method is associated to a part and not to the data
set type a part may reside in.
Methods could be understood as skills of a given project. Delimiting methods to
a project means build in more security and comfort at the same time.
Methods - Agreement
Each part has a method (1:1). This is automated
Methods will be defined in a project view
Project views may implement deviating executions of the same method
name
For example:
Project View
FLM
FLM1

Part name Associated Method


FLM01MD2
FLM01MD2

COB2
COB2

(execution with test options


(execution witH prod options

)
)

Architecture definitions always associate method ARCHDEF


All parts need at least a translator with FUNCT=PARSE to aquire
account data
Parts not under SCLM control can be concatenated with FLMCPYLB
FLMSYSLB libraries hold parts not under SCLM control
All methods of a subproject must be present in all views of this
subproject. For example, if view FLM contains the methods:
COPY
COPY
COPY
COPY
COPY

FLM@ARCD
FLM$BOOK
FLM@ASMH
FLM$COB2
FLM@L370

ARCHDEF
BOOKMASTER with foils style
ASMH
COB2 with TEST Options
L370

then FLM8, FLM9, ... must have these present but the contents
can be different
Project views of one sclm project should only contain the needed
methods. For example, it does not make sense for a PL/1 only project to
know COBOL.

Methods are the heartbeat of configuration management. BUILD works its way
through an invoked package or part of it according to the parts associated
method.
Methods allow for TSO, REXX, CLIST, ISPF, etc. integration and, therefore, are
perfectly able to integrate all kinds of tools, for example a data dictionary tool.
Methods may be structured using COPY, and eventually macros. A sample can
be found in Chapter 24, Translator Building Blocks, #LANG, #MACLIB, ... on
page 273.
Copyright IBM Corp. 1994

179

Methods may be modified for specific requirements. For example, specification


of data sets containing dependencies or the maximum number of includes or
change codes etc. For a detailed discussion, please refer to ISPF/SCLM Project
Manager's Guide, section Modifying Example Language Definitions.

180

ISPF/SCLM V4 Guide

Chapter 11. Security


Setting up a test environment with change and configuration management (CCM)
means to plan and build security into the system from the beginning. A
developer, for example, can only use methods that have been provided by the
SCLM project manager. This does not emphasize just control, but much more
comfort. To have the right things available at the right moment is comfort, - and
the best security.
Security may also be obtained through:
RACF (or equal) protection of applicable data sets
Authorization codes, which delimit manipulation of parts and allow for
maintenance in parallel
Backup concept

11.1.1 RACF Protection


RACF protection has already been discussed in 8.1.1, Security Scheme for
Project Data Sets on page 164.

11.1.1.1 Program Class Protection


Role management is organized through project views. After compilation and
linkage editing, these represent executable modules and reside in data set
prjid.PROJDEFS.LOAD. There is a potential risk that roles are used by
unauthorized persons and, therefore, must be separately protected (assign roles
to authorized user).
1. UACC=NONE for prjid.PROJDEFS.LOAD to initially setup the data set.
2. Define the following RACF profiles, For example:
RDEFINE PROGRAM FLM

ADDMEM('prjid.PROJDEFS.LOAD'/volser) UACC(NONE)

RDEFINE PROGRAM FLM1

ADDMEM('prjid.PROJDEFS.LOAD'/volser) UACC(NONE)

PERMIT FLM

CLASS(PROGRAM) ID(tso-user-ID) ACCESS(READ)

PERMIT FLM1

CLASS(PROGRAM) ID(tso-user-ID) ACCESS(READ)

ADDSD

'prjid.PROJDEFS.LOAD' GENERIC UACC(NONE)

PERMIT 'prjid.PROJDEFS.LOAD' ID(sclm-admin-user-ID) ACCESS(UPDATE)

3. Activate the PROGRAM class control, or refresh it if it is already activitated:


SETROPTS WHEN (PROGRAM) {REFRESH}

11.1.2 Authorization Code (AC) - Protection


Authorization codes may be used to limit sclm projects, and we have talked
about a possible implementation on 8.1.2, Alternate Definitions on page 165. A
setup scheme ought to exist to show developers their access rights at once, for
example a hierarchy view of archdefs show Authcode = FLM3 (teamleader's AC
for subproject FLM):

Copyright IBM Corp. 1994

181

SCLM41.HASINGH.ARCHDEF - HIERARCHY VIEW Command ===>


Member
Status
-------- ----------FLM01AP
FLM01AP1
FLM01ARH
FLM01CMD
FLM01LD1
FLM01LD2
FLM01LD3
FLM01LD4
FLM01SB1
FLM01SB2

Account
-------INTE
PROD
PROD
PROD
PROD
PROD
PROD
PROD
PROD
PROD

Chg Date
-------94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22

Chg Time
-------13:04:00
12:34:00
12:34:00
12:58:00
12:34:00
12:34:00
12:34:00
12:34:00
12:34:00
12:34:00

Row 1 to 10
Scroll ===
Language
-------ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF

Authc
----FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3
FLM3

11.1.3 Backup Concept


Backing up sclm projects may involve quite a challenge, which cannot ideally be
solved using incremental backup.
The reason is the strength of SCLM, basing it's information on account data sets
(VSAM), version data sets (VSAM), audit data sets (VSAM), partitioned data sets,
and eventually INFO/Man data sets. All these data sets must be synchronously
backed up.
Normally, incremental backup will check data sets for change and backup in
case a change was made.
A restore will be difficult because:
Data sets with a data loss must be identified.
Dependancies a destroyed data set may have had, must be recognized
For example:
Following a successful promote, a SCLM controlled data set of the target
hierarchy is destroyed. There is a backup of this data set reflecting the data
before promote. In this case, following dependancies must be observed:
1. Check data set types of same hierarchy level that are dependant (for
example OBJ, LIST, LMOD). These can then be restored.
2. Due to the restoring, the account data may not reflect the correct
information.
This is time consuming and a great source of errors.
Aggregate Backup and Recovery Support (ABARS) offers means to handle this
problem, and is a component of DFHSM respectively DFSMShsm.
ABARS can:
Backup sychronously all data sets belonging to a SCLM project
Restore data sets to a defined level in a short time
ABARS secures SCLM project consistency.

182

ISPF/SCLM V4 Guide

11.1.4 ABARS Implementation


To implement a procedure, five steps have to be pursued:
1. Definition of naming conventions for:
SCLM controlled data sets
Account files
Version data sets
Version/audit files
These can be taken from existing project definitions.
2. Create aggregate groups in ISMF:
ISMF offers a dialog to define the aggregate groups.
3. Create selection data set:
This data set defines applicable backup data sets, for example:
INCL(SCLM41.uid.**, SCLM41.TEAM.**, SCLM41.INTE.**, SCLM41.TEST.**, SCLM41.*.ACCTFILE, SCLM41.*.VERSFILE)

4. Installation of procedures DFHSM and DFHSMABR:


Note: DDnames MSYSIN and MSYSOUT must be defined.
5. Creation of GDG entries

11.1.5 Backup Execution


Backup is executed through a hsm command. It should be invoked at nighttime
to make sure there are no ongoing project activities.
It makes sense to do a daily security backup to be able to restore with the least
data loss.
Backup generally is very fast. Only when many aggregate contained data sets
are migrated to migration level 2 (tape or optical media), there may be delays.
Parallel backups can be done using ABARS, but another incremental backup
must not be executed at the same time.

11.1.6 Restore Project Data Sets


Restore the whole aggregate using one single hsm command.
This will restore all project data sets to the level they had at the last backup,
thereby keeping the data consistent.
In case an account, audit, or export data set is damaged and dual VSAM data
sets have been defined, a simple IDCAMS REPRO may repair the damaged file.
Note: Dual control data sets generally do not lead to performance losses.

Chapter 11. Security

183

11.1.7 Prevention Security Concept


Security primarily means prevention. Following is a discussion of a process, that
can still be done besides RACF and AC setups.
Backup through REXX user exit when promoting to level PROD for example
Dual Account, Export, Audit data sets.

11.1.7.1 Backup when Promoting to Production


The solution could be something like this:
1. FLMCNTRL macro extract from project view
FLMCNTRL ACCT=SCLM41.PROD.ACCTFILE,
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP,
VERS=SCLM41.PROD.VERSFILE,
VERPDS=@@FLMDSN.VERSION,
PRODMEXT1=SCLMISP,
PEXT1DS=SCLM41.PROJDEFS.LOAD,
PEXT1CM=LINK,
PEXT1OP='MET#P11 /',
MAXVIO=5000,
MAXLINE=75,
OPTOVER=Y

C
C
C
C
C
C
C
C
C
C

2. Invocation of SCLMISP (must be compiled and it's loadlib concatenated with


ISPLLIB). SCLMISP is needed to interface to ISPF services.
3. SCLMISP calls MET#P11 ( 11.1.7.5, SCLM Promote-Verify-Exit REXX on
page 187).

11.1.7.2 Save Previous Release


Previous releases may be saved by promoting from the current production group
into a non-key group before promoting new changes into the current production
group
Use one non-key group above the production group for each previous
release desired.
PROMOTE from the next to the top non-key group first and work DOWN to
the current production group in order to move everything up one notch.
PROMOTE the new changes into the production group as the last PROMOTE.
The desired sequence of PROMOTEs could be handled in a batch job.

184

ISPF/SCLM V4 Guide


FORBACK This is
KEY=N back

THRBACK This is
KEY=N back

TWOBACK This is
KEY=N back

ONEBACK This is
KEY=N back

RELEASE This is
KEY=Y

TEST This is
KEY=Y release

DEV2
DEV1
KEY=Y
KEY=Y

the production level code four releases

the production level code three releases

the production level code two releases

the production level code one release

the current production level code

the next set of changes for the next

Figure 115. Backup Scenario - Archive of Four Releases Back

11.1.7.3 Recover Previous Release


Recovery of the release in the ONEBACK group:
Need an alternate project definition with ONEBACK promoting to RELEASE.
Need to perform an UNCONDITIONAL promote because SCLM will know the
objects in RELEASE were not drawn down into ONEBACK
Development work in DEV1 and DEV2, may continue but UNCONDITIONAL
promotes will be required after ONEBACK promotes to RELEASE because
SCLM will know that the objects now in RELEASE were not the objects drawn
down into DEV1 and DEV2 even if the contents of the objects are the same.
SCLM will provide error messages but will let the promotes take place in
UNCONDITIONAL mode.
One needs to keep on one's toes after recovery and try to square away the
development and test groups by promoting into RELEASE and/or deleting objects
in the development and test groups (you want to get back to a normal situation
of CONDITIONAL promotes as soon as practical).

Chapter 11. Security

185


RELEASE This is the current production level code
KEY=Y

ONEBACK This is the production

KEY=Y level code one release

back

TWOBACK This is the production

KEY=Y level code two releases

back

THRBACK This is the production

KEY=Y level code three releases

back

FORBACK This is the production

KEY=Y level code four releases

back

TEST This is the next set of changes


KEY=Y for the next release

DEV2
DEV1
KEY=Y
KEY=Y

Figure 116. Backup Scenario - Inversed Archive Hierarchy to Restore Last Release

11.1.7.4 Backup of Changes


Members may be promoted to two groups in order to have a backup copy of
current changes.
Alternate project definition will contain a non-key group for the backup
PROMOTE from the alternate project definition first (must PROMOTE from a
key group to a non-key group in order to keep the members in the key group
for the next PROMOTE)
PROMOTE from the primary project definition last

186

ISPF/SCLM V4 Guide


RELEASE
KEY=Y

.
. . . . . . . . .

. . . . . . . . .
.

TEST
KEY=Y

DEV2
DEV1
KEY=Y
KEY=Y

Alternate Project Definition


has nonkey group BACKUP
. . . .
.

BACKUP
KEY=N

.
. . . .

Figure 117. Backup Scenario - Alternate Project Definition for Backup Group

11.1.7.5 SCLM Promote-Verify-Exit REXX


The REXX program MET#P11 may be invoked through the FLMCNTRL macro, in
which case MET#P11 must be found in the SYSEXEC or SYSPROC concatenation.
MET#P11 examplifies in this sample the levels ONEBACK and TWOBACK. The
promote exit may be coded as:
*********************************************************************
* Promote-Verify-Exit: Promote to ONEBACK/TWOBACK first
* - invoke SCLMISP, to include ISPF services
* - SCLMISP calls REXX pgm, which must be found in SYSEXEC concat
*********************************************************************
FLMCNTRL ACCT=account-file,
PRMEXT1=SCLMISP,
PEXT1DS=loadfile holding SCLMISP,
PEXT1CM=LINK,
PEXT1OP='REXX pgm/',
OPTOVER=Y

C
C
C
C
C

Figure 118. Backup Scenario - REXX Program Call in FLMCNTRL Macro

11.1.7.6 Promote-Verify-Exit MET#P11


/***********************REXX****************************************/
/*
*/
/* PROMOTE-VERIFY-EXIT
*/
/* - for archdef only
*/
/* - used to archive iteratively through the hierarchy
*/
/* * from ONEBACK TO TWOBACK
*/
/* * from PROD
TO ONEBACK
*/
/* - Is triggered when promote from TEST to PROD
*/
/* - When PROD & ONEBACK & TWOBACK are empty, UNCONDITIONAL PROMOTE*/
/* - A report will be written to terminal
*/
/* - The highest rc of 'FLMCMD PROMOTE' will be returned
*/
/*
*/
/*******************************************************************/
Trace off
Signal on Syntax
Signal on Halt
Signal on Novalue
Parse Upper Arg OPTIONS '/' ,
FNAME
',' ,

/* Optional Parameters list */


/* Function Name
*/
Chapter 11. Security

187

PROJECT
VIEW
USERID
GROUP
TYPE
PART
SCOPE
MODE
TOGROUP
JUNK
OPTIONS
FNAME
PROJECT
VIEW
USERID
GROUP
TYPE
PART
SCOPE
MODE
TOGROUP

=
=
=
=
=
=
=
=
=
=
=

LINES =
RETCD =
twoprc =
BASELINE=
BASETYPE=
BASELN1B=
BASELN2B=

','
','
','
','
','
','
','
','
','
.

,
,
,
,
,
,
,
,
,

/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

PROJECT
Alternate View
user ID
Group
Type
Member Name
Scope
Mode
Promote to Group
Throw away

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

strip(OPTIONS)
strip(FNAME)
strip(PROJECT)
strip(VIEW)
strip(USERID)
strip(GROUP)
strip(TYPE)
strip(PART)
strip(SCOPE)
strip(MODE)
strip(TOGROUP)
0
0
0
'PROD'
'ARCHDEF'
'ONEBACK'
'TWOBACK'

/*
/*
/*
/*
/*

Count Promote RCs


BACKUP Baseline
Select Basetype
Select Backup 1
Select Backup 2

*/
*/
*/
*/
*/

If TOGROUP = BASELINE then do


/* Select Baseline
*/
If TYPE = BASETYPE then do
/* Select Basetype
*/
LINES = LINES + 1
/* Mark LINES = yes */
Call OUT1TOP
/* Write top line
*/
TARGET = BASELN2B
/* Targetline
*/
'FLMCMD PROMOTE,'PROJECT','VIEW','BASELN1B','TYPE','PART''
targetrc = rc
twoprc = rc
/* First Promote count*/
Call TESTRC
/* Test RC
*/
TARGET = BASELN1B
/* Targetline
*/
'FLMCMD PROMOTE,'PROJECT','VIEW','BASELINE','TYPE','PART''
targetrc = rc
twoprc = twoprc + rc
/* + 2. Promote count */
Call TESTRC
Call OUT1BOT
/* Write bottom line */
end
/* end BASETYPE
*/
end
/* end BASELINE
*/
/*********************************************************************/
/* Write report
*/
/*********************************************************************/
If LINES > 0 then do
/* write report
*/
do queued()
/* all stacked lines */
parse pull LINE
/* start from top
*/
say LINE
end
end
EXIT RETCD
/******************************************************************/
/* TESTRC: test RC after PROMOTE
*/
/******************************************************************/
TESTRC:
If targetrc <> 0 then do
/* PROMOTE not ok */
If RETCD < targetrc then RETCD = targetrc
Call OUT1ERR
If twoprc = 32 then RETCD = twoprc
/* Both levels empty */
Call OUT1MSG
/* Allow PROMOTE
*/
end
else Call OUT1OK
return
/******************************************************************/
/* OUT1OK: Confirm archiving
*/
/******************************************************************/
OUT1OK:
queue ' '
queue 'MET#P11: PROMOTE/ARCHIVE to 'TARGET' was'
queue 'successfully accomplished'
queue ' '
return
/******************************************************************/
/* OUT1MSG: Reminders of possible errors
*/
/******************************************************************/

188

ISPF/SCLM V4 Guide

OUT1MSG:
queue 'Message:'
queue 'MET#P11: Type 'TYPE' of 'BASELN1B' did not contain 'PART
queue 'MET#P11: Type 'TYPE' of 'BASELINE' did not contain 'PART
queue 'MET#P11: ===> FLMCMD was probably not available'
queue ' '
return
/******************************************************************/
/* OUT1ERR: write error
*/
/******************************************************************/
OUT1ERR:
queue ' '
queue 'MET#P11: PROMOTE/ARCHIVE to 'TARGET' was'
queue 'not accomplished, PROMOTE has ended with RC=' targetrc
queue ' '
return
/******************************************************************/
/* OUT1TOP: write top lines
*/
/******************************************************************/
OUT1TOP:
queue '**'center('*',75,'*')'**'
queue '**'center(' ',75,'*')'**'
queue '**'center('Software Configuration and Library',
'Manager',75)'**'
queue '**'center(' ',75)'**'
queue '**'center('PROMOTE VERIFICATION EXIT REPORT',75)'**'
queue '**'center(' ',75)'**'
OUTLINE = 'Option:
'OPTIONS
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'Function:
'FNAME
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'PROJECT:
'PROJECT
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'Alternate View 'VIEW
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'USERID:
'USERID
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'GROUP:
'GROUP
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'TYPE:
'TYPE
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'Object:
'PART
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'SCOPE:
'SCOPE
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'MODE:
'MODE
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
OUTLINE = 'TO-GROUP:
'TOGROUP
OUTLINE = left(OUTLINE,28)
queue '**'center(OUTLINE,75)'**'
queue '**'center(' ',75)'**'
/******************************************************************/
/* OUT1BOT: write bottom lines
*/
/******************************************************************/
OUT1BOT:
queue '**'center('*',75,'*')'**'
queue '**'center(' ',75)'**'
queue '**'center('Software Configuration and Library',
'Manager',75)'**'
queue '**'center(' ',75)'**'
queue '**'center('End: PROMOTE VERIFICATION EXIT REPORT',75)'**'
queue '**'center(' ',75)'**'
/*OUTLINE = date('0')' 'time() */
queue '**'center(OUTLINE,75)'**'
queue '**'center(' ',75)'**'
queue '**'center('*',75,'*')'**'
return

Chapter 11. Security

189

11.1.7.7 SCLMISP - Interface to ISPF Services


SCLMISP has been described in SCLM WSP/2 Usage Guide. It must be compiled
with the assembler compiler and link edited. The code is available on the
enclosed diskette.
Implement Backup
Code FLMCNTRL macro in SW configurators view to reflect invocation of
MET#P11
SYSPROC concatenation must include the data set that contains
MET#P11.
Compile / link edit interface SCLMISP in
prjid.PROJDEFS.LOAD(SCLMISP).
ISPLLIB concatenation must include prjid.PROJDEFS.LOAD data set
Test your implementation. (You might want to switch Trace ' r ' on.).

11.1.8 Dual Account and Audit Data Sets


Dual data sets may lead to a better security if all account data would reside in
one data set. If, however, many account data sets are setup to reflect role
management, single account data sets seem sufficient, provided DFSMS backups
have been done regularly.
Table 10. Dual Control Data Sets:
Group

View

Name of data set

Define dual data sets


Decide which dual data sets you find necessary and enter them into the
matrix.
Enhance implementation of FLMCNTRL macro accordingly and don't
forget to allocate data sets.

11.1.9 Change Control


The following is a quotation from an SCLM conference disk:
Most of change management happens before SCLM gets involved. Users
request a change in functionality, testers report a discrepancy, or systems
programming wants to install a new release of a language. These requests are
tracked, and go through a life cycle.
1.
2.
3.
4.
5.
6.
7.
8.

Under assessment
Valid but unassigned
Under development
Promoted to integration
Promoted to test
Released to be filed
Installed at production (site x)
Closed

There is much information associated with Problem Trouble Reports (PTR) and
Change Requests (CR) which has nothing to do with SCLM, such as who

190

ISPF/SCLM V4 Guide

reported the problem, what supporting data exists, the estimated cost to
implement, what CCB approved the assignment to RELEASE N, and much more.
So what might SCLM users care about?
Well, what PTR/CRs are at stage ready to go to integration. But you have that
with SCLM change codes and the change code report.
Maybe you would like to make sure that all PTR/CRs being promoted have been
approved for this release. This requirement could fall either way; either the
change management system interrogates SCLM and builds a report, or SCLM
interrogates the change management system and fails a condition promote if
validation fails.
Since I preapprove all promotion (pull-up, not push-up), the former is how we did
it. This is still not required by SCLM, except (perhaps) to supply the change
codes (at a level) in tabular format that is suitable for import into a relational
database.
Pulling fixes shouldn't require a change management package since you have
change codes associated with members. What would a change management
package add?
In conclusion, the change management system is far more interested in SCLM's
data than SCLM is interested in the change management system's data. I am
willing to entertain the counter arguments.

11.1.9.1 Non-Key Groups for Staging QA Pull-Up

Production

Stage Prod

Systemtest

Stage QA2

Integration

Stage QA

Team

Development

Figure 119. Pull-up for Better Quality Assurance

Chapter 11. Security

191

A non-key group is put additionally into the project to stage the promote process
and allow for a safer roleplay.
The developer stages the parts in a staging group, where the quality assurance
function can pull-up whenever it is convenient, thereby also taking parts away
from the developer.

11.1.9.2 Use of Primary Non-Key Groups in an SCLM Hierarchy


The following is a quotation from an SCLM conference disk:
There is no SCLM restriction that two or more key groups cannot PROMOTE to
a non-key group.
This is not easy to explain. Using an automotive analogy: people usually believe
it is not possible to jump start a 6 volt car from a 12 volt car yet it can be done
safely if one takes a few precautions.
In SCLM Project Manager's Guide, section Primary Non-Key Group Testing
Techniques, there is a discussion about the use of a primary non-key group in
an alternate project definition. A similar discussion is in the earlier releases. The
problem is that a PROMOTE from a primary non-key group does not delete the
members. A primary group is a group that will be used in the concatenation of
data sets to find a member. All key groups in a hierarchical path above any
given group will be primary as will the group at which the concatenation begins.
Non-key groups are normally only primary when you start at a non-key group
and proceed up the path through other non-key groups to the first key group at
which point the non-key groups which only PROMOTE to one key group are
skipped. Having more than one key group PROMOTE into a non-key group will
make that group a primary group. You may get a warning message during the
assembly of the project definition.
One could use an alternate project definition with a corresponding key group for
promotional purposes. One should not simply make the primary non-key group a
key group in the alternate project definition. Alternate project definitions are
powerful tools that will gladly supply one with sufficient rope to hang oneself
from the nearest hierarchical tree; so be careful.
Promotion from the primary non-key group to a normal integration group will
leave members behind in the primary non-key group. They may be deleted
manually using SCLM utilities.

11.1.10 PDF Edit Outside SCLM


In case the hlq of the data set to be edited equals the hlq of the data set
hlq.PROJDEFS.LOAD, a warning message will be sent (SCLM standard since
SCLM 3.1)
There is a bit in the ISPF statistics indicating whether a file was edited by
SCLM or not. According to the setup in the PDF configuration table, the
editor may or may not be invoked.

192

ISPF/SCLM V4 Guide

11.1.10.1 PDF Configuration Table for Edit Control


SCLM project data sets must not be edited outside SCLM control. If so, account
files may not be in sync and may produce follow-up problems.
PDF Version 3.4 and later allows the SCLM project manager to select the
protection of SCLM data sets according to the following list.
Mode
WARN

ERROR

NONE

Description
ISPF/PDF examines if the edited part is member of a SCLM project. If
so, a warning will be given: Edited Member Possibly Part of an SCLM
Project.
Editing and saving of this member, however, will be honored.
ISPF/PDF examines if the edited part is member of a SCLM project. If
so, an error message will be provided: Member of SCLM Data Sets
May Not Be Editted.
Editing with the ISPF/PDF editor is now prohibited.
There is no checking at all. SCLM controlled data sets may be edited
outside SCLM.

Note: ISPF uses the following criteria to decide whether a member is part of an
SCLM project:
The existence of data set ' projid.PROJDEFS.LOAD', whereby projid is the hlq
of the data set where the edited part will reside.
The member was last saved by SCLM.

11.1.10.2 Technical Implementation


The technical implementation can be done via the ISPF/PDF configuration load
module ISRCONFG. The source to create such module may be found in
'ispf....SISPSAMP(ISRCNFIG)'.
This source contains a field named SCLMCHK defaulted to CL5'WARN '. To
change the edit mode, this field must be changed and the source compiled and
link edited.
More information for this customization can be found in ISPF Planning and
Customizing, the section for Tailoring ISPF Defaults.
Note: This module resides in 'ispf...SISPLPA' by default, which normally is
concatenated to LPALIB concatenation. Attention must be paid to make
sure you really access the modified configuration load module.

Chapter 11. Security

193

194

ISPF/SCLM V4 Guide

Chapter 12. Version Control


SCLM distiguishes two kinds of version control:
Vertical releases
Horizontal source histories.

12.1 Vertical Releases


Vertical releases reflect the number of parts of a given project and application in
a hierarchical level. In the top level, for example group PROD, all parts are
present. This is important to understand for delivery. SCLM supports a
multi-baseline concept, which means there can be as many baselines as levels
(key groups) in existance. For example, Figure 107 on page 163 contains a
maximum of five. The lower baselines, however, do not reflect the full resource
of parts, but rather the delta of parts.
Agreement
ONE full part release.
Many delta part releases.
A release is constructed through BUILDing.
Each release represents a baseline.
The baseline moves up the hierarchy as the promote moves up.

12.1.1 Development, Maintenance and Fix in Parallel


Development of parts depends on the project design.
Maintenance must be differentiated between a feature and a fix. A fix may be a
shortcut, while a feature may support a better solution and be contained in the
next release.
Baseline - Agreement
Fix refers to changes made to the production level (baseline Rx.1) and
will work through a separate sclm project and it's views.
Maintenance refers to changes made to the hierarchy level, where the
next release resides (baseline Rx.2) and may be executed through an
additional project view.
Development refers to third release (Rx.3).
Agreed ?
Y/N ______ .

A communication may be established between fix changes and the development.


See Chapter 16, Communication on page 215.

Copyright IBM Corp. 1994

195

12.1.1.1 Fix
Solution 1 - Fix Dominates and will be Integrated to PROD

prjid1
prjid2 (sclm(FIX)-Project)


prod
prod

AC=,

AC=FIX

qa

qa

AC=FIX

AC=x

- The fix developer maintains

parts with another AC, which

delimits these parts to QA,


developer
developer
and development can not be

AC=x

AC=FIX
done without communicating QA.

Figure 120. Fixes are Integrated Immediately to PROD

Solution 2 - Concatenation with JCL

prjid1

prjid2
(prjid2 = Fix Project)


prod
prod

AC=,

AC=,

qa

qa - PRE-Concatenated

AC=x

AC=FIX

developer
developer

AC=x

AC=FIX

Figure 121. Fix Load Data Sets, Preconcatenated

This project view does not allow FIXes promote to production.


Solution 3 - Concatenation JCL with Non-Key Group

prjid1

prjid2



prod
prod

AC=,

AC=,

apply

AC=FIX

qa

qa

AC=FIX

AC=x

developer
developer

AC=x

AC=FIX

(prjid2 = Fix Project)

<- Freeze promote


<- Double code (NON-KEY)
<- Concatenate APPLY, PROD,

Figure 122. Non-Key Group APPLY Preconcatenate PROD

196

ISPF/SCLM V4 Guide

This solution is basically the same as the previous one. It opens, however, the
possibility to pull back a fix in a running system (for example CICS) by deleting
the loadmodule (with Option 10.3.1) in the group APPLY.
Yet another QA view may allow a promote to PROD after a trial period.
Implement Fix View in sclm-FIX-project
TITLE '*** Fixes not to be included to PROD ***'
prjid
FLMABEG
*
PRJAC
FLMAGRP AC=(FIX)
-- sclm-project FIX
-*
....
*
* ==> Developer's view of fix project
*
* -----------------------------------* | dfix ==> QFIX ==> APLY / PROD
* -----------------------------------*
*********************************************************************
PROD
FLMGROUP KEY=Y,AC=,
APLY
FLMGROUP KEY=N,PROMOTE=PROD,ALTC=xxxDB,AC=(PRJAC)
QFIX
FLMGROUP KEY=Y,PROMOTE=APLY,ALTC=xxxDB,AC=(PRJAC)
dev1fix FLMGROUP KEY=Y,PROMOTE=QFIX,ALTC=DEVDB,AC=(PRJAC)
dummy
FLMGROUP KEY=Y,PROMOTE=QFIX,ALTC=DEVDB,AC=(PRJAC)
....

This would also allow for a combination to set up another view to allow promote
to PROD, which could be done by QA after a certain test period through the
concatenation.

12.1.2 Multiple Releases, Globals, Locals and Maintenance in Parallel

D
E
V
E
L
O
P

Concatenate Fixes

prjid1 to n


Baseline Rx.1
PROD
PROD

/ AC=,
AC=GLO
/ AC=,
Rx.2

prjid3(GLO)
prjid2(FIX)
TEST
Maintenance Rx.2

APLY
APLY
NK
NK AC=FIX
AC=prjid qa
Rx.3
/ AC=,

INTE

qa-GLOBAL
qa-fix
AC=prjid

AC=GLO
AC=FIX
-MENT

TEAM
LO-

CALS dev

developer
dev-GLOBAL
dev-fix
AC=GLO
AC=FIX

Figure 123. Concatenate Fixes, Integrate Maintenance, Control Development

This solution represents a combination of all relevant development necessities.


Fixes

Change the productive release, for example baseline Rx.1, through:


Non-key group APLY and preconcatenated load libraries, or
Direct promote to PROD (parts in APLY will be deleted).
Note: In case remote PROD systems must be considered, parts
should be promoted to a non-key delivery group when being

Chapter 12. Version Control

197

promoted to APLY, or PROD respectively (this can be


automated through a promote exit, as shown in sample
11.1.7.5, SCLM Promote-Verify-Exit REXX on page 187).
Globals

Are cross project functions and should be maintained through an own


subproject for better security and integrity.

Maintenance Consist of changes executed against the system test release, here
Rx.2, and will be developed / promoted through distinct project views
of an sclm project, for example FLM6.
Development Represents the next release, here Rx.3, of development.
Locals

(or project globals) are subproject cross functions, for example,


12.1.3, Keep Architecture Definitions Separate on page 198.

The whole setup requires role management and separated account files:
A SW developer can promote up to group TEAM (or STG1 respectively).
A SW teamleader may promote to group INTE directly.
A SW manager can promote up to group INTE, but may not edit.
A SW configurator can promote up to group TEST and eventually PROD, but
may not edit.

12.1.3 Keep Architecture Definitions Separate


Architecture definitions represent a blueprint of an application, and may
therefore be kept separate to enforce their fulfillment. This could be considered
another quality assurance approach.

prjid1

prod
Baseline Rx.1
prod

Rx.2
test

Rx.3
inte
AC=x3

AC=,

team

AC=x

developer
teamleader (develops archdefs for development)
AC=x
AC=x3

Figure 124. Archdefs must be Fulfilled

1. The sclm project leader (team leader) writes all architecture definitions (or is
responsible for it), provided the members exist, and promotes them through
a different promotion path in a promote container, for example:
***********************************************************************
* FLM01AP
*
* TEAMLEADER
* - CREATES PLANS (ARCHDEFS)
* - PROMOTES INTO DEVELOPER'S HIERARCHY
*
***********************************************************************
*
PROM
FLM01AP1 ARCHDEF N * APPLICATION FLM01AP1
PROM
FLM01SB1 ARCHDEF N *
PROM
FLM01SB2 ARCHDEF N * <== (*1)

198

ISPF/SCLM V4 Guide

PROM
PROM
PROM
PROM
PROM
PROM

FLM01ARH
FLM01CMD
FLM01LD1
FLM01LD2
FLM01LD3
FLM01LD4

ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF

Note: A third nonblank parameter (that is, N ) indicates that no date


checking is performed, thereby eliminating the need to build before
promoting, and is not recommended.
2. These parts receive another authorization code (for example FLM3).
Developers may not edit the archdefs (no edit access, no AC update).
3. BUILD for a developer can only be successful if parts are consistent (all
parts present) and built correctly using the project leaders archdefs.
4. PROMOTE must only be executed through archdefs, and this may be forced
by making Type = ARCHDEF a must (through Promote panel).

SCLM Promote - Entry Panel


Command ===>

Promote input:
Project . . .
From group .
Type . . . .
Member . . .

: SCLM41
. HASINGH
. ARCHDEF
.

Alternate - FLM

Define Enterprise Infrastructure


In 8.1.7, Hierarchy Organization on page 169 you have defined your groups.
Please amend now.

Your Solution
No. of releases
Levels
Roles

?
?
?
?

_________________________________________
___
________ ________ ________ ________ ________
________ ________ ________ ________ ________

FIX:
account-file-name d ?
account-file-name q ?
?
(version-file-name) ?
(version-pds-name ) ?
GLOBALs
account-file-name

?
?
(version-file-name) ?
(version-pds-name ) ?

LOCALS:
account-file-name

_____________________
_____________________
_____________________
_____________________
_____________________

(sclm41.dfix.acctfile )
(sclm41.qfix.acctfile )
(sclm41.fix.versfile )
(@@FLMDSN.VERSION
)

_____________________ (sclm41.glob.acctfile )
_____________________
_____________________ (sclm41.glob.versfile )
_____________________ (@@FLMDSN.VERSION
)

? _____________________ (sclm41.team.acctfile)
? _____________________ (sclm41.inte.acctfile)

Implement FIX, GLObal, Maintenance and Local Views


Now all information is available to implement these views.

Chapter 12. Version Control

199

12.2 Horizontal Source Versioning


In addition to vertical releases, source histories may be acquired by defining
versioning for a given type and group. Although any type and group could be
versioned, in practice it makes more sense for static data sets, for example
production data sets, fix qa data sets, global qa data sets, bought module data
sets, and many more.
Define Source Versioning

Group
Type
(i.e. PROD, FIX) (i.e. COBOL, REXX, ARCHDEF, SCRIPT)
________
________ ________ ________ ________ ________
________
________ ________ ________ ________ ________
________
________ ________ ________ ________ ________

12.2.1 Implementation
Implement Source Versioning
*********************************************************************
* ===> SW Configurator
*********************************************************************
FLMCNTRL ACCT=sclm41.prod.acctfile,
DSNAME=sclm41.@@FLMGRP.@@FLMTYP,
VERS=sclm41.prod.versfile,
VERPDS=@@FLMDSN.VERSION,
OPTOVER=Y
*
FLMATVER GROUP=PROD,TYPE=ARCHDEF,VERSION=YES
FLMATVER GROUP=PROD,TYPE=REXX,VERSION=YES
FLMATVER GROUP=PROD,TYPE=SOURCE,VERSION=YES
FLMATVER GROUP=PROD,TYPE=SCRIPT,VERSION=YES

Insert FLMATVER definitions


Allocate VSAM and PDS data sets
Compile / link edit views

12.2.2 Recording the Versioning


Recording starts after successful implementation.
Delta Versioning Recording - Agreement
Recording when? At:
SAVE (or through invocation of SAVE service)
Migrate (Selection 10.3.3)
Promote. Recording aquired for target group.
Last recording = Full source
Previous recordings = Delta

200

ISPF/SCLM V4 Guide

C
C
C
C

12.2.3 Retrieve a Recorded/Versioned Part


Only one part can be retrieved at a time and will be executed through selection
10.3.8.
Versioning - Agreement
A source part is referenced by a build map record
A build map record holds information for time, version#, etc.
An audit record holds information about the availability of source code.

Chapter 12. Version Control

201

202

ISPF/SCLM V4 Guide

Chapter 13. What is Configuration Management?


In a recent report on Configuration Management tools, Ovum defines
Configuration Management as the ability to identify, manage and control
software and software related components, such as requirement specifications,
documentation, test suites, as they change over time. This includes managing
the relationships between the software components and the related components.

Configuration management can be broken into several related processes.


Parts Access, is the classification, control and storage of the component parts
which make up an application. It manages user access to the component parts
that are maintained in the library system.
Build Management involves the process of building individual components or
complete applications from the component parts in development, the ability to
build or make an application. Dependency management is the part of build
management that allows the system to determine the minimum work (compiles
and such) that need to be done to rebuild an application or a component.
Change Control controls the introduction of change into an application or
component. It enforces the development process, ensuring quality control, and
creating a tracking mechanism for reporting.
Version Control represents the ability to maintain and control multiple variations
of a single component part. Expanding on this, it is the ability to version an
application or other compound part. That is, knowing which variant of each
component makes up a given version of an application.

13.1 Why Configuration Management?


The most basic concepts within configuration management have been around for
years: parts access and version control. In many small shops with few numbers
of programmers or simple application structures, these processes are handled
manually. And even in many large shops, tools which only address these basic
concepts of configuration management have been in use for years. But manual
processes and the basic functions are no match for today's complex
environment. The cost of not having functionally rich CM tools can be reflected
in the types of complaints voiced here and many more. They can be measured
in increased cycle time, poor quality, and dissatisfied customers.

13.2 Trends Driving Configuration Management


There are many trends driving software developers from manual processes or
basic CM tools to functionally rich CM tools. Developing software has never
been easy. Today's software development environment is increasing that
complexity. Frequently an application is made of parts created using various
tools: design tools, compilers, 4GLs, and more. In addition, developers often
must include a graphical user interface (GUI), which involves another tool.
Adding to that complexity is the challeng e of varied topologies. Frequently
today, an application is developed in one environment to execute on multiple
platforms. In the case of client/server applications, part of the code is targeted
Copyright IBM Corp. 1994

203

to the client and part to the server. These problems present new challenges to
development teams that are being asked to deliver software products at faster
and faster rates. Configuration Management tools help with these problems by
providing an efficient application development environment that helps control
and manage application components, tracks feature and defect changes to those
components, and helps build applications for varied topologies.
Developers who are grappling with these issues of complexity have recognized
that process can help bring order to the chaos. The Software Engineering
Institute (SEI) at Carnegie Mellon University has defined a software process
maturity model. In this model, the ability to produce quality software is
measured on a scale of one to five. It is closely related to process
implementation and improvement. One recognized means of raising maturity
levels is through the successful deployment of good configuration management,
and especially through an enforced process for introducing change into your
system. Once you have defined processes and enforce their implementation, the
quality of your application is enhanced. In fact, only when a system provides a
process, is it possible to achieve standards such as ISO 9000.
CM tools also help provide cost-effective maintenance by providing the ability to
identify exactly what was included in each release of an application, to rebuild
the application at any level, track changes to each level, and ensure fixes are
carried forward to later releases of the application.
These are the issues from a developer's perspective. From a management
perspective, corporations today are recognizing that software is a valuable asset
that must be managed, tracked and controlled. They can no longer afford to let
programmers work in unstructured, chaotic environments.

13.3 Build Management


As we just discussed, the increasing complexity of applications presents new
problems to the development team. Configuration management tools can help
address this problem with enhanced build management.
The most basic of CM tools only address build management by making the parts
available to a MAKE tool. This is an alternative that has been acceptable for
years. However, it requires the programmer to bridge between the CM tool and
the build tool, and it excludes the possibility of a tightly controlled process. As
build technology has advanced, state of the art CM tools have begun to integrate
build management into their tool. Building 3GL applications involves well
understood processes and steps, such as compile and link. 4GLs frequently
require that additional steps be taken, such as generating source for compile or
link, or incorporating a modify step within this process. Some CM tools are
geared to handle one or two types of development. But the requirement today is
for a build process that is flexible enough to incorporate many methodologies.
With larger and larger applications, dependency management becomes a critical
part of the build process. Effective dependency management improves the
efficiency of the CM system by minimizing the number of components that are
rebuilt following changes.
Hence, configuration management must incorporate build management with
dependency management to deliver a fully integrated development process.

204

ISPF/SCLM V4 Guide

13.4 Change Control


As discussed earlier, creating order from the chaos is a key function of a
configuration management tool. One way to accomplish this is to provide a
consistent and systematic approach for introducing change within your
application. In other words, provide a process for change control. This process
should be tailorable, provide the developer the opportunity to do impact analysis
before implementing a change and should provide a reporting facility for tracking
the changes. Additionally, integrating the process with the build function
provides a system which allows the developer to control the introduction of
change and build that change into the application or componentry in a reliable,
repeatable manner. This capability provides an auditable system where
changes can be tracked and appropriate reports generated.

13.5 Version Control


Development's job typically doesn't end when an application is released to the
end user. When version 1 is released, someone starts working on version 2.
Simultaneously, the same person or someone else has to fix bugs in version 1.
Additionally, the software may have been created for multiple platforms with
each platform version a bit different. Each of these versions must be easily,
quickly and reliably reproducible. But this problem really begins long before the
first release. During initial development, the versioning system must be able to
tell the test version from the version that has enhancement a, b, and c from the
version in an individual developer's workspace.

13.6 Imperatives for AD Tools


Tools today must be easy to use. This includes being easy to install which
covers both easy setup and the ability to efficiently migrate in applications from
other tools. It also means providing a graphical user interface that presents
function in an intuitive manner. Programmers want tools that can be tailored to
their environment and which can work with the other tools in their toolbox. In
the best case, this may mean tools have been setup to work with a set of tools,
or secondly, that they are easily tailored to work with a larger set of tools.

13.7 SCLM Identification


Parts identification is recorded by a parser at save or migrate time, as well as
BUILD (upward dependencies through generation) time.
SCLM contains a parser for almost all languages, as well as parsers written in
REXX for Cobol, Pl/1 and C.
Parser can be customized by the SCLM project manager. An example is
described in the ISPF/SCLM Project Manager's Guide.

Chapter 13. What is Configuration Management?

205

13.8 SCLM Management


Management of SCLM parts is done through:
Account records (who, when, where, how)
Audit records (versioning: when, who, where, what)
Build map records (footprint of a part)
This data is data about parts, metadata, and can be analyzed through one of the
following.
1. Online reports, like:
SCLM option 10.3.4 - Database Contents Reports
SCLM option 10.3.5 - Architecture Reports.
2. Invocation of DBACCT or DBUTIL service (see ISPF/SCLM Reference)

13.9 SCLM Control


SCLM verifies and delimits the access of developers to parts, integrates
consistently BUILT parts, and provides user exits for individual enhancements.

13.9.1 Access Control and Delimitation


At least one authorization code (AC) is bound to any part throughout SCLM.
The AC can generally be changed through option 10.3.1. To avoid changes to the
production level (where subprojects summit), this level must have its own
account file that can only be accessed in change mode by the SW configurator,
thereby effectively delimiting sclm subprojects.

13.9.2 Integrity
Having BUILT a part according to its associated language definition, it becomes
integral. This gives the SCLM project manager control of integrity by making the
language definitions available with the wanted skills for a given project. The
SCLM project manager represents an enterprise view of wants and needs which
may comfort and delimit developers. The SCLM project manager establishes the
integrity ceiling that developers are limited to.

13.9.3 Consistency
A part is consistent when present as an architecture definition and has been
BUILT integrally (successfully).
A PROMOTE can only happen for parts that are integral and consistent.

13.9.4 User Exits


SCLM provides several user exits:
1. At EDIT via FLMCNTRL and CCV
2. At BUILD via FLMCNTRL
3. At PROMOTE via FLMCNTRL
Subtime Verify
Subtime Copy

206

ISPF/SCLM V4 Guide

Subtime Purge
4. Implemented in language definitions at time
FUNCT=BUILD / VERIFY / COPY / PURGE

13.9.5 Example of a REXX CCV Routine


A change to a part without permission (or a change control order) is a habit in
many companies. But then, an effective control is normally not in effect. This
can be obtained through a change control verification routine (CCV). The
example just verifies the mandatory entry of a CCV number that again may
reference a change control sheet, and can be willingly enhanced.
/*REXX*/
/****************************************************************/
/* - A Change Code Number must be entered
*/
/* If NOT, prompt will occur
*/
/* True = RC 0. OK
*/
/* False = RC 8. This RC will prompt for a change code
*/
/****************************************************************/
ARG PARMS
PARSE VAR PARMS OP "/" PARM
PARSE VAR PARM GROUP "," TYPE "," MEMBER "," LANG ",",
USRID "," AUTH "," CCODE
IF CCODE NOT = "" THEN DO
RETURN 8
END

Figure 125. REXX MET#CCV1 Obliges a CCV Number

13.9.6 REXX CCV-Routine in FLMCNTRL


FLMCNTRL
ACCT=....,
VERCC=MET#CCV1,
VERCCDS=SCLM41.PROJDEFS.REXX,
VERCCOP='ANYPARM/',
VERCCCM=TSOLNK,
OPTOVER=Y

C
C
C
C
C
C

Figure 126. FLMCNTRL Macro Implementation of REXX CCV-Program

Implement CCV Routine


1. Code above REXX example in prjid.PROJDEFS.REXX.
2. prjid.PROJDEFS.REXX must be in SYSPROC concatenation. Alternately, it
may be in SYSEXEC concatenation.
3. Manipulate FLMCNTRL. Only necessary for views with edit permission.
4. Test behavior by editing any part (10.2).

13.9.7 Example of a REXX BUILD Translator


This example is only meant to give you an initial feeling of the huge possibilities
translators in language definitions provide. Actually this is the focal point of all
possible tool integration, like for example, data dictionary integration.

Chapter 13. What is Configuration Management?

207

********************************************************************
* BUILD TRANSLATOR - TEST PARMETERS
********************************************************************
FLMTRNSL CALLNAM='BUILD-PARAMETER',
FUNCTN=BUILD,
COMPILE=IRXJCL,
DSNAME=SCLM41.PRODJEFS.REXX,
VERSION=1.0,
GOODRC=4,
PORDER=1,
PDSDATA=Y,
OPTIONS='BUILDX1 PARAMETERTEST:
@@FLMPRJ @@FLMGRP @@FLMTYP @@FLMMBR @@FLMUID
@@FLMFDT @@FLMFTM @@FLMONM @@FLMINF @@FLMINC
@@FLMALT @@FLMDBQ @@FLMCUN @@FLMSRF'

C
C
C
C
C
C
C
C
C
C
C

Figure 127. REXX BUILDX1 to Demonstrate a REXX Build Translator

Note: Variable @@FLMONM is not available at promote time, and cannot be


included in this REXX Procedure (see section SCLM Variables and Their
SCLM Functions in ISPF/SCLM Reference).
This procedure does not run in REPORT mode, because the translator
would not really be processed.
/*REXX*/
/******************************************************************/
/* Build Processor
*/
/* - Print Parameter List for Demonstration
*/
/******************************************************************/
trace 'off'
signal on ERROR
/* E N T R Y *****************************************************/
/* Parameterlist
*/
/* Pos Len Name
Content
*/
/******************************************************************/
say 'BUILDX1: Start Translator-Function: BUILD'
parse arg PARAM
say 'Parameter:
' PARAM
parse arg L1PAR L1PRJ L1GRP L1TYP L1MBR L1UID ,
L1FDT L1FTM L1ONM L1INF L1INC ,
L1ALT L1DBQ L1CUN L1SRF .
say 'Environment ' ADDRESS()
say 'Option:
' L1PAR
say 'Projectname: ' L1PRJ
say 'Group:
' L1GRP
say 'Data set type ' L1TYP
say 'Member:
' L1MBR
say 'User:
' L1UID
say 'Date:
' L1FDT
say 'Time:
' L1FTM
say 'Output-Member:' L1ONM
say 'SCLM-Pointer: ' L1INF
say 'INCL-Pointer: ' L1INC
say 'ALT.-Project: ' L1ALT
say 'DB-Qualific.: ' L1DBQ
say 'CU-Name:
' L1CUN
say 'Default type: ' L1SRF
exit 0
/******************************************************************/
/* Error Routine
*/
/******************************************************************/
ERROR:
say 'BUILDX1-ERROR: Statement' sigl 'endet with RC = ' RC
return

Figure 128. REXX BUILDX1 to Demonstrate a REXX Build Procedure

208

ISPF/SCLM V4 Guide

13.9.8 Invocation REXX Procedure from FLMCNTRL Macro


FLMCNTRL ACCT=SCLM41.projdefs.acctfile,
BLDEXT1=IRXJCL,
BEXT1DS=SCLM41.PROJDEFS.REXX,
BEXT1OP='BUILDX1C TEST @@FLMDSN:'
BEXT1CM=LINK,
MAXLINE=75,
OPTOVER=Y

C
C
C
C
C
C

Figure 129. Example to Invoke REXX Program through FLMCNTRL Macro

The BUILD exit is executed at the end of BUILD


Variable @@FLMDSN is passed only when:
PDSDATA=Y set in FLMTRNSL macro (see ISPF/SCLM Reference,
FLMTRNSL macro)
BEXT1CM=LINK
/*REXX*/
/******************************************************************/
/* BUILD Exit Control: Invocation via FLMCNTRL
*/
/******************************************************************/
trace 'off'
signal on ERROR
/******************************************************************/
/* E N T R Y ****************************************************/
/* Parameterlist
*/
/* Pos Len Name
CONTENT
*/
/******************************************************************/
say 'BUILDX1C: Control of BUILD parameters in language ??? '
say 'Call invocations are language specific. See BUILD Service
'
parse arg PARAM
say 'Parameter:
' PARAM
parse arg L1PAR ':' L1SCV ',' L1PRJ ',' L1ALTP ',',
L1UID ',' L1GRP ',' L1TYP ',' L1MBR ',' L1SCOPE ',',
L1MODE ',' L1LIST ',' L1REP ',' L1THLQ ',',
L1DMSGS ',' L1DREPT ',' L1DLIST ',' L1DEXIT.
say 'Parameters: ' L1PAR
say 'Service:
' L1SCV
say 'SCLM Project: ' L1PRJ
say 'SCLM ALT-PRJ: ' L1ALTP
say 'User-ID:
' L1UID
say 'Group:
' L1GRP
say 'Type:
' L1TYP
say 'Member:
' L1MBR
say 'Scope:
' L1SCOPE
say 'Mode:
' L1MODE
say 'Listoutput: ' L1LIST
say 'Report:
' L1REP
say 'Workfile:
' L1THLQ
say 'Messages at: ' L1DMSGS
say 'Reports to : ' L1DREP
say 'Lists to :
' L1DLIST
say 'Exit Routine: ' L1DEXIT
/******************************************************************/
/* Return to calling routine
*/
/******************************************************************/
exit 0
/******************************************************************/
/* Error Routine
*/
/******************************************************************/
ERROR:
say 'BUILDX1C-ERROR: Statement' sigl 'endet with RC = ' RC
return

Figure 130. REXX BUILDX1C to Demonstrate a REXX Build Procedure

Chapter 13. What is Configuration Management?

209

210

ISPF/SCLM V4 Guide

Chapter 14. Change and Problem Management


It is good practice in application development to base changes on a change
application form, which may be part of the archdefs.
Change Control - Agreement
A CCV# must be present.
Control of CCV# through CCV routine.
A CCV bridge to INFO/Management is possible (see ISPF/SCLM Project
Manager's Guide, Appendix B).

14.1.1 Implementation of CCV Example


We already have introduced a CCV sample in 13.9.1, Access Control and
Delimitation on page 206. This program can be considerably enhanced, for
example by reading an ISPF table, which is part of a small separate application
entering user IDs and their permitted change codes.
SCLM calls the change code verification routine when the SCLM editor, the
migration, import and export utilities, and the migrate, import, export, save and
store services are invoked.

Copyright IBM Corp. 1994

211

212

ISPF/SCLM V4 Guide

Chapter 15. Delivery


Delivery of software may consist of full version, delta version, and respectively
hot fix version. This may be solved by a promote exit.

PRODUCTION

or archive

DELIVERY (NON KEY)


Separate
Account
Full version

Data Set

PROD (shadow)
1.
1.
PROD (shadow)

Delta version

2.

FIX 2.

TEST
copy H prom.ex
prx I copy
APLY

INTE

QA

developer
developer

Figure 131. SW Delivery - Project View

Group DELIVERY is served by promote exits or special project views (which


facilitate repeated promote)
Software delivery from group DELIVERY can be done through:
DFSMShsm (ABARS), since a cluster of data sets have to be delivered
synchroneously. Refer to 11.1.4, ABARS Implementation on page 183
for more details.
Netview/DM.
SCLM EXPORT / SCLM IMPORT.
Delete PDSs and create PDS again, as well as REPRO initial value to
account file to make entry state of DELIVERY group.
11.1.7.1, Backup when Promoting to Production on page 184 may be
considered a suitable, enhancable example.
Insert group DELIVERY
Insert group DELIVERY (DELV) with an own account file in appropriate
views.
Insert above stated example MET#P11 (see 11.1.7.6, Promote-Verify-Exit
MET#P11 on page 187) as another REXX program to promote to group
delivery in appropriate views.
Apply the DELGROUP service (see ISPF/SCLM Reference) to cleanup the
DELIVERY group first.

Copyright IBM Corp. 1994

213

214

ISPF/SCLM V4 Guide

Chapter 16. Communication


Naturally, it is important that a fix developer informs other fellow developers of
fix changes made, and it would be nice to set up an automatic notification. SCLM
does not have a facility to do this at this moment.
The following REXX program may serve your imagination as an example of what
could be done.

16.1 Notification at Promote with TSO Send


FLMCNTRL ACCT=SCLM41.PROJDEFS.ACCTFILE,
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP,
VERCC=MET#CCV1,
VERCCDS=SCLM41.PROJDEFS.REXX,
VERCCOP='ANYPARM/',
VERCCCM=TSOLNK,
PRMEXT3=MET#SND1,
PEXT3DS=SCLM41.PROJDEFS.REXX,
PEXT3OP='/',
PEXT3CM=TSOLNK,
MAXVIO=10000,
OPTOVER=Y

X
X
X
X
X
X
X
X
X
X
X

/***********************REXX****************************************/
/* PROMOTE-PURGE-EXIT
*/
/* Send Notification to QA after completion of promote
*/
/* A QUICK AND DIRTY SAMPLE
*/
/*******************************************************************/
trace 'o'
Parse upper arg OPTIONS '/'
FNAME ',' ,
PROJECT ','
VIEW
','
USERID ','
FRGROUP ','
TYPE
','
PART
','
SCOPE
','
MODE
','
TOGROUP ','
JUNK
.
OPTIONS
FNAME
PROJECT
VIEW
USERID
FRGROUP
TYPE
PART
SCOPE
MODE
TOGROUP
SAY
SAY
SAY
SAY
SAY

=
=
=
=
=
=
=
=
=
=
=

,
,
,
,
,
,
,
,
,
,

/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

Optional Parameters list */


FNAME Name
*/
PROJECT
*/
Alternate View
*/
user ID
*/
Group promoted from
*/
Type
*/
Member Name
*/
Scope
*/
Modus
*/
Group promoted to
*/
Throw away
*/

strip(OPTIONS)
strip(FNAME)
strip(PROJECT)
strip(VIEW)
strip(USERID)
strip(FRGROUP)
strip(TYPE)
strip(PART)
strip(SCOPE)
strip(MODE)
strip(TOGROUP)

' '
'***********************'
'PART(S) 'PART' PROMOTED FROM 'FRGROUP' TO 'TOGROUP
'***********************'
' '

"SEND 'SW-Manager notified ===> ' USER(sw manager) LOGON"

Implement Notification
1. Code above REXX example and insert in prjid.PROJDEFS.REXX.
2. prjid.PROJDEFS.REXX must be SYSPROC concatenated.
3. Test your coding by promoting a part.

Copyright IBM Corp. 1994

215

16.2 SCLM Batch


Phone Home Another useful notification can be done by modifying the skeleton
for BUILD (ispf...SISPSENU(FLMB$)) and PROMOTE (ispf...SISPSENU(FLMP$))
batch jobs so that the TEMPNAME exec contains lines like this after the FLMCMD
invocation:
SET ZISPFRC = &&LASTCC
ISPEXEC VPUT (ZISPFRC) SHARED
IF &&ZISPFRC = 0 THEN +
SEND 'BUILD of &SEGMENT &SECTION was successful.' +
USER(&ZUSER.)
ELSE +
SEND 'BUILD of &SEGMENT &SECTION was unsuccessful.' +
USER(&ZUSER.)

That way our SCLM batch jobs tell us if they worked or not -- we don't have to
read the job output unless there was a problem.

16.3 Check Predecessor Account Data with MET#PRE


This routine examines predecessor problems, if a part would be promoted from
group to togroup.
Note: The DBACCT service cannot be invoked via the SCLM command interface
(this example was included in an ADPS invocation) and must be written
separately.
/*REXX*********************************************************/
/* MET#PRE - Predecessor Check
*/
/*
*/
/**************************************************************/
/* This routine examines predecessor problems, if a SCLM
*/
/* member would be promoted from 'group' to 'togroup'.
*/
/*
*/
/* Member must exist in 'group' as well as in 'togroup'
*/
/*
*/
/* This REXX is based on ADPS implementation and it's
*/
/* interface DDKSCLM, since SCLM service DBACCT can not be
*/
/* invoked with SCLM 3.3 via FLMCMD
*/
/*
*/
/* Return codes:
*/
/* 0
normal completion
*/
/* 4
Predecessor problem existent
*/
/* 8
any error
*/
/* 11
invalid return code from any ISPF service
*/
/**************************************************************/
Trace o
/* get TYPC NAME DDNAME DSN NAMC ADDR ADR-space USERPARM
*/
Parse Source . $t $n $dd $dsn $i $d $a $up
/* get Project Prj-Definition Group Type Member Togroup
Parse Arg project prjdef group type member togroup .

*/

/***************************************************************
* Initialization
***************************************************************/
Call ISPF '0 CONTROL ERRORS RETURN'
msg. = ''
msg.0 = 0
/***************************************************************
* Examine
***************************************************************/
If togroup = '' Then Do
Say 'false amount of parameters'
Say ' '
Say 'Parameter must be:
'
Say ' Project Prj-Definition Group Type Member Togroup '
Call Exit 0
End
If togroup = group Then Do
Say 'Startgroup and targetgroup are identical '
Call Exit 8

216

ISPF/SCLM V4 Guide

End
/***************************************************************
* DO
***************************************************************/
/* Projectdefinition for ADPS interface in profile pool
ddk0wsap = prjdef
Call ISPF '0 VPUT (DDK0WSAP) PROFILE'
/* get accounting Information from actual group
sclmrc=DDKSCLM('DBACCT',project,group,type,member, ,
'FGR','ACCT','LIST','MSG')
If sclmrc = 0 Then
Call SCLMMSG

*/
*/

If fgr = togroup Then Do


Say member 'exists only in ' togroup
Say 'No Part Predecessor Problem Available'
Call Exit 0
End
predecf = Substr(acct, 125, 12)

/* Predecessor-Date Startgroup*/

/* get accounting information from toGROUP


rtc = DDKSCLM('DBACCT',project,togroup,type,member, ,
'FGRT','ACCTT','LISTT','MSG')
If rtc > 4 Then
Call SCLMMSG

*/

If rtc = 4 Then Do
Say member 'was not found in' togroup 'or higher'
Call Exit 8
End
changet = Substr(acctt, 28, 12)

/* Change-Date */

If changet >> predecf Then Do


Say 'Predecessor Lock exists:'
Say 'Change date in
' Left(togroup,8) ':' changet
Say 'Predecessordate in ' Left(fgr,8) ':' predecf
Call Exit 4
End
Say 'There is not predecessor lock'
Call Exit 0
/*==============================================================
* SCLMMSG Subroutine to set error messages due to SCLM rc
* Parm
none
*=============================================================*/
SCLMMSG:
If msg.0 > 0 Then Do
Do i = 1 To msg.0
Say msg.i
End
End
Else
Say 'unexpected error with DBACCT service'
Call EXIT 0
Return
/*==============================================================
* ISPF - Subroutine to invoke ISPEXEC
* Parm maxrc|* 'ISPEXEC command'
*=============================================================*/
ISPF:
Arg ispfmax ispfcmd
Drop ZERRMSG
Address ISPEXEC ispfcmd
ispfrc = rc
If ispfmax='*' Then
If ispfrc<0 | ispfrc>ispfmax Then Do
If "SYMBOL"('ZERRMSG')='VAR' Then
Say zerrmsg
Else
Say 'unexpected error with ISPF service' ispfcmd 'Rc:' ispfrc
Call EXIT 11
End
rc = ispfrc
Return rc
/*==============================================================
* TSO - Subroutine to invoke a TSO Command
* Parm maxrc|* 'TSO command'
*
Output: rc

Chapter 16. Communication

217

*=============================================================*/
TSO:
Arg tsomax tsocmd
msgmode = MSG('OFF')
Address TSO tsocmd
tsorc = rc
msgmode = MSG('ON')
If tsomax = '*' Then
If tsorc<0 | tsorc > tsomax Then Do
Say 'Error at TSO Command' tsocmd 'Rc='tsorc
Call EXIT '11'
End
rc = tsorc
Return rc
/*==============================================================
* EXIT - exit here with retcode and optional error message
* Parm: rc <msgid>
*=============================================================*/
EXIT:
Parse Arg exitrc .
Exit exitrc

218

ISPF/SCLM V4 Guide

Chapter 17. Verification Management


Verification may be done by:
Human beings (organized in a roleplay of SW developer, SW manager, etc.)
Architecture definitions to plan, identify, and control parts of an application
consistently
SCLM's include reference ability

17.1 Verified by Roles


Verification is implemented implicitly using different roles (see Chapter 9, Role
Management on page 173).

17.1.1.1 Promote Report


A PROMOTE in REPORT mode is always needed and should be produced prior
to the real PROMOTE, also to support role play.

17.2 Verified by Architecture Definition


Architecture definition parts represent a blueprint of an application, and, when
kept seperately (see 12.1.3, Keep Architecture Definitions Separate on
page 198), contribute considerably to the verification process.

17.3 Verified by Include Tracking


The SCLM parsers identify language dependable include references. These
include references do not have to be coded in architecture defininitions. The
SCLM project manager, however, has to define which libraries are to be
considered SCLM controlled include libraries (through usage of FLMSYSLB and
FLMCPYLB), and those not controlled by SCLM.
The SCLM build processor attempts to resolve all include references to source
members before it invokes any translator. However, for some translators, the
include for a source member cannot be resolved until after the translator
invocation. Such includes are referred to as dynamic includes (a typical example
is a DSECT or CSECT that has to be generated as a copybook prior to being
included as copy part of a source program). Refer to ISPF/SCLM Project
Manager's Guide, section Dynamic Include Tracking for more details.

17.4 Non-SCLM-Verified Include Objects


Many installations need to include object modules for applications they have
bought, for example. Refer to 19.1.6, Link-edit with Parts from Non-SCLM Data
Set on page 244 for a detailed description.

Copyright IBM Corp. 1994

219

220

ISPF/SCLM V4 Guide

Chapter 18. Meta Project


SCLM manages it's project initiating and project controlling parts in
prjid.PROJDEFS.* data sets. What would be more convenient than to control
these parts through the use of SCLM? And versioning of source parts could be
conveniently and additionally used.
Meta Project - Agreement
prjid.PROJDEFS.* data sets = meta data sets
Meta data sets parts = meta parts
Your SCLM meta project view name = ________ (for example, #SCLM)

18.1 Simple Meta-project Implementation


**********************************************************************
TITLE '*** PROJECT DEFINITION for Meta Project *** '
SCLM41 FLMABEG
PRJAC
FLMAGRP AC=(SCLM)
ARCHDEF FLMTYPE
ASM
FLMTYPE
DOCS
FLMTYPE
JCL
FLMTYPE
LIST
FLMTYPE
LMAP
FLMTYPE
LOAD
FLMTYPE
OBJ
FLMTYPE
PROJECTS FLMTYPE EXTEND=METHODS
METHODS FLMTYPE
REXX
FLMTYPE
SCRIPT FLMTYPE
PROJDEFS FLMGROUP KEY=Y,AC=(PRJAC)
PRIVDEFS FLMGROUP KEY=Y,PROMOTE=PROJDEFS,ALTC=PRIVDB,AC=(PRJAC)
FLMCNTRL ACCT=SCLM41.PROJDEFS.ACCTFILE,
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP,
VERS=SCLM41.PROJDEFS.VERSFILE,
VERPDS=@@FLMPRJ.PROJDEFS.@@FLMTYP.VERSION,
VERCC=MET#CCV1,
VERCCDS=SCLM41.PROJDEFS.REXX,
VERCCOP='ANYPARM/',
VERCCCM=TSOLNK,
PRMEXT3=MET#SND1,
PEXT3DS=SCLM41.PROJDEFS.REXX,
PEXT3OP='/',
PEXT3CM=TSOLNK,
MAXVIO=10000,
OPTOVER=Y
PRIVDB FLMALTC ACCT=HASINGH.PRIVDEFS.ACCTFILE,
DSNAME=HASINGH.@@FLMGRP.@@FLMTYP
FLMATVER GROUP=PROJDEFS,TYPE=ARCHDEF,VERSION=YES
FLMATVER GROUP=PROJDEFS,TYPE=PROJECTS,VERSION=YES
FLMATVER GROUP=PROJDEFS,TYPE=METHODS,VERSION=YES
FLMATVER GROUP=PROJDEFS,TYPE=SCRIPT,VERSION=YES
FLMATVER GROUP=PROJDEFS,TYPE=REXX,VERSION=YES
FLMATVER GROUP=PROJDEFS,TYPE=JCL,VERSION=YES
COPY FLM@ARCD
-- ARCHITECTURE DEF. LANGUAGE -COPY FLM@BOOK
-- Bookmaster
LANGUAGE -COPY FLM@REXX
-- REXX
LANGUAGE -COPY FLM@TEXT
-- TEXT
LANGUAGE -COPY @ASMHRC4
-- ASMHRC4 Compiler with RC=4=ok
COPY FLM@ASMH
-- ASMH
Compiler with RC=0=ok
FLMAEND

X
X
X
X
X
X
X
X
X
X
X
X
X
X

Figure 132. Hierarchy SCLM Meta Project

Copyright IBM Corp. 1994

221

By now we have created and changed a lot of project parts in this workshop and
you will agree that these parts should be controlled and versioned by SCLM.
This will be our next task.
Implement Meta Project
1. Create a meta project definition (as exemplified before).
2. Compile and link-edit that view. After successful completion, you will be
able to control (migrate / edit / build / promote) all your projects under
this meta project.
Project ..... prjid
Alternate ... #sclm
Group ....... userid

(the whole enterprise )


(the meta project view )
(the admin group
)

3. Migrate all PROJDEFS parts:


Project definitions with A C = , with the ASMH method you have
specified with GOODRC=4
Other project definitions (and parts thereof) with ASMH
Archdefs with method ARCHDEF
JCL with TEXT
REXX with REXX
And so on
4. Create an architecture definition for meta project, ie:
* MET##H:
*
&----> H
*
&-----> #
* &--------> MET
*
* PROJECT ===>
* ALTVIEW ===>
*
INCL
MET##L
INCL
MET##L1
*
PROM
MET#01PA
PROM
MET#02PV
PROM
MET#03PD
PROM
MET#04CL
*
PROM
MET#CCV1
PROM
MET#P11
PROM
MET#SND1
PROM
MET#SAVE
PROM
MET#XREF

= HIGH-LEVEL PLAN
= ADMINISTRATOR'S WINDOW
= SCLM CONTROL PROJECT
SCLM41
#SCLM
ARCHDEF
ARCHDEF

* COMPILE/LINK METAPROJECT
* COMPILE/LINK SCLMISP

JCL
JCL
JCL
JCL

N
N
N
N

*
*
*
*

ALLOC ACCTFILE AND PDS


ALLOC VERSFILE AND PDS
ALLOC PROJECT DATA SETS
COMPILE/LINK METAPROJECT (INITIAL CL)

REXX
REXX
REXX
REXX
REXX

N
N
N
N
N

*
*
*
*
*

CHANGE-CODE-VERIFICATION-EXIT (REXX)
PROM-VER-EXT ==> ONEBACK / TWOBACK
NOTIFICATION EXAMPLE
SAVE SERVICE INVOCATION
AS IS - MAKES XREF FROM METAPROJECT

5. BUILD using above archdef


6. PROMOTE using above archdef
Note: This simple implementation is not a true 2-level implementation and
always requires PROMOTE before a prjview can be worked with.

18.2 Create Complex Documentation with REXX MET#XREF


The PDF option 3.1 is used to print appropriate PROJDEFS data set for analysis
with MET#XREF. By enclosing the aquired index headings to the project
documentation, it furnishes a cross reference of parts contained in in the index
list.
1. Print applicable data sets with PDF option 3.1.
2. Exit PDF (with below panel).

222

ISPF/SCLM V4 Guide

Specify Disposition of List Data Set


Command ===>
Log Data Set options not available
List Data Set Disposition
Process option . . . 4

1. Print data set and delete


2. Delete data set without printing
3. Keep data set - Same
(allocate same data set in next session)
4. Keep data set - New
(allocate new data set in next session)

3. Rename uid.SPFn.LIST to uid.XREF.LIST.


4. %MET#XREF (invoke procedure (must be in SYSPROC concatenation)).
5. The output will look something like this:
.* **************ended: 01/08/94 11:43:46
.*:h2 id=hsi9090.Analysis 'HASINGH.XREF.LIST' - per 08/01/94
.*:p.
.* ***********Group PROJDEFS 2 ****************
:ih1.Group
:ih2.PROJDEFS
:ih1.PROJDEFS, Group
.* ************Type PROJECTS 3 ***************
:ih1.Types
:ih2.PROJECTS
:ih1.PROJECTS, Type
:ih1.$TYPES.PROJECTS
:ih1.PROJECTS, Type
:ih2.$TYPES
:ih1.FLM##PD.PROJECTS
:ih1.PROJECTS, Type
:ih2.FLM##PD
:ih1.FLM1#PD.PROJECTS
:ih1.PROJECTS, Type
:ih2.FLM1#PD
:ih1.FLM3#PD.PROJECTS
:ih1.PROJECTS, Type
:ih2.FLM3#PD
:ih1.FLM8#PD.PROJECTS
:ih1.PROJECTS, Type
:ih2.FLM8#PD
. .....
.*:h2.Contents Callout
.* 565 BookMaster Inputlines generated.
.*:toc.
.*:Index id=Xnn.The Structure of the Project SCLM41

6. And when added to the project documentation, the index will contain a cross
reference of parts, for example:
F
FLM##PD.PROJECTS
MET#ALT1.PROJECTS
MET#ALT2.PROJECTS
MET#ALT3.PROJECTS
MET#ALT4.PROJECTS
MET#CNT1.PROJECTS
MET#GRP1.PROJECTS
MET#LDTS.PROJECTS
MET#TYPS.PROJECTS

M
MET#ALT1.PROJECTS
contained in FLM##PD.PROJECTS
contained in FLM1#PD.PROJECTS
contained in FLM2#PD.PROJECTS
contained in FLM3#PD.PROJECTS
contained in FLM8#PD.PROJECTS

18.2.1 REXX MET#XREF to Create Bookmaster Index Tags


/***********************REXX****************************************/
/*
*/
/* Input: ISPF 3.1 "Print entire data set" / "print index listing" */
/*
- SCLM41.PROJDEFS.ARCHDEF
"L"
*/
/*
- SCLM41.PROJDEFS.SOURCE
"L"
*/
/*
- SCLM41.PROJDEFS.REXX
"X"
*/
/*
- SCLM41.PROJDEFS.JCL
"X"
*/
/*
- SCLM41.PROJDEFS.LOAD
"X"
*/
/* Output: :ihx. statements for Bookmaster file BMOUT
*/

Chapter 18. Meta Project

223

/*
:index. statements per "Project"
*/
/*
*/
/* Return Codes: 0 - Done
*/
/*
4 */
/*
8 - Error allocprefix file XREF
*/
/*
12 - Input error, bad "type" found
*/
/*
16 */
/*
*/
/*trace ?I
*/
/*******************************************************************/
Signal on Syntax
Signal on Halt
Signal on Novalue
Trace off
input_name = "'HASINGH.XREF.LIST'" /* Unloaded 3.1 List
*/
output_name = "'SCLM41.PROJDEFS.SCRIPT(MET#XDOK)'" /* Output to Meta */
bm.
= ''
/* Reset bookmaster vars.
*/
number.
= 0
/* All counts to zero
*/
cproj
= ''
/* No project yet
*/
cgrp
= ''
/* No group yet
*/
csrc
= ''
/* Reset SOURCE name
*/
ctype
= ''
/* No type yet
*/
cmbr
= ''
/* No member yet
*/
xdate
= ''
/* Date of xref list
*/
xtime
= ''
/* Time of xref list
*/
Call bm_hdr
/* Bookmaster header lines */
Address TSO "ALLOC F(XREF) DA("input_name") SHR REUSE"
If RC > 0 Then
/* Error in allocating
*/
Call ExitRtn 8 'Error allocating XREF.LIST, RC='RC
'EXECIO * DISKR XREF (STEM iline. FINIS)' /* Read XREF file
*/
Say iline.0 'records from XREF'
Do I = 1 to iline.0
/* all lines
*/
iline.i = Substr(iline.i,2)
/* Remove control char
*/
end
/************************Input loop***************************** */
cr = 1
/* Start: first line input */
Do I = 1 by 1 while(cr < iline.0) /* until all lines done
*/
Call Find_new_type
/* Check for "TYPE:"
*/
Select
/* "Type" to be processed
*/
When ctype = 'ARCHDEF' Then
/* ARCHDEF entry
*/
Call process_ARCH
When ctype = 'SOURCE' Then
/* SOURCE entry
*/
Call process_SOURCE
When ctype = 'REXX'
Then
/* REXX
entry
*/
Call process_REXX
When ctype = 'JCL'
Then
/* JCL
entry
*/
Call process_JCL
When ctype = 'LOAD'
Then
/* LOAD
entry
*/
Call process_LOAD
Otherwise nop
/* Call ExitRtn 12 "Unexpected Type found:" ctype */
End
/* Select Type
*/
End
/* Read lines
*/
/*******final processing******************************************/
Call bme_trailer
/* BookMaster trailer lines */
Say number.bkm 'BookMaster lines generated'
Address TSO "ALLOC F(BMOUT) DA("output_name") OLD REUSE"
"EXECIO * DISKW BMOUT (STEM BM. FINIS)" /* write records
*/
Address TSO "FREE F(BMOUT)"
Return 0
/* End of Main program
*/
/*******process ARCHDEF*******************************************/
process_ARCHDEF:
Call member_lines
/* process member list
*/
Do cr = cr to iline.0 until(w1 = 'PROJECT:')
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
End
Do cr = cr to iline.0 until(w3 = 'DATE:') /* next dataset
*/
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
If w2 = 'LOAD' Then Do
/* architecture line LOAD
*/
Call bme ':ih1.'cproj', Projekt' /* xxxxx, Projekt entry
*/
Call bme ':ih2.'w3'.LOAD'
/* mmmm.LOAD
entry
*/
Call bme ':ih1.'w3'.'w4
/* LOAD.mmmmm
entry
*/
cload = w3'.LOAD'
/* save current LOAD name
*/
End
If w1 = 'PROJECT:' Then Do
/* header line "project"
*/
cload = ''
/* reset LOAD name
*/
carch = w4'.ARCHDEF'
/* set ARCHDEF member name */
cmbr = w4
/* save member name
*/
End
If Substr(w2,1,4) = 'INCL' & Length(cmbr) > 1 ,
Then Do
/* architecture lines INCLx */
Call bme ':ih1.'w3'.'w4
/* mmmmm.ttttt
entry */
Call bme ':ih2.contained in 'carch /* "in" mmmmm.ARCHDEF entry */

224

ISPF/SCLM V4 Guide

If cload <> '' Then Do


Call bme ':ih2.contained in 'cload /* in mmmmm.LOAD entry */
Call bme ':ih1.'cload
/* mmmmm.LOAD
entry */
Call bme ':ih2.'w3'.'w4
/* mmmmm.tttt
entry */
End
/*
*/
Call bme ':ih1.'carch
/* mmmmm.ARCHDEF entry */
Call bme ':ih2.'w3'.'w4
/* mmmmm.tttt
entry */
Call bme ':ih1.'w4', Type'
/* ttttt.TYPE
entry */
Call bme ':ih2.'w3
/* mmmmm
entry */
End
If w2 = 'PROM' & w4 = 'JCL' Then Do
/* architecture line PROM */
Call bme ':ih1.'w3'.'w4
Call bme ':ih2.contained in 'carch
Call bme ':ih1.'carch
Call bme ':ih2.'w3'.'w4
Call bme ':ih1.'w4', Type'
Call bme ':ih2.'w3
End
End
ctype = ''
/* ARCHDEF has been done */
Return
/* ******Types REXX, JCL, LOAD & SOURCE****************************** */
process_REXX:
call member_lines
/* process member list
*/
ctype = ''
/* REXX has been done
*/
Return
process_COPY:
call member_lines
/* process member list
*/
call detail_lines
/* process COPY lines
*/
ctype = ''
/* COPY has been done
*/
Return
process_JCL:
call member_lines
/* process member list
*/
ctype = ''
/* JCL has been done
*/
Return
process_LOAD:
call member_lines
/* process member list
*/
ctype = ''
/* LOAD has been done
*/
Return
process_SOURCE:
call member_lines
/* process member list
*/
call detail_lines
/* process SOURCE lines
*/
ctype = ''
/* SOURCE has been done
*/
Return
/* ******copy and source lines ************************************* */
detail_lines:
/* COPY and SOURCE lines */
Do cr = cr to iline.0 until(w1 = 'PROJECT:')
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
End
Do cr = cr to iline.0 until(w3 = 'DATE:') /* next dataset
*/
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
If w1 = 'PROJECT:' Then Do
/* header line "project"
*/
csrc = w4'.'ctype
/* set src member name
*/
cmbr = w4
/* save member name
*/
Call bme '.* PROJECT: 'w4'.'ctype
cr '*************'
End
If w1 <> 'TYPE:' & w2 = 'COPY' & ,
w3 <> 'FLMTYPE' & Length(cmbr) > 1 ,
Then Do
/* source line COPY
*/
Call bme ':ih1.'w3'.'ctype
/* mmmmm.ttttt
entry
*/
Call bme ':ih2.contained in 'csrc /* "in" mmmmm.src entry */
Call bme ':ih1.'csrc
/* mmmmm.ARCHDEF
entry */
Call bme ':ih2.'w3'.'ctype
/* mmmmm.tttt
entry */
End
End
ctype = ''
/* copy or SOURCE done
*/
Return
/* ******Member List************************************************ */
member_lines:
/* process member list
*/
Call Skip_header_lines
/* Skip header lines
*/
done = 0
/* End-of-loop indicator
*/
Do cr = cr to iline.0 until(done = 1) /* every directory line
*/
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
Say '****mbr line:' w1 w2 w3 w4 w5 '***' cr
If w1 = 'MAXIMUMS:' | ,
/* end of directory
*/
w1 = 'TOTALS:' | ,
(w1 = 'END' & w2 = 'OF' & w3 = 'MEMBER') Then
Do
done = 1
/* End of member list
*/
End
Else Do
If w1 = 'PROJECT:' Then
/* headers within mbr list
*/

Chapter 18. Meta Project

225

Call Skip_header_lines
/* Skip header lines
Else
If Length(w1) > 1 Then Do
/* ignore one char names
Call bme ':ih1.'w1'.'ctype
/* member.type
entry
Call bme ':ih1.'ctype', Type' /* type header
Call bme ':ih2.'w1
/* member within type
End
End
End
Return
/* **************** Skip list headers ******************************
Skip_header_lines:
/* Skip any header line
done = 0
/* Loop control
Do cr = cr to iline.0 until(done=1) /* to last line of header
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
Say '*** Skip_h_l:' w1 w2 w3 w4 w5 w6 w7 w8 '***'
If w2 = '(HEX)' | w1 = 'COL' | ,
w3 = '(HEX)' Then Do
/* End of header lines
cr = cr +1
/* Skip current record
done = 1
/* end header, stop loop
End
End
Return
/* **************** find new type **********************************
Find_new_type:
/* Find new type
done = 0
/* loop control
Do cr = cr to iline.0 until(done=1) /*
Parse Upper Value iline.cr WITH w1 w2 w3 w4 w5 w6 w7 w8
If w1 = 'PROJECT:' & w3 = 'DATE:' Then Do
xdate = Strip(w4)
/* Save Xref date
If cproj <> '' & cproj <> Strip(w2) Then
Call bme "'.*..Index id=X##.The Structure of the Project '",
cproj "-" xdate xtime
/* Index Call "old" proj
cproj = Strip(w2)
/* Save project name
If w2 <> cproj Then Do
/* new "Project"
Call bme ':ih1.Projects'
/* Projects
entry
Call bme ':ih2.'cproj
/* pppppp
entry
Call bme ':ih1.'cproj', Project' /* pppppp, Project entry
End
End
If w1 = 'GROUP:' & w3 ='TIME:' & w2 <> cgrp Then Do
cgrp = Strip(w2)
/* Save group name
xtime = Strip(w4)
/* Save xref time
Call bme '.* ***********Group 'cgrp cr '****************'
Call bme ':ih1.Group'
/* Group entry
Call bme ':ih2.'cgrp
/* gggggg
entry
Call bme ':ih1.'cgrp', Group' /* gggggg, Group
entry
End
If w1 = 'TYPE:' & w3 = 'PAGE:' Then Do /* "Type" header line
ctype = Strip(w2)
/* Save "type" name
Call bme '.* ************Type 'ctype cr' ***************'
Call bme ':ih1.Types'
/* Types entry
Call bme ':ih2.'ctype
/* tttttt
entry
Call bme ':ih1.'ctype', Type' /* tttttt, Type
entry
cr = cr + 1
/* Skip current record
done = 1
/* type found, stop loop
End
End
Return
/* **************** first output lines *****************************
bm_hdr:
/* Bookmaster header lines
Call bme '.* **************ended:' Date('E') Time('N')
Call bme '.*:h2.Analysis 'input_name ' - per',
xdate xtime
/* date & time footprint
Call bme '.* :p.'
Return
/* **************** final output************************************
bme_trailer:
/* final output lines
Call bme '.* :h2.Contents Callout' /* contents callout
Call bme '.*' number.bkm + 2 'BookMaster Inputlines generated.'
Call bme '.* :toc.'
/* contents callout
Call bme '.*..Index id=Xnn.The Structure of the Project 'cproj
Return
/* End of subroutine
/* **************** create output record ***************************
bme: Procedure expose bm. number.
/* create Bookmaster entry
i = number.bkm
/* number of lines generated
i = i + 1
/* increase by 1
bm.i = arg(1)
/* save argument
number.bkm = i
/* save number of lines
Return i
/* number of records queued
/* **************** error exit routine *****************************
ExitRtn:
/* Exit from a Pgm with a msg
Parse arg rc msg
/* Get return code and message

226

ISPF/SCLM V4 Guide

*/
*/
*/
*/
*/

*/
*/
*/
*/

*/
*/
*/

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

If msg <> '' Then say msg


Exit '0'rc
Return

/* Display any message


/* End of program

*/
*/

18.3 Complex Meta-project Implementation


An even better support for a meta project could be obtained by a true SCLM
project with 3 levels to reflect a meta development, test and production
environment.
Note: The provided solution is based on naming conventions that do not apply
elsewhere, and must consequently be customized.
S C L M
H
M
E

T

A
SCLM
prod

Manager

H PROMOTE
R
O SCLM

Exit
J
ADMIN
test
E


C

T

H PROMOTE

Exit

admin1 admin2 admin3

SCLM

PROD
ie. S9200
System
H

SCLM
HTEST ie. S9200T
System

Figure 133. 3 Level Meta Project

1. A separate meta project is set up:

metaprj
*
PRJAC
*
ARCHDEF
PROJECTS
METHODS
* ...
PRODDEFS
TESTDEFS
PRIVDEFS
*

TITLE '*** PROJECT DEFINITION for Meta Project *** '


FLMABEG
FLMAGRP AC=(SCLM)
FLMTYPE
FLMTYPE EXTEND=METHODS
FLMTYPE
etc.
FLMGROUP KEY=Y,AC=(PRJAC)
FLMGROUP KEY=Y,PROMOTE=PRODDEFS,AC=(PRJAC)
FLMGROUP KEY=Y,PROMOTE=TESTDEFS,ALTC=PRIVDB,AC=(PRJAC)
FLMCNTRL ACCT=SCLM41.PRODDEFS.ACCTFILE,
DSNAME=@@FLMPRJ.@@FLMGRP.@@FLMTYP,
MAXVIO=10000,
OPTOVER=Y

X
X
X

*
PRIVDB FLMALTC ACCT=HASINGH.PRIVDEFS.ACCTFILE,
X
DSNAME=HASINGH.@@FLMGRP.@@FLMTYP
*
COPY FLM@ARCD
-- ARCHITECTURE DEF. LANGUAGE -COPY @ASMPRJ
-- ASMH PROJECT
COPY @ASMPRJT
-- ASMH TEST PROJECT
COPY @LKEDPRJ
-- 370 LINKAGE EDITOR FOR PROJECT DEF
* ...
etc.
FLMAEND

Figure 134. Hierarchy Complex SCLM Meta Project

2. A language definition ASMPROJ builds a project view, and also:


a. Packs (MET#B01) compile list output.

Chapter 18. Meta Project

227

b. Generates (MET#B02) a project view for a test environment for


association with language definition ASMPROJT.
3. A promote translator ( MET#P21) is invoked to copy the prjview to TEST or
PROD environment respectively.

18.3.1 Language Definition ASMPROJ (Member @ASMPRJ)


***====================================================================
*** SCLM LANGUAGE DEFINITION "ASMPROJ"
***
PARSE: SCLM ASM PARSER
***
BUILD: ASSEMBLER H COMPILE FOR PROJDEFS (MVS)
***
+ GENERATE TESTPROJECT PROJDEFS (MVS)
***====================================================================
*
ASMPROJ FLMSYSLB EPO.ISPF410.SISPMACS
FLMSYSLB SYS1.MACLIB
*
FLMLANGL
LANG=ASMPROJ,VERSION=V1.0
***********************************************************************
* PARSER TRANSLATOR:
***********************************************************************
*
FLMTRNSL CALLNAM='SCLM ASM PARSE',
C
FUNCTN=PARSE,
C
COMPILE=FLMLPGEN,
C
PORDER=1,
C
OPTIONS=(SOURCEDD=SOURCE,
C
PARSEMEM=@@FLMMBR,
C
STATINFO=@@FLMSTP,
C
LISTINFO=@@FLMLIS,
C
LISTSIZE=@@FLMSIZ,
C
LANG=A)
*
(* SOURCE
*)
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMDSN(@@FLMMBR)
*
***********************************************************************
* BUILD TRANSLATOR(S):
***********************************************************************
*
FLMTRNSL
CALLNAM='ASM-MVS',
C
FUNCTN=BUILD,
C
COMPILE=IEV90,
C
VERSION=V1.0,
C
GOODRC=4,
C
PORDER=1,
C
OPTIONS=(NODECK,OBJECT,XREF(FULL))
*......................................................................
*
DDNAME ALLOCATION:
*FLMALLOC
IOTYPE=O,DDNAME=SYSGO,KEYREF=OBJ,RECNUM=10000
FLMALLOC IOTYPE=O,DDNAME=SYSLIN,KEYREF=OBJ,RECNUM=9000,DFLTTYP=OBJ
FLMALLOC
IOTYPE=I,DDNAME=SYSLIB,KEYREF=SINC
FLMCPYLB
EPO.ISPF410.SISPMACS
FLMCPYLB
SYS1.MACLIB
FLMALLOC
IOTYPE=S,DDNAME=SYSIN,KEYREF=SINC,RECNUM=9000
FLMALLOC
IOTYPE=W,DDNAME=SYSUT1,RECNUM=25000
FLMALLOC
IOTYPE=A,DDNAME=SYSTERM
FLMCPYLB
NULLFILE
FLMALLOC
IOTYPE=A,DDNAME=SYSPUNCH
FLMCPYLB
NULLFILE
FLMALLOC
IOTYPE=W,DDNAME=SYSPRINT,RECNUM=50000,
C
RECFM=FBA,LRECL=133,PRINT=Y
*
***********************************************************************
*
PACK COMPILELIST FOR MVS
***********************************************************************
FLMTRNSL
CALLNAM='PACK-LIST',
C
FUNCTN=BUILD,
C
COMPILE=SCLMISP,
C
DSNAME=SCLM41.PROJDEFS.LOAD,
C
CALLMETH=LINK,
C
VERSION=V1.0,
C
GOODRC=0,
C
PORDER=1,
C
OPTIONS='%MET#B01 SYSPRINT,,PACKLIST,,PACK'
*......................................................................
*
DDNAME ALLOCATION:
FLMALLOC
IOTYPE=U,DDNAME=SYSPRINT
FLMALLOC
IOTYPE=O,DDNAME=PACKLIST,RECNUM=50000,
C
RECFM=FBA,LRECL=133,
C

228

ISPF/SCLM V4 Guide

KEYREF=LIST
*---------------------------------------------------------------------*
- COPY PROJECT-DEFINITION TO CREATE TESTPROJECT
*---------------------------------------------------------------------*
FLMTRNSL
CALLNAM='CREATE TESTPROJECT',
C
FUNCTN=BUILD,
C
COMPILE=SCLMISP,
C
DSNAME=SCLM41.PROJDEFS.LOAD,
C
VERSION=1.0,
C
CALLMETH=LINK,
C
GOODRC=4,
C
PORDER=1,
C
OPTIONS='MET#B02 @@FLMMBR,NOTEST'
*......................................................................
*
DDNAME ALLOCATION:
*
(* PROJECT-INPUT *)
FLMALLOC
IOTYPE=S,DDNAME=MPROJ,KEYREF=SINC
*
(* CSECT-SOURCE-OUTPUT *)
FLMALLOC
IOTYPE=P,DDNAME=TPROJ,KEYREF=OUT1,RECNUM=1500,
C
DIRBLKS=5,DFLTTYP=PROJECTS,LANG=ASMPROJT,MEMBER=@@FLMONM
*
***====================================================================

18.3.2 REXX Program MET#B01 to Pack Compile List Output


/* === REXX ======================================================== */
/*
SCLM-USER-TRANSLATOR-ROUTINE AT PROMOTE (COPY-PHASE)
*/
/*
"MET#B01"
"PACK / UNPACK DATA SETS
*/
/* ================================================================= */
/* SET TRACEMODE
*/
TREXX = 'MET#B01'
'ISPEXEC VGET (S92SCLT1 S92SCLT2 S92REXX) PROFILE'
IF RC = 0 THEN DO
IF (POS(TREXX,S92REXX) > 0) | (S92REXX = '') THEN DO
IF S92SCLT1 = 'TRACE X' THEN DO
INTERPRET S92SCLT2
/* SET TRACE
*/
END
ELSE DO
INTERPRET S92SCLT1
/* SET TRACE
*/
END
END
END
/*********************************************************************/
/* GET INPUT PARAMETERS:
*/
PARSE UPPER ARG FROMDD ',' FROMMEMB ',' TODD ',' TOMEMB ',' PACKOPT .
SS = "MET#B01 - ***"
HRC = 0
IF (PACKOPT <> 'PACK' & PACKOPT <> 'UNPACK') THEN DO
SAY SS 'MISSING PARAMETER PACK OR UNPACK| ABORT |'
EXIT 8
END
IF PACKOPT = 'PACK' THEN DO
LMPACK = 'PACK'
END
ELSE DO
LMPACK = ''
END
/* COPY DATA SETS WITH LMCOPY

*/

'ISPEXEC LMINIT DATAID(FROMID) DDNAME('FROMDD') ENQ(SHR)'


IF RC <> 0 THEN DO
SAY SS 'ERROR OCCURRED WHEN ALLOCATING DAT SET' FROMDD 'RC:' RC
HRC = 8
END
ELSE DO
'ISPEXEC LMINIT DATAID(TOID) DDNAME('TODD') ENQ(SHR)'
IF RC <> 0 THEN DO
SAY 'ZERRSM:' ZERRSM
SAY 'ZERRLM:' ZERRLM
SAY SS 'ERROR OCCURRED WHEN ALLOCATING DATA SET' TODD 'RC:' RC
HRC = 8
END
ELSE DO
'ISPEXEC LMCOPY FROMID('FROMID') FROMMEM('FROMMEMB') ,
TODATAID('TOID') TOMEM('TOMEMB')' LMPACK
IF RC <> 0 THEN DO
SAY SS 'ERROR AT' PACKOPT 'OF DATA SET' FROMDD 'RC:' RC
HRC = 8
Chapter 18. Meta Project

229

END
END
END
'ISPEXEC LMFREE DATAID('FROMID')'
'ISPEXEC LMFREE DATAID('TOID')'
EXIT HRC

18.3.3 REXX Program MET#B02 to Make Test Project Definition


/* REXX **************************************************************/
/* MET#B02 Create Test-project-definition from original project
*/
/*
*/
/* CREATED
------------------------------------------------------ */
/* 08.12.92
*/
/*
*/
/* INVOCATION FROM LANGUAGE DEFINITION "ASMPROJ" ------------------- */
/* CALL MET#B02 INPUT-DATASET,Member,LANGUAGE,PROOFGROUP,GOODRC
*/
/*
*/
/* Parameter ------------------------------------------------------- */
/* INPUT DATASET= SCLM-LIBNAME
*/
/* Member
= Source-Member
*/
/* etc.
*/
/* RCs ------------------------------------------------------------ */
/* 0 = OK
*/
/* 8 = Technical Error / Abort
*/
/*********************************************************************/
trexx = 'MET#B02'
/* set trace
*/
'ISPEXEC VGET (s92sclt1 s92sclt2 s92rexx) PROFILE'
IF rc = 0 THEN DO
/*
*/
IF (POS(trexx,s92rexx) > 0) | (s92rexx = '') THEN DO
IF s92sclt1 = 'TRACE X' THEN DO /*
*/
INTERPRET s92sclt2
/* Trace setzen
*/
END
/*
*/
ELSE DO
/*
*/
INTERPRET s92sclt1
/* Trace setzen
*/
END
/*
*/
END
/*
*/
END
/*
*/
/*********************************************************************/
/*
*/
/*
*/
/* Set input parameters
*/
/*
*/
PARSE UPPER ARG flmmbr ',' test .
/*
*/
ss = 'MET#B02 - ***'
/*
*/
zn = 0
/*
*/
maxrc = 0
/*
*/
/*
*/
/*
*/
/*********************************************************************/
/* Examine SCLM project name conventions - PLEASE CUSTOMIZE
*/
/*********************************************************************/
/*
*/
PARSE UPPER VAR flmmbr n1 2 n25 6 nn /*
*/
/*
*/
IF ((n1 = 'S') & (DATATYPE(N25) = 'NUM') & (LENGTH(N25) = 4) &,
((nn = 'X') | (nn = 'F') | (nn = 'M') |,
(nn = 'L') | (nn = ''))) THEN DO /*
*/
namkonv = 'JA'
/*
*/
END
/*
*/
ELSE DO
/*
*/
SIGNAL END_EXIT
/* ---> EXIT
*/
END
/*
*/
/*
*/
/*
*/
/*********************************************************************/
/* Combine Test project name
- PLEASE CUSTOMIZE
*/
/*********************************************************************/
/*
*/
mainproj = SUBSTR(flmmbr,1,5)
/*
*/
altproj = STRIP(SUBSTR(flmmbr,6,1)) /*
*/
testproj = mainproj || 'T'
/*
*/
/***************************************** END OF CUSTOMIZING ********/
/*
*/
/* Loop to copy records
*/
/* Records will be checked for project name
*/
/* and transferred in test project name
*/
/*
*/
ddend = 0
/*
*/
/*
*/
DO WHILE ddend = 0
/*
*/

230

ISPF/SCLM V4 Guide

'EXECIO 1 DISKR mproj'


/*
*/
IF rc = 0 THEN DO
/*
*/
zn = zn + 1
/*
*/
PULL recd
/*
*/
IF POS(mainproj,recd) > 0 THEN DO
IF POS(mainproj,recd) > 66 THEN DO
SAY ss 'Projectname in line ' zn ' not changed
***'
maxrc = 8
/*
*/
ddend = 1
/*
*/
PUSH recd
/*
*/
END
/*
*/
ELSE DO
/*
*/
recdpref= SUBSTR(recd,1,71) /*
*/
recdrest= SUBSTR(recd,72,9) /*
*/
PARSE VAR recdpref string1 (mainproj) string2
PARSE VAR string2 string2a ' ' string2b
IF LENGTH(string2) = length(string2a) THEN DO
recdnew = SUBSTR(string1 || testproj || string2,1,71) ||,
recdrest
SAY ss 'Lineend of line ' zn ' truncated**'
maxrc = 4
/*
*/
END
/*
*/
ELSE DO
/*
*/
recdnew = string1 || testproj || string2a || ' ' ||,
string2b || recdrest
END
/*
*/
PUSH recdnew
/*
*/
END
/*
*/
END
/*
*/
ELSE DO
/*
*/
PUSH recd
/*
*/
END
/*
*/
'EXECIO 1 DISKW tproj'
/*
*/
IF rc = 0 THEN DO
/*
*/
maxrc = rc
/*
*/
SIGNAL END_EXIT
/*
*/
END
/*
*/
END
/*
*/
ELSE DO
/*
*/
ddend = 1
/*
*/
END
/*
*/
END
/*
*/
/*
*/
/*
*/
/* Close data sets
*/
/*
*/
'EXECIO 0 DISKR mproj (FINIS)'
/*
*/
IF rc = 0 THEN DO
/*
*/
maxrc = rc
/*
*/
END
/*
*/
'EXECIO 0 DISKW tproj (FINIS)'
/*
*/
IF rc = 0 THEN DO
/*
*/
maxrc = rc
/*
*/
END
/*
*/
/*
*/
/*
*/
/* Return to SCLM
*/
/*
*/
END_EXIT:
/*
*/
EXIT maxrc
/*
*/

18.3.4 Language Definition ASMPROJT (Member @ASMPRJT)


***====================================================================
*** SCLM LANGUAGE DEFINITION "ASMPROJT"
***
PARSE: SCLM ASM PARSER
***
BUILD: ASSEMBLER H COMPILE FOR TEST-PROJDEFS (MVS)
***====================================================================
*
ASMPROJT FLMSYSLB EPO.ISPF410.SISPMACS
FLMSYSLB SYS1.MACLIB
*
FLMLANGL
LANG=ASMPROJT,VERSION=V1.0
*
***********************************************************************
* PARSER TRANSLATOR:
*---------------------------------------------------------------------*
FLMTRNSL CALLNAM='SCLM ASM PARSE',
C
FUNCTN=PARSE,
C
COMPILE=FLMLPGEN,
C
PORDER=1,
C
OPTIONS=(SOURCEDD=SOURCE,
C
Chapter 18. Meta Project

231

PARSEMEM=@@FLMMBR,
STATINFO=@@FLMSTP,
LISTINFO=@@FLMLIS,
LISTSIZE=@@FLMSIZ,
LANG=A)
(* SOURCE
*)
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMDSN(@@FLMMBR)

C
C
C
C

*
***********************************************************************
* BUILD TRANSLATOR(S):
***********************************************************************
*
FLMTRNSL
CALLNAM='ASM-MVS',
C
FUNCTN=BUILD,
C
COMPILE=IEV90,
C
VERSION=V1.0,
C
GOODRC=4,
C
PORDER=1,
C
OPTIONS=(NODECK,OBJECT,XREF(FULL))
*......................................................................
*
DDNAME ALLOCATION:
*FLMALLOC
IOTYPE=O,DDNAME=SYSGO,KEYREF=OBJ,RECNUM=10000
FLMALLOC IOTYPE=O,DDNAME=SYSLIN,KEYREF=OBJ,RECNUM=9000,DFLTTYP=OBJ
FLMALLOC
IOTYPE=I,DDNAME=SYSLIB,KEYREF=SINC
FLMCPYLB
EPO.ISPF410.SISPMACS
FLMCPYLB
SYS1.MACLIB
FLMALLOC
IOTYPE=S,DDNAME=SYSIN,KEYREF=SINC,RECNUM=9000
FLMALLOC
IOTYPE=W,DDNAME=SYSUT1,RECNUM=25000
FLMALLOC
IOTYPE=A,DDNAME=SYSTERM
FLMCPYLB
NULLFILE
FLMALLOC
IOTYPE=A,DDNAME=SYSPUNCH
FLMCPYLB
NULLFILE
FLMALLOC
IOTYPE=W,DDNAME=SYSPRINT,RECNUM=50000,
C
RECFM=FBA,LRECL=133,PRINT=Y
*
***********************************************************************
*
PACK COMPILELIST FOR MVS
***********************************************************************
*
FLMTRNSL
CALLNAM='PACK-LIST',
C
FUNCTN=BUILD,
C
COMPILE=SCLMISP,
C
DSNAME=SCLM41.PROJDEFS.LOAD,
C
CALLMETH=LINK,
C
VERSION=V1.0,
C
GOODRC=0,
C
PORDER=1,
C
OPTIONS='%MET#B01 SYSPRINT,,PACKLIST,,PACK'
*......................................................................
*
DDNAME ALLOCATION:
FLMALLOC
IOTYPE=U,DDNAME=SYSPRINT
FLMALLOC
IOTYPE=O,DDNAME=PACKLIST,RECNUM=50000,
C
RECFM=FBA,LRECL=133,
C
KEYREF=LIST
***-----------------------------------------------------------------***

18.3.5 Language Definition LKEDPROJ (Member @LKEDPRJ)


*
FLMLANGL LANG=LKEDPROJ,CANEDIT=N,VERSION=V1.0
*
***********************************************************************
* BUILD TRANSLATOR(S): LINKAGE EDITOR FOR SCLM PROJDEFS (MVS)
***********************************************************************
*
FLMTRNSL CALLNAM='LINK-PROJDEFS',
C
FUNCTN=BUILD,
C
COMPILE=IEWL,
C
VERSION=V1.0,
C
GOODRC=0,
C
PORDER=3,
C
OPTIONS=(LIST,XREF,LET,DCBS,NORENT,AMODE=24,RMODE=24)
*......................................................................
*
DDNAME ALLOCATION USING DDNAME-SUBSTITUTION:
* 1
(* SYSLIN *)
FLMALLOC IOTYPE=S,KEYREF=SINC,DDNAME=SYSLIN,RECNUM=20000
* 2
(* LOAD MODULE NAME *)
FLMALLOC IOTYPE=L,KEYREF=LOAD
* 3
(* SYSLMOD *)
FLMALLOC IOTYPE=P,DDNAME=SYSLMOD,KEYREF=LOAD,
C
RECFM=U,BLKSIZE=6144,RECNUM=500
* 4
(* SYSLIB *)

232

ISPF/SCLM V4 Guide

FLMALLOC IOTYPE=A,DDNAME=SYSLIB
FLMCPYLB COBOL.V1R4M0.COB2LIB
FLMCPYLB VSPASCAL.VSPV1R2.SAMPRUN1
FLMCPYLB PLI.V2R3M0.SIBMBASE
FLMCPYLB PLI.V2R3M0.PLIBASE
FLMCPYLB VSPASCAL.VSPV1R2.SAMPMSG1
FLMCPYLB EPO.ISPF410.LOADLIB
*
FLMCPYLB SYS1.SISPLOAD
*
FLMCPYLB SUDB2C.DSN230.DSNLOAD
*
FLMCPYLB IMSESA.RESLIB
*
FLMCPYLB CICS.V3R3M0.SDFHLOAD
FLMCPYLB SYS1.LINKLIB
* 5
(* N/A *)
FLMALLOC IOTYPE=N
* 6
(* SYSPRINT *)
FLMALLOC IOTYPE=O,DDNAME=SYSPRINT,KEYREF=LMAP,RECFM=FBA,
C
LRECL=121,RECNUM=2500,PRINT=Y
* 7
(* N/A *)
FLMALLOC IOTYPE=N
* 8
(* N/A *)
(BINDER NO LONGER NEEDS SYSUT1 )
FLMALLOC IOTYPE=N
* 9
(* N/A *)
FLMALLOC IOTYPE=N
* 10
(* N/A *)
FLMALLOC IOTYPE=N
* 11
(* N/A *)
FLMALLOC IOTYPE=N
* 12
(* SYSTERM *)
FLMALLOC IOTYPE=A,DDNAME=SYSTERM
FLMCPYLB NULLFILE
*
***********************************************************************
*** SCLM USER EXIT
*PROMOTE SCLM PROJEKT-DEF*
***
"COPY LOADMODULE IN (PROJECT).PROJDEFS.LOAD VIA MET#P21"
***
- TO LEVEL TEST AS TESTPROJECT AND
***
- TO LEVEL PROD WHEN PRODUCTION PROJECT
***
- EVENTUALLY GENERATE FROM MEMBERNAME A DEVIATING NAME
***
FOR LOADMOD OF ALTERNATE PROJECT DEFINITION
***********************************************************************
*
FLMTRNSL
CALLNAM='PROMOTE-EXIT',
C
FUNCTN=COPY,
C
COMPILE=SCLMISP,
C
DSNAME=SCLM41.PROJDEFS.LOAD,
C
VERSION=1.0,
C
CALLMETH=LINK,
C
PDSDATA=Y,
C
GOODRC=4,
C
PORDER=1,
C
OPTIONS='%MET#P21 /@@FLMPRJ,@@FLMGRP,@@FLMTYP,@@FLMMBR, C
@@FLMTOG'

18.3.6 REXX Program MET#P21 (Promote-Copy-Exit) to Copy Project Definition


/* REXX **************************************************************/
/* MET#P21 User-Exit with Promote (Copy)
*/
/*
Copy Member to prjid.PROJDEFS.LOAD
*/
/*
*/
/* Invocation ------------------------------------------------------ */
/* CALL MET#P21 InputDataSet,Member,TargetGroup
*/
/*
*/
/* Parameter ------------------------------------------------------- */
/* InputDataSet = SCLM-Library
*/
/* Member
= Membername
*/
/* TargetGroup = PromoteTOgroup
*/
/* etc.
*/
/* RC -------------------------------------------------------------- */
/* 0 = ok
*/
/* Return-Codes from LM Services
*/
/*
*/
/*********************************************************************/
TRACE off
Signal on Syntax
Signal on Halt
Signal on Novalue
Parse Upper Arg OPTIONS
PROJECT
GROUP
TYPE
PART
TOGROUP
JUNK

'/'
','
','
','
','
','
.

,
,
,
,
,
,

/*
/*
/*
/*
/*
/*
/*

Optional Parameters list */


PROJECT
*/
Group
*/
Type
*/
Member Name
*/
Promote to Group
*/
Throw away
*/
Chapter 18. Meta Project

233

OPTIONS = strip(OPTIONS)
PROJECT = strip(PROJECT)
GROUP = strip(GROUP)
TYPE
= strip(TYPE)
PART
= strip(PART)
TOGROUP = strip(TOGROUP)
flmdsn = PROJECT'.'GROUP'.'TYPE
/*********************************************************************/
trexx = 'MET#P21'
/* Set Program
*/
'ISPEXEC VGET (s92sclt1 s92sclt2 s92rexx) PROFILE'
IF rc = 0 THEN DO
/*
*/
IF (POS(trexx,s92rexx) > 0) | (s92rexx = '') THEN DO
IF s92sclt1 = 'TRACE X' THEN DO /*
*/
INTERPRET s92sclt2
/* Set Trace
*/
END
/*
*/
ELSE DO
/*
*/
INTERPRET s92sclt1
/* Set Trace
*/
END
/*
*/
END
/*
*/
END
/*
*/
/*********************************************************************/
ss = "MET#P21 - ***"
lmrc = 0
"ISPEXEC CONTROL ERRORS RETURN"
/* TSOMSG = MSG(OFF) */
/* ...Parse SCLM-DataSetName ....................................... */
/* ...(END, if not Typ = LOAD) ..................................... */
IF (TYPE = 'LOAD') THEN DO
lmrc = 0
SIGNAL END_EXIT
END

/* ---> exit */

/* Check SCLM project name standards - MUST BE CUSTOMIZED

....... */

PARSE UPPER VAR PART n1 2 n25 6 nn


IF ((n1 = 'S') & (DATATYPE(N25) = 'NUM') & (LENGTH(N25) = 4)) THEN DO
namkonv = 'YES'
END
ELSE DO
namkonv = 'NO'
END
/*....Receive last character of PART and create .................. */
/*....main project name PROJMAIN without alt.-suffixes ............ */
alterkz = SUBSTR(PART,LENGTH(PART),1)
SELECT
WHEN (alterkz = 'F') THEN DO
projmain = SUBSTR(PART,1,LENGTH(PART)-1)
END
WHEN (alterkz = 'L') THEN DO
projmain = SUBSTR(PART,1,LENGTH(PART)-1)
END
WHEN (alterkz = 'M') THEN DO
projmain = SUBSTR(PART,1,LENGTH(PART)-1)
END
WHEN (alterkz = 'X') THEN DO
projmain = SUBSTR(PART,1,LENGTH(PART)-1)
END
OTHERWISE DO
projmain = PART
alterkz = ''
END
END
/*....Receive last character of PROJMAIN and create ................ */
/*....main project name PROJNAME without any suffixes .............. */
testkz = SUBSTR(projmain,LENGTH(projmain),1)
projname = projmain
/*....customization ITSC
projname = PROJECT

................................ */

/*....Check TargetGroup for PROMOTE ................................ */


/*....when wrong TargetGroup : Message ............................ */
/*....END, if TargetLevel neither TESTDEFS nor PRODDEFS ............ */

234

ISPF/SCLM V4 Guide

SELECT
WHEN (TOGROUP = 'PRODDEFS') THEN DO
IF ((testkz = 'T') | (namkonv = 'NO')) THEN DO
SAY ss'*******************************************************'
SAY ss' Promote TEST-Project to PROD. The loadmodule
***'
SAY ss' will NOT be copied to PROJDEFS.LOAD
***'
SAY ss'*******************************************************'
lmrc = 4
SIGNAL END_EXIT
/* ---> EXIT */
END
END
WHEN (TOGROUP = 'TESTDEFS') THEN DO
IF ((testkz = 'T') & (namkonv = 'YES')) THEN DO
SAY ss'***************************************************'
SAY ss' Promote PROD-Project to TEST. The Loadmodule ***'
SAY ss' will NOT be copied to PROJDEFS.LOAD
***'
SAY ss'***************************************************'
lmrc = 4
SIGNAL END_EXIT
/* ---> EXIT */
END
END
OTHERWISE DO
LMRC = 0
SIGNAL END_EXIT
/* ---> EXIT */
END
END
/* End SELECT check TOGROUP */
/*....Membername
/*....<PROJNAME>
/*...."PROMOTE"
/*...."DELETE"
/*...."MIGRATE"
/*...."FIX"

<LOADMBR> in TargetLib
fetch: ................
for primary Project Definition ....................
for alternate Definition with Suffix "F".........
for alternate Definition with Suffix "L".........
for alternate Definition with Suffix "M".........
for alternate Definition with Suffix "X".........

SELECT
WHEN (alterkz = 'F') THEN
loadmbr = 'PROMOTE'
END
WHEN (alterkz = 'L') THEN
loadmbr = 'DELETE'
END
WHEN (alterkz = 'M') THEN
loadmbr = 'MIGRATE'
END
WHEN (alterkz = 'X') THEN
loadmbr = 'FIX'
END
OTHERWISE DO
loadmbr = projNAME
END
END

*/
*/
*/
*/
*/
*/

DO
DO
DO
DO

/*....COMBINE LIBRARY AND CHECK - MUST BE CUSTOMIZED ............... */


indsn = "'" || flmdsn || "'"
loaddsn = projname || ".PROJDEFS.LOAD"
outdsn = "'" || loaddsn || "'"
outmbr = "'" || loaddsn || "("loadmbr")'"
dsninfo = SYSDSN(outmbr)
IF ((dsninfo = 'OK') | (dsninfo = 'MEMBER NOT FOUND')) THEN DO
lmrc = 0
END
ELSE DO
SAY ss' ********************************************************'
SAY ss' User-Exit to copy to 'loaddsn' library'
SAY ss' Error TargetLoadLibrary' loaddsn':'
SAY ss' 'DSNINFO' ***'
IF (TOGROUP = 'TESTDEFS') THEN DO
SAY ss' Execution User-Exit aborted
******'
SAY ss' PROMOTE however will continue
******'
lmrc = 4
END
ELSE DO
SAY ss' Promote is consequently aborted
******'
lmrc = 8
END
SAY ss' ********************************************************'
SIGNAL END_EXIT
/* ---> Exit */
END
/*....Invocation of LM Services .................................... */

Chapter 18. Meta Project

235

"ISPEXEC LMINIT DATAID(INPUT),DATASET("indsn") ENQ(SHRW)"


lmrc = rc
IF lmrc = 0 THEN DO
SAY ss' ********************************************************'
SAY ss' User-Exit to copy to 'loaddsn' library'
SAY ss' LMINIT-Error 'indsn'. Returncode: ' lmrc
SAY ss' ********************************************************'
END
ELSE DO
"ISPEXEC LMINIT DATAID(OUTPUT),DATASET("outdsn") ENQ(SHRW)"
lmrc = rc
END
IF lmrc = 0 THEN DO
SAY ss' ********************************************************'
SAY ss' User-Exit to copy to 'loaddsn' library'
SAY ss' LMINIT-Error 'outdsn'. Returncode: ' lmrc
SAY ss' ********************************************************'
END
ELSE DO
"ISPEXEC LMCOPY FROMID("input") FROMMEM("PART"),
TODATAID("output") TOMEM("loadmbr"),REPLACE"
lmrc = rc
END
IF lmrc = 0 THEN DO
SAY ss' ********************************************************'
SAY ss' User-Exit to copy to 'loaddsn'-library'
SAY ss' LMCOPY-Error. Returncode: ' lmrc
SAY ss' ********************************************************'
END
ELSE DO
SAY ss' ================================================'
SAY ss' Copy Loadmodule "'PART'" as "'loadmbr'"'
SAY ss'
in 'loaddsn' was successful ** RC = 0'
SAY ss' ================================================'
END
"ISPEXEC LMFREE DATAID("input")"
"ISPEXEC LMFREE DATAID("output")"
/*....END (and error exit ) ....................................... */
END_EXIT:
EXIT lmrc
/*************end */

18.3.7 Architecture Definition ASMPROJ - Example


The naming convention used provides a production environment for the project
hlq S9200 and a test environment for another project hlq S9200T, both of which
are derieved from the part names.
The above REXX program MET#P21 requires careful customization.
******************************************************* MEMBER AS9200
*
* HL ARCHITEKTUR-DEFINITION
FOR SCLM-PROJECT S9200
*
INCL LS9200
ARCHDEF
* LEC MAIN PROJDEF
INCL LS9200F ARCHDEF
* LEC ALT. PROJDEF PROMOTE
INCL LS9200L ARCHDEF
* LEC ALT. PROJDEF DELETE
INCL LS9200X ARCHDEF
* LEC ALT. PROJDEF FIX
INCL LS9200T ARCHDEF
* LEC MAIN PROJDEF
INCL LS9200TF ARCHDEF
* LEC ALT. PROJDEF PROMOTE
INCL LS9200TL ARCHDEF
* LEC ALT. PROJDEF DELETE
INCL LS9200TX ARCHDEF
* LEC ALT. PROJDEF FIX
*-------------------------------------------------------- END AS9200
******************************************************* MEMBER LS9200
*
* LINK EDIT CONTROL (LEC) ARCHDEF
FOR MAIN SCLM-PROJDEF S9200
*
LKED LKEDPROJ
******** LINK PROJDEFS ********
INCL S9200
ARCHDEF
* INPUT OBJECT-MODUL
*
LOAD S9200
LOADMVS
* OUTPUT LADEMODUL
*
LMAP S9200
LMAPMVS
* OUTPUT LINK-LISTE
*
*-------------------------------------------------------- END LS9200
******************************************************* MEMBER S9200
*
* COMPILE CONTROL (CC) ARCHDEF
FOR MAIN SCLM-PROJDEF. S9200
*

236

ISPF/SCLM V4 Guide

SINC S9200
PROJDEF
* INPUT SOURCE
OUT1 S9200T PROJDEF
* OUTPUT TESTPROJECT
OBJ S9200
OBJMVS
* OUTPUT OBJECT-MODUL
LIST S9200
COMPMVS
* OUTPUT COMPILELIST
*-------------------------------------------------------- END S9200

*
*
*
*

******************************************************* MEMBER LS9200T


*
* LINK EDIT CONTROL (LEC) ARCHDEF
FOR MAIN SCLM-PROJDEF FOR S9200T
*
LKED LKEDPROJ
******** LINK PROJDEFS ********
INCL S9200T ARCHDEF
* INPUT OBJECT-MODUL
*
LOAD S9200T LOADMVS
* OUTPUT LADEMODUL
*
LMAP S9200T LMAPMVS
* OUTPUT LINK-LISTE
*
*-------------------------------------------------------- END LS9200T
******************************************************* MEMBER S9200T
*
* COMPILE CONTROL (CC) ARCHDEF
FOR MAIN SCLM-PROJDEF FOR S9200T
*
SINC S9200T PROJDEF
* INPUT SOURCE
*
OBJ S9200T OBJMVS
* OUTPUT OBJECT-MODUL
*
LIST S9200T COMPMVS
* OUTPUT COMPILELIST
*
*-------------------------------------------------------- END S9200T

That's not the end


but a good chance to point you now to Chapter 1 of ISPF/SCLM Project
Manager's Guide, which now has much more meaning to you and can be
very helpful to understand more about Software Configuration and L ibrary
M anagement (SCLM).

Chapter 18. Meta Project

237

238

ISPF/SCLM V4 Guide

Chapter 19. Optimization


19.1.1 PDS-E
ISPF Version 4.1 also supports, with DFS, extended partitioned load data sets.

19.1.2 Coding with Select Statements


Are you bugged by coding nested IFs? Do you find yourself testing r c = 0 all the
time? Does your code keep getting indented? Are you having trouble reading
your code?
Why not try using the Select statement the next time.
The Current_Way of coding.
Do
Function_1
if rc = 0 then
Do
Function_2
if rc = 0 then
Do
Function_3
End
End
End

A New_Way of coding.
Do
Select;
When New_Function_1()
then NOP; /* Failure_1 */
When New_Function_2()
then NOP;
When New_Function_3()
then NOP;
Otherwise; /* Success */
End;
End;

The key is each function executed must return a boolean 1 or 0 meaning:


Boolean 0: Success, continue, do not stop, etc....
Result: Select skips to next when statement
Boolean 1: Abort, stop, rc=0, etc...
Result: Execute this when statement and exit the select
If Otherwise is executed within the select, everything is successful.
This is a different way to think about things. It's fast. It's easy
to code. It eliminates a lot of indentation of next functions. It
allows unique debug logic to be inserted at the error point to capture
additional debugging information without modification of the base
functions.

19.1.3 Submit to Batch


It is good practice to do builds and promotes in batch mode. To be able to do so,
the SCLM project manager must customize 'ispf...SISPSENU(FLMLIBS)'.

19.1.4 Establish an Own Class for Batch Jobs


To let developers work in an almost uninterrupted mode, it is adviseable to
direct all SCLM jobs to a prioritized class.

19.1.5 Output Load Module in Non-SCLM Data Set


19.1.5.1 Reason
The main reason that we would like to have a common LOADLIB at the
lowest level is that the system folks do not want to add 13 loadlib data sets
to the CICS concatenation. So, if the developers can build at the low level
and then after a clean compilation and linkage editing of the load module,
have the load module copied from their level data set(under SCLM) to the
common one(non-SCLM), there will only need to be one loadlib data set for
CICS.
Copyright IBM Corp. 1994

239

Note: There is no necessity to do so. MVS will allow 123 data sets to
concatenate. This normally suffices to concatenate all DEVELOPER data
sets. Good results were assembled at SCLM reference account
'Neckarwerke Esslingen, Germany'.
I would rather see a drawback in having many developers work through
one group, thereby opening the delimiting of parts to a shared group.

19.1.5.2 Solution 1 - Output Loadmodule with Linkage Editor


The following is a quotation from an SCLM conference disk:
The linkage editor is a pretty good copy utility for load modules. It struck me
that if you changed the SYSLMOD FLMALLOC from IOTYPE=P to IOTYPE=U,
add DDNAME=zzz, and then make sure that your non-SCLM data set has been
previously allocated to DDNAME=zzz, that you would be in business. So I tried
it and it worked. The load module ended up in FTSOMR1.NONSCLM.DATA SET.
Here is a sample language definition @COPY1 and an ARCHDEF.

240

ISPF/SCLM V4 Guide

***********************************************************************
*
370/LINKAGE EDITOR LANGUAGE DEFINITION FOR SCLM
* ADD FLMCPYLB MACROS FOR EACH 'STATIC' INPUT DATA SET FOR LINKEDIT
* PROCESSING, TO THE 'SYSLIB' FLMALLOC MACRO.
* MAKE SURE PORDER=3. THE LINK EDIT USES DD NAME LIST SUBSTITUTION.
* CUSTOMIZE THE 'OPTIONS' AND 'GOODRC' FIELDS TO YOUR STANDARDS.
***********************************************************************
FLMLANGL
LANG=LOADX,CANEDIT=N,VERSION=L370V1.0
*
FLMTRNSL CALLNAM='IEFBR14',
C
FUNCTN=BUILD,
C
COMPILE=IEFBR14,
C
VERSION=1,
C
GOODRC=0,
C
PORDER=1
* 1
(* SYSLMOD *)
FLMALLOC IOTYPE=A,DDNAME=SYSLMOD
FLMCPYLB FTSOMR1.NONSCLM.DATA SET
*
FLMTRNSL CALLNAM='LKED/370 EXTERNAL',
C
FUNCTN=BUILD,
C
COMPILE=IEWL,
C
VERSION=F64,
C
GOODRC=0,
C
PORDER=3,
C
OPTIONS=(DCBS,MAP)
* 1
(* SYSLIN *)
FLMALLOC IOTYPE=S,KEYREF=INCL,RECFM=FB,LRECL=80,
C
RECNUM=20000,DDNAME=SYSLIN
* 2
(* LOAD MODULE NAME *)
FLMALLOC IOTYPE=L,KEYREF=LOAD
* 3
(* SYSLMOD *)
FLMALLOC IOTYPE=U,DDNAME=SYSLMOD
* 4
(* SYSLIB *)
FLMALLOC IOTYPE=A,DDNAME=SYSLIB
* ADD FLMCPYLB MACROS FOR EACH STATIC INPUT DATA SET
*
FLMCPYLB SYS2.PLI.PLIBASE
FLMCPYLB SYS1.LINKLIB
* 5
(* N/A *)
FLMALLOC IOTYPE=N
* 6
(* SYSPRINT *)
*
FLMALLOC IOTYPE=O,KEYREF=LMAP,RECFM=FBA,LRECL=121,
C
FLMALLOC IOTYPE=O,RECFM=FBA,LRECL=121,
C
RECNUM=2500,PRINT=Y,DDNAME=SYSPRINT
* 7
(* N/A *)
FLMALLOC IOTYPE=N
* 8
(* SYSUT1 *)
FLMALLOC IOTYPE=W,RECFM=U,LRECL=0,RECNUM=5000,
C
DDNAME=SYSUT1
* 9
(* N/A *)
FLMALLOC IOTYPE=N
* 10
(* N/A *)
FLMALLOC IOTYPE=N
* 11
(* N/A *)
FLMALLOC IOTYPE=N
* 12
(* SYSTERM *)
FLMALLOC IOTYPE=A,DDNAME=SYSTERM
FLMCPYLB NULLFILE
**********************************************************************
* CHANGE ACTIVITY:
*
* OY34273 - 900810 - CHANGED LRECL=6144 TO LRECL=0 FOR SYSLMOD AND *
*
SYSUT1. GT4045 - AAB
*
**********************************************************************
* 5665-402 (C) COPYRIGHT IBM CORP 1980, 1989

Figure 135. Sample SCLM Language with Output Directed To NON-SCLM Data Set

And the ARCHDEF:


*
* DEFINE LOAD MODULE: TEST
*
LOAD TEST LOAD
INCLD TESTIT ASMH
LKED LOADX

Chapter 19. Optimization

241

19.1.5.3 Solution 2 - Copy Translator as REXX Procedure


Embedding a Copy Translator
FLMTRNSL CALLNAM='......',
FUNCTN=COPY,
COMPILE=SCLMISP,
CALLMETH=LINK,
DSNAME=SCLM.PROJDEFS.LOAD,
GOODRC=4,
PDSDATA=Y,
OPTIONS='%COPY TEMP',
PORDER=1
FLMALLOC IOTYPE=W,DDNAME=SYSIN
FLMALLOC IOTYPE=W,DDNAME=SYSUT1
FLMALLOC IOTYPE=W,DDNAME=SYSPRINT,PRINT=Y
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMDSN

C
C
C
C
C
C
C
C

Figure 136. Translator Sample Embedding Copy Procedure

REXX Copy Procedure Called Copy


/* REXX */
Arg mem
"ALLOC FILE(DEST) DATA SET('uid.LOAD') OLD"
Queue ' COPY INDD=SOURCE,OUTDD=DEST'
Queue ' SELECT MEMBER=(('mem',,R))'
"EXECIO " Queued() " DISKW SYSIN (FINIS"
"CALL 'SYS1.LINKLIB(IEBCOPY)'"
"FREE FILE(DEST)"

Figure 137. Copy Procedure as Translator

19.1.5.4 Solution 3 - Promote Exit Invocation of IEBCOPY


Below is another sample with IEBCOPY in a promote exit to copy PSBs and
DBDs to their appropriate TEST or PROD libraries.

PROD

SYS1.LIB1.DBDLIB I copy copy H SYS1.LIB1.PSBLIB

TEST

SYS1.LIB2.DBDLIB I copy copy H SYS1.LIB2.PSBLIB

PRIV

Figure 138. Promote Exit MET#P12 for IEBCOPYing PSB and DBD

242

ISPF/SCLM V4 Guide

/*REXX *************************************************************/
/* 27.07.92 CREATED
*/
/* from SCLM data set sclm.userid.LOAD to SYS1.LIB2.xxxLIB bzw. */
/* from SCLM data set sclm.userid.LOAD to SYS1.LIB1.xxxLIB.
*/
/* (xxx = DBD or PSB)
*/
/*******************************************************************/
trace off
arg xxx @@FLMPRJ @@FLMGRP @@FLMTYP @@FLMMBR .
if substr(@@FLMGRP,5,4) = "PROD" then do
say xxx"-Module may not be promoted to PROD"
return 4
end
if @@FLMTYP = "LINK" then do
say "DBD-module should reside in a LOAD-Library"
return 8
end
if @@FLMTYP <> "LOAD" then return 0
say "MET#P12 started"
say "Project:" @@FLMPRJ "Gruppe:" @@FLMGRP "Type: @@FLMTYP,
"Member: " @@FLMMBR
say "Action: " XXX"-Promote"
FROMDSN = @@FLMPRJ"."@@FLMGRP"."@@FLMTYP
if substr(@@FLMGRP,5,4) = "PRIV" then
TODSN = "SYS1.LIB1."XXX"LIBT"
else
if @@FLMGRP = userid() then
TODSN = 'SYS1.LIB2."XXX"LIBT"
else
call ENDE 12
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* COPY member to target PDS
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
say "Copy Member" @@FLMMBR "from" FROMDSN "to" TODSN
AMSG = msg("OFF")
"FREE FILE(FROMID)"
"FREE FILE(TOID)"
AMSG = msg("ON")
"ALLOC FILE(FROMID) DATA SET('"FROMDSN"') SHR"
if RC <> 0 then do
call ENDE 16
end
"ALLOC FILE(TOID) DATA SET('"TODSN"') OLD"
if RC <> 0 then do
"FREE FILE("FROMID")
call ENDE 20
end
"ALLOC FILE(SYSUT1) REUSE NEW UNIT(VIO) TRACKS SPACE(5 5)"
"ALLOC FILE(SYSUT2) REUSE NEW UNIT(VIO) TRACKS SPACE(5 5)"
"ALLOC FILE(SYSPRINT) DATA SET(*) OUTPUT REUSE"
"ALLOC FILE(SYSIN) REUSE NEW UNIT(VIO) TRACKS SPACE(1)",
"BLKSIZE(3120) LRECL(80) RECFM(F B)"
TEXT.0 = 2
TEXT.1 = " COPY INDD=((FROMID,R)),OUTDD=TOID"
TEXT.2 = " SELECT M="@@FLMMBR
"EXECIO * DISKW SYSIN (STEM TEXT. FINIS"
"CALL 'SYS1.LINKLIB(IEBCOPY)'"
"FREE FILE(FROMID)"
"FREE FILE(TOID)"
"FREE FILE(SYSUT1)"
"FREE FILE(SYSUT2)"
"FREE FILE(SYSPRINT)"
"FREE FILE(SYSIN)"
return RC
ENDE:
arg MSGNR .
if MSGNR = 0 then do
say "MET#P12-Exit ended normally"
exit MSGNR
end
say "MET#P12-Exit ended with error" MSGNR
exit MSGNR

Figure 139. REXX Promote Exit MET#P12

The picture depicts an additonal copy of:

Chapter 19. Optimization

243

PSBs to data set SYS1.LIB2.PSBLIB when promoting from private to


development
Note: The names refer to an example and can be changed.
PSBs to data set SYS1.LIB1.PSBLIB when promoting from development to
production
DBDs to data set SYS1.LIB2.DBDLIB when promoting from private to
development
DBDs to data set SYS1.LIB1.DBDLIB when promoting from development to
production.
Note: A return code of nonzero will promote the parts but not fulfill the copy to
the applicable promote exit libraries.

19.1.6 Link-edit with Parts from Non-SCLM Data Set


First, this solution doesn't involve FLMSYSLB. It does use FLMCPYLB and
FLMALLOC in the link-edit (FLMxxxx) member definition for the SCLM
environment. Object code and no source code was provided. Under SCLM,
there is a way to use such objects during link-edit. In the project definition,
specify FLMALLOC as follows:
*

(* OBJ *)
FLMALLOC
FLMCPYLB

(1)
IOTYPE=I, KEYREF=INCL,DDNAME=OBJ (2)
SERIES1.OBJ
(3)

Note:
1. IOTYPE=I - this means that it will use the data set referenced by
FLMCPYLB as input (this data set will be read from, not written to.).
2. KEYREF=INCL - this is telling SCLM to use the data set as part of the
hierarchy specified by DDNAME. In this case that DDNAME references
the object hierarchy.
3. FLMCPYLB - specifies which data set to copy from. The data set
SERIES.OBJ which I have listed here is a data set I created under
ISPF, and copied all object modules provided to me into this data set.
This solution does not track modules, it just uses bought modules to
complete the build.

19.1.7 Block Sizes for Link Editor


The following is a quotation from an SCLM conference disk:
I recently ran into blocksize problems with a project I was working on. I
needed to adjust the SIZE parameter for the linkage editor in the language
definition in FLM01370:
FLMTRNSL CALLNAM='LKED/370',
FUNCTN=BUILD,
COMPILE=IEWL,
VERSION=F64,
GOODRC=3,
PORDER=3,
OPTIONS=(DCBS,MAP,SIZE=(182K,64K))

The requirements for this parameter are discussed in section Size Parameter
Guidelines of MVS/DFP 3.3: Linkage Editor and Loader

244

ISPF/SCLM V4 Guide

19.1.7.1 Block Size Override


We use a blocksize of 19060 for our load libraries and haven't have any
problems on Versions 3.3, 3.4 or 3.5. Be sure you are using the DCB parameter
on the link-edit step. This parameter basically says you can override the
SYSLMOD blocksize.

19.1.8 ISPF Option 3.2, BLKSIZE = 0


A nice new feature.
With the recent installation of DFP 3.1, there is a new capability that many of us
should take advantage of when we can. If you are about to allocate a new data
set and have no particular BLKSIZE requirements, try the following:
BLKSIZE = 0
The system will calculate the most efficient block size
dependent on the actual unit, and we then set BLKSIZE accordingly.

19.1.9 DASD Management with DFHSM


It is recommended you review DASD Management plans to include
considerations for SCLM. Usually, this involves DFHSM daily space
management. You can direct DFHSM to take any data set that is in, say, four
extents and migrate or recall the data set so that the contents are compressed
and in a single primary extent. This takes care of freeing up the empty
cylinders/tracks at the from level.
DFHSM also insures that target amounts of free cylinders/tracks are created
every day so that when an SCLM promote expands the t o level, DASDM has
room to satisfy the secondary space extent requests.

19.1.10 Single Archdef


In many cases you don't even need CC archdefs. If you have a LEC archdef that
does an INCLD on a source member, or build the source member directly, SCLM
will generate a CC or GL archdef under the covers to be used for the duration of
the build (it is never stored as a physical member). The information for this
generated archdef is taken from the language definition by using the KEYREF
and DFLTTYPE parameters on the FLMALLOC macros.
You will still need to have LEC archdefs.

19.1.11 Unwanted Outputs


You may like to use copy to discard some of the listing outputs as the object is
promoted up the hierarchy. For example, PL/1 with DB2 produces one output
from the PL/1 preprocessor step and two from the DB2 preprocessor step and
one more from the PL/1 compile step.
As these outputs reach a certain level in the hierarchy, you may want to discard
the PL/1 preprocessor listing and one of the ones from the DB2 preprocessor.
At a certain level of the hierarchy, these listing variations have no further value.
The main reason for this is reduction of the DASD required to store and contain
a very large project.
One way around this problem would be to change your translators so that SCLM
doesn't even manage the listing data sets? You could use COPY and PURGE
Chapter 19. Optimization

245

translators for the source to move the listings along the levels you wanted the
listings for. Then when you promoted higher, the last PURGE would eliminate
the unwanted listings.
So if you had a hierarchy like:
RELEASE
|
SVT
|
FVT
|
EUT
+-------|-------+
DEV1
DEV2
DEV3

and you didn't want the listings after FVT, then you could have DEV1, DEV2,
DEV3, EUT and FVT LISTING data sets. You change the BUILD translator to use
them instead of KEYREF=OUTx data sets and provide COPY and PURGE
translators that are sensitive to the promotion level.

19.1.12 VSAM Maintenance


Execute a LISTCAT of the SCLM VSAM accounting data set. For help on how to
execute LISTCAT under TSO, enter HELP LISTCAT (from within ISPF enter TSO
HELP LISTCAT).
Under DATA, look for the CA-SPLIT statistics. Rule of thumb: if data CA-splits is
10 or more, you should reorganize via REPRO.
CI-splits are relatively harmless. CA-splits cause data to be stored out of
sequence which can hurt performance. Also, vast stretches of DASD could be
dead space; a reorg will reclaim space.
It is recommended that you place your VSAM accounting data set on a cached
DASD controller (for example, on a 3889-23 or a 3990-3) and make sure that its
SMS management class specifies that it can use the read only DASD cache.
Because of all the index set IO's, SCLM has a very high read to write ratio, and
the use of a read cache will make SCLM sing.
If the VSAM accounting data set is cached, make sure that you specify NOIMBED
and NOREPLICATE since you want to pack data as tightly as possible into the
cache.
Also, try to minimize CI-splits. The cost of a CA-split can be hundreds of IOs.
FREESPACE (0 60) should perform better for most folks while wasting less DASD.
A way to determine this is to reorganize your SCLM accounting data set and
then let it be used for a considerable period of time (2 weeks?). Then run
LISTCAT and see how many CI-SPLITS and how many CA-SPLITS. Reorganize
the VSAM accounting data set but set FREESPACE(0 60) and then let it be used
again for an equal period of time. Then run LISTCAT and compare CI-SPLITS
and CA-SPLITS. If the CA-SPLITS are less and the CI-SPLITS are not t o o much
higher then stick with your FREESPACE. Otherwise, adjust your FREESPACE
values until you achieve an optimum.
Leave the data and index CI sizes alone. Larger CI sizes will make direct VSAM
IOs less efficient.
Place the index and data on separate volumes.

246

ISPF/SCLM V4 Guide

Note: The algorithm was optimized with Release 3.4.

19.1.13 Create Dependencies for Calls


SCLM acknowledges and maintains all dependencies automatically through
parsing parts. This can be exploited, as seen in the following example:

19.1.13.1 Language Definition @CIC1CPY - Create Copy


***********************************************************************
*
COBOL/VS COPY with CICS Preprocessor
***********************************************************************
CIC1CPY FLMSYSLB
CICS31.COBLIB
FLMLANGL
LANG=CIC1CPY,VERSION=CPY10V00
*
FLMTRNSL CALLNAM='SCLM COBOL PARSE',
C
FUNCTN=PARSE,
C
COMPILE=FLMLPCBL,
C
PORDER=1,
C
OPTIONS=(@@FLMLIS,@@FLMSTP,@@FLMSIZ,@@FLMPRJ,
C
@@FLMGRP,@@FLMTYP,@@FLMMBR,)
*
(* SOURCE *)
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMPRJ.@@FLMGRP.@@FLMTYP(@@FLMMBR)
*
* BUILD TRANSLATOR(S)
*
*
- CICS PRECOMPILE FLMTRNSL CALLNAM='CICS PRE-COMPILE',
C
FUNCTN=BUILD,
C
COMPILE=DFHECP1$,
C
DSNAME=CICS31.LOADLIB,
C
VERSION=2.1,
C
GOODRC=4,
C
PORDER=1,
C
PARMKWD=PARM1,
C
OPTIONS=(LANGLVL(2),NOSOURCE,NOSEQ,CICS,DLI)
* 1
(* SYSIN *)
FLMALLOC IOTYPE=S,KEYREF=SINC,RECFM=FB,LRECL=80,
C
DDNAME=SYSIN
* 2
(* SYSPUNCH *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,KEYREF=OUT1,
C
RECNUM=4000,DDNAME=SYSPUNCH,PRINT=Y
* 3
(* SYSPRINT *)
FLMALLOC IOTYPE=O,KEYREF=OUT2,RECFM=FBA,LRECL=121,
C
RECNUM=5000,PRINT=Y,DDNAME=SYSPRINT

19.1.13.2 Archdef to Create COPY from EXEC CICS


SINC WEFP023P SOURCE
OUT1 WEFP023 SOURCE
OUT2 WEFP023P LIST

19.1.13.3 Input Part WEFP023P Associated with Language CIC1CPY


WEFP023 Section.
EXEC CICS XCTL PROGRAM(A-PROGRAM)
COMMAREA(CO-AREA) LENGTH(KCLKBPB) END-EXEC.
WEFP023-99.
GOBACK.
WEFP023-EX. EXIT.

19.1.13.4 Output Part WEFP023 from Language CIC1CPY after


Build
*
*

WEFP023 Section.
EXEC CICS XCTL PROGRAM(A-PROGRAM)
COMMAREA(CO-AREA) LENGTH(KCLKBPB) END-EXEC.
CALL 'DFHEI1' USING DFHEIV0 A-PROGRAM CO-AREA KCLKBPB.
WEFP023-99.
GOBACK.
WEFP023-EX. EXIT.

Chapter 19. Optimization

247

19.1.13.5 Invocation COPY Member


A program contains, for example, a 'COPY WEFP023', which outlines the ability
to transient any CICS command or command suite in a copy.

19.2 Language with CICS Preprocessor and Compile List Packing


The following sections contain various definition examples covering this topic.

19.2.1 Architecture Definition Examples


19.2.1.1 HL Part AQQQQQQQ
INCL LQQQQQQQ ARCHDEF

* LEC ARCHDEF (for CICS)

19.2.1.2 LEC Part LQQQQQQQ for Target Environment CICS


LKED
CMD
CMD
INCL
LOAD
LMAP

LKEDC
INCLUDE SYSLIB(DFHELII)
ENTRY CEESTART
MQQQQQQQ ARCHDEF
QQQQQQQ LOADCICS
QQQQQQQ LMAPCICS

* LEC ARCHDEF F. C/370 PRELINK


* OUTPUT LOAD MODUL
*
* OUTPUT BINDER LISTING
*

19.2.1.3 LEC Part MQQQQQQQ for C/370 Prelink (CICS)


LKED
INCL
*--*NCL
*NCL
*--LOAD

CPRLK
QQQQQQQ ARCHDEF
P...... ARCHDEF
P...... ARCHDEF

* CC ARCHDEF F. OBJCICS
* LINKED C MODULES:
*
CC ARCHDEF
*
CC ARCHDEF

QQQQQQQ PRLKCICS

* OUTPUT PRELINKED MODUL

19.2.1.4 CC Part QQQQQQQ for Target Environment CICS


SINC QQQQQQQ C
OBJ QQQQQQQ OBJCICS
LIST QQQQQQQ COMPCICS

* SOURCE MODUL
* OUTPUT OBJECT MODUL
* OUTPUT COMPILER LISTING

*
*
*

19.2.2 Language Definition @LKEDC - Binder for CICS


***====================================================================
*** SCLM LANGUAGE DEFINITION "LKEDC"
***
BINDER FOR CICS
***====================================================================
FLMLANGL LANG=LKEDC,CANEDIT=N,VERSION=V1.0
***********************************************************************
* BUILD TRANSLATOR:
*---------------------------------------------------------------------*
- BINDER *---------------------------------------------------------------------FLMTRNSL CALLNAM='LINK-CICS',
C
FUNCTN=BUILD,
C
COMPILE=IEWL,
C
VERSION=V1.0,
C
GOODRC=0,
C
PORDER=3,
C
OPTIONS=(LIST,XREF,LET,RENT)
*......................................................................
*
DDNAME ALLOCATION USING DDNAME-SUBSTITUTION:
* 1
(* SYSLIN *)
FLMALLOC IOTYPE=S,KEYREF=SINC,DDNAME=SYSLIN,RECNUM=20000
* 2
(* LOAD MODULE NAME *)
FLMALLOC IOTYPE=L,KEYREF=LOAD
* 3
(* SYSLMOD *)
FLMALLOC IOTYPE=P,DDNAME=SYSLMOD,KEYREF=LOAD,LANG=LOADC,
C
RECFM=U,RECNUM=500
* 4
(* SYSLIB *)
FLMALLOC IOTYPE=A,DDNAME=SYSLIB
FLMCPYLB CICS.P.SDFHLOAD
FLMCPYLB SYS1.COB2CICS
FLMCPYLB SYS1.COB2LIB
FLMCPYLB SYS1.DB2.LINKLIB
FLMCPYLB PLI.PLIBASE
FLMCPYLB PLI.SIBMBASE

248

ISPF/SCLM V4 Guide

FLMCPYLB
FLMCPYLB
* 5
FLMALLOC
* 6
FLMALLOC

EDC.SEDCBASE
IMSA.RESLIB
(* N/A *)
IOTYPE=N
(* SYSPRINT *)
IOTYPE=O,DDNAME=SYSPRINT,KEYREF=LMAP,LANG=LMAPC,
C
RECFM=FBA,LRECL=121,RECNUM=2500,PRINT=Y
* 7
(* N/A *)
FLMALLOC IOTYPE=N
* 8
(* N/A *)
FLMALLOC IOTYPE=N
* 9
(* N/A *)
FLMALLOC IOTYPE=N
* 10
(* N/A *)
FLMALLOC IOTYPE=N
* 11
(* N/A *)
FLMALLOC IOTYPE=N
* 12
(* SYSTERM *)
FLMALLOC IOTYPE=A,DDNAME=SYSTERM
FLMCPYLB NULLFILE
***=================================================================***

19.2.3 Language Definition @CPRLK - C Prelink


***====================================================================
*** SCLM LANGUAGE DEFINITION "CPRLK"
***
C PRELINK
***====================================================================
FLMLANGL
LANG=CPRLK,CANEDIT=N,VERSION=V1.0
***********************************************************************
* BUILD TRANSLATOR:
*---------------------------------------------------------------------*
- C PRELINK *---------------------------------------------------------------------FLMTRNSL CALLNAM='C370-PRELINK',
C
FUNCTN=BUILD,
C
COMPILE=EDCPRLK,
C
VERSION=V1.0,
C
GOODRC=4,
C
PORDER=1,
C
OPTIONS=(NCAL,NOER)
*......................................................................
*
(* SYSIN
* INPUT FILE = OBJECT MODULE(S) *)
FLMALLOC
IOTYPE=S,KEYREF=SINC,DDNAME=SYSIN,RECNUM=20000
*
(* SYSMOD * OUTPUT FILE = PRELINKED MODULE *)
FLMALLOC
IOTYPE=O,KEYREF=LOAD,RECFM=FB,LRECL=80,RECNUM=20000,
C
DDNAME=SYSMOD,DFLTTYP=PRLKCICS,LANG=PRELINK
*
(* SYSOUT * PRELINK LISTING
*)
*
(*
* LRECL=80,RECFM=F/FB
*)
FLMALLOC
IOTYPE=W,DDNAME=SYSOUT,PRINT=Y
*
(* SYSPRINT * PRELINK DIAGNOSTIC MESSAGES
*)
*
(*
* LRECL=137,RECFM=VBA,BLKSIZE=882 *)
FLMALLOC
IOTYPE=W,DDNAME=SYSPRINT,PRINT=Y
*
(* SYSLIB * AUTOCALL LIBRARY
*)
FLMALLOC
IOTYPE=A,DDNAME=SYSLIB
FLMCPYLB
NULLFILE
*
(* SYSMSGS * PRELINK MESSAGE DATA SET
*)
FLMALLOC
IOTYPE=A,DDNAME=SYSMSGS
FLMCPYLB
EDC.SEDCMSGS(EDCPMSGE)
***=================================================================***

19.2.4 Language Definition @CCP - C Precompile/CICS


Translate/Compile/Pack
***====================================================================
*** SCLM LANGUAGE DEFINITION "CCP"
***
C-PRECOMPILE/CICS TRANSLATE/COMPILE/PACK
***====================================================================
CCP
FLMSYSLB EDC.SEDCHDRS
FLMSYSLB CICS.SDFHC370
FLMLANGL LANG=CCP,VERSION=V1.0
***********************************************************************
* PARSER TRANSLATOR:
*---------------------------------------------------------------------FLMTRNSL CALLNAM='C370 PARSER',
C
FUNCTN=PARSE,
C
COMPILE=FLMLSS,
C
PORDER=1,
C
OPTIONS=(PTABLEDD=,
C
SOURCEDD=SOURCE,
C
TBLNAME=FLMPC370,
C

Chapter 19. Optimization

249

STATINFO=@@FLMSTP,
C
LISTINFO=@@FLMLIS,
C
LISTSIZE=@@FLMSIZ,
C
CONTIN=0,
C
EOLCOL=72)
*
(* SOURCE
*)
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMPRJ.@@FLMGRP.@@FLMTYP(@@FLMMBR)
**********************************************************************
* BUILD TRANSLATORS:
*---------------------------------------------------------------------* (1)
- C/370 PREPROCESSOR COMPILER PHASE *---------------------------------------------------------------------FLMTRNSL CALLNAM='C370-PREPROC',
C
FUNCTN=BUILD,
C
COMPILE=EDCCOMP,
C
VERSION=1.0,
C
PARMKWD=PARM0,
C
GOODRC=3,
C
PORDER=3,
C
OPTIONS=(NOSEQ,PPONLY)
*......................................................................
*
DDNAME ALLOCATION USING DDNAME-SUBSTITUTION:
* 01
(* SYSIN * SOURCE INPUT *)
FLMALLOC IOTYPE=S,KEYREF=SINC,RECFM=VB,LRECL=136,
C
RECNUM=20000,DDNAME=XYSIN
* 02
(* SYSLIN * OBJECT MODUL *)
FLMALLOC IOTYPE=A,DDNAME=XYSLIN
FLMCPYLB NULLFILE
* 03
(* SYSMSGS * C-COMPILER MESSAGE DATA SET *)
FLMALLOC IOTYPE=A,DDNAME=SYSMSGS
FLMCPYLB EDC.SEDCMSGS(EDCMSGE)
* 04
(* SYSLIB * SYSTEM INCLUDE FILES = #INCLUDE <...> *)
FLMALLOC IOTYPE=A,DDNAME=SYSLIB
FLMCPYLB EDC.SEDCHDRS
FLMCPYLB CICS.SDFHC370
* 05
(* USERLIB * USER INCLUDE FILES = #INCLUDE "..." *)
FLMALLOC IOTYPE=I,DDNAME=USERLIB,KEYREF=SINC
* 06
(* SYSPRINT * COMPILER GENERATED ERROR MESSAGES *)
FLMALLOC IOTYPE=W,DDNAME=XYSPRINT,PRINT=Y
* 07
(* SYSCPRT * COMPILER OUTPUT LISTING *)
FLMALLOC IOTYPE=W,DDNAME=XYSCPRT,PRINT=Y
* 08
(* SYSPUNCH * OBJECT MODUL, NICHT BENOETIGT WEGEN PPONLY *)
FLMALLOC IOTYPE=A,DDNAME=XYSPUNCH
FLMCPYLB NULLFILE
* 09
(* SYSUT1 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=XYSUT1
* 10
(* SYSUT4 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=XYSUT4
* 11
(* SYSUT5 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=XYSUT5
* 12
(* SYSUT6 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=XYSUT6
* 13
(* SYSUT7 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=XYSUT7
* 14
(* SYSUT8 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=XYSUT8
* 15
(* SYSUT9 *)
FLMALLOC IOTYPE=W,RECFM=VB,LRECL=137,RECNUM=2000,DDNAME=XYSUT9
* 16
(* SYSUT10 * PASS C-PREPROCESSOR OUTPUT *)
*
(*
* TO CICS TRANSLATOR
*)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=50000,DDNAME=XYSUT10
*---------------------------------------------------------------------* (2)
- CICS TRANSLATOR *---------------------------------------------------------------------FLMTRNSL
CALLNAM='CICS TRANSLATE C',
C
FUNCTN=BUILD,
C
COMPILE=DFHEDP1$,
C
DSNAME=CICS.P.SDFHLOAD,
C
VERSION=V1.0,
C
PARMKWD=PARM9,
C
GOODRC=0,
C
PORDER=3,
C
OPTIONS=(MAR(1,72,0),NSEQ)
*......................................................................
*
DDNAME ALLOCATION USING DDNAME-SUBSTITUTION:
* 01
(* N/A *)
FLMALLOC IOTYPE=N
* 02
(* N/A *)
FLMALLOC IOTYPE=N
* 03
(* N/A *)
FLMALLOC IOTYPE=N
* 04
(* N/A *)

250

ISPF/SCLM V4 Guide

FLMALLOC IOTYPE=N
* 05
(* SYSIN * CICS TRANSLATOR INPUT PASSED FROM *)
*
(*
* C COMPILER PREPROCESSOR PHASE
*)
FLMALLOC IOTYPE=U,DDNAME=XYSUT10
* 06
(* SYSPRINT * CICS TRANSLATOR LISTING *)
FLMALLOC IOTYPE=W,DDNAME=YYSPRINT,RECFM=FBA,
C
LRECL=121,RECNUM=20000,PRINT=Y
* 07
(* SYSPUNCH * PASS CICS TRANSLATOR OUTPUT TO C-COMPILER *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=50000,DDNAME=YYSPUNCH
*---------------------------------------------------------------------* (3)
- C/370 COMPILE *---------------------------------------------------------------------FLMTRNSL CALLNAM='C370-COMPILE',
C
FUNCTN=BUILD,
C
COMPILE=EDCCOMP,
C
VERSION=1.0,
C
PARMKWD=PARM1,
C
GOODRC=4,
C
PORDER=3,
C
OPTIONS=(AGG,CHE(ALL),EXP,FL(I),LANG(ANSI),LO,
C
MAR(1,72),MEM,OPT(1),RENT,NOSEQ,SHOW,SO,SS,XR)
*......................................................................
*
DDNAME ALLOCATION USING DDNAME-SUBSTITUTION:
* 01
(* SYSIN * COMPILER INPUT PASSED *)
*
(*
* FROM CICS TRANSLATOR *)
FLMALLOC IOTYPE=U,DDNAME=YYSPUNCH
* 02
(* SYSLIN * OBJECT MODUL, IF COMPILE WITH OPTION "OBJECT" *)
FLMALLOC IOTYPE=O,KEYREF=OBJ,RECFM=FB,LRECL=80,
C
RECNUM=50000,DDNAME=SYSLIN,DFLTTYP=OBJCICS,LANG=OBJCC
* 03
(* SYSMSGS * C-COMPILER MESSAGE DATA SET *)
FLMALLOC IOTYPE=A,DDNAME=SYSMSGS
FLMCPYLB EDC.SEDCMSGS(EDCMSGE)
* 04
(* SYSLIB * SYSTEM INCLUDE FILES = #INCLUDE <...> *)
FLMALLOC IOTYPE=A,DDNAME=SYSLIB
FLMCPYLB EDC.SEDCHDRS
FLMCPYLB CICS.SDFHC370
* 05
(* USERLIB * USER INCLUDE FILES, DONE IN PPONLY PHASE *)
FLMALLOC IOTYPE=A,DDNAME=USERLIB
FLMCPYLB NULLFILE
* 06
(* SYSPRINT * COMPILER GENERATED ERROR MESSAGES *)
FLMALLOC IOTYPE=W,DDNAME=SYSPRINT,PRINT=Y
* 07
(* SYSCPRT * COMPILER OUTPUT LISTING PASSED TO PACK TRL. *)
FLMALLOC IOTYPE=W,DDNAME=SYSCPRT,RECNUM=50000,
C
RECFM=VBA,LRECL=137,PRINT=Y
* 08
(* SYSPUNCH * OBJECT MODUL, IF COMPILE WITH OPTION "DECK" *)
FLMALLOC IOTYPE=A,DDNAME=SYSPUNCH
FLMCPYLB NULLFILE
* 09
(* SYSUT1 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=SYSUT1
* 10
(* SYSUT4 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=SYSUT4
* 11
(* SYSUT5 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=SYSUT5
* 12
(* SYSUT6 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=SYSUT6
* 13
(* SYSUT7 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=SYSUT7
* 14
(* SYSUT8 *)
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=2000,DDNAME=SYSUT8
* 15
(* SYSUT9 *)
FLMALLOC IOTYPE=W,RECFM=VB,LRECL=137,RECNUM=2000,DDNAME=SYSUT9
* 16
(* SYSUT10 *)
FLMALLOC IOTYPE=A,DDNAME=SYSUT10
FLMCPYLB NULLFILE
*---------------------------------------------------------------------*
- PACK COMPILER LISTING *---------------------------------------------------------------------FLMTRNSL
CALLNAM='PACK-LIST C',
C
FUNCTN=BUILD,
C
COMPILE=SCLMISP,
C
CALLMETH=LINK,
C
VERSION=V1.0,
C
GOODRC=0,
C
PORDER=1,
C
OPTIONS='%MET#B01 SYSCPRT,,PACKLIST,,PACK'
*
(REXX MET#B01 COPIES LISTING WITH LM-SERVICES )
*
(TO SCLM LIST DATA SET IN PACKED FORMAT.
)
*......................................................................
*
DDNAME ALLOCATION:
FLMALLOC
IOTYPE=U,DDNAME=SYSCPRT
FLMALLOC
IOTYPE=O,DDNAME=PACKLIST,KEYREF=LIST,RECNUM=50000,
C
RECFM=FBA,LRECL=133,DFLTTYP=COMPCICS,LANG=COMPCC
***====================================================================

Chapter 19. Optimization

251

252

ISPF/SCLM V4 Guide

Chapter 20. Workstation Connection


This chpater discusses various ways to connect a programmable workstation to
an SCLM session.

20.1 Workstation for OS/2


ISPF/PDF Version 3.1 already included a Workstation for OS/2 feature, which can
no longer be operated with Version 4.1, and has consequently been purged.

20.2 AD/Cycle WorkStation Platform/2


WSP/2 succeeded workstation for OS/2 but was no longer pursued in favor of
LAN library development. In some countries a major discount is offered (up to
70% for a package buy of 6). This makes this product (mainly it's SCLM interface
Library List) still attractive for a transient period of time until an integration of
distributed edit and build is achieved.
WorkStation Platform/2 provides services for three types of users:
Tool builders
WorkStation Platform/2 provides a set of APIs that serve as a base for
integrating workstation tools or host tools. Tool builders can use these APIs
to build tools that access WSP/2 services or to register their tools. Once
registered, these tools appear on the WSP/2 Main Window, and WSP/2 users
can invoke them.
Application developers
Application developers can develop either host- or workstation-based
applications. Using a set of tools designed to help them increase their
productivity, developers select the tools from the WSP/2 Main Window on the
basis of their application development activities.
End users
End users can access WSP/2 through the Main Window.

20.2.1 New Functions with Release 1.2


WorkStation Platform/2 1.2 introduced new functions to the product and also
changed some of the existing functions. Changed functions include:
Installation and maintenance utility
Service manager
Terminology
Mapping file
New functions:
Text editor

Although available in the product, it seems not advisable to be used.

Copyright IBM Corp. 1994

253

20.2.1.1 Installation and Maintenance Utility


The changes to the installation and maintenance utility include changes to the
windows and also the possibility to install products from diskette. When you
install a product from the Action pull down, you will be prompted for input.

20.2.1.2 Service Manager


Because this release of WorkStation Platform/2 supports the connection to other
than SCLM library managers, the system access option in the options pulldown
had to be extended. You now have to specify:
Systems

MVS or VM

Libraries

SCLM (host)

Projects

MYPROJ1 or MYPROJ2.

If you are working with the MVS-SRPI connection, you now have the freedom to
choose the server alias names. These names are no longer restricted to
EHORUNS and EHOXFER. This allows you to setup SRPI profiles for all host
sessions you want to use, and switch between those sessions without the need
to bring down OS/2 communications manager.

20.2.1.3 Mapping File


When connecting WorkStation Platform/2 to an SCLM 3.4 library on the , the
host mapping files, EPFMAPM.DAT and EPFMAPV.DAT, are no longer required.
The parameters that are coded in those two files must now be coded in the
SCLM project definition and WorkStation Platform/2 will retrieve them to a
workstation file project definition.PRV in the work directory (EPFWORKDIR)
when the project is defined.
The mapping files are still required when working with pre-SCLM 3.4 releases.

20.3 ISPF Version 4.1 Client/Server Front End


The Client/Server interface has been discussed in detail in the previous chapters
of this document.
Due to the protocol used (TCP/IP or APPC), products that use another protocol
(for example CODE/370 R1.2 workstation feature) cannot integrally be used
together with this release of ISPF C/S.

20.4 LAN Library


With the May 24th '94 application development announcement, a statement of
direction was given, pointing out that future application development is likely to
move to a workstation managed library system.
Although we believe in the huge potentials of a LAN library centric view, we
would like to take the opportunity to pinpoint a few facts:
The application decides the development environment. For a transient
period, applications may be maintained in an orderly fashion.

254

ISPF/SCLM V4 Guide

To prepare for LAN library migration


To exercise software configuration BUILD techniques; the comfortable
and easy-to-accept part of library management systems
To understand host-based applications

To implement a multi-baseline test environment


To migrate applications to a higher evolution compiler
To prepare applications for redevelopment by cutting them to pieces,
which makes a library management system mandatory

SCLM will remain a nonextra-fee component in ISPF to enable software


configuration and library management in a centric library view.
Storing workstation applications in SCLM provides several benefits:

SCLM can be used as a single point of access for the workstation code.
Application source, executables, and outputs can be protected and
backed-up using the host.
SCLM's configuration management can be used to ensure that the
application is current.
Library management and versioning capabilities can be used to track the
application parts through the hierarchy and retain backup versions.

Chapter 20. Workstation Connection

255

256

ISPF/SCLM V4 Guide

Chapter 21. Diskette Material


All material used for this workshop is contained on the enclosed diskette. For
your convenience we put an overview of parts in this section.

21.1.1 Project Definitions

SCLM41.PRIVDEFS.PROJECTS - HIERARCHY VIEW Command ===>

Member
Status
-------- ----------$TYPES
FLM##PD
FLM1#PD
FLM3#PD
FLM8#PD
FLM9#PD
MET##PD
MET#ALT1
MET#ALT2
MET#ALT3
MET#ALT4
MET#ATV
MET#CNT1
MET#CNT2

Account
-------PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS

21.1.2 Language Definitions

SCLM41.PRIVDEFS.METHODS

Chg Date
-------94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/28
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/08/02

Chg Time
-------14:31:00
16:36:00
16:41:00
16:41:00
16:42:00
16:50:00
13:35:00
11:51:00
11:52:00
11:50:00
16:52:00
09:23:00
09:27:00
16:22:00

- HIERARCHY VIEW -

Command ===>

Copyright IBM Corp. 1994

Member
Status
-------- ----------@ASMHRC4
@ASMPRJ
@ASMPRJT
@CCP
@CIC1CPY
@COPY1
@LANG
@LKEDC
@LKEDPRJ
@PRLK
FLM$BOOK
FLM$COB2
FLM@ASMH
FLM@BOOK
FLM@L370

Account
-------PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS

Chg Date
-------94/07/19
94/08/02
94/08/02
94/07/25
94/07/26
94/07/25
94/07/28
94/07/25
94/08/03
94/07/25
94/08/02
94/07/22
94/08/02
94/08/02
94/08/02

Chg Time
-------09:50:00
13:00:00
15:01:00
15:10:00
09:27:00
14:28:00
16:45:00
15:09:00
14:04:00
15:09:00
16:26:00
10:46:00
16:48:00
16:49:00
16:49:00

Row 1 to 14 of 26
Scroll ===> PAGE
Language
-------ASMH
ASMHRC4
ASMHRC4
ASMHRC4
ASMHRC4
ASMHRC4
ASMHRC4
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH

Bld Map
------PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS

Row 6 to 20 of 22
Scroll ===> PAGE
Language
-------ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH
ASMH

Authcode
-------SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM

257

21.1.3 REXX Programs

SCLM41.PRIVDEFS.REXX - HIERARCHY VIEW Command ===>


Member
Status
-------- ----------BUILDX1
BUILDX1C
DUMMY
MET#B01
MET#B02
MET#CCV1
MET#PRE
MET#P11
MET#P12
MET#P21
MET#SAVE
MET#SND1
MET#XREF
SCLMAPND

Account
-------PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS

21.1.4 Assembler Programs

SCLM41.PRIVDEFS.ASM

Chg Date
-------94/07/28
94/07/28
94/07/21
94/07/28
94/08/02
94/07/28
94/07/28
94/07/28
94/07/28
94/08/03
94/07/28
94/07/28
94/08/01
94/07/29

Chg Time
-------14:03:00
14:03:00
15:55:00
14:03:00
15:19:00
14:03:00
14:04:00
14:04:00
14:04:00
15:39:00
14:04:00
14:04:00
11:41:00
13:59:00

- HIERARCHY VIEW -

Command ===>

21.1.5 Job Control

SCLM41.PRIVDEFS.JCL - HIERARCHY VIEW Command ===>

258

ISPF/SCLM V4 Guide

Language
-------REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX
REXX

Authcode
----SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM

Row 1 to 1 of 1
Scroll ===> PAGE

Member
Status
Account Chg Date Chg Time Language Authcode
-------- ----------- -------- -------- -------- -------- ----SCLMISP
PROJDEFS 94/08/03 16:08:00 ASMH
SCLM

Row 1 to 14 of 15
Scroll ===> PAGE

Member
Status
-------- ----------FLM#01PA
FLM#02PV
FLM#03PD
JOBCARD
MET#01PA
MET#02PV
MET#03PD
MET#04CL
M3L#01PA
M3L#02PV
M3L#03PD
M3L#04CL
SCLMJOB

Account
-------PROJDEFS
PROJDEFS
PROJDEFS
PRIVDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS

Chg Date
-------94/08/03
94/08/03
94/08/03
94/07/18
94/08/03
94/08/03
94/08/03
94/08/03
94/08/03
94/08/03
94/08/03
94/08/03
94/08/03

Chg Time
-------16:05:00
16:06:00
16:06:00
09:51:00
16:06:00
16:06:00
16:06:00
16:06:00
16:07:00
16:07:00
16:07:00
16:07:00
16:07:00

Row 1 to 13 of 13
Scroll ===> PAGE
Language
-------TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT
TEXT

Authcode
----SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM

21.1.6 Architecture Definitions

SCLM41.PRIVDEFS.ARCHDEF

- HIERARCHY VIEW -

Command ===>

Member
Status
-------- ----------#ALVIEWS
AQQQQQQQ
ASMPROJ
AS9200
FLM#
FLM##H
FLM##L
FLM1#H
FLM1#L
FLM3#H
FLM3#L
FLM8#H
FLM8#L
FLM9#H
FLM9#L
LQQQQQQQ

Account
-------PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS
PROJDEFS

Chg Date
-------94/08/04
94/07/20
94/08/03
94/08/03
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/22
94/07/20

Chg Time
-------08:43:00
09:51:00
15:37:00
16:04:00
16:34:00
10:38:00
10:38:00
10:38:00
10:38:00
10:36:00
10:38:00
10:39:00
10:39:00
10:39:00
10:39:00
09:49:00

Row 1 to 16 of 29
Scroll ===> PAGE
Language
-------ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF
ARCHDEF

Authcode
----SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM
SCLM

21.1.7 FOILS in LIST3820 Format


The foils can be printed from the diskette file SCLMFOIL.LIST3820 . A printout in
smaller format can be found in Chapter Chapter 26, Workshop Foils on
page 285.

Chapter 21. Diskette Material

259

260

ISPF/SCLM V4 Guide

Chapter 22. Standards


22.1.1 ANSI/IEEE
Software Requirements Specification, IEEE STD 830-1984
Software Quality Assurance, ANSI/IEEE STD 730.1-1988
IEEE Guide for Software Quality Assurance Planning, IEEE STD 983-1986
Software Configuration Management Plans, IEEE STD 828-1990
Guide to Software Configuration Management, IEEE STD 1042-1987
Software Reviews and Audits, IEEE STD 1028-1988
Software Test Documentation, IEEE STD 829-1983, and Software Unit Testing,
IEEE STD 1008-1987
Software Project Management Plans, IEEE STD 1058.1-1987
Software Verification and Validation Plans, IEEE STD 1012-1986
Also consider MIL-STD-2167A (United States Department of Defense).

22.1.2 ISO9000
To facilitate the standardization of the many aspects of quality, the International
Organization for Standardization (ISO) has developed a set of international
standards for quality systems, which are known as the ISO 9000 Series of Quality
Standards. These standards apply to all organizations producing a product or
service and are being accepted wordwide. An indication of their acceptance and
significance in the software engineering industry, in particular, is reflected in
Hubner's words: To obtain an ISO 9000 certification has become a business
necessity in Europe It is only a matter of time before ISO 9000 certification
becomes a business necessity in North America and the Orient.
The key ISO 9000 standards are:
ISO 9001, Quality systems - Model for quality assurance in design /
development production, installation and servicing
ISO 9002, Quality systems - Model for quality assurance in production and
installation
ISO 9003, Quality systems - Model for quality assurance in final inspection
and test
ISO 9001 provides the most comprehensive requirements for a software quality
system where a contractual agreement between two parties must demonstrate
the supplier's capability to design and supply a product or service.
Recognizing the peculiarities of the software industry, ISO 9000-3, a guideline for
the application of ISO 9001 to the development, distribution and maintenance of
software, has been released. Configuration management is a key element within
this ISO 9000-3 guideline for software.

Copyright IBM Corp. 1994

261

262

ISPF/SCLM V4 Guide

Chapter 23. SCLM Translator Interfaces


This topic assists the experienced SCLM (Software Configuration and Library
Manager) user in attaching tools of choice to the SCLM project definition. These
tools, called translators in SCLM, include compilers, linkage editors, text
processors, preprocessors, and test tools. The SCLM interface to translators is
described in detail with a description of the parameter list passed by SCLM to a
translator, examples of language definitions with and without the use of ddname
substitution lists, and the use of IKJEFTSR for translators that need a special
environment. This information will assist the experienced SCLM user in
sophisticated use of existing translators, modification of translators for use in
SCLM projects, and using the SCLM interface for new translators.

23.1.1.1 ITIRC KEYWORDS


Ddname substitution list
IKJEFTSR
SCLM
SCLM migration
Software Configuration and Library Manager
Translator
TSO Service Routine

23.1.2 Before We Begin


This report is written for the SCLM user who needs to write translators and
language definitions. The user should be skilled in the use of language
definitions supplied with SCLM and in modifying them to meet the needs of
application developers. Knowledge of the FLMALLOC macro, DDNAME keyword,
and the IOTYPE keyword is required. The user should also be able to modify,
assemble, and link-edit SCLM project definitions. Programming and JCL skills
will be helpful in writing and using translators.
Programmers and project leaders involved in migrating an existing application to
SCLM libraries may find this information helpful. This information may also be
helpful for establishing new applications under SCLM library controls.

23.1.3 Basic Skills


This section will describe how translators are specified with the FLMTRNSL
macro for invocation by SCLM. Comparisons to JCL will help illustrate these
points and also demonstrate migration considerations for existing projects. This
is a review for the SCLM user who has not been actively involved in writing
language definitions.

23.1.4 FLMTRNSL Macro


The FLMTRNSL macro is similar to a JCL EXEC statement. The EXEC statement
specifies a load module to execute with the PGM keyword, whereas the
FLMTRNSL macro specifies a translator with the COMPILE keyword. COMPILE is
a misnomer in that the translators are not restricted to compilers.

Copyright IBM Corp. 1994

263

The order of JCL EXEC statements determines the order in which load modules
will be considered for execution. The same concept holds true for language
definitions in that the order of the FLMTRNSL macros in a language definition
determines the order in which the translators will be considered for execution.
See Figure 140 for a comparison of a JCL EXEC statement and and FLMTRNSL
macro.

JCL:
//STEP1 EXEC PGM=IEFBR14
FLMTRNSL:
FLMTRNSL COMPILE=IEFBR14,FUNCTN=BUILD,PORDER=0
Figure 140. IEFBR14 as a Translator. This example compares JCL with the FLMTRNSL
macro.

Note the keywords used for the FLMTRNSL macro:


COMPILE - like PGM in JCL, it specifies the entry point name on the
translator load module or the REXX program.
FUNCTN - tells SCLM when to execute the translator.

PARSE - during SCLM migration utility or a save in an edit session

VERIFY - during SCLM BUILD and PROMOTE verification

BUILD - during SCLM BUILD

COPY - before SCLM PROMOTE function copies the member to the next
library

PURGE - when SCLM deletes a member from a library

PORDER - parameter order to the translator.

0 - no parameters

1 - OPTIONS list without a ddname substitution list

2 - ddname substitution list without an options list

3 - OPTIONS list followed by a ddname substitution list

The FLMTRNSL macro OPTIONS keyword serves the same purpose as the JCL
EXEC statement PARM keyword. The ddname substitution list as well as the
parameter order detail will be covered later in this report.

23.1.5 Conditional Execution


At times we want the return code from the execution of a translator to determine
whether to execute or skip another translator. JCL provides an elaborate
mechanism to handle this task. SCLM only handles a subset of the situations
handled by JCL without the need for additional translators. This is one reason
why a simple migration from an existing application development environment to
SCLM may not be possible. Additional translators may need to be written in
order to provide an equivalent execution of the translators.
In Figure 141 on page 265 there are two translators to be executed: ABC and
XYZ. However, we do not want to execute XYZ if the return code from ABC is

264

ISPF/SCLM V4 Guide

greater than 4. This is a common situation when a nonzero return code


indicates an error condition.

JCL with COND:


//STEP1 EXEC PGM=ABC
//STEP2 EXEC PGM=XYZ,COND=(5,GE)
FLMTRNSL with GOODRC:
FLMTRNSL COMPILE=ABC,FUNCTN=BUILD,PORDER=0,GOODRC=4
FLMTRNSL COMPILE=XYZ,FUNCTN=BUILD,PORDER=0
Figure 141. Conditional Translator Execution. This example compares conditional
execution in JCL with the return code check in the FLMTRNSL macro.

Notice that the condition to continue execution with the next translator in the
language definition is specified on the FLMTRNSL macro for the translator that
may have a nonzero return code. This is in contrast to JCL in which the
condition for successful execution is specified on the next EXEC statement.
If a return code exceeds the value of GOODRC. then all of the translators which
follow in the language definition will be skipped. However, in JCL we can select
which programs to execute by using the COND keyword on any EXEC statement.
This provides a type of IF-THEN-ELSE logic to the control of execution in JCL
which cannot be duplicated with only the use of the GOODRC keyword.
This is the reason why there is not a one-to-one correspondence in the logic
used in JCL and that used in language definitions. Migration from an existing
application development environment which makes extensive use of JCL
conditional execution will require skilled translator work to provide an equivalent
function for SCLM.

23.1.6 TSO Address Space


SCLM executes in a TSO address space. This is true for the EXECUTE option as
well as the SUBMIT option on SCLM panels. The SUBMIT option appears at first
glance to be non-TSO since a job is submitted to the job queue. However, that
job contains a step for IKJEFT01 which is TSO. Therefore, even the SUBMIT
option of the SCLM panels results in translator execution in a TSO address
space.

23.1.7 CALLMETH
The FLMTRNSL macro CALLMETH keyword may be used to specify three
different ways of passing control to a translator:
ATTACH - default value, used for translator load modules.
LINK - used for translator load modules which require access to ISPF
variables or services.
TSOLNK - used for translator TSO commands, REXX programs, or CLISTs.
SCLM uses IKJEFTSR (TSO Service Routine) with link flags X'00010001' to
invoke the translator.
Not all translators may be successfully invoked by one of these three methods.
In those cases one needs an interface program that gets control from SCLM,
establishes a proper environment for the desired translator, and then passes

Chapter 23. SCLM Translator Interfaces

265

control to the desired translator. In these situations, it is the interface program


that is the true translator since it gets control from SCLM. An interface program
may establish an environment by using IKJEFTSR with the appropriate link flags
to pass control to the desired tool (load module, command, CLIST).
Examples of interface programs provided by SCLM are the translators FLMTMSI
for SCRIPT and FLMTMMI for DFSUNUB0. See Figure 142 for sample assembly
language code for using IKJEFTSR to execute a command with link flags
specified by the translator.

*
* LNKFLAGS, COMMAND, AND CMDLEN STORAGE AREAS NEED TO BE SET TO THE
* PROPER VALUES FOR THE DESIRED COMMAND BEFORE THE CALL TO IKJEFTSR
*
*
*
LOCATE IKJEFTSR AND EXECUTE THE COMMAND
*
L
1,CVTADDR
* ADDRESS OF THE CVT
L
1,CVTTVT(,1)
* ADDRESS OF THE TVT
L
R15,TSVTASF-TSVT(,1)
* ADDRESS OF IKJEFTSR
*
CALL (15),(LNKFLAGS,COMMAND,CMDLEN,RETCODE,RSNCODE,ABNDCODE), X
VL,MF=(E,CALLPRMS)
* CALL IKJEFTSR
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
* CONSTANTS
*
CVTADDR EQU 16
* ADDRESS OF THE CVT
CVTTVT EQU X'9C'
* OFFSET OF TVT POINTER IN CVT
*
LNKFLAGS DS
0F
* MODEL FLAGS FOR IKJEFTSR CALL
DC
X'00'
* MUST BE ZEROS
DC
X'01'
* UNAUTHORIZED ENVIRONMENT
DC
X'00'
* NO DUMP ON ABEND
DC
X'01'
* TSO CMD, REXX, CLIST
*
COMMAND DS
CL400
* COMMAND BUFFER
CMDLEN DS
F
* LENGTH OF COMMAND IN BUFFER
*
LNKPRMS DS
0F
* IKJEFTSR CALL RETURN PARAMETERS
RETCODE DS
F
* RETURN CODE FROM IKJEFTSR
RSNCODE DS
F
* REASON CODE FROM IKJEFTSR
ABNDCODE DS
F
* ABEND CODE FROM IKJEFTSR
*
CALLPRMS CALL ,(,,,,,,,,),MF=L
* PARM AREA FOR CALL MACRO
*
* TSO VECTOR TABLE NEEDED FOR TSVTASF AND TSVT
*
IKJTSVT DSECT
IKJTSVT
* TSO VECTOR TABLE

Figure 142. IKJEFTSR Sample Interface. This sample code calls IKJEFTSR to invoke a
command.

23.1.8 FLMALLOC
Most translators need input, ouput, and work data sets. These files are identified
by FLMALLOC macros which immediately follow the FLMTRNSL macro for
invocation of the translator. At run time, a TSO allocation is performed for each
of the files. This is why the macro is called FLMALLOC.
The JCL counterpart of the FLMALLOC macro is the data definition statement. In
general there will be one FLMALLOC macro for each ddname (data definition
name on a data definition statement) when one migrates a JCL application
development job stream to an SCLM language definition. This should not affect
the translator, and no reprogramming should be required.

266

ISPF/SCLM V4 Guide

23.1.9 DDNAME Substitution List


Ddname substitution lists are needed for effective use of SCLM. These lists are
needed when one translator would like to refer back to a different ddname used
in a previous translator. Referal back to a previous data definition statement in
a previous EXEC statement is a common practice in JCL.
The classic example is the situation in which translator ABC produces output in
a data set with ddname name OUTPUT, and translator XYZ needs this data set
for ddname INPUT. JCL does not require the ddnames to be the same for the
XYZ INPUT data definition statement to refer back to the ABC OUTPUT data
definition statement. However, the FLMTRNSL macro does require the ddnames
to be the same in order to refer back to a previous FLMALLOC macro.
In this classic example, the ddnames are different. One may use a ddname
substitution list in an SCLM language definition so that XYZ can refer back to
ddname OUTPUT from ABC and use it as ddname INPUT. This is a common
situation when converting existing JCL EXEC statements to FLMTRNSL macros
for migration to SCLM.
This is an important point. Ddname substitution lists are needed when one
translator needs to refer back to a different ddname for a previous translator.
Ddname substitution lists were not invented for SCLM. These structures have a
long history and may be used with many IBM products such as compliers,
linkage editors, and utilities. Outside of SCLM, they are not often encountered,
and it would be a safe bet that only one per cent of programmers have ever
used them outside of SCLM.
A ddname substitution list is a list of contiguous 8 byte values similar to a
parameter list. Products which use ddname substitution lists may document the
number and order of these values in a programming guide and reference. The
order is usually different for each product. Some of these values may be
ddnames generated by the operating system while others may be member
names or hexadecimal zeros.
Products which are programmed to use ddname substitution lists (IEBGENER,
IEV90) will examine the standard parameter list received from the caller to see if
a ddname substitution list has been passed. If no such list has been passed,
then the product will use the ddnames it was programmed to read and write
(SYSIN, SYSOUT). However, if such a list has been received, then the program
will use the ddnames in this list (usually generated by the system).
This is an important point. You can only use a ddname substitution list if the
translator has been programmed to use one. If you write a translator that will
use a ddname substitution list, then you need to use the parameter list SCLM
will be passing to the translator. The details of this parameter list will be
covered later in this document.
The examples which follow will review these points and lead us to the details of
the parameter list SCLM passes to translators.

Chapter 23. SCLM Translator Interfaces

267

23.1.10 Refer Back without DDNAME Substitution List


In Figure 143, there are two translators for the BUILD function: ABC and XYZ.
ABC writes output to ddname OUTPUT. XYZ uses the output from ABC to
produce a report. XYZ uses ddname OUTPUT for its input data set (which in this
case is the output from ABC). A ddname substitution list is not required since
ABC and XYZ use the same ddname (OUTPUT) for the data set of interest.

FLMTRNSL COMPILE=ABC,FUNCTN=BUILD,PORDER=0
FLMALLOC IOTYPE=S,DDNAME=INPUT,KEYREF=SINC
FLMALLOC IOTYPE=W,DDNAME=OUTPUT
FLMTRNSL COMPILE=XYZ,FUNCTN=BUILD,PORDER=0
FLMALLOC IOTYPE=U,DDNAME=OUTPUT
FLMALLOC IOTYPE=A,DDNAME=REPORT

Figure 143. Refer Back without DDname Substitution List. Both DDNAME keywords must
have the same value for a refer back.

IOTYPE=U tells SCLM to refer back to the prior translators in the language
definition until an FLMALLOC macro is located with DDNAME=OUTPUT. The
DDNAME keywords must match for the refer back to occur.

23.1.11 Refer Back with DDNAME Substitution List


It is rare that the ddnames for two translators will match. When they do not
match and a refer back is needed, one may use a ddname substitution list.
In Figure 144 on page 269, there are two translators for the BUILD function:
ABC and XYZ. ABC writes output to ddname OUTPUT. XYZ uses the output
from ABC as input data to produce a report. XYZ uses ddname RECIN for its
input data set. A ddname substitution list is required since ABC and XYZ use
different ddnames (OUTPUT and RECIN) for the data set of interest.
The specification for ABC shows that ABC has been programmed to use a
ddname substitution list. The specification states that this list consists of three 8
byte values: one for the OUTPUT ddname, one that is not applicable, and one
for the INPUT ddname. SCLM will build the ddname substitution list for us, but
we must specify the three values in the proper order. The FLMALLOC macro
specifies an 8 byte value when PORDER is a 2 or a 3. SCLM will plug in the
system generated ddnames and build the parameter list from the FLMALLOC
macros.
We will still need to use the FLMALLOC keyword DDNAME in order to provide a
match. This is not a problem because when PORDER is a 2 or a 3, the DDNAME
keywords on the FLMALLOC macros are used as labels and are not put into the
ddname substitution list.
This is an important point. PORDER of 2 or 3 causes the DDNAME keywords on
the FLMALLOC macros to be used as labels so that one may specify a value that
will match a DDNAME keyword for another translator.

268

ISPF/SCLM V4 Guide

FLMTRNSL
FLMALLOC
FLMALLOC
FLMALLOC

COMPILE=ABC,FUNCTN=BUILD,PORDER=2
IOTYPE=W,DDNAME=RECIN
* OUTPUT DDNAME
IOTYPE=N
* NOT APPLICABLE
IOTYPE=S,KEYREF=SINC
* INPUT DDNAME

FLMTRNSL COMPILE=XYZ,FUNCTN=BUILD,PORDER=0
FLMALLOC IOTYPE=U,DDNAME=RECIN
FLMALLOC IOTYPE=A,DDNAME=REPORT

Figure 144. Refer Back with DDname Substitution List. DDNAME keywords are used as
labels.

IOTYPE of N causes SCLM to place X'0000000000000000' in the ddname


substitution list. A not applicable value is 8 hexadecimal zeros.

23.1.12 Refer Back with IEBGENER Bridge


There are situations in which a translator is not programmed to use ddname
substitution lists, and its ddnames do not match those used in other translators.
In these situations, one may use IEBGENER as a bridge between the two
translators. IEBGENER, as with many IBM utilities, is programmed to use a
ddname substitution list.
The use of IEBGENER as a bridge between two translators uses this general
technique:
1. Construct an FLMTRNSL for the first translator.
2. Construct an FLMTRNSL for IEBGENER with PORDER=3 so that a ddname
substitution list is used.
3. Use the DDNAME keyword on the FLMALLOC for SYSUT1 to match the
DDNAME needed from the first translator, and use IOTYPE=U to refer back
to the DDNAME.
4. Use the DDNAME keyword on the FLMALLOC for SYSUT2 to match the
DDNAME needed in the next translator.
5. Construct an FLMTRNSL for the third translator.
6. Use IOTYPE=U on the FLMALLOC that needs the data set from the first
translator to refer back to the DDNAME match on SYSUT2 in IEBGENER.
This bridge works because IEBGENER copies SYSUT1 to SYSUT2. SYSUT1 refers
back to the needed data set from the first translator which is then copied to
SYSUT2. The third translator refers back to SYSUT2 which is a copy of the
desired data set from the first translator.
In Figure 145 on page 270, there are two translators for the BUILD function:
ABC and XYZ. ABC writes output to ddname OUTPUT. XYZ uses the output
from ABC to produce a report. XYZ uses ddname RECIN for its input data set. A
ddname substitution list is required since ABC and XYZ use different ddnames
(OUTPUT and RECIN) for the data set of interest.
The specification for ABC indicates that ABC is not programmed to use a
ddname substitution list. This situation calls for the use of IEBGENER as a
bridge between ABC and XYZ.

Chapter 23. SCLM Translator Interfaces

269

FLMTRNSL COMPILE=ABC,FUNCTN=BUILD,PORDER=0
FLMALLOC IOTYPE=S,DDNAME=INPUT,KEYREF=SINC
FLMALLOC IOTYPE=W,DDNAME=OUTPUT
FLMTRNSL
FLMALLOC
FLMALLOC
FLMALLOC
FLMALLOC
FLMALLOC
FLMCPYLB
FLMALLOC
FLMCPYLB
FLMALLOC
FLMALLOC
FLMALLOC
FLMALLOC
FLMCPYLB
FLMALLOC
FLMCPYLB

COMPILE=IEBGENER,FUNCTN=BUILD,PORDER=3
IOTYPE=N
* NOT APPLICABLE
IOTYPE=N
* NOT APPLICABLE
IOTYPE=N
* NOT APPLICABLE
IOTYPE=N
* NOT APPLICABLE
IOTYPE=A
* SYSIN
NULLFILE
IOTYPE=A
* SYSPRINT
NULLFILE
IOTYPE=N
* NOT APPLICABLE
IOTYPE=U,DDNAME=OUTPUT
* SYSUT1
IOTYPE=W,DDNAME=RECIN
* SYSUT2
IOTYPE=A
* SYSUT3 (NOT USED BY IEBGENER)
NULLFILE
IOTYPE=A
* SYSUT4 (NOT USED BY IEBGENER)
NULLFILE

FLMTRNSL COMPILE=XYZ,FUNCTN=BUILD,PORDER=0
FLMALLOC IOTYPE=U,DDNAME=RECIN
FLMALLOC IOTYPE=A,DDNAME=REPORT

Figure 145. Refer Back with IEBGENER Bridge. IEBGENER is needed because the
ddnames do not match and translator ABC is not programmed to use a ddname
substitution list.

There are 11 values in a ddname substitution list for IBM utilities, such as
IEBGENER. Even though IEBGENER does not use SYSUT3 or SYSUT4, it does not
hurt anything to specify them as dummy data sets as in Figure 145. The
FLMALLOC statements used to construct a ddname substitution list must be
specified in the correct order.

23.1.13 PORDER and Parameter Lists


When a translator receives control from SCLM, register one will be pointing to a
parameter list. The contents of this parameter list depends upon the value of the
PORDER keyword in the FLMTRNSL macro. In general, it is not possible to
determine the PORDER value from the parameter list.
Some PORDER values will not be valid for some translators. For example,
PORDER=2 puts the ddname substitution list in a different place than
PORDER=3 even though they both direct SCLM to construct a ddname
substitution list. The following figure illustrates the parameter list structure for
various values of PORDER.

270

ISPF/SCLM V4 Guide

Register 1 contains the address of the parameter list.


The parameter list consists of 2 contiguous words: WORD1 and WORD2.
The high order (sign) bit of WORD2 is ON for all values of PORDER.
PORDER=0

WORD1 is zero.
WORD2 is zero (except the high order bit).

PORDER=1

WORD1 is the address of a half word length field followed


by the value of the OPTIONS keyword. The length field is
on a half word (but not full word) boundary. The value of the
length field is the number of bytes in the OPTIONS list.
WORD2 is the address of a half word length field on a half
word (but not full word) boundary. The value of the half word
length field is zero.

PORDER=2

WORD1 is the address of a half word length field followed


by the ddname substitution list. The length field is on a
half word (but not full word) boundary. The value of the
length field is the number of bytes in the ddname substitution
list.
WORD2 is the address of a half word length field on a half
word (but not full word) boundary. The value of the half word
length field is zero.

PORDER=3

WORD1 is the address of a half word length field followed


by the value of the OPTIONS keyword. The length field is
on a half word (but not full) word boundary. The value of the
length field is the number of bytes in the OPTIONS list.
WORD2 is the address of a half word length field followed
by the ddname substitution list. The length field is on a
half word (but not full word) boundary. The value of the
length field is the number of bytes in the ddname substitution
list.

Figure 146. PORDER and the Parameter List. The value of PORDER determines the
placement of an OPTIONS list and a ddname substitution list in the parameter list.

Chapter 23. SCLM Translator Interfaces

271

272

ISPF/SCLM V4 Guide

Chapter 24. Translator Building Blocks, #LANG, #MACLIB, ...


If you have multiple language definitions that only differ in small details (such as
macro libraries referenced), you will eventually find you have a maintenance
problem when you need to make a change to the common part of the language
definition.
For a project that involved using the assembler in various combinations of macro
libraries, PLX compiler and CICS translator steps I packaged each translator into
an assembler macro and was easily able to build a large number of languages
from a few simple building blocks. To avoid having to specify same set of data
sets to both the parser as FLMSYSLB and translators as FLMCPYLB, I also
created a #LANG macro which combines the FLMLANGL, FLMSYSLB, parser
and saves the data set names in a macro variables where they are retrieved
within the language translator macros.
#LANG macro Combines FLMSYSLB, FLMLANGL, and parser translator.
#MACLIB macro Generates FLMCPYLB for each library specified on #LANG.
#ASM macro Assembler H language translator.
#PLX macro PL/X or PLAS language translator.
#CICS macro CICS language translator.
#APPEND macro Translator to concatenate listings. Note: With DISP=MOD
support in 3.4, this is no longer needed but I haven't updated the
other language macros.
SCLMAPND exec REXX exec called by #APPEND (uses MVSPIPE and DSINFO
from MVSTOOLS)
@LANGS copy Examples of complex language definitions made simple by using
the building blocks
MACRO
&LANGNME #LANG &LIB=,
&NAME='No Name',
&SYNTAX=
*====================================================================
MNOTE *,'======== &LANGNME ========='
MNOTE *,&NAME
*====================================================================
LCLA &MAC_CT
Index
GBLC &MACLIST(20)
Array of library names
GBLA &MACNUM
Number of libraries
&MACNUM SETA N'&LIB
&MAC_CT SETA 2
AIF
(&MACNUM LT 1).LPEND
&LANGNME FLMSYSLB &LIB(1)
&MACLIST(1) SETC '&LIB(1)'
.LOOP AIF (&MAC_CT GT &MACNUM).LPEND
FLMSYSLB &LIB(&MAC_CT)
&MACLIST(&MAC_CT) SETC '&LIB(&MAC_CT)'
&MAC_CT SETA &MAC_CT+1
AGO
.LOOP
.LPEND ANOP
FLMLANGL
LANG=&LANGNME
AIF
('.&SYNTAX' EQ '.').MEND
FLMTRNSL CALLNAM=&NAME,
FUNCTN=PARSE,
COMPILE=FLM@SCAN,
PORDER=1,

X
X

X
X
X
X

Figure 147 (Part 1 of 2). #LANG Macro

Copyright IBM Corp. 1994

273

OPTIONS=(PARSEDSN=''@@FLMPRJ.@@FLMGRP.@@FLMTYP'',
PARSEMEM=@@FLMMBR,
STATINFO=@@FLMSTP,
LISTINFO=@@FLMLIS,
LISTSIZE=@@FLMSIZ,
LANG=&SYNTAX.)

X
X
X
X
X

.MEND ANOP
MEND

Figure 147 (Part 2 of 2). #LANG Macro

MACRO
#MACLIB
LCLA &MAC_CT
GBLC &MACLIST(20)
GBLA &MACNUM
&MAC_CT SETA 1
.LOOP AIF (&MAC_CT GT &MACNUM).LPEND
FLMCPYLB &MACLIST(&MAC_CT)
&MAC_CT SETA &MAC_CT+1
AGO
.LOOP
.LPEND ANOP
MEND

Index
Array of library names
Number of libraries

Figure 148. #MACLIB Macro

MACRO
#ASM &IN=,&OBJ=,&PRT=
--ASSEMBLER 'H' INTERFACE-FLMTRNSL CALLNAM='ASM H',
FUNCTN=BUILD,
COMPILE=IEV90,
VERSION=2.1,
GOODRC=4,
PORDER=3,
PARMKWD=1,
OPTIONS=(NOOBJECT,DECK,RENT,XREF(SHORT),
LINECOUNT(55))

*
* 1
* 2
* 3
* 4
* 5

X
X
X
X
X
X
X
X

--SYSLIN-FLMALLOC IOTYPE=A
FLMCPYLB NULLFILE
--N/A-FLMALLOC IOTYPE=N
--N/A-FLMALLOC IOTYPE=N
--SYSLIB-FLMALLOC IOTYPE=I,KEYREF=SINC,DDNAME=SYSLIB
#MACLIB
--SYSIN-AIF ('.&IN' EQ '.').AINA
FLMALLOC IOTYPE=U,DDNAME=&IN
AGO .AINZ

.AINA ANOP
FLMALLOC IOTYPE=S,KEYREF=SINC,RECFM=FB,LRECL=80,
RECNUM=9000
.AINZ ANOP
* 6
--SYSPRINT-AIF ('.&PRT' EQ '.').APRTA
FLMALLOC IOTYPE=W,RECFM=FBM,LRECL=121,RECNUM=50000,
PRINT=Y,DDNAME=&PRT
AGO .APRTZ
.APRTA ANOP
FLMALLOC IOTYPE=O,KEYREF=LIST,RECFM=FBM,LRECL=121,
RECNUM=20000,PRINT=Y,DFLTTYP=LISTING
.APRTZ ANOP
* 7
--SYSPUNCH-AIF ('.&OBJ' EQ '.').AOBJA
FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,
RECNUM=9000,DDNAME=&OBJ
AGO .AOBJZ

Figure 149 (Part 1 of 2). #ASM Macro

274

ISPF/SCLM V4 Guide

.AOBJA ANOP
FLMALLOC IOTYPE=O,KEYREF=OBJ,RECFM=FB,LRECL=80,
RECNUM=9000,DFLTTYP=OBJ

.AOBJZ ANOP
* 8
--SYSUT1-FLMALLOC IOTYPE=W,RECFM=FB,LRECL=80,RECNUM=15000
* 9
--SYSTERM-FLMALLOC IOTYPE=A
FLMCPYLB NULLFILE
MEND

Figure 149 (Part 2 of 2). #ASM Macro

MACRO
#CICS &COMPILE=,
&DSNAME=,
&VERSION=A.B,
&OPTIONS=''
*========== CICS PRECOMPILER ========================================
MNOTE *,'== &COMPILE &VERSION ======'
MNOTE *,&OPTIONS
*
--- CICS PRECOMPILER
FLMTRNSL CALLNAM='CICS PRECOMP',
FUNCTN=BUILD,
COMPILE=&COMPILE.,
DSNAME=&DSNAME.,
VERSION=&VERSION.,
GOODRC=00,
PORDER=1,
OPTIONS=(&OPTIONS.)
* 1
(* SYSIN *)
FLMALLOC IOTYPE=S,KEYREF=SINC,RECFM=FB,LRECL=80,
DDNAME=SYSIN
* 2
(* SYSPRINT *)
FLMALLOC IOTYPE=W,RECFM=FBA,LRECL=121,
RECNUM=5000,PRINT=Y,DDNAME=SYSPRINT
* 3
(* SYSPUNCH *)
FLMALLOC IOTYPE=O,RECFM=FB,LRECL=80,KEYREF=OUT1,
RECNUM=4000,DDNAME=SYSPUNCH,PRINT=Y
MEND

X
X
X

C
C
C
C
C
C
C
C
C
C

Figure 150. #CICS Macro

MACRO
#APPEND &IN=,&OUT=LISTING
LCLA &IN_CT
Index
LCLC &IN_LIST
List of DDnames
&IN_CT SETA 1
.LOOP AIF (&IN_CT GT N'&IN).LPEND
&IN_LIST SETC '&IN_LIST &IN(&IN_CT)'
&IN_CT SETA &IN_CT+1
AGO
.LOOP
.LPEND ANOP
***********************************************************************
* APPEND STEP (CONCATENATE LISTINGS TO LISTING FILE)
***********************************************************************
FLMTRNSL CALLNAM='APPEND',
C
FUNCTN=BUILD,
C
COMPILE=IRXJCL,
C
VERSION=V3R2M0,
C
GOODRC=0,
C
PORDER=1,
C
PARMKWD=1,
C
OPTIONS='SCLMAPND OUT &IN_LIST'
* 1
--OUT-FLMALLOC IOTYPE=O,RECFM=FBA,LRECL=133,RECNUM=50000,
X
KEYREF=LIST,DFLTTYP=&OUT,DDNAME=OUT
MEND

Figure 151. #APPEND Macro

Chapter 24. Translator Building Blocks, #LANG, #MACLIB, ...

275

/* REXX */
/* PROGRAM NAME: SCLMAPND
*/
/*
*/
/* DESCRIPTIVE NAME:
*/
/* Concatenate Build translator listings
*/
/*
*/
/* COPYRIGHT: (C) COPYRIGHT IBM CORP 1991
*/
/*
*/
/* STATUS: N/A
*/
/*
*/
/* FUNCTION:
*/
/* Concatenates DD's to allow, for example, the PLAS and Assembler
*/
/* listings for a module to be combined into a single listing file. */
/*
*/
/* NOTES:
*/
/*
DEPENDENCIES: DSNINFO (from MVSTOOLS)
*/
/*
MVSPIPE (from MVSTOOLS)
*/
/*
INPUT/OUTPUT FILES: None.
*/
/*
RESTRICTIONS: None.
*/
/*
ERROR MESSAGES: See program for details.
*/
/*
USAGE: SCLM Build translator
*/
/*
RESTART/RECOVERY: None
*/
/* ENTRY CONDITIONS:
*/
/*
SYNTAX:
*/
/*
SCLMAPND outdd indd1 ... inddn
*/
/*
*/
/*
PARAMETERS:
*/
/*
outdd
DD name to be concatanated to
*/
/*
indd1
list of DD's to be concatenated to outdd
*/
/*
*/
/*
OPTIONS:
*/
/*
None
*/
/*
*/
/*
EXECUTION EXAMPLES:
*/
/*
SCLMAPND OUT PLASPRT ASMPRT LINKPRT
*/
/*
- Will copy PLASPRT, ASMPRT and LINKPRT to the OUT DD
*/
/*
*/
/* NORMAL EXIT CONDITIONS:
*/
/*
RETURN CODES:
*/
/*
0
Successful completion
*/
/*
*/
/* ERROR EXIT CONDITIONS:
*/
/*
RETURN CODES:
*/
/*
8 - Syntax error - unsuccessful completion
*/
/*
20 - Novalue error - local definitions not performed
*/
/*
*/
/* OPERATION:
*/
/* Parse parameters
*/
/* Trap output of DSNINFO command to determine record length of
*/
/* output file.
*/
/* Set up pipeline command to read all of the input DDs
*/
/* Issue pipe command to:
*/
/* - Read all the input data sets
*/
/* - Truncate/expand records to output file record length
*/
/* - Write to the output data set
*/
/*
*/
/* OWNED/SUPPORTED BY: CICS Products Tools Development.
*/
/*
Contact the LCS Help Desk.
*/
/*
BUXTON @ WINVMJ
*/
/*
*/
/* CHANGE ACTIVITY:
*/
/*
*/
/* Reason for Change
ATW# Init DDMmmYY */
/*--------------------------------------------------------------------*/
/* @00= Initial version
nnnn RFB 29Apr91 */
/*====================================================================*/
/* Standard Prologue for REXX execs
*/
/*====================================================================*/
Parse Upper Arg parms0 '(' opts0; pnum=WORDS(parms0); onum=WORDS(opts0)
Parse Upper Source . itype exec0 . . exec addr_name .
Parse Upper version impl . . langlevel .
Address 'TSO';
RC=0;ret=0; Signal On NOVALUE; Signal On SYNTAX; Signal On HALT
/*====================================================================*/
/* End of the Prolog
*/
/*====================================================================*/

Figure 152 (Part 1 of 2). EXXx SCLMAPND to Concatenate Build Translator Listings

276

ISPF/SCLM V4 Guide

/*--------------------------------------------------------------------*/
/* Parse parameters
*/
/*--------------------------------------------------------------------*/
Parse Var parms0 outdd indd1 inddn
/*--------------------------------------------------------------------*/
/* Trap output of DSNINFO command to determine record length of
*/
/* output file.
*/
/*
*/
/* (LISTDSI is unusable because it doesn't work on VIO data sets)
*/
/*--------------------------------------------------------------------*/
x=outtrap('dsi.',7)
/* Set up for output trapping */
'DSNINFO' outdd 'FILE'
/* Find output DD attributes */
ret=rc
If ret<>0 then
/* Error retrieving attributes */
Do
Say 'Return code' ret 'from DSNINFO'
Signal exit
End
x=outtrap('OFF')
Parse Var dsi.4 . 'LRECL....' lrecl . /* Lrecl in 4th line of output */
/*--------------------------------------------------------------------*/
/* Set up pipeline command to read all of the input DDs
*/
/*--------------------------------------------------------------------*/
pipecmd = 'QSAM' indd1
/* Read first data set
*/
Do i = 1 To WORDS(inddn)
pipecmd= pipecmd '| APPEND QSAM' WORD(inddn,i) /* Read other inputs*/
End i
/*--------------------------------------------------------------------*/
/* Issue pipe command to:
*/
/* - Read all the input data sets
*/
/* - Truncate/expand records to output file record length
*/
/* - Write to the output file
*/
/*--------------------------------------------------------------------*/
'PIPE' pipecmd,
/* Read the input files
*/
'| SPECS 1-* 1-'lrecl,
/* Ensure output record length */
'| QSAM' outdd
/* Write to output file
*/
ret=rc
If ret<>0 then
Say 'Return code' ret 'from MVSPIPE'
EXIT:
/*====================================================================*/
/* Standard Epilogue for REXX execs
*/
/*====================================================================*/
COMEXIT:
If itype = 'FUNCTION' Then
Exit ret;
Else
Do; Parse Var ret ret .; Exit ret; End
NOVALUE:
/* Identify source of problem */
Say 'NoValue error' exec0 'line' sigl;
If langlevel>3.45 Then
/* Condition built-in-func. supported */
Say 'Referenced variable is' condition('D');
If SOURCELINE() <> 0 Then
Say SOURCELINE(sigl)
ret = 20; Signal Comexit
HALT:
Say 'Halt condition' exec0 sigl; ret = 20; Signal Exit
SYNTAX:
syntax_rc = rc;
Say 'Syntax error' syntax_rc exec0 'line' sigl; ret = 20;
If SOURCELINE() <> 0 Then
Say SOURCELINE(sigl)
Say 'Error -' ERRORTEXT(syntax_rc); Signal Comexit

Figure 152 (Part 2 of 2). EXXx SCLMAPND to Concatenate Build Translator Listings

Chapter 24. Translator Building Blocks, #LANG, #MACLIB, ...

277

*=====================================================================
*
Language definitions
*=====================================================================
*
*=====================================================================
*
Copy member contained within this project definition
*
(Because language unique to this project or special needs)
*=====================================================================
*
COPY @COBC2
-- COBOL with CICS 2 translator
COPY @LINK
-- Linkage editor
*
*=====================================================================
*
Copy member contained in CSM project definition
*
(Because language definition is common across projects)
*=====================================================================
*
COPY @ARCD
-- Architecture definition
COPY @BOOK
-- Bookmaster for 3820
COPY @BOOKTRM
-- Bookmaster for terminal (1403)
COPY @DTL
-- Dialog tag language
*
*=====================================================================
*
Language definitions coded in-line
*
(Because local macros (in CSM project) keep them short)
*=====================================================================
*
-- Assembler/CICS 2
ASMC2
#LANG NAME='Assembler with CICS 2 translator',
SYNTAX=A,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
#CICS COMPILE=DFHEAP1$,
DSNAME=HCI2212.LOADLIB,
VERSION=2.1,
OPTIONS=' '
#ASM IN=SYSPUNCH,PRT=ASMPRT
#APPEND IN=(SYSPRINT,ASMPRT)
*
*
-- Assembler/CICS 3
ASMC3
#LANG NAME='Assembler with CICS 3 translator',
SYNTAX=A,
LIB=(SYS1.MACLIB,HCI3321D.SRC.ADFHMAC,SYS1.AMODGEN)
#CICS COMPILE=DFHEAP1$,
DSNAME=HCI3321D.SDFHLOAD,
VERSION=3.2,
OPTIONS=' '
#ASM IN=SYSPUNCH,PRT=ASMPRT
#APPEND IN=(SYSPRINT,ASMPRT)
*
*
-- Assembler H
ASMH
#LANG NAME='Assembler H',
SYNTAX=A,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
#ASM
*
*
-- Assembler H - CICS3 Macros - No translator
ASMM3
#LANG NAME='Assembler H w/CICS3 macro',
SYNTAX=A,
LIB=(SYS1.MACLIB,HCI3321D.SRC.ADFHMAC,SYS1.AMODGEN)
#ASM
*
-- CLIST
CLIST
#LANG NAME='TSO CLISTs',
SYNTAX=R
*
-- General purpose (no Build)
GEN
#LANG NAME='General Pupose Translator',
SYNTAX=T
*
-- ISPF CLIST
ISPFCLST #LANG NAME='ISPF CLISTs',
SYNTAX=R
*
-- ISPF Panels
ISPFPANL #LANG NAME='ISPF Panels',
SYNTAX=T
*
-- ISPF Panels
ISPFMSG #LANG NAME='ISPF Messages',
SYNTAX=T
*
-- JCL
JCL
#LANG NAME='JCL',
SYNTAX=T

Figure 153 (Part 1 of 2). @LANG Copy

278

ISPF/SCLM V4 Guide

X
X
C
C
C

X
X
C
C
C

X
X

X
X

X
X
X
X
X
X

*
MACRO

-- Macros
#LANG NAME='Assembler Macros',
SYNTAX=A,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
*
-- BMS maps
MAP
#LANG NAME='Assembler H- for BMS maps',
SYNTAX=A,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
#ASM
*
-- MISC
MISC
#LANG NAME='Misc stuff',
SYNTAX=T
*
-- Messages
MSG
#LANG NAME='Messages',
SYNTAX=T
*
-- CICS Panels
PANEL
#LANG NAME='CICS Panels',
SYNTAX=T
*
-- PLX
PLX
#LANG NAME='PL/X Language',
SYNTAX=P,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
#PLX
#ASM IN=PLXUT2,PRT=ASMPRT
#APPEND IN=(PLXPRT,ASMPRT)
*
-- PLX / CICS 2
PLXC2
#LANG NAME='PL/X w/CICS 2 translator',
SYNTAX=P,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
#CICS COMPILE=DFHEPP1$,
DSNAME=HCI2212.LOADLIB,
VERSION=2.1,
OPTIONS='PLS,PLSA0'
#PLX IN=SYSPUNCH
#ASM IN=PLXUT2,PRT=ASMPRT
#APPEND IN=(SYSPRINT,PLXPRT,ASMPRT)
*
-- PLX / CICS 3
PLXC3
#LANG NAME='PL/X w/CICS 3 translator',
SYNTAX=P,
LIB=(SYS1.MACLIB,HCI3321D.SRC.ADFHMAC,SYS1.AMODGEN)
#CICS COMPILE=DFHEPP1$,
DSNAME=HCI3321D.SDFHLOAD,
VERSION=3.2,
OPTIONS='PLS,PLSA0'
#PLX IN=SYSPUNCH
#ASM IN=PLXUT2,PRT=ASMPRT
#APPEND IN=(SYSPRINT,PLXPRT,ASMPRT)
*
-- PLX - CICS3 macros no translate
PLXM3
#LANG NAME='PL/X w/CICS3 macro',
SYNTAX=P,
LIB=(SYS1.MACLIB,HCI3321D.SRC.ADFHMAC,SYS1.AMODGEN)
#PLX
#ASM IN=PLXUT2,PRT=ASMPRT
#APPEND IN=(PLXPRT,ASMPRT)
*
-- Macros
PLXMACRO #LANG NAME='PLX Macros',
SYNTAX=P,
LIB=(SYS1.MACLIB,HCI2212.SRC.MACLIB,SYS1.AMODGEN)
*
-- RDLDATA - Not buildable on MVS
RDLDATA #LANG NAME='Resource definitions',
SYNTAX=T
*
-- REXX
REXX
#LANG NAME='REXX execs',
SYNTAX=R

X
X
X
X

X
X
X
X
X

X
X
C
C
C

X
X
C
C
C

X
X

X
X
X
X

Figure 153 (Part 2 of 2). @LANG Copy

Chapter 24. Translator Building Blocks, #LANG, #MACLIB, ...

279

280

ISPF/SCLM V4 Guide

Chapter 25. SCLM Invocation


25.1.1 TSO SCLM Batch Job - An Example
//SCLMJOB JOB ,account.userid,MSGCLASS=T,
// MSGLEVEL=(1,1),NOTIFY=userid
//*
//********** JOBcard must be replaced
//*
//SCLM PROC P='*'
//*-------------------------------------------- PREPARE PROCLIB
//GENER0 EXEC PGM=IEBGENER
//SYSPRINT DD DUMMY
//SYSIN
DD DUMMY
//SYSUT1 DD DUMMY
//SYSUT2 DD DSN=&&CLIST0(TEMPNAME),DISP=(MOD,PASS),UNIT=SYSDA,
//
SPACE=(TRK,(2,2,2)),
//
DCB=(LRECL=255,BLKSIZE=6144,DSORG=PO,RECFM=VB)
//*-------------------------------------------- RUN SCLM
//prjid EXEC PGM=IKJEFT01,REGION=7M,TIME=1439,DYNAMNBR=200
//*
//STEPLIB
DD DSN=prjid.PROD.LOAD,DISP=SHR
//
DD DSN=IMSESA.RESLIB,DISP=SHR
//
DD DSN=SPF.V3R5M0.LOAD,DISP=SHR
//
DD DSN=SUDB2B.DSN220.DSNEXIT,DISP=SHR
//
DD DSN=SUDB2B.DSN220.DSNLOAD,DISP=SHR
//
DD DSN=SUDB.QMF240.DSQLOAD,DISP=SHR
//
DD DSN=SUDB.CSP330.ADLOAD,DISP=SHR
//
DD DSN=SUDB.CSP330.AELOAD,DISP=SHR
//
DD DSN=SYS1.COB2COMP,DISP=SHR
//
DD DSN=SYS1.PLILINK,DISP=SHR
//
DD DSN=CICS.V3R1M1.LOADLIB,DISP=SHR
//******************************************************************
//* CSP LIBRARIES
//******************************************************************
//DCALOAD
DD DISP=SHR,DSN=SUDB.CSP330.ADLOAD
//
DD DISP=SHR,DSN=SUDB.CSP330.AELOAD
//DCADZGD
DD DISP=SHR,DSN=SUDB.CSP330.DZGMSG
//DCAHECD
DD DISP=SHR,DSN=SUDB.CSP330.FZEMSG
//DCASAMD
DD DISP=SHR,DSN=SUDB.CSP330.DCASAMD
//DCAEZED
DD DISP=SHR,DSN=SUDB.CSP330.EZEMSG
//DCAMAPD
DD DISP=SHR,DSN=SUDB.CSP330.FZEMAPDS
//DCATESD
DD DISP=SHR,DSN=SUDB.CSP330.FZETUTOR
//UTILALF
DD DISP=SHR,DSN=SUDB.CSP330.UTILALF.ALF
//*-------------------------------------------------------------------//SYSEXEC
DD DSN=prjid.PROD.REXX,DISP=SHR
//*-------------------------------------------- ISPF/PDF LIBRARIES
//ISPMLIB
DD DSN=SPF.V4R1M0.SISPMENU,DISP=SHR
//ISPSLIB
DD DSN=SPF.V4R1M0.SISPSENU,DISP=SHR
//ISPPLIB
DD DSN=SPF.V4R1M0.SISPPENU,DISP=SHR
//ISPTLIB
DD DSN=SPF.V4R1M0.SISPTENU,DISP=SHR
//ISPTABL
DD UNIT=VIO,DISP=(NEW,PASS),SPACE=(CYL,(1,1,5)),
//
DCB=(LRECL=80,BLKSIZE=19040,DSORG=PO,RECFM=FB),
//
DSN=&TABLESP
//ISPPROF
DD UNIT=VIO,DISP=(NEW,PASS),SPACE=(CYL,(1,1,5)),
//
DCB=(LRECL=80,BLKSIZE=19040,DSORG=PO,RECFM=FB),
//
DSN=&TABLESP
//ISPLOG
DD SYSOUT=&P,
//
DCB=(LRECL=120,BLKSIZE=2400,DSORG=PS,RECFM=FB)
//*-------------------------------------------- NLS TABLE
//SYSPRINT DD SYSOUT=Project
//SYSTSPRT DD SYSOUT=Project
//R
DD SYSOUT=&P,
//
DCB=(LRECL=80,BLKSIZE=3120,RECFM=FBA)
//L
DD SYSOUT=&P,
//
DCB=(LRECL=259,BLKSIZE=3120,RECFM=VB)
//M
DD SYSOUT=&P,
//
DCB=(LRECL=80,BLKSIZE=80,RECFM=F)
//E
DD DSN=&&EXIT,
//
DISP=(NEW,PASS),SPACE=(TRK,(5,10),RLSE),
//
DCB=(LRECL=160,BLKSIZE=3200,RECFM=FB),UNIT=3380
//*-------------------------------------------- OUTPUT FILES
//ZFLMDD DD DUMMY
//*
//FLMMSGS DD SYSOUT=Project

Copyright IBM Corp. 1994

281

//*-------------------------------------------- TEMP CLIST COMMAND


//SYSPROC
DD DSN=&&CLIST0,DISP=(OLD,DELETE)
//
DD DSN=SUDB.CSP330.ADCLISV,DISP=SHR
//
DD DSN=SUDB.CSP330.AECLISV,DISP=SHR
//
DD DSN=prjid.PROD.REXX,DISP=SHR
//*-------------------------------------------- TSO INPUT FILE
//SYSTSIN DD DUMMY
//*-------------------------------------------- FLMCMD INPUT FILE
//FLMCMD DD DUMMY
//
PEND
//*
//STEP1 EXEC SCLM
//*
//GENER0.SYSUT1 DD *
FLMCMD BUILD,prjid,,DEV1,ARCHDEF,FLM01AP1,,N,C,Y,Y,,M,R,L,E
//*
//prjid.SYSTSIN DD *
ISPSTART CMD(%TEMPNAME)
//*

25.1.2 REXX Program with ISPF Variables Example


/* REXX
SCLRDGI1 */
/*
* Sample REXX Exit to save SDF/II output into an SCLM hierarchy
* after calling the generation function
*
* This Exit is based on the SDF/II supplied DGICXBRR REXX
* supplied with the product. Make necessary modifications at
* bottom of REXX SCLRDGI1.
*/
Address 'ISPEXEC'
'ISPEXEC VGET',
/* Get variables from shared pool */
'(ICVUETSY ICVUEOMN ICVUEOLN) SHARED'
Select
when icvuetsy = 1 then do
/* generation for CICS/BMS
*/
end
otherwise do
say
say 'Cannot save output in SCLM-Project, watch it!!!'
say
exit
end
end
If icvueoln='' then do

/* If no data set name given


*/
/* use the DD-name
*/
'ISPEXEC VGET (ICVUEODD) SHARED' /* Get the DD-name
*/
'ISPEXEC LMINIT DATAID(DATAID) DDNAME('icvueodd')' /*Get dataid*/
If rc>0 then Exit
dgiscact = ''

'ISPEXEC BROWSE DATAID('dataid')', /* Call PDF browse service


'MEMBER('icvueomn')'
'ISPEXEC LMFREE DATAID('dataid')' /* Free the dataid
end
else do
dsn = strip(icvueoln,'B',"'") /* strip the quotes
*/
If dsn=icvueoln then
/* the name is not quoted
dsn = sysvar(syspref)||'.'||dsn /* use the TSO-prefix
dsn = "'"||dsn"("icvueomn")'" /* And add the member name */

*/
*/

*/
*/

dgiscact = ''
'ISPEXEC BROWSE DATASET('dsn')' /* Call PDF browse service
end

*/

Say "*************************************"
Say "* Do you want to save Data in SCLM? *"
Say "*************************************"
pull ans
if substr(ans,1,1) <> 'Y' then Exit
/*
* Save the member in SCLM hierarchy if
*/
$prj = 'SAA1'
/* SCLM
$prjdef = 'SAA1'
/* SCLM
$grp = 'STADE1'
/* SCLM
$typ = 'BMSSRC'
/* SCLM
$language = 'BMS'

282

ISPF/SCLM V4 Guide

BMS
project
project definition
developement group
typ for saved map

*/
*/
*/
*/

sclmdsn = $prj||"."||$grp||"."||$typ
sclmmbr = sclmdsn||"("||icvueomn||")"
sclmmbr = "'"||sclmmbr||"'"
Address 'TSO'
/*
* Copy the generated SDF/II output to the SCLM hierarchy
*/
"alloc fi(in) da("||dsn||") reuse shr"
"alloc fi(out) da("||sclmmbr||") reuse shr"
"EXECIO * diskr in (finis stem src."
"EXECIO * diskw out (finis stem src."
"free fi(in)"
"free fi(out)"
/*
* Register with SCLM
*/
savecmd = "SAVE,"||$prj||","||$prjdef||","||$grp||","||$typ || ,
","||icvueomn||","||","||","||","||$language
"flmcmd "||savecmd
if rc = 0 then do
Say "*"
Say "* Member " icvueomn " has been saved successfully"
Say "* in the SCLM hierarchy of project" $prj "."
Say "*"
End
/*
* SCLM-Build
*/
savecmd = "BUILD,"||$prj||","||$prjdef||","||$grp||","||$typ || ,
","||icvueomn||","||","||","||","||$language
"flmcmd "||savecmd
if rc = 0 then do
Say "*"
Say "* Member " icvueomn " has been built successfully"
Say "*"
End
Address 'ISPEXEC'
Exit

Chapter 25. SCLM Invocation

283

284

ISPF/SCLM V4 Guide

Chapter 26. Workshop Foils


These foils are put here for your convenience. The original foil format can be
found on the enclosed diskette.
The foils cover two topics:
1. Part 1: The SCLM project manager work, starting at 26.1, Project
Organization on page 285.
2. Part 2: The development cycle, starting at 26.21, The Promote Process on
page 295.
Note: The foil contents need an SCLM knowledged person to be explained and
interpretated. The time available did not allow for detailed explanations.

26.1 Project Organization

P
PRODUCTION
R

O
B
DELIVERY
L

E
PRODUCTION
FIXes
M
(shadow)
I
/
C

H
Systemtest
Maintenance
A
I

N
G

E
Integration Development

M
A

N
Staging

G
E

M
Team

N
T

Rx.3 Rx.2 Rx.1

Development

PC
PC

Copyright IBM Corp. 1994

ROLES
C
O
N
F
I
G
U
R
A
T
M O
A R
N
A
G
E
R

D
E
V
E
L
O
P
E
R

285

26.2 Project Description


Serie of PDSs
Accounting File (VSAM)
(SCLM Data Base,
(SCLM Control)
bulk data (parts))
Meta Data

ProjectDefinition
(Load Module)
Project Views

prjid.account.file

(Name defined by PD)

I H

prjid.PROJDEFS.LOAD
prjid.group.type

I H

(Name defined as
(Name defined

by

output name from

project

ASMH compile / link


edit)

definition (PD))

26.3 SCLM Project Data Sets


TITLE 'Project Definition for Project prjid
'
*
* 1LQ (first level qualifier - define SCLM enterprise project
prjid
FLMABEG
*
* 3LQ / define data set types
ARCHDEF
FLMTYPE
SOURCLST FLMTYPE
LMAP
FLMTYPE
LOAD
FLMTYPE
OBJ
FLMTYPE
SOURCE
FLMTYPE
*
* 2LQ / define data set groups
RELEASE
FLMGROUP AC=(P),KEY=Y
TEST
FLMGROUP AC=(P),KEY=Y,PROMOTE=RELEASE
DEV1
FLMGROUP AC=(P),KEY=Y,PROMOTE=TEST
DEV2
FLMGROUP AC=(P),KEY=Y,PROMOTE=TEST
*
* define account file to control parts
FLMCNTRL ACCT=prjid.account.file
*
* define language definitions (methods)
COPY FLM@ARCD
-- SCLM Architecture
COPY FLM@PLIO
-- PL/I
COPY FLM@ASM
-- ASMH
*
FLMAEND

286

ISPF/SCLM V4 Guide

26.4 Partitioned Data Sets


prjid.RELEASE.ARCHDEF
prjid.RELEASE.SOURCLST
prjid.RELEASE.LMAP
prjid.RELEASE.LOAD
prjid.RELEASE.OBJ
prjid.RELEASE.SOURCE
prjid.TEST.ARCHDEF
prjid.TEST.SOURCLST
prjid.TEST.LMAP
prjid.TEST.LOAD
prjid.TEST.OBJ
prjid.TEST.SOURCE
prjid.DEV1.ARCHDEF
prjid.DEV1.SOURCLST
prjid.DEV1.LMAP
prjid.DEV1.LOAD
prjid.DEV1.OBJ
prjid.DEV1.SOURCE

prjid.DEV2.ARCHDEF
prjid.DEV2.SOURCLST
prjid.DEV2.LMAP
prjid.DEV2.LOAD
prjid.DEV2.OBJ
prjid.DEV2.SOURCE

Account-File: prjid.account.file
Project Definitions: prjid.PROJDEFS.LOAD

26.5 Data Base Structure for Project prjid


prjid.RELEASE.ARCHDEF

.LOAD

.LMAP

RELEASE

.OBJ

AC=P

.SOURCLST

.SOURCE
ie. part FLM01MD1, authorization code P

prjid.TEST.ARCHDEF

.LOAD

.LMAP

TEST

.OBJ

AC=P

.SOURCLST

.SOURCE
ie. part FLM01MD1, authorization code P

prjid.DEV1/2.ARCHDEF

.LOAD

.LMAP

DEV1

DEV2

.OBJ

AC=P

AC=P
.SOURCLST

.SOURCE
ie. part FLM01MD1, authorization code P

Chapter 26. Workshop Foils

287

26.6 Define Types


Types are idential on all hierarchy levels

....

LOAD

OBJ

SOURCE
TEST

....
....

LOAD
LOAD


OBJ

OBJ

SOURCE
SOURCE

DEV1
DEV2

26.7 Define Protection Scheme


Data Set

Developer

SCLM Project Mgr.

Project Definition
'prjid.PROJDEFS.LOAD'

READ

CONTROL

Project Data Base


'prjid.group.type'

UPDATE READ

CONTROL

Account File (VSAM)


'prjid.role.acctfile'

UPDATE

CONTROL

Version Data Sets


'prjid.group.type.version'

UPDATE READ

CONTROL

Audit Control (VSAM)


'prjid.role.versfile'

UPDATE

CONTROL

CSP Control
'prjid.PROJDEFS.CONTROL'

READ

CONTROL

288

ISPF/SCLM V4 Guide

26.8 Project Views


Provide a roleplay through different navigation and limitation of group access.

RELEASE

NONKEY Group

ie.

BACKUP

TEST

NONKEY Group

ie.

Integration

Developer 1
Developer 2

26.9 Project View for Parallel Maintenance


26.9.1.1 Concatenation Solution

PRODUCTION

(AC=P)


TEST


FIXTEST

(AC=P)


(AC=F)

FIXDEV
Developer 1
Developer 2
(AC=F)

(AC=P)


(AC=P)

Chapter 26. Workshop Foils

289

26.10 Method PLIO - an Example


FLMLANGL
LANG=PLIO,VERSION=PLIOV4.0
* PARSER TRANSLATOR
FLMTRNSL CALLNAM='PL/I PARSER',
FUNCTN=PARSE,
COMPILE=FLMLPGEN,
PORDER=1,
OPTIONS=(SOURCEDD=SOURCE,
PARSEMEM=@@FLMMBR,
STATINFO=@@FLMSTP,
LISTINFO=@@FLMLIS,
LISTSIZE=@@FLMSIZ,
LANG=I)
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMPRJ.@@FLMGRP.@@FLMTYP(@@FLMMBR)
* BUILD --PL/I OPTIMIZER INTERFACE-FLMTRNSL CALLNAM='PL/I OPTIMIZER',
FUNCTN=BUILD,
COMPILE=IEL0AA,
VERSION=4.0,
PORDER=3,
GOODRC=4,
OPTIONS=(MACRO,OBJECT,SOURCE,XREF,F(I))
* 1
(* SYSLIN *)
FLMALLOC IOTYPE=O,KEYREF=OBJ,RECFM=FB,LRECL=80,
RECNUM=5000,DFLTTYP=OBJ
* 2,3
......
* 4
(* SYSLIB *)
FLMALLOC IOTYPE=I,KEYREF=SINC
* 5
(* SYSIN *)
FLMALLOC IOTYPE=A
FLMCPYLB NULLFILE
* 6
(* SYSPRINT *)
FLMALLOC IOTYPE=O,KEYREF=LIST,RECFM=VBA,LRECL=125,
RECNUM=5000,PRINT=Y,DFLTTYP=*LST
* 7
(* SYSPUNCH *)
FLMALLOC IOTYPE=A,DDNAME=SYSIN
FLMCPYLB NULLFILE
* 8
(* SYSUT1 *)
FLMALLOC IOTYPE=W,RECFM=F,LRECL=4051,RECNUM=5000

26.11 Method Example PORDER


JCL:
//PROC0

PROC

//STEP1

EXEC

PGM=IEFBR14

SCLM Macros:
FLMLANGL LANG=METH1,VERSION=V0R0M0
FLMTRNSL COMPILE=IEFBR14,FUNCTN=BUILD,PORDER=0

290

ISPF/SCLM V4 Guide

C
C
C
C
C
C

26.12 Method Example GOODRC


JCL:
//STEP1
//STEP2

EXEC
EXEC

PGM=ABC
PGM=XYZ,COND=(5,GE)

SCLM Macros:
FLMTRNSL COMPILE=ABC,FUNCTN=BUILD,PORDER=0,GOODRC=4
FLMTRNSL COMPILE=XYZ,FUNCTN=BUILD,PORDER=0

26.13 Method Example DD STATEMENTS


JCL:
//STEP1
//SYSIN
//INPUT
//OUTPUT

EXEC
DD
DD
DD

PGM=GAC
DUMMY
DSN=SCLM41.DEV1.SOURCE(mbr),DISP=SHR
DSN=SCLM41.DEV1.SOURCLST(mbr),DISP=SHR

SCLM Macros:
FLMTRNSL COMPILE=GAC,FUNCTN=BUILD,PORDER=0
FLMALLOC
FLMCPYLB
FLMALLOC
FLMCPYLB
FLMALLOC
FLMCPYLB

IOTYPE=A,DDNAME=SYSIN
NULLFILE
IOTYPE=A,DDNAME=INPUT
SCLM41.DEV1.SOURCE(mbr)
IOTYPE=A,DDNAME=OUTPUT
SCLM41.DEV1.SOURCLST(mbr)

Chapter 26. Workshop Foils

291

26.14 Method Example for Translator MBS


JCL:
//HURRA
//STEP1
//SYSIN
//INPUT
//OUTPUT
//SYSUT1

PROC
EXEC
DD
DD
DD
DD

//SYSUT2 DD
//SYSUT3 DD

PGM=MBS
DUMMY
DSN=SCLM41.DEV1.SOURCE(mbr),DISP=SHR
DSN=SCLM41.DEV1.SOURCLST(mbr),DISP=SHR
UNIT=SYSDA,DISP=(NEW,DELETE),SPACE=(TRK,(2,5)),
DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB,DSORG=PS)
UNIT=SYSDA,DISP=(NEW,DELETE),SPACE=(TRK,(2,5)),
DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB,DSORG=PS)
UNIT=SYSDA,DISP=(NEW,DELETE),SPACE=(TRK,(2,5)),
DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB,DSORG=PS)

SCLM Macros:
FLMLANGL
FLMTRNSL

LANG=HURRA
COMPILE=MBS,FUNCTN=BUILD,PORDER=0

FLMALLOC
FLMCPYLB
FLMALLOC
FLMCPYLB
FLMALLOC
FLMCPYLB
FLMALLOC
FLMALLOC
FLMALLOC

IOTYPE=A,DDNAME=SYSIN
NULLFILE
IOTYPE=A,DDNAME=INPUT
SCLM41.DEV1.SOURCE(mbr)
IOTYPE=A,DDNAME=OUTPUT
SCLM41.DEV1.SOURCLST(mbr)
IOTYPE=W,DDNAME=SYSUT1,LRECL=80,RECFM=FB,RECNUM=1000
IOTYPE=W,DDNAME=SYSUT2,LRECL=80,RECFM=FB,RECNUM=1000
IOTYPE=W,DDNAME=SYSUT3,LRECL=80,RECFM=FB,RECNUM=1000

26.15 Method Example for Translator PMO


SCLM-Macros:
FLMTRNSL

COMPILE=PMO,FUNCTN=BUILD,PORDER=0

FLMALLOC

IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB,
DDNAME=INPUT
IOTYPE=O,KEYREF=LIST,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=OUTPUT

FLMALLOC

CC Archdef
SINC
LIST

292

ISPF/SCLM V4 Guide

mbr
mbr

SOURCE
SOURCLST

26.16 Method Example for Translator BHC


SCLM Macros:
FLMTRNSL

COMPILE=BHC,FUNCTN=BUILD,PORDER=0

FLMALLOC IOTYPE=I,KEYREF=SINC,DDNAME=SYSLIB
FLMCPYLB SYS1.TEST.MACLIB
FLMCPYLB SYS1.MACLIB
FLMALLOC IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB,
DDNAME=INPUT
FLMALLOC IOTYPE=O,KEYREF=LIST,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=OUTPUT

CC Archdef
SINC
LIST

mbr
mbr

SOURCE
SOURCLST

26.17 Method Example for Multiple Translators


SCLM Macros:
FLMTRNSL

COMPILE=DEF1,FUNCTN=BUILD,PORDER=0

FLMALLOC

IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB,
DDNAME=INPUT
IOTYPE=O,KEYREF=LIST,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=OUTPUT

FLMALLOC

FLMTRNSL

COMPILE=DEF2,FUNCTN=BUILD,PORDER=0

FLMALLOC
FLMALLOC

IOTYPE=U,DDNAME=INPUT
IOTYPE=O,KEYREF=LIST,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=LISTING

CC Archdef
SINC
LIST

mbr
mbr

SOURCE
SOURCLST

Chapter 26. Workshop Foils

293

26.18 Method Example for Translator DEF1 and DEF2


SCLM Macros
FLMTRNSL

COMPILE=DEF1,FUNCTN=BUILD,PORDER=0

FLMALLOC

IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB,
DDNAME=INPUT
IOTYPE=O,KEYREF=OUT8,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=OUTPUT

FLMALLOC

FLMTRNSL

COMPILE=DEF2,FUNCTN=BUILD,PORDER=0

FLMALLOC
FLMALLOC

IOTYPE=U,DDNAME=INPUT
IOTYPE=O,KEYREF=OUT6,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=LISTING

CC Archdef
SINC
OUT6
OUT8

mbr
mbr
MEMBERX

SOURCE
SOURCLST
ERRORLST

26.19 Method Example for Translator with Parameters


SCLM Macros:
FLMTRNSL

COMPILE=DEF1,FUNCTN=BUILD,PORDER=1

FLMALLOC
FLMALLOC

IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB,
DDNAME=INPUT
IOTYPE=O,KEYREF=OUT8,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=OUTPUT

FLMTRNSL

COMPILE=DEF2,FUNCTN=BUILD,PORDER=1

FLMALLOC
FLMALLOC

IOTYPE=U,DDNAME=INPUT
IOTYPE=O,KEYREF=OUT6,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=LISTING

CC Archdef
SINC
OUT6
OUT8
PARM

294

ISPF/SCLM V4 Guide

mbr
SOURCE
mbr
SOURCLST
MEMBERX ERRORLST
XXX,AAAA

26.20 Method Example for Translator with Option List


SCLM Macros:
FLMTRNSL

COMPILE=DEF1,FUNCTN=BUILD,PORDER=1,PARMKWD=PARM4

FLMALLOC
FLMALLOC

IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB,
DDNAME=INPUT
IOTYPE=O,KEYREF=OUT8,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=OUTPUT

FLMTRNSL

COMPILE=DEF2,FUNCTN=BUILD,PORDER=1,PARMKWD=PARM7

FLMALLOC
FLMALLOC

IOTYPE=U,DDNAME=INPUT
IOTYPE=O,KEYREF=OUT6,RECNUM=5000,LRECL=133,RECFM=VBA,
DDNAME=LISTING

CC Archdef
SINC
OUT6
OUT8
PARM4
PARM7

mbr
SOURCE
mbr
SOURCLST
MEMBERX ERRORLST
XXX,AAAA
XXX,QQQQ

26.21 The Promote Process


D E V E L O P M E N T C Y C L E

AUTOMATION

SCLM edit

change
H manipulate
Prod

part

Parse
I and

Integr.

Speichern

good


Dn

D2

Integrate M/C/S

I BUILD I
Developm

good

or

I
I TEST

good

1) Repeat cycle in next

see 1)

level of hierarchy
I PROMOTE

goodH Changes integrated

Chapter 26. Workshop Foils

295

26.22 Create / Change a Part


Menu RefList

RefMode SCLM Utilities Help


------------------------------------------------------------------------------SCLM Edit - Entry Panel
Command ===>
SCLM Library:
Project . .
Group . . .
Type . . .
Member . .

: SCLM41
Alternate - FLM
: HASINGH . . . TEAM
. . . INTE
. . . TEST
. SOURCE
.
(Blank or pattern for member selection list)

Initial Macro . .
Profile Name . . .

(If blank, defaults to data set type)

Enter / to select option


/ Confirm Cancel/Move/Replace
Mixed Mode
Change code . . . . . . FLM
Authorization code . .
Parser volume . . . . .

F1=Help
F2=Split
F10=Actions F12=Cancel

(If blank, the default auth code is used)


(If blank, the default volume is used)
F3=Exit

F7=Backward F8=Forward

F9=Swap

26.23 SCLM Edit Profile


MEMBER:

FLM01MD1 --------- SCLM EDIT PROFILE ---------------------------------COMMAND ===>

Type desired values, then press Enter.


Enter CANCEL command to exit without processing the member.
LANGUAGE
===> ASMH
CHANGE CODE ===> CCNUMBER

(Use = to retrieve last entry)

TUTORIAL

--------------------- VALID LANGUAGES ----------------------- TUTORIAL


COMMAND ===>

The following languages are valid for Project prjid


ARCHDEF

296

ISPF/SCLM V4 Guide

ASMH

PLIO

26.24 Draw Down Part FLM01EQU

RELEASE

FLM01AP1 FLM01EQU FLM01MD1 FLM01MD1 FLM01MD1


FLM01ARH FLM01MD1 FLM01MD2 FLM01MD2 FLM01MD2
FLM01CMD FLM01MD2 FLM01MD3 FLM01MD3 FLM01MD3
FLM01LD1 FLM01MD3 FLM01MD4 FLM01MD4 FLM01MD4
FLM01LD2 FLM01MD4 FLM01MD5 FLM01MD5 MAIN1
FLM01LD3 FLM01MD5 FLM01MD6 FLM01MD6 MAIN2
FLM01LD4 FLM01MD6
FLM01SB1
FLM01SB2


SOURCLST LOAD
ARCHDEF SOURCE OBJ

TEST

SOURCLST LOAD
ARCHDEF SOURCE OBJ

DEV1

DEV2

FLM01EQU

SOURCLST LOAD
ARCHDEF SOURCE OBJ
ARCHDEF SOURCE OBJ
SOURCLST LOAD

26.25 Architecture Definitions


SCLM's Software Configuration = Define Architecture Definition
How must a part be treated?
Which parts belong together?
SCLM has an own architecture definition language.
Functions of Architecture Definitions
Group Parts in HL, LEC, CC, and Generic Architecture Definitions:
Programs
Maps
DB-parts
Comments
Structure Archdefs
etc.
Link edit objects to loadmod
Overwrite standard language options for CC or LEC plans.
Define another output type as predefined in language definition.

Chapter 26. Workshop Foils

297

26.26 Some Archdef Commands


LKED

Link Edit Command

LOAD

Name of load module

INCL

Reference to another plan

COPY

Copy other plans

INCLD

Refer to (and execute) source parts

CMD

Command to Linkage Editor

ALIAS

Define an alias for load module

SINC

Include source part

PROM

Promote parts without executing

26.27 Archdefs of SCLM Sample


LEC
CC

FLM01LD1FLM01CMD FLM01MD1
HL


FLM01SB1

LEC

FLM01LD2 FLM01MD2

HL

LEC

FLM01AP1


FLM01LD3 FLM01MD3

HL

FLM01MD5



FLM01ARH
FLM01SB2

FLM01MD6

FLM01LD4 FLM01MD4

LEC

298

ISPF/SCLM V4 Guide

26.28 Build an Application


BUILD = compile, link edit, format, - what ever
BUILD possible for:

Architecture definition

Source part

Delta Build: Only necessary compiles and such will be executed

Menu SCLM Utilities Jobcard Help


-------------------------------------------------------------------------------SCLM Build - Entry Panel
Command ===>
Build input:
Project .
Group . .
Type . . .
Member . .

:
.
.
.

SCLM41
Alternate - FLM
HASINGH
archdef
Enter / to select option
flm01ap1
/ Error Listings only

Mode . . 1 1.
2.
3.
4.
Output control:
Ex
Messages . . 3
Report . . . 3
Listings . . 3

Conditional
Unconditional
Forced
Report

Scope . . . 2 1.
2.
3.
4.

Sub
3
1. Terminal
3
2. Printer
3
3. Dataset
4. None

Process . . 1 1. Execute
2. Submit

F1=Help
F2=Split
F10=Actions F12=Cancel

F3=Exit

Limited
Normal
Subunit
Extended

Printer . . H
Volume . .
F7=Backward F8=Forward

F9=Swap

Chapter 26. Workshop Foils

299

26.29 Build of Archdef FLM01SB1


FLMCMD BUILD,prjid,,DEV1,ARCHDEF,FLM01SB1

FLM01SB1


FLM01LD1 FLM01CMD FLM01MD1 FLM01MD1
Typ:
ARCHDEF H

H
H

Typ:
Typ:
Typ:
Typ:
ARCHDEF ARCHDEF OBJ
LOAD

LIST



FLM02MD2 FLM01MD1
FLM02LD2
H
H
H

Typ:

Typ:
Typ:
ARCHDEF
OBJ
LOAD


LIST

26.30 Build with Plan FLM01AP1

RELEASE

FLM01AP1 FLM01EQU FLM01MD1 FLM01MD1 FLM01MD1


FLM01ARH FLM01MD1 FLM01MD2 FLM01MD2 FLM01MD2
FLM01CMD FLM01MD2 FLM01MD3 FLM01MD3 FLM01MD3
FLM01LD1 FLM01MD3 FLM01MD4 FLM01MD4 FLM01MD4
FLM01LD2 FLM01MD4 FLM01MD5 FLM01MD5 MAIN1
FLM01LD3 FLM01MD5 FLM01MD6 FLM01MD6 MAIN2
FLM01LD4 FLM01MD6
FLM01SB1
FLM01SB2

SOURCLST LOAD
ARCHDEF SOURCE OBJ

TEST

SOURCLST LOAD
ARCHDEF SOURCE OBJ

DEV1

DEV2

FLM01MD1 FLM01MD1 FLM01MD1


FLM01MD3 FLM01MD3 FLM01MD3
FLM01MD4 FLM01MD4 FLM01MD4

FLM01MD5 FLM01MD5 MAIN1
FLM01MD6 FLM01MD6
FLM01EQU

ARCHDEF SOURCE OBJ


SOURCLST LOAD
ARCHDEF SOURCE OBJ
SOURCLST LOAD

EDIT
H TEST H EXAMINE
II

300

ISPF/SCLM V4 Guide

H OK H PROOF M (MODULE) CREATE

H PROMOTE

26.31 Language Definitions Versus Architecture Definitions


External Aspect:
Create Project Views and Project Skills
Types

Language Definition

..
ARCHDEF
ASMH
PLI
..

Parts have
Projec View:
H prjid.PROJDEFS.LOAD
associated Methods
Member prjid

...
ARCHDEF
ASMH
PLI
...

Project Data Base

Internal Aspect: Work with


Archdef

Project Views

Skills

(Methods)


and Archdefs
Archdef

Association of Methods when EDIT/SAVE or MIGRATE.


Association recorded in account records.
Types may have parts with different language definitions.
Architecture definitions are just source.

26.32 PROMOTE an Application


PROMOTE is done from bottom level to top level according to project view.
PROMOTE is possible for architecture definition and source part.
All scoped parts will be promoted, that is, source, object, load, and such

Menu SCLM Utilities Jobcard Help


-----------------------------------------------------------------------------SCLM Promote - Entry Panel
Command ===>
Promote input:
Project . . .
From group .
Type . . . .
Member . . .

:
.
.
.

SCLM41
HASINGH
ARCHDEF
FLM01AP1

Alternate - FLM

Mode . . 1 1. Conditional
2. Unconditional
3. Report

Scope . . . 1 1. Normal
2. Subunit
3. Extended

Output control:
Ex Sub
Messages . . 3 3
1. Terminal
Report . . . 3 3
2. Printer
3. Dataset
4. None

F1=Help
F2=Split
F10=Actions F12=Cancel

F3=Exit

Process . . 1 1. Execute
2. Submit
Printer . . H
Volume . .
F7=Backward F8=Forward

F9=Swap

Chapter 26. Workshop Foils

301

26.33 PROMOTE with Source Part


FLMCMD PROMOTE,prjid,DEV1,SOURCE,FLM01MD3

RELEASE

FLM01AP1 FLM01EQU FLM01MD1 FLM01MD1 FLM01MD1


FLM01ARH FLM01MD1 FLM01MD2 FLM01MD2 FLM01MD2
FLM01CMD FLM01MD2 FLM01MD3 FLM01MD3 FLM01MD3
FLM01LD1 FLM01MD3 FLM01MD4 FLM01MD4 FLM01MD4
FLM01LD2 FLM01MD4 FLM01MD5 FLM01MD5 MAIN1
FLM01LD3 FLM01MD5 FLM01MD6 FLM01MD6 MAIN2
FLM01LD4 FLM01MD6
FLM01SB1
FLM01SB2

ARCHDEF SOURCE OBJ


SOURCLST LOAD

TEST


FLM01MD3 FLM01MD3 FLM01MD3 FLM01MD3



SOURCLST LOAD

ARCHDEF SOURCE OBJ

DEV1

DEV2

SOURCLST LOAD
ARCHDEF SOURCE OBJ
SOURCLST LOAD
ARCHDEF SOURCE OBJ

26.34 PROMOTE with Plan FLM01AP1

RELEASE

FLM01AP1 FLM01EQU FLM01MD1 FLM01MD1 FLM01MD1


FLM01ARH FLM01MD1 FLM01MD2 FLM01MD2 FLM01MD2
FLM01CMD FLM01MD2 FLM01MD3 FLM01MD3 FLM01MD3
FLM01LD1 FLM01MD3 FLM01MD4 FLM01MD4 FLM01MD4
FLM01LD2 FLM01MD4 FLM01MD5 FLM01MD5 MAIN1
FLM01LD3 FLM01MD5 FLM01MD6 FLM01MD6 MAIN2
FLM01LD4 FLM01MD6
FLM01SB1
FLM01SB2

SOURCLST LOAD
ARCHDEF SOURCE OBJ

TEST

FLM01MD1 FLM01MD1 FLM01MD1


FLM01MD3 FLM01MD3 FLM01MD3 EXAMINTE PROOF M H OK
FLM01MD4 FLM01MD4 FLM01MD4
PROOF K I
FLM01MD5 FLM01MD5 MAIN1
H PROMOTE
FLM01MD6 FLM01MD6

PROOF M H NOK

NO ACCEPT I

TO DEVELOPER
FLM01EQU

ARCHDEF SOURCE OBJ


SOURCLST LOAD

DEV1

DEV2

ARCHDEF SOURCE OBJ


SOURCLST LOAD
ARCHDEF SOURCE OBJ
SOURCLST LOAD

302

ISPF/SCLM V4 Guide

26.35 Multiple Releases in Parallel

D
E
V
E
L
O
P

Concatenate Fixes

prjid1 to n


Baseline Rx.1
PROD
PROD

/ AC=,
AC=GLO
/ AC=,
Rx.2

prjid3(GLO)
prjid2(FIX)
TEST
Maintenance Rx.2

APLY
APLY
AC=prjid qa
NK
NK AC=FIX
Rx.3
/ AC=,

INTE

qaGLOBAL
qafix
AC=prjid

AC=GLO
AC=FIX
MENT

TEAM
LO

CALS dev

developer
devGLOBAL
devfix
AC=GLO
AC=FIX

Fixes
change the productive release, that is, Rx.1
Globals
are cross project functions
Maintenance are changes against the systest release, that is, Rx.2
Development represents the next release, that is, Rx.3
Locals
(or project globals) are subproject cross functions
The whole setup requires role management and separated account files.

26.36 Tips and Conclusions


BUILD

Scope: always NORMAL (Non-ADA)

Mode : always CONDITIONAL or REPORT

Always with Architecture definition

PROMOTE

Scope: always NORMAL

Mode : always CONDITIONAL or REPORT

Before promoting, a build should have been done with an architecture


definition of greatest scope.

Chapter 26. Workshop Foils

303

26.37 SCLM Invocation


Through general program interface (API)
Batch Invocation:

ISPF Version 3.1: TSO-Batch

ISPF Version 3.2, 3.3: ISPF-Batch

Invocation in:

Program (PL/1, COBOL, Pascal, FORTRAN): FLMLNK

CLIST or REXX-Procedure: FLMCMD

TSO/E native: FLMCMD

From SCLM panels with SUB command

From batch job

26.38 SCLM Services


BUILD
DBACCT
DBUTIL
DELETE
DELGROUP
END
EXPORT
FREE
IMPORT
INIT
LOCK
MIGRATE
PARSE
PROMOTE
RPTARCH
SAVE
START
STORE
UNLOCK

304

ISPF/SCLM V4 Guide

BUILD a part
Read Account Record
Create customizable reports of SCLM data base
Delete part
Delete members, and their meta data of a defined group
End SCLM session
Export account records
Free SCLM id
Import account records
Init an SCLM id
Lock part
Migrate part
Parse part
Promote part
Create architecture report
Save part
Start SCLM Service Session
Store account record
Unlock part

26.39 Conversion Views

RELEASE
Project
KEY=Y
View

TEST
KEY=Y

DEV1
DEV2
KEY=Y
KEY=Y

Alternate

RELEASE
Project

KEY=Y
View

Alternate

RELEASE
Project

KEY=Y
View

TEST

KEY=Y

26.40 Pilot Project


Workshop
Small Applications
All Compilers and Subsytems
Promote process customization
Test functions

26.41 Authorization Codes


Freeze changes of a part to a defined group
Multi baseline
Delimit areas of application developement

FLM01MD1/A PROD
FLM01MD2/A
FLM01MD3/A A,B
FLM01MD4/B
FLM01MD5/B
FLM01MD6/B

TEST

A,B

INTEGRATION

FLM01MD1/A A,B

DEV2

DEV3

DEV1
FLM01MD1/A
FLM01MD1/T
FLM01MD1/T
FLM01MD2/B B,T

A,T
FLM01MD2/T A,T
FLM01MD4/A
FLM01MD5/B

FIX
F

DEVFIX
F

Chapter 26. Workshop Foils

305

26.42 Export / Import


1. Define project definition for receiving project.
Language definitions must be consistent.
Types must be consistent.
Groups and project name must not be consistent.
2. Create data sets for receiving project.
3. Export wanted application account records in an own, separated export data
set (must be defined through FLMCNTRL macro).
4. Copy all data (not just source) to receiving project.
5. Import all (exported) account records in receiving project.

26.43 SCLM and Test Methods - Scenario


1. Prepare program for:
Test or
Production
2. Conclusion:
A Test-Program may not be promoted (beyond a defined group).
A Prod-Program cannot be interactively tested.
Programs not under SCLM control may not be allowed.
3. Scenario:
a. It must all be transparent to the developer.
b. The SCLM project manager must solve the problem.
c. Quality assurance requires revision ability.
d. The solution must be transparent to all involved.

306

ISPF/SCLM V4 Guide

26.44 SCLM and Methods with Test Options


Project View
Alternate Project View

1a

PROD

PROD'

(AC=)

/
Method=COB2
Method=COB2
VERSION=COB2V1.0
VERSION=COB2TEST
OPTIONS=(NOTEST,..)
OPTIONS=(TEST,..)

2a
2

SYSTEST

SYSTEST'

(AC=)

/

2I3a

3a

3
TEST

TEST'



4
4
4

4a
4a
4a

DEV1 DEV2 DEV3


DEV1' DEV2' DEV3'


Result:
1) OK: 4I1 or 4aI1a DRAWDOWN Module
2) OK: 4a
BUILD Test Application/H COBTEST / H SATT
3) OK: 4aH3a
PROMOTE. Test Application/ check
H SATT
NOK
Further PROMOTE to 2a and 1a locked.
NOK 3a crosses 3 and PROMOTE without REBUILD not possible
4) OK: 3
REBUILD. MemberVersion increases by 1.
PROMOTE
5) OK: 3H2H1
6) OK: 4 REBUILD and 4H3H2H1 as Alternative to 2) till 5)

Chapter 26. Workshop Foils

307

308

ISPF/SCLM V4 Guide

Index
Special Characters
.RESP 129
.TYPE 129
.WINDOW 130
)PNTS 131
< a b > 129
< b o t i n s t > 127
< d t a f l d d > 127
< m s g > 131
< p s > 132
< t o p i n s t > 127

Numerics
3270 Environment
action bar 86
function key defaults 89
hardware terminals 85
input-fields 69
residual session in GUI 118
using CM Mouse 90

A
AB attribute type 127
ab tag 129
ABSL attribute type 127
AC Limits
accounting 153
Action Bars 128
ABAR 45
action bar pull-downs 8
changing 45
disabling in edit only 147
DTL tag definitions 39
Hilite Disabled 45
in 3270 mode 86
non-tabable 41
removing 42
ADDPOP 124, 125, 129
Agreement
AC 165
Audit Record 201
Build Map Record 201
Delta Reverse 200
Methods 179
Versioning 195
Agreements
Development 195
Edit 174
Fix 195
Maintenance 195
APPC
configuring for OS/2 103

Copyright IBM Corp. 1994

APPC (continued)
control point 103
performance of 120
quick configure 98

C
Calendar 77
CEF attribute type 127
CH attribute type 127
Change Control
CCV Example Implementation 211
CCV must be 211
CCV to INFO/Mgmt. possible 211
character attribute override 136
checkboxes 133
CKBOX(ON) 133
CM Mouse
BDF and MMM examples 92
CM Mouse pop-ups 91
CM Mouse with ISPF 4.1 90
Color
CUA Attributes 71
edit hilite 15
Global Colors 71
language sensitive editing 15
point-and-shoot 70
Configuring
APPC for CM/2 103
TCP/IP for OS/2 99
Control
at BUILD 206
at edit 206
at PROMOTE 206
Consistency 206
Delimitation 206
Example 207
Integrity 206
User Exits 206
CT attribute type 127
CUA attribute types 127

D
Data Set List Utility 24
Data Set Management
Developer Data Sets 168
Production Data Sets 166
Delivery
ABARS 213
Export/Import 213
Full Source 213
Netview 213
description of ISPF C/S 121

309

dialog boxes 129


Downloading GUI 110
DT attribute type 127
DTL
< a b > 129
botinst 127
dtafldd 127
location 131
msg 131
msgtype 131
padc 128
topinst 127

GUI (continued)
special considerations 116
split screen 118, 149
starting from an icon 148
tabbing 117
TSO commands 118
GUI parameter on ISPSTART 123
GUISCRD parameter on ISPSTART 125
GUISCRW parameter on ISPSTART 125

E
EDIT 153
Editor
Edit Primary Command 72
removing highlighting 147
EE attribute type 127
Enter key 126, 131
ET attribute type 127

F
FIELD statement in )PNTS 132
FKA command 126
Forward Retrieve
RETF 30
FP attribute type 127
FRAME parameter on ISPSTART
frames, window 125
function key area 131
Function Keys
accessing reflists 67
default 3270 89
Function Keys status 76
Global Colors 58
Tailoring Display 59
functions key area 126
functions keys 126

125

G
GDDM support 136
Graphical User Interface
See GUI
GUI
changing colors 119
connecting the MVS host 114
downloading to your PC 110
editor 149
entering workstation commands 118
getting around in 117
invoking workstation server 112
PC enter key 117
performance of 120
problems with 115
residual 3270 session 118

310

ISPF/SCLM V4 Guide

Icon for OS/2 workstation 113


Identification
BUILD 205
Parser 205
PROMOTE 205
ISPDTLC
dialog 42, 46
syntax 44, 46
ISPF
C/S terminology 98
command shell 19
configuration defaults 147
Keylist Definitions 48
setting 5
ISPF and the Future 148
Terminology 153
ISPF Command
FKA 60
ISPDTLC 42, 46
ISPFVAR 41
KEYLIST 49, 58
KEYS 50, 58
PFSHOW 59, 60
PSCOLOR 70
REFACTD 66
REFACTL 66
REFADDD 66
REFADDL 67
REFLISTD 66
REFLISTL 66
REFOPEND 66
REFOPENL 66
SETTINGS 41
ISPSTART 123, 125
ISPSTRT program 134
ISRCONFG, modifying 147

J
Jump from leader dots

K
Keylist
change 53
create 50
creating 63

Keylist (continued)
delete 54
DTL tag definition 55
ISPFKEYS 48
ISPKYLST 57
ISPPROF 48
panel definition 57
Keylist Definitions
See ISPF
keylists 126

O
Overview
WSP/2 253

P
pad character 128
PADC 128
PAS 131
Performance Issues 120
PF keys
See Function Keys
PIN attribute type 127
Pinging the host 116
Point-and-Shoot
input-fields 69
noninput fields 69
user point-and-shoot 81
Point-and-Shoot Fields 9, 131
pop-up windows 129
PREFIX parameter on FKA command 126
PRINTDS Command 7
Project Control
CCM Overview 163
Hierarchy 169
Meta Project 164
Protection through AC 165
SCLM Project Manager's Basic Rules 164
Security through RACF 164
Project Management Environment
ISPF Systemdata set concatenation 159
ISPLLIB Data Set Concatenation 159
SYSEXEC Data Set Concatenation 159
SYSPROC Data Set Concatenation 159
TSO Systemdata sets 159
PS attribute type 128, 132
ps tag 132
PT attribute type 128
pull-down menus 128
push buttons 126, 131

L
LEF attribute type 127
LI attribute type 127
LIBDEF
dialog query LIBDEF facility 35
display utility 36
search order for ISPLLIB 37
stack facility 33
library management 153
LID attribute type 127
line-mode output 136
LU 6.2
See APPC

M
Management
Account records 206
Audit records 206
Build map records 206
Mapping File
EPFMAPM.DAT 254
EPFMAPV.DAT 254
Member Selection List 10
message boxes 129
Message ID 29
Meta Project
Simple Implementation 221
Microsoft Windows
configuring TCP/IP 107
hang with FTP 108
MNEM 129
mnemonics 129
modal dialogs 129
modeless dialogs 134
Mouse in 3270
See CM Mouse
multipmt 133
Multivolume Data Set Support 27

N
NEF attribute type 127
NOPREFIX parameter on FKA command
NT attribute type 127

126

RACF Protection
reasons for using ISPF C/S 121
Referral List
definition 61
personal lists 61
reference lists 61
RefMode 61
shared list 65
Referral Lists 10
RefList
See Referral List
Retrieve Pop-Up
RETP 31
Role Management
SCLM Project Manager 174

Index

311

Role Management (continued)


SW Configurator 174
SW Developer 174
SW Manager 174
through Project View 175
Role-Management
implement 176
SW Configurator 174, 175
SW Manager 174
RP attribute type 128

TSO
handling output 118, 148
printds command 148
TSO Commands
ELISTA 159
LISTA ST H 159

U
User Status

SAC attribute type 128


sample screens 122
SCLM 153, 155
Concepts 153
Option 10 157
VSAM file 153
SCLM Example
TSO Environment 159
SCLM Project Manager
Tasks 158
SCLM Terminology
Accounting 153
Architecture Definition 154
build 153, 155
Configuration management 153, 154
group 154
hierarchies 154
language 154
library 154
method 153
processing scope 155
project 154
project database 154
promote 153, 155
types 154
SELECT WSCMD 135
Server Alias Names
EHORUNS 254
EHOXFER 254
SI attribute type 128
split screen 134
Split Screen in GUI 118
START service 134
SUC attribute type 128

T
TCP/IP
configuring for OS/2 99
performance of 120
quick configure 98
title bar text 124
TITLE parameter on ISPSTART
Tool Integration 207
Transmission Control Protocol
See TCP/IP

312

ISPF/SCLM V4 Guide

124

80

View Facility 13
VOI attribute type 128
VSAM
building a profile data set 22
changing a profile data set 24
using a profile data set 23
VSAM file 153
VTAM definitions 103

W
WASL attribute type 128
window frames 125
WINDOW parameter on )BODY statement
Windows (Microsoft)
See Microsoft Windows
WINSOCK.DLL problem 110
workstation command interface 135
WSCMD 135
WT attribute type 128

Z
ZAPPTTL 124
ZGUI 124, 133
ZPF variables 126
ZWINTTL 124

125

Printed in U.S.A.

GG24-4407-00

You might also like