SG 246111

Front cover
IBM VisualAge COBOL

Remote Edit/Compile/Debug
Taking COBOL to the Next Level!
Have fun while developing and

maintaining COBOL programs
Exploit the advantages of

mainframe and workstation
Enhance your COBOL

coding productivity
Andrea Conzett
Karl Bender
Scott Davis
Veronique Quiblier
Henk van der Wijk
ibm.com/redbooks
International Technical Support Organization
IBM VisualAge COBOL

Remote Edit/Compile/Debug:
February 2002
SG24-6111-00
Take Note! Before using this information and the product it supports, be sure to read the
general information in “Special notices” on page xiii.
First Edition (February 2002)
This edition applies to Version 3 of IBM VisualAge COBOL for use with the Windows NT or
Windows 2000 operating system
Comments may be addressed to:

IBM Corporation, International Technical Support Organization
Dept. QXXE Building 80-E2
650 Harry Road
San Jose, California 95120-6099
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 2002. 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.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
IBM trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Chapter 1. Executive overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.1 Scenario 1: host offloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.2 Scenario 2: host offloading with remote data access . . . . . . . . . . . . . 5
1.2.3 Scenario 3: remote development . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 2. Component connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2 Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 3. System connection definitions . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.2 Using the MVS Connections Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2.1 Host and user definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.2.2 Data transfer definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2.3 Port definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2.4 Data set filter definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.2.5 File mapping definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Chapter 4. Project definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... .. 33

4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... .. 34
4.2 Starting the IBM VisualAge COBOL Projects Wizard . . . . . . . . ...... .. 34
4.3 Opening an existing project. . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... .. 35
4.4 Creating a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... .. 37
4.4.1 Connection properties are not defined . . . . . . . . . . . . . . . ...... .. 38
© Copyright IBM Corp. 2002 iii

4.4.2 Connection properties are defined . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 5. WorkFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.1 WorkFrame elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.1.1 Project toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.1.2 Menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.1.3 File filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.1.4 Project container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.1.5 Project monitor and command window . . . . . . . . . . . . . . . . . . . . . . . 57
5.2 WorkFrame views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.2.1 Tree view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.2.2 Icon view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.2.3 Details view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.3 Change project settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.3.1 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.3.2 Environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.3.3 Additional settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.4 WorkFrame actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.4.1 Create your own actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Chapter 6. Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.2 Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.3.1 Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.3.2 Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.3.3 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.3.4 Insert SQL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 7. Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.2 Compiler options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.3 Local syntax check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.4 Compilation on the host. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Chapter 8. Job Monitor and TSO Commands server . . . . . . . . . . . . . . . . . 85

8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
8.2 Job Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
8.2.1 Submitting jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
8.2.2 Managing job spooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
8.3 TSO Commands server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.3.1 TSO Commands window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.3.2 Add a TSO command action to your project . . . . . . . . . . . . . . . . . . . 94
iv IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
Chapter 9. Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
9.2 What can be debugged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
9.3 Overview of debugging setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9.4 Setting up your workstation for remote debugging . . . . . . . . . . . . . . . . . 102
9.5 Preparing your program for debugging . . . . . . . . . . . . . . . . . . . . . . . . . . 104
9.5.1 Using the sidefile option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
9.5.2 Preparation for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
9.5.3 Preparation for IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
9.6 Debug a CICS program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
9.6.1 Using DTCN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.7 Debugging an IMS online program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.7.1 Using CEEROPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.7.2 Using CEEUOPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.8 Debug a batch program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.9 Debugging a TSO foreground program . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.10 Debugging a DB2 program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.10.1 DB2 batch program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.10.2 DB2 Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.11 Using the Distributed Debugger user interface . . . . . . . . . . . . . . . . . . . 119
9.11.1 Menu options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.11.2 Source listing pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.11.3 Control pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.11.4 Value pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
9.11.5 Debugging an exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Appendix A. Sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Compile JCL for debugging (general) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Compile JCL using sidefile option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Compile JCL for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
DTCN transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
CEEUOPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Compile JCL for IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
With CEEROPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
With CEEUOPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
CEEROPT module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
CEEUOPT module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Debug a batch program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Debug a DB2 batch program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
DB2 WLM startup procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Appendix B. The Debug Tool and TCP/IP in CICS . . . . . . . . . . . . . . . . . . 151

Customizing for the Debug Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Contents v
Updating the CICS system definition (CSD) for Debug Tool. . . . ...... . 152
Updating the CICS startup job . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . 153
Updating the CICS authorized library . . . . . . . . . . . . . . . . . . . . . ...... . 153
Installing and customizing TCP/IP sockets in CICS . . . . . . . . . . . . . ...... . 154
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 159

IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 159
Other resources . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 159
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 159
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 159
IBM Redbooks collections . . . . . . . . . . . . . . . . . ...... ....... ...... . 160
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
vi IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
Figures
1-1 VisualAge COBOL WorkFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1-2 MVS Connections Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1-3 Parsing editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1-4 Development cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1-5 Workstation compile error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1-6 Job Monitor window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1-7 TSO Commands window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1-8 Enterprise debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2-1 Remote E/C/D components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3-1 MVS connections definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3-2 Connection Properties window, Host and User tab . . . . . . . . . . . . . . . . 24
3-3 Password prompt for MVS connection. . . . . . . . . . . . . . . . . . . . . . . . . . 25
3-4 Connection Properties window, Data Transfer tab . . . . . . . . . . . . . . . . 26
3-5 Connection Properties window, Ports tab . . . . . . . . . . . . . . . . . . . . . . . 27
3-6 Directory Properties window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3-7 Local and host file mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3-8 Mapping Properties window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4-1 VisualAge COBOL Projects window . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4-2 Browse for an Existing Project window . . . . . . . . . . . . . . . . . . . . . . . . . 36
4-3 Create New Project window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4-4 Remote System Not Set Up message . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4-5 Enter a project name window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4-6 Enter project folder information window . . . . . . . . . . . . . . . . . . . . . . . . . 40
4-7 No MVS System Connected message. . . . . . . . . . . . . . . . . . . . . . . . . . 41
4-8 Browse for a Source Folder window . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4-9 Browse MVS directories window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4-10 Select source folders window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4-11 Project Folder Information window with source directories . . . . . . . . . . 45
4-12 Folder Not Found message window . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4-13 Environment variables pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4-14 Edit Environment Variable window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4-15 Change Default Settings message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4-16 Project Created message window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5-1 WorkFrame window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5-2 The WorkFrame file filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5-3 WorkFrame view with only source files . . . . . . . . . . . . . . . . . . . . . . . . . 55
5-4 The possible actions on a COBOL source member. . . . . . . . . . . . . . . . 56
5-5 The possible actions on a JCL member. . . . . . . . . . . . . . . . . . . . . . . . . 56
© Copyright IBM Corp. 2002 vii

5-6 WorkFrame icon view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5-7 WorkFrame details view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5-8 Detailed view of columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5-9 Project settings notebook - directory page. . . . . . . . . . . . . . . . . . . . . . . 61
5-10 Project settings notebook - environment variables page . . . . . . . . . . . . 62
5-11 Tools Setup window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5-12 Add Action notebook, General page . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5-13 Add Action notebook, Types page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6-1 FFS architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6-2 Automatic filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6-3 LPEX Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6-4 Context sensitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6-5 Insert SQL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6-6 Graphical compare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
7-1 Compile options notebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7-2 Run local compile from editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7-3 Compile error feedback in WorkFrame . . . . . . . . . . . . . . . . . . . . . . . . . 81
7-4 Compile error feedback in the editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
8-1 Job submitted message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
8-2 Job Completed message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
8-3 Submit JCL window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
8-4 Select JCL file window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
8-5 Submit temporary JCL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
8-6 Job Monitor job details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
8-7 Job Monitor view output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8-8 TSO command execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8-9 Add tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
8-10 Add Ask time action — General page . . . . . . . . . . . . . . . . . . . . . . . . . . 95
8-11 Add Ask time action — Support page . . . . . . . . . . . . . . . . . . . . . . . . . . 96
8-12 Action icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8-13 TSO Commands daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
9-1 Elements of a debugging session . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9-2 Remote Debugger — startup window . . . . . . . . . . . . . . . . . . . . . . . . . 103
9-3 IBM Distributed Debugger Daemon window . . . . . . . . . . . . . . . . . . . . 103
9-4 Debug Tool CICS Control - Primary Menu (example 1). . . . . . . . . . . . 107
9-5 Debug Tool CICS Control — Primary Menu (example 2) . . . . . . . . . . 108
9-9 Distributed Debugger window with CICS program. . . . . . . . . . . . . . . . 111
9-10 Distributed Debugger window with an IMS transaction . . . . . . . . . . . . 115
9-11 Multiple debugging sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9-12 Debugger file pulldown menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
viii IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
9-13 Application Preferences — Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9-14 Hover variable content display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9-15 Debugger profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9-16 Exception filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9-17 Debugger source pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9-18 Stacks control pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
9-19 Breakpoints control pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
9-20 Modules control pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
9-21 Monitors value pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
9-22 Storage value pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
9-23 Registers value pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
9-24 Mapping value pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
9-25 Application exception message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
9-26 Debug an exception — monitor variables . . . . . . . . . . . . . . . . . . . . . . 133
9-27 Debug an exception — fix the problem . . . . . . . . . . . . . . . . . . . . . . . . 134
Figures ix
x IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
Tables
7-1 Compiler options of interest for MVS projects . . . . . . . . . . . . . . . . . . . . 80
© Copyright IBM Corp. 2002 xi

xii IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
Special notices
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, North Castle Drive, Armonk, NY 10504-1785.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact IBM Corporation, Dept.
600A, Mail Drop 1329, Somers, NY 10589 USA.
Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.
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.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of these
Web sites.
© Copyright IBM Corp. 2002 xiii

IBM trademarks
The following terms are trademarks of the International Business Machines

Corporation in the United States and/or other countries:
e (logo)® IBM OS/400
Redbooks (logo)™ IMS S/390
AIX Language Environment S/400
AS/400 MQSeries SP
CICS MVS TXSeries
DB2 OS/2 VisualAge
DFS OS/390 z/OS
Other company trademarks

The following terms are trademarks of other companies:
C-bus is a trademark of Corollary, Inc. in the United States and/or other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of
Sun Microsystems, Inc. in the United States and/or other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft
Corporation in the United States and/or other countries.
PC Direct is a trademark of Ziff Communications Company in the United States and/or

other countries and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel

Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries licensed
exclusively through The Open Group.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by
SET Secure Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks of
others.
xiv IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
Preface
This IBM Redbook details the configuration and use of some of the features of
IBM VisualAge COBOL Version 3.
The vast majority of high level language applications, written in COBOL, PL/I, or
C, are running in an MVS or OS/390 environment. Such environments are very
specific, especially if subsystems like DB2, IMS, or CICS are involved. In
addition, the source code and test data for these applications are usually stored
and controlled on the mainframe system.
Therefore, so that the mainframe application programmer can use the modern
application development tools which are available to Java programmers, IBM has
added the capability to develop and maintain MVS applications to its COBOL
development environment for Windows NT.
The mainframe application programmer can now use VisualAge COBOL to edit,
compile, and debug an MVS application without even logging on to TSO.
Although the programmer is working in a workstation environment, the source
code remains on the mainframe and the program is running in its target
environment for debugging.
VisualAge COBOL provides a state-of-the-art graphical user interface for all the
tasks involved in the development and maintenance of mainframe applications,
including batch, DB2, CICS, and IMS applications. Also, using a modern
development environment to maintain and develop mission critical batch and
server applications can help a company to retain its skilled COBOL developers
while attracting talented new programmers who are familiar with similar tools
used in Java.
This book introduces you to various development scenarios. The first part of the
book explains how the Remote Edit/Compile/Debug model can help to increase
the productivity of an application developer. The second part of the book
describes the architecture in more detail, to help you understand how VisualAge
COBOL can fit into your environment and address your requirements. Although
written for VisualAge COBOL, this book can also be easily used as a reference
for VisualAge PL/I.
© Copyright IBM Corp. 2002 xv

The team that wrote this redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, San Jose Center.
Andrea Conzett was an Advisory Information Technology Specialist at the

IBM International Technical Support Organization, San Jose Center. He has
16 years of experience in application development from both IBM internal and
customer projects. He writes extensively and teaches IBM classes worldwide
on all areas of COBOL and PL/I application development. Andrea is currently
responsible for the worldwide sales and technical sales support for VisualAge
COBOL and VisualAge PL/I, as well as other IBM tools in the high level
languages area.
Karl Bender is an Advisory IT Specialist in IBM Germany. He has 13 years of

experience in the OS/390 and CICS applications field. His areas of expertise
include Language Environment for OS/390, CICS, COBOL, PL/I, and the Debug
Tool.
Scott Davis is with IBM Technical Sales in Germany. He has 17 years of

experience in the application programming field.
Veronique Quiblier is the Technical Sales Specialist for IBM EMEA located in La
Gaude /France. She has 16 years of experience in application development. Her
areas of expertise include COBOL, PL/I, CICS, and DB2.
Henk van der Wijk is a consultant at Delion in The Netherlands. He has 16

years of experience in the field of information technology. He holds a Masters
degree in Science, with a specialization in Knowledge Engineering. His areas of
expertise include mainframe environments, especially Web enablement of legacy
systems. Henk has been involved in the implementation and roll-out of VisualAge
COBOL at several customers in the financial industry and government.
Thanks to the following people for their contributions to this project:
Bob Haimowitz
International Technical Support Organization, Poughkeepsie Center
Barbara Price, Brent Hawks, Gary Mazo, Ira Sheftman, Sheila Sholars, Francisco
Anaya, Jean Nardi
IBM Santa Teresa Laboratory, San Jose, California
xvi IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
Notice
This publication is intended to help application development management,
application developers, and OS/390 system programmers to understand the
advantages of deploying a cooperative application development environment.
In addition, the use of VisualAge COBOL for the basic tasks of editing,
compiling, and debugging programs in such an environment are explained in
detail for reference. The information in this publication is not intended as the
specification of any programming interfaces that are provided by VisualAge
COBOL. See the PUBLICATIONS section of the IBM Programming
Announcement for VisualAge COBOL for more information about what
publications are considered to be product documentation.
Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments

about this or other Redbooks in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an Internet note to:
redbook@us.ibm.com
򐂰 Mail your comments to the address on page ii.
Preface xvii
xviii IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
1
Chapter 1. Executive overview

This chapter provides a conceptual overview which is aimed at management. It
describes the various scenarios supported by VisualAge COBOL and discusses
their advantages and disadvantages.
© Copyright IBM Corp. 2002 1

1.1 Introduction
Within the Application Framework from IBM, application development is
performed through the use of the IBM family of VisualAge tools. One of the
underlying concepts and advantages to a development shop with VisualAge is
that it maintains the VisualAge “same look-and-feel". Regardless of the
application language (C, COBOL, PL/I) — or even the development platform
(Windows NT, OS/2, OS/390) — the development environment tools will still look
and perform similarly.
Note: The availability of individual tools or technologies may vary because

different IBM laboratories are producing the tools which are implemented, when
applicable, in the various VisualAge packages.
1.2 Scenarios
VisualAge technology offers the COBOL developer three different scenarios with
which he can develop COBOL applications that are targeted to run in an OS/390
production environment:
򐂰 Scenario 1: Host offloading
򐂰 Scenario 2: Host offloading with remote data access
򐂰 Scenario 3: Remote development
All three of these scenarios were developed in response to the need to optimize
the use of the workstation. IBM has primarily concentrated on using the
workstation to improve the efficiency in the development of host applications.
These scenarios can be implemented separately, or can be mixed within:
򐂰 Companies
򐂰 Departments
򐂰 Workstations
Within this managerial summary, all scenarios are briefly explained. Later in the
book, we explain how companies can use VisualAge COBOL to remotely
develop and maintain their COBOL MVS / OS/390 applications with Version 3.
Regardless of which scenario a company chooses, the base for all VisualAge
COBOL development on the desktop is the WorkFrame, which provides the
environment for a development project. A project is the complete set of data and
actions needed to complete a programming task. All tools are integrated into the
WorkFrame, thus reducing the clutter and inefficiency of having different folders.
2 IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
An example of the VisualAge COBOL WorkFrame is shown in Figure 1-1.
Figure 1-1 VisualAge COBOL WorkFrame
One advantage of VisualAge COBOL is the ability for the customer to customize
the WorkFrame. It is very easy to integrate one’s own tools as well as data types.
1.2.1 Scenario 1: host offloading

The host offloading scenario is not new. Five to six years ago, it was the main
method of improving efficiency. In this scenario, it is a development requirement
that the necessary source files, as well as the application data, must be present
on the workstation. This scenario is emulation dependent, but allows developers
to develop COBOL applications on the workstation and to utilize the workstation
as the execution platform with the produced executables. This scenario naturally
allows companies to develop COBOL applications that will ultimately run on an
Intel platform.
Chapter 1. Executive overview 3

Under this scenario, however, the client platform can also be used as the
development platform, even though the production execution platform is different,
for example:
򐂰 AIX
򐂰 AS/400
򐂰 VSE
򐂰 MVS
򐂰 OS390
This scenario is reached by transferring the necessary source files, copybooks,

data definitions, to the workstation and building a mirror of your execution
environment on the workstation. The development on the workstation produces
an Intel executable and the test phase of the development cycle is carried out on
the workstation. After development test, files are transferred back to the
execution environment for compilation and link within the execution address
space.
Obviously, the host offloading scenario requires that the applicable middleware,
like CICS, DB2, or MQSeries, is installed and configured on the development
client. Also, while the COBOL language as such is compatible between the Intel
and OS/390 platforms, there are only a few date and time related Language
Environment (LE) callable services available with the COBOL compiler for
Windows. No other LE services are available on this client platform, because
there is no Language Environment on Windows. If a customer makes extensive
use of LE services, this might be an issue to consider when choosing a
development scenario.
Each development shop must decide for themselves whether having an

application test completed on the workstation will be sufficient for their needs. As
time has shown, many shops wish to test again within the address space of the
execution environment and the actual execution middleware.
Shortcomings
In many development shops, however, the size of test databases excludes the
use of the workstation as the development platform. Also, the fact that some
databases are not available on the workstation, for example IMS DB, prohibited
utilizing the workstation for these databases, and as such, for certain types of
application development on the workstation.
As mentioned earlier, if a test within the execution environment is wanted for final
confirmation, the logic of maintaining two test databases, one on the client and a
mirror on the execution platform, also brought shortfalls within the host offloading
scenario.
1.2.2 Scenario 2: host offloading with remote data access
To address the aforementioned points, IBM has provided, within VisualAge
COBOL, the capability to access data on the MVS host remotely. No longer does
a development shop need to maintain two databases. No longer is VSAM
emulation needed on the workstation. Also, it is no longer necessary to emulate
IMS or to limit development of applications requiring IMS DB access on the host.
This enabling technology, remote data access, is our second scenario. In this
scenario, the source files and copybooks are still required on the workstation. An
Intel based executable is still produced and is still tested on the workstation.
However, data is now accessed from MVS through an APPC connection.
To offer similar test results, VisualAge COBOL also offers, within the compiler
options, the possibility to treat the data within a platform that can be chosen:
򐂰 S/390
򐂰 Native
Development then has the choice to process data types as either high Endian or
low Endian, IEEE, or hex floating point format. The only data type that cannot be
chosen is pointers. Host pointers are 8 bytes and native (workstation) pointers
are 4 bytes. The remote data access scenario is thus the same as the host
offloading scenario, but simply leaves the data on the initial or execution platform.
Shortcomings
Database emulation within the first scenario, transactional emulation, or the
reliance of consistent middleware behavior between different platforms, has
certain pitfalls, however, which were voiced within the COBOL Advisory Council,
a group of IBM COBOL users.
Horror stories of preprocessor compile errors on the execution platform after a

successful test on the workstation only serve to epitomize the problem of having
a development environment and platform which are different than the application
execution platform. Other common problems were emulation software release
schedules not keeping pace with actual host software functionality, or the inability
to emulate the Language Environment. Companies even complained about the
need to have constant file transfers.
To address these issues, IBM has added to VisualAge the ability to implement a
different development model through the use of remote development technology.
This leads to the third scenario, which we will now describe.

1.2.3 Scenario 3: remote development
We refer to this final scenario, in which VisualAge COBOL can be used, as
remote edit/compile/debug, or remote development. In this scenario, all the
advantages offered from a workstation platform are leveraged while maintaining
the actual development location of the MVS / OS/390 host. Some advantages
include:
򐂰 Multi-threading (unlimited "sessions")
򐂰 Visually oriented
򐂰 Color capability
򐂰 Mouse oriented
򐂰 More flexibility
򐂰 Quicker development in newer technology and tools
Refer back to Figure 1-1 on page 3. The locations defined within WorkFrame are
actually partitioned data sets. Interfaces between standard OS/390 software,
VisualAge COBOL supplied host software, and VisualAge tools allow developers
to cover the main aspects of software development on their MVS or OS/390 host
from within the VisualAge COBOL environment on the workstation. A description
of this remote functionality is the basis of this redbook.
In addition to the shortcomings of the host offloading scenario, mentioned earlier,

several other customer complaints have also been resolved:
򐂰 COBOL developers in an offloading environment are over-tasked:
– COBOL developers are not CICS or DB2 administrators.
򐂰 Different development languages and platforms utilize different development
user interfaces; for example:
– Java on the workstation and COBOL on the host
– C++ on the workstation and COBOL on the host
򐂰 Data processing students (new hires) have learned data processing with the
aid of workstation tools.
򐂰 The development environment does not justify or leverage current workstation
hardware:
– For example, on a 300 MHz, 128 MB workstation, the primary
development tool is 3270 emulation.
򐂰 File transferring between host and workstation utilizes too many resources
and is too primitive.
The core task of software development consists of writing new program source or
changing existing source files. These files have to be compiled and linked
cleanly. After this, an application test needs to be performed.
VisualAge COBOL utilizes the newest in Java Framework based user interfaces,
giving the VisualAge "same look-and-feel". Developers are now guided through
the process of how to define and make their TCP/IP system connections and
map their partitioned data sets to virtual drives with classic wizards. The end
result is seen below in Figure 1-2. Natural for workstation tools, the information
presented here can also be changed using the right mouse button.
Figure 1-2 MVS Connections Manager
The foundation of this connection is an IBM-developed Foreign File System

(FFS) residing on the host and client. The FFS is delivered with VisualAge
COBOL. The transport medium, the only non-VisualAge COBOL software, is the
required OS/390 HTTP server, which is standard software for OS/390.
The concept of the FFS is similar to the UNIX-founded Network File Server
(NFS). Partitioned data sets are mapped to a virtual drive on the workstation.
Any attempt to find the file on the physical workstation will result in "File Not
Found". However, through this network filing system, we are now capable of
using workstation tools for mainframe development, without having to utilize FTP.

Editing
This means a company can now have all the benefits of modern workstation
editors, such as these:
򐂰 Token highlighting
򐂰 Mouse based
򐂰 Multiple views
򐂰 Lexical checking
But when the developer selects File—>Save in the editor, the save takes place
on the System/390 partitioned data set in the seamless environment. The editor
is a language parser, so if the developer opens a COBOL source, then the
COBOL parser is activated, as shown in Figure 1-3.
Figure 1-3 Parsing editor
Or, if the developer has mapped a JCL partitioned data set, then when the JCL is
opened, the JCL parser will automatically be activated. Note that it is just as easy
to customize the editor as it is to customize the WorkFrame.
One of the issues mentioned by the COBOL Advisory Council was how to take
the load off the host, or how to reduce the cycles needed. VisualAge COBOL
achieves this by giving the developer the ability to use the Windows-based
COBOL compiler on his FFS source for syntax checking. This results in an
almost massive reduction in number of submitted jobs on the System/390. It also
raises productivity because of its workstation base.
Development cycle
In a standard 3270 mode, a developer is in an edit session. To compile, he now
must swap screens to get to the JCL partitioned data set. He then has to select
that JCL member to be able to submit the job. He now needs to swap screens
again to get to the JES queue. If there is a large number of jobs, he needs to
scroll down (PF8) to reach the last submitted job. He now needs to select that
individual job output. In browse mode, he now needs to scroll further to the end
of the job output for any syntax errors.
However, the errors are not at the very end, but rather a couple of pages before,
so the developer needs to scroll back (PF7) to the errors. Now he can see the
line number which raised the error, as well as the error message. But the actual
line of code is not displayed, therefore he needs to go to the command line and
issue a find command with the line number. Now he can see the code and
remember what the error was, but if the job had several errors then he must
repeat this process to attain each error and the line causing it.
In any case, he needs to swap screens again to get to the edit session, and after
changing the code, he needs to swap screens again to get to the JCL PDS. As
you can see, this cyclic process with a limited number of ISPF sessions can be
extremely tedious. Even if a developer has enough multiple sessions or userids,
the process of swapping must always be initiated by the developer.

Figure 1-4 illustrates these tasks in a classic host development environment, as
we have just described, as well as in the remote edit/compile/debug (E/C/D)
environment.
Edit Edit
Select PF9 Compile
Remote E/C/D
PF9 Classic Host Submit Double- click
Submit Hold Edit
Select Compile
JCL PDS
M PF8 Submit MVS
PF9
PF7
Edit
F 102
COPYBOOK PF9
Figure 1-4 Development cycle
Syntax checking
In remote development using VisualAge COBOL, as shown in Figure 1-4, the
development is not only quicker, it is easier, because the tools initiate
themselves. The editor has all the project actions within the Project menu item,
so we assume that the developer is in an edit session as in the classic
development example.
The developer is making code changes, perhaps making lexical errors. When the
focus within the editor changes lines, the prior line is immediately parsed. If a
lexical error exists, the error message is displayed immediately under the bad
line, and focus is restored to the line with the error, as shown in Figure 1-3 on
page 8. When the developer has finished editing, he selects (within the editor)
Project—>Compile. The result is shown in Figure 1-5.
Figure 1-5 Workstation compile error handling
The project monitor automatically comes up, and the compile is started. Any
errors from the compile step (no link) are displayed in the monitor. When the
developer double-clicks on the error message, the editor automatically comes up
to the top of the desktop, with the cursor already at the line of code with the error,
and inserts the error message in the line following the bad code.

With the focus already on the line of code, the developer edits again. He either
uses a hot-key or goes to the editor menu item Compile, and compiles again
until the return code is acceptable. To achieve this, the development department
has incurred absolutely no host costs.
Remote compile — job submission

After a successful workstation compile, the developer can use measured cycles
on the host, cycles that almost every development department is charged for.
Now the developer can utilize remote job submission to submit compile-link job
control language (JCL) to the host.
For this phase of development, VisualAge COBOL delivers a Job Monitor; with a
host and a client part. The JCL can either reside on the client, perhaps on a LAN
drive or on the developer’s workstation, or on the host. If development has
mapped their JCL partitioned data sets, the JCL members are also within the
WorkFrame project which the developer can submit.
All aspects of the JES queue are within the Job Monitor window, as shown in
Figure 1-6. Because the monitor automatically refreshes, the developer can
immediately see what the return code was without having to initiate anything.
Figure 1-6 Job Monitor window
Remote command execution
In case a development shop wishes to use TSO commands to compile, or if a
pre-allocation must first take place, VisualAge COBOL also offers a TSO
Commands window. From this workstation user interface, the developer has a
TSO Command Line interface and can start any REXX or CLIST — everything
that can be done from the TSO command prompt. The result of the command is
displayed in the command output pane, as shown in Figure 1-7.
Figure 1-7 TSO Commands window
The TSO command feature can also be used when creating actions in
WorkFrame. For example, a TSO command, CLIST, or REXX procedure on the
mainframe can be launched directly from within the WorkFrame environment. In
this case, the command output is being displayed in WorkFrame’s monitor pane.

Remote debug
After a successful compile and link on the host, development now enters the test
phase, the last phase, still in the VisualAge COBOL environment. From the
WorkFrame project the developer starts a debug daemon which will listen to a
predefined port. The developer then starts whatever needs to be tested —
IMS/TM, IMS BMP, CICS transaction, simple batch job, or any combination.
Figure 1-8 shows a CICS debug session running parallel to a batch program.
When the host debugger is activated a conversation is established between the

debug engine on the host and the distributed debugger on Windows NT. From
this moment on, the developer now uses the distributed debugger interface,
although he is actually testing his host application in its real environment.
Each debug session is a page tab in the distributed debugger notebook, so the
developer can go from a running CICS debug session to the running IMS/TM
debug session simply by selecting the page tab in the notebook. All relevant host
information for that debug session is then shown, such as:
򐂰 Program source code
򐂰 Stack
򐂰 Registers
򐂰 Storage
򐂰 Variables
򐂰 Breakpoints
Figure 1-8 Enterprise debugging
For a more detailed explanation, refer to Chapter 9, “Debugging” on page 99. At

this point, the advantages from workstation implementation for host development
can be clearly seen. During the two simultaneous debug sessions referred to
previously, the developer is able to edit or submit jobs, or start a CLIST, if he
wishes. The development session is not single-threaded in a 3270 environment.
1.3 Summary
The workstation, due to its underlying hardware technology, does have
advantages as a development platform. However, using the workstation as an
emulator of the actual execution environment for development is an older
technology whose limitations are no longer necessary. VisualAge for COBOL
used in a remote mode offers all of the advantages of workstation development
even though the actual development platform location remains the host.

2
Chapter 2. Component connectivity

This chapter describes the infrastructure that is used in VisualAge COBOL to
provide the communication between the host system and the workstation.

2.1 Introduction
The advantages of remote development were apparent to customers as well as
to IBM. However, Version 2 of VisualAge COBOL made the implementation of
this possibility a little more complicated than envisioned.
IBM wanted to use as much standard software as possible to accomplish the

goal. To that end, Version 2 used a variety of IBM software components to enable
workstation capability for host applications, not just in the file handling, but also in
the JES queue, the TSO command capability. (Some companies actually want to
bring a customer into a very proprietary situation. But IBM’s use of standard
software illustrates a policy that was just the opposite.)
Thus, in Version 3.0 of VisualAge COBOL, we did not simply concentrate the
connectivity technology in IBM VisualAge laboratories and use it only for
VisualAge remote development. Rather, we also developed the architecture to
reflect the latest in remote technology knowledge, for example, by using the
HTTP server as a transport medium.
All software required for remote development, except for the standard HTTP
server delivered with OS/390, the IBM Debug Tool for OS/390, and the Loopback
adapter for Windows NT on the NT CD, is delivered on the VisualAge COBOL
CD. Gone are the RSH commands, the NFS, as well as the difficult configuration
needed for the APPC high performance transaction. All the complications
experienced in Version 2 are gone. The performance is quicker, the reliability is
better, Version 3 is the vindication of Version 2 visionaries.
2.2 Infrastructure
Because the development of VisualAge’s remote development has occurred
primarily within VisualAge laboratories, it was decided that the complete host
software, the server tools, and the configuration requirements, as well as the
client tools, should be delivered on the VisualAge COBOL CD.
Attention: This redbook does not explain how you install and configure the
different parts or tools. The documentation and instructions are completely
provided within the delivered CD. All host code is provided on the CD and is
SMP installable. Its installation and configuration is described in a file called
inst390.pdf, which can be found on the CD.
When comparing Version 2 installation and configuration problems with those of
Version 3.0, we notice drastic improvements in performance with Version 3.0.
IBM Europe was experiencing about two weeks of service for the initial host
configuration for Version 2, without obtaining high performance. With Version 3.0,
the average configuration has taken only two days.
Figure 2-1 illustrates the various components.

UNIX System Services
copybooks
COBOL
FFS PL/I includes
JCL
source
JES
IGYFSERV
HTTP Job
Monitor
TSO
FFS Module JMServer Command
Server
FFS Server
Windows client
Figure 2-1 Remote E/C/D components
On the host side, there are two parts delivered with Version 3.0.
򐂰 Job Monitor
򐂰 Foreign File System (FSS)
Chapter 2. Component connectivity 19

TCP/IP has remained the transport protocol. The medium, as stated, has
changed from NFS to the HTTP Server from OS/390. The IBM HTTP Server is
standard software for OS/390. It must be configured for your development
system. However, the necessary change information is included. Essentially, a
systems programmer simply cuts and pastes from the IBM delivered file into his
configuration file for the HTTP server. In our experience, having a dedicated
HTTP server for COBOL development is the better implementation. A company
can have several HTTP servers running with one dedicated for the developers.
The Job Monitor is responsible for all requests from the job monitor running on
the Windows system. It is a started task running in TSO address space. You
must configure the startup job to your host development system, but the required
configuration information is included in the IBM delivered file.
The second element is the Foreign File System (FSS) server. This server
processes all file handling requests between Windows and MVS. For example,
requests for file opens, saves, or allocating new data sets are handled by the
FFS server. The FFS server runs in the UNIX System Services (USS) and is
delivered as a binary.
The job monitor’s counterpart on the workstation is the JMServer. The

counterpart to the FFS server is the FFSModule.exe. There are several
executables that together make up the functionality of the Foreign File System,
among them FFSServer.exe. However, it is the FFSModule which talks to the
FFS Server running in USS.
If your company wishes to also implement the remote command server, then an
APPC transaction will need to be configured on the host to handle the requests.
The transport protocol is still TCP/IP, but when the request arrives on the host,
the APPC transaction (IGYFSERV) will accept the request and direct it to TSO.
With the remote command server, developers can submit TSO commands, start
REXX procedures, or CLISTs, from the VisualAge COBOL environment.
3
Chapter 3. System connection

definitions
This chapter explains the settings that need to be provided in order to make use
of the remote edit and compile features:
򐂰 Host and user definitions
򐂰 Data transfer definitions
򐂰 Port definitions
򐂰 Data set filter definitions
򐂰 File mapping definitions

3.1 Introduction
The remote edit/compile/debug feature provides a cooperative development
environment between a Windows workstation and an OS/390 mainframe.
This means that the presentation client or the user interface is running on the
workstation, while the data and some of the execution logic remains on the
mainframe system.
The execution logic of an application development task can be editor functions, a

compile job, or the execution of a program in debugging mode. The data involved
in an application development task can be source code, JCL, load modules, or
application data processed by a running application program.
When working with mainframe assets from a workstation, the workstation has to
know what these assets are, and where, on what system, they are located. Since
the communication between the workstation and the host system in a remote
edit/compile/debug environment is based on TCP/IP, the basic information that
has to be defined to the development client workstation is the TCP/IP address or
host name of the serving OS/390 system.
Other information is specific to the remote file serving task, like data set filter
definition, data set control block information, and host to workstation mapping
information. This information can be defined using the VisualAge COBOL MVS
Connections Manager (see Figure 1-2 on page 7).
As shown in Figure 3-1, the following functions obtain communication information

from the MVS Connections Manager definitions:
򐂰 WorkFrame
򐂰 Editor
򐂰 Job Monitor
򐂰 TSO Commands Server
OS/390
IBM HTTP Server APPC
Foreign File System Remote Commands

server Job Monitor server
server
TCP/IP
TCP/IP
WorkFrame LPEX Job TSO

Editor Monitor Commands
MVS Connections Manager
VisualAge COBOL
Windows NT
Figure 3-1 MVS connections definitions
You can define as many different MVS systems as you like; or the same system
many times with different user IDs. You can connect to one, several, or all of
those systems at the same time.
3.2 Using the MVS Connections Manager

Before you can actually work with the remote connection of VisualAge COBOL
you need to configure the workstation software. The MVS Connections Manager
takes care of the configuration. You start this manager by selecting Start —>
Programs —> IBM VisualAge COBOL —> Tools - Remote Access —> MVS
Connections.
Chapter 3. System connection definitions 23

3.2.1 Host and user definitions
When you define remote connection parameters for the first time, you will see the
screen shown in Figure 3-2.
Figure 3-2 Connection Properties window, Host and User tab
This window asks requests the following information:

򐂰 MVS system name: Enter the name of the MVS system that you want to
work with. This can be the TCP/IP address, or the host name with which the
system is known to TCP/IP.
򐂰 System shortname: Enter a nickname for that system. This nickname is
used by the Job Monitor and the TSO Command Server to identify the system
you want to work with.
򐂰 MVS User ID: Enter the TSO userid that you use on that system.
Note: All of the above mentioned fields are mandatory.
The password that comes with the userid is not stored anywhere within
VisualAge COBOL. Once you have the connection settings finished and you
connect to the host, you are prompted for the TSO password that you use on this
mainframe. Figure 3-3 shows the window for the password.
You are prompted for every system that you want to connect to, although it is
possible to indicate on this menu that Passwords are the same for all hosts.
If you check this box, you will be prompted just once; otherwise, you will be
prompted for every system.
Figure 3-3 Password prompt for MVS connection
3.2.2 Data transfer definitions

After providing all the information that is needed, click the Next button in order to
get to the next screen, as shown in Figure 3-4.

Figure 3-4 Connection Properties window, Data Transfer tab
In order to perform the correct code page translations when transferring data
between the mainframe and the workstation it is necessary for VisualAge
COBOL to know which code pages are used on the workstation as well as on the
host. These code pages are provided in this window.
The Local Code Page is determined automatically by VisualAge COBOL from

the Windows operating system settings and displayed.
The Host Code Page needs to be provided by the system programmer.
The Drive Letter is necessary to map the remote file system to a local drive.
This is the way to give VisualAge COBOL access to your data sets and their
members. The drive letter can be selected by choosing one of the free drive
letters on your workstation. The drive letters that are used by your network are
taken into consideration and are not available.
3.2.3 Port definitions
Again, after specifying the desired fields, clicking the Next button brings up the
next screen, as shown in Figure 3-5.
Figure 3-5 Connection Properties window, Ports tab
The information that is required in this window needs to be provided by the

system programmer, although usually the default port numbers are correct, at
least for the Job Port.
Recommendation: We recommend that you define a separate HTTP server

for the exclusive use of VisualAge COBOL users. This way you can start and
stop the server without interfering with other HTTP applications. The default
Web Port for the HTTP server is 80. Therefore, if you have already an HTTP
server running, you might have to define a different port for the HTTP server
that is defined for FFS.

3.2.4 Data set filter definitions
Once you completed all the fields, you can close the Connection Properties
window by selecting the Finish button.
After that, it is time to tell VisualAge COBOL with which data sets you want to
work. These can be data sets that contain COBOL source, JCL, copy members,
or other relevant elements. These data sets are the ones that you want to work
on when you are connected to the mainframe.
The connection is made using the drive letter as specified in Figure 3-4 on
page 26 in combination with high-level qualifiers from the data sets. Once a drive
letter and the high-level qualifiers are known and the connection with the host is
active, you are able to use any data set that begins with any of the specified
high-level qualifiers.
You can narrow down the number of accessible data sets by specifying a
mid-level qualifier as well.
Example: Suppose you have the following data sets:

򐂰 REDBOOKS.APPL.COBOL
򐂰 REDBOOKS.APPL.JCL
򐂰 REDBOOKS.APPL.COPY
򐂰 REDBOOKS.LISTING
򐂰 REDBOOKS.PROC
Assigning a drive letter to just the high-level qualifier REDBOOKS gives you the
possibility to make use of all of these data sets. If you specify the mid-level
qualifier APPL as well, then only the first three data sets are available:
򐂰 REDBOOKS.APPL.COBOL
򐂰 REDBOOKS.APPL.JCL
򐂰 REDBOOKS.APPL.COPY
In the window shown in Figure 3-6, you can specify the high-level and mid-level
qualifiers that you want to make use of.
In this example, we specified both the high-level and the mid-level qualifier.
Figure 3-6 Directory Properties window
3.2.5 File mapping definitions

VisualAge COBOL offers actions that can be executed against data such as
source code, JCL, executables, object code, command lists. The available
actions depend on the type of the data. For example, source code can be edited
and compiled; JCL can be edited and submitted; object code can be linked;
executables and command lists can be run.
VisualAge COBOL knows what type of data a file contains by looking at its
workstation file name extension. Therefore, if you are working with members of
partitioned data sets on a mainframe, you have to provide the data type
information to VisualAge COBOL.

This is done on a data set level rather than the individual member level. It means
that VisualAge COBOL assumes that all the members in a given partitioned data
set contain the same type of data; for example, a data set does not contain
source code and JCL members at the same time.
The mapping between a mainframe partitioned data set and its workstation file
extension is being done using the last level qualifier of the partitioned data set
name. VisualAge COBOL provides some default settings already when you
install the product. The lower right pane of the MVS Connections Manager
window (see Figure 1-2 on page 7) contains those mapping definitions.
Figure 3-7 shows the mappings that are defined by default.
Figure 3-7 Local and host file mappings
In our sample installation, we store the copy books in a data set called
REDBOOKS.APPL.COPY. Because COPY is not on the default list of host files,
we had to define the corresponding mapping.
You might have different naming conventions in your company, and therefore
probably you will need to define additional mappings. In order to define a new
mapping, right-click on any of the existing mappings and select New... from the
pop-up menu, or select File —> New mapping from the MVS Connections
Manager menu bar.
Note that the mappings you add yourself are only available when working with
the host system you defined them to. This means that first you must select the
corresponding connection in the top pane before you can add a new mapping. If
you have more than one connection defined, you have to add the new mappings
to every connection individually if you have the same naming conventions on the
different systems.
On the Mapping Properties window, specify the local file extension and the last
level qualifier of your partitioned data set, as shown in Figure 3-8. Make sure to
put the two asterisks (**) in front of the last level qualifier.
Figure 3-8 Mapping Properties window
The file types you most likely need are:

򐂰 cbl for COBOL source
򐂰 cpy for copy books
򐂰 jcl for JCL
If you want to work with file types other than the defaults, you might also have to
define the actions that can be performed against these files. Refer to 5.4.1,
“Create your own actions” on page 64 for further details.

4
Chapter 4. Project definition

This chapter describes how to define an MVS project and its settings. It covers
the following topics:
򐂰 Starting the IBM VisualAge COBOL Projects Wizard
򐂰 Opening an existing project
򐂰 Creating a new project

4.1 Introduction
With VisualAge COBOL, you organize your code by grouping related files into
projects. A COBOL project is the complete set of data and actions you need to
complete a programming task. An MVS project typically includes the COBOL
source programs you want to edit and compile, as well as related files like JCL
and BMS maps.
The actions that can be performed against this data depend on the kind of data.
A source file, for example, can be edited or compiled. JCL can be edited or
submitted. A REXX procedure can be edited or executed.
The single development environment where your project data and actions are
integrated and organized is called WorkFrame. In WorkFrame you can work with
your files directly rather than accessing them through individual tools.
VisualAge COBOL provides pre-configured COBOL projects. When you create

your own COBOL projects, you get a complete set of actions, types, and
environment variable settings. But you can also define and add your own actions,
for example, to interface with software configuration management tools.
There are three different kinds of pre-configured projects:

򐂰 Workstation GUI project, including actions for the visual GUI builder
򐂰 Workstation non-GUI project, including actions for debugging a program
executing on the workstation
򐂰 MVS project, including actions to connect to a host system, start the Job
Monitor, and start the TSO Commands server
4.2 Starting the IBM VisualAge COBOL Projects Wizard

You need to define a project before you can use the VisualAge COBOL
development tools. There is a wizard to help you to define a project.
From the Windows Start menu, select Programs —> IBM VisualAge COBOL
—> IBM VisualAge COBOL Projects. A window appears, as shown in
Figure 4-1.
Figure 4-1 VisualAge COBOL Projects window
There are two actions available from this window:

1. You can open an existing project. “Opening an existing project” on page 35
will cover this possibility.
2. You can create a new project. “Creating a new project” on page 37 explains in
detail how to create a project.
4.3 Opening an existing project

The IBM VisualAge COBOL Projects wizard default comes up with the Open
existing Project tab active. You can now select an existing project and open it.
This is done by clicking the specific project and then clicking the Open button.
WorkFrame then opens with the settings for this specific project and you can start
working with the project.
Chapter 4. Project definition 35

After installing VisualAge COBOL, there is no project in the list. As soon as you
create a new project, it will be added to this list. You can also add projects to this
list by clicking the Browse for more projects... button, for example, if you want
to open one of the sample projects provided with VisualAge COBOL. This results
in a selection screen, as shown in Figure 4-2. Here you can change the directory
and browse for other project files.
Figure 4-2 Browse for an Existing Project window
As you will learn in 4.4, “Creating a new project” on page 37, the project
definitions are saved in a directory. Therefore, you can also open that directory,
for example, in Windows Explorer, and open a project by double-clicking its icon.
The file has the name of the project and an extension of .IWP.
This is a faster way of opening an existing project.
Note: When opening an existing project directly from the directory, please be
aware that opening the folder will show all the project files that are created in
this particular directory. There are two files present per project: an .iwo file and
an .iwp file. Double-clicking the .iwp file opens your project. The .iwo file
contains project settings and can be ignored, but it may not be deleted.
4.4 Creating a new project
To create a new project, click the Create New Project tab on the COBOL
Projects window (see Figure 4-1 on page 35). The Create New Project pane is
displayed, as shown in Figure 4-3.
Figure 4-3 Create New Project window
In this book we focus on the capabilities of VisualAge COBOL that allow you to
maintain and develop applications that reside on an MVS system. Therefore, we
only explain how to work with MVS projects. On the Create New Project pane,
the MVS Project is selected by default. Click Next >> to continue. What happens
next depends on whether you have already defined connection properties.

4.4.1 Connection properties are not defined
In case you did not perform the procedure to set up the connection properties
from the previous chapter, you receive a message as shown in Figure 4-4.
Figure 4-4 Remote System Not Set Up message
If you click OK, you are guided through the steps as described in Chapter 3,
“System connection definitions” on page 21. If you select Cancel, you can still
proceed with the project definitions, but you will have to define the connections
later before you can work with the project.
Note: We recommend that you define the System Connections settings before
defining the MVS project. This gives you the chance to have all the information
available that you will need to define the data sets that you want to include in
your project. In case you want to define the System Connections settings at a
later stage, you need to complete the project settings afterwards from within
WorkFrame.
After defining the System Connections properties, you can return to the project
wizard and continue with the definition and settings of the project that you are
creating.
Regardless of which way you choose, you will now continue with the definitions
as described in the next section.
4.4.2 Connection properties are defined
The next stage of your project definition is shown in Figure 4-5.
Figure 4-5 Enter a project name window
On this screen, enter the name under which the project will be known. This name
will appear on the title bar of the WorkFrame window. It is also the name of the
.iwp file.
In fact, this is the only information that you need to enter on this window. The
other fields are grayed out, because they are not relevant for MVS projects. An
MVS project does not deliver an executable or DLL on the workstation, since the
target for the load module is the mainframe. It is produced by the COBOL
compiler and linker on OS/390, and not by VisualAge COBOL.

Again, click Next >> to enter the project folder information, as shown in
Figure 4-6.
Figure 4-6 Enter project folder information window
The intention of this window is to gain information about the locations where the
various project files are stored. These directories can be:
򐂰 User directories, containing source code, JCL, and other data you want to
work with
򐂰 System directories, containing data generated and used by VisualAge
COBOL
User directories
The first listbox on the window (refer back to Figure 4-6 on page 40) is initially
empty. You can specify one or more directories where source code or other
elements are stored that you want to work with. These are typically directories
that can be found on the mainframe you are connected to. But they can also
reside on your local workstation or the network you are connected to.
To add a directory, click the Add button that is located to the right of the listbox. If
you are not currently connected to an MVS system, a message window shows up
as in Figure 4-7.
Figure 4-7 No MVS System Connected message
Clicking the Yes button will cause the Connection Manager to perform the
Connect-all action. VisualAge COBOL tries to connect to all systems defined by
the MVS Connections Manager. For every system, the password is requested.
When the connections are established successfully, or after clicking the No

button, a browse window appears, as shown in Figure 4-8.

Figure 4-8 Browse for a Source Folder window
As with the Windows Explorer interface, you can navigate through all the
available drives and directories. You can select local or LAN drives and
directories, or, if you are connected to a mainframe, you can select libraries from
the corresponding host system.
The sample in Figure 4-8 shows drive R, which is mapped to an MVS system as
defined in the MVS Connections Manager (see Figure 3-4 on page 26, or
Figure 1-2 on page 7).
When you select an MVS drive, you get all the data set qualifiers defined for that
system. Compare Figure 4-9 here with the directories defined in Figure 1-2 on
page 7.
Figure 4-9 Browse MVS directories window
Click the + in front of a directory to expand it. The complete path of a fully
expanded directory constitutes a complete data set name. The lowest directory is
the last level qualifier of the data set name.

You can select multiple data sets by pressing and holding the Ctrl key on your
keyboard while selecting directories with the left mouse button. In Figure 4-10 we
selected the COBOL, COPY, and JCL directory.
Figure 4-10 Select source folders window
When you click the Add button, your selected directories are added to the
window with the project folder information (see Figure 4-11).
If you want to delete a directory from the project folder information list, just select
the directory in the listbox and click the Delete button.
Figure 4-11 Project Folder Information window with source directories
System directories
Every project that you define needs to have a working directory. This is a
directory in which files are stored that are produced during a local compile. You
can do local compiles using the VisualAge COBOL compiler on the workstation
to perform syntax checks of your COBOL source. This way you only have to use
valuable mainframe resources once to do the final compile of your program in its
target execution environment.

A local compile can result in the following files:
򐂰 Listing: This file contains the source with expanded copy books, the compiler
options used, and all the compiler messages. The file has the name of the
source with the extension .LST.
򐂰 Object: The object file is the compiled program. It is stored with the name of
the source and an .OBJ extension.
򐂰 Adata: When compiling with the SYSADATA compiler option the compiler
generates SYSADATA information. This information is used by the Program
Understanding tool to present the source in a graphical fashion. The
SYSADATA file is stored with its sourcename and extension .ADT.
The final directory that you need to specify for your project is the place where you
want to store the files containing the project definitions. As mentioned before
(see page 4.3, “Opening an existing project” on page 35), you can go to this
directory to open projects without having to use the Projects wizard. For
example, you can create a folder on your desktop to store the project definition
files.
Now that you defined all the directories needed for your project you can continue
to the next screen. Click the Next button. If any of the specified project folders do
not exist yet, a message box appears, as shown in Figure 4-12.
Figure 4-12 Folder Not Found message window
By clicking the Yes button, the folder will be created. If you do not create the
directory at this moment, you will be prompted for it at later stages.
Environment variables
The next screen (see Figure 4-13) is also the final screen, and it is provided for
specifying environment variables. If you have some variables that you would like
to add to your project, then this is the place to specify them. As with the source
folder information, you can always change or add environment variables later
from the WorkFrame window.
Figure 4-13 Environment variables pane
The one variable provided per default by VisualAge COBOL is the SYSLIB
variable. This variable tells VisualAge COBOL where to look for copybooks. If
you have copybooks on the host used by programs you want to work with, you
need to add the library to the SYSLIB variable. This is used by the VisualAge
COBOL compiler when you do local compiles for syntax checks.

Click the Edit button. The next window (see Figure 4-14) shows the editable
fields where you can add your data sets. Remember that you have to specify the
correct drive letter, in our sample the R:-drive. Specify the directory as defined in
the MVS Connections Manager, and add the lower level qualifiers after a
backslash.
Figure 4-14 Edit Environment Variable window
After clicking the OK button, the new value for SYSLIB is displayed on the
environment variables pane of the project definition window.
As a last step, click Finish. When you changed the SYSLIB variable, you will be
prompted to save the new settings as default, as shown in Figure 4-15.
Figure 4-15 Change Default Settings message
You can save the new setting as a sample for future projects. How many different
MVS projects you will define on your workstation depends on your environment:
򐂰 How many applications are you working on?
򐂰 How are your application assets, like source code and JCL, organized?
Do you have a different set of libraries for each application?
As you can see from the project definition steps outlined above, the main
elements of a project are the source data sets you want to work with.
After clicking Yes or No on the Change Default Settings window, the project
wizard shows the final message window (Figure 4-16), and WorkFrame opens
your new project.
Figure 4-16 Project Created message window

5
Chapter 5. WorkFrame
WorkFrame is a development environment that lets you work with your project in
an organized way. It provides a single view of your project data and makes all the
actions available that can be performed in a project. See Chapter 4, “Project
definition” on page 33 for more information about VisualAge COBOL projects.
In this chapter, the following topics are discussed:

򐂰 WorkFrame elements
򐂰 WorkFrame views
򐂰 Project settings
򐂰 WorkFrame actions

5.1 WorkFrame elements
Once a new project has been created, or an existing project has been opened,
the VisualAge COBOL WorkFrame is shown (see Figure 5-1). The title of the
window contains the name of the project that you specified when you created the
project (see Figure 4-5 on page 39).
Figure 5-1 WorkFrame window
Other elements include these (refer to the numbers in Figure 5-1):

1. Project toolbar
2. Menu bar
3. File filter
4. Project container
5. Project monitor and command window
5.1.1 Project toolbar

The project toolbar contains buttons for frequently used actions. Buttons to clear,
save, or print the content of the project monitor pane are on the left side of the file
filter entry field.
On the right side of the file filter are buttons for other project related actions, such
as these:
򐂰 Edit a new source file
򐂰 Connect MVS drives
򐂰 Disconnect MVS drives
򐂰 Start the MVS Connections Manager
򐂰 Start the Job Monitor
򐂰 Start the TSO Commands server user interface
Buttons for actions that you create yourself also go here (see 5.4.1, “Create your
own actions” on page 64).
Note: Moving the cursor over a button activates the hover help text, which
shows you the button name. Or if you like, you can change the display style to
permanently show the button names: from the menu bar, select View —>
Toolbars —> Style —> Graphic and Text.
5.1.2 Menu bar

The menu bar contains menu items to launch Project Scoped and File Scoped
actions, set the project options, and access the online help.
File contains menu items related to project activities. You can create or open
projects from here, or you can change the project settings for your current project
(see5.3, “Change project settings” on page 60).
Edit contains the actions that apply to any selected file (or subproject). The menu
changes depending on the type of file selected.
View contains menu options that can be used to adjust the way of presenting the
information in the WorkFrame. For instance, it is possible to have the Auto
Refresh option turned on or off. See 5.2, “WorkFrame views” on page 57 for more
information about presenting the project data within WorkFrame.
Actions lists all the Project Scoped actions available. For an MVS Project, for
example, there are actions to connect and disconnect MVS drives, start the Job
Monitor and TSO Command server, start the BMS map editor, or create a new
source file. It also contains a facility to create your own actions (Tools Setup).
Options contains facilities to specify options for actions. For an MVS project,
there is only a notebook which lets you define interactively the compiler options
that you want to use when performing a local compile for syntax check.
Chapter 5. WorkFrame 53
Both Project Scoped and File Scoped actions are accessible from pop-up
menus. See 5.1.4, “Project container” on page 55 for more information about the
pop-up menus.
5.1.3 File filter

If you do not want to see the entire content of your data sets, you can set filters.
You can use the drop-down list from the file filter input field, as shown in
Figure 5-2. In this example, we only want to see COBOL source files (extension
*.cbl or *.cpy).
Figure 5-2 The WorkFrame file filter
Notice in Figure 5-3 that the content of the WorkFrame project container has
changed. In front of the directory R:\REDBOOKS.APPL\JCL there is no + sign
any more. Obviously, this directory does not contain any COBOL or COPY
source, and therefore remains empty with this view.
Figure 5-3 WorkFrame view with only source files
You can also type your own filter. It does not have to be just the file extension. If
you only want to see all the members starting with XYZ then type *XYZ* in the file
filter entry field. Note that the filter works on the entire path name, not just the
actual file or member name. Therefore you need to put the wild character * in
front of your filter criterion.
5.1.4 Project container

The project container is the area where the files are displayed that you want to
work with in your project.
WorkFrame is context sensitive, which means that it offers different actions

depending on the type of file that is selected. By clicking on a file with the right
mouse button, the context-sensitive pop-up menu appears.
Here are some examples. Figure 5-4 is the menu for a source code member. In
addition to editing, you can also compile a program using the local VisualAge
COBOL compiler.
Figure 5-4 The possible actions on a COBOL source member
Figure 5-5 shows the menu for a JCL member. JCL can be edited like the source
code member, but it cannot be compiled. Instead, it can be submitted on the
MVS host system.
Figure 5-5 The possible actions on a JCL member
In local workstation projects, you have additional file types with additional
actions. For example, an object file can be linked, and an executable can be run
or debugged.
5.1.5 Project monitor and command window
This is the area where the results and messages of actions are displayed. For
instance, the submission of a job and the results of a syntax check compile will
appear in this pane.
This pane also offers a regular Windows command prompt. Just click it and type
any command. Thus you do not have to switch between various windows when
working on a project. For example, if you want to know the IP address of your
workstation in order to specify it as a runtime parameter when debugging a host
program, you can execute the ipconfig command right in WorkFrame.
Use the push buttons in the project toolbar (see 5.1.1, “Project toolbar” on
page 52) to clear, save, or print the contents of the project monitor pane.
5.2 WorkFrame views

You can display your files in the project container in various ways. Whatever way
you choose, only the files that correspond with the filter you specified are shown
(see 5.1.3, “File filter” on page 54).
The three different views are:

򐂰 Tree view
򐂰 Icon view
򐂰 Details view
5.2.1 Tree view

The default when creating a project is the tree view. The directories are listed in
the same order as they have been entered when creating the project. A plus sign
(+) in front of the directory or data set name means that there are files or
members in it. When you click the + sign, the members are listed in alphabetical
order. This is shown in Figure 5-1 on page 52 and Figure 5-2 on page 54.
5.2.2 Icon view
Another way of viewing the contents of the WorkFrame is the icon view.
The icon view shows instantly all the members from all directories that are set for
the project. A sample of the icon view is shown in Figure 5-6.
Figure 5-6 WorkFrame icon view
You can see all members, but you cannot see to which directory they belong.
One way to find out in what directory a member resides is to right-click its name
and select Show full MVS name from the pop-up menu. Alternatively, you can
select the member and then select Edit —> Show full MVS name from the
menu bar.
Depending on the number of directories that are specified in the project, it might
be fairly easy to tell what the directory must be from looking at the extension. For
instance, having just one directory with JCL members makes the guess more
obvious.
5.2.3 Details view
The final data view offered by WorkFrame is the details view. This view is shown
in Figure 5-7.
Figure 5-7 WorkFrame details view
The details view shows you detailed information about the members, including
the directory they are in (location), and the date and time when they have been
changed the last time.
All possible details can be viewed by selecting File —> Project Settings —>
Columns. By default, all fields are selected to show up in the detailed view, but
you can deselect fields from your view. In the example above (Figure 5-7) we
moved the Location field more up and have only the fields Icon, Name, Location,
Last Write Date, and Last Write Time selected.
Figure 5-8 shows the Columns window with the settings that were used with the
view shown in Figure 5-7 on page 59.
Figure 5-8 Detailed view of columns
To make a column show up in a different place, just select that column and click
as many times as necessary on the Up button or Down button to place the
column in the desired spot.
5.3 Change project settings

In WorkFrame you can change the settings that you defined when creating the
project. Select File —> Project Settings and then any of the options to open the
project settings notebook.
The following settings can be changed:

򐂰 Directories
򐂰 Environment variables
򐂰 Name
򐂰 Columns displayed
򐂰 Sort order for columns
5.3.1 Directories
On the Directories page (see Figure 5-9) you can add or delete data sets that
you want to work with. The order in which the directories are listed is the order in
which they are presented in any view of the project container of WorkFrame.
Figure 5-9 Project settings notebook - directory page
To add or delete directories, just edit the entries in the multi-line entry field.
The working directory must be one of the defined source directories. For
performance reasons, it has to be a local directory, although the remote
directories are also shown in the drop-down listbox. WorkFrame does not allow
an MVS directory as working directory. If you select a remote directory, you
receive a somewhat misleading error message when you click OK to save the
settings. But make sure that the working directory is on a workstation drive.
5.3.2 Environment variables
On the Environment page (see Figure 5-10) you can change the settings for the
environment variables.
Figure 5-10 Project settings notebook - environment variables page
Environment variables are a workstation concept. They are used, for example, to
allocate data or to define concatenation sequences. The SYSLIB environment
variable is the same as the SYSLIB DD statement in an MVS environment. It tells
the compiler where to look for copy books. While the MVS COBOL compiler uses
the SYSLIB DD statement, the Windows COBOL compiler of VisualAge COBOL
uses the SYSLIB environment variable. It has to be defined when you perform
local compiles for syntax check.
If you have a lot of standard copy books used by most of the programs, you might
want to copy them to a workstation drive and point the SYSLIB environment
variable to this local directory. This improves the performance of local compiles.
5.3.3 Additional settings

The other pages in the project settings notebook let you change the appearance
of the project, not the actual project data like the directories and environment
variables:
Project Name: This is the name that shows up on the windows title bar of the
WorkFrame project. The project is listed by this name in the
project list (see Figure 4-1 on page 35).
Columns: On this page you can select the columns you want to see in the
details view of your project. See 5.2.3, “Details view” on page 59
for more information about the columns.
Sort: This page is used to specify the column by which the members
in the project container should be sorted.
5.4 WorkFrame actions

WorkFrame actions are tasks that are performed during the program
development process. They are considered as either Project Scoped actions or
File Scoped actions.
Project Scoped actions are available from the Actions option on the menu bar or
as a popup menu from the project container.
File Scoped actions are available through the popup menu from the member in
the project container or from the Edit option on the menu bar when selecting a
member in the project container.
File Scoped actions have a member from the project container as input. Edit,
compile, or submit for example work on a program source or JCL member.
The available Project Scoped actions depend on the type of project. The default
actions for an MVS project are:
򐂰 Edit a new file: This starts the LPEX editor with an empty window. You can
start to enter code for a new program.
򐂰 Connect MVS Drives: This action performs FFS connections to all the MVS
systems defined in the Connections Manager.
򐂰 Disconnect MVS Drives: This releases all the current FFS connections.
򐂰 Setup MVS Connections: This action invokes the Connections Manager.
򐂰 MVS Job Monitor: This invokes the Job Monitor.
򐂰 Start remote debug daemon: This action activates a listener waiting for
debug requests from a mainframe system running the IBM Debug Tool. When
the remote debug daemon receives such a request, it starts the Distributed
Debugger of VisualAge COBOL and communicates with the Debug Tool on
the mainframe during a debugging session.
򐂰 TSO Commands: This action starts the TSO Commands server interface.
򐂰 Stored Procedure Manager: This invokes the Stored Procedures Manager,
a feature that helps generating a CREATE PROCEDURE SQL statement.
򐂰 BMS Editor: This invokes the BMS Editor, a visual builder for BMS maps.
The maps are painted like a graphical user interface and the tool generates
the BMS source.
5.4.1 Create your own actions

The last option in the Actions menu is called Tools Setup. Through this option,
you can change the existing actions (not recommended) or even define your
own. When you define your own action, this action will be available to all existing
and future projects, independent of the type of project.
The easiest way to find out how to define an action is to look at the definition of
the existing actions. Select Actions —> Tools Setup from the menu bar to start
the tools setup window as shown in Figure 5-11.
Figure 5-11 Tools Setup window
Right-click any of the items in the list. The context menu offers three options:
򐂰 Add
򐂰 Change
򐂰 Delete
By selecting the Add option, you can define your own action through a notebook
as shown in Figure 5-12. The data of the action which you clicked is filled in
already. This way, you have an example when you create your own action.
Therefore, make sure that you select an action that is similar to the new one you
want to create.
Figure 5-12 Add Action notebook, General page
The Edit action shown here is a File Scoped action, which means that it is
available for a specific file. The LPEX editor (IWZWLX40.exe) is the program the
action starts with the selected file loaded. Therefore, the Action applies to File
checkbox is checked.
There is also another action called Edit a new file. This action also starts the
LPEX editor, so the same executable is specified in the Program entry field. But
the action applies to the project. Therefore, LPEX starts without loading an
existing file.
For File Scoped actions, the Types page (see Figure 5-13) of the notebook
allows you to specify the kind of data a file can contain if the action is to be
available to the file.
Figure 5-13 Add Action notebook, Types page
The available types in the list on the right side of the page are defined in the tools
setup under Types (see Figure 5-11 on page 64). This definition provides the
mapping between the plain English type name and the file extension of a
corresponding file. COBOLSource, for example, is mapped to the extension .cbl
— which means that an action defined for the source type COBOLSource is
available to all members with a .cbl file extension.
For a discussion of the remaining pages in the action notebook, refer to 8.3.2,
“Add a TSO command action to your project” on page 94.
6
Chapter 6. Editing
This chapter discusses a few aspects of the VisualAge COBOL LPEX editor,
such as:
򐂰 Connectivity
򐂰 Views
򐂰 Navigator
򐂰 Profiles
򐂰 SQL code assistant

6.1 Introduction
Someone’s favorite editing tool can be compared to their own car, which they use
every day. This naturally leads to a certain amount of affection regardless of its
functionality or ease of use. Even if a car owner takes a test drive in a different
car of a much higher class, the car owner can state that the new functions are
good, they might even admit that in some respects the other car is better than
their own car, but....
In the last five years the shift in technological as well as tool advancement has
predominantly taken place on the client platform. In a world based on senses,
having and utilizing a graphical user interface for work has captured not only the
business world, but also the domestic world.
One of the greatest complaints with host developers is the fact that host tools are
character-based. The ability to use the workstation capability, the graphical
interface, is not available for host development.
6.2 Connectivity
In Version 2, VisualAge COBOL tried to offer the VisualAge LPEX editor for host
development through the NFS Server within the USS on 390. One of the major
difficulties was that IBM does not offer an NFS client. Customers were therefore
forced to acquire a third party NFS client to enable developers to exploit
workstation capabilities on their host source code.
With Version 3.0, VisualAge COBOL has developed their own file system
(Foreign File System) to address the NFS shortcomings as well as to be
independent of third parties. Now developers are able to enjoy and maximize the
VisualAge COBOL LPEX workstation editor for editing their host source files.
The architecture for the new Foreign File System is shown in Figure 6-1.
Figure 6-1 FFS architecture
As can be seen in this diagram, any file handling is performed between the SASH
and the FFS Server residing in the USS. The FFS covers not only the LPEX
handling rather all file handling between Windows NT tools and the host.
For instance, if a developer was editing his COBOL source in Notepad and
issued the save, FSS would process the save on the host. FFS has the same
responsibility for a copy command that was issued, for example, from the NT
Explorer or from the MS DOS command prompt.
Chapter 6. Editing 69
6.3 Functionality
The prior example with Notepad was used only to establish the functionality of
FFS. At the current state of development, an enterprise editor such as LPEX is
the norm, and therefore it is also included with VisualAge COBOL. This editor is
very visually oriented, maximizing the usage of color, mouse, and windowing
capability.
LPEX is just as flexible as the WorkFrame itself. Companies can integrate their
own tools easily into the editor, not only on a permanent basis, but also through
the use of REXX macros, and integration can be done dynamically.
Listing all the features of the LPEX editor would fill an entire book. In this chapter,
therefore, we mention only a few aspects of LPEX. But we encourage you to
check out all of its menu functions. As with VisualAge in general, the help for
LPEX is very comprehensive. Most probably, any editor function you can think of
is available in LPEX and can be found through the menu actions.
We offer a quick introduction to a few features:

򐂰 Various views and windows
򐂰 Navigator
򐂰 Profiles
򐂰 SQL code generator
Those features might be especially interesting for mainframe programmers who

are only familiar with their host editor and are not used to workstation tools.
6.3.1 Views
Host based tools cannot offer a multiple view capability. With host editors, a
developer has the possibility to exclude certain elements within the view, but the
fact remains that a host editor only allows that single view. In LPEX, different
views are available simultaneously for COBOL source files:
򐂰 SQL or CICS APIs
򐂰 Data Division
򐂰 All divisions
򐂰 Outline of program
򐂰 Comments
You can also create your own filter, specifying what lines you want to be
displayed.
As shown in Figure 6-2, the views are automatically available depending on the
file type. The sample shows a JCL file.
Figure 6-2 Automatic filtering
Of course, a new view of the complete file is also available. Any changes the
developer makes within any of the views is automatically reflected in all views by
LPEX. Any files can either be opened as separate windows or as one window
managed through a ring manager, keeping the desktop clutter to a minimum.
Ring management is also available when files are opened separately.
6.3.2 Navigator
To help with large source files, LPEX also offers a Navigator function. This
separate window shows the different sections and paragraphs within the source.
Like most graphical interfaces, double-clicking on a section box brings the focus
in the editor to this point. This is shown in Figure 6-3.
Figure 6-3 LPEX Navigator
6.3.3 Profiles
LPEX is context sensitive. This means that when the focus changes source code
lines, the last line is parsed and proofed against the language profile. These
profiles can be expanded and changed. Customers can even make their own
profile, although LPEX is delivered with 62 different profiles, including C, COBOL,
JAVA, and even JCL.
As shown in Figure 6-4, as LPEX notices the file syntax, it also changes the
WorkFrame capabilities that it offers. In this case, when JCL is present, LPEX
changes the action bar to include the capability to submit the JCL directly from
the editor. Within the Project menu item, next to Submit Job, most WorkFrame
actions are also available from within the editor.
Figure 6-4 Context sensitive
6.3.4 Insert SQL code
LPEX provides a code generator to create EXEC SQL statements. Input for the
feature is a table mapping file created by the Data Assistant tool, which is part of
VisualAge COBOL.
The SQL code generation feature available from the Edit menu option in LPEX
guides the application developer through the process of creating any kind of
EXEC SQL statement by allowing him to select all the parts of the statement from
combination boxes or list boxes. The generated statement is then copied into the
source code at the cursor position. Figure 6-5 shows a sample for an update
statement.
Figure 6-5 Insert SQL code
6.4 Summary
As mentioned, the number of features within LPEX could comprise a small book.
Keystroke recorders, key behavior emulation of ISPF, XEDIT, and a compare
functionality, as shown in Figure 6-6, are only a few.
The use of a graphical interface for source editing increases a developer’s

productivity. It brings the host programmer to a level of development tooling
similar to that used by the newer programmers, by developers on client platforms.
Regardless of the development platform, through LPEX and FFS a company’s
developers can enjoy and exploit one development tool for source editing,
regardless of whether it is used for host source or source files residing on the
Windows NT client.
Figure 6-6 Graphical compare
7
Chapter 7. Compiling
This chapter covers the following topics:
򐂰 Specifying compiler options
򐂰 Using the VisualAge COBOL workstation compiler for syntax checking
򐂰 Performing a compilation on the mainframe

7.1 Introduction
After editing the source code, the next step in the development cycle is to
compile and link the program in order to produce executable code. This code is
optimized for the platform it is targeted to run on, and therefore it cannot be
ported from one platform to another. Only the source code is portable, but it has
to be compiled with the platform-specific compiler.
Before translating the source code into machine readable code, a compiler
checks if the source complies with the syntax rules. The VisualAge COBOL
compiler is source compatible with the Language Environment based OS/390
COBOL compiler, which means that source code which compiles without syntax
errors on the Windows platform will compile without syntax errors on the OS/390
system.
After applying major changes to a program, a developer typically compiles the

program several times until the source is free of syntax errors. A compile run on
the mainframe can be expensive and slow, depending on the capacity of the
system.
It therefore makes sense to use the VisualAge COBOL workstation compiler to

check the syntax before running the final compile on the target host system. This
local compile does not have to produce an object deck, and no link step is
necessary because the MVS program is not meant to execute on the
workstation.
7.2 Compiler options

Before you compile a program, it might be necessary to look at the compiler
options and change some of them to your needs. The compiler options are set by
default, but they can be adjusted to the situation.
In WorkFrame, select Options —> Compile. All possible options are presented
in a notebook style window. Figure 7-1 shows the general options page of this
notebook.
Figure 7-1 Compile options notebook
A few of the compiler options are of interest when dealing with an MVS project.
In the compile notebook, set the options that your program needs, and click OK
to save them. In particular, you might want to set the options listed in Table 7-1.
Chapter 7. Compiling 79
Table 7-1 Compiler options of interest for MVS projects
Page Compiler option Comments
General Compile only No object code is saved, no link edit is being performed
Syntactic Process COPY, BASIS, and Check this option if your program uses copy books.
REPLACE statements
(LIB option)
Syntactic Copy file search path As an alternative to specifying the SYSLIB

environment variable (see 5.3.2, “Environment
variables” on page 62) you can enter the search path
for copy book files here. Use this option if copy files are
in the form COPY MYCOPY.
However, the copy file search path does not affect copy
statements in the form COPY MYCOPY OF MYLIB or
COPY MYCOPY TO MYLIB. In this case, set the
MYLIB environment variable for the project to the folder
(or folders) containing the MYLIB copy files.
Syntactic Perform syntax check on all Allows syntax-checking of COBOL programs that
source statements contain EXEC CICS and EXEC SQL statements,
(ANALYZE option) without having CICS or DB2 UDB installed on your
workstation. The compiler might issue informational or
warning messages (such as about reserved words)
that you do not get when you preprocess the program.
Processing Generate SYSADATA Use ADATA when you want the compiler to create a
(ADATA option) SYSADATA file, which contains records of additional
compilation information. This information can be used
by other tools, like for instance Program
Understanding.
7.3 Local syntax check

The local syntax check can be invoked in various ways:
򐂰 From the Project menu option within the LPEX editor, as shown in Figure 7-2.
Be sure to save your changes to the source member before you submit a local
compile.
򐂰 In WorkFrame, select the COBOL source member you want to compile and
run Edit —> Compile from the WorkFrame menu bar.
򐂰 In WorkFrame, right-click the COBOL source member you want to compile
and select Compile from the pop-up menu.
Figure 7-2 Run local compile from editor
The project monitor pane in your WorkFrame project lists the results of the
compilation, as shown in Figure 7-3.
Figure 7-3 Compile error feedback in WorkFrame
When you double-click an error message in the project monitor pane, the editor
will load the program source, annotated with all the error messages exactly
where the errors occur. The cursor is placed on the statement in error that you
clicked in WorkFrame (see Figure 7-4).
Figure 7-4 Compile error feedback in the editor
Thus you do not have to switch between an editor screen and a compilation
output screen, as you do in a mainframe based development environment.
Simply fix the problem in the editor, jump to the next error by selecting Actions
—> Next error from the editor menu bar (or press Alt+N), and eliminate all the
errors this way. Save the source and run another local compile for syntax
checking.
Checking your source code this way saves time and resources on the mainframe.
Once your source code is syntactically correct, you can submit a compilation job
on the mainframe in order to produce a load module ready for unit testing.
7.4 Compilation on the host
In order to compile and link a program on the mainframe, you have to run a
compilation job or execute some procedures as you do in a mainframe
development environment. However, VisualAge COBOL provides you with the
means to submit a job or execute a TSO procedure from within the workstation
environment without the need to log on to TSO.
You can edit the JCL or CLIST or REXX procedure just like you can edit the
program source code. How to submit the JCL and check the output of the job, or
how to execute the procedure, is explained in Chapter 8, “Job Monitor and TSO
Commands server” on page 85.
If you want to prepare your program for debugging, refer to Chapter 9,

“Debugging” on page 99 for information about what additional JCL parameters
and statements you need.
8
Chapter 8. Job Monitor and TSO

Commands server
This chapter describes the following topics:
򐂰 Job Monitor
򐂰 TSO Commands server

8.1 Introduction
The most basic tasks of program development can be summarized as follows:
1. Edit the source code.
2. Compile the program.
3. Test the program and find errors.
Those tasks are covered in VisualAge COBOL by the editor (with the ability to
edit remote source files), the workstation based compiler, and the Distributed
Debugger that allows you to control a debugging session from the workstation.
But VisualAge COBOL goes even further than just supporting the basic tasks.
The main idea is that you do not have to log on to TSO at all anymore when
maintaining and developing MVS applications. Not only does this help to
increase the productivity of a programer; it also helps to save mainframe
resources and thus save a lot of money. TSO sessions are among the most
expensive procedures on an MVS system.
In order to achieve this independence from TSO sessions, VisualAge COBOL

provides the means to do the following:
򐂰 Submit batch jobs from the workstation, for example, for host compiles and
batch job execution in debug mode.
򐂰 Manage the job spool and view the job log and sysprint.
򐂰 Execute TSO commands, CLISTs, and TSO REXX procedures from the
workstation.
To perform these tasks, the following features are used:

򐂰 The Job Monitor
򐂰 The TSO Commands server
8.2 Job Monitor

The Job Monitor allows you to submit batch jobs from the workstation and to
monitor the execution of such jobs. It takes the information about your mainframe
systems from the MVS Connections manager (see Chapter 3, “System
connection definitions” on page 21). Therefore, you do not have to configure
anything specifically for the Job Monitor on your workstation.
To start the Job Monitor, select Programs —> IBM VisualAge COBOL —>
Tools - Remote Access —> Job Monitor from the Windows Start menu.
Because the Job Monitor is independent of FFS, you have to provide your TSO
password when you start the Job Monitor, even if you are connected to the host
system through the MVS Connections Manager. When you submit a job from
within a WorkFrame project or the LPEX editor, the Job Monitor is being started
automatically if it is not running already.
8.2.1 Submitting jobs

To submit a job, for example, to compile a program on the mainframe or execute
a batch program, you have four options. With the first two options listed here, the
job is being submitted on the system where the JCL resides. With the last two
options, you can specify the MVS system you want the job to run on. It has to be
one of the systems defined in the MVS Connections Manager.
򐂰 WorkFrame Edit menu action
In WorkFrame, select a JCL member by right-clicking its name. From the
menu bar, select Edit —> Submit job on MVS. Like the message you get in
TSO, a message window appears telling you the job number assigned by
JES, as shown in Figure 8-1.
Figure 8-1 Job submitted message
Again, like the message you receive in TSO (with the notify parameter in the
job card), a message window appears when the job finishes, including the
maximum return code (see Figure 8-2).
Chapter 8. Job Monitor and TSO Commands server 87

Figure 8-2 Job Completed message
򐂰 WorkFrame pop-up menu action

In WorkFrame, right-click a JCL member and select Submit job on MVS from
the pop-up menu. This results in the same actions as the first option
described above.
򐂰 Job Monitor action
From the Job Monitor window select File —> Submit. On the Submit JCL
window (see Figure 8-3), you can select the system on which you want the job
to run, as well as the JCL file you want to submit to this system. The available
host systems are the ones that you defined in the MVS Connections
Manager. If you select another host system than the one you are logged on to
in the Job Monitor, you will be prompted again for the password on the new
system.
Figure 8-3 Submit JCL window
To select the JCL file you want to submit, you can click the button with the three
dots (...). From the next window (Figure 8-4), you can select the drive and the file
containing the JCL. The drive can be local or an MVS system that you are
connected to.
If you select a local JCL file, you can submit it even if you are not connected to
the MVS system through the MVS Connections Manager. If you select an MVS
drive, you have all the directories as defined in the MVS Connections Manager
for this system.
Select a JCL file and click the Submit button on the Submit JCL window. As with
the previous two options to submit a job, you will receive a JCL Submitted
message and a Job Completed message.
Figure 8-4 Select JCL file window

򐂰 LPEX editor action
On MVS you would most likely submit a job from within the editor, and you
can do this with VisualAge COBOL too. If you are editing a file with the file
name extension .jcl, you have an LPEX menu item available called Submit
Job. When you select this action, VisualAge COBOL writes the JCL to a
temporary file and starts the submit action from the Job Monitor window.
The Submit JCL window appears with the JCL file already filled in, as shown
in Figure 8-5.
Figure 8-5 Submit temporary JCL file
The MVS system filled in is the system where the JCL file resides. But you
can still select another system before you submit the job.
Using the submit action in the LPEX editor, you can make changes to the
JCL, submit it, and then close the JCL file without saving the changes. Again,
this is very common when developing on MVS.
8.2.2 Managing job spooling

Once you run a job, you may want to look at the output. The Job Monitor window
(Figure 8-6) lists all the jobs on a system matching a given filter. The default filter
is set to jobs with an owner equal to the user ID defined for the system in the
MVS Connections Manager. If you click a filter, you can see the job details for all
the jobs in the right pane.
Figure 8-6 Job Monitor job details
When you select an individual job from the list, you have the option to cancel,
hold, purge, or release it. This can be achieved by clicking on the corresponding
icon in the tool bar or selecting the action from the context menu. The two tool
buttons on the left are for submitting a job (see “Job Monitor action” on page 88)
and viewing the output of a job.
When you select to view the output of a job, including the job log, JCL, and
system messages, as well as job specific sysout data, the output is presented in
an LPEX editor session. This way you can easily edit and save the output or
apply viewing filters.
If you want to look just at a specific sysout data set, you can select it in the right
pane, right-click, and select View output from the pop-up menu, as shown in
Figure 8-7.

Figure 8-7 Job Monitor view output
8.3 TSO Commands server

The TSO Commands server lets you execute any TSO command, CLIST, or
REXX procedure on an MVS system without logging on to TSO. VisualAge
COBOL provides a specific user interface to launch TSO commands from, or you
can write your own workstation dialogs. Like any other procedure, you can add
procedures using the TSO Commands feature as a WorkFrame action. This is
described later in this chapter.
8.3.1 TSO Commands window

To start the TSO Commands window, select Programs —> IBM VisualAge
COBOL —> Tools - Remote Access —> TSO Commands from the Windows
Start menu. Besides bringing up the TSO Commands window, this will also start
the core services needed to execute a TSO command on the mainframe. Those
are the same core services that the Job Monitor uses.
The TSO Commands window basically consists of an input field and an output
area as shown in Figure 8-8. The host systems that are available to run the
command on are the systems you defined in the MVS Connections manager.
Because the TSO Commands server is independent of FFS, you have to provide
your TSO password when you send a command to a host system, even if you
are connected to this system through the MVS Connections Manager.
Figure 8-8 TSO command execution
All the commands you executed during a session are available from the
command input combination box, so you can rerun them without having to type
them in again.
The command history combination box also lists all the commands executed
during a session. If you select there one of the previously executed commands,
the output produced by that command at the time of its earlier execution is
displayed in the command output area.
The command input field is only used to launch a command or procedure.

If your procedure asks for some input you have to write your own workstation
dialog. The TSO Commands window does not allow to interact with a running
procedure. However, you can pass input as parameters at the time of invocation,
as shown in Figure 8-8.

The CLIST that produced the output in this sample looks as follows:
PROC 1 NAME
WRITE HELLO &NAME
EXIT
The following CLIST would not work with the TSO Commands window because it
contains a READ statement:
PROC 0
WRITE WHO ARE YOU?
READ NAME
WRITE HELLO &NAME
EXIT
In this case you would have to add first your own dialog running on the
workstation. This dialog can be a REXX procedure or even a GUI program. It
would have to collect the input from the user and then pass it as a parameter to
the TSO procedure. How you can launch a TSO procedure from within your own
workstation application (as opposed to using the TSO Command window) is
discussed in the next section. As an example, we explain how to add a TSO
command action to a WorkFrame project.
8.3.2 Add a TSO command action to your project

In 5.4.1, “Create your own actions” on page 64 you can find information on how
to create a WorkFrame action in general. In the following explanation, we take
you step by step through the process of creating a WorkFrame action that asks
for the system time on a mainframe system. If you execute this action, the time is
displayed in the project monitor pane of your WorkFrame action. The purpose of
this sample is to show you how to launch a TSO command from outside the TSO
Commands window.
To create the “time” action, do the following:

1. In your MVS Project, select Actions —> Tools Setup from the menu bar.
2. On the Tools Setup window, right-click Tools and select Add... as shown in
Figure 8-9.
Figure 8-9 Add tool
3. Complete the fields on the Add Action window General page tab, as shown in
Figure 8-10. Make sure that you specify the correct path for the rexx.exe.
Check the Session Monitor check box. It means that you want to receive the
output in the WorkFrame project monitor pane.
This time sample action applies to the project and does not act on a file.
Figure 8-10 Add Ask time action — General page

4. Because the action does not apply to files, there is no input required from the
Types page.
On the Support page, select the Use parameter string radio button and
specify a Project Scoped parameter as shown in Figure 8-11. Specify the
correct directory where you put the actual procedure (gettime.cmd).
Figure 8-11 Add Ask time action — Support page
Here is the gettime.cmd file:

'@ECHO OFF'
trace o
/* The following command runs the TSO command 'time' on the system that is
defined in the MVS Connections Manager with the Short name 'redbooks' */
address cmd
'c:\ibmcobw\jre\bin\java -jar c:\ibmffs\bin\JobMonitor.jar -command system
REDBOOKS time'
exit
This command uses the Java Runtime Environment Version 1.3 which is
shipped with VisualAge COBOL. If you have on your system an earlier JDK or
JRE installed already from another source, you have to make sure that you
specify the correct java.exe in this command.
There are two variables in this procedure, the MVS system where you want to
run the command, and the command itself.
5. On the Menus page, check Add to Project Menu and, if you wish, also Add
to Project Toolbar. The Add to Project menu adds an entry in the Actions
menu of all your existing and future WorkFrame projects, independent of the
type of project.
6. Click OK and close the Tools setup window. You now have an additional
Action available from the Actions menu, called whatever you specified as
Action in step 3. If you also checked Add to Project Toolbar in the previous
step, you will find an additional button on the right of your toolbar in the
Workframe window, as shown in Figure 8-12:
Figure 8-12 Action icon
If the TSO Commands server or the Job Monitor is running already, you can now
execute the action from your project's action menu (or tool bar). The system time
of the MVS system will be displayed in the project monitor command window
within your WorkFrame project.
If you do not want to start the TSO Commands server window or the Job Monitor
before executing a WorkFrame action that launches a TSO command, you can
create another action just to start the core services required for TSO commands.
Proceed as described above for the “Ask time” action. Do not check the Session
Monitor check box on the General page (Figure 8-10 on page 95). This action
does not produce any output to be viewed.
On the Support page, specify another procedure in the project scoped parameter
string entry field (Figure 8-11 on page 96). This procedure should have the
following content:
'@ECHO OFF'
trace o
/* The following command starts the TSO Commands Server daemon. */
address cmd 'c:\ibmcobw\jre\bin\java -jar c:\ibmffs\bin\JMServer.jar'
exit
Again, make sure you use the correct java.exe.

When you start this TSO Commands server daemon, a DOS Command window
opens with a number (see Figure 8-13). You can minimize this window, but do not
close it. In order to stop the daemon, just press Ctrl+C while in the DOS window.
Figure 8-13 TSO Commands daemon
9
Chapter 9. Debugging
This chapter discusses how to prepare programs for debugging in various
execution environments, and how to invoke those programs for testing. It
contains the following topics:
򐂰 Setting up the environment for debugging
򐂰 Preparing a program for debugging
򐂰 Debugging CICS programs
򐂰 Debugging IMS online programs
򐂰 Debugging batch programs
򐂰 Debugging TSO foreground programs
򐂰 Debugging DB2 programs (including Stored Procedures)
򐂰 How to use the Distributed Debugger

9.1 Introduction
With the VisualAge COBOL for Windows NT Remote Debugger, you enter a
whole new world for debugging your host COBOL applications. It even gives you
the opportunity to debug your production applications when using the latest
COBOL compiler on OS/390 (IBM COBOL for OS/390 V2.2 or later, or V2.1 with
corresponding PTFs).
When debugging host programs from the workstation, there are two products
involved:
򐂰 The IBM Debug Tool for OS/390 provides the actual debugging engine. It
runs on the platform where the program execution takes place, which is the
mainframe. It requires the application program to run under Language
Environment.
򐂰 The Distributed Debugger feature of VisualAge COBOL provides the
graphical user interface for the debugging session. It communicates with the
Debug Tool through TCP/IP.
Debugging a program consists of three steps:

򐂰 Preparing the program for debugging
򐂰 Starting the listener on the workstation
򐂰 Executing the program in debug mode
9.2 What can be debugged

With the VisualAge COBOL Remote Debugger, you can debug applications that
run on a remote host in an OS/390 environment from your workstation.
The following execution environments are supported:

򐂰 CICS
򐂰 IMS (both IMS Database Manager and IMS Transaction Manager)
򐂰 Batch (JES)
򐂰 TSO
򐂰 DB2 (including Stored Procedures)
The following languages are supported:

򐂰 COBOL
򐂰 C, C++
򐂰 PL/I
򐂰 Compiled Java Code
򐂰 Assembler
9.3 Overview of debugging setup
In order to understand how to invoke the debugger in the different environments,
it is important to know the elements that are involved. Figure 9-1 shows an
overview of the process and the components involved when debugging a
program remotely.
Language Environment OS/390

runtime parameter:
TEST(,,,VADTCPIP&9.11.22.333:*)
debugging
application program sidefile
subsystem Debug Tool source listing

(CICS, IMS, DB2, batch)
TCP/IP
TCP/IP address 9.11.22.333 TCP/IP

Remote Debugger Daemon
source listing
VisualAge COBOL Distributed Debugger Windows
Figure 9-1 Elements of a debugging session
The application program is running within a subsystem under Language

Environment. If the program has to be debugged, the Language Environment will
do the following:
򐂰 Tell the Debug Tool to become active.
򐂰 Send a corresponding request to the correct workstation where the Remote
Debugger Daemon is running.
򐂰 Start communicating with the Distributed Debugger of VisualAge COBOL.
Chapter 9. Debugging 101

Three additional elements are involved when running a program in debug mode,
as opposed to running it in normal production:
򐂰 The debugger needs debugging information about the application program.
This information can be in the load module itself or it can reside in a separate
file, also known as a sidefile. See 9.5.1, “Using the sidefile option” on
page 104 for more information about this option, which is available with the
newer compiler versions of IBM COBOL for OS/390 or IBM Enterprise
COBOL for z/OS.
򐂰 The source listing produced by the compiler has also to be available during
the debugging session.
򐂰 The Language Environment has to know that the program should be
debugged. It must also know the address of the workstation where the
debugging session is to be conducted using the Distributed Debugger of
VisualAge COBOL.
The first two elements listed here have to be prepared when compiling the
program for testing. This is described in 9.5, “Preparing your program for
debugging” on page 104.
The third element can be provided either at compile time or at execution time,
depending on the execution environment. The sections following the program
preparation discuss the options available for the various runtime environments.
Note: The option to provide the debug execution information at compile

time is available to all the execution environments. This is the CEEUOPT
option. However, except for IMS DC, for all the other execution
environments there is a simpler, more convenient option available.
Therefore, we describe the CEEUOPT option in detail when we discuss
IMS execution, although it is part of the preparation (see 9.7.2, “Using
CEEUOPT” on page 113).
9.4 Setting up your workstation for remote debugging

The Distributed Debugger of VisualAge COBOL provides only the user interface
for the debugging session. The actual debugging takes place on the mainframe
where the Debug Tool sends information to the workstation for display.
Whenever a debugging request is passed to the Debug Tool by an executing

application, the Debug Tool sends a request to the workstation to have the
Distributed Debugger started and initialized. In order to be able to receive this
request, there has to be a listener running on the workstation.
Therefore, independent of the runtime environment on the mainframe, on the
workstation you always have to start the listener before you can run a program
for debugging on the host.
To start the listener, select Programs —> IBM VisualAge COBOL —>
Tools - Remote Access —> Remote Debugger from the Windows start menu.
This starts the IBM Distributed Debugger Daemon on your workstation and
brings up two windows.
Figure 9-2 shows the Remote Debugger window.
Figure 9-2 Remote Debugger — startup window
Figure 9-3 shows the IBM Distributed Debugger Daemon window.
Figure 9-3 IBM Distributed Debugger Daemon window
Important: You can minimize these two windows, but do not close them.
This is basically all you have to do on your workstation to prepare for debugging.
Once you finished debugging host applications, just click Stop on the Distributed
Debugger Daemon window to close both windows.
In the following sections we discuss how to prepare and execute programs for
debugging in the various execution environments.

9.5 Preparing your program for debugging
When running a program in debug mode using a source level debugger like
Debug Tool and VisualAge COBOL Distributed Debugger, two sets of information
must be available:
򐂰 Symbolic debug information tables
򐂰 Source listing
In order to create this information, you have to specify a few things in the JCL
when you compile your program. These requirements are the same regardless of
the target execution environment (batch, TSO, CICS, IMS DC, DB2 SP):
򐂰 Specify the TEST compiler option. This creates the symbolic debug
information tables and writes them into the object module unless you use the
sidefile option (see 9.5.1, “Using the sidefile option” on page 104).
򐂰 Write the SYSPRINT of the compile step to a sequential file or PDS member
that you keep. The data set name of this source listing is being written to the
object module by the compiler. Thus you do not have to specify its location at
runtime when debugging.
The listing data set should have a logical record length of 133 and a record
format of FBA.
򐂰 If the program you are compiling is to be executed in a CICS or IMS online
environment, there are additional adjustments you have to make. See 9.5.2,
“Preparation for CICS” on page 105 and 9.5.3, “Preparation for IMS” on
page 106 for more information.
Refer to “Compile JCL for debugging (general)” on page 136 for sample JCL.
9.5.1 Using the sidefile option

Usually when you prepare a program for debugging, the compiler puts the
debugging information into the load module. This causes the load module to be
inflated which has an impact on the execution performance. Therefore, after
debugging, you have to compile your program again without the TEST option,
before you move it into production.
But with the new production debugging option (which is also called the sidefile
debugging option), the compiler does not write the debugging information into the
object module but rather to a separate file. Therefore you do not have to
recompile your program for production. This also means that, if you encounter a
program error during production, you do not have to recompile the program first
before you can debug it. This way you know for sure that the program you debug
is exactly the same as the one you have in production.
In order to use the sidefile option, do the following:
򐂰 Specify the SYM and SEPARATE sub-options of the TEST compiler option, as
shown here: TEST(ALL,SYM,SEPARATE)
򐂰 Add a SYSDEBUG DD statement to the compile step specifying a data set where
the symbolic debug information tables are written to. This is the so called
sidefile.
The SYSDEBUG DD statement must specify the name of a sequential data set,
the name of a PDS or PDSE member, or an HFS path. The data set logical
record length must be between 80 and 1024, the record format F or FB.
You do not need to specify any additional data set in the execution JCL. As
with the source listing, the location of the sidefile is hard coded in the object
module, therefore you have to keep that same data set for as long as the load
module is in production.
Refer to “Compile JCL using sidefile option” on page 136 for a sample JCL.
9.5.2 Preparation for CICS

In addition to the changes described above, you have to link an additional
module to your application program, if this program is running under CICS. What
module you have to link depends on the option you use to invoke the debugger
when executing the program in test mode:
򐂰 If you use the standard CICS transaction to set up debugging (DTCN) then
you have to link the standard EQADCCXT module to your application
program. This module can be found in the Debug Tool SEQAMOD data set
(for example EQAW.V1R2M0.SEQAMOD).
See 9.6.1, “Using DTCN” on page 107 for more information about the DTCN
transaction.
“DTCN transaction” on page 137 shows a sample compile and link JCL for
use with the DTCN transaction execution.
򐂰 If you use your own user option module you have to link CEEUOPT. Refer to
9.7.2, “Using CEEUOPT” on page 113 for more information about the
CEEUOPT user exit.
“CEEUOPT” on page 138 shows a sample compile and link JCL for use with
the user option execution.
You can use DFHYXTVL and DFHEITVL as sample translate, compile, and link
jobs for your CICS programs. These members can be found in the CICS system
SDFHPROC data set (for example CICS.V4R1M0.SDFHPROC).

9.5.3 Preparation for IMS
There are two options available to invoke the debugger in an IMS online
execution environment, CEEROPT and CEEUOPT. See 9.7, “Debugging an IMS
online program” on page 111 for a discussion of those two options.
If you use CEEROPT, you do not have to add anything specific to the compile
and link job, except for the usual TEST compile parameter and the data set name
for the sysprint.
If you use CEEUOPT, you have to link this module to your application program,
as with any other execution environment. Therefore, before you can prepare your
application program for debugging, you have to create the CEEUOPT module, as
described in 9.7.2, “Using CEEUOPT” on page 113.
“Compile JCL for IMS” on page 138 shows example jobs and programs for the
use with the two options, CEEROPT and CEEUOPT.
9.6 Debug a CICS program

Make sure the Debug Tool and TCP/IP sockets are installed and set up correctly
in your CICS. For a description on how to do this, see Appendix B, “The Debug
Tool and TCP/IP in CICS” on page 151.
As explained above, there is always the possibility to use the CEEUOPT option to
initiate the debugger when executing a program. This option is further described
in 9.7.2, “Using CEEUOPT” on page 113. In order to run the program in debug
mode when using the CEEUOPT, all you have to do is to run the transaction or
the ECI program that calls the program to be debugged. The debugger user
interface will automatically start and load the program when it is called.
If you link the CEEUOPT module to your application program, the program will
always execute in debug mode. If you just want to run it without debugging, you
will have to relink it first without the CEEUOPT module.
Therefore, with CICS, there is a special transaction that allows you to specify how
you would like to execute your program. In order to use this transaction, you have
to link the EQADCCXT standard Debug Tool module to your application program
(see 9.5.2, “Preparation for CICS” on page 105).
In any case, the CICS region startup JCL needs one additional DD statement to
enable TCPIP. The DD name is SYSTCPD and should specify the TCPIP.DATA
data set. Also, the SEQAMOD library of the IBM Debug Tool (for example
EQAW.V1R2M0.SEQAMOD) has to be concatenated in the STEPLIB.
9.6.1 Using DTCN
On your CICS terminal, enter the transaction DTCN. You will see the panel shown
in Figure 9-4.
DTCN Debug Tool CICS Control - Primary Menu SCSCCOB1
Select the combination of resources to debug (see Help for more information)
Terminal Id ==> T018
Transaction Id ==>
Program Id ==>
User Id ==>
Select type and ID of debug display device

Session Type ==> MFI MFI, TCP, APPC, LU2
PWS Type ==> VAD, CODE
Port/SessionId ==> TCP Port or APPC Session ID
Display Id ==> T018
Generated String: TEST(ALL,,PROMPT,MFI%T018:*)

Repository String: No string currently saved in repository
Figure 9-4 Debug Tool CICS Control - Primary Menu (example 1)
By default, this panel just shows the last four digits of your terminal ID and a MFI
session type. MFI is the MainFrame Interface, the text based user interface for
the Debug Tool that can be used when there is no TCP/IP and/or VisualAge
COBOL available to use the Distributed Debugger graphical user interface.
To use the remote debugger, you must choose a session type of TCP, a PWS type
of VAD, and your display ID for the remote debugger. The display ID is the terminal
ID in the case of an MFI session type, or the IP address of the workstation in the
case of a TCP session type, as when using the VisualAge COBOL Distributed
Debugger.
The debugger can be initiated based on four resources:

򐂰 Terminal
򐂰 Transaction
򐂰 Program
򐂰 User ID

Terminal
The panel in Figure 9-5 shows a setup where your debugger is based upon the
CICS session’s terminal ID. You can see also that we added the session type, the
PWS type and the display ID.
With this setup, any program compiled with the test compile option which is
invoked through a transaction entered at the terminal T018 will start the remote
debugger.
Terminal Id ==> T018
Transaction Id ==>
Program Id ==>
User Id ==>

Session Type ==> TCP MFI, TCP, APPC, LU2
PWS Type ==> VAD VAD, CODE
Display Id ==> 9.112.16.168
Generated String: TEST(ALL,,PROMPT,VADTCPIP&9.112.16.168:*)

Figure 9-5 Debug Tool CICS Control — Primary Menu (example 2)
Transaction
In the panel shown in Figure 9-6, you see a setup where your debugger is based
upon the transaction ID, for example VABX. When you start this transaction from
any CICS terminal, and the program that goes with it was compiled with the test
compile option, the remote debugger will be started.
Terminal Id ==>
Transaction Id ==> VABX
Program Id ==>
User Id ==>

Display Id ==> 9.112.16.168

Program
The panel in Figure 9-7 shows a setup where debugging is based upon the
program ID, for example a program named BUGBAT. Whenever this program is
executed in this CICS region, whether through a transaction or a program call or
link, and the program was compiled with the test compile option, the remote
debugger will be started on the terminal with the TCP/IP address 9.112.16.168.
Terminal Id ==>
Transaction Id ==>
Program Id ==> BUGBAT
User Id ==>

Display Id ==> 9.112.16.168


User ID
In the panel shown in Figure 9-8, debugging is based upon the CICS user’s user
ID, in this example, KARLB. That means that from whatever terminal this user is
logged on to and enters any transaction that starts any program that was
compiled with the test compiler option, the remote debugger will start on the
workstation with the TCP/IP address 9.112.16.168.
Terminal Id ==>
Transaction Id ==>
Program Id ==>
User Id ==> KARLB

Display Id ==> 9.112.16.168

You can also use combinations of the above selections. For example if you
specify a transaction ID and a user ID, the debugger will only be started when the
specified user runs the transaction. This way other users can run the same
transaction for their own purpose without causing the debugger to start on
somebody else’s workstation.
If you select any of these options and the setup was correct the Distributed
Debugger window appears as shown in Figure 9-9.
Figure 9-9 Distributed Debugger window with CICS program
9.7 Debugging an IMS online program

Before VisualAge COBOL became available, if you wanted to debug an IMS
transaction, you had to use the batch terminal simulator (BTS), but with the
VisualAge COBOL Distributed Debugger, you can also debug applications
directly in the IMS Transaction Monitor MPP region.
As with every other environment, you have to provide the TEST runtime
parameter to Language Environment. But unlike the other environments, with
IMS there is no facility to do this at the execution time of the program that has to
be debugged. There is no IMS transaction like the DTCN transaction in CICS
(see 9.6.1, “Using DTCN” on page 107) at the moment.

There are two ways to pass the TEST option to Language Environment:
򐂰 Use the CEEROPT user exit from the SCEESAMP library and add it to your
dependent IMS region STEPLIB (LE Library Routine Retention need to be
pre-initialized). This way all the programs in the region run in debug mode if
they have been compiled with the TEST option.
򐂰 Use a CEEUOPT options module and link it to the programs you want to
debug. This way only specific programs will run in debug mode.
In any case, the IMS region startup JCL needs one additional DD statement to
enable TCPIP. The DD name is SYSTCPD and should specify the TCPIP.DATA
data set. Also, the SEQAMOD library of the IBM Debug Tool (for example
9.7.1 Using CEEROPT

CEEROPT is an assembler language source file used to establish region-wide
LE run-time options defaults. The default values contained in the CEEROPT
source file can be edited, assembled, and linked at any time, to create the
CEEROPT stand-alone load module.
All transactions that run in the IMS MPP region operate using these default
values for the run-time options. The CEEROPT module resides in a user
specified load library that has to be allocated to STEPLIB in the startup job for
the IMS region.
Enabling LE library routine retention

To be able to use CEEROPT in IMS, the Language Environment runtime option
LRR (library routine retention) must be in effect. To use LRR in an IMS
dependent region, you must do the following:
1. In your JCL or procedure used to bring up IMS dependent regions, specify
that you want IMS to invoke dependent region pre-initialization routines. Do
this by specifying a suffix on the preinit keyword of the IMS dependent
region.
2. In the DFSINTxx member of the IMS.PROCLIB library (where xx is the suffix
specified by the preinit keyword in step 1 above), include the name
CEELRRIN.
When the module CEELRRIN is invoked by IMS, Language Environment library

routine retention is initialized.
Creating a CEEROPT module

In order to create a CEEROPT module for debugging, do the following:
1. Copy member CEEWROPT from the Language Environment SCEESAMP
library (for example CEE.SCEESAMP) into a user JCL library and edit it.
2. Copy member CEEDOPT or CEECOPT from the LE SCEESAMP library into
your CEEWROPT member in place of the comment lines following the SYSIN
DD statement.
3. Change the CSECT name and labels from CEEDOPT to CEEROPT.
4. Change the parameters on the CEEXOPT macro statement to reflect the
values you have chosen for this region-specific run-time options load module.
5. Code just the options you want to change. Options you omit from CEEROPT
will remain the same as the installation defaults.
The TEST option you have to add for debugging looks like this:
TEST=((ALL,*,PROMPT,VADTCPIP&&9.11.22.333:*),NONOVR)
where the IP address is the address of your workstation where the Remote
6. Change DSNAME=YOURLIB in the SYSLMOD DD statement to the name of
the partitioned data set into which you want your CEEROPT load module to
be link-edited. This data set does not need to be APF authorized. If you
currently have a CEEROPT load module in your data set, it will be replaced by
the new version.
The CEEROPT module has to be in a load library that is allocated to
STEPLIB in the startup job for the IMS region.
7. Check the SYSLIB DD statement to ensure the data set names are correct.
8. Submit the job. CEEWROPT should run with a condition code of 0.
You can find a sample job to create a CEEROPT module in “CEEROPT module”
on page 145.
9.7.2 Using CEEUOPT

The application programmers at your site might need more than one set of
run-time options. You can create application-specific run-time options modules
using the Language Environment CEEWUOPT sample job.
Each run of the CEEWUOPT sample job can create a new CEEUOPT options
module in a user-specified library. The application programmer can include one
of these CEEUOPT modules when link-editing an application. The options in
CEEUOPT override the default options in CEEDOPT or CEECOPT only for the
specific program it is linked to, unless NONOVR was specified for the option
when CEEDOPT or CEECOPT was created.

CEEWUOPT does not use SMP/E to create the options module, so it can be run
several times to create several different CEEUOPT modules, each in its own
user-specified library. Refer to the Language Environment documentation to
select the values for your application-specific run-time options modules.
To invoke the remote debugger you only need the TEST option in the form of
CEEXOPT TEST=(,,,"VADTCPIP&&9.11.22.333:*")
Creating a CEEUOPT module

In order to create a CEEUOPT module for debugging, do the following:
1. Copy member CEEWUOPT from the Language Environment SCEESAMP
library (for example CEE.SCEESAMP) into a user JCL library and edit it.
2. Copy member CEEUOPT from the LE SCEESAMP library into your
CEEWUOPT member in place of the comment lines following the SYSIN DD
statement.
3. Change the parameters on the CEEXOPT macro statement in CEEUOPT to
reflect the values you have chosen for this application-specific run-time
options module.
4. Code just the options you want to change. Options you omit from CEEUOPT
will remain the same as the installation defaults.
The TEST option you have to add for debugging looks like this:
TEST=(,,,"VADTCPIP&&9.11.22.333:*")
Here the IP address is the address of your workstation where the Remote
5. Change DSNAME=YOURLIB in the SYSLMOD DD statement to the name of
the partitioned data set into which you want your CEEUOPT load module to
be link-edited. If you currently have a CEEUOPT load module in your data set,
it will be replaced by the new version.
6. Check the SYSLIB DD statement to ensure the data set names are correct.
7. Submit the job. CEEWUOPT should run with a condition code of 0.
You can find a sample job to create a CEEUOPT module in “CEEUOPT module”
on page 146.
Now, if you have done all of this, you can create an IMS transaction to start your
program, issue a stop and start region, start your program, and start your
transaction which will start your debug session on your workstation. This is
shown in Figure 9-10.
Figure 9-10 Distributed Debugger window with an IMS transaction
9.8 Debug a batch program

As with any other environment, you can link the CEEUOPT module to your batch
program to pass the TEST runtime parameter to Language Environment.
But a much easier and a much more flexible way to specify the TEST runtime
option in a batch job is to provide a parameter in the EXEC statement.
The parameter has the format:

PARM=(‘/TEST(,,,VADTCPIP&9.11.22.333:*)’)
In this statement, the IP address is the address of your workstation where the
Remote Debugger Daemon is running.
When debugging a batch program you need one additional DD statement in your
JCL to enable TCPIP. The DD name is SYSTCPD and should specify the
TCPIP.DATA data set.
Also, the SEQAMOD library of the IBM Debug Tool (for example
You can find a sample of execution JCL in “Debug a batch program” on

page 146.

In batch, as with any other environment, you can run several copies of your load
module at the same time in remote debug mode, just to test and see how it reacts
with different runtime libraries and how the differences are in the different levels
of your module.
Figure 9-11 shows the debugger window with five copies of the same program
running at the same time. With the tabs right below the icon bar, you can control
which version you are currently debugging by clicking on the tab you want to
have in the foreground.
Figure 9-11 Multiple debugging sessions
9.9 Debugging a TSO foreground program

A TSO foreground program is similar to a batch program. The difference is that
there is no JCL to describe the execution environment. Instead, this has to be
done in a TSO command prompt.
Make sure Language Environment’s SCEERUN library and Debug Tool’s
SEQAMOD library are in the linklist or your system. If not, you can use the
TSOLIB command to STEPLIB them.
Also, SYSTCPD has to be allocated with the TCPIP.DATA data set. To do this just
enter the following command in the TSO command prompt before you call the
program you want to debug:
alloc dd(systcpd) da(‘TCPIP.DATA’) shr reuse
If TCP/IP is not available, you will receive the following message:

EQA9999E - Debug Tool TCPIP error
EQA9999E - Loc=005 Func=INITAP Fc=1011 Rc=-1
InitApi ErrNo = 000003F3
***
To start your program for debugging, type the following command in the TSO
command prompt:
call 'redbooks.appl.load(dttest)' '/TEST(,,,VADTCPIP&9.11.22.333:*)'
Here, the IP address is the address of your workstation where the Remote
9.10 Debugging a DB2 program

Except for the DB2 Stored Procedure, a DB2 program is a program that
accesses a DB2 database, but it actually runs in one of the other environments.
For example, it could be a CICS program that accesses DB2 or a batch program
that accesses DB2. Therefore, when it comes to debugging those programs, they
have to be handled as CICS or batch programs. There is nothing additional that
has to be done.
However, the JCL of a DB2 batch program looks slightly different and a DB2
Stored Procedure is actually running within DB2.
9.10.1 DB2 batch program

A DB2 batch program, a batch program that accesses DB2 tables, is running
under the TSO batch monitor. Therefore the TEST runtime parameter must not
be specified in the EXEC statement, but rather with the TSO command that runs
the DB2 program.

As with a regular batch program, you need an additional DD statement in your
JCL to enable TCPIP. The DD name is SYSTCPD and should specify the
TCPIP.DATA data set.
Also, the SEQAMOD library of the IBM Debug Tool (for example
You can find a sample execution JCL for a DB2 batch program in “Debug a DB2
batch program” on page 147.
9.10.2 DB2 Stored Procedures

DB2 Stored Procedures are user-written programs that are stored at the
database server and can be invoked by client applications using SQL
statements.
Stored Procedures are predefined processes that execute the DB2 server side of
applications. They can be called locally, on the same system where the
application runs, or remotely from a different system.
The SQL CALL statement is used to invoke a Stored Procedure. A Stored

Procedure can receive parameters from the calling program and return data back
to it.
The DB2 Stored Procedure has to be defined to the database manager using the
CREATE PROCEDURE statement. That is where you have to define the TEST
runtime parameter for Language Environment if you want to debug the Stored
Procedure.
Here is a sample CREATE PROCEDURE statement:

CREATE PROCEDURE CS_ADD_CUSTOMER
(IN CHAR(20),IN CHAR(20),IN CHAR(30),
INOUT INT,INOUT CHAR(80),INOUT CHAR(240))
LANGUAGE COBOL
EXTERNAL NAME ADDCUST
PARAMETER STYLE GENERAL
WLM ENVIRONMENT DSNAWLMP
PROGRAM TYPE MAIN
DYNAMIC RESULT SETS 1
RUN OPTIONS 'TEST(,,,VADTCPIP&9.112.27.253:*)';
If you want to run the Stored Procedure without debugging you can use the
ALTER PROCEDURE statement:
ALTER PROCEDURE CS_ADD_CUSTOMER
RUN OPTIONS 'NOTEST';
Or, to run it in debug mode again, just run the following statement:
ALTER PROCEDURE CS_ADD_CUSTOMER
RUN OPTIONS 'TEST(,,,VADTCPIP&9.112.27.253:*)';
The startup JCL for the workload manager under which the Stored Procedure is
to be running needs one additional DD statement to enable TCPIP. The DD name
is SYSTCPD and should specify the TCPIP.DATA data set. Also, the SEQAMOD
library of the IBM Debug Tool (for example EQAW.V1R2M0.SEQAMOD) has to
be concatenated in the STEPLIB.
You can find a sample WLM startup JCL in “DB2 WLM startup procedure” on
page 148.
9.11 Using the Distributed Debugger user interface

Once a program is compiled with the TEST option and it is running with the TEST
runtime parameter, the VisualAge COBOL Distributed Debugger starts, if the
Remote Debugger Daemon is running on the workstation with the TCP/IP
address specified in the TEST runtime parameter.
This Distributed Debugger is not only used to render the information from the
Debug Tool on MVS to the workstation. It is also a debugging engine used when
testing a program that is executing on the workstation. In addition, the Distributed
Debugger supports not just COBOL, but also PL/I, C/C++, and Java. It runs on
Windows and AIX.
When you are using the Distributed Debugger for example to test a COBOL
program that is running on MVS, be aware that some features and options you
might find are only relevant with other languages or platforms.
If you have the Distributed Debugger up and running with one of your programs,
we encourage you to explore the menu options, including options from pop-up
menus (right-click) in the source listing and the other panes, in order to get
acquainted with all the features of this tool.
In this section, we only discuss a few items to get you started, such as:
򐂰 Some menu options
򐂰 The source listing pane
򐂰 The control pane
򐂰 The value pane

9.11.1 Menu options
The options on the menu bar are context sensitive, which means that you see
different options depending on the pane you selected and the tabs within the
panes.
An option that is always there is the File option (see Figure 9-12). Among other
actions, it lets you increase and decrease the font size in your debugger window,
and you can select preferences. This gives you some control over the layout of
your debug session.
Figure 9-12 Debugger file pulldown menu
Select Preferences... from the File menu to start the Application Preferences
window (Figure 9-13).
Figure 9-13 Application Preferences — Debug
If you select Debug, for example, you can check the Allow Tool Tip Evaluation
check box. This option enables hover help. Hover help provides you with a quick
way to view the contents of variables in the Source pane. When you rest the
pointer on a variable, a pop-up menu appears displaying the contents of that
variable. This is shown in Figure 9-14.
Figure 9-14 Hover variable content display

The profiles are files that contain information about your debugging session, like
breakpoints you set or variables you specified for monitoring. There is a separate
profile for every program you debug. When you start a program in debugging
mode, the Distributed Debugger first checks if there is already a profile for this
program. If it finds a profile, it loads the file. This way you do not have to specify
your breakpoints or variables to monitor every time again.
Figure 9-15 shows the Application Preferences Profiles window. Here you can
delete a profile if you want to start from scratch the next time you start the
program in debug mode. The profiles have a file extension starting with @w or
@m, depending on if the program executes on Windows or on MVS. This way
you can have the same program name on both platforms without confusing the
Distributed Debugger.
Figure 9-15 Debugger profiles
The exception filters and other settings are also stored in the profile which means
that you can set them individually for each program you are debugging. You can
select the types of exceptions or the exception level you want the debugger to
recognize, as shown in Figure 9-16.
Figure 9-16 Exception filters
The Debug and the Source menu options are also always present. The Debug
pull-down menu offers the same actions as the icon bar to control the debugging
session, and a few more. It lets you:
򐂰 Execute the program step by step, one statement at a time.
򐂰 Run to a breakpoint.
򐂰 Terminate the program by running it to completion.
򐂰 Automatically stop at all entry points or when date fields are accessed.
򐂰 Run from the last executed statement to the cursor position in the source
without having to set a breakpoint there.
򐂰 Jump to the cursor position in the source without executing the statements
between the last executed statement and the statement at the cursor position.
The Distributed Debugger Source pull-down menu contains options that deal with
the content of the source pane. For example, you can:
򐂰 Find text and entry points in source.
򐂰 Set some breakpoints (there are more options in the Breakpoints menu,
available when Breakpoints are selected in the control pane).
򐂰 Enable the hover help to view the contents of variables in the source pane
򐂰 Change the font size in the source pane.
򐂰 Select the source, disassembly, or a mixed view.

9.11.2 Source listing pane
The source pane contains the source listing of the program you are debugging.
On the left side there is a gray area with the line numbers. The line numbers and
the source statements are either blue for executable statements, or black for
code that cannot be executed, like comment lines or data definitions.
The statement that will be executed next is highlighted with a light blue
background and an arrow in the line number area.
To set line breakpoints, just double-click with the left mouse button on the line
number. The line number is then marked with a red dot to indicate that execution
will stop before executing this statement when you select run from the Debug
menu. This dot turns gray when you disable the breakpoint. Double-click that dot
again to delete the line breakpoint. To set, delete, disable, or enable line
breakpoints, you can also click on a line using the right mouse button, and select
the appropriate action from the pop-up menu.
Mark a variable name by double-clicking on it. Right-click the marked name and
select options from the pop-up menu to add the variable to the monitor (see
9.11.4, “Value pane” on page 128) or find other occurrences of the variable in
your source.
Figure 9-17 shows an example of a source pane with an active breakpoint on line
12 and a temporarily disabled breakpoint on line 15. Execution is stopped and
the next line to be executed in the program when the user selects step or run is
line 10.
Figure 9-17 Debugger source pane
9.11.3 Control pane

The IBM Distributed Debugger control panes let you control stacks, breakpoints
and modules.

Stacks
Figure 9-18 shows a Stacks control pane with the stack properties. You can use
the Stacks control pane to view program call stack information. Initially, the call
stack display trees are collapsed so only thread numbers and thread names are
shown. You can expand each call stack tree structure to display the names of all
entries in the call stack.
When you select a thread or entry, the Stacks control pane displays its source.
Use the pop-up menu in the Stacks control pane to view call stack properties.
Figure 9-18 Stacks control pane
Breakpoints
The Breakpoints control pane shows all the breakpoints that have been set so far
in this debug session, or on a previous debug session for the same program if
there is a profile for this program available.
When you click a function or line breakpoint in the list, the arrow in the line
number area of the source pane indicates where in the source code the
breakpoint is set. Deferred breakpoints cannot be seen in the source pane.
The breakpoint entries in the list provide you with a summary of the breakpoints'
properties. A pop-up menu selection available by right-clicking allows you to view
these properties in greater detail. Pop-up menu options also let you enable or
disable breakpoints and delete breakpoints.
Figure 9-19 shows a Breakpoints control pane with entry and line breakpoints.
This thread contains a main program that calls a subprogram. The entry
breakpoint is set on the subprogram, as well as one of the line breakpoints.
Figure 9-19 Breakpoints control pane
Modules
Use the Modules control pane to view program modules, compilation units, and
entry points. Each module display tree can be expanded to display the names of
all compilation units in the module. Each compilation unit can then be expanded
to display the names of all entry points in the compilation unit.
Initially, module display trees are shown for only those components containing
debug information. To display all program components used by the program
being debugged, check the Show All Components selection in the Modules
pull-down menu.
When a program module, compilation unit, or entry point is selected, its source
code is displayed in the source pane.

You can see program module, compilation unit, and entry point properties by
using a pop-up menu in the Modules control pane. Function breakpoints can also
be set by using a pop-up menu in the Modules control pane.
Figure 9-20 shows a Modules control pane with one program module and two
compilation units, one entry point each.
.
Figure 9-20 Modules control pane
9.11.4 Value pane

In the value pane there are several tabs that give you control over variables,
storage and registers.
Monitors
The monitors value pane shows variables that you previously added. To add a
variable to the monitors do the following:
1. Mark the variable anywhere in the source pane, for example, by
double-clicking on the name.
2. Right-click the marked variable name.
3. Select Add to Program Monitor from the pop-up menu.
Right-click a variable in the monitor pane for action you can perform against the
variable, like remove it from the monitor (delete), or change the representation
from character to hex or vice versa. Another option is editing the value of the
variable, which can also be done by double-clicking on it (see Figure 9-21).
After you changed the value of a variable you have to press Enter to save the
changes. If you want to cancel your changes, just click the variable name before
you press Enter.
Figure 9-21 Monitors value pane
Locals
In the locals pane you can monitor all the variables, and you can also edit the
contents and everything else described for the monitor pane. But unlike with the
monitors pane, where you only see the variables that you put there, in the locals
pane you automatically have all the variables that are accessible to the program
that is currently executing in the debug session. Those variables are being put
there by the debugger, once the program is initialized.
Storage
In the storage pane you can view the actual storage contents, change the
representation and edit the registers and the contents.

If you want to see the storage of a specific variable, you can add the variable to
the storage monitor the same way you add it to the program monitor (see
“Monitors” on page 128). The debugger then creates a new tab in the value pane
with the name of the variable to be monitored. On this pane you have there are
two additional push buttons:
Go to Address Contains the address of the location that the new pane has
been opened to. If you have scrolled away from this address,
clicking this push button causes a return to the location.
Delete Monitor Removes the new Storage Monitor pane.
Figure 9-22 shows the storage pane with the option to monitor the variable
TOTIN.
Figure 9-22 Storage value pane
Registers
In the registers pane you can watch the registers and you can also edit or map
the storage areas and display the contents of a selected storage block according
to a user-defined layout specified in an XML file.
Figure 9-23 shows a sample of a registers pane and how to map the storage by
right-clicking a register.
Figure 9-23 Registers value pane
The sample in Figure 9-24 shows the mapping of GPR register 12 from above.
The mapping contains the DSA, the backchain, and the save area registers in the
mapping pane.
Figure 9-24 Mapping value pane

9.11.5 Debugging an exception
Using the VisualAge COBOL debugger is especially useful when dealing with an
application exception.
Let us assume you run a program on your MVS system and the program abends
with a system 0CB error. You can probably find out what the problem is by
reading a dump. But it is much more fun and easier to use the remote debugger.
Execute your program in debug mode. When the Distributed Debugger is started
run your program (F5) without setting any breakpoints. When the exception is
encountered a message window shows up as in Figure 9-25.
Figure 9-25 Application exception message
When you click OK, the window closes. In the Distributed Debugger source pane
the statement that caused the exception is highlighted. The debugger actually
backs up this statement so you can rerun it. You might remember that always the
statement is highlighted that is to be executed next.
Before you execute the statement again you might want to look at the content of
the variables involved, as shown in Figure 9-26.
Figure 9-26 Debug an exception — monitor variables
As you can see, this statement is dividing something by a variable that contains
zero. To make sure that this is really the problem, or in order to be able to
continue with the debugging session, you can change the value of this variable
as described in , “Monitors” on page 128. In the icon bar, or the Debug menu, you
have new options enabled for stepping, running, or retrying an exception.
If you change the value of that variable to something bigger than zero and click
the button to retry the exception (see Figure 9-27), you will be able to continue
with the program. Put the cursor on a statement before the one that caused the
exception and select Jump to Location from the Debug menu. Now you can
step through that statement again with the new value and you have the proof that
the problem was caused by an invalid input that the program received.

Figure 9-27 Debug an exception — fix the problem
A
Appendix A. Sample code

This appendix contains sample JCL and program code to illustrate some of the
instructions in Chapter 9, “Debugging” on page 99. Some specifics are
highlighted in the samples.

Compile JCL for debugging (general)
Here is a simple compile job for a batch program. Except for the fact that for a
DB2 program there is an additional precompile step, this compile JCL also
applies to compiling a DB2 program, including a DB2 Stored Procedure. See 9.5,
“Preparing your program for debugging” on page 104 for more information about
compiling a program for test.
//CONZETTC JOB (999,POK),NOTIFY=CONZETT,
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),TIME=1440
//COB EXEC PGM=IGYCRCTL,
// PARM='QUOTE,LIB,OBJECT,XREF,RENT,TEST'
//STEPLIB DD DSNAME=IGY.V2R2M0.SIGYCOMP,DISP=SHR
//SYSLIB DD DSNAME=CONZETT.AJC.COPY,DISP=SHR
//SYSIN DD DSNAME=CONZETT.AJC.COBOL(HELLO),DISP=SHR
//SYSPRINT DD DSNAME=CONZETT.AJC.LISTING(HELLO),DISP=SHR
//SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSDA,
// DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
// DCB=(BLKSIZE=3200)
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//LKED EXEC PGM=HEWL,COND=(8,LT,COB),REGION=4096K
//SYSLIB DD DSNAME=CEE.SCEELKED,DISP=SHR
// DD DSNAME=CONZETT.AJC.LOAD,DISP=SHR
// DD DSNAME=SYS1.LINKLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=CONZETT.AJC.LOAD(HELLO),DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//LKED.SYSIN DD *
ENTRY HELLO
NAME HELLO(R)
/*
Compile JCL using sidefile option

This is the same job as in “Compile JCL for debugging (general)” on page 136,
but with the production debugging or sidefile option. See 9.5.1, “Using the sidefile
option” on page 104 for more information about the sidefile option.
//CONZETTC JOB (999,POK),NOTIFY=CONZETT,
//COB EXEC PGM=IGYCRCTL,
// PARM='QUOTE,LIB,OBJECT,XREF,RENT,TEST(SYM,SEPARATE)'
//STEPLIB DD DSNAME=IGY.V2R2M0.SIGYCOMP,DISP=SHR
//SYSLIB DD DSNAME=CONZETT.AJC.COPY,DISP=SHR
//SYSIN DD DSNAME=CONZETT.AJC.COBOL(HELLO),DISP=SHR
//SYSPRINT DD DSNAME=CONZETT.AJC.LISTING(HELLO),DISP=SHR
//SYSDEBUG DD DSNAME=CONZETT.AJC.DEBUG(HELLO),DISP=SHR
//SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSDA,
// DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
// DCB=(BLKSIZE=3200)
//LKED EXEC PGM=HEWL,COND=(8,LT,COB),REGION=4096K
//SYSLIB DD DSNAME=CEE.SCEELKED,DISP=SHR
// DD DSNAME=SYS1.LINKLIB,DISP=SHR
//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=CONZETT.AJC.LOAD(HELLO),DISP=SHR
//LKED.SYSIN DD *
ENTRY HELLO
NAME HELLO(R)
/*
Compile JCL for CICS

There is a slight difference between the JCL used to compile and link a CICS
program for execution with the DTCN transaction or the user exit CEEUOPT.
Here are samples for both options. See 9.5.2, “Preparation for CICS” on
page 105 for more information about the options.
DTCN transaction
Note that in this job the module EQADCCXT to be linked is found in the Debug
Tool product library.
//KARLBDT JOB (999,POK),NOTIFY=KARLB,
//*ROC JCLLIB ORDER=(KARLB.PROCLIB)
Appendix A. Sample code 137

//STEP1 EXEC DFHEITVL,
// PARM.TRN='QUOTE,COBOL2',
// PARM.COB='XREF,NODYNAM,LIST,MAP,LIB,QUOTE,TEST(ALL)',
// PARM.LKED='LIST(SUMMARY),MAP,XREF,AMODE=31,RMODE=ANY',
// INDEX='CICSTS13.CICS'
//TRN.SYSPRINT DD SYSOUT=*
//TRN.SYSIN DD DISP=SHR,DSN=REDBOOKS.APPL.COBOL(BUGBAT)
//COB.SYSPRINT DD DISP=SHR,DSN=REDBOOKS.APPL.LISTING(BUGBAT)
//LKED.DTCN DD DISP=SHR,DSN=EQAW.V1R2M0.SEQAMOD
//LKED.SYSLMOD DD DISP=SHR,DSN=REDBOOKS.APPL.LOAD
//LKED.SYSPRINT DD SYSOUT=*
//LKED.SYSIN DD *
INCLUDE DTCN(EQADCCXT)
NAME BUGBAT(R)
/*
CEEUOPT
Note that in this job the module CEEUOPT to be linked is found in a user library
because the module has to be assembled first by the user.
//KARLBDT JOB (999,POK),NOTIFY=KARLB,
//*ROC JCLLIB ORDER=(KARLB.PROCLIB)
//STEP1 EXEC DFHEITVL,
// PARM.TRN='QUOTE,COBOL2',
// PARM.COB='XREF,NODYNAM,LIST,MAP,LIB,QUOTE,TEST(ALL)',
// PARM.LKED='LIST(SUMMARY),MAP,XREF,AMODE=31,RMODE=ANY',
// INDEX='CICSTS13.CICS'
//TRN.SYSPRINT DD SYSOUT=*
//TRN.SYSIN DD DISP=SHR,DSN=REDBOOKS.APPL.COBOL(BUGBAT)
//COB.SYSPRINT DD DISP=SHR,DSN=REDBOOKS.APPL.LISTING(BUGBAT)
//LKED.UOPT DD DISP=SHR,DSN=REDBOOKS.APPL.LOAD
//LKED.SYSLMOD DD DISP=SHR,DSN=REDBOOKS.APPL.LOAD
//LKED.SYSPRINT DD SYSOUT=*
//LKED.SYSIN DD *
INCLUDE UOPT(CEEUOPT)
NAME BUGBAT(R)
/*
Compile JCL for IMS

The following sample contains compile and link JCL with instream IMS online
programs. Refer to 9.5.3, “Preparation for IMS” on page 106 for more information
about preparing an IMS program for debugging.
With CEEROPT
Besides the TEST compiler option there is nothing specific to be added to this
JCL.
//HAIMO1 JOB (999,POK),'BOB HAIMOWITZ',CLASS=A,MSGCLASS=T,
// NOTIFY=&SYSUID,TIME=1440,REGION=0M
/*JOBPARM L=999,SYSAFF=SC47
//*************
//* COBOL IMS APPLICATION; ALL MODULES COMPILED WITH TEST
//* COMPILE & LINK EDIT THE COBOL IMS APPLICATIONS
//* COMPILE COBIMS1, IAP26A, LINK TO PRODUCE IMSTESTL.TNUC1(IAPMDI26)
//*************
//* COMPILING COBIMS1
//*************
//COBOL1 EXEC PGM=IGYCRCTL,
// PARM='TEST,NODYNAM,LIB,MAP,OBJECT,RES,APOST,XREF'
//STEPLIB DD DSN=IGY.V2R1M0.SIGYCOMP,DISP=SHR
//SYSLIB DD DSN=MQM.SCSQCOBC,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR
//* DD DSN=USER.IMSTM.ROPT.SRC,DISP=SHR
//SYSPRINT DD DISP=SHR,DSN=IMS610S.LISTING(COBIMS1)
//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),
// UNIT=VIO,SPACE=(80,(500,200))
//SYSUT1 DD UNIT=VIO,SPACE=(460,(350,100))
//SYSIN DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. COBIMS1
* COBOL370
*REMARKS.
* CALLS IAP26A & IAP26B MPP TO RECEIVE SINGLE SEGMENT MESSAGE
*
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 FILLER PIC X(16) VALUE '*** BEGIN WS ***'.
******************************************************************
* IMS DECLARATIONS
******************************************************************
77 GU-FUNC PIC X(4) VALUE 'GU '.

77 ROLL-FUNC PIC X(4) VALUE 'ROLL'.
77 DISPLAY-LL PIC 99999.
77 DISPLAY-ZZ PIC 99999.
01 INPUT-MESSAGE.
03 IN-LL PIC S9(4) COMP.
03 IN-ZZ PIC S9(4) COMP.
03 IN-TRANCODE PIC X(8).
03 IN-DATA.
04 IN-LINE1 PIC X(80).
04 FILLER PIC X(1024).
01 LPLM PIC S9(9) BINARY.
01 DLI-MSG.
02 DLIMSG-1 PIC X(18) VALUE 'ERROR ON DLI CALL '.
02 DLIMSG-CALL PIC X(10).
02 DLIMSG-2 PIC X(18) VALUE '. STATUS CODE WAS '.
02 DLIMSG-STAT PIC X(2).
02 DLIMSG-3 PIC X(22) VALUE ' '.
01 SUBNAME PIC X(12) VALUE ' '.
01 CNTR PIC S9(9) BINARY.
01 CNTC PIC S9(9) BINARY.
01 CNTV PIC S9(9) BINARY.
01 TEMP PIC 9999 COMP.
01 CEETEST-PARMS.
05 CMD-LENGTH PIC S9(4) COMP VALUE 80.
05 CMD-LIST PIC X(80) VALUE SPACES.
01 FC.
05 SEV PIC S9(4) USAGE IS BINARY.
05 MSGNO PIC S9(4) USAGE IS BINARY.
05 FLGS PIC X(1).
05 FACID PIC X(3).
05 ISI PIC X(4).
LINKAGE SECTION.
01 IOPCB.
02 IO-LTERM PIC X(8).
02 IO-RESV PIC X(2).
02 IO-STATUS PIC X(2).
02 IO-PREF PIC X(12).
02 IO-MODN PIC X(8).
02 IO-USERID PIC X(8).
02 IO-GROUPID PIC X(8).
PROCEDURE DIVISION.
*********************************************************
* CALL CEETEST IF NOT COMPILED WITH TEST OPTION BUT STILL
* WANT TO INVOKE THE DEBUGGER
* MOVE SPACES TO CMD-LIST.
* MOVE ";" TO CMD-LIST.
* CALL "CEETEST" USING CEETEST-PARMS FC.
* DISPLAY "CEETEST-PARMS" CEETEST-PARMS.
* DISPLAY "FC " FC.
ENTRY 'DLITCBL' USING IOPCB.
COMPUTE LPLM = 40.
PERFORM VARYING CNTR FROM 1 BY 1 UNTIL CNTR > LPLM
MOVE "$$" TO IO-STATUS
COMPUTE CNTV = CNTR + 1000
COMPUTE CNTC = CNTR + 2000
MOVE "IAP26A" TO SUBNAME
CALL "IAP26A" USING CNTR BY CONTENT CNTC
BY VALUE CNTV BY REFERENCE IOPCB
DISPLAY "CANCEL " SUBNAME
DISPLAY "RETURNED CNTR: ", CNTR, " CNTC: ", CNTC,
" CNTV: ", CNTV
END-PERFORM.
* TEST(NONE): NO EXCEPTION SHOULD BE SHOWING. LEAVE CNTR UNCHANGE
* TEST(ERROR): DIVIDE BY ZERO EXCEPTION. LEAVE CNTR UNCHANGE
* TEST(ALL): CHANGE CNTR TO SOMETHING OTHER THAN 41 IN MONITOR,
* THREAD TERMINATING EXCEPTION
COMPUTE TEMP = LPLM + 1.
IF CNTR = TEMP
COMPUTE TEMP = CNTR / ( CNTR - LPLM - 1)
GOBACK
ELSE
STOP RUN.
/*
//**************************************************************
//* COMPILING IAP26A
//**************************************************************
//COBOL2 EXEC PGM=IGYCRCTL,
// PARM='TEST,NODYNAM,LIB,MAP,OBJECT,RES,APOST,XREF'
//STEPLIB DD DSN=IGY.V2R1M0.SIGYCOMP,DISP=SHR
//SYSLIB DD DSN=MQM.SCSQCOBC,DISP=SHR
//* DD DSN=USER.IMSTM.ROPT.SRC,DISP=SHR
//SYSPRINT DD DISP=SHR,DSN=IMS610S.LISTING(IPA26A)
//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),
// UNIT=VIO,SPACE=(80,(500,200))
//SYSIN DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. IAP26A

* COBOL370
*REMARKS.
* CALLED BY COBIMS1 TO CALL CBLDLIT
*
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 FILLER PIC X(16) VALUE '*** BEGIN WS ***'.
******************************************************************
* IMS DECLARATIONS
******************************************************************
77 GU-FUNC PIC X(4) VALUE 'GU '.

77 ROLL-FUNC PIC X(4) VALUE 'ROLL'.
77 DISPLAY-LL PIC 99999.
77 DISPLAY-ZZ PIC 99999.
01 INPUT-MESSAGE.
03 IN-LL PIC S9(4) COMP.
03 IN-ZZ PIC S9(4) COMP.
03 IN-TRANCODE PIC X(8).
03 IN-DATA.
04 IN-LINE1 PIC X(80).
04 FILLER PIC X(1024).
01 DLI-MSG.
02 DLIMSG-1 PIC X(18) VALUE 'ERROR ON DLI CALL '.
02 DLIMSG-CALL PIC X(10).
02 DLIMSG-2 PIC X(18) VALUE '. STATUS CODE WAS '.
02 DLIMSG-STAT PIC X(2).
02 DLIMSG-3 PIC X(22) VALUE ' '.
01 CEETEST-PARMS.
05 CMD-LENGTH PIC S9(4) COMP VALUE 80.
05 CMD-LIST PIC X(80) VALUE SPACES.
01 FC.
05 SEV PIC S9(4) USAGE IS BINARY.
05 MSGNO PIC S9(4) USAGE IS BINARY.
05 FLGS PIC X(1).
05 FACID PIC X(3).
05 ISI PIC X(4).
LINKAGE SECTION.
01 RCNT PIC S9(9) USAGE IS BINARY.
01 VCNT PIC S9(9) USAGE IS BINARY.
01 CCNT PIC S9(9) USAGE IS BINARY.
01 IOPCB.
02 IO-LTERM PIC X(8).
02 IO-RESV PIC X(2).
02 IO-STATUS PIC X(2).
02 IO-PREF PIC X(12).
02 IO-MODN PIC X(8).
02 IO-USERID PIC X(8).
02 IO-GROUPID PIC X(8).
PROCEDURE DIVISION USING RCNT, CCNT,
BY VALUE VCNT,
BY REFERENCE IOPCB.
DISPLAY "***** ENTER IAP26A *****".
DISPLAY "RCNT BY REFERENCE: ", RCNT, " BY CONTENT: ", CCNT.
DISPLAY "VCNT BY VALUE : ", VCNT.
* ENTRY 'DLITCBL' USING IOPCB.
****************************************************************
* GET IMS MESSAGES FROM INPUT QUEUE AND PROCESS
****************************************************************
GET-IMS-MSG.
COMPUTE VCNT = VCNT + 100.
CALL 'CBLTDLI' USING GU-FUNC, IOPCB,
INPUT-MESSAGE.
COMPUTE CCNT = CCNT - 100.
GOBACK.
****************************************************************
* ERROR ROUTINE TO CATER FOR UNEXPECTED DL1 STATUS CODES
****************************************************************
D-RETURN-CODE.
DISPLAY DLI-MSG.
GOBACK.
/*
//*************
//* LINK COBIMS1, IAP26A TO IMSTM1
//*************
//LKED EXEC PGM=IEWL,COND=(8,LE,COBOL2),
// PARM='LIST,XREF,LET,RENT,MAP'
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=CEE.SCEELKED,DISP=SHR
//* DD DSN=IMSTESTL.TNUC1,DISP=SHR
//* CHANGE BELOW
//RESLIB DD DSN=IMS610S.RESLIB,DISP=SHR
//* CHANGE BELOW
//SYSLMOD DD DSN=IMS610S.PGMLIB,DISP=SHR
//SYSUT1 DD UNIT=VIO,DCB=BLKSIZE=1024,
// SPACE=(1024,(200,20))
//SYSLIN DD DSN=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN

//SYSIN DD *
INCLUDE RESLIB(DFSLI000)
ENTRY DLITCBL
NAME IAPMDI26(R)
/*
With CEEUOPT
Only the link step is different when you use the CEEUOPT, because you have to
link this module to your application program.
//UOPT DD DSN=KARLB.VA.LOAD,DISP=SHR
// SPACE=(1024,(200,20))
// DD DDNAME=SYSIN
//SYSIN DD *
ENTRY DLITCBL
NAME IAPMDI26(R)
/*
With CEEUOPT
Only the link step is different when you use the CEEUOPT, because you have to
link this module to your application program.
//UOPT DD DSN=KARLB.LOADLIB,DISP=SHR
// SPACE=(1024,(200,20))
// DD DDNAME=SYSIN
//SYSIN DD *
ENTRY DLITCBL
NAME IAPMDI26(R)
/*
CEEROPT module
This is a sample job to create a CEEROPT module. Refer to 9.7.1, “Using
CEEROPT” on page 112 for more information about the use of a CEEROPT
module.
//CEEWROPT JOB 1,'5645-001',MSGLEVEL=(1,1)
//STEP1 EXEC PGM=ASMA90,PARM='DECK,NOOBJECT'
//SYSPUNCH DD DSN=&&TEMPOBJ(CEEROPT),DISP=(,PASS),UNIT=SYSDA,
// SPACE=(TRK,(1,1,1)),DCB=(BLKSIZE=3120,LRECL=80,DSORG=PO)
//SYSLIB DD DSN=CEE.SCEEMAC,DISP=SHR <<<<<<
// DD DSN=SYS1.MACLIB,DISP=SHR ++++++
//SYSIN DD *
CEEROPT CSECT
CEEROPT AMODE ANY
CEEROPT RMODE ANY
CEEXOPT ABPERC=((NONE),OVR), X
TEST=((ALL,*,PROMPT,VADTCPIP&&9.112.16.168:*),NONOVR)
END
/*
/*
//STEP2 EXEC PGM=IEWL,
// PARM='NCAL,RENT,LIST,XREF,LET,MAP,SIZE=(9999K,96K)'
//SYSLMOD DD DSN=IMS610S.PGMLIB,DISP=SHR §§§§§§
//SYSLIB DD DSN=&&TEMPOBJ,DISP=(OLD,PASS)
//SYSLIN DD *
INCLUDE SYSLIB(CEEROPT)
ENTRY CEEROPT
ORDER CEEROPT
NAME CEEROPT(R)
/*

CEEUOPT module
This is a sample job to create a CEEUOPT module. Refer to 9.7.2, “Using
CEEUOPT” on page 113 for more information about the use of a CEEUOPT
module.
//CEEWUOPT JOB 1,'5645-001',MSGLEVEL=(1,1)
//STEP1 EXEC PGM=ASMA90,PARM='DECK,NOOBJECT'
//SYSPUNCH DD DSN=&&TEMPOBJ(CEEUOPT),DISP=(,PASS),UNIT=SYSDA,
// SPACE=(TRK,(1,1,1)),DCB=(BLKSIZE=3120,LRECL=80,DSORG=PO)
//SYSLIB DD DSN=CEE.SCEEMAC,DISP=SHR <<<<<<
// DD DSN=SYS1.MACLIB,DISP=SHR ++++++
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
CEEXOPT TEST=(,,,"VADTCPIP&&9.112.16.168:*")
END
/*
//STEP2 EXEC PGM=IEWL,
// PARM='NCAL,RENT,LIST,XREF,LET,MAP,SIZE=(9999K,96K)'
//SYSLMOD DD DISP=OLD,DSN=KARLB.LOADLIB
//SYSLIB DD DSN=&&TEMPOBJ,DISP=(OLD,PASS)
//SYSLIN DD *
INCLUDE SYSLIB(CEEUOPT)
ENTRY CEEUOPT
ORDER CEEUOPT
NAME CEEUOPT(R)
/*
//* ========> END OF JOB CEEWUOPT <========
//
Debug a batch program

This is a sample job to execute a batch program in debug mode using the
Distributed Debugger of VisualAge COBOL. Refer to 9.10.1, “DB2 batch
program” on page 117 for more information about debugging a batch program.
//CONZETTT JOB (999,POK),NOTIFY=CONZETT,
//*
//STEP10 EXEC PGM=IEFBR14
//PAAU90I DD DSN=CONZETT.RESTART.TRANSED4,DISP=(MOD,DELETE,DELETE),
// SPACE=(TRK,(1,0))
//PAAUES DD DSN=CONZETT.RESTART.ERRSRCH1,DISP=(MOD,DELETE,DELETE),
// SPACE=(TRK,(1,0))
//STEP20 EXEC PGM=PAPA111,
// REGION=32000K,PARM=('/TEST(,,,VADTCPIP&9.112.26.139:*)')
//STEPLIB DD DSNAME=CEE.SCEERUN,DISP=SHR
// DD DSNAME=EQAW.V1R2M0.SEQAMOD,DISP=SHR
//SYSDBOUT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSTCPD DD DISP=SHR,DSN=TCPIP.TCPPARMS(TCPDATA)
//PAAU90 DD DSN=CONZETT.RESTART.TRAN9002,DISP=OLD
//PAFJEZPA DD DSN=CONZETT.EASYPAY.MASTER,DISP=SHR
//PAFJCAPP DD DSN=CONZETT.CAP.D8530,DISP=SHR
//TRNPRT DD DUMMY,DCB=BLKSIZE=133
//PAAU90I DD DSN=CONZETT.RESTART.TRANSED4,DISP=(,CATLG,DELETE),
// UNIT=SYSDA,
// DCB=(RECFM=FB,LRECL=90,BLKSIZE=27990),
// SPACE=(CYL,(5,5),RLSE)
//PAAUES DD DSN=CONZETT.RESTART.ERRSRCH1,DISP=(,CATLG,DELETE),
// UNIT=SYSDA,
// DCB=(RECFM=FB,LRECL=25,BLKSIZE=27975),
// SPACE=(CYL,(2,1),RLSE)
//*
Debug a DB2 batch program

This is a sample job to execute a DB2 batch program in debug mode using the
Distributed Debugger of VisualAge COBOL. Refer to 9.10.1, “DB2 batch
program” on page 117 for more information about debugging a DB2 batch
program.
//DBA005R JOB (999,DAL),NOTIFY=DBA005,
// CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),TIME=1440
//JOBLIB DD DSN=DB2.V7R1M0.DSNA.SDSNEXIT,DISP=SHR
// DD DSN=DB2.V7R1M0.SDSNLOAD,DISP=SHR
// DD DSN=EQAW.SEQAMOD,DISP=SHR
// DD DSN=DBA005.AJC.LOAD,DISP=SHR
//*
//* STEP 1: RUN PROGRAM
//DB2SPCL EXEC PGM=IKJEFT01,DYNAMNBR=20,COND=(4,LT)
//DBRMLIB DD DSN=DBA005.AJC.DBRMLIB,DISP=SHR

//SYSTSPRT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSTCPD DD DISP=SHR,DSN=CENTER.PARMLIB(TCPDATA)
//SYSTSIN DD *
DSN SYSTEM(DSNA)
RUN PROGRAM(CSCALLAC) PLAN(CSCALLAC)-
LIB('DBA005.AJC.LOAD')-
PARMS('/TEST(,,,VADTCPIP&9.112.27.246:*)')
END
/*
DB2 WLM startup procedure

This is a sample JCL for the workload manager (WLM) startup procedure if DB2
Stored Procedures running under this WLM have to be debugged using the
Distributed Debugger of VisualAge COBOL. Refer to 9.10.2, “DB2 Stored
Procedures” on page 118 for more information about debugging a DB2 Stored
Procedure.
//DSNAWLMP PROC DB2SSN=DSNA,NUMTCB=1,APPLENV=DSNAWLMP
//*
//DSN710 EXEC PGM=DSNX9WLM,TIME=1440,
// PARM='&DB2SSN,&NUMTCB,&APPLENV',
// REGION=0M
//STEPLIB DD DISP=SHR,DSN=DB2.V7R1M0.DSNA.RUNLIB.LOAD
// DD DISP=SHR,DSN=DB2.V7R1M0.SDSNLOAD
// DD DISP=SHR,DSN=CBC.SCBCCMP
// DD DISP=SHR,DSN=CEE.SCEERUN
// DD DISP=SHR,DSN=EQAW.SEQAMOD
//SYSEXEC DD DISP=SHR,DSN=DB2.V7R1M0.DSNA.SDSNCLST
//SYSTSPRT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSABEND DD DUMMY
//DSNTRACE DD SYSOUT=*
//SYSTCPD DD DISP=SHR,DSN=CENTER.PARMLIB(TCPDATA)
//**** Data sets required by the SQL Procedures Processor
//SQLDBRM DD DISP=SHR, <== DBRM Library
// DSN=DB2.V7R1M0.DSNA.DBRMLIB.DATA
//SQLCSRC DD DISP=SHR, <== Generated C Source
// DSN=DB2.V7R1M0.DSNA.SRCLIB.DATA
//SQLLMOD DD DISP=SHR, <== Application Loadlib
// DSN=DB2.V7R1M0.DSNA.RUNLIB.LOAD
//SQLLIBC DD DISP=SHR, <== C header files
// DSN=CEE.SCEEH.H
// DD DISP=SHR,
// DSN=CEE.SCEEH.SYS.H
//SQLLIBL DD DISP=SHR, <== Linkedit includes
// DSN=CEE.SCEELKED
// DD DISP=SHR,
// DSN=DB2.V7R1M0.SDSNLOAD
//SYSMSGS DD DISP=SHR, <== Prelinker msg file
// DSN=CEE.SCEEMSGP(EDCPMSGE)
//*
//**** Workfiles required by the SQL Procedures Processor
//SQLSRC DD UNIT=SYSDA,SPACE=(16000,(20,20)),
// DCB=(RECFM=FB,LRECL=80)
//SQLPRINT DD UNIT=SYSDA,SPACE=(16000,(20,20)),
// DCB=(RECFM=VB,LRECL=137)
//SQLTERM DD UNIT=SYSDA,SPACE=(16000,(20,20)),
//SQLOUT DD UNIT=SYSDA,SPACE=(16000,(20,20)),
//SQLCPRT DD UNIT=SYSDA,SPACE=(16000,(20,20)),
//SQLUT1 DD UNIT=SYSDA,SPACE=(16000,(20,20)),
//SQLUT2 DD UNIT=SYSDA,SPACE=(16000,(20,20)),
//SQLCIN DD UNIT=SYSDA,SPACE=(32000,(20,20))
//SQLLIN DD UNIT=SYSDA,SPACE=(8000,(30,30)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=400)
//SQLDUMMY DD DUMMY
//SYSMOD DD UNIT=SYSDA,SPACE=(16000,(20,20)),

B
Appendix B. The Debug Tool and TCP/IP

in CICS
In order to enable debugging of a CICS application using the IBM Debug Tool in
conjunction with the VisualAge COBOL Distributed Debugger, you have to
customize CICS for the Debug Tool and TCP/IP for the communication with the
Distributed Debugger.
This appendix describes the following topics:

򐂰 Customizing CICS for the Debug Tool
򐂰 Customizing CICS for TCP/IP

Customizing for the Debug Tool
The Debug Tool consists of two partitioned data sets:
򐂰 SEQAMOD data set (for example EQAW.V1R2M0.SEQAMOD), which
contains the Debug Tool load modules
򐂰 SEQASAMP data set (for example EQAW.V1R2M0.SEQASAMP), which
contains the samples for the Debug Tool.
To use TCP/IP sessions to carry the communications for remote debugging of

your CICS applications, take the following actions or have a systems
administrator doing it for you:
򐂰 Update the CICS system definition.
򐂰 Update the CICS startup job.
򐂰 Update the CICS authorized library.
Updating the CICS system definition (CSD) for Debug Tool

Merge the supplied Debug Tool definitions into your existing job for maintaining
the CSD. The statements for defining Debug Tool to CICS are in the member
EQACCSD, which is in the SEQASAMP library.
Here is a sample job to perform the CSD updates:

//EQAWCCSD JOB (999,POK),NOTIFY=KARLB,
//STEP1 EXEC PGM=DFHCSDUP,REGION=2M,PARM='CSD(READWRITE),COMPAT'
//STEPLIB DD DSN=CICSTS13.CICS.SDFHLOAD,DISP=SHR
//DFHCSD DD DSN=CICSSYSF.CICSCOB1.DFHCSD,DISP=SHR
//SYSIN DD DISP=SHR,DSN=EQAW.V1R2M0.SEQASAMP(EQACCSD)
The EQACCSD member of SEQASAMP also includes the Transient Data Queue
definitions for Transaction Server CICS for ESA V5.1 and later. If you have a
Transaction Server you must also uncomment the Transient Data Queue part of
member EQACCSD.
If your CICS is older than Transaction Server (CICS V5.1), for example CICS
V4.1, you must leave the Transient Data Queue definitions in EQACCSD in
comment when you submit this job and run also the EQACDCT sample from
SEQASAMP.
Merge the EQACDCT member into your existing job for maintaining the DCT.
Remember, you need this step only in CICS V4.1 and below.
Updating the CICS startup job
Make sure that all of the Debug Tool modules that are defined in EQACCSD are
in libraries that CICS can access. You can make the libraries accessible to CICS
by including them in the DFHRPL concatenation in the CICS startup job.
Here is an example of the DFHRPL DD in a CICS startup job:

//DFHRPL DD DSN=&INDEX1..SDFHLOAD,DISP=SHR
// DD DISP=SHR,DSN=CEE.SCEECICS
// DD DISP=SHR,DSN=CEE.SCEERUN
// DD DISP=SHR,DSN=EQAW.V1R2M0.SEQAMOD
// DD DISP=SHR,DSN=TCPIP.SEZATCP
Make sure that the following libraries are in your DFHRPL:

CEE.SCEECICS The Language Environment CICS library
CEE.SCEERUN The Language Environment runtime library
EQAW.V1R2M0.SEQAMOD The Debug Tool runtime library
TCPIP.SEZATCPIP The TCPIP library, see “Installing and customizing
TCP/IP sockets in CICS” on page 154.
For a complete sample of a CICS startup job refer to the CICS documentation.
Now you can install the EQA group, for example using the following CICS
transaction:
CEDA INSTALL GROUP(EQA) LIST(KBLIST)
Updating the CICS authorized library

Copy the SEQAMOD member EQA00DYN to one of the authorized libraries that
CICS can access.
You can also create a new library, for example VACOBOL.SEQADYN, APF
authorize it, copy EQA00DYN into it and put it in the STEPLIB DD concatenation
of your CICS startup job, as in the following example:
//STEPLIB DD DSN=&INDEX1..SDFHAUTH,DISP=SHR
// DD DSN=CICSTS13.CPSM.SEYUAUTH,DISP=SHR
// DD DSN=TCPIP.SEZALINK,DISP=SHR
// DD DISP=SHR,DSN=VACOBOL.SEQADYN
Appendix B. The Debug Tool and TCP/IP in CICS 153

Installing and customizing TCP/IP sockets in CICS
Unless you already activated TCP/IP in the CICS region you must now activate it
including setting up, configuring and starting CICS TCP/IP. So if it is already done
you can skip this chapter, but if not, here are the steps how to do it:
1. Add the library TCPIP.SEZALINK to the STEPLIB DD concatenation of your
CICS startup job.
2. Add the library TCPIP.SEZATCP to the DFHRPL DD concatenation of your
CICS startup job.
3. Make sure you code the DFHSIT override TCPIP=YES.
4. You can define all the necessary resources by running an RDO job as in this
example:
//KARLBCSD JOB (999,POK),NOTIFY=KARLB,
//STEP1 EXEC PGM=DFHCSDUP,REGION=2M,PARM='CSD(READWRITE),COMPAT'
//STEPLIB DD DSN=CICSTS13.CICS.SDFHLOAD,DISP=SHR
//DFHCSD DD DSN=CICSSYSF.CICSCOB1.DFHCSD,DISP=SHR
//SYSIN DD DISP=SHR,DSN=TCPIP.SEZAINST(EZACICCT)
The EZACICCT member of the TCPIP.SEZAINST library should contain all
the necessary definitions for the TCP/IP modules and files.
5. Now you must configure the CICS TCP/IP environment. This is done by
running the following job for example:
//KARLBVS JOB (999,POK),NOTIFY=KARLB,
//* THIS JOB DELETES AND RECREATES A TCPIP CONFIGURATION
//* DATA SET
//*
//DELETE EXEC PGM=IDCAMS,REGION=1M
//SYSIN DD *
DELETE VACOBOL.CICS.TCP.CONFIG
SET MAXCC=0
/*
//DEFINE EXEC PGM=IDCAMS,REGION=1M
//SYSIN DD *
DEFINE CLUSTER(NAME(VACOBOL.CICS.TCP.CONFIG)-
VOLUME(TOTCI3) REUSE -
CYL(1 1)-
IMBED -
RECORDSIZE(150 150)-
FREESPACE(0 15)-
INDEXED)-
DATA(NAME(VACOBOL.CICS.TCP.CONFIG.DATA)-
KEYS(16 0)) -
INDEX(NAME(VACOBOL.CICS.TCP.CONFIG.INDEX))
/*
//ASM1 EXEC PGM=ASMA90,REGION=1024K,
// PARM='OBJECT,TERM'
// DD DSN=TCPIP.SEZACMAC,DISP=SHR
//SYSTERM DD SYSOUT=*
//SYSPUNCH DD DISP=SHR,DSNAME=NULLFILE
//SYSLIN DD DSNAME=&&OBJECT,DISP=(MOD,PASS),UNIT=SYSALLDA,
// SPACE=(400,(500,50)),
// DCB=(RECFM=FB,BLKSIZE=400,LRECL=80)
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(5,1))
//SYSIN DD *
EZACICD TYPE=INITIAL, X
PRGNAME=EZACICDF, X
FILNAME=EZACONFG
EZACICD TYPE=CICS, X
APPLID=SCSCCOB1, X
TCPADDR=TCPIPMVS, X
NTASKS=20, X
DPRTY=10, X
CACHMIN=10, X
CACHMAX=20, X
CACHRES=5, X
ERRORTD=CSKN
EZACICD TYPE=LISTENER, X
TRANID=CSKL, X
PORT=3000, X
BACKLOG=40, X
ACCTIME=30, X
GIVTIME=10, X
REATIME=300, X
NUMSOCK=100, X
MINMSGL=4, X
APPLID=SCSCCOB1
EZACICD TYPE=FINAL
/*
//LINK EXEC PGM=HEWL,REGION=500K,
// PARM='XREF,LIST,MAP',COND=(4,LT)
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(5,1)),DISP=(NEW,PASS)
//SYSLMOD DD DISP=SHR,DSNAME=KARLB.LOADLIB(TCPTEMP)
//SYSLIN DD DSNAME=&&OBJECT,DISP=(OLD,DELETE)
Appendix B. The Debug Tool and TCP/IP in CICS 155

//*
//FILELOAD EXEC PGM=TCPTEMP
//STEPLIB DD DISP=SHR,DSN=KARLB.LOADLIB
//EZACONFG DD DSNAME=VACOBOL.CICS.TCP.CONFIG,DISP=OLD
//*
//*
/*
6. After this you should install the group SOCKETS, which has been created by
the EZACICCT job (see 4 on page 154). You can use the following CICS
transaction as an example:
CEDA INSTALL GROUP(SOCKETS) LIST(KBLIST)
7. Now you should be able to start TCP/IP in your CICS region. Enter the
following CICS transaction:
EZAO,START,CICS
Abbreviations and acronyms
APF authorized program facility MFI MainFrame Interface
APPC advanced MPP message processing
program-to-program program
communication MVS multiple virtual storage
BMS basic mapping support NFS Network File System
BTS batch terminal simulator PTF program temporary fix
CICS Customer Information Control RDO resource definition on-line
System
SP Stored Procedure
COBOL common business oriented
language SPM Stored Procedure Manager
CSD CICS system definition TCP/IP Transmission Control
Protocol/Internet Protocol
DB data base
TM transaction monitor
DC data communication
TSO time sharing option
DSA dynamic storage area
USS UNIX System Service,
ECI external call interface formerly Open Edition
FFS Foreign File System WLM WorkLoad Manager
FTP file transfer protocol Environment
GPR general purpose register XML eXtensible Markup Language
GUI graphical user interface
HTTP Hypertext Transfer Protocol
IBM International Business
Machines Corporation
IEEE Institute of Electrical and
Electronics Engineers
IMS information management
system
ITSO International Technical
Support Organization
JCL Job Control Language
JDK Java Development Kit
JES Job Entry Subsystem
JRE Java Runtime Environment
LE Language Environment
LRR library routine retention

Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 159.
򐂰 Client/Server Implementation Using TXSeries, UDB, and VisualAge COBOL
on Windows NT, SG24-5359
Other resources
These publications are also relevant as further information sources:
򐂰 VisualAge COBOL for Windows NT: Getting Started, GC27-0811
򐂰 VisualAge COBOL for Windows NT: Remote Edit-Compile-Debug User’s
Guide, SC27-0810
򐂰 VisualAge COBOL Programming Guide, SC27-0812
򐂰 Debug Tool User’s Guide and Reference, SC09-2137
Referenced Web sites

This Web site is also relevant as a further information source:
򐂰 http://www-4.ibm.com/software/ad/cobol/cobfs500.htm
VisualAge COBOL home page
How to get IBM Redbooks

You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM

images) from that site.

IBM Redbooks collections
Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
Index
SEPARATE 105
A SYM 105
abend 132
TEST 104
adata file 46
connection definition 21
ALTER PROCEDURE 118
Connections Manager 23
APPC transaction 20
connectivity 18, 68
application exception 132
context sensitive 55, 73
copybooks 47
B core services 92, 97
batch program 115 CREATE PROCEDURE 118
BMS Editor 64
breakpoints 126
BTS 111
D
Data Assistant 74
data set filter definition 28
C data set qualifier 28
CEELRRIN 112 data transfer definitions 25
CEEROPT 112 DB2 program 117
CEEUOPT 113 DB2 Stored Procedure 118
CICS workload manager 119
authorized library 153 debug
customize for Debug Tool 152 batch program 115
customize for TCP/IP 154 breakpoints 126
startup job 153 change variable value 129
system definition 152 CICS program 106
CICS map 64 display ID 107
code page DTCN 107
host 26 program 109
local 26 terminal 108
translation 26 transaction 108
compilation unit 127 user ID 110
compile 77 Daemon 103
error feedback 81 DB2 program 117
local 80 batch 117
mainframe 83 Stored Procedure 118
messages 82 exception 132
overview 10 exception filters 122
remote 83 IMS program 111
compiler options 78 CEEROPT 112
ADATA 80 CEEUOPT 113
ANALYZE 80 listener 103
compile only 80 locals 129
copy file search path 80 modules 127
LIB 80 monitors 128

overview 14 extension 29
preferences 120 EZAO transaction 156
prepare program 104
CICS 105
IMS 106
F
file compare 75
process 101
file details 59
production 104
file filter 54
profiles 122
file handling 69
registers 130
file mapping definition 29
setup 101
file name extension 29
sidefile option 104
file scope action 63
source listing 124
Foreign File System 68
stacks 126
storage 129
supported languages 100 G
TSO foreground program 116 graphical user interface 100
user interface 119
control pane 125
hover help 121
H
host offloading 3
menu options 120 host offloading with remote data access 5
source pane 124 hover help 53
value pane 128 HTTP Server 20
variables 128
workstation setup 102
Debug Tool 100 I
development scenarios 2 IBM Debug Tool 100
display ID 107 installation 18
Distributed Debugger 100
Distributed Debugger Daemon 103 J
drive letter 26 JDK 97
DTCN transaction 107 Job Monitor 86
job filter 90
E manage spool 90
edit 67 view output 91
compare 75 job number 87
filter 71 JRE 97
macros 70
Navigator 72 L
overview 8 Language Environment services 4
profiles 73 LE services 4
ring manager 71 library routine retention 112
SQL code generator 74 link 83
views 70 listener 102
entry point 127 listing file 46
environment variables 47, 62 local compile 80
SYSLIB 48, 62 LPEX editor 70
EQADCCXT 105 LPEX Navigator 72
exception 132
M REXX procedure 92
MainFrame Interface 107
map 64
mapping definitions 30
S
sample JCL
member details 59 compile batch program 136
MFI 107 compile CICS program 137
multiple debug sessions 116 compile IMS online program 138
MVS connections 22 CEEROPT 139
MVS Connections Manager 23 CEEUOPT 144
create CEEROPT module 145
N create CEEUOPT module 146
Navigator 72 DB2 WLM startup procedure 148
NFS 7, 68 debug batch program 146
debug DB2 batch program 147
IMS online program
O CEEUOPT 144
object file 46
sidefile option 136
offloading 3
save mainframe resources 86
scenarios 2
P host offloading 3
password 25, 87, 93 host offloading with remote data access 5
port remote development 6
definitions 27 settings
job 27 columns 63
Web 27 directories 61
production debugging 104 environment variables 62
program abend 132 project name 63
program monitor 128 sort 63
project sidefile option 104
browse 36 source level debugger 104
create new 37 source listing 104, 124
definition 33 SQL code generator 74
files 40 Stored Procedure 118
GUI 34 Stored Procedures Manager 64
MVS 34 submit job 87
name 39 from editor 90
non-GUI 34 job id message 87
open 35 local JCL 89
project scope action 63 overview 12
project wizard 34 return code 87
select system 88
symbolic debug information 104
R syntax checking 10, 80
Redbooks Web site 159
SYSDEBUG 105
Contact us xvii
SYSLIB 47, 62
remote data 5
SYSOUT 91
Remote Debugger 100
SYSPRINT 104
remote development 6
SYSTCPD 106, 112, 115, 117–119
remote edit/compile/debug 6
Index 163
system directories 45
T
TCP/IP sockets 106, 154
tools setup 64
TSO commands 92
command history 93
command output 93
core services 92
overview 13
parameter 93
user interface 92
WorkFrame action 94
TSO foreground program 116
TSO password 25, 87, 93
U
user directories 41
V
value pane 128
variables 128
view
details 59
icon 58
tree 57
W
WLM 119
WorkFrame 51
actions 63
create 64, 94
file types 66
REXX 95
define project 34
filter 54
menu 53
monitor and command window 57
project container 55
settings 60
toolbar 52
views 57
working directory 45, 61
workload manager 119
X
XML 130
IBM VisualAge COBOL Remote Edit/Compile/Debug: Taking COBOL to the Next Level!
(0.2”spine)
0.17”<->0.473”
90<->249 pages
Back cover ®
IBM VisualAge COBOL

Remote Edit/Compile/Debug
Have fun when This IBM Redbook details the configuration and use of some
developing and of the features of IBM VisualAge COBOL Version 3.
INTERNATIONAL
maintaining COBOL TECHNICAL
programs The mainframe application programmer can now use SUPPORT
VisualAge COBOL to edit, compile, and debug an MVS ORGANIZATION
application without even logging on to TSO. Although the
Exploit the
programmer is working in a workstation environment, the
advantages of the
source code remains on the mainframe, and the program is
mainframe and the running in its target environment for debugging. BUILDING TECHNICAL
workstation INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM VisualAge COBOL provides a state-of-the-art graphical
Enhance the COBOL user interface for all the tasks involved in the development
programmer and maintenance of mainframe applications, including batch, IBM Redbooks are developed by
productivity DB2, CICS, and IMS applications. Additionally, using a modern the IBM International Technical
development environment to maintain and develop mission Support Organization. Experts
from IBM, Customers and
critical batch and server applications will help your company
Partners from around the world
retain skilled COBOL developers while attracting talented new create timely technical
programmers who are familiar with similar tools used in Java. information based on realistic
scenarios. Specific
This book introduces the reader to various development recommendations are provided
to help you implement IT
scenarios, showing how the Remote Edit/Compile/Debug
solutions more effectively in
model can help to increase the productivity of an application your environment.
developer. Although written for VisualAge COBOL, this book
can also be easily used as a reference for VisualAge PL/I.
For more information:

ibm.com/redbooks
SG24-6111-00 ISBN 0738417939

SG 246111

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SG 246111

Uploaded by

Copyright:

Available Formats

Front cover

IBM VisualAge COBOL

Have fun while developing and

Exploit the advantages of

Enhance your COBOL

IBM VisualAge COBOL

First Edition (February 2002)

Comments may be addressed to:

© Copyright International Business Machines Corporation 2002. All rights reserved.

Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

IBM trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Chapter 1. Executive overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Component connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3. System connection definitions . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 4. Project definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... .. 33

© Copyright IBM Corp. 2002 iii

Chapter 8. Job Monitor and TSO Commands server . . . . . . . . . . . . . . . . . 85

Appendix A. Sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Appendix B. The Debug Tool and TCP/IP in CICS . . . . . . . . . . . . . . . . . . 151

Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 159

1-1 VisualAge COBOL WorkFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

© Copyright IBM Corp. 2002 vii

7-1 Compiler options of interest for MVS projects . . . . . . . . . . . . . . . . . . . . 80

© Copyright IBM Corp. 2002 xi

References in this publication to IBM products, programs or services do not imply

Such information may be available, subject to appropriate terms and conditions,

© Copyright IBM Corp. 2002 xiii

The following terms are trademarks of the International Business Machines

Other company trademarks

PC Direct is a trademark of Ziff Communications Company in the United States and/or

ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel

© Copyright IBM Corp. 2002 xv

Andrea Conzett was an Advisory Information Technology Specialist at the

Karl Bender is an Advisory IT Specialist in IBM Germany. He has 13 years of

Scott Davis is with IBM Technical Sales in Germany. He has 17 years of

Henk van der Wijk is a consultant at Delion in The Netherlands. He has 16

Thanks to the following people for their contributions to this project:

We want our Redbooks to be as helpful as possible. Send us your comments

Chapter 1. Executive overview

© Copyright IBM Corp. 2002 1

Note: The availability of individual tools or technologies may vary because

Figure 1-1 VisualAge COBOL WorkFrame

1.2.1 Scenario 1: host offloading

Chapter 1. Executive overview 3

This scenario is reached by transferring the necessary source files, copybooks,

Each development shop must decide for themselves whether having an

Horror stories of preprocessor compile errors on the execution platform after a

Chapter 1. Executive overview 5

In addition to the shortcomings of the host offloading scenario, mentioned earlier,

Figure 1-2 MVS Connections Manager

The foundation of this connection is an IBM-developed Foreign File System

Chapter 1. Executive overview 7

Figure 1-3 Parsing editor

Chapter 1. Executive overview 9

Submit Hold Edit

Figure 1-4 Development cycle

Chapter 1. Executive overview 11

Remote compile — job submission

Figure 1-6 Job Monitor window

Figure 1-7 TSO Commands window

Chapter 1. Executive overview 13