IBM Developer for z/OS

IBM Developer for z/OS Enterprise Edition

16.0

Welcome and Getting Started

Last updated 2024-10-16

IBM
About this PDF
© International Business Machines Corporation 1992, 2024.

This PDF was generated from the content of the IBM® Developer for z/OS® online documentation. It is
provided for reference only. Many of the links in this PDF do not lead to a target location on the IBM
Developer for z/OS IBM Documentation site. For the most recent content, go to https://www.ibm.com/
docs/en/developer-for-zos/latest.
Some of the content in the IBM Developer for z/OS IBM Documentation site is embedded from other
IBM product documentation sites. Because of this content reuse, the embedded content might not be
included in the generated PDFs.
Welcome to IBM Developer for z/OS
IBM Developer for z/OS is a modern, robust tool set for developing and maintaining IBM z/OS applications
through the use of DevOps practices. It helps you deliver more, faster, and with better quality and greater
agility.
IBM Developer for z/OS is available in two editions. For a detailed comparison of each product, see
Compare Editions on the product website. Unless specifically stated otherwise, this IBM Documentation
uses the product names IBM Developer for z/OS and Developer for z/OS to refer to both editions.
Developer for z/OS
Offers COBOL, PL/I, High Level Assembler, REXX, C/C++, JCL, and Java™ development tools on an
Eclipse base. Its modern Eclipse-based editors include a rich set of tools for creating, verifying, and
understanding code assets in z/OS, Git, and Jazz repositories. The Eclipse tooling also encompasses
debug, unit test, build, and deploy functions, as well as a software analysis tools that checks your
assets against software coding rules and reports quality metrics.
Developer for z/OS Enterprise Edition
Offers developers the option to choose Eclipse or Microsoft VS Code for their z/OS integrated
development environment. This edition adds IBM Dependency Based Build and Wazi Deploy. It is
available as a standalone product or as a component of Application Delivery Foundation for z/OS.

The product offers these benefits and features for modernizing your z/OS development and integrating
with DevOps practices:
• Modern, simple z/OS development
• Advanced debugging of composite z/OS applications
• Advanced application structure and quality analysis tools
• Automated unit testing and code coverage
• Source control, lifecycle management and problem diagnosis integration
• Customize and extend the development environment
• Licensing to suit your needs
• IBM Dependency Based Build (available in Enterprise Edition)

© Copyright IBM Corp. 1992, 2024 1

 • Expanded IDE choices including Microsoft VS Code (available in Enterprise Edition)
• Customization and automation of z/OS application deployment for test and production environments
in a continuous integration/continuous delivery (CI/CD) pipeline with IBM Wazi Deploy (available in
Enterprise Edition)

Components and tools

For an overview of the components and tools available with Developer for z/OS and Developer for z/OS
Enterprise Edition, select a topic from this table.

Table 1. Developer for z/OS components and tools

Component Developer for z/OS Developer for z/OS Enterprise
Edition
Accessing and managing source code
Connecting to a z/OS system ✔ ✔
Eclipse EGit for integration with ✔ ✔
Git repositories
Accessing source files in ✔ ✔
an Engineering Workflow
Management (Jazz) repository
Accessing source files in the ✔ ✔
CA Endevor Software Change
Manager (SCM)

Table 1. Developer for z/OS components and tools

Application development environments
Developing with Eclipse ✔ ✔
Developing with IBM Developer ✔
for z/OS on VS Code

Table 1. Developer for z/OS components and tools

Runtime environments
Developing with Db2 for z/OS ✔ ✔
Developing CICS applications ✔ ✔
Developing IMS applications ✔ ✔
Developing web services and ✔ ✔
SOA with Enterprise Service
Tools

Table 1. Developer for z/OS components and tools

Debugging applications
IBM Debug for z/OS ✔

Table 1. Developer for z/OS components and tools

Building and deploying applications
IBM Dependency-Based Build ✔

2 Developer for z/OS: Welcome and Getting Started

 Table 1. Developer for z/OS components and tools (continued)
Building and deploying applications
IBM Engineering Workflow ✔ ✔
Management
Integrating IBM Z Systems ✔ ✔
Development and Test
Environment with Developer for
z/OS
Deploying to z/OS with IBM Wazi ✔
Deploy

Table 1. Developer for z/OS components and tools

Analyzing and measuring software quality
Code Review ✔ ✔
Gathering an reporting metrics ✔ ✔
for COBOL and PL/I programs
Determining code coverage ✔ ✔

Table 1. Developer for z/OS components and tools

Managing the development environment
Host-based projects ✔ ✔
Distributing updates by using ✔ ✔
push-to-client

Table 1. Developer for z/OS components and tools

Customizing and extending the development environment
Creating menu actions in Menu ✔ ✔
Manager
Common Access Repository ✔ ✔
Manager (CARMA)

What's New in this Release

What's new in IBM Developer for z/OS and Developer for z/OS Enterprise
Edition
Product Release Details
• Fix list for IBM Developer for z/OS and IBM Developer for z/OS Enterprise Edition
• IBM Developer for z/OS client-server compatibility
• Software Product Compatibility Reports
Related Products
What's new in IBM Explorer for z/OS Version 3.3
Enterprise Edition Components
• What's new in IBM z/OS Debugger
• What's new in IBM Dependency Based Build

Welcome to IBM Developer for z/OS 3

 • What's new in IBM Developer for z/OS on VS Code (formerly IBM Wazi for VS Code)
• What's new in IBM Wazi Deploy

Version 17.0.0
Db2 for z/OS Development
Db2 for z/OS Development tooling is enhanced to include these new functions:
• Deployment of external SQL stored procedures.
• Debugging native and external SQL stored procedures.
• Filtering catalog navigation results by any column type.
• Importing connection profiles from IBM Data Studio.
• Generating declarations (DCLGEN).
• A toolbar for common Db2 for z/OS actions.
• Autofill of prior parameter values when re-executing a query.
• Large object support.
• Consistent feedback from query execution when no rows are returned.
• Viewing multiple result sets returned from a query.
For information about these new functions, see Developing with Db2 for z/OS.
Dependency Based Build Integration
Adds support for IBM Dependency Based Build 3.0.0 to perform user builds with the new zBuilder
DBB framework. The zBuilder framework simplifies user build functionality by moving many of the
user prompts to configurations and defaults, thereby enhancing the user experience for mainframe
developers. To learn more about user builds with zBuilder, see Setting up and running a user build
with zBuilder.
Eclipse 4.31 and Java 17 Support
The product client is now built on Eclipse 4.31 with support for Java 17 and IBM Explorer for z/OS
Aqua 3.4. For the Eclipse documentation, see Eclipse documentation.
Editors
• The COBOL parser now supports function prototypes, with which you can define the function name,
parameters, and returning value of a user-defined function or other non-COBOL external functions
such as C functions and invoke these functions.
• The HLASM Editor now supports local custom macros in local property groups.
Remote Connection Emulator
The redesign of Remote Connection Emulator that was introduced in IBM Developer for z/OS 16.0.5 is
refined and enhanced with several usability improvements.
Deprecated and removed components
z/OS Automated Unit Testing Framework (ZUnit)
ZUnit is removed. The recommended replacement is IBM Test Accelerator for Z. For more
information about this new offering, see the IBM Test Accelerator for Z product website and IBM
Test Accelerator for Z documentation.
IBM Installation Manager
Support for client installation by using IBM Installation Manager is removed. The IBM Developer
for z/OS client can be installed by using the Eclipse p2 provisioning platform. For more information
about installing the Eclipse client, see Installing the IBM Developer for z/OS Eclipse client.
IBM Wazi for Dev Spaces
Wazi for Dev Spaces is removed from IBM Developer for z/OS Enterprise Edition.

4 Developer for z/OS: Welcome and Getting Started

 Prior versions
For a list of what's new in product versions prior to version 17.0.0, click these links:
• Version 16.0.x
• Version 15.0.x
• Version 14.2.x

Limitations in COBOL 6.4, PL/I 6.1, and CICS 6.1 support

COBOL 6.4
• The z Systems® LPEX Editor does not support highlighting of user defined function names. The COBOL
Editor does support highlighting.
• Program control flow diagrams do not display changes in program flow that are made by user defined
functions.
• Data flow diagrams do not display the flow of data to or from variables in user defined functions.
• The Perform Hierarchy view does not display changes made in program flow by user defined functions.
• The Data Elements view does not display variables defined in user defined functions.

PL/I 6.1
• No support is included for the MAXRUNONIF compiler option.

CICS 6.1
• The z Systems LPEX Editor, PL/I Editor, and COBOL Editor support only the standard CICS TS API and
SPI commands, which does not include variants such as the CICS external interfaces.
• The COBOL and PL/I parsers report errors for the following EXEC CICS statements and options. The
compilers process these statements and options without error.
– EXTRACT STATISTICS with the POLICY or POLICYRULES options
– INQUIRE POLICY, INQUIRE POLICYRULE, INQUIRE SECRECORDING, and INQUIRE TAG with the
START, NEXT, or END options.

Download documentation in PDF format

The IBM Developer for z/OS and IBM Developer for z/OS Enterprise Edition documentation is available in
PDF format. You can download these PDF files for offline use.
The documentation also includes a PDX package that you can download to search the documentation
across all PDF files. To download the PDX package, use the Download PDF link at the bottom of the table
of contents.

Welcome to IBM Developer for z/OS 5

 Tip: For the most up-to-date documentation, download PDFs whenever you access them, or establish
a routine for frequent downloads. The date that each PDF file was created is printed on the cover
of each PDF file. In most cases, PDF manuals are updated with the same frequency as the online
product documentation. The PDX package is not updated with the same frequency. The online IBM
Documentation site is the most up-to-date version of the documentation, followed by the individual PDF
files available from this page. The PDX package is the least up-to-date.
You can download the PDF format manuals for Developer for z/OS from the left column in the following
table. The right column shows where you can find the online version of the content from each PDF
manual. For PDF versions of some of the products that are included with IBM Developer for z/OS
Enterprise Edition, click these links:
• IBM Debug for z/OS PDF documentation

PDF format documentation Online HTML format documentation

Getting Started, Installation, Troubleshooting, and Reference
Welcome and Getting Started Welcome to IBM Developer for z/OS
Installing and Configuring Host Components Installing and configuring the host components
• IBM Explorer for z/OS Program Directory
• IBM z/OS Explorer Extensions Program Directory
• IBM z/OS Explorer Extensions Configuration
Guide
• IBM z/OS Explorer Extensions Configuration
Reference
• IBM z/OS Source Code Analysis Program
Directory
• IBM Remote System Explorer API Program
Directory
• IBM Dependency Based Build Program Directory
• Rocket GIT for z/OS Program Directory
• IBM Open Enterprise SDK for Python Program
Directory
• IBM Wazi Deploy Program Directory (PDF)
• IBM Wazi Deploy Configuration Guide

6 Developer for z/OS: Welcome and Getting Started

 PDF format documentation Online HTML format documentation
Getting Started, Installation, Troubleshooting, and Reference
Migrating to IBM Developer for z/OS enterprise Migrating to Developer for z/OS Enterprise Edition
Edition or Application Delivery Foundation for z/OS
Choosing and Installing a Client Choosing and installing a client
Troubleshooting and Support Troubleshooting and support
Reference Reference

Developing with Eclipse

Setting up an Eclipse Development Environment Setting up an Eclipse development environment
Loading Source Files Loading source files into the Developer for z/OS
workspace
Organizing source files with projects and
subprojects

Editing Source Files Editing source program files

Developing with Db2, CICS, and IMS Developing with Db2 for z/OS
Developing CICS applications
Developing IMS applications
Developing web services and SOA with
Enterprise Service Tools

Verifying, Analyzing, and Measuring Code Checking syntax and program dependencies
Source code analysis with code review
Gathering and reporting metrics for COBOL and
PL/I programs

Building Code Building your code

Determining code coverage Determining code coverage
Remote debugging with an Eclipse IDE Using z/OS Debugger
Managing and Extending the Eclipse Environment Managing the development environment for a
team
Extending product functions

Developing with Enterprise Edition IDEs and tools

Developing with IBM Developer for z/OS on VS
Code
Wazi Deploy Deploying to z/OS with IBM Wazi Deploy

Release notes
Description
IBM Developer for z/OS consists of a common workbench and an integrated set of tools that support
end-to-end, model-based development, runtime testing, and rapid deployment of simple and complex
applications. It offers an integrated development environment (IDE) with advanced, easy-to-use tools and

Welcome to IBM Developer for z/OS 7

 features to help WebSphere®, CICS, and IMS developers rapidly analyze, design, code, debug, and deploy
complex applications.
For more information on the enhancements and added function in this release of Developer for z/OS, see
What's new.
For more information about the Developer for z/OS family of products, see the IBM Developer for z/OS
website.

Accessibility features in Adobe Acrobat Reader

For information about the accessibility features in Adobe Acrobat Reader, see Adobe Acrobat Reader Help
and Accessibility features.
For information about setting the accessibility preferences, see Reading PDF files with reflow and
accessibility features.
For information about using the keyboard to navigate a PDF file in Adobe Acrobat Reader, go to the Adobe
Acrobat Reader help and see Keyboard shortcuts.

Announcement
The Developer for z/OS announcement is available at Announcement Letter.

System requirements
For a complete listing of the Developer for z/OS hardware and software requirements including
prerequisites and co-requisites, see the Detailed system requirements for a specific product page of
Software Product Compatibility Reports. On this page:

1. Type Developer for z/OS in the search field and click Search.
2. From the Version list, select the product version you want.

Prerequisites
IBM Developer for z/OS (Developer for z/OS) is a licensed program to support users who write large-scale
business applications.
Prerequisite software must be installed and operational before the product will work. Corequisite
software is required to support specific features of Developer for z/OS. These requisites must be installed
and operational at runtime for the corresponding features to work as designed.
For a complete listing of the Developer for z/OS software requirements including prerequisites and
co-requisites, see the Software Product Compatibility Reports.

Installing Developer for z/OS

For client installation information, see Installing the IBM Developer for z/OS Eclipse client.
For host installation and configuration information, see Installing and configuring the host components.
For information about installing the help content for Developer for z/OS locally, see IBM Documentation
Offline.

IBM Software Support

For product support, go to the IBM Support pages. Before you contact IBM Software Support, gather the
background information that you need to describe your problem. When describing a problem to an IBM
software support specialist, be as specific as possible and include all relevant information so that the
specialist can help you solve the problem. To save time, know the answers to these questions:
• What software versions were you running when the problem occurred?

8 Developer for z/OS: Welcome and Getting Started

 • Do you have logs, traces, or messages that are related to the problem?
• Can you reproduce the problem? If so, what steps do you take to reproduce it?
• Is there a workaround for the problem? If so, be prepared to describe the workaround.
For contact information and guidelines or reference materials, read the IBM Support Guide.
For product news, events, and other information, visit the IBM Developer for z/OS product page.

FAQ for IBM Developer for z/OS

Get answers to frequently asked questions about IBM Developer for z/OS.

How do I download and install IBM Developer for z/OS?

You can find the instructions at Installing IBM Developer for z/OS.

What hardware and software is required for IBM Developer for z/OS?
You can generate a detailed system requirements report at Software Product Compatibility Reports.

Which version of the IBM Developer for z/OS client is compatible with which version
of the Developer for z/OS server?
For more information about client-server compatibility, see IBM Developer for z/OS client-server
compatibility.

Do you offer product training?

Yes. For more information about online training for IBM Developer for z/OS and related products, see
remote training.

Do you offer a digital badge?

Yes. For more information about the digital badge, go to self-paced learning.

How can I provide feedback?

Your feedback is important for us to improve IBM Developer for z/OS. You can provide feedback in these
ways:
• At the top of any topic, next to the question "Was this topic helpful?", click Yes or No. Provide your
feedback in the window that opens.

• In the topic header, click Contact Us to send an email to the content development team.

How is IBM Developer for z/OS related to Rational Developer for z Systems?
IBM Developer for z/OS is the latest generation in a product family that has evolved, and undergone
several name changes, since it was first released in 2003. The original base offering was released
back under the name WebSphere Studio Enterprise Developer (WSED). Then in 2005 it was renamed to
WebSphere Developer for zSeries (WDz) and in 2007 there was a slight change to WebSphere Developer
for System z®. When the development team moved from the IBM WebSphere organization to the IBM

Welcome to IBM Developer for z/OS 9

 Rational® organization later that year we introduced the name Rational Developer for System z. The
product was known by that name for 8 years with only a minor adjustment in 2015 when we decided that
‘z Systems’ was a better description since it does not matter to the product whether you are running a z9®,
z10, z13®, and so on. Also in 2015 we introduced IBM Explorer for z/OS Aqua which brought the product
closer than ever to the rest of the z Systems Software suite, such as IBM File Manager (FM), IBM Fault
Analyzer (FA), and the CICS Tools. The name change to IBM Developer for z/OS at that time reflected that
closer alignment.
With the introduction of IBM Developer for z Systems v14.0 in 2016, we bumped up the version number
from 9.5.1 to again more clearly align the offering with other products in the z Systems software family.
We also responded to customer requests for an enterprise level development and debugging solution that
supports both a mixture of developers who quickly adopt the IDE and others who remain working under
ISPF. This solution was known as IBM Developer for z Systems Enterprise Edition V14.0, and it combined
IBM Developer for z/OS with IBM Debug for z Systems V14.0 in one product. We also offered an even
more comprehensive solution for enterprise development, Application Delivery Foundation for z Systems
V3.0 (ADFz), which is a bundle of IBM Developer for z/OS EE, File Manager, Fault Analyzer and Application
Performance Analyzer.
Finally, in 2019, we introduced IBM Developer for z/OS V14.2 and adopted the change from "z Systems"
to "z/OS" to align with the other offerings of ADFz, such as Fault Analyzer for z/OS, File Manager for
z/OS and Application Performance Analyzer for z/OS. Along with the new name, V14.2 included a new
product icon as part of our re-branding of the DevOps portfolio to give the products a more modern and
unified look and feel. As the product continues to evolve and modernize, our development team remains
committed to providing you with a smooth transition from one version to the next with delivering features
and tooling that help your development teams evolve and modernize too.

Videos and learning resources for Developer for z/OS

Access video and learning resources for Developer for z/OS.
IBM Developer for z/OS videos on IBM Media Center
DevOps on IBM Media Center
IBM Debug for z/OS on IBM Media Center
IBM Developer for z/OS free, online self-paced course
IBM Developer for z/OS free, remote instructor-led training
Search for IBM Developer for z/OS courses on IBM Training
Enterprise DevOps Training on IBM Developer
DevOps Acceleration Program
Cultivating Z Talent on the IBM Community site
Tutorials in the IBM Developer for z/OS Documentation
Samples in the IBM Developer for z/OS Documentation

10 Developer for z/OS: Welcome and Getting Started

Getting started

Quick start guide

Use this guide to get started with the installation of IBM Developer for z/OS and IBM Developer for z/OS
Enterprise Edition.

Product overview
Developer for z/OS consists of a common workbench and integrated set of tools that support end-to-end
development of on-demand applications and help make mainframe development, web development, and
integrated mixed workload or composite development faster and more efficient. For a full list of product
components available in each edition of Developer for z/OS, see “Welcome to IBM Developer for z/OS” on
page 1.

Access the software

Download the IBM Developer for z/OS Client and Host software from the IBM Explorer for z/OS Aqua
mainframe downloads website.
Developer for z/OS is available as part of different products. Contact the person responsible for the
purchase of Developer for z/OS, or possibly your local IBM representative, to learn which product was
purchased, so you can select the correct product registration method, as pricing and available features
differ for each product.
IBM Developer for z/OS (program number 5724-T07)
The Developer for z/OS client enhances the functionality provided by z/OS Explorer. Activation of
client features is managed by the client.
IBM Developer for z/OS Enterprise Edition (program number 5755-AB5)
The IBM Developer for z/OS Enterprise Edition provides the same Eclipse client functionality as
Developer for z/OS. However, activation of client features is managed by the host, and this product
provides additional debug related capabilities, such as a 3270 interface, and additional clients.
IBM Application Delivery Foundation for z/OS (program number 5755-AB1)
Application Delivery Foundation for z/OS provides Developer for z/OS Enterprise Edition, which is
described earlier, combined with other products useful for z/OS application development activities.

Evaluate the hardware and system configuration

For a complete listing of the Developer for z/OS hardware and software requirements including
prerequisites and co-requisites, see the Software Product Compatibility Reports.
For information about client-server compatibility, see IBM Developer for z/OS client-server compatibility.

Install the workstation components

For instructions on installing the Developer for z/OS client, see Choosing and installing a client.

Install the host components

Before doing any installation, review Planning in the IBM Developer for z/OS Host Configuration Guide to
learn about migration, planning, installation, configuration, and deployment considerations.
To install the host components of Developer for z/OS, follow the installation instructions in the z/OS
Explorer Extensions Program Directory (GI13-5624).

© Copyright IBM Corp. 1992, 2024 11

 To install the host components of the batch code analysis tools, follow the configuration instructions that
are found in the z/OS Source Code Analysis Program Directory (GI13-5625).
Configuration of the host components of Developer for z/OS includes a number of tasks, some required
and some optional. To configure the host functions, see the information found in these documents:
• IBM Developer for z/OS Host Configuration Guide (https://www.ibm.com/docs/en/developer-for-zos/
latest?topic=configuration-developer-zos-host-guide)
• IBM Developer for z/OS Host Configuration Reference (https://www.ibm.com/docs/en/developer-for-
zos/latest?topic=configuration-developer-zos-host-reference)
For information about additional host components supported by each edition of Developer for z/OS, and
instructions for installing and configuring them, see Installing and configuring the host components.

Getting help
Help for using the product is available in the welcome page, the IBM Documentation, online and offline,
the context-sensitive helps, and language-sensitive help, and cheat sheets.

IBM Documentation online

IBM Documentation contains help topics about the product function and provides tools that you can use
to find information. It is available both from a browser and from the product user interface. To open IBM
Documentation, do one of these steps:
• Open a browser on https://www.ibm.com/docs/en/developer-for-zos/17.0.
Tip: For an easier browse and search experience, open the online help by using this method. The IBM
Documentation is not supported by the Eclipse help system. If you open the online help by using Help >
Help Contents, you might see multiple error messages in the log and get unexpected or incorrect help
search results.
• In the product menu bar, click Help > Help Contents. The IBM Documentation opens in a new window.
To open the IBM Developer for z/OS section of the help content, click IBM Developer for z/OS in the
table of contents.

IBM Documentation offline

IBM Documentation is available for installation on a workstation. After it is installed on your workstation,
the offline documentation contains the full product documentation contents and does not require
an internet connection. To learn about IBM Documentation offline and how to install it, see IBM
Documentation Offline.

Context-sensitive help
While you are using the product, you can open context-sensitive help that relates to the current view or
window. To open the context-sensitive help:
On Windows: Place the cursor in a field and press F1, Ctrl+F1, or Shift+F1.
On macOS: FN+F1
Remote Connection Emulator: To open help for the main Remote Connection Emulator window and for
the Edit profile fields, click the ? icon. The corresponding help topic opens in IBM Documentation.
To control where context-sensitive help opens, open the Preferences window and select Help. In the
Context help area, you can select the following locations for context help:
• In the dynamic help view: This view remains open while you are working in the workbench. Its content
changes as you bring focus to different areas of the user interface. This option is available for the main
workbench window only. It contains options for opening help contents, searching the help, opening help
bookmarks, and opening the help index.

12 Developer for z/OS: Welcome and Getting Started

• In an infopop: This view opens in a pop-up window below the dialog or area of the window that has
focus. This option is available for the main workbench window and for dialogs. From it you can open
related links or help preferences, or switch to the dynamic help view.

• In a dialog tray: This view slides open at the side of a dialog. This option is available for dialogs only. It
contains the same options as the dynamic help view.

Getting started 13
 Language-sensitive help
Many of the editors available with the product offer language-sensitive help. Language-sensitive help
opens the programming language references for programming statements and keywords that are selected
in the editor. Language-sensitive help is available in these editors:
• COBOL Editor
• JCL Editor
• PL/I Editor
• REXX Editor
• z Systems LPEX Editor
For more information about language-sensitive help, and other help available in the editors, see Getting
help while editing source files. If you have trouble using language-sensitive help, see “Troubleshooting
language-sensitive help” on page 16.

Cheat sheets
Cheat sheets provide guidance for some of the most common tasks you can do with the product. They
also serve as a good overall introduction to product features and how to use them. To open the product
cheat sheets:
1. Click Help > Cheat Sheets.
2. In the Cheat Sheet Selection window, expand IBM Developer for z/OS.
3. Select Getting Started Catalog and click OK. The cheat sheets open in a new tab in the workbench.

Welcome page
The Welcome page provides resources to orient you to IBM Developer for z/OS and help you start using
a new workspace. If you are new to IBM Developer for z/OS, the Welcome page is a good place to
start for learning about major features of the product and links to getting started information. If you
are an experienced user, the Welcome page is also a convenient location to read about new features
and technologies that are related to the product. Other Eclipse-based products that are installed in your
environment also contribute content to the Welcome page.
The Welcome page is displayed the first time that you start the product. If the Welcome page is not
currently open, click Help > Welcome.

Troubleshooting help problems

IBM Documentation has some requirements and limitations when accessed from Eclipse-based products.
You might experience any of the following problems opening the helps or populating the web browser
with help content.
• The help content pane is empty.

14 Developer for z/OS: Welcome and Getting Started

• A message indicates help is not available.
• A message indicates a network error.
• The browser opens with help content, but performance is slow.
For a list of the products in the Aqua product family that might be affected by the migration to IBM
Documentation, see IBM Explorer for z/OS Aqua Product Versions.
To solve some of the problems with IBM Documentation support for the IBM Explorer for z/OS Aqua
product family, follow these guidelines:
Use a supported browser:
The following browsers have been tested with the product and can open IBM Documentation. Other
browsers might not function correctly. To choose a browser:
1. On the Preferences window, click General > Web Browser.
2. Select Use external web browser, and then select one of these browsers.
• Windows: Chrome, Microsoft Edge
• macOS: Chrome, Safari
Open IBM Documentation in an external browser
On Windows, you must set Help preferences to use an external browser. IBM Documentation does not
support the internal Eclipse browser. On macOS helps open in an external browser by default, and the
preferences in this procedure are not available.
1. Open the Preferences window and click Help in the navigation pane.
2. From the Open help contents list, select In an external browser.
Update plugin_customization.ini
If you select Help > Help Contents to open the online help, you might see the message Help is
unavailable. This issue is caused by an error in the product plugin_customization.ini file. To
resolve this issue, do these steps:
1. Edit this file:

IBM Developer for

zOS\plugins\com.ibm.developer.for.zos.product_16.0.0.202210132216\plugin_
customization.ini
2. Change the org.eclipse.help.base/help_home= parameter from this:

org.eclipse.help.base/help_home=/com.ibm.wsentdev.doc/topics/
kc_version_welcome_rdz.html

to this:

org.eclipse.help.base/help_home=/com.ibm.etools.getstart.wsentdev.doc/topics/aintro.html

3. Restart the product.

4. Click Help > Help Contents.
The product overview page opens in the online help.

Getting started 15
 Performance
You might notice a delay as the browser populates with the help content. The IBM Documentation
team is aware of performance issues and is working to improve the speed of populating the help
window.

Troubleshooting language-sensitive help

If you have trouble opening language-sensitive help, try these tips for working around known issues.
IBM Developer for z/OS provides language-sensitive help for program statements and keywords in COBOL
and PL/I files. This help includes support for EXEC CICS, EXEC SQL, and EXEC DLI statements.
Language-sensitive help opens the programming reference for the statement or keyword that is selected
in the editor.
When you open language-sensitive help, you might see a message similar to the following: It indicates
that the web browser (Microsoft Edge in this example) is preventing Eclipse from opening an external
browser.

To work around this issue:

1. Open the Preferences window.
2. In the navigation pane, select Help.
3. From the Open help contents list, select In the help browser. This change to the help preferences,
bypasses the external browser block.

16 Developer for z/OS: Welcome and Getting Started

 4. If you also see a message similar to the following, click the link to open the content in a new window.

Related information
“Preferences” on page 74
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.

First steps for developing applications in zIDE

First steps include some of the tasks you might want to complete to begin developing z/OS applications
by using the Developer for z/OS z/OS integrated development environment (zIDE). It provides links to
other topics that contain the details about how to complete each task.
The following table describes some tasks that you might want to begin with when you start working with
zIDE.

Table 2. First steps for developing applications in zIDE

Task Description More information
Customize workbench Some useful settings include • “Preferences” on page 74
preferences preferences for the editors.
• Setting z Systems LPEX Editor
preferences
• Setting COBOL Editor
preferences
• Setting PL/I Editor preferences
• Setting JCL Editor preferences

Getting started 17
 Table 2. First steps for developing applications in zIDE (continued)
Task Description More information
Customize perspectives to show The z/OS Projects perspective • Working with perspectives
only the views that you need or provides a default set of views
• Working with views and editors
want to see for accessing and using tools
for application development. You
can customize the perspectives
for the layout that works best for
you.
Create a connection to a remote Remote system connections • Connecting to a z/OS system
system allow for access to files and
resources on remote AIX® and
z/OS systems.
Connect to a Git repository With the DBB integration, you can Integrating IBM Dependency
upload individual source files to a Based Build and Developer for
z/OS system from a local GitHub z/OS
repository clone or from a local
IDz project.
Create a property group Property groups store options Creating and editing property
that you use to build groups
applications. They allow for
creation of specific sets of
resource options, storing them,
and reusing them for multiple
resources.
Set up build options appropriate Build options are stored in Setting property group
for your environment property groups. When you options for editors, compilers,
create a property group, you use preprocessors, and build
it to set build options for your
applications.
Set up the qualifier for The Developer for z/OS show Setting compiler options for show
error feedback and Show dependencies and remote dependencies and remote syntax
Dependencies actions syntax check functions detect check
dependencies for COBOL, PL/I,
and Assembler programs. These
functions use the COBOL and
PL/I compilers and High Level
Assembler to locate the copy
members, include files, and
macros that are needed to
compile a program properly.
Modify default JCL procedures The default JCL procedures and • ELAXF* remote build
and job cards appropriately for job cards are defined in property procedures
your environment groups.
• Setting options for procedures
and steps

18 Developer for z/OS: Welcome and Getting Started

 Table 2. First steps for developing applications in zIDE (continued)
Task Description More information
Allocate a data set to contain The JCL options that are stored in • Allocating data sets
generated JCL property groups generate JCL for
compiling, linking, and running
applications. This generated JCL
is stored in a partitioned data set
member for submission to the
JES subsystem.
Verify that your workstation- MVS™ file system mappings map Mapping data sets and
remote-system mapping is workstation file extensions to partitioned data set members
correct low-level MVS data set qualifiers
to ensure correct data transfers
between the workstation and the
remote system.

Becoming familiar with zIDE perspectives and views

To access and work with z/OS and zEnterprise® resources from the workbench, you can open either of two
default perspectives that are customized for z/OS and zEnterprise application development: the Remote
System Explorer perspective or the z/OS Projects perspective.
• You can use the Remote System Explorer perspective to do MVS based tasks that are equivalent to tasks
done in ISPF:
– View lists of data sets and members
– Allocate or delete data sets
– Create or delete members
– Edit text
– Submit JCL
– Submit TSO commands
You do most of those tasks in the Remote Systems view.
• You can use the z/OS Projects perspective to carry out a particular development effort. The z/OS
Projects perspective is included with the Developer for z/OS editions of the product. It provides tools
for connecting to UNIX and z/OS systems. In its z/OS Projects view, you can work with local and remote
z/OS projects, and MVS and z/OS UNIX subprojects.
By default, the z/OS Projects perspective includes the Remote Systems view, where you can do
several of the remote system tasks that were listed earlier. This perspective also includes views that you
can use to obtain the output of a specific job and display it. Organizing source files with projects and
subprojects explains some of the basics of working in the z/OS Projects view.
After you learn about these perspectives and the benefits of using them as you work, you can proceed to
customize a perspective if you want to close default views or open other related views. See the related
topics for information on the content of each perspective and instructions for customizing the perspective.
Related reference
“Remote System Explorer” on page 20
The Remote System Explorer is a perspective that provides an interface for managing remote systems
with conventions that are similar to ISPF.
“z/OS Projects perspective” on page 21

Getting started 19
 Use the z/OS Projects perspective to define, connect, and work with remote systems, and to create, edit,
and build projects, subprojects, and files on remote UNIX and z/OS systems.

Remote System Explorer

The Remote System Explorer is a perspective that provides an interface for managing remote systems
with conventions that are similar to ISPF.
As you work in this perspective, you can do these tasks:
• Define and connect to remote systems
• Manage your connections
• View lists of resources
• Add or modify file mappings
• Allocate or delete data sets
• Create or delete members
• Edit text
• Submit JCL
• Submit TSO commands
• Add or modify job filters
To open the Remote System Explorer, if it is not already open when you start, do these steps:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) >
Perspective > Open Perspective > Other.
2. Click Remote System Explorer.
3. Click OK. The Remote System Explorer opens.
The Remote System Explorer contains the following views:
• Remote Systems view
• Properties view
• Outline view
• Tasks view
• z/OS File System Mapping view
• Team view
• Remote Scratchpad view
• Remote Systems Details view
You can close views and open views to customize the perspective.
To close a view, click the X close button in the upper right corner of the view.
If you close a view, you can open the view again. To open one of the default views that were closed:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) > Show
View. A menu that lists the default views associated with the Remote System Explorer perspective is
displayed.
2. Click the name of the view you want to open.
To open a view that is not a default for the perspective you are working in, you must determine the
perspective that contributes the view:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) > Show View
> Other. Folders are listed for each perspective that is defined in the workbench.
2. Search through the folders until you find the view you want to open.
3. Click the name of the view you want to open.

20 Developer for z/OS: Welcome and Getting Started

 When you have a custom mix of default and other views you would like to use repeatedly based on a
perspective, you can save this customized perspective:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) > Save
Perspective As.
2. Type a name for your customized perspective in the Name field.
You can now open, close, and reset the customized perspective to the default configuration you defined
when you saved the customized perspective.
Related reference
“Becoming familiar with zIDE perspectives and views” on page 19
To access and work with z/OS and zEnterprise® resources from the workbench, you can open either of two
default perspectives that are customized for z/OS and zEnterprise application development: the Remote
System Explorer perspective or the z/OS Projects perspective.
Getting Started with the Remote System Explorer

z/OS Projects perspective

Use the z/OS Projects perspective to define, connect, and work with remote systems, and to create, edit,
and build projects, subprojects, and files on remote UNIX and z/OS systems.
The z/OS Projects perspective is included with the Developer for z/OS edition of the product.
The z/OS Projects perspective contains the following views:

Some components add views to this perspective when you install them. The Eclipse EGit component, for
example, adds the Git Repositories view and the Git Staging view to this perspective.
You can close views and open views to customize the perspective.
If you close a view, you can open the view again. To open one of the default views that were closed:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) > Show
View. A menu that lists the default views associated with the z/OS Projects perspective is displayed.
2. Click the name of the view you want to open.
To open a view that is not a default for the perspective you are working in, you must determine the
perspective that contributes the view:

Getting started 21
 1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) > Show View
> Other. Folders are listed for each perspective that is defined in the workbench.
2. Search through the folders until you find the view you want to open.
3. Click the name of the view you want to open.
When you have a custom mix of default and other views you would like to use repeatedly based on a
perspective, you can save this customized perspective:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) > Save
Perspective As.
2. Type a name for your customized perspective in the Name field.
You can now open, close, and reset the customized perspective to the default configuration you defined
when you saved the customized perspective.
Related concepts
Editing source program files
Snippets view
Monitoring jobs with the JES Subsystem
Related tasks
“Switching to a new perspective” on page 24
As you develop z/OS programs, you might want to switch to the perspective where z/OS projects, builds,
and JCL generation are supported. After you open the z/OS Projects perspective for the first time, the
workbench includes the perspective in a list that is available from the shortcut bar.
Related reference
“z/OS Projects view” on page 22
“Becoming familiar with zIDE perspectives and views” on page 19
To access and work with z/OS and zEnterprise® resources from the workbench, you can open either of two
default perspectives that are customized for z/OS and zEnterprise application development: the Remote
System Explorer perspective or the z/OS Projects perspective.
“Remote System Explorer” on page 20
The Remote System Explorer is a perspective that provides an interface for managing remote systems
with conventions that are similar to ISPF.
“Keyboard shortcuts” on page 24
Many keyboard shortcuts are available in the workbench.
Related information
Developer for z/OS product website
Defining resource options with property groups

z/OS Projects view

Use the z/OS Projects view to work with local and remote z/OS projects and MVS and z/OS UNIX
subprojects.
The z/OS Projects view shows all local and remote z/OS projects you defined and their MVS and z/OS
UNIX subprojects. It also includes any host-based projects that might be added to the view when you
connect to a remote system. If the view contains no projects, you can click a link in the view to create a
z/OS project, create an MVS subproject, import a z/OS project, or open help for z/OS projects.
By using this view, you can accomplish the following tasks:
• Create and delete projects and subprojects.
• Rebuild projects and subprojects, which compiles all code in the project.
• Build specific project content, which compiles the code that is contained in a partitioned data set
member.
• Allocate partitioned and sequential data sets.

22 Developer for z/OS: Welcome and Getting Started

• Start an edit session for a specific file or partitioned data set member.
• Move, copy, rename, and delete files or partitioned data set members.
• Add and remove remote files in a subproject.
• Check the syntax or dependencies of a file or partitioned data set member.
• Run executable files.
• Import and export projects so that you can share them with others.
• Work with the property groups associated with subprojects or files to set build options.
• Access other Developer for z/OS tools for working with z/OS resources, such as debug tools, team tools,
File Manager tools, Enterprise Service Tools, and data tools.
The view also provides several toolbar functions that allow for control of the contents of the view itself.
These tools are accessible from the menu at the top of the view.
Show > Local Files
Select this toggle menu item to display local files in the view. Clear it to hide local files.
Show > Remote Files
Select this toggle menu item to display remote files in the view. Clear it to hide remote files.
Show > MVS File Extensions
Select this toggle menu item to display file extensions for files in online or offline MVS subprojects.
Clear it to hide file extensions.
Note: Clearing this option does not affect the ability of editors to recognize language-sensitive content
type, syntax highlighting, or other functions that are based on the language type. When a file is opened
in an editor, the editor title tab displays the file extension.

Filter
Select a filter to apply to the view.
Related concepts
Organizing source files with projects and subprojects
Related information
Configure z/OS UNIX subprojects
Create a ZDT test environment

MVS Files details view

Use the MVS Files subsystem details view to explore MVS files on the remote system
From the Remote Systems view, you can open the MVS Files subsystem details view. This view displays
details about the MVS Files subsystem on the selected z/OS system.
To explore files in the MVS Files subsystem details view:
• To open the MVS Files subsystem details view, do either of the following steps:
a) In the Remote Systems view, select MVS Files and then click Show in Table on the menu.
b) From the Remote System Details view, double-click the name of the remote system to which you
are connected, then double-click MVS Files.
The MVS Files subsystem contains the following entries:
– My Data Sets - the default MVS files filter.
– Retrieved Data Sets - the last 10 data sets that you searched for by using the Retrieve Data Set
action or added by using the allocate actions.
– Any other MVS file filters that you created.
– My Favorites - any search query results you saved by using the Remote z/OS Search view.
• To drill down to the MVS files located by each filter, double-click the filter in this view.

Getting started 23
 • Use the following icons and menu to lock, unlock, or refresh the view, navigate through the files and
filters in the view, change the columns that are displayed in the view, or locate a specific resource in
the view.
Option Description

Lock and Unlock Toggles the selected resource between locked and unlocked status. If
the resource is unlocked, selecting an object in the Remote Systems
view updates the details view.

Refresh Refreshes the view.

Move Backward Navigates backward and forward among pages you previously viewed.
and Move Forward

Move up one level Navigates up the hierarchy of MVS Files, filters, data sets, and partitioned
data set members.

Customize Table Opens the Customize Table window, which you can use to add, remove,
or reorder columns in the view.
Select Input Switches to a different local or remote object.
Position To Locates the first resource that matches the string you enter in the
Position To window.
Subset Opens the Subset window to select criteria for limiting the contents that
are displayed in the view.

Switching to a new perspective

As you develop z/OS programs, you might want to switch to the perspective where z/OS projects, builds,
and JCL generation are supported. After you open the z/OS Projects perspective for the first time, the
workbench includes the perspective in a list that is available from the shortcut bar.
To open the z/OS Projects perspective:
1. In the workbench, select Window (on Windows) or IBM Developer for z/OS (on macOS) >
Perspective > Open Perspective > Other.
The Select Perspective wizard opens.
2. Click z/OS Projects.
3. Click OK.
The z/OS Projects perspective opens.
On the workbench shortcut bar, you can click Open a Perspective to switch to the z/OS Projects
perspective.
Related reference
“z/OS Projects perspective” on page 21
Use the z/OS Projects perspective to define, connect, and work with remote systems, and to create, edit,
and build projects, subprojects, and files on remote UNIX and z/OS systems.

Keyboard shortcuts
Many keyboard shortcuts are available in the workbench.
For a complete list of keyboard shortcuts available in the workbench:
1. In the Preferences window, navigate to General > Keys.
2. Do either of the following steps:
• To sort the list of key bindings by category, click the Category table heading.
• To sort the list of key bindings by context, click the When table heading.

24 Developer for z/OS: Welcome and Getting Started

 3. Do either of the following steps:
• To find keyboard shortcuts that are active in a particular context, type the context name in the filter
field.
• To find keyboard shortcuts for the Remote Systems view or z/OS Projects view, for example, type
Remote Systems View or z/OS Projects View in the filter field.
Related information
“Preferences” on page 74
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.

z/OS Integrated Development Environment (zIDE) icons

These icons are displayed in the Remote Systems view and the z/OS Projects view.

Remote Systems view

These icons are commonly seen under the z/OS connection tree of the Remote Systems view.

Table 3. Remote systems, subsystems, and filters

Icon Description Icon Description
A z/OS system A z/OS system to which
you connected
The z/OS UNIX files The z/OS UNIX Files
subsystem subsystem in a z/OS
system to which you are
connected
The z/OS UNIX Shells The z/OS UNIX Shells
subsystem subsystem in a z/OS
system to which you are
connected
The MVS Files The MVS Files
subsystem subsystem in a z/OS
system to which you are
connected
The TSO Commands The TSO commands
subsystem subsystem in a z/OS
system to which you are
connected
A remote command The JES subsystem
shell, such as a TSO
shell or a z/OS UNIX
shell
The JES subsystem in A filter that is defined for
a z/OS system to which the z/OS UNIX files, MVS
you are connected files, or JES subsystem
A filter that is defined The My Favorites folder
by using the Retrieve in the MVS Files
Data Set or Retrieve subsystem
Job action

Getting started 25
 Table 4. Drives, folders, files, and data sets.
Tip: To see more file icons, open the Preferences window and navigate to General > Editors > File
Associations.

Icon Description Icon Description

A local hard disk or root A file folder
directory
A file A partitioned data set

A partitioned data set A partitioned data set

that is expanded that is migrated
A partitioned data set on A sequential data set
an offline volume or partitioned data set
member on a z/OS
system
A VSAM data set on a A remote file (typically
z/OS system a partitioned data
set member) that is
associated with the
LPEX editor by default
Scroll down through a Scroll up through a list
list of partitioned data of partitioned data set
set members members
A generation data group An alias that is defined
for a partitioned data set
An alias that is defined
for a sequential data set

Table 5. JES jobs

Icon Description Icon Description
A JES job A JES job that is running

A JES job for which

a command (such as
purge or hold) was
issued

Table 6. Other icons

Icon Description Icon Description
A symbolic link. This
icon is a decorator. It is
added to the icons for
files or folders that are
symbolic links.

Related information
“Preferences” on page 74

26 Developer for z/OS: Welcome and Getting Started

 Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.

z/OS Projects view

These icons are commonly seen in the z/OS Projects view.

Table 7. Projects, subprojects, and files.

Tip: To see more file icons, open the Preferences window and navigate to General > Editors > File
Associations.

Icon Description Icon Description

A local z/OS project or a A remote z/OS project
z/OS UNIX subproject
An MVS subproject A file folder

A file A partitioned data set

A partitioned data set A sequential data set

that is expanded or partitioned data set
member on a z/OS
system
A file that is associated A remote file (typically
with the LPEX editor by a partitioned data
default set member) that is
associated with the
LPEX editor by default
A file that is associated A file that is associated
with the COBOL Editor with the PL/I editor by
by default default
A zComponent A zComponent project
(Engineering Workflow (Engineering Workflow
Management integration Management integration
resource type) resource type)
A zFolder (Engineering A zFile (Engineering
Workflow Management Workflow Management
integration resource integration resource
type) type)

Related information
Orientation to Engineering Workflow Management for Developer for z/OS users
“Preferences” on page 74
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.

How do I . . . ?
Obtain answers to frequently asked questions about using the z/OS integrated development environment.
1. How do I determine the product level of the remote system server?
In the Remote Systems view, connect to the remote system and then select MVS Files. The server
level is shown in the Server Level field of the Properties view
2. How do I determine which APARs or PTFs are applied to the remote system server?

Getting started 27
 Open a z/OS UNIX command shell and issue the following two commands:
• $ cd /usr/lpp/IBM/zexpl/bin
• $ ./version.sh
The list of APARS is displayed as shown in the following example:

Wed Feb 28 04:44:12 2019 -- COPY -- HHOPE10 v14.1.7.0 created 27 Feb 2019

14.1.7.0: AM41857 AM43628 AM52641 AM50744 AM51321 AM52427 AM52635

3. How do I determine the product level of the client?

From the main menu bar, select Help > About Developer for z/OS.
4. Some functions in the Remote Systems view are disabled. How do I enable them?
Some functions, such as Retrieve Data Set and Find Member, require the remote system server to
be at a certain product level. To access these functions, install the latest Developer for z/OS product
version on the remote system server.
5. How do I set the default editor for my COBOL or PL/I files?
a. In the Preferences window, expand the General > Editor categories.
b. Select File Associations.
c. In the File types list, select a file extension, such as .cbl or .pli.
d. In the Associated editors list, select COBOL Editor or PL/I Editor.
e. Click Default.
f. Click OK to save the changes.
6. The tooling icon in the COBOL or PL/I Editor is disabled. How do I enable it?
a. In the Preferences window, expand the COBOL or PL/I category.
b. Select Real-Time Syntax Checking.
c. Clear the Disable syntax parser checkbox.

Tips and tricks for zIDE

These tips and tricks give some helpful ideas for increasing your productivity.

AND search queries

You can use the Remote z/OS Search window to run an AND search query:
1. Open the Remote z/OS Search window.
2. In the Content strings field, type a search string with the following syntax:

.*<literal1>.+<literal2>

To find all lines in a program that contain the strings IF and WS-PHARM, for example, type the following
search string:

.*IF.+WS-PHARM

Moving from 3270 ISPF to IBM Developer for z/OS

Experienced ISPF users who move to the IBM Developer for z/OS client as a development platform must
learn new terminology, new concepts, and new methods to complete tasks. You must also learn how to
use different artifacts and know how they relate to each other. Even though the development tools are
different, the overall application development work flow is the same.

28 Developer for z/OS: Welcome and Getting Started

 The typical z/OS development environment includes using Interactive System Productivity Facility (ISPF)
and switching between several tools to develop applications in a z/OS environment. The overall process
includes these tasks:
• Edit your source file and save the file.
• Edit the JCL code that is required to run your job on the z/OS system.
• Compile your application by submitting it to run on the z/OS system.
• Monitor and review the job output.
• If there are errors, edit the source file to make corrections. If there are errors, you must remember
where the error is, switch to an editing session to make corrections, and repeat the cycle.

Using this information

The topics that are presented here are limited in scope. They do not describe the entire product but
explain basic tasks and the differences you might experience between the workstation client and the
mainframe development environment.
You can print the entire set of information as one PDF file by using the help system print feature. Click the
print icon. Choose one of the following options:
• Print this topic
Select this option to print a single topic.
• Download this page
Select this option to obtain a generated PDF of a single topic.
• Download this section
Select this option to obtain a generated PDF of a topic and its subtopics.

Architecture
IBM Developer for z/OS consists of a mainframe system component and a workstation client component.

Remote system
The mainframe system component is also referred to as the remote system component. It is the part
of the product that is installed on the z/OS mainframe. The remote system component is the z/OS
mainframe to which you connect to access data. This portion of the product is installed into a z/OS logical
partition (LPAR) by the site system programmer.
The remote system component provides the interface between the workstation client and traditional
development components, such as Job Entry Subsystem (JES) and the file system.
• During setup, you create a connection between the workstation client and remote system components.
• The remote system component provides transaction management system functions to communicate
with Information Management System (IMS) and CICS.
• Problem determination tools, such as the IBM Debug Tool, are included.

Workstation client
The workstation client is the element that is installed on a personal computer operating environment.
It must be installed on each developer's computer. Throughout the product documentation, the term
IBM Developer for z/OS refers to the workstation component. The client software can be installed on a
Microsoft Windows or macOS operating system. The two components communicate by using TCP/IP.
The workstation client component provides a graphical user interface to access to the remote system
component. This interface is built on the Eclipse framework and infrastructure. Many other products are
built on Eclipse and they can share the user interface. More information about the Eclipse platform is at
www.eclipse.org.

Getting started 29
 The user interface contains a set of development tools that support the development, maintenance, and
web service enablement of enterprise applications.
• Access z/OS assets. You can organize, allocate, manage, and edit z/OS data sets and tools.
• Develop, maintain, compile, and assemble source files by using integrated language-sensitive editors
for COBOL, PL/I, IBM High Level Assembler (HLASM), C/C++, Java, job control language (JCL), basic
mapping support (BMS), and Message Format Service (MFS). You can access source directly from
Multiple Virtual Storage (MVS) data sets or through a number of source control management (SCM)
systems.
• Manage and edit data such as these information types:
– Queued sequential access method (QSAM) or sequential data sets
– Virtual Storage Access Method (VSAM) or indexed data sets
– Relative and entry sequenced data sets
– Db2 tables and views
– Information Management System (IMS) databases
• Access to your z/OS Job Entry Subsystem (JES) to submit jobs and JES spool files to organize and
manage batch jobs.
• Access other tools such as wizards and declarative development tools that replace low-level coding to
create, deploy, and test web services; and use Enterprise Generation Language (EGL) to develop Java
Platform, Enterprise Edition applications.

Remote system communication

The z/OS operating system is different from a workstation operating system architecturally. To facilitate
the transport of data sets and files between the remote system and the client workstation, information
about data transfer and port connections must be defined. Information about data transfer is called
mapping information.
Port
Defines the communication channel that is used to transport data between the workstation and
remote system.

30 Developer for z/OS: Welcome and Getting Started

 Mapping
Defines the information that is required to move files between the workstation and remote system:
• File type
• Transfer mode
• Host and local code pages

Port
A port is an end point for communication between applications. It is the logical connection between the
remote system components and the workstation component. The port provides queues for sending and
receiving data. Each port has a port number for identification. The port number must be specified when
you create a connection between the remote system and workstation.
The system programmer for your site defines a port number during installation for a remote daemon or
REXEC port. You must contact the system programmer for your site to obtain the type of port and the port
number.

Mapping
Most operating systems recognize and differentiate files by their file extensions, which are referred to
as the file type. For example, a file with the .txt extension is processed as a text file, while a file with
the .html extension is processed as a hypertext markup language file. On the z/OS system, the concept
of file extensions does not exist. Therefore, each data set type or file must be explicitly defined so that it is
transported and processed between the remote system and the workstation correctly.
The transfer mode refers to whether the file is transported as text or binary.
A computer system translates keyboard inputs to character values according to the code page that is
specified on each system. z/OS systems employ the EBCDIC family of code pages and most workstation
systems employ the ASCII family of code pages. When a file is transported between these two operating
systems, code-page conversion must be taken into account so that the file is translated and displayed
correctly on the destination system. IBM Developer for z/OS handles this translation automatically, but
to do so, it must be told in advance what code pages are being used on the remote system and the
workstation.
Specifying mapping definitions provides the file type, transfer mode, and code page information that
is required to transfer data between the remote system and workstation. The term mapping is used
throughout the product documentation to refer to defining file transfers and other information. Developer
for z/OS provides a set of default mappings to simplify the setup. For example, all data sets with an end
qualifier COBOL are mapped to the .cbl file extension and text transfer mode. This mapping causes the
members to be treated as COBOL source files when they are transported and opened on the workstation.
Another default mapping assigns load modules with the end qualifier LOAD to the .exe file extension and
binary transfer mode.
Each z/OS system can have its own mapping. Mapping definitions are defined by using the z/OS File
System Mapping view.

Key environment concepts

One of the challenges of learning a different environment is understanding the terminology.
The following table lists several terms that have different names in the mainframe and workstation
environments.

Table 8. Terms used in mainframe and workstation environments

Mainframe Workstation Description
Data set File A group of related data that is stored and retrieved
by an assigned name.

Getting started 31
 Table 8. Terms used in mainframe and workstation environments (continued)
Mainframe Workstation Description
Allocate Create Assign a resource to a specific task.
Extension File type A tag of three or four letters, which are preceded
by a period, that identifies the file format or the
application that is used to create the file.
Open Load
ABEND Crash, failure, hang An abnormal completion of a program.
Catalog Directory, folder A file structure where data sets and files are
stored on a system.
Job Process A program that is processing.
Task Thread A single unit of work within a program.

Navigating
One of the first differences you might notice between IBM Developer for z/OS and ISPF is how you
navigate the product. You navigate ISPF by using the keyboard to type on panels and in the command line.
In Developer for z/OS you use a mouse to select menu items, controls, and items from lists and tables,
and you use the keyboard for typing text.
You use these user interface objects to complete tasks.
Workspace
The top-level folder on your computer where information about all the resources that you work
with is stored. It contains local z/OS projects and files and information about your remote system
connections and your development preferences and settings.
Perspectives
A collection of views that relates to a specific high-level task. These perspectives are commonly used:
• The z/OS Projects perspective provides tools for accessing remote systems, creating projects, and
submitting builds. This view is relevant to z/OS COBOL, PL/I, and HLASM project work.
• The Debug perspective enables debugging z/OS remote and local applications.
• The Enterprise Service Tools perspective provides tools for building and testing web services.
Each perspective contains several views that provide a different function or a different way of
viewing the resources that you are working with. For a description of the views in the z/OS Projects
perspective, for example, see “Key views” on page 33.
Windows
Places to type information, select items from lists, and click controls to complete actions. Most
windows open in response to selecting a menu item.
Menu bar
At the top of the workspace, the menu bar contains frequently used actions. When you click a menu,
one or more actions occur.
Toolbar
At the top of the workspace just below the menu bar, the toolbar changes contents according to the
active window or editor. Actions in the toolbar might apply to particular views, so these actions might
be enabled or disabled according to the state of the active view or editor.
Menus
Lists of specific actions that you can do in the user interface. Most views provide menus, which you
access by positioning the mouse pointer in the view and pressing the right mouse button.

32 Developer for z/OS: Welcome and Getting Started

Figure 1. Example of a user interface

Note: The graphical user interface is sometimes referred to as the z/OS integrated development
environment or zIDE. These two terms are used throughout the documentation.
Related concepts
“Key views” on page 33
Perspectives are composed of views. To understand how to work with views, you must first understand
the functions that are supported by each view.
“Tips on using the user interface” on page 35
The user interface is robust, and with it, you can complete many functions. These tips can help you
become proficient with the user interface.

Key views
Perspectives are composed of views. To understand how to work with views, you must first understand
the functions that are supported by each view.
The following list provides a brief description of some key views and the types of tasks that you can do in
each.
Remote Systems
The Remote Systems view supports the connection to remote systems. After a connection is made to
a remote system, use this view to browse through remote data sets, files, and jobs.

Getting started 33
 ISPF functions such as data set allocation, rename, or delete (ISPF option 3.2), move and copy (3.3),
and data set listing (3.4) can be performed in this view.
Jobs that are submitted to the job subsystems can be viewed and manipulated under the Job Entry
Subsystem (JES) that is found in your z/OS system connection definition. You can view a list of jobs
and complete operations such as view output, purge, cancel, and hold against these jobs. For a
detailed view of these jobs, you can also display them in a tabular view by selecting Show in Table
from the menu. The tabular view provides a more ISPF-like view of your jobs. To view job output,
highlight any completed job, and select Open. Job outputs are displayed in the default text editor.
Remote Shell
The Remote Shell view provides a command-line interface to support the execution of TSO
commands. You can run commands, CLIST, and REXX from the command line and view the output
on the same view. The command inputs and outputs can also be saved.
To open the Remote Shell view, select TSO Commands in the Remote Systems view, and click
Launch TSO.
Remote Error List
The Remote Error List displays errors that result from failed operations. Errors such as syntax errors,
build problems, and code generation are displayed in this tabular view. The error information contains
a link that opens the source line with the syntax problem.
Property Group Manager
The Property Group Manager displays property groups that are defined on local and remote systems.
Property groups define the attributes and attribute values that are used to compile applications and
standardize your development environment.
z/OS Projects
The z/OS Projects view organizes the files that you downloaded to your computer or create on your
computer to be uploaded. Use this view to work with projects, subprojects, data sets, and members to
complete these tasks:
• Create and delete projects and subprojects.
• Rebuild projects and subprojects, which compiles all code in the project.
• Build specific project content, which compiles the code that is contained in a partitioned data set
member.
• Allocate partitioned and sequential data sets.
• Start an edit session for a specific file or partitioned data set member.
• Move, copy, rename, and delete files or partitioned data set members.
• Add and remove remote files in a subproject
Properties
The Properties view shows file attributes and data set statistics of selected resources. It is similar to
ISPF option 3.2.
z/OS File System Mapping view
The z/OS File System Mapping view shows the mappings that are defined on the remote system. This
view displays the relationships between a mapping criterion and the corresponding workstation file
extensions and transfer modes. It also displays the relationships between local and host code pages.
To view the information for a system definition, select the system in the Remote Systems view. The
z/OS File System Mapping view loads and displays the mapping information that is defined for the
system.
Related concepts
“Navigating” on page 32
One of the first differences you might notice between IBM Developer for z/OS and ISPF is how you
navigate the product. You navigate ISPF by using the keyboard to type on panels and in the command line.

34 Developer for z/OS: Welcome and Getting Started

In Developer for z/OS you use a mouse to select menu items, controls, and items from lists and tables,
and you use the keyboard for typing text.
“Tips on using the user interface” on page 35
The user interface is robust, and with it, you can complete many functions. These tips can help you
become proficient with the user interface.

Tips on using the user interface

The user interface is robust, and with it, you can complete many functions. These tips can help you
become proficient with the user interface.
• To customize the layout and content of any perspective, drag it to the location that you want on the user
interface.
• To close a view that you are not using, click X on the view tab. Closing a view does not modify or delete
any of its content. To open a closed view, click Window (on Windows) or IBM Developer for z/OS (on
macOS) > Show View.
• To maximize the viewing area of a view, double-click its title. This action is especially useful for the z
Systems LPEX Editor and the Job Entry Subsystem (JES). To restore the viewing area to the original size,
double-click the view title again.
• You can access keyboard shortcuts for many menu items and window functions. Look for keyboard
shortcuts on menus. After you become more familiar with the user interface, you might find that you can
rely less on the mouse and use the keyboard for accomplishing more tasks:

Related concepts
“Key views” on page 33
Perspectives are composed of views. To understand how to work with views, you must first understand
the functions that are supported by each view.
“Navigating” on page 32
One of the first differences you might notice between IBM Developer for z/OS and ISPF is how you
navigate the product. You navigate ISPF by using the keyboard to type on panels and in the command line.

Getting started 35
 In Developer for z/OS you use a mouse to select menu items, controls, and items from lists and tables,
and you use the keyboard for typing text.

Resource management with property groups

Property groups are sets of property values that you define for z/OS procedures and data sets, libraries,
and compiler, link, Db2 bind, BMS/MFS, and HLASM assemble options. Property groups manage resource
properties. They can be shared among systems, projects, resources, and users.
Property groups are created and managed in the Property Group Manager. Figure 2 on page 36 shows a
portion of the property group that is associated with the COBOL sample that is supplied with the product.
At the bottom of the graphic, you can see the Property Group Manager view.
The properties within a property group depend on the type of resource for which the property group is
defined.

Figure 2. Property Group for the COBOL sample

Preparing to work
Before you can start working on files, you must connect to a z/OS system. This process entails two steps:
defining the connection and then establishing the connection.
If you define multiple connections to a single remote system and your site uses the push-to-client
function to distribute updates to remote system connections, then all connections to the remote system
are updated.

36 Developer for z/OS: Welcome and Getting Started

Connecting to a z/OS system
To access z/OS files from the Developer for z/OS client, you must define a connection to a z/OS system.
Define only one connection to a particular z/OS system in each workspace. If you define multiple
connections to a single z/OS system, and your site uses the push-to-client function to distribute updates
to z/OS system connections, then all connections to the z/OS system are updated. The Developer for z/OS
product does not support different configurations of the same z/OS system in a single workspace.
1. In the Remote Systems view, click Define a connection to a remote system and double-click
z/OS.
2. In the New Connection window, select z/OS and click Next.
Tip: If you are creating a connection for the first time, you are prompted to create a profile before you
can create the new connection. After you create the connection, you can share this profile to allow
other users to have this connection in their Remote Systems view.
3. Enter the following values in the fields on this window.
Host name
The TCP/IP address of the z/OS system.
Connection name
A name for the system, for example, new.zos.system.connection. This field defaults to the
host name.
Description
A description of the connection.
Verify host name
Select this checkbox to verify that the host name is valid before you connect.
4. To define the connection with default values, click Finish. To set properties for the connection, click
Next.
5. On the Connection Configuration page, specify these options:
• Daemon Port: Specify a valid port number. Consult your host system administrator for the port
number to use.
• Authentication method: Choose a method for authenticating with the z/OS system. Select userid/
password if you log on to the z/OS system by using a user ID and password. Select certificate
if you use client certificate authentication. Client certificate authentication is for users who must
connect to a z/OS system by using a device such as an integrated circuit card (like smart card). For
more information, see Creating a connection for client certificate authentication.
6. In the Remote Systems view, select a z/OS connection.
7. Right-click and select Connect.
8. On the Enter Password window, type your user ID and password.
Passwords are limited to 30 characters.
9. To save your user ID and password, select the Save user ID and Save password checkboxes.
Note: The Save password checkbox can be disabled. For more information, see
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDENY_PASSWORD_SAVE in the related topics.
10. Click OK.
If the remote system is configured to secure the connection with encrypted communication, the
Import Host Certificate window opens. This window opens the first time that you attempt to
connect to a remote system secured with encrypted communication. Subsequent connections use
the imported host certificate. When a remote system connection is secured, the Properties view for
the MVS Files subsystem displays SSL Enabled.
11. Click Finish to import the host certificate.
12. If the remote system is configured for push-to-client, you might be prompted to accept configuration
updates.

Getting started 37
 For more information about updating configurations and preferences, see the related links.
The Remote Systems view displays the short name of the new connection with five nodes under the
connection name:
• z/OS UNIX Files is the z/OS UNIX file subsystem. This node contains two folders: My home and Root.
You can create more z/OS UNIX file folders by adding new filters to this node.
• z/OS UNIX Shells is a command subsystem. When you open a z/OS UNIX command shell, its name is
displayed under this node.
• MVS Files is the MVS file subsystem. This node contains three folders: My Data Sets displays MVS
files that match the filter userid.* in which userid is the user ID with which you connected to the remote
system. You can create more MVS file folders by adding filters to this node. You can change the sort
order of data sets by using the MVS Files preference page. Retrieved Data Sets displays data set
names searched for and added by using the Retrieve Data Sets action or by allocating a data set. My
Favorites displays search queries that you ran and saved in the Remote z/OS Search view.
• TSO Commands is a command subsystem. When you open a TSO command shell, its name is displayed
under this node.
• JES is the JES subsystem. This node contains three folders: My Jobs displays jobs that are submitted
under the user ID with which you connected to the z/OS system. You can create more job folders by
adding new filters to this node. Retrieved Jobs displays jobs searched for and added by using the
Retrieve Job action. Active Jobs shows jobs that are running.
• Db2 for z/OS provides tools for connecting to Db2 databases and running and tuning SQL queries. For
more information about Db2 for z/OS tooling, see Developing with Db2 for z/OS.

After you connect to the remote system, you can control the contents that are displayed under JES, MVS
Files, and z/OS UNIX Files by defining filters for these subsystems. You can add search queries to the
MVS Files folder by running and saving remote z/OS searches. For instructions, see the related topics.
System administrators can configure remote systems to automatically disconnect users after a period
of inactivity. Contact your system administrator if you have any questions about maintaining an active
connection to a remote system.
Related tasks
Creating a connection for client certificate authentication
Updating workspace configurations and preferences

38 Developer for z/OS: Welcome and Getting Started

Related reference
RSE returns message RSEG1242 on connection attempt
Related information
Defining extra Java startup parameters with _RSE_JAVAOPTS

Connecting to a z/OS system

To access z/OS files from the Developer for z/OS client, you must define a connection to a z/OS system.
Define only one connection to a particular z/OS system in each workspace. If you define multiple
connections to a single z/OS system, and your site uses the push-to-client function to distribute updates
to z/OS system connections, then all connections to the z/OS system are updated. The Developer for z/OS
product does not support different configurations of the same z/OS system in a single workspace.
1. In the Remote Systems view, click Define a connection to a remote system and double-click
z/OS.
2. In the New Connection window, select z/OS and click Next.
Tip: If you are creating a connection for the first time, you are prompted to create a profile before you
can create the new connection. After you create the connection, you can share this profile to allow
other users to have this connection in their Remote Systems view.
3. Enter the following values in the fields on this window.
Host name
The TCP/IP address of the z/OS system.
Connection name
A name for the system, for example, new.zos.system.connection. This field defaults to the
host name.
Description
A description of the connection.
Verify host name
Select this checkbox to verify that the host name is valid before you connect.
4. To define the connection with default values, click Finish. To set properties for the connection, click
Next.
5. On the Connection Configuration page, specify these options:
• Daemon Port: Specify a valid port number. Consult your host system administrator for the port
number to use.
• Authentication method: Choose a method for authenticating with the z/OS system. Select userid/
password if you log on to the z/OS system by using a user ID and password. Select certificate
if you use client certificate authentication. Client certificate authentication is for users who must
connect to a z/OS system by using a device such as an integrated circuit card (like smart card). For
more information, see Creating a connection for client certificate authentication.
6. In the Remote Systems view, select a z/OS connection.
7. Right-click and select Connect.
8. On the Enter Password window, type your user ID and password.
Passwords are limited to 30 characters.
9. To save your user ID and password, select the Save user ID and Save password checkboxes.
Note: The Save password checkbox can be disabled. For more information, see
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDENY_PASSWORD_SAVE in the related topics.
10. Click OK.
If the remote system is configured to secure the connection with encrypted communication, the
Import Host Certificate window opens. This window opens the first time that you attempt to
connect to a remote system secured with encrypted communication. Subsequent connections use

Getting started 39
 the imported host certificate. When a remote system connection is secured, the Properties view for
the MVS Files subsystem displays SSL Enabled.
11. Click Finish to import the host certificate.
12. If the remote system is configured for push-to-client, you might be prompted to accept configuration
updates.
For more information about updating configurations and preferences, see the related links.
The Remote Systems view displays the short name of the new connection with five nodes under the
connection name:
• z/OS UNIX Files is the z/OS UNIX file subsystem. This node contains two folders: My home and Root.
You can create more z/OS UNIX file folders by adding new filters to this node.
• z/OS UNIX Shells is a command subsystem. When you open a z/OS UNIX command shell, its name is
displayed under this node.
• MVS Files is the MVS file subsystem. This node contains three folders: My Data Sets displays MVS
files that match the filter userid.* in which userid is the user ID with which you connected to the remote
system. You can create more MVS file folders by adding filters to this node. You can change the sort
order of data sets by using the MVS Files preference page. Retrieved Data Sets displays data set
names searched for and added by using the Retrieve Data Sets action or by allocating a data set. My
Favorites displays search queries that you ran and saved in the Remote z/OS Search view.
• TSO Commands is a command subsystem. When you open a TSO command shell, its name is displayed
under this node.
• JES is the JES subsystem. This node contains three folders: My Jobs displays jobs that are submitted
under the user ID with which you connected to the z/OS system. You can create more job folders by
adding new filters to this node. Retrieved Jobs displays jobs searched for and added by using the
Retrieve Job action. Active Jobs shows jobs that are running.
• Db2 for z/OS provides tools for connecting to Db2 databases and running and tuning SQL queries. For
more information about Db2 for z/OS tooling, see Developing with Db2 for z/OS.

After you connect to the remote system, you can control the contents that are displayed under JES, MVS
Files, and z/OS UNIX Files by defining filters for these subsystems. You can add search queries to the
MVS Files folder by running and saving remote z/OS searches. For instructions, see the related topics.
System administrators can configure remote systems to automatically disconnect users after a period

40 Developer for z/OS: Welcome and Getting Started

 of inactivity. Contact your system administrator if you have any questions about maintaining an active
connection to a remote system.
Related tasks
Creating a connection for client certificate authentication
Updating workspace configurations and preferences
Related reference
RSE returns message RSEG1242 on connection attempt
Related information
Defining extra Java startup parameters with _RSE_JAVAOPTS

File editors
The workstation provides several editors for source files and uses the file extension to associate editors
with files. Some editors are more robust than others and are limited to selected file extensions. You might
want to start with the z Systems LPEX Editor because it provides an easier skill transfer from ISPF.
The z Systems LPEX Editor can be used to edit COBOL, PL/I, Assembler, and JCL files. However, so that
you have some idea of the different editors, the following table shows the available editors and the type of
files that each editor opens.

Table 9. Editors
Editor File type
COBOL Editor COBOL
PL/I Editor PL/I
JCL Editor JCL
BMS Editor Basic mapping support (BMS) files
MFS Editor Message format service (MFS) files
z Systems Data Editor Queued sequential access method (QSAM) and
partitioned data set (PDS) files

Related concepts
Remote C/C++ Editor
Remote Makefile Editor
z Systems Data Editor
Related information
Getting started with the z Systems LPEX Editor

Introduction to the z Systems LPEX Editor

The z Systems LPEX Editor provides editing features and capabilities that are specific to the needs of z/OS
users.
Using the LPEX editor preference page, you can modify aspects of the editor. To make the editor behave
more like ISPF, you can associate the ISPF profile with the editor. Using the ISPF profile provides the
following familiar capabilities:
• Prefix area for ISPF prefix commands.
• Command line for ISPF line commands.
The ISPF profile supports most, but not all, commands available in ISPF.
Related tasks
“Setting the ISPF profile preference” on page 42

Getting started 41
 The z Systems LPEX Editor can be set up to behave more like ISPF with a selected set of ISPF commands.
Related information
Getting started with the z Systems LPEX Editor

Setting the ISPF profile preference

The z Systems LPEX Editor can be set up to behave more like ISPF with a selected set of ISPF commands.
1. In the left pane of the Preferences window, click LPEX Editor.
2. In the Editor Profile field, click ispf.
3. Click OK.
Related concepts
Setting z Systems LPEX Editor preferences

Terminology differences for ISPF users

On the ISPF editor, commands that are used in the prefix area are referred to as line commands.
Commands that are used on the command line are referred to as primary commands. In the z Systems
LPEX editor, however, the commands that are used in the prefix area are referred to as the prefix
commands, while the commands that are used on the command line are referred to as line commands.
Prefix command area
Prefix commands can be typed in the prefix area in the editor. These commands apply only to the
line or lines that they are typed on. To access the prefix area, make sure that the prefix area option is
enabled. To verify this option, open the Preferences window and select LPEX Editor > Controls.
Line command area
Press the Esc key anywhere on the editor to position the cursor at the beginning of the command
window. Type the command on the window and then press the Enter key to apply the command.
Related concepts
“Introduction to the z Systems LPEX Editor” on page 41
The z Systems LPEX Editor provides editing features and capabilities that are specific to the needs of z/OS
users.
“Productivity features” on page 42
A number of features in the workbench and z Systems LPEX Editor enhance your ability to work with files.

Productivity features
A number of features in the workbench and z Systems LPEX Editor enhance your ability to work with files.

Viewing files
Filter view
Displays only selected sections of a file such as Comments, Divisions, and Errors. To return from the
filter view, click Show all to display the full the content.

42 Developer for z/OS: Welcome and Getting Started

Multiple views of a file
To open multiple views of the same file, from the editor menu, click View > Open new view.

Compare files
To compare two files, hold down the Ctrl key, and select them in the Remote Systems view. Then,
click Compare With > Each Other. Double-click the title of the editor to maximize the view, if
necessary.

Content assist
Content assist helps you insert or finish a line of code in the editor.
To open content assist, place the cursor in the source, and press Ctrl+Spacebar. A list of valid keywords
and identifiers is displayed. You can then select a syntax element. If you select fully qualified verb
constructs, content assist shows the variable definition and source.

Color
Default color settings for the z Systems LPEX Editor help you quickly identify various parts of the source.
You can customize the colors in the LPEX Editor preferences. This list indicates default color settings:
• Keywords are blue.

Getting started 43
 • Identifiers such as variables, paragraph names, and section names are black.
• Literals are maroon.
• Comments are green.
• COBOL sequence numbers are green.

Customizing the z Systems LPEX Editor

The LPEX Editor in IBM Developer for z/OS can be customized. You can use options that are found
under the LPEX Editor preferences to customize standard editor options such as appearance, saving, and
printing.
In the left pane of the Preferences window, select LPEX Editor > z Systems LPEX Editor, and then
choose the preference you want to work with. For example, to change the LPEX incremental find function,
select Find Text in the navigation pane, and then select the Incremental find dialog preference.

Related concepts
Setting z System LPEX Editor preferences

ISPF profile
You can edit text in the z Systems LPEX Editor several ways, depending on the preference that is selected
for the editor profile.
If the profile is set to ispf, you can use ISPF commands in the prefix area as in the ISPF Editor.

44 Developer for z/OS: Welcome and Getting Started

Table 10. Other prefix commands
Function Command
Copy or move after a line a
Copy or move before a line b
Copy c
Delete a line d
Display the excluded line f
Insert a new line i
Display the last excluded line l
Move m
Overlay o
Repeat r

Table 11. Prefix commands for a block of lines

Function Command
Block data shift left <<
Block data shift right >>
Block column shift left ((
Block column shift right ))
Copy a block cc
Delete a block dd
Overlay a block oo
Repeat a block rr
Exclude a block xx
Convert the case of a block lcc and ucc

Related concepts
“Introduction to the z Systems LPEX Editor” on page 41
The z Systems LPEX Editor provides editing features and capabilities that are specific to the needs of z/OS
users.
“Productivity features” on page 42
A number of features in the workbench and z Systems LPEX Editor enhance your ability to work with files.

z Systems LPEX Editor keyboard shortcuts

For most z Systems LPEX Editor functions, keyboard shortcuts on Windows and macOS are available.
Many of these keyboard shortcuts have functions that are equivalent to ISPF Editor function keys.
You can click Help > Show Active Keybindings on the menu bar to access a list of the available shortcut
keys. You can also press Ctrl+Shift+L (on Windows) or +Shift+L (on macOS).

Getting started 45
Quick tasks
This topic describes some common tasks that you might perform with IBM Developer for z/OS and links
you to more information about completing them.
The tasks illustrated in this topic are representative of the kinds of tasks that developers commonly
perform with IBM Developer for z/OS. It is not an exhaustive list of the tasks that you can perform with
the product, but a sampling that can help you become productive with the product more quickly. For each
task included in the list at the end of this topic, the task topic provides the following information about
completing that task:
• A summary of the steps involved in completing the task.
• Links to help topics that provide instructions for each step.
• Links to tutorials, where available.
• Links to online demonstrations, where available. The links to the demonstrations indicate the version of
IBM Developer for z/OS in which the demonstration was created.
The list at the end of this topic shows all quick tasks in alphabetical order by task name, but you can also
see a list of tasks organized by component name (such as Enterprise Service Tools or z/OS Integrated
Development Environment) in the following link:
“Quick tasks by component” on page 46

Quick tasks by component

This topic lists all quick task topics organized by Developer for z/OS component.

All Components
These tasks are not specific to a component.
“Preferences” on page 74

BMS Map Editor

“Creating BMS maps” on page 50

Enterprise Service Tools

CICS environment
“Enabling a CICS COBOL program as an MTOM/XOP Web service” on page 62
“Generating a batch outbound driver (meet-in-the-middle scenario)” on page 63
“Generating a CICS service provider from a Web service description (top-down scenario)” on page
65
“Generating a single Web service (bottom-up scenario)” on page 69
IMS Environment
“Generating an IMS SOAP Gateway Web service provider” on page 66
“Generating an IMS SOAP Gateway Web service requester” on page 68

Menu Manager
“Creating menus and menu actions” on page 53

MFS Editor
“Creating MFS message definitions” on page 54

46 Developer for z/OS: Welcome and Getting Started

 z Systems Code Generators
“Creating COBOL programs from templates and snippets” on page 51

z/OS Debugger
Preparing to debug

z/OS Integrated Development Environment

“Changing a high-level qualifier” on page 47
“Connecting to a remote system” on page 48
“Creating reusable z/OS search queries” on page 56
“Editing and compiling code on a local system” on page 57
“Editing and compiling code on a remote system” on page 59
“Editing files with the z Systems LPEX Editor” on page 60
“Managing properties with property groups” on page 71
“Navigating partitioned data sets” on page 72
“Setting up tracing” on page 75

Changing a high-level qualifier

This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.

Summary
To change the high-level qualifier (HLQ) of a z/OS project:
1. Import a z/OS project.
2. Specify the location of the source file to be imported.
3. Select and modify the HLQ for the subprojects that are to be imported.

Help topics
The following help topics provide more information about changing the high-level qualifier of a z/OS
project:
• Importing a z/OS project
• Exporting a z/OS project
• Changing the high-level qualifier of an MVS subproject
Related information
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries

Getting started 47
 This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Connecting to a remote system

This topic illustrates how to create a connection to a remote system and create filters to view data sets.

Summary
One of the first tasks that you need to complete in Developer for z/OS is to create a connection to a
remote z/OS system so that you can see and work with z/OS files in your workspace. This topic includes
links to documentation, tutorials, and demonstrations for the following tasks:
• Creating a connection to a remote system.
• Creating filters to view your data sets.
• Troubleshooting remote connections.

48 Developer for z/OS: Welcome and Getting Started

Help topics
The following help topics provide more information about connecting to remote systems:
• Creating a new connection to a remote system
• Connecting to a remote system
• Creating a connection using client certificate authentication
• Creating a filter for MVS Files
• Creating a filter for a JES subsystem
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups

Getting started 49
 This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Creating BMS maps

This topic illustrates the BMS map editing support available in Developer for z/OS.

Summary
To use the Developer for z/OS BMS map editing support:
1. Create a new BMS map.
2. Edit the BMS map.
3. Generate the JCL for the assemble link.

Help topics
The following help topics provide more information about BMS map editing support:
• Creating a new BMS map set
• Creating BMS map set JCL

Tutorials and samples

BMS tutorial
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system

50 Developer for z/OS: Welcome and Getting Started

 This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Creating COBOL programs from templates and snippets

This topic illustrates how to create COBOL programs from templates and snippets.

Summary
To create a COBOL program from templates and snippets:
1. Create a new COBOL program using predefined templates.
2. Customize features for these templates.
3. Reuse code snippets by leveraging the Snippets view.

Help topics
The following help topics provide more information about customizable templates and snippets:
• Creating COBOL programs from a template
• Preferences for COBOL code templates
• Preferences for COBOL features
• Editing with snippets
Related information
Changing a high-level qualifier

Getting started 51
 This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing

52 Developer for z/OS: Welcome and Getting Started

 This topic illustrates how to set up tracing.

Creating menus and menu actions

This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.

Summary
Developer for z/OS includes a tool called Menu Manager that you can use to create your own menu
actions and add them to pop-up menus in the z/OS Projects view and the z Systems LPEX editor. Creating
custom actions and adding them to a pop-up menu involves the following tasks:
1. Creating actions for use on the z/OS Projects view and on the z Systems LPEX editor.
2. Creating a menu to organize the actions.
3. Customizing the output options.

Help topics
The following help topics provide more information about creating menus and menu actions:
• Creating custom pop-up menus
• Creating a new action
• Creating a new custom menu
• Creating menu actions for z/OS actions and variables

Tutorials and samples

• Submit JCL with Dynamic Variable Substitution
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service

Getting started 53
 This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Creating MFS message definitions

This topic illustrates the MFS editing support available in Developer for z/OS.

Summary
To use the Developer for z/OS MFS editing support:
1. Create an MFS device format.
2. Edit the device format definition.
3. Customize the MFS preferences.
4. Create an MFS message definition.
5. Generate JCL to run MFS.

Help topics
The following help topics provide more information about MFS map editing support:
• Creating a new device format definition
• Editor features
• Preferences
• Creating a new MFS message definition
• JCL generation
Related information
Changing a high-level qualifier

54 Developer for z/OS: Welcome and Getting Started

This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing

Getting started 55
 This topic illustrates how to set up tracing.

Creating reusable z/OS search queries

This topic illustrates how to save and reuse frequently performed z/OS searches.

Summary
You can use the My Search Queries function of RSE to save and reuse your frequently performed remote
z/OS searches.
1. Perform a remote z/OS search.
2. Add the search results to My Search Queries
3. Rerun the query as needed.
4. Modify the search query as needed.
5. Work with the search results.

Help topics
The following help topics provide more information about creating reusable z/OS search queries:
• Searching a remote z/OS system
• Saving search queries (also includes instructions for running and editing saved queries)
• Working with search results
• Using remote index search
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service

56 Developer for z/OS: Welcome and Getting Started

 This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Editing and compiling code on a local system

This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.

Summary
To edit and compile code on a local system, you need to complete the following tasks:
1. Create a local z/OS project.
2. Create a property group and associate it with your project.
3. Create a new source file or copy an existing file into the new project.
4. Edit your source code.
5. Build the local project.

Help topics
The following help topics explain how to complete these steps:
• Creating a local z/OS project
• Creating a local z/OS project from a sample
• Creating and editing property groups
• Associating and overriding property groups
• A Quick Start Guide for the z Systems LPEX Editor
Related information
Changing a high-level qualifier

Getting started 57
 This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing

58 Developer for z/OS: Welcome and Getting Started

 This topic illustrates how to set up tracing.

Editing and compiling code on a remote system

This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.

Summary
To edit and compile code on a remote system, you need to complete the following tasks:
1. Create a connection to a remote system.
2. Create a property group and associate it with your MVS files.
3. Define filters so that you can see your data sets.
4. Allocate a new data set.
5. Edit your source code.
6. Generate JCL to compile your program.
7. Submit the job and view the output on JES.

Help topics
The following help topics explain how to complete these steps:
• Creating a new connection to a remote system
• Connecting to a remote system
• Creating and editing property groups
• Associating and overriding property groups
• Defining a filter for MVS files
• Allocating a new data set
• Editing a sequential data set or PDS member
• A Quick Start Guide for the z Systems LPEX Editor
• Generating JCL, submitting a job, and viewing the output

Sample
Running a simple COBOL application on a remote system
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions

Getting started 59
 This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Editing files with the z Systems LPEX Editor

Use the z Systems LPEX editor to edit remote files.

Summary
To use the z Systems LPEX editor to edit remote files:
• To open the LPEX editor, click the name of a COBOL or PL/I file.
• To enter text into a file, click in the working area of the editor and begin typing.
• To type on the command line, click in the command-line area or press the Esc key and begin typing.
• To toggle back and forth between insert mode and replace mode, press the Insert key.
• To delete text, use the Delete key or the Backspace key.
• To insert a blank line, press Enter at the end of a line or Ctrl+Enter anywhere on a line.

60 Developer for z/OS: Welcome and Getting Started

Help topics
The following help topics provide more information about editing with the z Systems LPEX editor:
• A Quick Start Guide for the z Systems LPEX Editor
• Setting preferences for the z Systems LPEX Editor
• Using content assist
• Key settings in the ISPF editor profile
• Real-time syntax checking of PL/I files
• z Systems LPEX commands
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)

Getting started 61
 This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Enabling a CICS COBOL program as an MTOM/XOP Web service

This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.

Summary
To enable a CICS COBOL program as an MTOM/XOP Web service:
1. Create a provider-mode pipeline configuration file that includes the CICS-supplied MTOM/XOP
handler.
2. Enable your CICS program as an MTOM/XOP Web service.
3. Deploy the MTOM/XOP Web service to CICS.
4. Invoke the MTOM/XOP Web service from a Java, J2C, MTOM/XOP, SOAP client. (For guidance, see the
demonstration, "Part 2 - Invoke MTOM/XOP Web services from a Java, J2C, MTOM/XOP, SOAP client in
WebSphere Application Server" at he bottom of this page.)

Help topics
The following help topics provide more information about MTOM/XOP Web services:
• Generate CICS MTOM/XOP Web service (bottom-up)
• Bottom-up wizard - MTOM/XOP files - Interpretive XML Conversion
• Web services for CICS project
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug

62 Developer for z/OS: Welcome and Getting Started

 Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Generating a batch outbound driver (meet-in-the-middle scenario)

This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."

Summary
To generate an outbound COBOL driver running in batch mode using Enterprise Service Tools:
1. Create a z/OS project and import source files for the project.
2. Use the New XML to COBOL Mapping wizard to map the data structure of the schema to the COBOL
copybook.
3. Edit the mapping file to specify how to map the data structures.
4. Generate the outbound converter from the mapping file.

Help topics
The following help topics provide more information about generating an outbound COBOL driver:
• Creating an Eclipse project
• Copying source files into a project using the Navigator view

Getting started 63
 • Map to an Existing Service Interface (meet-in-middle) wizard
• Using the mapping editor to create data mappings in a mapping session file
• XML to COBOL mapping concepts
• Generate Web services files
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences

64 Developer for z/OS: Welcome and Getting Started

 Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Generating a CICS service provider from a Web service description (top-

down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).

Summary
To generate a new CICS COBOL service provider from an existing Web service description:
1. Connect to a z/OS system.
2. Define a CICS connection.
3. Create a new Web Services for CICS project and import the WSDL file you want to generate the service
from.
4. Generate the Web service from the WSDL file.
5. Complete the coding of the program to implement the service.
6. Copy the COBOL source and the copybooks to the remote system.
7. Deploy the service to CICS.
8. Test the Web service using the Web Services Explorer.

Help topics
The following help topics provide more information about generating CICS service providers:
• Connecting to a remote system
• Web services for CICS project
• Create New Service Implementation (top-down) wizard
• Copying remote files
• Building a z/OS project or subproject
• Deploying the Web service artifacts to CICS
• Web Services Explorer
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions

Getting started 65
 This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Generating an IMS SOAP Gateway Web service provider

This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.

Summary
To generate artifacts for IMS Connect and IMS SOAP Gateway to expose an existing IMS application as a
Web service provider:
1. Create a new IMS SOAP Gateway project.
2. Import source files into the project.
3. Generate the Web service.
4. Copy the XML converter to the remote system for compiling and link-editing.

66 Developer for z/OS: Welcome and Getting Started

Help topics
The following help topics provide more information about generating an IMS SOAP Gateway Web service
provider:
• Enabling an application for the IMS SOAP Gateway
• IMS SOAP Gateway project
• Creating a new single-service project
• Importing source files into a single-service project
• Generating Web service files from the IMS application
• Copying remote files
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)

Getting started 67
 This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Generating an IMS SOAP Gateway Web service requester

This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.

Summary
To generate a Web service requester to support the IMS SOAP Gateway Callout feature:
1. Create a new IMS SOAP Gateway project.
2. Ensure that you have the following required files in the project:
• The Web service description (WSDL) of the service you want to invoke
• The COBOL copybook to hold the request and response data
3. Create request and response mappings for the callout scenario.
4. Generate a Callout XML converter.
5. Copy the XML converter to the remote system for compiling and link-editing.

Help topics
The following help topics provide more information about generating an IMS SOAP Gateway Web service
requester:
• Enabling an application for the IMS SOAP Gateway
• IMS SOAP Gateway project
• Starting the XML to COBOL Mapping wizard (response mapping)
• Starting the XML to COBOL Mapping wizard (request mapping)
• Generating Web services files
• Copying remote files
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions

68 Developer for z/OS: Welcome and Getting Started

 This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Generating a single Web service (bottom-up scenario)

This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.

Summary
To generate a single Web service for a COBOL program and deploy it to CICS:
1. Create a "Web services for CICS" project.
2. Use the single-service wizard to generate converters, the WSBind file, and the WSDL file from the
COBOL program.
3. Use RSE to copy the generated artifacts to the MVS and the z/OS UNIX Files subsystem.
4. Create a z/OS project and MVS subproject and use the zIDE to build the converter program.

Getting started 69
 5. Use Remote Connection Emulator to install the WSBind file and the WSDL file.

Help topics
The following help topics provide more information about generating and deploying Web services:
• About single-service projects
• Creating a new single-service project
• Create New Service Interface (bottom-up) wizards
• Copying remote files
• Creating a z/OS project
• Creating an MVS subproject
• Adding a remote file to an MVS subproject
• Building a z/OS project or subproject
• Using the Remote Connection Emulator

Tutorials and samples

The CICS catalog manager example application
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)

70 Developer for z/OS: Welcome and Getting Started

 This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Managing properties with property groups

This topic illustrates how to create property groups and associate them with resources.

Summary
To create a property group and associate it with a resource:
1. Connect to a remote system.
2. Open the Property Group Manager.
3. Select a connected remote system and create a new property group for it.
4. Add property values to the group and save the group.
5. Select the resource you want to assign the properties to and associate the group with the resource.

Help topics
The following help topics provide more information about property groups:
• Connecting to a remote system
• Managing resource properties with property groups
• Creating and editing property groups
• Associating and overriding property groups
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets

Getting started 71
 This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing
This topic illustrates how to set up tracing.

Navigating partitioned data sets

This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.

Help topics
The following help topics provide more information about using the PDS navigation mechanism and
Locate command:
• Working with large partitioned data sets

72 Developer for z/OS: Welcome and Getting Started

• Setting preferences for MVS Files subsystems
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
Setting up tracing

Getting started 73
 This topic illustrates how to set up tracing.

Preferences
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.
To open the Preferences window:
• Windows: From the main menu, select Window > Preferences.
• macOS: From the main menu, select IBM Developer for z/OS > Preferences.
• From an editor: Right-click and select Preferences.
Some product user interface windows also provide a link to the Preferences window. You can click this
link to open the Preferences.
To navigate in the Preferences window, you can expand and collapse preference categories. For example,
to navigate to the Formatter preference page of the PL/I Editor, expand PL/I > Editor and select
Formatter.
For more information about setting preferences for specific components, see the related topics.
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)

74 Developer for z/OS: Welcome and Getting Started

 This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Setting up tracing
This topic illustrates how to set up tracing.
Eclipse workbench preferences
BMS Map Editor Preferences
CARMA preferences
Setting COBOL Editor preferences
Debug Preferences
Enterprise Service Tools preferences
JCL Editor preferences
JES subsystem preferences
MFS Editor preferences
Setting PL/I Editor preferences
Pushing configurations and preferences to client workstations
z/OS Integrated Development Environment (zIDE) preferences
Setting z Systems preferences
Setting z Systems LPEX Editor preferences
z/OS solutions preferences

Setting up tracing
This topic illustrates how to set up tracing.

Summary
You can set varying tracing levels for specific Developer for z/OS components. During execution, trace
entries are produced and placed in the workspace\.metadata\.trace file. A trace shows the flow of the
execution of a program and can help with troubleshooting and debugging problems.
• Open the Preferences page for Developer for z/OS and navigate to Tracing.
• Locate the component for which you need to set up tracing and set the appropriate level of tracing.
• When tracing is complete, restore the default tracing settings.

Help topics
The following help topics provide more information about tracing:
• Tracing
• Tracing tab

Getting started 75
 • Troubleshooting and support for Developer for z/OS
Related information
Changing a high-level qualifier
This topic illustrates how to change the high-level qualifier of z/OS MVS subprojects when importing and
exporting projects.
Connecting to a remote system
This topic illustrates how to create a connection to a remote system and create filters to view data sets.
Creating BMS maps
This topic illustrates the BMS map editing support available in Developer for z/OS.
Creating COBOL programs from templates and snippets
This topic illustrates how to create COBOL programs from templates and snippets.
Creating menus and menu actions
This topic illustrates how to create custom menus and menu actions for the z/OS Projects view and the z
Systems LPEX editor.
Creating MFS message definitions
This topic illustrates the MFS editing support available in Developer for z/OS.
Creating reusable z/OS search queries
This topic illustrates how to save and reuse frequently performed z/OS searches.
Preparing to debug
Editing and compiling code on a local system
This topic illustrates the Developer for z/OS tools for editing and compiling source code on a local
(workstation) system.
Editing and compiling code on a remote system
This topic illustrates the Developer for z/OS tools for connecting to a remote z/OS system, allocating a
data set, and editing and compiling source code.
Editing files with the z Systems LPEX Editor
Use the z Systems LPEX editor to edit remote files.
Enabling a CICS COBOL program as an MTOM/XOP Web service
This topic illustrates how to enable a CICS COBOL program as an MTOM/XOP Web service.
Generating a batch outbound driver (meet-in-the-middle scenario)
This topic illustrates how to generate an outbound COBOL driver running in batch mode using Enterprise
Service Tools. This task is called "meet-in-the-middle."
Generating a CICS service provider from a Web service description (top-down scenario)
This topic illustrates how to generate a new CICS COBOL service provider from an existing Web service
description (WSDL).
Generating an IMS SOAP Gateway Web service provider
This topic illustrates how to generate artifacts for IMS Connect and IMS SOAP Gateway to expose an
existing IMS application as a Web service provider.
Generating an IMS SOAP Gateway Web service requester
This topic illustrates how to generate a Web service requester to support the IMS SOAP Gateway Callout
feature.
Generating a single Web service (bottom-up scenario)
This topic illustrates how to generate a single Web service for a COBOL program and deploy it to CICS.
Managing properties with property groups
This topic illustrates how to create property groups and associate them with resources.
Navigating partitioned data sets
This topic illustrates how to navigate a partitioned data set using the new PDS navigation mechanism.
Preferences

76 Developer for z/OS: Welcome and Getting Started

 Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.

Tutorials
Complete tutorials with specific learning objectives for the product.

Eclipse workbench basic tutorial

IBM Developer for z/OS is built on the Eclipse platform. The Eclipse documentation included in this IBM
Documentation includes a basic workbench tutorial. For an introductory tutorial that guides you through
workbench basics, see Basic tutorial.

Getting started with z/OS application development

Learn the steps for building and debugging a COBOL application by using the Global Auto Mart (GAM)
sample. Compile and build a program that searches a database for the make and model of a car.
Learning objectives
Learn how to do the following tasks:
• Create a connection to a z/OS system
• Use repositories
• Create z/OS projects on the local system
• Create MVS subprojects
• Add remote files to subprojects
• Create, modify, and apply property groups
• Assemble, link, compile, and debug COBOL source code
Time required
Approximately 2 hours and 10 minutes.

Load the Global Auto Mart source files

Learn how to create a connection to a z/OS remote system, allocate partitioned data sets, and load the
source files into the data sets.
Learning objectives
In this module, you learn how to use the Developer for z/OS product to do these tasks:
• Create a connection to a remote z/OS system
• Create partitioned data sets on the remote system
• Transfer source files from the workstation to the remote system
Time required
60 minutes
Prerequisites
To complete this module, you must have the following items:
• The Developer for z/OS client that is installed on your local workstation
• Access and permission to connect to a remote system that runs z/OS
• For the “Create database tables ” on page 81 lesson, permission to create and modify database
tables on the remote system

Open the Global Auto Mart source files

Learn how to open the source files for the Global Auto Mart sample application, which is shipped with
Developer for z/OS.
To open the Global Auto Mart source files:

Getting started 77
 1. Start Developer for z/OS.
2. From the main menu, select Window (on Windows) or IBM Developer for z/OS (on macOS) >
Perspective > Open Perspective > z/OS Projects.
3. To open the Global Auto Mart sample, click File > New > Example. The New Example wizard opens.
4. Expand Workstation Global Auto Mart Samples, select Global Auto Mart COBOL Sample, and click
Next.
5. In the Project name field, type GlobalAutoMart and click Finish. The project is added to the z/OS
Projects view.

Create a connection to the remote system and partitioned data sets

Before you can build the project, you must create partitioned data sets on the remote system. These data
sets are where the source and files are generated when you assemble, link, and compile the source.
You must know the IP address or name of the remote system and have permission to access it.
To create a connection to the remote system and partitioned data sets:
1. Create and connect to a z/OS connection. For more information about creating a z/OS connection, see
Connecting to a z/OS system.
2. Allocate the following partitioned data sets. Specify your user ID for <HLQ>.
• <HLQ>.AUTOMART.ASSEMBLE for Assembler source files.
• <HLQ>.AUTOMART.CNTL for shipped and generated JCL.
• <HLQ>.AUTOMART.COBOL for COBOL source files.
• <HLQ>.AUTOMART.LISTING for compiler listing output files.
• <HLQ>.COBOL.COPYLIB* for copybooks.
• <HLQ>.COBOL.SYSDEBUG* for debugger output files.
• <HLQ>.ASMOBJS.OBJ* for Assembler object deck files.
• <HLQ>.COBOBJS.OBJ* for COBOL object deck files.
• <HLQ>.DB2DBRM* the database request module location.
• <HLQ>.LOAD* the load module location.
These partitioned data sets store both source files and files that are generated during assembling,
linking, and compiling. If you have questions about the data set characteristics to assign to each
partitioned data set, contact your systems administrator. Data set names that are flagged with * are
the default data set names that are specified in a property group when you create it. If your site
follows a different naming convention, allocate data sets with names that follow the convention, and
be sure to update the property group to follow the convention.
On the remote system, the partitioned data sets are added to the MVS Files > Retrieved Data Sets folder.
This folder is usually referred to as a filter, because it shows only the most recently allocated data sets on
the remote system that use your user ID as the high-level qualifier.

78 Developer for z/OS: Welcome and Getting Started

Upload local source files to the remote system
Now that you created partitioned data sets, you can upload the files that are on the local workstation to
the remote system. There are several ways to transfer your local project files to the remote system; this
lesson describes a copy/paste approach.
You must be connected to the remote system.
To upload your local source files to the remote system:
1. In the z/OS Projects view, expand GlobalAutoMart > GAM_COBOL > COBOLBMS.
2. Select all the BMS files, right-click, and click Copy.
3. In the Remote Systems view, select the remote system and expand MVS Files > My Data Sets.
4. Right-click the <HLQ>.AUTOMART.ASSEMBLE partitioned data set name and click Paste. The files
from the local workstation are stored in the remote partitioned data set. Alternatively, you can select
the BMS files from the local project, and drag them into the <HLQ>.AUTOMART.ASSEMBLE partitioned
data set.
5. Copy the files from the COPYBOOK folder of the GlobalAutoMart project into the
<HLQ>.COBOL.COPYLIB partitioned data set.
6. Copy the files from the GAMOVDB, GAMOVII, GAMOVMI, GAMOVMM, and GAMOVSI folders of the
GlobalAutoMart project into the <HLQ>.AUTOMART.COBOL partitioned data set.
7. Copy the files from the JCL folder of the GlobalAutoMart project into the <HLQ>.AUTOMART.CNTL
partitioned data set.
When you finish copying and pasting, all of the local source files available are displayed on the remote
system.

Getting started 79
80 Developer for z/OS: Welcome and Getting Started
Create database tables
Learn how to create the database tables on the remote system. You must have special privileges to
be able to create and modify database tables on the remote system, so check with your systems
administrator before beginning.
This lesson assumes that you have a solid understanding of COBOL, JCL, and compilation.
The GAM0VDB.cbl file inserts data into the Global Auto Mart sample database tables. To create the
database tables that are needed for the Global Auto Mart tutorial:
1. Compile the GAM0VDB.cbl file with the following provided copybooks: GAM0BCD, GAM0BDD, GAM0BED,
GAM0BMD and GAM0BPD.
2. Edit <HLQ>.AUTOMART.CNTL(GAM0VCDB), and provide the database schema name by changing all
instances of &SCHEMA to match the schema name you want to use. If you do not know which schema
name to use, ask your systems administrator.
3. Submit the GAM0VCDB JCL file to run GAMOVDB. If the required tables exist, the JCL drops them. If the
tables do not exist, it creates them. The JCL then runs GAM0VDB to populate the tables.

Set up a z/OS project

Learn how to create a property group, create a z/OS project and MVS subproject, and add resources to the
subproject.
Learning objectives
After completing the lessons in this module you will know understand the concepts and know how to
do the following:
• Create a property group
• Create a z/OS project and MVS subproject
• Add files from the remote system to the MVS subproject
• Create additional subprojects and add resources to them.
Time required
30 minutes

Create a property group

A property group is a set of resource values that allows easy sharing and management of build properties
and settings. Learn how to create a property group to apply to z/OS resources.
1. Open the z/OS Projects perspective. The Property Group Manager is one of the views in the z/OS
Projects perspective.
2. Contact your system administrator for the location on the remote system of these resources:
• Macro libraries
• CICS load libraries
• CICS copy libraries where the COBOL DFHAID can be found
• SQLCA copy library, if it is not a file to which the procedures already point
• Any additional link libraries that are needed for the project and debugging
3. In the Property Group Manager, right-click the remote system you are connected to and select New
Property Group. The property group editor opens.
4. In the Name field, type AUTOMART.
5. In the Description field, type Property group for Global Auto Mart sample. The
property group editor has a series of tabs along the bottom. Most of these tabs have a navigation

Getting started 81
 pane on the left side that you can use to select a specific page in the property group editor.

6. Select the tabs and pages listed in this table to set property values in the AUTOMART property group.
Many of the fields provide default values. Unless the table specifies otherwise, you can use the default
values in the property group with the Global Auto Mart sample programs.

Table 12. Property values for the AUTOMART property group

Tab Page Field Value
JCL JCL job card Specify the JCL that is required for compiling on the
remote system. For more information, contact your
systems administrator.
Data set for <HLQ>.AUTOMART.CNTL
generated JCL
COBOL Runtime Runtime Select Db2 and CICS. Select the version of CICS in
Environments Environments use at your site.
Procedures and Procedure and Expand the ELAXFCOC procedure and select the
Steps step table COBOL step name.
Listing output <HLQ>.AUTOMART.LISTING
data set
SYSLIB Leave <HLQ>.COBOL.COPYLIB in the field and add the
CICS copy library that contains the COBOL DFHAID
member and the COBOL copy library that contains the
SQLCA member.

82 Developer for z/OS: Welcome and Getting Started

 Table 12. Property values for the AUTOMART property group (continued)
Tab Page Field Value
SYSTSIN Use the instructions in the comments of this field
instructions to customize the code. Work with the database
administrator to determine the best method for
binding the module to a database package and access
plan. You can either include the JCL inline or use a
bind file. If you are using a bind file, create the bind
file in a bind PDS. If the Bind Procedure needs a
STEPLIB data set, it can be added to the top of the
SYSTSIN instructions as demonstrated in the sample
JCL.
Link Procedures and Procedure and Expand the ELAXFLNK procedure and select the LINK
Steps step table step name.
Link libraries Specify any link libraries that are needed for the
project and for debugging. For more information, see
your systems administrator.
Load module Leave <HLQ>.LOAD in the field and add the load
location library that CICS uses. For more information, see your
systems administrator.
Assem Procedures and Procedure and Expand the ELAXFASM procedure and select the ASM
bler Steps step table step name.
Assembler SYSPARM(DSECT),NOOBJECT,DECK
options
Listing output <HLQ>.AUTOMART.LISTING
data set
Macro libraries Leave the default values in place and add the location
of the remote system macro libraries partitioned data
sets and the partitioned data set containing the CICS®
macros. Separate multiple entries with spaces.
Support error Clear this checkbox.
feedback

Additional JCL //SYSPUNCH DD

DISP=SHR,DSN=&HLQ..COBOL.COPYLIB(&MEM.)

The &HLQ. and &MEM. variables in this JCL statement

are replaced with the high-level qualifier and the
member name of the selected BMS map file when you
assemble the BMS maps in the subproject.
7. Close the property group editor and save the changes.
8. In the Property Group Manager, expand the remote system. The property group that you created is
listed among the property groups that are associated with that particular remote system. If you had
trouble with this lesson or would like to learn more about property groups, read the information in
Managing resource properties with property groups.

Getting started 83
 Create a z/OS project and MVS subproject
Creating z/OS projects and subprojects provides a way to organize your remote files on your local
workstation. Learn how to set up a z/OS project and subproject for this tutorial.
1. To open the z/OS Projects view from the main menu, select Window (on Windows) or IBM Developer
for z/OS (on macOS) > Perspective > Open Perspective > z/OS Projects. If z/OS Projects it is not
one of the first options shown, you might have to select Other, scroll down, and then select z/OS
Projects.
2. Right-click the z/OS Projects view, and then select New > z/OS Project.
3. In the Project name field, type zOS Global Auto Mart.
4. Select Create an MVS subproject and then click Finish. The New MVS Subproject window opens.
5. Complete the fields on this window as shown in the following screen capture:
• Connection name: Select the remote system to which you uploaded the Global Auto Mart source
files.
• Project name: Contains the name of the z/OS project.
• Subproject name: Type GAM0MC1.
• High-level qualifier: Contains your z/OS logon ID.
• Runtime environment: Select Any.
• Select and add resources to the subproject: Select this checkbox.
• Property Group: Click Select a property group to associate with the subproject, and then select
the AUTOMART property group.

84 Developer for z/OS: Welcome and Getting Started

6. Click Finish. The Add Resources to Subproject window opens.
7. Select <HLQ>.AUTOMART.ASSEMBLE(GAM0MC1.asm).
8. Click OK. The z/OS Projects view is updated with the project, the subproject, and the data set
member.

Getting started 85
 Create additional subprojects
One function of subprojects is to represent the resources required to build a particular load module.
Because the Global Auto Mart project contains more than one load module, you must create one
subproject for each load module
1. Select the zOS Global Auto Mart project, and then right-click and select New > MVS Subproject. The
New MVS Subproject window opens.
2. Complete the fields on this window as follows:
• Connection name: Select the remote system to which you uploaded the Global Auto Mart source
files.
• Project name: Contains the name of the z/OS project.
• Subproject name: Type GAM0MC2.
• High-level qualifier: Contains your z/OS logon ID.
• Runtime environment: Select Any.
• Select and add resources to the subproject: Select this checkbox.
• Property Group: Click Select a property group to associate with the subproject, and then select
the AUTOMART property group.
3. Click Finish. The Add Resources to Subproject window opens.
4. Select <HLQ>.AUTOMART.ASSEMBLE(GAM0MC2.asm).
5. Click OK. The z/OS Projects view is updated with the subproject and the data set member.
6. Repeat this procedure to create subprojects for the following source programs. Associate the
AUTOMART property group with each subproject.

MVS Subproject Name Source Program

GAM0MC3 <HLQ>.AUTOMART.ASSEMBLE(GAM0MC3.asm)
GAM0VII <HLQ>.AUTOMART.COBOL(GAM0VII.cbl)
GAM0VMI <HLQ>.AUTOMART.COBOL(GAM0VMI.cbl)
GAM0VMM <HLQ>.AUTOMART.COBOL(GAM0VMM.cbl)
GAM0VSI <HLQ>.AUTOMART.COBOL(GAM0VSI.cbl)

The zOS Global Auto Mart project is updated with the following subprojects and source files:

86 Developer for z/OS: Welcome and Getting Started

Assemble, link, and compile the z/OS projects
Learn how to assemble and link the BMS maps and compile the COBOL code to build the Global Auto Mart
sample.
Learning objectives
In this module, you learn how to use the associated property groups to do these tasks:
• Assemble the BMS maps
• Assemble and link the BMS maps
• Compile the COBOL source
Time required
20 minutes
Prerequisites
To successfully complete the lessons in this module, you must have:
• Permission to create and modify database tables on the remote system.
• All other prerequisites that are mentioned in Modules 1 and 2

Assemble the BMS maps

Learn how to assemble each of the BMS maps, which is the first step in compiling and building the Global
Auto Mart sample.
1. In the z/OS Projects view, right-click GAM0MC1.asm and select Generate JCL > For Assemble. The
JCL data set and member name window opens.

Getting started 87
 2. Verify that the Job Name, JCL data set name, and Member name are correct and click OK. The JCL
Generation Complete window opens.

3. Click Submit. The Job Submission window opens.

4. Click Locate Job. In the Remote Systems view, the Retrieved Jobs filter of the JES subsystem opens.
The job name is highlighted in the filter list.
5. Select the Retrieved Jobs filter, and then select Show in Table. The Remote Systems Details view
opens. This view shows the results of the jobs that were run. Use it to determine whether the jobs
were completed successfully.

88 Developer for z/OS: Welcome and Getting Started

6. Repeat steps “1” on page 87 through “4” on page 88 for the GAM0MC2.asm and GAM0MC3.asm files.
Make sure that the information provided in the Return Info column is NORMAL and the Return Code
column contains values of 4 or less for all three jobs that were completed. Contact your systems
programmer if there are any other return values. If you must change a property group, be sure to save
the changes to the property group, and then regenerate the JCL and resubmit the jobs
In the z/OS Projects view, a JCL file is added to each of your subprojects.

Assemble and link the BMS maps with property group overrides
Learn how to assemble and link the BMS maps with property group overrides.
You must be in the z/OS Projects perspective and connected to the remote system.
To assemble and link the BMS maps with property group overrides:
1. In the z/OS Projects view, expand zOS Global Auto Mart > GAM0MC1 and select the
<HLQ>.AUTOMART.ASSEMBLE(GAM0MC1).asm member.
2. Right-click and select Property Group > Override Properties. The property group editor opens.
3. Open the Assembler tab at the bottom of the property group editor and select Procedures and Steps
from the left panel of options.
4. Expand the ELAXAFASM procedure and select the ASM step.
5. Scroll down to the bottom of the page.
6. In the Assembler Options field, replace the existing options with SYSPARM(MAP).
7. Remove the text that you entered in the Additional JCL text box.
8. Close and save the property group editor.

Getting started 89
 9. Repeat steps “2” on page 89 through “8” on page 89 for the GAM0MC2.asm and GAM0MC3.asm
members.
10. Select the GAM0MC1.asm member, and then right-click and select Generate JCL > For Assemble
Link.
11. In the Load Module Member Name window click OK.

12. In the JCL data set and member name window, click OK.

13. In the JCL Generation Complete window, click Submit.

90 Developer for z/OS: Welcome and Getting Started

14. In the Job Submission window, click Locate Job.

In the Remote Systems view, the Retrieved Jobs filter of the JES subsystem opens. The job name is
highlighted in the filter list.
15. Generate and submit JCL for assemble and link for the GAM0MC2.asm and GAM0MC3.asm
members.
16. Select the Retrieved Jobs filter, and then select Show in Table. The Remote Systems Details view
opens. This view shows the results of the jobs that were run. Use it to determine whether the jobs
were completed successfully.
Make sure that the information provided in the Return Info column is NORMAL and the Return Code
column contains values of 4 or less for all three jobs that were completed. Contact your systems
programmer if there are any other return values.
If you must change a property group, be sure to save the changes on the property group, and then
regenerate the JCL and resubmit the jobs.
For each program that you assembled and linked, a load module, a listing file, and an object file are
added to the data set locations defined in the property group for these files.

Compile the Global Auto Mart sample

Learn how to compile the Global Auto Mart sample.
You must be in the z/OS Projects perspective and connected to your remote system.
You must have permissions on the remote system to bind Db2. Check with your systems administrator to
ensure that you have these permissions.
For each subproject that contains a COBOL source file:
1. In the z/OS Projects view, right-click the subproject name.
2. Click Rebuild Subproject.
3. Wait for the build process to complete.
4. Expand the remote system in the Remote Systems view.
5. Expand JES.
6. Right-click My Jobs and then select Refresh.
7. Right click and select Show in Table. The updated jobs are displayed in the Remote System Details
view.
8. Ensure that all jobs submitted in rebuilding the project completed with a return code of NORMAL and
return information with a value of 4 or less. If the jobs did not complete successfully or you received a
JCL error, ask your systems administrator if you have the partitioned data sets set up correctly.

Getting started 91
 Debug the Global Auto Mart sample
Learn how to debug COBOL code in the Developer for z/OS client.
Learning objectives
In this module, you learn how to use the Developer for z/OS product to do the following tasks:
• Run the Global Auto Mart sample
• Understand how to set CICS resource definitions
• Debug the source
Time required
20 minutes
Prerequisites
To complete this module successfully, you need to meet the following prerequisites:
• The Global Auto Mart sample assembled, linked, and compiled with no errors.
• All prerequisites for modules 1, 2, and 3.

Set up the CICS resource definitions

The Global Auto Mart sample comes prepackaged with a JCL file that automatically sets up the CICS
resource definitions for you. Learn how to use this JCL. To create the CICS resource definitions manually,
skip to the second half of the lesson.
To set up the CICS resource definitions by using the provided JCL:
1. In the Remote Systems view, click My Data Sets > <HLQ>.AUTOMART.CNTL.
2. Right-click the file GAMCSDUP.jcl.
3. Click Submit. The job is submitted.
4. While still in the Remote Systems view, expand JES.
5. Right-click My Jobs.
6. Click Show in Table. The Remote System Details view opens.
7. Verify that the jobs completed successfully.
Tip: Refresh the table to retrieve the recently submitted job.

Manually create CICS resource definitions

To create the CICS Resource Definitions manually instead of by using JCL, you can map the following
program definitions (PDs), transaction definitions (TDs), DB2Entry Definitions (DB2EDs), and DB2Trans
Definitions (DB2TDs):
• GAM0VMM maps to GAM0VMM PD
• GAM0VMI maps to GAM0VMI PD
• GAM0VII maps to GAM0VII PD
• GAM0VSI maps to GAM0VSI PD
• GAM0VMM PD maps to GBMM TD
• GAM0VMI PD maps to GBMI TD
• GAM0VII PD maps to GBII TD
• GAMOVSI PD maps to GBSI TD
• GBSI TD maps to GBSI DB2TD
• GBII TD maps to GBII DB2TD
• GBMI TD maps to GBMI DB2TD
• GBMM TD maps to GBMM DB2TD
• GBSI DB2TD maps to GBMI DB2ED

92 Developer for z/OS: Welcome and Getting Started

• GBII DB2TD maps to GBII DB2ED
• GBMI DB2TD maps to GBMI DB2ED
• GBMM DB2TD maps to GBMM DB2ED

Run the sample

Learn how to run the Global Auto Mart sample.
To run the sample:
1. Open CICS.
2. Enter the transaction GBMI. The program starts, and a window opens and prompts you to enter a
number that corresponds to the make of a car.
3. Enter a value. The screen prompts you to enter a number corresponding to the model of a car.
4. Enter a value. All database matches to your query are displayed. If you are unable to get the program
to run correctly, contact your systems administrator.

Debug the Global Auto Mart sample by using DTCN

Learn how to debug the Global Auto Mart sample by using DTCN.
To debug the Global Auto Mart sample by using DTCN:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Perspective > Open
Perspective > Debug. If the previous sequence is not among the initial options, click Other > Debug.
The Debug perspective opens.
2. In the Debug perspective, hover the cursor over the Debug UI Daemon (circled red in the image) to
make sure that it is listening on port 8001.

3. To change the listening port:

a. Click the down arrow beside the icon.
b. Click Change Port. The Preferences window opens.
c. Enter the port number into the Daemon port field.
d. Click OK.
4. Open CICS.
5. Type the transaction DTCN.
6. Enter either a Transaction ID of GBMI or a Program ID of GAM0VMI, GAM0VMM, GAM0VII, or
GAM0VSI.
7. Change the Session Type to TCP.
8. Enter the Port Number 8001.
9. Change the Display ID to the IP address of the workstation with Developer for z/OS running on it. To
find the IP address of this workstation, click the down arrow next to the listening icon and select Get
Workstation IP. You can then copy the IP address out of the window that opens and paste it into the
appropriate location.
10. Save the changes.
11. Exit the DTCN transaction.

Getting started 93
 12. Run the program again by entering GBMI. The program opens in the Debug perspective of the local
workspace.

Summary: Global Auto Mart

This tutorial guided you through building and compiling the Global Auto Mart sample. You compiled a
COBOL project that prompts the user for the make and model of a car and then displays all corresponding
entries in the database.

Lessons learned
You can now do the following tasks in the Developer for z/OS client:
• Create a connection to a z/OS remote system
• Use repositories on the remote system
• Create z/OS projects and subprojects
• Add remote files to subprojects
• Create, modify, and apply property groups
• Define property group overrides
• Assemble, link, compile, and debug COBOL source code

Submitting JCL with dynamic variable substitution

Learn how to use Menu Manager and the JCL substitution mechanism to submit JCL with dynamic variable
substitution.
If you have multiple programs of the same type, for example, COBOL with CICS and Db2, and these
programs use the same JCL to compile and link-edit them, you can create an action that compiles each
program by using the same JCL. This action eliminates the need to create a separate JCL file for each of
these programs and then modify that JCL each time a different program must be compiled. You need to
edit the JCL only once to mark the parameters that must be overridden for each compilation.
You can dynamically link resources to commands and start those commands with different parameters.
You can use these abilities to do the following tasks:
• Submit different JCL for the same resource, each time with different parameters, without modifying the
source JCL files. The resource in this case is a different entity from the JCL that is to be submitted.
• Submit the JCL that is itself the resource that is being acted on. You can submit the same JCL different
times with different parameters without modifying the original JCL source.
• Provide JCL that multiple users can share; each user does not need modified versions of the JCL files.
This tutorial describes how to use these capabilities.

Learning objectives
Using this tutorial, you learn how to do the following tasks:
• Prepare the JCL for dynamic variable substitution
• Create a menu action with default override values for identified parameters
• Test the new action

Time required
This tutorial takes approximately 60 minutes to finish. If you explore other concepts that are related to
this tutorial, it can take longer to complete.

Prerequisites
Before you complete the lessons that are described in this tutorial, you must do the following steps:

94 Developer for z/OS: Welcome and Getting Started

1. Connect to a remote system.
2. Create a z/OS project and MVS subproject in the z/OS Projects view.
3. Add data sets to the subproject that you can submit for compiling and link-editing. You use these data
sets to test the new action.

Prepare the JCL for dynamic variable substitution

Learn how to identify and mark parameters for dynamic variable substitution.
Developer for z/OS must identify the parameters that must be substituted when the Menu Manager
command is processed. You must create a template from the JCL that must be processed so that
the commands can be identified. In the template, surround each parameter in the JCL that must be
substituted with exclamation marks (!), as shown in the following sample JCL.
This JCL defines a program resource to CICS that is in ELISEE.TEST.JCL(PROGRDO). It was prepared
to mark where the substitution parameters are located. The parameters in this sample JCL that require
substitutions are USERID, PROGRAM, GROUP, and LANGUAGE.

//!USERID!C JOB ,
// MSGCLASS=H,TIME=(,4),REGION=28M,COND=(16,LT),NOTIFY=!USERID!
//*************************************************************
//* @START_RRS_COPYRIGHT@ *
//* LICENSED MATERIALS - PROPERTY OF IBM *
//* *
//* RESTRICTED MATERIALS OF IBM *
//* *
//* (C) COPYRIGHT IBM CORP. 2005, 2024 *
//* *
//* @END_RRS_COPYRIGHT@ *
//*************************************************************
//*************************************************************
//* *
//* RDO RESOURCE DEFINITIONS *
//* *
//*************************************************************
//* *
//* MODIFY THE FOLLOWING DD CARDS TO MATCH YOUR SITE *
//* INFORMATION. *
//* *
//* NAME PURPOSE *
//* --------- ------------------------------------- *
//* STEPLIB CICS SDFHLOAD AND SDFHAUTH DATASETS *
//* DFHCSD CSD DATASET *
//* *
//*************************************************************
//* *
//DEFINE EXEC PGM=DFHCSDUP,REGION=1024K,PARM='CSD(READWRITE)'
//STEPLIB DD DSN=CICSTS.V3R1M0.CICS.SDFHLOAD,DISP=SHR
// DD DSN=CICSTS.V3R1M0.CICS.SDFHAUTH,DISP=SHR
//DFHCSD DD DSN=CICSTS31.DFHCSD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE PROGRAM(!PROGRAM!) GROUP(!GROUP!)
DESCRIPTION(CICS RDO PROGRAM DEFINITION)
LANGUAGE(!LANGUAGE!) CEDF(YES) DATALOCATION(ANY) EXECKEY(USER)
STATUS(ENABLED)
/*
//

Create a menu action with default override values for identified parameters
Learn how to use Menu Manager to create a menu action for supplying values for the parameters that are
identified in the JCL.
You create actions and specify default override values for parameters by using Menu Manager.
To create an action and specify override parameter values:
1. In the Preferences window, navigate to Menu Manager > Actions and Menus.
2. To create an action file, click New.
The New File window opens.

Getting started 95
 3. To indicate that the actions in the new file are run against files, click File.
The Project/Subproject option allows for the creation of actions that are run against projects and
subprojects.
4. Type a file path name for the action file, or to open the location to store the file, click Browse, and
type a file name for it.
Action files are stored in XML format, so specify a file name with the .xml extension, such as
c:\worklocation\myActions.xml. The directory path you specify must exist.
5. Click Next.
The "Create file content" page opens.
6. Click Create a new local/remote action, and then click Finish.
The Menu Manager New Action Wizard opens.
7. In the Name field, type Define Program to CICS and, in the Comment field, type a comment
that describes the new action.
The name that you specify is the name that is displayed in the menu when you select the program or
file and right-click to do the action.
8. From the Context list, select a context for the action.
The context defines the areas of the workbench in which the action is available.
Selecting All, for example, makes the action available in all contexts. Selecting MVS Files in Remote
Systems view makes the action available only when you select an MVS file in the Remote Systems
view of the workbench.
9. Click Next.
The File Associations page opens.
10. Select one or more file types to associate with this action and click Add.
The file types are added to the Chosen File Types list.
11. Click Next.
The Data Set Filters page opens.
12. Click Next.
The Run Options page opens.
13. Enter the command and parameters for the Submit action. Separate multiple entries with commas.
You must enter the command on one line. You can specify the following parameters with the Submit
command:
PROMPT | NOPROMPT
Use one of these parameters, depending on whether a window must prompt for overrides for the
default parameters. PROMPT opens a window that allows for the overriding of some of the values
before the JCL is submitted. If you specified all necessary values and do not need a prompt,
specify NOPROMPT. For repetitive tasks, where the values are either the same or supplied in
variables, NOPROMPT might be preferred. For other tasks where input is needed, PROMPT might be
preferred.
The following command prompts users to enter a value.

Submit,ELISEE.TEST.JCL(PROGRDO),PROMPT,2,Variable,Value,Submit,Define program to CICS

using batch RDO definition,PROGRAM,$name,USERID,$userid,GROUP,MYGROUP,LANGUAGE,COBOL

The following command does not prompt users for a value:

Submit,ELISEE.TEST.JCL(PROGRDO),NOPROMPT,2,
PROGRAM,$name,USERID,$userid,GROUP,MYGROUP,LANGUAGE,COBOL

SPECIFYCASE M | U
SPECIFYCASE is specified after the PROMPT | NOPROMPT keyword. For each variable value,
specify the M or U option to indicate whether the value can be mixed case or must be uppercase.
The following example defines three variables: websvdir, WSDLFILE, and CORRFILE. The websvdir

96 Developer for z/OS: Welcome and Getting Started

 variable is substituted with an uppercase value. The other two variables are substituted with
mixed-case values.

Submit,ELISEE.TEST.JCL(PROGRAM),PROMPT,SPECIFYCASE,2,Variable,Value,Submit,Define
program,websvdir,$input(Web Service directory,testdir),U,WSDLFILE,$input(WSDL filename,
wsdlfile),M,CORRFILE,$input(XML Correlator file name,Corrfile),M

14. Click Show on generic menu.

15. Click Use existing action.
16. Click Select.
The Action Selection window opens.
17. Expand com.ibm.etools.varsubstitution.
18. Select com.ibm.ftt.ui.menumanager.mfivarsubsaction and click OK.
19. To save the action and close the wizard, click Finish.
20. To close the Preferences window, click OK.

Parameter override values

The following considerations apply when you are specifying parameter override values:
• If you do not specify a value for the PROGRAM parameter, then the selected resource is the one that
is acted on as the JCL to run. For example, you might have to submit a CICS start JCL that has certain
options without modifying the JCL itself. Different users can submit the same JCL, but with different
parameter values.
• If you do specify a value for the PROGRAM parameter, then it is the JCL to run when the action
is requested. The resource that is selected by right-clicking is then associated with the JCL to be
submitted.
• If you specify a parameter in the JCL but you do not specify an override value, then that parameter value
is replaced with an empty string. For example, consider the following entry in a JCL:

MEMBER=!PROG!,PARM='1920'

If you do not specify an override value for the !PROG! entry, then that entry becomes:

MEMBER=,PARM='1920'

The following variable values are useful. To see all the available variable values, click Variables on the
Run Options page of the Menu Manager New Action wizard.
$name
Returns the name of the resource that is selected when the menu option is displayed. It returns the
name of the member.
$fullname
Returns the name of the resource that is selected when the menu option is displayed. It returns the
name of the data set and the member name in the format DATASET(MEMBER).
$datasetname
Returns the name of the data set that contains the member resource that is selected by right-clicking
on it.
Related information
“Preferences” on page 74
Use the Preferences window to set preferences both for the workbench and for specific components of
IBM Developer for z/OS.

Test the new action

Learn how to test the new action on a data set in an MVS subproject.
To test the new action, do these steps:

Getting started 97
 1. Right-click a CICS program that you want to submit for compiling and link-editing.
2. Click Define Program to CICS.
The Variable Substitution window opens, listing the override values that you specified for the
variables that require them. You can click Details to preview the JCL before you submit it.

3. To submit the JCL with the variable substitutions, click Submit.

A job submission window opens.

Using the BMS Map Editor

This series of steps guides you through some of the features and capabilities of the BMS Map Editor. For
detailed information about procedures and configuration, see the specific topics in the BMS Map Editor
helps.
Note: Regularly save any modifications to a map set.

98 Developer for z/OS: Welcome and Getting Started

In Developer for z/OS, the BMS Map Editor is associated with .bms map set files and is available in any
perspective. The editor uses the following views:
• Project Explorer
• Outline
• Palette
• Properties
You can import map set files into certain perspectives, such as Enterprise Service Tools.
You can export maps to a JavaServer Faces Web page and its components.

Creating a project
Map sets can be created only in an existing project. To create a project:
1. From the main menu, select File > New > Project.
2. In the New Project wizard that opens, expand General > Project. Click Next.
3. Type Test project as the project name. Click Finish to close the wizard and create the project.
Test project is listed in the Project Explorer view. To open this view from the main menu, select
Window (on Windows) or IBM Developer for z/OS (on macOS) > Show View > Other and type Project
Explorer as the filter text.

Creating a map set

To create a map set in a project:
1. From the main menu, select File > New > Other.
2. In the New wizard that opens, enter Map Set as the filter text and select BMS > Map Set from the list
of file wizards.
3. Click Next.
4. Select Test project as the parent folder.
5. Type NEWMAPSET as the file name. The .bms extension is automatically added.
6. Click Finish to accept the default configuration.
The map set file NEWMAPSET.BMS is listed in theTest project project in the Project Explorer view.

Adding maps to the map set

To add and modify maps and fields in the map set:
1. Open the map in the editor by double-clicking NEWMAPSET.BMS if it is not already open
2. Start by tagging and dragging the mouse down to and to the right in the Design canvas. Notice the size
and position of the map are shown in the pop-up box.
3. in the Basic drawer of the Palette view, select Map.
4. Move the cursor to the Design canvas, and click to place the map.
You can use the Select tool in the Default drawer to move and resize the map.

Viewing and modifying map properties

Select a map in the Design canvas. The map properties are shown in the Properties view. The selected
map is also highlighted in the Outline view.
To modify map properties from the Design canvas, complete the following steps:
1. In the Outline view, right-click MAP2. The map is highlighted in the Design canvas.

2. Click Toggle Black and White Mode, , in the upper-right corner of the Design canvas to view the
selected map more easily.

Getting started 99
 3. Right-click the highlighted map in the Design canvas and select Map Properties from the menu to
modify the settings.
To modify map properties under the Source tab, complete the following steps:
1. Click the Source tab below the Design canvas.
2. Locate the Map1 label.
3. Place the cursor in the source code and change the map size parameters to SIZE=(14,60). This
action changes the height of the map to 14 columns and the width to 60 columns. The change is
shown in the Properties view.

Adding and modifying fields

To add and modify a label field:
1. in the Constant Fields drawer of the Palette, select Label.
2. Click in the Design canvas to place the field. If the location is not valid, for example, outside the
boundaries of an existing map, you cannot place the field.

3. If the label field is not shown with the map in the Outline view, select Show Unnamed Fields, , to
show the label field.
4. Left-click the field in the Design canvas and type a new label value.
5. Double-click the field in the Design canvas.
6. Add a name for the label field, and click Apply. Click Show Unnamed Fields again; the field is now
shown with its name in the Outline view.
7. Right-click the field in the Outline view. Select Cut to remove the field from its current map.
8. Select a different map in the Outline view. Press Ctrl+V to place the field into that map.
To add and modify a password field:
1. Click the Password field button in the Variable Fields drawer.
2. Place the pointer in the Design canvas. A drop box is added to the pointer.
3. Click and hold the left mouse button at the location that you want.
4. Draw the field to a width of five characters and release the mouse button.
Note: The height in the pop-up box cannot be greater than two characters; the drawn box can be only
0 or 1 character high.
Align the fields by completing the following steps:
1. In the Outline view, select multiple fields by holding the Ctrl key and clicking the field icons.
2. Right-click one of the highlighted fields in the Design canvas, and select Align > Align to Parent > Top.
The fields are aligned to the top of the map.
Use the Shift key with the Select tool to grab and move multiple items in the Design canvas. View the
maps and fields with the other display options to see how they can assist you in modifying maps and
fields.

Filtering and previewing maps

Use the Filters feature to view, prioritize, or hide specific maps within a set:
1. Click Filters above the Design canvas. The name of the current filter is shown below the button.
2. Click New to add a filter.
3. Move maps up or down the filter list, or clear maps.
Note the changes in the Preview pane. Filters display the enabled maps in order, as you look at the
Preview pane or Design canvas (the second map is placed behind the first and the third is placed
behind the second).

100 Developer for z/OS: Welcome and Getting Started

 4. Click OK to complete the filter modification.
5. Click the list beside the Filters button and select the newly added filter from the list of available filters.
The filtered maps are not shown in the Design canvas or the Outline view.
6. Click the Preview tab. In Normal mode, the filtered maps are not shown.
The Preview page shows maps and fields in Web and Normal mode. Normal mode provides a terminal-
like preview, with full filtering capability. The Web mode shows all maps in a set.

The CICS catalog manager example application

The CICS catalog example application is a working COBOL application that is designed to illustrate best
practice when connecting CICS applications to external clients and servers using Web services for CICS,
and using Web service modules generated by Enterprise Service Tools.

The example is constructed around a simple sales catalog and order processing application, in which the
end user can perform these functions:
• List the items in a catalog.
• Inquire on individual items in the catalog.(inquireSingle)
• Order items from the catalog.
The catalog is implemented as a VSAM file.
Installation of the base catalog manager application is covered in the CICS 5.3 Transaction Server
documentation. A Web client front end is provided with the catalog manager application. Configuration
of the Web client is also described in the CICS 5.3 Transaction Server documentation. The Web client
calls multiple Web Services that are provided by the base catalog example application after it has been
enabled for Web services.

The base application

The base application, with its 3270 user interface, provides functions with which you can list the contents
of a stored catalog, select an item from the list, and enter a quantity to order. The application has a
modular design which makes it simple to extend the application to support newer technology, such as
Web services.

This illustration shows the structure of the base application (for a detailed description of the application
see “Description of the catalog manager application” on page 124).

Figure 3. Structure of the base application

Getting started 101

 Installing and setting up the base application
Before you can run the base application you must define and populate two VSAM data sets, and install
two transaction definitions.

Creating and defining the VSAM data sets

The example application uses two KSDS VSAM data sets to be defined and populated. One data set
contains configuration information for the example application. The other contains the sales catalog.
1. Locate the JCL to create the VSAM data sets.

During CICS installation, the JCL is placed in the hlq.SDFHSAMP library:

• Member DFH$ECNF contains the JCL to generate the configuration data set.
• Member DFH$ECAT contains the JCL to generate the catalog data set.
2. Modify the JCL and access method services commands.
a) Supply a valid JOB card.
b) Supply a suitable high level qualifier for the data set names in the access method services
commands.
As supplied, the JCL uses a high level qualifier of HLQ.
The following command defines the catalog file:

DEFINE CLUSTER (NAME(hlq.EXMPLAPP.catname)-

TRK(1 1) -
KEYS(4 0) -
RECORDSIZE(80,80) -
SHAREOPTIONS(2 3) -
INDEXED -
) -
DATA (NAME(hlq.EXMPLAPP.catname.DATA) -
) -
INDEX (NAME(hlq.EXMPLAPP.catname.INDEX) -
)

where
• hlq is a high level qualifier of your choice
• catname is a name of your choice. The name used in the example application as supplied is
EXMPCAT.
The following command defines the configuration file:

DEFINE CLUSTER (NAME(hlq.EXMPLAPP.EXMPCONF)-

TRK(1 1) -
KEYS(9 0) -
RECORDSIZE(350,350) -
SHAREOPTIONS(2 3) -
INDEXED -
) -
DATA (NAME(hlq.EXMPLAPP.EXMPCONF.DATA) -
) -
INDEX (NAME(hlq.EXMPLAPP.EXMPCONF.INDEX) -
)

where hlq is a high level qualifier of your choice.

3. Run both jobs to create and populate the data sets.
4. Use the CEDA transaction to create a FILE definition for the catalog file.
a) Enter the following: CEDA DEF FILE(EXMPCAT)G(EXAMPLE).
Alternatively, you can copy the FILE definition from CICS supplied group DFH$EXBS.
b) Enter the following additional attributes:

102 Developer for z/OS: Welcome and Getting Started

 DSNAME(hlq.EXMPLAPP.EXMPCAT)
ADD(YES)
BROWSE(YES)
DELETE(YES)
READ(YES)
UPDATE(YES)
c) Use the default values for all other attributes.
5. Use the CEDA transaction to create a FILE definition for the configuration file.
a) Enter the following: CEDA DEF FILE(EXMPCONF) G(EXAMPLE).
Alternatively, you can copy the FILE definition from CICS supplied group DFH$EXBS.
b) Enter the following additional attributes:
DSNAME(hlq.EXMPLAPP.EXMPCONF)
ADD(YES)
BROWSE(YES)
DELETE(YES)
READ(YES)
UPDATE(YES)
c) Use the default values for all other attributes.

Defining the 3270 interface

The example application is supplied with a 3270 user interface to run the application and to customize it.
The user interface consists of two transactions, EGUI and ECFG.
Use the CEDA transaction to create TRANSACTION definitions for both transactions.
a) To define transaction EGUI, enter the following: CEDA DEF TRANS (EGUI) G(EXAMPLE)
PROG(DFH0XGUI).
b) To define transaction ECFG, enter the following: CEDA DEF TRANS (ECFG) G(EXAMPLE)
PROG(DFH0XCFG)

Use the default values for all other attributes.

Note: The correct operation of the example application does not depend on the names of the
transactions, so you can use different names if you wish.
Alternatively, you can copy the TRANSACTION definitions from CICS supplied group DFH$EXBS.

Completing the installation

To complete the installation, install the RDO group that contains your resource definitions.
Enter the following command at a CICS terminal: CEDA I G(EXAMPLE).

The application is now ready for use.

Web service support for the example application

The Web service support extends the example application, providing a Web client front end and two
versions of a Web service endpoint for the order dispatcher component.

The Web client front end and one version of the Web service endpoint are supplied as enterprise archives
(EARs) that will run in the following environments:
• WebSphere Application Server Version 5 Release 1 or later

Getting started 103

 • WebSphere Studio Application Developer Version 5 Release 1 or later with a WebSphere unit test
environment
• WebSphere Studio Enterprise Developer Version 5 Release 1 or later with a WebSphere unit test
environment
The second version of the Web service endpoint is supplied as a CICS service provider application
program (DFH0XODE).

Configuring code page support

As supplied, the example application uses two coded character sets. You must configure your system to
enable data conversion between the two character sets.

The coded character sets used in the example application are:

CCSID
Description
037
EBCDIC Group 1: USA, Canada (z/OS), Netherlands, Portugal, Brazil, Australia, New Zealand)
1208
UTF-8 Level 3
Add the following statements to the conversion image for your z/OS system:

CONVERSION 037,1208;
CONVERSION 1208,037;

Installing Web service support

Before you can run the Web service support for the example application, you must create two HFS
directories, and create and install a number of CICS resource definitions.

Creating the HFS directories

Web service support for the example application requires a shelf directory and a pickup directory in the
Hierarchical File System (HFS).

The shelf directory is used to store the Web service binding files that are associated with WEBSERVICE
resources. Each WEBSERVICE resource is, in turn, associated with a PIPELINE. The shelf directory is
managed by the PIPELINE resource and you should not modify its contents directly. Several PIPELINES
can use the same shelf directory, as CICS ensures a unique directory structure beneath the shelf directory
for each PIPELINE.
The pickup directory is the directory that contains the Web service binding files associated with a
PIPELINE. When a PIPELINE is installed, or in response to a PERFORM PIPELINE SCAN command,
information in the binding files is used to dynamically create the WEBSERVICE and URIMAP definitions
associated with the PIPELINE.
The example application uses /var/cicsts for the shelf directory.
A pipeline will read in an XML pipeline configuration file at install time. It is therefore also useful to define
a directory in which to store these.

Creating the PIPELINE definition

The complete definition of a pipeline consists of a PIPELINE resource and a pipeline configuration file.
The file contains the details of the message handlers that will act on Web service requests and responses
as they pass through the pipeline.

104 Developer for z/OS: Welcome and Getting Started

The example application uses the CICS-supplied SOAP 1.1 handler to deal with the SOAP envelopes of
inbound and outbound requests. CICS provides sample pipeline configuration files which you can use in
your service provider and service requester.
More than one WEBSERVICE can share a single PIPELINE, therefore you need define only one pipeline
for the inbound requests of the example application. You must, however, define a second PIPELINE for
the outbound requests as a single PIPELINE cannot be configured to be both a provider and requester
pipeline at the same time.
1. Use the CEDA transaction to create a PIPELINE definition for the service provider.
a) Enter the following: CEDA DEF PIPE(EXPIPE01) G(EXAMPLE).
Alternatively, you can copy the PIPELINE definition from CICS supplied group DFH$EXWS.
b) Enter the following additional attributes:

STATUS(Enabled)
CONFIGFILE(/usr/lpp/cicsts
/samples/pipelines/basicsoap11provider.xml)
SHELF(var/cicsts)
WSDIR(/usr/lpp/cicsts/samples/webservices/wsbind/provider/)

Note: The HFS entries are case sensitive and assume a default CICS HFS install root of /usr/lpp/
cicsts.
2. Use the CEDA transaction to create a PIPELINE definition for the service requester.
a) Enter the following: CEDA DEF PIPE(EXPIPE02) G(EXAMPLE).
Alternatively, you can copy the PIPELINE definition from CICS supplied group DFH$EXWS.
b) Enter the following additional attributes:

STATUS(Enabled)
CONFIGFILE(/usr/lpp/cicsts
/samples/pipelines/basicsoap11requester.xml)
SHELF(var/cicsts)
WSDIR(/usr/lpp/cicsts/samples/webservices/wsbind/requester/)

Note: The HFS entries are case sensitive and assume a default CICS HFS install root of /usr/lpp/
cicsts.

Creating a TCPIPSERVICE
As the client connects to your Web services over an HTTP transport you must define a TCPIPSERVICE to
receive the inbound HTTP traffic.
Use the CEDA transaction to create a TCPIPSERVICE definition to handle inbound HTTP requests.
a) Enter the following: CEDA DEF TCPIPSERVICE(EXMPPPORT) G(EXAMPLE).

Alternatively, you can copy the TCPIPSERVICE definition from CICS supplied group DFH$EXWS.
b) Enter the following additional attributes:
URM(NONE)
PORTNUMBER(port) where port is an unused port number in your CICS system.
PROTOCOL(HTTP)
TRANSACTION(CWXN)
c) Use the default values for all other attributes.

Dynamically installing the WEBSERVICE and URIMAP resources

Each function exposed as a Web service requires a WEBSERVICE resource to map between the incoming
XML of the SOAP BODY and the COMMAREA interface of the program, and a URIMAP resource that routes
incoming requests to the correct PIPELINE and WEBSERVICE. Although you can use RDO to define and

Getting started 105

 install your WEBSERVICE and URIMAP resources, you can also have CICS create them dynamically when
you install a PIPELINE resource.
Install the PIPELINE resources.

Use the following commands:

CEDA INSTALL PIPELINE(EXPIPE01) G(EXAMPLE)
CEDA INSTALL PIPELINE(EXPIPE02) G(EXAMPLE)
When you install each PIPELINE resource, CICS scans the directory specified in the PIPELINE's WSDIR
attribute (the pickup directory). For each Web service binding file in the directory, that is for each file with
the .wsbind suffix, CICS installs a WEBSERVICE and a URIMAP if one does not already exist. Existing
resources are replaced if the information in the binding file is newer than the existing resources.
When the PIPELINE is later disabled and discarded all associated WEBSERVICE and URIMAP resources
will also be discarded.
If you have already installed the PIPELINE, use the PERFORM PIPELINE SCAN command to initiate the
scan of the PIPELINE's pickup directory.
When you have installed the PIPELINEs, the following WEBSERVICEs and their associated URIMAPs will
be installed in your system:
dispatchOrder
dispatchOrderEndpoint
inquireCatalog
inquireSingle
placeOrder
The names of the WEBSERVICEs are derived from the names of the Web service binding files; the
names of the URIMAPs are generated dynamically. You can view the resources with a CEMT INQUIRE
WEBSERVICE command.
The following display shows the names of the PIPELINE, the URIMAP, and the target program that is
associated with each WEBSERVICE.
Note: In this example, there is no URIMAP or target program displayed for WEBSERVICE(dispatchOrder)
because the WEBSERVICE is for an outbound request.

I WEBS
STATUS: RESULTS - OVERTYPE TO MODIFY
Webs(dispatchOrder ) Pip(EXPIPE02)
Ins Dat(20041203)
Webs(dispatchOrderEndpoint ) Pip(EXPIPE01)
Ins Uri(£539140 ) Pro(DFH0XODE) Com Dat(20041203)
Webs(inquireCatalog ) Pip(EXPIPE01)
Ins Uri(£539141 ) Pro(DFH0XCMN) Com Dat(20041203)
Webs(inquireSingle ) Pip(EXPIPE01)
Ins Uri(£539142 ) Pro(DFH0XCMN) Com Dat(20041203)
Webs(placeOrder ) Pip(EXPIPE01)
Ins Uri(£539150 ) Pro(DFH0XCMN) Com Dat(20041203)

WEBSERVICE(dispatchOrderEndpoint) represents the local CICS implementation of the dispatch order

service.

Creating the WEBSERVICE resources with RDO

As an alternative to using the PIPELINE scanning mechanism to install WEBSERVICE resources, you can
create and install them using Resource Definition Online (RDO).

Important: If you use RDO to define the WEBSERVICE and URIMAP resources, you must ensure that their
Web service binding files are not in the PIPELINE's pickup directory.

106 Developer for z/OS: Welcome and Getting Started

1. Use the CEDA transaction to create a WEBSERVICE definition for the inquire catalog function of the
example application.
a) Enter the following: CEDA DEF WEBSERVICE(EXINQCWS) G(EXAMPLE).
b) Enter the following additional attributes:

PIPELINE(EXPIPE01)
WSBIND(/usr/lpp/cicsts/samples
/webservices/wsbind/inquireCatalog.wsbind)
2. Repeat the preceding step for each of the following functions of the example application.
WEBSERVICE PIPELINE
Function name attribute WSBIND attribute

INQUIRE SINGLE EXINQSWS EXPIPE01 /usr/lpp/cicsts/samples

ITEM /webservices/wsbind
/provider/inquireSingle.wsbind

PLACE ORDER EXORDRWS EXPIPE01 /usr/lpp/cicsts/samples

/webservices/wsbind
/provider/placeOrder.wsbind

DISPATCH STOCK EXODRQWS EXPIPE02 /usr/lpp/cicsts/samples

/webservices/wsbind
/requester/dispatchOrder.wsbind

DISPATCH STOCK EXODEPWS EXPIPE01 /usr/lpp/cicsts/samples

endpoint (optional) /webservices/wsbind
/provider/dispatchOrderEndpoint.wsbind

Creating the URIMAP resources with RDO

As an alternative to using the PIPELINE scanning mechanism to install URIMAP resources, you can create
and install them using Resource Definition Online (RDO).

Important: If you use RDO to define the WEBSERVICE and URIMAP resources, you must ensure that their
Web service binding files are not in the PIPELINE's pickup directory.
1. Use the CEDA transaction to create a URIMAP definition for the inquire catalog function of the example
application.
a) Enter the following: CEDA DEF URIMAP(INQCURI) G(EXAMPLE).
b) Enter the following additional attributes:

USAGE(PIPELINE)
HOST(*)
PATH(/exampleApp/inquireCatalog)
TCPIPSERVICE(SOAPPORT)
PIPELINE(EXPIPE01)
WEBSERVICE(EXINQCWS)
2. Repeat the preceding step for each of the remaining functions of the example application.
Use the following names for your URIMAPs:

Function URIMAP name

INQUIRE SINGLE ITEM INQSURI
PLACE ORDER ORDRURI
DISPATCH STOCK Not required

Getting started 107

 Function URIMAP name
DISPATCH STOCK endpoint (optional) ODEPURI

a) Specify the following distinct attributes for each URIMAP:

Function URIMAP name PATH WEBSERVICE

INQUIRE SINGLE INQSURI /exampleApp/inquireSingle EXINQSWS
ITEM
PLACE ORDER ORDRURI /exampleApp/placeOrder EXORDRWS
DISPATCH ODEPURI /exampleApp/dispatchOrder EXODEPWS
STOCK endpoint
(optional)
b) Enter the following additional attributes, which are the same for all the URIMAPs:
USAGE(PIPELINE)
HOST(*)
TCPIPSERVICE(SOAPPORT)
PIPELINE(EXPIPE01)

Completing the installation

To complete the installation, install the RDO group that contains your resource definitions.
Enter the following command at a CICS terminal: CEDA I G(EXAMPLE).

The application is now ready for use.

Configuring the example application

The base application includes a transaction (ECFG) that you can use to configure the example application.

The configuration transaction uses mixed case information. You must use a terminal that can handle
mixed case information correctly.
The transaction lets you specify a number of aspects of the example application. These include:
• The overall configuration of the application, such as the use of Web services
• The network addresses used by the Web services components of the application
• The names of resources, such as the file used for the data store
• The names of programs used for each component of the application
The configuration transaction lets you replace CICS-supplied components of the example application with
your own, without restarting the application.
1. Enter the transaction ECFG to start the configuration application.
CICS displays the following screen:

108 Developer for z/OS: Welcome and Getting Started

 CONFIGURE CICS EXAMPLE CATALOG APPLICATION

Datastore Type ==> VSAM STUB|VSAM

Outbound WebService? ==> NO YES|NO
Catalog Manager ==> DFH0XCMN
Data Store Stub ==> DFH0XSDS
Data Store VSAM ==> DFH0XVDS
Order Dispatch Stub ==> DFH0XSOD
Order Dispatch WebService ==> DFH0XWOD
Stock Manager ==> DFH0XSSM
VSAM File Name ==> EXMPCAT
Server Address and Port ==> myserver:99999
Outbound WebService URI ==> http://myserver:80/exampleApp/dispatchOrder
==>
==>
==>
==>
==>

PF 3 END 12 CNCL

2. Complete the fields.

Datastore Type
Specify STUB if you want to use the Data Store Stub program.
Specify VSAM if you want to use the VSAM data store program.
Outbound WebService
Specify YES if you want to use a remote Web service for your Order Dispatch function, that is, if you
want the catalog manager program to link to the Order Dispatch Web service program.
Specify NO if you want to use a stub program for your Order Dispatch function, that is, if you want
the catalog manager program to link to the Order Dispatch Stub program.
Catalog Manager
Specify the name of the Catalog Manager program. The program supplied with the example
application is DFH0XCMN.
Data Store Stub
If you specified STUB in the Datastore Type field, specify the name of the Data Store Stub
program. The program supplied with the example application is DFH0XSDS.
Data Store VSAM
If you specified VSAM in the Datastore Type field, specify the name of the VSAM data store
program. The program supplied with the example application is DFH0XVDS.
Order Dispatch Stub
If you specified NO in the Outbound WebService field, specify the name of the Order Dispatch
Stub program. The program supplied with the example application is DFH0XSOD.
Order Dispatch WebService
If you specified YES in the Outbound WebService field, specify the name of the program
that functions as a service requester. The program supplied with the example application is
DFH0XWOD.
Stock Manager
Specify the name of the Stock Manager program. The program supplied with the example
application is DFH0XSSM.
VSAM File Name
If you specified VSAM in the Datastore Type field, specify the name of the CICS FILE definition.
The name used in the example application as supplied is EXMPCAT.
Server Address and Port

Getting started 109

 Outbound WebService URI
If you specified YES in the Outbound WebService field, specify the location of the Web service
that implements the dispatch order function. If you are using the supplied CICS endpoint set this
to: http://myserver:myport/exampleApp/dispatchOrder where myserver and myport
are your CICS server address and port respectively.

Configuring the Web client

Before you can use the Web client, you must configure it to call the appropriate end points in your CICS
system.
1. Enter the following in your Web browser: http://myserver:9080/ExampleAppClientWeb/,
where myserver is the hostname of the server on which the Web service client is installed.

The example application displays the page shown in Figure 4 on page 110:

Figure 4. Welcome Page for the CICS Example Application

2. Click the CONFIGURE button to bring up the configuration page.
The configuration page shown in Figure 5 on page 111 displayed.

110 Developer for z/OS: Welcome and Getting Started

 Figure 5. Configuration Page for the CICS Example Application
3. Enter the new endpoints for the Web service.
There are three endpoints to configure:
Inquire catalog
Inquire item
Place order
a) In the URLs replace the string 'myCicsServer' with the name of the system on which your CICS is
running.
b) Replace the port number '9999' with the port number configured in the TCPIPSERVICE, in the
example this to 30000.
4. Click the SUBMIT button.
The Web application is now ready to run.
Note: The URL that the Web services invoke is stored in an HTTP session. It is therefore necessary to
repeat this configuration step each time a browser is first connected to the client.

Running the example application

You can run the example application in two ways: you can use the BMS interface, and you can use a Web
client.

Getting started 111

 Running the example application with the BMS interface
The base application can be invoked using its BMS interface.
1. Enter transaction EGUI from a CICS terminal.

The example application displays the following menu:

CICS EXAMPLE CATALOG APPLICATION - Main Menu

Select an action, then press ENTER

Action . . . . 1. List Items

2. Order Item Number ____
3. Exit

F3=EXIT F12=CANCEL

The options on the menu enable you to list the items in the catalog, order an item, or exit the
application.
2. Type 1 and press ENTER to select the LIST ITEMS option.
The application displays a list of items in the catalog.

CICS EXAMPLE CATALOG APPLICATION - Inquire Catalog

Select a single item to order with /, then press ENTER

Item Description Cost Order

-----------------------------------------------------------------
0010 Ball Pens Black 24pk 2.90 /
0020 Ball Pens Blue 24pk 2.90 _
0030 Ball Pens Red 24pk 2.90 _
0040 Ball Pens Green 24pk 2.90 _
0050 Pencil with eraser 12pk 1.78 _
0060 Highlighters Assorted 5pk 3.89 _
0070 Laser Paper 28-lb 108 Bright 500/ream 7.44 _
0080 Laser Paper 28-lb 108 Bright 2500/case 33.54 _
0090 Blue Laser Paper 20lb 500/ream 5.35 _
0100 Green Laser Paper 20lb 500/ream 5.35 _
0110 IBM Network Printer 24 - Toner cart 169.56 _
0120 Standard Diary: Week to view 8 1/4x5 3/4 25.99 _
0130 Wall Planner: Eraseable 36x24 18.85 _
0140 70 Sheet Hard Back wire bound notepad 5.89 _
0150 Sticky Notes 3x3 Assorted Colors 5pk 5.35 _

F3=EXIT F7=BACK F8=FORWARD F12=CANCEL

3. Type / in the ORDER column, and press ENTER to order an item.

The application displays details of the item to be ordered.

112 Developer for z/OS: Welcome and Getting Started

 CICS EXAMPLE CATALOG APPLICATION - Details of your order

Enter order details, then press ENTER

Item Description Cost Stock On Order

-----------------------------------------------------------------------------
0010 Ball Pens Black 24pk 2.90 0011 000

Order Quantity: 5
User Name: CHRISB
Charge Dept: CICSDEV1

F3=EXIT F12=CANCEL

4. If there is sufficient stock to fulfil the order, enter the following information.
a) Complete the ORDER QUANTITY field.
Specify the number of items you want to order.
b) Complete the USERID field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
c) Complete the CHARGE DEPT field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
5. Press ENTER to submit the order and return to the main menu.
6. Select the EXIT option to end the application.

The Web service enabled application

You can invoke the example application from a Web browser.
1. Enter the following in your Web browser: http://myserver:9080/ExampleAppClientWeb/,
where myserver is the host name of the server on which the Web service client is installed.

The example application displays the page shown in Figure 6 on page 114.

Getting started 113

 Figure 6. Welcome Page for the CICS Example Application
2. Click the INQUIRE button.
The example application displays the page shown in Figure 7 on page 114.

Figure 7. Inquire Page for the CICS Example Application

3. Enter an item number, and click the SUBMIT button.
Tip: The base application is primed with item numbers in the sequence 0010, 0020, ... through 0210.
The example application displays the page shown in Figure 8 on page 115, which contains a list of
items in the catalog, starting with the item number that you entered.

114 Developer for z/OS: Welcome and Getting Started

 Figure 8. List Items Page for the CICS Example Application
4. Select the item that you want to order.
a) Click the radio button in the Select column for the item you want to order.
b) Click the SUBMIT button.
The example application displays the page shown in Figure 9 on page 116:

Getting started 115

 Figure 9. Order Details Page for the CICS Example Application
5. To place an order, enter the following information.
a) Complete the Quantity field.
Specify the number of items you want to order.
b) Complete the User Name field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
c) Complete the Department Name field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
d) Click the SUBMIT button.
The example application displays the page shown in Figure 10 on page 116 to confirm that the order
has been placed:

Figure 10. Order Confirmation Page for the CICS Example Application

116 Developer for z/OS: Welcome and Getting Started

Creating and deploying CICS Web services artifacts
This topic and its subtopics describe how to use the Enterprise Service Tools to create the files needed to
deploy the CICS catalog manager example application as a Web service.

Web services in CICS provides an interpretive engine that converts XML data to and from language
structures. The interpretive engine does not support all the data constructs and types in the COBOL
language, making it necessary for the CICS Web services developer to write additional code or a wrapper
program to process unsupported types. The behavior of the interpretive engine is not configurable,
whereas a user may have very specific needs in processing SOAP messages.
A standard interface between CICS combined with a user supplied program that provides XML conversion
to and from language structures is called the "vendor interface". The vendor interface allows users to have
pluggable XML conversion. XML converters generated by Enterprise Service Tools have broader support
for data constructs and types. We recommend using these XML converters with the vendor interface. For
improved debugging, CICS Transaction Server Version 3.1 treats the compiled converters as user code,
which allows debugging should a failure occur. The interpretive engine cannot be debugged or changed by
the user.
New in CICS Transaction Server Version 3.1, is a batch job called DFHLS2WS (Language Structure to
WSDL) which is equivalent to the bottom-up approach of Web services development . Enterprise Service
Tools, used in combination with the vendor interface as a replacement for DFHLS2WS, provides expanded
functionality to the end user. This combination helps a user to enable Web service interface with a COBOL
data type that is not supported by the CICS interpretive conversion engine, generally without requiring the
user to write any additional wrapper conversion program.
Related concepts

“Artifacts necessary to enable a Web service under CICS” on page 117

Related tasks

“Deploying the Web service artifacts to CICS” on page 120

“Creating Web service artifacts for CICS” on page 118

Artifacts necessary to enable a Web service under CICS

This topic describes the WSBind file, the WSDL file, and the driver and conversion programs generated by
the Enterprise Service Tools wizards.

WSBind file
The WSBind file is a resource that describes to CICS the specifics of the Web service. For example, it
contains information about what the system should do to convert an input XML document to a COBOL
language structure and what to do to convert the output COBOL data to the output XML document.
Enterprise Service Tools can be used to generate both Vendor and Native WSBind files.
The WSBind file is an EBCDIC binary file, CICS expects the WSBind file to be encoded in the EBCDIC
variant used by the region. The extension of the generated WSBind file is always set to .wsbind.
The WSBind File Viewer can be used to display the contents of the WSBind file.

Enterprise Service Tools Converters

In the CICS vendor scenario, CICS delegates conversion of SOAP requests and response messages to
vendor conversion programs. The same wizard in the Enterprise Service Tools that generates the WSBind
file also generates vendor conversion programs suitable for use with the CICS vendor interface. These
vendor conversion programs consist of a driver, a request XML converter and a response XML converter.
The XML converters convert an input XML document to a COBOL language structure and convert the

Getting started 117

 output COBOL data to the output XML document. The driver program manages the communication
between CICS and the XML converters.

WSDL
The WSDL file describes the Web service to the Web service clients. The same wizard in the Enterprise
Service Tools that generates the WSBind file and the vendor conversion programs also generates the
WSDL file.
The WSDL file can also be used by the CICS system to validate messages received and sent by the Web
service. The validation can be turned on and off when the CICS Web service resource is installed or
configured. Validation is useful when you test or debug your Web service. Validation will slow down the
Web service performance and you may want to turn it off in the production version of the Web service.
Note: Make sure that you use the WSDL file, WSBind file, and XML conversion programs that are
generated from the same language source file (and the same wizard session). Do not mix artifacts from
other sources or tools. For example do not combine XML conversion programs generated by the wizard
from the Enterprise Service Tools with a WSDL file or a WSBind file generated by the DFHLS2WS batch job
(part of the CICS Web service assistant tool that is included in CICS Transaction Server version 3.1 and
later).
Related concepts

“Creating and deploying CICS Web

services artifacts” on page 117

Related tasks

“Deploying the Web service artifacts to CICS” on page 120

“Creating Web service artifacts for CICS” on page 118

Creating Web service artifacts for CICS

This topic describes the development steps that you need to perform to create the needed artifacts to
install a new Web service in CICS using the Enterprise Service Tools perspective.
This process uses the Create New Service Interface (bottom-up) wizard from the Enterprise Service Tools.
Note: You can also achieve these tasks using the batch processor .

Locating the CICS application source and copy books

In order to generate the artifacts needed to enable an application as a Web service, the Create New
Service Interface (bottom-up) wizard must have access to either a complete program or copy book
containing the language structure that is the interface to the application.
Since generated artifacts (the XML converters, the driver, the WSBind file, and the WSDL file) must be
transferred to a z/OS system, you can use the z/OS projects and system perspectives of Developer for
z/OS to assist with this task. Also if your program source and copy books are located on z/OS you can
access them using the z/OS projects perspective.
Create a local project and import the program source files for the CICS program to the project. If the
program source files exist on a remote system, use the Remote Systems view to copy them to your local
project.

Generating the Web services artifacts conversion artifacts

Follow these steps to generate the Web services artifacts:
1. Verify that the Navigator view is open. If the Navigator view is not open, follow these steps to open the
Navigator view:

118 Developer for z/OS: Welcome and Getting Started

 a. In the menu bar of the workbench, select Window > Show View > Other. The Show View wizard
opens.
b. In the Show View wizard:
i) Expand General.
ii) Select Navigator.
iii) Click OK.
The Navigator view opens.
2. Start the Enterprise Service Tools Wizard Launchpad:
a. In the Navigator view, right-click the program source file containing the interface data structure for
the program.
b. Select Enable Enterprise Web Service.
The Enterprise Service Tools Wizard Launchpad opens.
3. Launch the Create New Service Interface (bottom-up) wizard:
a. In the Enterprise Service Tools Wizard Launchpad:
i) In the Runtime list box, select Web Services for CICS.
ii) In the Scenario list box, select Create New Service Interface (bottom-up).
iii) In the Conversion type list box, select Compiled XML Conversion.
iv) Click Start.
The Create New Service Interface (bottom-up) wizard opens.
4. On the first page of the wizard (entitled Language Structures):
a. In the Request Language Structure tab, select the high-level language structure that is the input
structure for the application. By default the first structure defined in the program source file is
selected.
b. In the Response Language Structure tab, select the high-level language structure that is the
output structure for the application. Additional structures are allowed to be selected or omitted.
However, by default the first structure defined in the program source file is selected.
c. Click Next.
5. On the second page of the wizard (entitled Generation Options):
a. In the XML Converters tab:
i) In the Specify identification attributes group, verify or change other entries that apply for
your z/OS system (for example, the name of the CICS application program in "Service program
name:" should be correct).
ii) In the Specify character encodings group, verify or change other entries that apply for your
z/OS system.
b. In the WSDL and XSD tab:
i) In the Service Location field, type the Endpoint URI.
Note: The local portion of the URI (excludes server and port) is used as the default for the local
URI in the WSBind (for example, /exampleApp/inquireSingle).
c. Click Next.
6. On the third page of the wizard (entitled Web Services for CICS):
a. In the Basic Options tab:
i) In the Specify targets for WSBind file group:
a) In the input field WSBind file container, specify the folder and subfolder in which you want
the WSBind file to be generated.

Getting started 119

 ii) In the Specify application program properties group, if your CICS program communicates via a
channel.
a) Expand the Program interface list box and select CHANNEL.
b) In the Container name field, type the name of the container.
b. In the Advanced Options tab, specify installation options for the CICS Web service. If you do not
specify these properties you might have to define them at install time during the manual creation of
the Web service definitions in CICS.
c. Click Next.
7. On the fourth page of the wizard (titled File, data set, or member selection):
a. In the XML Converters tab:
i) In the Converter file container field, specify the folder and subfolder in which you want the
converter programs to be created.
ii) In the input field Converter driver file name, type the name of the file in which you want the
converter programs to be generated.
Note: By default, all the converter programs (driver, request converter, and response converter)
are placed in the same file. If you clear the checkbox Generate all to driver, you can specify a
different file to contain each converter program, or you can clear the checkbox that precedes a
converter program's name to cause the wizard not to generate that converter program.
b. In the WSDL and XSD tab:
i) In the WSDL file container field, specify the folder and subfolder in which you want the WSDL
and XSD files to be generated.
ii) In each of the input fields WSDL file name, Request XSD file name, and Request XSD file
name, type the name that you want to use for the file. Clear the checkbox that precedes the
request XSD file name or the response XSD file name to cause the wizard not to generate that
file.
c. Click Finish.

The Create New Service Interface (bottom-up) wizard generates the specified output.

Building the XML converters

The XML converters consist of multiple programs that must be compiled and statically linked together
with the converter driver program as the main entry point. Using the z/OS projects perspective create a
remote project that refers to the target system for your Web service. In order to build the XML converters,
a version of Enterprise COBOL that supports XML parsing (version 3.1 or later) is required. Copy the XML
converter files to a remote z/OS system, using the Remote Systems view in the z/OS Projects perspective
(or, you can generate the files directly to the remote system from within the Enable Enterprise Web
Service wizards). Browse for the XML Converter files in the Remote Systems view and add them to the
remote project. Edit the properties of the remote project to reflect the compile and link options specific
to your z/OS system account. The target load library for the remote project should be in the DFHRPL
concatenation of the target CICS region. When the converter programs are generated into separate files,
nominate the converter driver as the main entry point and right-click the remote project to open the
menu. Select rebuild project from the menu. The results of the build, including the compilation listings,
will appear in the remote project.

Deploying the Web service artifacts to CICS

This topic describes how to deploy the Web service artifacts to CICS

120 Developer for z/OS: Welcome and Getting Started

Setting up a CICS Web services provider PIPELINE
A TCPIPSERVICE resource using the HTTP protocol and listening on the desired port must be created and
installed. First, create a PIPELINE resource that uses the previously created TCPIPRESOURCE. Within the
PIPELINE resource definition, the WSDir or "pickup" directory must be defined which enables auto-install
of Web services directly from WSBind files.
You can find detailed information on setting up a provider type PIPELINE in the CICS 3.1 documentation.

Moving generated artifacts to the host system

While building the XML converter programs, you deployed the XML converter load module to the host
system. You now need to transmit the remaining artifacts, the WSBind and WSDL to the WSDir or "pickup"
directory for the CICS PIPELINE under which the Web service will be installed. The "pickup" directory
exists in an HFS on the target system.
Note: Both the WSBind and WSDL files are sensitive to codepage translation. Since the WSBind is in
EBCDIC and the WSDL declares a UTF-8 encoding declaration, you must transmit these files in binary
mode to the host system.

Auto-installing the Web service

After having transmitted the WSBind and WSDL to the PIPELINE pickup directory, you can do an auto-
install if all of the fields on the advanced tab of the WSBind properties page in Developer for z/OS are
completed correctly. You can then issue a

CEMT PERFORM PIPELINE(pipelinename) SCAN

If this completes successfully you should see a new WEBSERVICE resource created by doing a

CEMT INQUIRE WEBSERVICE(*)

The name of the WEBSERVICE is derived from the first 31 characters of the WSBind file name. If you do a

CEMT INQUIRE URIMAP(*)

you will also see that a URIMAP resource is automatically created. The URIMAP resource maps a local
URI to WEBSERVICE resource. By default full WSDL validation is turned off (for performance reasons). To
turn it on you can do a

CEMT SET WEBSERVICE(webservicename)

and change "novalidation" to "validation". Doing this causes CICS to use the provided WSDL to do full
validation of SOAP requests and responses related to this particular WEBSERVICE resource. The location
of the WSDL that CICS uses for validation is visible when viewing a WEBSERVICE resource. If the WSDL
specified in the WSBind file is not found at the expected location in the filesystem, the WSDL entry in the
WEBSERVICE resource will be empty or blank.

Manually installing the Web service

The manual install is recommended for cases where it is not possible to know all of the necessary details
to populate the advanced tab of the WSBind properties page. The WSBind and WSDL need to be moved to
the pickup directory.
The details of creating URIMAP and WEBSERVICE resources manually are explained in depth in the CICS
documentation.

Getting started 121

 Related concepts

“Artifacts necessary to enable a Web service under CICS” on page 117

“Creating and deploying CICS Web
services artifacts” on page 117

Related tasks

“Creating Web service artifacts for CICS” on page 118

Enabling the catalog example for Web services using Developer for z/OS
You can use Enterprise Service Tools to generate XML conversion artifacts that utilize the CICS vendor
interface to provide conversion services of request and response SOAP messages for the catalog manager
COBOL application.

This section describes how to enable one of the functions of the base application as a Web service. This
Web service, named inquireSingle, provides a Web service client with the ability to query individual items
in the catalog.

Generating Web services artifacts for the inquireSingle Web service

The copy book containing the combined interface definition for the catalog manager is located in the
CICS samples dataset with member name DFH0XCP1. The inquireSingle Web service uses a subset of the
interface definition which can be found in a separate copy book DFH0XCP4.

You can run the Create New Service Interface (bottom-up) wizard against either of these copy books,
keeping in mind that if you choose to go with DFH0XCP1 you should make sure on the first page of
the wizard (entitled Language structures) to select the redefinition CA-INQUIRE-SINGLE REDEFINES
CA-REQUEST-SPECIFIC and all of its child elements.
Note: Filler items are not displayed.
One of the benefits of using Enterprise Service Tools is support for the REDEFINES modifier. You do not
have to factor out your interface definition into separate copy books for each redefinition.
The Create New Service Interface (bottom-up) wizard expects that all imported COBOL language
structures have a level 01 containing element declared. You must add the declaration 01 DFH0XCMN
to the top of whichever copy book you decide to use. The name of the level 01 is important in this case so
that the root element name used by the XML converters matches what is expected by the CICS Web client
for the catalog application.
See “Locating the CICS application source and copy books” on page 118 for how to access the copy books
mentioned in the workspace.
After the source for the copy books is in the workspace, see “Generating the Web services artifacts
conversion artifacts” on page 118 for details on how to generate the XML converters, driver, and WSBind
and WSDL files, using the following inputs to the Create New Service Interface (bottom-up) wizard.
Follow these steps to use the Create New Service Interface (bottom-up) wizard:
1. Verify that the Navigator view is open. If the Navigator view is not open, follow these steps to open the
Navigator view:
a. In the menu bar of the workbench, select Window > Show View > Other. The Show View wizard
opens.
b. In the Show View wizard, expand General, select Navigator, and click OK.
The Navigator view opens.

122 Developer for z/OS: Welcome and Getting Started

2. Start the Enterprise Service Tools Wizard Launchpad:
a. In the Navigator view, right-click DFH0XCP1.cbl.
b. Select Enable Enterprise Web Service.
The Enterprise Service Tools Wizard Launchpad opens.
3. Launch the Create New Service Interface (bottom-up) wizard:
a. In the Enterprise Service Tools Wizard Launchpad, make these selections and click Start:
Runtime: Web Services for CICS
Scenario: Create New Service Interface (bottom-up)
Conversion type: Compiled XML Conversion
The Create New Service Interface (bottom-up) wizard opens.
4. Enter the following values for each page of the wizard. If a value is not specified for a particular input
field or list box selection, then use the default value already displayed for that field or list box.
a. On the Language structures page:
Request language structure: CA-INQUIRE-SINGLE
Response language structure: CA-INQUIRE-SINGLE
b. On the Generation Options XML Converters tab:
Service program name: DFH0XCMN
Request Codpage: Codepage of your CICS system
Host Codepage: Codepage of your CICS system
Response Codepage: Codepage of your CICS system
c. On the Generation Options WSDL and XSD tab Endpoint URI field, specify http://
yourserver:yourport/exampleApp/inquireSingle.
d. On the Web Services for CICS Basic Options tab WSBind file name field, specify
inquireSingle.
e. On the File, data set, or member selection XML Converters tab:
Converter driver file name: DFHXCP4D
Request Converter file name: DFHXCP4I
Response Converter file name: DFHXCP4O
f. On the File, data set, or member selection WSDL and XSD tab WSDL file name field, specify
inquireSingle.
The Create New Service Interface (bottom-up) wizard generates the specified output.

Deploying and installing the inquireSingle Web service

This topic describes how to deploy and install the inquireSingle Web service.

After generating the converters in “Generating Web services artifacts for the inquireSingle Web service”
on page 122, refer to following sections to deploy and install the inquireSingle Web service:
1. To build the converters and deploy the load module to the host system, see “Creating Web service
artifacts for CICS” on page 118.
2. To deploy the WSBind and WSDL files to the "EXPIPE01" PIPELINE WSDir (pickup directory), see
“Deploying the Web service artifacts to CICS” on page 120.
3. To install the new Web service and check if it is in service, see “Deploying the Web service artifacts to
CICS” on page 120.

You can now invoke the inquireSingle Web service from the web client.

Getting started 123

 Combined interface definition DFH0XCP1
This topic contains a listing of the input and output interface definitions from the CICS samples dataset
with the member name DFH0XCP1.

>> 01 DFH0XCMN.

* Catalogue COMMAREA structure

03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2).
03 CA-RESPONSE-MESSAGE PIC X(79).
03 CA-REQUEST-SPECIFIC PIC X(911).
* Fields used in Inquire Catalog
03 CA-INQUIRE-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-LIST-START-REF PIC 9(4).
05 CA-LAST-ITEM-REF PIC 9(4).
05 CA-ITEM-COUNT PIC 9(3).
05 CA-INQUIRY-RESPONSE-DATA PIC X(900).
05 CA-CAT-ITEM REDEFINES CA-INQUIRY-RESPONSE-DATA
OCCURS 15 TIMES.
07 CA-ITEM-REF PIC 9(4).
07 CA-DESCRIPTION PIC X(40).
07 CA-DEPARTMENT PIC 9(3).
07 CA-COST PIC X(6).
07 IN-STOCK PIC 9(4).
07 ON-ORDER PIC 9(3).
* Fields used in Inquire Single
03 CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC.
05 CA-ITEM-REF-REQ PIC 9(4).
05 FILLER PIC 9(4).
05 FILLER PIC 9(3).
05 CA-SINGLE-ITEM.
07 CA-SNGL-ITEM-REF PIC 9(4).
07 CA-SNGL-DESCRIPTION PIC X(40).
07 CA-SNGL-DEPARTMENT PIC 9(3).
07 CA-SNGL-COST PIC X(6).
07 IN-SNGL-STOCK PIC 9(4).
07 ON-SNGL-ORDER PIC 9(3).
05 FILLER PIC X(840).
* Fields used in Place Order
03 CA-ORDER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-USERID PIC X(8).
05 CA-CHARGE-DEPT PIC X(8).
05 CA-ITEM-REF-NUMBER PIC 9(4).
05 CA-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(888).

Description of the catalog manager application

This topic and its subtopics describe the CICS catalog manager example application.

Components of the base application

This topic describes the components of the base application.

Table 13. Application Components

Type Comment

Member name in SDFHSAMP

DFH0XCMN Cobol Source Source code for the catalog
manager application
DFH0XVDS Cobol Source Source code for the VSAM data-
store module
DFH0XSDS Cobol Source Source code for the stubbed
data-store module

124 Developer for z/OS: Welcome and Getting Started

Table 13. Application Components (continued)
Type Comment

Member name in SDFHSAMP

DFH0XSOD Cobol Source Source code for the stubbed
version of the order dispatch
module
DFH0XWOD Cobol Source Source code for the order
dispatch module that makes an
outbound Web service request
DFH0XODE Cobol Source Source code for the stubbed
version of the order dispatch
endpoint
DFH0XSSM Cobol Source Source code for the stubbed
version of the stock manager
module
DFH0XGUI Cobol Source Source code for the BMS
interface controller application
DFH0XCFG Cobol Source Source code for the application
configuration module
DFH0XCP1 Copybook Cobol copybook definition for
catalog manager inquire and
place order operations
DFH0XCP2 Copybook Cobol copybook definition for
dispatch order and stock
manager operations
DFH0XCP3 Copybook Cobol copybook definition for the
inquire list operation
DFH0XCP4 Copybook Cobol copybook definition for the
inquire single operation
DFH0XCP5 Copybook Cobol copybook definition for the
place order operation
DFH0XCP6 Copybook Cobol copybook definition for the
dispatch order operation
DFH0XCP7 Copybook Cobol copybook definition that is
mapped to a SOAP request for
the dispatch order operation
DFH0XCP8 Copybook Cobol copybook definition that is
mapped to a SOAP response for
the dispatch order operation
DFH0XM1 Copybook Cobol copybook for BMS
interface
DFH0XM2U Copybook Customized Cobol copybook for
BMS inquire interface
DFH0XM3 Copybook Cobol copybook for BMS
interface to configuration module

Getting started 125

 Table 13. Application Components (continued)
Type Comment

Member name in SDFHSAMP

DFH0XS1 BMS Mapset BMS Mapset for application user
interface
DFH0XS2 BMS Mapset BMS Mapset for the inquire
operation of the application user
interface
DFH0XS3 BMS Mapset BMS Mapset for the configuration
module

Table 14. CICS Resource Definitions

Resource name Resource type Comment
EXAMPLE CICS Resource definition group CICS resource definitions
required for the example
application
EGUI TRANSACTION Transaction to invoke program
DFH0XGUI to start the BMS
interface to the application
(Customizable)
ECFG TRANSACTION Transaction to invoke the
program DFH0XCFG to start
the example configuration BMS
interface (Customizable)
EXMPCAT FILE File definition of the EXMPCAT
VSAM file for the application
catalog (Customizable)
EXMPCONF FILE File definition of the EXMPCONF
application configuration file.

The catalog manager program

The catalog manager is the controlling program for the business logic of the example application, and all
interactions with the example application pass through it.

To ensure that the program logic is simple, the catalog manager performs only limited type checking and
error recovery.
The catalog manager supports a number of operations. Input and output parameters for each operation
are defined in a single data structure, which is passed to and from the program in a COMMAREA.

COMMAREA structures
This topic describes the COMMAREA structures.

* Catalogue COMMAREA structure

03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2).
03 CA-RESPONSE-MESSAGE PIC X(79).
03 CA-REQUEST-SPECIFIC PIC X(911).
* Fields used in Inquire Catalog
03 CA-INQUIRE-REQUEST REDEFINES CA-REQUEST-SPECIFIC.

126 Developer for z/OS: Welcome and Getting Started

 05 CA-LIST-START-REF PIC 9(4).
05 CA-LAST-ITEM-REF PIC 9(4).
05 CA-ITEM-COUNT PIC 9(3).
05 CA-INQUIRY-RESPONSE-DATA PIC X(900).
05 CA-CAT-ITEM REDEFINES CA-INQUIRY-RESPONSE-DATA
OCCURS 15 TIMES.
07 CA-ITEM-REF PIC 9(4).
07 CA-DESCRIPTION PIC X(40).
07 CA-DEPARTMENT PIC 9(3).
07 CA-COST PIC X(6).
07 IN-STOCK PIC 9(4).
07 ON-ORDER PIC 9(3).
* Fields used in Inquire Single
03 CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC.
05 CA-ITEM-REF-REQ PIC 9(4).
05 FILLER PIC 9(4).
05 FILLER PIC 9(3).
05 CA-SINGLE-ITEM.
07 CA-SNGL-ITEM-REF PIC 9(4).
07 CA-SNGL-DESCRIPTION PIC X(40).
07 CA-SNGL-DEPARTMENT PIC 9(3).
07 CA-SNGL-COST PIC X(6).
07 IN-SNGL-STOCK PIC 9(4).
07 ON-SNGL-ORDER PIC 9(3).
05 FILLER PIC X(840).
* Fields used in Place Order
03 CA-ORDER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-USERID PIC X(8).
05 CA-CHARGE-DEPT PIC X(8).
05 CA-ITEM-REF-NUMBER PIC 9(4).
05 CA-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(888).

* Dispatcher/Stock Manager COMMAREA structure

03 CA-ORD-REQUEST-ID PIC X(6).
03 CA-ORD-RETURN-CODE PIC 9(2).
03 CA-ORD-RESPONSE-MESSAGE PIC X(79).
03 CA-ORD-REQUEST-SPECIFIC PIC X(23).
* Fields used in Dispatcher
03 CA-DISPATCH-ORDER REDEFINES CA-ORD-REQUEST-SPECIFIC.
05 CA-ORD-ITEM-REF-NUMBER PIC 9(4).
05 CA-ORD-QUANTITY-REQ PIC 9(3).
05 CA-ORD-USERID PIC X(8).
05 CA-ORD-CHARGE-DEPT PIC X(8).
* Fields used in Stock Manager
03 CA-STOCK-MANAGER-UPDATE REDEFINES CA-ORD-REQUEST-SPECIFIC.
05 CA-STK-ITEM-REF-NUMBER PIC 9(4).
05 CA-STK-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(16).

Return codes
Each operation of the catalog manager can return a number of return codes.

Code Explanation

Type
General 00 Function completed without error
Catalog file 20 Item reference not found
21 Error opening, reading, or ending
browse of catalog file
22 Error updating file
Configuration file 50 Error opening configuration file
51 Data store type was neither STUB
nor VSAM
52 Outbound Web service switch
was neither Y nor N

Getting started 127

 Code Explanation

Type
Remote Web service 30 The EXEC CICS INVOKE
WEBSERVICE command returned
an INVREQ condition
31 The EXEC CICS INVOKE
WEBSERVICE command returned
an NOTFND condition
32 The EXEC CICS INVOKE
WEBSERVICE command returned
a condition other than INVREQ or
NOTFND
Application 97 Insufficient stock to complete
order
98 Order quantity was not a positive
number
99 DFH0XCMN received a
COMMAREA in which the CA-
REQUEST-ID field was not set
to one of the following: 01INQC,
01INQS, or 01ORDR

INQUIRE CATALOG operation

This operation returns a list of up to 15 catalog items, starting with the item specified by the caller.

Input parameters

CA-REQUEST-ID
A string that identifies the operation. For the INQUIRE CATALOG command, the string contains
"01INQC"
CA-LIST-START-REF
The reference number of the first item to be returned.

Output parameters
CA-RETURN-CODE
CA-RESPONSE-MESSAGE
A human readable string, containing "num ITEMS RETURNED" where num is the number of items
returned.
CA-LAST-ITEM-REF
The reference number of the last item returned.
CA-ITEM-COUNT
The number of items returned.
CA-CAT-ITEM
An array containing the list of catalog items returned. The array has 15 elements; if fewer than 15
items are returned, the remaining array elements contain blanks.

128 Developer for z/OS: Welcome and Getting Started

INQUIRE SINGLE ITEM operation
This operation returns a single catalog item specified by the caller.

Input parameters

CA-REQUEST-ID
A string that identifies the operation. For the INQUIRE SINGLE ITEM command, the string contains
"01INQS"
CA-ITEM-REF-REQ
The reference number of the item to be returned.

Output parameters
CA-RETURN-CODE
CA-RESPONSE-MESSAGE
A human readable string, containing RETURNED ITEM: REF=item-reference' where item-
reference is the reference number of the returned item.
CA-SINGLE-ITEM
An array containing in its first element the returned catalog item.

PLACE ORDER operation

This operation places an order for a single item. If the required quantity is not available a message is
returned to the user. If the order is successful, a call is made to the Stock Manager informing it what item
has been ordered and the quantity ordered.

Input parameters

CA-REQUEST-ID
A string that identifies the operation. For the PLACE ORDER operation, the string contains '01ORDR'
CA-USERID
An 8-character user ID which the application uses for dispatch and billing.
CA-CHARGE-DEPT
An 8-character department ID which the application uses for dispatch and billing.
CA-ITEM-REF-NUMBER
The reference number of the item to be ordered.
CA-QUANTITY-REQ
The number of items required.

Output parameters
CA-RETURN-CODE
CA-RESPONSE-MESSAGE
A human readable string, containing 'ORDER SUCCESSFULLY PLACED'.

DISPATCH STOCK operation

This operation places a call to the stock dispatcher program, which in turn dispatches the order to the
customer.

Input parameters

CA-ORD-REQUEST-ID
A string that identifies the operation. For the DISPATCH ORDER operation, the string contains
'01DSPO'

Getting started 129

 CA-ORD-USERID
An 8-character user ID which the application uses for dispatch and billing.
CA-ORD-CHARGE-DEPT
An 8-character department ID which the application uses for dispatch and billing.
CA-ORD-ITEM-REF-NUMBER
The reference number of the item to be ordered.
CA-ORD-QUANTITY-REQ
The number of items required.

Output parameters
CA-ORD-RETURN-CODE

NOTIFY STOCK MANAGER operation

This operation takes details of the order that has been placed to decide if stock replenishment is
necessary.

Input parameters

CA-ORD-REQUEST-ID
A string that identifies the operation. For the NOTIFY STOCK MANAGER operation, the string contains
'01STKO'
CA-STK-ITEM-REF-NUMBER
The reference number of the item to be ordered.
CA-STK-QUANTITY-REQ
The number of items required.

Output parameters
CA-ORD-RETURN-CODE

BMS presentation manager

The presentation manager is responsible for all interactions with the end user via 3270 BMS panels. No
business decisions are made in this program.

Data handler
The data handler provides the interface between the catalog manager and the data store.

The example application provides two versions of the data handler:

• The first version uses a VSAM file as the data store.
• The second version is a dummy program that always returns the same data on an inquire and does not
store the results of any update requests.

Dispatch manager
The dispatch manager is responsible for dispatching the order to the customer once the order has been
confirmed.

The example application provides two versions of the dispatch manager program:
• The first version is a dummy program that returns a correct response to the caller, but takes no other
action.
• The second version is a Web service requester program that makes a request to the endpoint address
defined in the configuration file.

130 Developer for z/OS: Welcome and Getting Started

Order dispatch endpoint
The order dispatch program is a Web service provider program that is responsible for dispatching the item
to the customer.

In the example application, the order dispatcher is a dummy program that returns a correct response
to the caller, but takes no other action. It makes it possible for all configurations of the example Web
services to be operable.

Stock manager
The stock manager is responsible for managing the replenishment of the stock.

In the example program, the stock manager is a dummy program that returns a correct response to the
caller, but takes no other action.

Application configuration
The example application includes a program that lets you configure the base application.

File structures and definitions

The CICS catalog manager example application uses two VSAM files: the catalog file which contains the
details of all items stocked and their stock levels, and the configuration file which holds user-selected
options for the application.

Catalog file
The catalog file is a KSDS VSAM file which contains all information relating to the product inventory.

Records in the file have the following structure:

Name COBOL data type Description

WS-ITEM-REF-NUM PIC 9(4) Item reference number
WS-DESCRIPTION PIC X(40) Item description
WS-DEPARTMENT PIC 9(3) Department identification
number
WS-COST PIC ZZZ.99 Item price
WS-IN-STOCK PIC 9(4) Number of items in stock
WS-ON-ORDER PIC 9(3) Number of items on order

Configuration file
The configuration file is a KSDS VSAM file which contains information used to configure the example
application.
The configuration file is a KSDS VSAM file with 3 distinct records, General Information, Outbound URL,
and Catalog file information, as shown in the following tables:

Table 15. General information record

Name COBOL data type Description
PROGS-KEY PIC X(9) Key field for the general
information record, containing
'EXMP-CONF'

Getting started 131

 Table 15. General information record (continued)
Name COBOL data type Description
filler PIC X
DATASTORE PIC X(4) A character string that specifies
the type of data store program to
be used. Values are:
'STUB'
'VSAM'

filler PIC X
DO-OUTBOUND-WS PIC X A character that specifies
whether the dispatch manager is
make an outbound Web service
request. Values are:
'Y'
'N'

filler PIC X
CATMAN-PROG PIC X(8) The name of the catalog manager
program
filler PIC X
DSSTUB-PROG PIC X(8) The name of the dummy data
handler program
filler PIC X
DSVSAM-PROG PIC X(8) The name of the VSAM data
handler program
filler PIC X
ODSTUB-PROG PIC X(8) The name of the dummy order
dispatcher module
filler PIC X
ODWEBS-PROG PIC X(8) The name of the outbound Web
service order dispatcher program
filler PIC X
STKMAN-PROG PIC X(8) The name of the stock manager
program
filler PIC X(10)

Table 16. Outbound URL record

Name COBOL data type Description
URL-KEY PIC X(9) Key field for the general
information record, containing
'OUTBNDURL'
filler PIC X

132 Developer for z/OS: Welcome and Getting Started

 Table 16. Outbound URL record (continued)
Name COBOL data type Description
OUTBOUND-URL PIC X(255) Outbound URL for the order
dispatcher Web service request

Table 17. Catalog file information

Name COBOL data type Description
URL-FILE-KEY PIC X(9) Key field for the general
information record, containing
'VSAM-NAME'
filler PIC X
CATALOG-FILE-NAME PIC X(8) Name of the CICS FILE resource
used for the catalog file

Customizing CARMA using plug-in projects tutorial

CARMA can be customized by using Eclipse plug-in projects. The following modules provide you with a
starting point in developing your own CARMA customization.
Note: Module 1-5 and 9 are independent of each other and can be completed in any order. Modules 6-8
build off of Module 5 and each other, as a result they must be completed in order. Module 9 involves some
host configuration of the Sample PDS RAM, which might involve special permissions.

Learning objectives
After completing the modules in this module, you will have an understanding of the following concepts:
• Creating an Developer for z/OS Eclipse plug-in project
• Using the plug-in Manifest Editor to add dependencies and extensions
• Use the plugin.xml file to modify extensions and their attributes
• Create packages, classes, and folders within an Eclipse plug-in project
• Create and modify Java classes to add enhanced functionality to the plug-ins

Time required
The time that is required to complete these modules vary. Each module contains an approximate time
required.

Prerequisites
To successfully complete the modules, you should have:
• Developer for z/OS installed on your local workspace
• Access to a z/OS host system and any required authentication
• Basic understanding of Java coding and debugging
Tip:
Eclipse plug-in development requires the Plug-in Development perspective. This perspective is not
enabled by default in Developer for z/OS. To enable it:
1. Open the Preferences window.
2. Navigate to General > Capabilities.
3. On the Capabilities page, expand Development and select Plug-in Development.
4. Click Apply and Close.

Getting started 133

 To open the perspective, click Window (on Windows) or IBM Developer for z/OS (on macOS) >
Perspective > Open Perspective > Other, and then select Plug-in Development and click Open.

Create an Eclipse plug-in project

Customizing CARMA is done by creating Eclipse plug-in projects that handle the particular enhancement.
This lesson guides you through creating an Eclipse plug-in project that is specialized for this CARMA
tutorial.
To create a new Eclipse plug-in project:
1. Start Developer for z/OS.
2. Select the Desired workspace.
3. If you are starting with a clean workspace, minimize the Welcome Screen, and Create the new
Developer for z/OS Eclipse plug-in Project from the current perspective by selecting File > New >
Project.
4. In the new project wizard, select Plug-in Development > Plug-in Project. Click Next.
5. Enter the appropriate name for the project in the Project Name text field. Click Next.
6. Ensure that the names in the Plug-in ID and the Plug-in Name text fields correlate with those
specified with the particular plug-in project.
7. Keep the default settings under Plug-in Options and Rich Client Application. Click Next.
8. Clear the checkbox, Create a plug-in using one of the templates, and click Finish.
9. If you are prompted to open the Plug-ins Perspective, select Yes to open that perspective now.
The wizard closes and you see your project in the Package Explorer view of the Plug-ins Perspective.

Run and debug the plug-in project

This lesson teaches you how to run and debug the plug-in you created in the previous exercise.
To run and debug the plug-in:
1. In the Package Explorer view, make sure that there are no errors in your Eclipse plug-in project. If
there are, follow the little, red X, error icon down through the directories to the source, and correct
these errors before proceeding.
2. In the main menu bar, select the drop-down arrow beside the Run button, and select Run
Configurations from the menu.

a) To debug, you would select the down button beside the Debug icon , select Debug
Configurations, and follow the rest of the steps.
3. From the left menu, double-click on the Eclipse Application option. A new run configuration opens,
this might take a little while to open.
4. Select the Configurations tab from the top tab menu.
5. Mark the checkbox, Clear the configuration area before launching. If this is not set, Developer for
z/OS does not know how to pick up the new plug-ins you developed.
6. Click Apply to save the changes.
7. You can select which plug-ins you have developed to run in the testing workbench. To do this, select
the Plug-ins tab from the top menu.
8. In the Launch With dropdown menu, select the option: plug-ins selected below only.
9. In the panel below the dropdown menu will be a list of the various plug-ins associated with Developer
for z/OS. Find the directory that is labeled Workspace. Check the plug-ins that you want included in
your build. Clear those you do not want to be included in the build.
10. Click Run. This launches a second instance of Developer for z/OS in a testing workspace.
Note: If you have already started Developer for z/OS in the testing workspace once before, be sure to
close it out before you start it again, else you get an error.

134 Developer for z/OS: Welcome and Getting Started

Return to the exercise summary for steps on how to determine if your CARMA plug-in ran successfully.

Module 1: Adding decorators to the user interface

This module takes you through the steps to add a decorator, or image overlay, to the CARMA members
shown in the CARMA Repositories view.
You add a lock decorator to display on members when they are locked and a question mark decorator to
display on members when members need their metadata synchronized.
Note: The sample RAMs that come with Developer for z/OS do not support the Lock function. You want to
use this exercise with a RAM that supports the Lock function.

Learning objectives
After completing the lessons in this exercise, you will be able to:
• Create a Developer for z/OS plug-in Project
• Import graphics to the plug-in project
• Modify the Java Activator class, so the plug-in is able to find the necessary graphics
• Create a Java Decorator class and write code to display the appropriate graphic
• Modify the plugin.xml file to provide the org.eclipse.ui.decorators extension point
• Run and debug the sample plug-in

Time required
This module takes approximately 30 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Created an Eclipse plug-in project
• An accessible directory containing a graphic of a lock and a question mark, or other representative
graphics, with dimensions of approximately 11 x 13 pixels

Lesson 1: Create an icons folder and import sample graphics

In this lesson, you create an icons folder and import the sample graphics to use as your decorators.
Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:
• Project Name: com.ibm.carma.plugin.decorators
• ID: com.ibm.carma.plugin.decorators
• Name: Decorators
To create the icons folder and import the graphics:
1. In the Package Explorer view, right-click on the com.ibm.carma.plugin.decorators plugin-
project you created, and select New > Folder.
2. In the New Folder dialog box that opens, select com.ibm.carma.plugin.decorators as the
parent folder.
3. Enter icons as the name of the folder, and click Finish. You should see the icons folder appear under
your com.ibm.carma.plugin.decorators project.
4. Right click the icons folder, and select Import.
5. In the Import dialog box that opens, select General > File System. Click Next.
6. In the From Directory text field, either enter in the path name of the directory containing your graphics
or click Browse and browse for the appropriate directory. Once a directory has been specified, it
should open in the panels below the text field.

Getting started 135

 7. Select either the complete directory from the left panel or just the individual files from the right panel
to be imported. When all files that you want to import have been marked with a check, click Finish.
In the Package Explorer view, expand com.ibm.carma.plugin.decorators >icons, and you should
see the graphics that you imported.

Lesson 2: Modify the Java Activator class

The Activator class is created automatically with the creation of the Eclipse plug-in project. This lesson
guides you through the steps to modify the Activator class to display the appropriate graphics as
decorators.
To update the Java Activator class:
1. In the Package Explorer view, navigate to the Activator class by expanding
com.ibm.carma.plugin.decorators > src > com.ibm.carma.plugin.decorators, and
double-click on the Activator.java file to open it in the editor.
2. Scroll down, and below the getDefault method, add the following method to the Java Activator
class:

public static ImageDescriptor getImageDescriptor(String path)

{
return imageDescriptorFromPlugin(PLUGIN_ID, path);
}

This method provides a way for the Activator class to find the graphics you plan to use as
decorators.
3. Ensure that the following classes and packages are included in the import commands. An easy way of
doing this is by right-clicking within the editor, and selecting Source > Organize Imports and verifying
all the listed import statements were included. You can also manually enter the import commands at
the top of the class with any other import commands.

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.ui.plugin.AbstractUIPlugin;
import org.osgi.framework.BundleContext;

4. Save the Activator.java file.

Lesson 3: Create a Java Decorator class

You create the Decorator class in this lesson, which will later be responsible for placing the graphics as
decorators on CARMA members.
To create the Java Decorator class:
1. Start by setting the appropriate dependencies for the Eclipse plug-in project. Right click the
com.ibm.carma.plugin.decorators Eclipse plug-in project, and select PDE Tools > Open
Manifest. This opens the Plug-in Editor in the main editor window.
2. From the bottom menu of tabs in the Plug-in Editor, select Dependencies. This opens the plug-in
dependency editor.
3. Ensure the following plug-ins are listed in the first panel:
• org.eclipse.ui
• org.eclipse.core.runtime
• com.ibm.carma.core(9.0.0)
4. If any of the plug-ins are missing, click the Add button. In the Plug-in Selection dialog box that
opens, enter the name of the missing plug-in in the filter text field. When it appears in the panel,
select it, and click OK.
5. Now, you create a new package to contain the Decorator class. Placing relevant
Java classes together in packages helps to keep your code organized. Right click the
com.ibm.carma.plugin.decorators plug-in project, and select New Package.
6. In the New Java Package dialog box that opens, enter decorator in the Name text field, and click
Finish. You should see the package you just created appear in the src directory.

136 Developer for z/OS: Welcome and Getting Started

 7. Right click the decorator package you created, and select New > Class.
8. In the Name text field, enter Decorator.
9. Next, to the Superclass text field, click Browse to browse for the class that your Descriptor class
extends.
10. In the Superclass Selection dialog box that opens, enter LabelProvider in the text field. Select
the class that is part of the org.eclipse.jface.viewers package, and click OK.
11. Next, to the Interfaces panel, click Add. In the Implemented Interfaces Selection dialog box that
opens, enter ILightweightLabelDecorator, and select the matching item that appears. Click
OK.
12. Click Finish to close out of the New Java Class dialog box.
You should see the Decorator class appear under the decorator package and the source code for the
Decorator class open in the editor.

Lesson 4: Develop the code for the Java Decorator class

In this lesson, you develop code for the Decorator class that handles the decorating of the CARMA
resources in the CARMA Repositories view.
To add this functionality to theDecorator class:
1. Between the class declaration and the decorate method, add two static ImageDescriptor
variables that contain the ImageDescriptor path names for the lock decorator and the question
mark decorator. For example:

private static ImageDescriptor lock;

private static ImageDescriptor question;
static
{
lock = Activator.getImageDescriptor("icons/lock.jpg");
question = Activator.getImageDescriptor("icons/question_mark.jpg");
}

Tip: The file names you provide should correspond with the names of the icons you imported into the
icons folder.
2. Add the code to the body of the decorate() method that adds a locked suffix to the CARMA
members and containers when they are locked, or decorate them with question marks if the
MemberInfoMap has not been set. The following pseudocode demonstrates this:

if( resource is CARMA Container or CARMA Member){

if( Member Info Map Set){
if( Member Info Map Set contains the Key “locked”){
if( value for the key “locked” is not empty string){
decorate CARMA Member/Container with lock decorator
Add “locked” suffix to CARMA Member/Container }
} else {
decorate CARMA Member/Container with question decorator
}
}
}

Use the following example sample code to implement this functionality.

public void decorate(Object resource, IDecoration decoration)

{
if(resource instanceof CARMAContainer || resource instanceof CARMAMember)
{
CARMAResource myResource = (CARMAResource) resource;
if(myResource.isSetMemberInfoMap())
{
try
{
EMap myMap = myResource.getMemberInfoMap();
if(myMap.containsKey("locked"))
{
String value = myMap.get("locked").toString();
if( !value.equals(""))
{
decoration.addOverlay(lock);

Getting started 137

 if(myResource instanceof CARMAMember)
decoration.addSuffix(" - (Member Locked)");
else
decoration.addSuffix(" - (Container Locked)");
}
}
}
catch(NotSynchronizedException e)
{
//TODO handle exception
}
}
else
{
decoration.addOverlay(question);
decoration.addSuffix(" - (Not Syncronized)");
}
}
}

3. Automatically import the classes and types.

Ensure that the following imports are included:

import com.ibm.carma.plugin.decorators.Activator;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.viewers.IDecoration;
import org.eclipse.jface.viewers.ILightweightLabelDecorator;
import org.eclipse.jface.viewers.LabelProvider;
import com.ibm.carma.model.CARMAMember;
import com.ibm.carma.model.CARMAContainer;
import com.ibm.carma.model.CARMAResource;
import com.ibm.carma.transport.NotSynchronizedException;
import org.eclipse.emf.common.util.EMap;

4. If the com.ibm.carma.model part of your import packages statement is still underlined in red, then
right-click on it and select the quick fix, "Add com.ibm.carma.model to list of imported packages."
5. Save the source and debug any errors.

Lesson 5: Modify the plugin.xml file

In this lesson, you modify the plugin.xml file to provide the org.eclipse.ui.decorators extension
point and attributes.
To modify the plugin.xml file:
1. In the Package Explorer view, right-click on the CARMA Decorators plug-in project, and select PDE
Tools > Open manifest. The Plug-in Editor opens.
2. To extend the plugin.xml file, select the Extensions tab from the list of tabs at the bottom.
3. Click Add. In the New Extension dialog box that opens, enter org.eclipse.ui.decorators in the
Extension Point filter text field.
4. From the results that are found, select the one that matches the filter text exactly, and click Finish.
5. The Plug-in Editor should still be open. At the bottom, select the plugin.xml tab from the bottom
menu of items. You might have to select the >> button to make this option visible. The plugin.xml
file should open in the Plug-in Editor.
6. The following skeleton code is provided already:

<plugin>
<extension
point="org.eclipse.ui.decorators">
</extension>
</plugin>

Between the open and close extension tags, place the following code:

<description
adaptable="true"
class="decorator.Decorator"
id="com.ibm.carma.ui.ftt.sample"
label="Sample Decorator"
lightweight="true"
location="BOTTOM_RIGHT"

138 Developer for z/OS: Welcome and Getting Started

 state="true">
</description>
<enablement>
<or>
<objectClass name="com.ibm.carma.model.CARMAMember"/>
<ObjectClass name="com.ibm.carma.model.CARMAContainer"/>
</or>
</enablement>

Note: The information that follows the class attribute tells the plug-in what class to use and where
it is located. This location should correspond with the pkg_you_created.class_name. If you
followed the names that are provided in this tutorial, then your package and class name should be
the same as those given.
7. Click save and resolve any errors.

Summary: Module1
This module has guided you through the steps to create an Eclipse plug-in project that adds decorators to
CARMA members and containers, which are locked or unsynchronized.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Make sure that you are connected to your host system. Create a new connection if needed.
2. Open the CARMA Repositories view by selecting from the file menu, Window (on Windows) or IBM
Developer for z/OS (on macOS) > Show View > CARMA Repositories View.
3. Expand a RAM that supports the Lock option.
4. Right click a CARMA member within that RAM, and select Lock.
5. The CARMA member should lock, and your lock icon appear in the lower-right hand corner of the
CARMA member icon. For example:

Module 2: Hide or disable CARMA actions with plug-in extension points

There are several ways to develop CARMA plug-ins. This module explores hiding and disabling CARMA
actions using plug-in extension points.

Learning objectives
After completing the lessons in this module, you will be able to:
• Create an Eclipse plug-in project
• Add dependencies to a plug-in project
• Add and modify extensions that are associated with a plug-in project
• Run and debug a plug-in project

Time required
This module takes approximately 30 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Created an Eclipse plug-in project

Lesson 1: Add the plug-in dependencies

This lesson teaches you how to add required dependencies to your plug-in project.
The plug-in dependencies are a list of any other plug-ins that contribute code to your plug-in project or
that must be on your project's classpath in order to compile.

Getting started 139

 Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:
• Project Name: com.ibm.carma.plugin.disable.options
• Plug-in ID: com.ibm.carma.plugin.disable.options
• Plug-in Name: Disable Options
To add dependencies to your plug-in:
1. Make sure that you are in the Plug-in Development perspective.
2. In the Package Explorer view, right click your Eclipse plug-in project, and select PDE Tools > Open
Manifest. The Plug-in Editor opens.
3. From the tabs at the bottom of the Plug-in Editor, select Dependencies.
4. Check to see whether the dependency, com.ibm.carma.ui is listed in the left panel. If not, click the
Add button to the right of the left panel. In the text field of the Plug-in Selection dialog box, enter in
the name of the plug-in as filter text.
5. Select the first plug-in that appears matching the filter text, and click OK.
You have now added com.ibm.carma.ui to your list of dependencies. You should see it listed in the left
panel with any other default dependencies.

Lesson 2: Use the plug-in editor to add and modify extensions

Plug-in project extensions can be used to modify actions that are associated with CARMA. The extension
that you will create in this lesson will be used to disable the Delete and Open With menu options.
You will also specify the particular RAM with which you would like to associate your plug-in project.
To create this extension:
1. From the Plug-in Editor, click the Extensions tab from the bottom menu of options.
2. Click the Add button to the right of the panel. In the New Extension dialog box that opens, enter
com.ibm.carma.ui.ramBrowserActions in the text field.
3. Select the extension matching your search query, and click Finish. You see the extension that is listed
in the panel under All Extensions. Beneath the extension listing, you should also see a (ram) listing
similar to:
4. Highlight the RAM. To the right, you should see two text fields appear, ramId and uniqueId.
5. If you know the particular ID for the RAM you would like to modify with your plug-in, you can enter
that in the ramId text field.
6. If you know which RAM you would like to modify with your plug-in, but do not know the particular ID
associated with it, use the uniqueId option.
a) Open the CARMA Repositories view by selecting from the file menu, Window (on Windows) or
IBM Developer for z/OS (on macOS) > Show View > CARMA Repositories. You can have to select
Other and browse for the particular view if it is not in the main menu.
b) If you do not have a connection to your host system already setup, you have to do that now. Open
the Remote Systems Explorer view and follow the instructions in Connecting to CARMA.
c) Expand the host system, and right-click on the particular RAM you want to modify with your
plug-in. For this tutorial, the examples use the sample PDS RAM. Select Properties.
d) In the dialog box that opens, take note of the Unique Identification value.
e) Return to the Plug-in Editor and in the uniqueId text field, enter the unique identification value
that you just found.
7. Below the ram is an action. Highlight the action, and you will see two drop-down menus appear on
the right-hand side, actionId and state.
a) The values available for actionId correspond to the five actions that can be performed in CARMA:
new, open, open with, remove, and refresh.

140 Developer for z/OS: Welcome and Getting Started

 b) The values available for state correspond to the three states that these actions can be in:
enabled, disabled, and hidden.
8. With the first action item under the RAM highlighted, use the dropdown actionId menu to
select: com.ibm.carma.action.remove. Use the dropdown state menu to select: disable. This
disables the Delete option in the RAM's pop-up menu.
9. Next, you want to create a second action. In the left panel of the Plugin Editor, click the Add button.
10. In the New Extension dialog box that appears, enter the filter
com.ibm.carma.action.ramBrowserAction. Select the matching extension, and click Finish.
11. Expand the extension, and update the ramId or uniqueId to the appropriate value for your RAM.
12. Select the action below the ram. On the right-hand side, in the actionID dropdown menu, select
com.ibm.carma.action.openWith. In the state dropdown menu, select disabled. This allows
for the option Open With to be seen by the user, but will not allow it to be selected.
13. Save the changes that you made in the Plug-in Editor and resolve any errors.

Summary: Module 2
This module has guided you through the steps to create a plug-in project to disable the Delete and Open
With menu options on CARMA Members.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Make sure that you are connected to your host system.
2. Open the CARMA Repositories view.
3. Expand the RAM that you developed your plug-in to modify down to an individual member within the
RAM and right-click it.
4. Right click any member within that RAM. The menu that appears should not allow you to select the
Delete or Open With options.

Module 3: Disable CARMA actions programmatically

This module guides you through how to hide or disable CARMA actions programmatically. The result of
this module is the same as Module 2.

Learning objectives
After completing this module you should know how to:
• Create an Eclipse plug-in project
• Define the plug-in extensions and dependencies
• Modify the Activator class
• Run or Debug the Eclipse plug-in project

Time required
This module should take approximately 30 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Created an Eclipse plug-in project

Getting started 141

 Lesson 1: Define the extensions and dependencies for the plug-in project
This lesson guides you through defining extension points, including dependencies, creating an extension
to the plug-in, and modifying the Activator class to customize the menu options.
Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:
• Project Name: com.ibm.carma.plugin.disable.programatically
• ID: com.ibm.carma.plugin.disable.programatically
• Name: CARMA_Modify_Actions Plug-in
To define the extensions and dependencies for your plug-in project:
1. Make sure that you are in the Plug-in Development perspective.
2. In the Package Explorer view, right click com.ibm.carma.plugin.disable.programatically,
your plug-in project, and select PDE Tools > Open Manifest. The Plug-in Editor opens.
3. From the list of tabs at the bottom of the Plug-in Editor, select Extensions.
4. Click the Add button on the Extensions page.
5. In the New Extension dialog box that opens, type the extension name, org.eclipse.ui.startup
in the Extension Point filter text field.
6. When this extension appears in the panel below, select it, and click Finish. You will see the extension
appear in the panel of the Extension page of the Plug-in Editor.
7. You do not need to specify any attributes to this extension. Adding this extension just tells Eclipse to
run your plug-in when the workbench starts up.
8. While you are still in the Plug-in Editor, you should also add the dependencies that the plug-in needs.
To do this, select the Dependencies tab from the bottom menu of tabs.
9. In the left panel, Required Plug-ins, make sure com.ibm.carma.ui is listed. If it is not, click Add,
and filter for the particular plug-in. Select it, and click Finish.

Lesson 2: Modify the Java Activator class

To reflect the modifications of the states and actions available to the CARMA member or container, you
need to modify the Activator class.
To modify the Java Activator class:
1. Open the Java Activator class. In the Package Editor
view, expand com.ibm.carma.plugin.disable.programatically > src >
com.ibm.carma.plugin.disable.programatically. Double-click on the Activator.java
class to open it.
2. Scroll down in the Activator class and find the start method declaration.
You want to provide code that modifies the RAMActionRegistry, where the available actions and
their states are stored, to disable the Open With option. You will also must identify the particular RAM
to which you want the modifications to be applied. This can be done with either the RAM's uniqueId
or the ramId. The following example assumes that you will use the RAM's uniqueId.
Sample code:

public void start(BundleContext context) throws Exception

{
RAMActionRegistry myRegistry = RAMActionRegistry.getRegistry();
myRegistry.setUniqueRAMActionState("com.ibm.carma.sample.PDSRAM",
"com.ibm.carma.action.remove",
RAMActionState.DISABLED);
}

Note: If you choose to use the ramId as the RAM identification, then change the fourth line of code to:

myRegistry.setRAMActionState("ramId",
"com.ibm.carma.action.openWith",
RAMActionState.DISABLED);

142 Developer for z/OS: Welcome and Getting Started

 And provide the appropriate ramId.
3. Import the needed classes and packages which tells the Activator class where to find the other
types you mentioned in your code. Right click in the editor and select Source > Organize Imports, and
verify the packages to import.
Ensure that the following packages were imported, add any to the import commands at the top of the
Activator class if necessary:

import org.eclipse.ui.plugin.AbstractUIPlugin;
import org.osgi.framework.BundleContext;
import com.ibm.carma.ui.view.*;

4. Save the source and resolve any errors.

Summary: Module 3
This module has guided you through the steps to create a plug-in project and modify the actions available
in the menu when you right-click on CARMA members in the CARMA Repositories view.

Results:
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Make sure that you are connected to your host system
2. Open the CARMA Repositories view
3. Expand the RAM that you developed your plug-in to modify down to the individual CARMA members.
4. Right click any member within that particular RAM.
5. Attempt to select the Delete option. You should be unable to select this option.

Module 4: Adding an action to CARMA menu using plug-in extension points

In this module, you create a Browse Member Action, and add it to the CARMA menu using an extension
point. This new action allows for a CARMAMember to be selected and opened in a read-only mode.
Note: This module involves more Java coding and debugging than the previous modules.

Learning objectives
After completing this module, you should be able to:
• Create an Eclipse plug-in project
• Create Java classes to add items to the menu
• Add the action to an extension point
• Run and debug the plug-in project

Time required
This module should take approximately 45 minutes to complete.

Prerequisites
To successfully complete this module, you should have:
• Created an Eclipse plug-in project

Lesson 1: Create the BrowseMemberAction class

In this lesson, you create the Java class responsible for handling the actions that are associated with
browsing a CARMA member.
Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:

Getting started 143

 • Project Name: com.ibm.carma.plugin.browse
• ID: com.ibm.carma.plugin.browse
• Name: Browse Menu
To create the BrowseMemberAction Java class:
1. First, you want to set up the dependencies that are associated with this plug-in project. In the
Package Explorer view, right click com.ibm.carma.plugin.browse, your plug-in project, and
select PDE Tools > Open Manifest.
2. In the Plug-in Editor that opens, select Dependencies tab from the bottom menu of options.
3. In the left panel, check to seewhet the following dependencies are listed:
• org.eclipse.ui.ide
• org.eclipse.core.resources
• com.ibm.carma.core
• com.ibm.carma.ui
If these dependencies are not listed, then click Add button, filter for each, and add them.
4. Save your changes.
5. Now, you create the BrowseMemberAction class. In the Package Explorer view, right click your
plug-in project and select New > Package.
6. In the New Java Package dialog box that opens, enter in browse as the package name. Expand
com.ibm.carma.plugin.browse > src, and you should see the package that is listed.
7. Right click the browse package you created, and select New > Class. The New Java Class dialog box
opens.
8. In the Name text field, enter BrowseMemberAction.
9. To the right of the Interfaces panel, select the Add button. The Implemented Interfaces Selection
dialog box opens.
10. In the text field, enter in IViewActionDelegate to filter for the appropriate interface. Select it
when it appears in the Matching items panel below the text field, and click OK.
11. Click Finish to close the New Java Class dialog box and create the Java class, which opens in the
editor.

Lesson 2: Develop code for the BrowseMemberAction class

This lesson guides you through the steps to develop the needed code for the BrowseMemberAction
class.
To develop the code for the BrowseMemberAction class:
1. Open the BrowseMemberAction class in the editor if it is not already open. In the Package
Explorer expand com.ibm.carma.plugin.browse > src > browse, and double-click on the
BrowseMemberAction class.
2. The first method that you will write is selectionChanged.
This method is used to control the items for which the browse action is enabled. In the following
example code, the browse member action is enabled only on CARMA members and only for one
member at a time. Because of this, checks must be performed before enabling the browser action. The
following pseudocode demonstrates this:

if (more than one item is selected)

disable action;

if (item selected is CARMA member)

enable action
else
disable action

Use the following sample code to implement this method:

144 Developer for z/OS: Welcome and Getting Started

 public void selectionChanged(IAction action, ISelection selection) {
Iterator i = ((IStructuredSelection) selection).iterator();

// by default assume false

action.setEnabled(false);

if( ((IStructuredSelection) selection).size() != 1){

return;
}

while (i.hasNext()) {
Object next = i.next();
if (next instanceof CARMAMember) { // the element is a member
//remember the item selected so if the action is run it knows
//which item to run the action against
this.itemSelected = (CARMAMember) next;
} else {
this.itemSelected = null;
return;
}
}

// if we passed the test...then enable the action

action.setEnabled(true);
}

3. The second method that you write is the run method.

This method is called when you want to invoke the BrowserMemberAction. To open the
CARMAMember in browse-only mode, the workbench needs to download the contents of the file from
the RAM into the IFile, a type of file in Eclipse, set the IFile properties to read-only, and then open
the IFile. The following pseudocode demonstrates this:

Get the CARMAMember the user wants to browse;

Create an IFile that represents the CARMAMember;
Download contents of the CARMAMember into the IFile;
Set the properties of the IFile to read-only;
Call Eclipse to open the IFile;

Use the following sample code to implement this method:

public void run(IAction action) {

//if itemSelected is null then the browse action was run
//on something that is not a CARMA Member, this should never happen
if (this.itemSelected != null) {
//Get the name of the CARMA Member
String memberName = itemSelected.getFileName();

//Create a temporary location on the workstation to hold the

//local cache of the file
IWorkspace myWorkspace = ResourcesPlugin.getWorkspace();
IWorkspaceRoot myRoot = myWorkspace.getRoot();

IProject myResource = myRoot.getProject("/BootCampTemp");

//If the temporary directory that holds the temporary files

//does not exist create it
if( !myResource.exists() ){
try{
myResource.create(new NullProgressMonitor());
} catch(Exception e){
e.printStackTrace();
}
}

//If the temp location which is a project is not open

//open it
if( !myResource.isOpen()){
try{
myResource.open(new NullProgressMonitor());
} catch(Exception e){
e.printStackTrace();
}
}

//Make sure the temporary space is of the right type and exists
if (myResource instanceof IContainer && myResource.exists()) {
IContainer myContainer = (IContainer) myResource;

Getting started 145

 //Create the IFile in the temporary location
final IFile myFile = myContainer.getFile(new Path(memberName));

//Create the job that will get the contents of the file
GetContentsJob myJob = new GetContentsJob("CRAJOB1", itemSelected);

//Run the Job

myJob.schedule();

try{
InputStream myStream = null;
while( (myStream = myJob.getStream()) == null){
}

//Copy the contents into the IFile

if(!myFile.exists())
myFile.create(myStream, true, new NullProgressMonitor());
} catch(Exception e){
e.printStackTrace();
}

//Set the file's attributes to read-only and open the file

Display display = Display.getDefault();
display.syncExec(new Runnable() {
public void run() {
IWorkbenchPage page =
PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage();

try {
ResourceAttributes myAttributes = myFile.getResourceAttributes();
if(myAttributes == null){
myAttributes = new ResourceAttributes();
}
//setting the attributes to readonly
myAttributes.setReadOnly(true);
try{
myFile.setResourceAttributes(myAttributes);
} catch(Exception e){
e.printStackTrace();
}
//opening the file in browse mode
IDE.openEditor(page, myFile, true);
} catch (PartInitException e) {
//TODO handle exception
System.out.println(e);
}
}
});
}
}
}

4. Verify that all the packages the class needs are imported. Add any that are listed below but are not
already included in the import statements:

import java.io.InputStream;
import java.util.Iterator;

import org.eclipse.core.resources.IContainer;
import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IWorkspace;
import org.eclipse.core.resources.IWorkspaceRoot;
import org.eclipse.core.resources.ResourceAttributes;
import org.eclipse.core.resources.ResourcesPlugin;
import org.eclipse.core.runtime.NullProgressMonitor;
import org.eclipse.core.runtime.Path;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.swt.widgets.Display;
import org.eclipse.ui.IViewActionDelegate;
import org.eclipse.ui.IViewPart;
import org.eclipse.ui.IWorkbenchPage;
import org.eclipse.ui.PartInitException;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.ide.IDE;

146 Developer for z/OS: Welcome and Getting Started

 import com.ibm.carma.model.CARMAMember;
import com.ibm.carma.ui.job.GetContentsJob;

5. Save the source and debug any errors.

Lesson 3: Add the action to an extension point

Adding extension points to the BrowserMemberAction lets Developer for z/OS know where to
incorporate your plug-in into the rest of the system.
To add the action to an extension point:
1. In the Plug-in Development perspective, right click your Eclipse plug-in project in the Package
Explorer view and select PDE Tools > Open Manifest to open the Plug-in Editor.
2. From the bottom menu of tabs, select Extensions. Click the Add button.
3. In the New Extension dialog box that opens, type the filter text, org.eclipse.ui.popupMenus in
the Extension Point filter text field.
4. Highlight the extension point that matches your filter, and click Finish. You should see the extension
that you selected added to the list of extensions in the left panel on the Extensions page.
5. Now, select the plugin.xml tab from the menu options at the bottom of the Plug-in Editor.
6. Replace the existing code with the following:

<plugin>
<extension
id="carma.bootcamp.ui.actions"
point="org.eclipse.ui.popupMenus">
<objectContribution
id="CARMA.Bootcamp.browse"
objectClass="com.ibm.carma.model.CARMAMember">
<action
class="browse.BrowseMemberAction"
id="BootCamp.browse"
label="Browse Member"
menubarPath="open">
</action>
</objectContribution>
</extension>
</plugin>

Summary: Module 4
In this module, you have created a plug-in that would allow you to open a particular CARMAMember in a
read-only environment.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Make sure that you are connected to your host system.
2. Open the CARMA Repositories view.
3. Expand a RAM on your host system down until you see the individual members.

Module 5: Creating a new CARMA view using the existing CARMA context
provider
This module will take you through the steps of creating a new CARMA view using the default CARMA
context provider.

Learning objectives
After completing this module, you should be able to:
• Create an Eclipse plug-in project
• Import images into the plug-in project

Getting started 147

 • Create Java classes to implement the enhanced functionality offered by the plug-in
• Run and debug the plug-in project

Time required
This module should take approximately 30 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Created an Eclipse plug-in project
• A image with dimensions of 16 x 16 pixels to use as the icon for your view

Lesson 1: Set up dependencies, import images, and create the Java class
This lesson shows you how to add the dependencies, import images, and to create a Java class to handle
the view.
Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:
• Project Name: com.ibm.carma.plugin.view
• Plug-in ID: com.ibm.carma.plugin.view
• Plug-in Name: New View
To perform the setup for this plug-in:
1. In the Plug-in Development perspective, right-click on the com.ibm.carma.plugin.view plug-in
project and select, PDE Tools > Open Manifest. Find the Dependencies tab at the bottom of the
Plug-in Editor.
2. Select the Dependencies tab, and click the Add button. In the dialog box that opens, filter for each of
the following if they are not already listed:
• org.eclipse.ui.ide
• com.ibm.carma.ui
For each dependency, as it appears in the list, highlight it, and click OK.
3. Next, you want to import your files from the local source to the project. In the Package Explorer
view, right click com.ibm.carma.plugin.view, and select New > Folder. In the New Folder dialog
box that appears, select CARMA Developer View as the parent folder, and enter icons as the
name. Click Finish.
You should see the icons directory appear under the com.ibm.carma.plugin.view plug-in
project.
4. To import the icons, right-click on the icons directory and select Import. In the Import dialog box
that opens, select General > File System. Click Next.
5. Browse for the particular directory where your images are stored. Once you have selected the
directory, the directory structure is shown in the left panel below, and the individual files are shown
in the right. Mark the files or directories you want to import with a check mark, and click Finish to
import the files.
Back in the Package Explorer view, if you expand the icons directory, you should see your selected
files now within the directory.
6. Finally, you want to set up the Java class that handles the view. Start by creating a package to contain
the file; right-click on com.ibm.carma.plugin.view, and select New > Package.
7. In the New Java Package dialog box that opens, enter view as the package name.
You should see the package appear under the src directory of the plug-in project.
8. To add the Java class, right-click on the view package you just created, and select New > Class.
The New Java Class dialog box opens.

148 Developer for z/OS: Welcome and Getting Started

 9. In the Name text field, enter the class name as CARMADeveloperView.
10. To the left of the Superclass text field, click Browse. The Superclass Selection dialog box opens.
11. In the text field, enter BaseCarmaBrowser. Select the class that matches your filter, and click OK.
12. Back in the New Java Class view, click Finish to create the Java class. The dialog box closes and the
class opens in the editor.

Lesson 2: Write the Java code to handle the CARMADeveloperView

You need to implement two methods to control the CARMA view, createFramelist and
createViewer.
To implement this code, you use the FrameList and Viewer class. The FrameList is a list of frames
that allow navigation through the view. The Viewer contains the structure that you see in the view.
For the frame list, you create a frame list for a tree viewer, which looks similar to the default CARMA
Repositories view. For the viewer, you set the content provider to the default CARMA Content Provider.
To implement the Java methods:
1. Open the CARMADeveloperView class by expanding, in the Package Explorer view,
com.ibm.carma.plugin.view > view, and double-clicking CARMADeveloperView.
2. In the editor, you want to add the createFrameList method.
This method first creates the TreeViewerFrameSource, then create a new FrameList, and then
set the source to the TreeViewerFrameSource. Use the following sample code to implement this
functionality:

protected FrameList createFrameList()

{
/*
* This code manages the front-back buttons in the view
* Will take the default tree frame listener from eclipse.
*/
TreeViewerFrameSource source = new TreeViewerFrameSource((TreeViewer)getViewer());

/* This is a TreeViewer.
* Create the frame list.
*/
FrameList frameList = new FrameList(source);
source.connectTo(frameList);

return frameList;
}

3. Next, you want to overwrite the createViewer so that it creates the CARMATreeViewer with the
default CARMAContentProvider. Use the following sample code to implement this functionality:

protected StructuredViewer createViewer(Composite parent)

{
/*
* Create the structure that you want to be present in the view here.
* The example uses the CARMA tree model like the CARMA Repositories view.
*/
CARMATreeViewer viewer = new CARMATreeViewer(parent);
return viewer;
}

4. Ensure that all classes and packages that are mentioned in the source are included in the import
commands at the beginning of the class. The easiest way to do this is to right click in the editor and
select Source > Organize Imports.
Be sure to verify that the following classes were all imported:

import org.eclipse.jface.viewers.StructuredViewer;
import org.eclipse.jface.viewers.TreeViewer;

import org.eclipse.swt.widgets.Composite;

import org.eclipse.ui.views.framelist.FrameList;
import org.eclipse.ui.views.framelist.TreeViewerFrameSource;

Getting started 149

 import com.ibm.carma.ui.view.BaseCarmaBrowser;
import com.ibm.carma.ui.widget.CARMATreeViewer;

5. Save your changes and debug any errors.

6. Finally, you must add the appropriate extension and configure it. In the Plug-in Editor,
select the Extensions tab at the bottom of the editor. Click Add. Filter for the extension:
org.eclipse.ui.views. When it appears, select it, and click OK. You should see the extension
that is listed in the left panel.
7. Open the plugin.xml tab from the bottom menu of tabs. Configure the plugin.xml file as follows:

<plugin>
<extension
point="org.eclipse.ui.views">
<category
name="BootCamp"
id="carma.bootcamp.ui">
</category>
<view
name="CARMA Developer View"
icon="icons/sample.gif"
category="carma.bootcamp.ui"
class="view.CARMADeveloperView"
id="view.CARMADeveloperView">
</view>
</extension>
</plugin>

Note: The attributes that are used in the plugin.xml file are described in more detail below:
• Category: the attributes that are used with this markup correspond to the labeling and view of the
Show View dialog box
– Name: the name that appears as the enclosing category in the Show View dialog box
– Id: the id of the category that the view should display under when searching for it in the Show
View dialog box
• View: the attributes that are used with this markup correspond to the labeling, appearance, and
location of the source for the actual view you created
– Name: the label that is given to the view, this name appears in the tab that is associated with the
view, and also in the Show View dialog box
– Icon: the image to associate with the view, this is shown in the tab associated with the view, and
also next to its label in the Show View dialog box
– Category: the id of the category that the view should display under when searching for it in the
Show View dialog box
– Class: the Java class you wrote that controls the view, you should provide the enclosing package
as well
– Id: the unique identifier for the view

Summary: Module 5
This module has guided you through the steps to create a plug-in project that creates the CARMA
Developer View.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Open the CARMA Developer View by selecting from the main file menu, Window (on Windows) or
IBM Developer for z/OS (on macOS) > Show View > Other.
2. In the Show View dialog box that opens, enter the filter text: CARMA Developer View. You should
see this view appear.
3. Select it, and click OK.

150 Developer for z/OS: Welcome and Getting Started

4. Your CARMA Developer View opens. If you followed the tutorial exactly, it looks almost exactly like
the CARMA Repository View except the icon in the tab is different.

Module 6: Creating and using a custom label provider to customize a view

This module guides you through the steps of creating and using a custom label provider to customize the
CARMA view you created in Module 5.
The Label Provider controls how each item in a view is displayed. It controls the string and icon that is
displayed to identify the item. This module adds text to the CARMA Repository Manager that displays
when CARMA is connected to that RAM. It also changes the icon that is displayed for COBOL CARMA
Members.

Learning objectives
After completing the lessons in this module you should be able to:
• Build extra functionality on top of an existing Eclipse plug-in project
• Develop Java code to control the labels in the CARMA Developer View
• Run or debug the modified plug-in project

Time required
This module should take approximately 45 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Completed Exercise 5: Creating a new CARMA view using the existing CARMA context provider
• An image to use as an icon for COBOL members

Lesson 1: Set up the plug-in project from Exercise 5

This exercise builds onto of the plug-in project that you created in Exercise 5. If you have not completed
Exercise 5, do so before beginning this lesson. This lesson guides you through the steps in modifying the
plug-in that is created in Exercise 5 for Exercise 6.
To modify the plug-in project from Exercise 5:
1. Star Developer for z/OS in the Plug-in Development perspective. In the Package Explorer view, right-
click the com.ibm.carma.plugin.view plug-in project, and select PDE Tools > Open Manifest.
This opens the Plugin Manifest Editor
2. From the bottom list of tabs, select Dependencies.
3. Make sure the dependency, com.ibm.carma.ui is listed in the left panel of dependencies. If it is not,
click the Add button and use the text field to filter for the dependency. When it appears, highlight it,
and click OK.
You should see the dependency added to the list of dependencies that are listed on the left panel.

Lesson 2: Create the CustomLabelProvider class

In this lesson, you create a CustomLabelProvider class that handles how each item in the CARMA
Developer View is displayed.
To create the CustomLabelProvider class:
1. To start, add the getImageDecorator() method to the Activator class. Expand
com.ibm.carma.plugin.view > src > com.ibm.carma.plugin.view, and double-click on the
Activator class. It should open in the editor
2. Add the following method to the Activator class:

public static ImageDescriptor getImageDescriptor(String path)

{

Getting started 151

 return imageDescriptorFromPlugin(PLUGIN_ID, path);
}

This static method allows the image descriptor or decorator to be retrieved from the appropriate
location in the plug-in project.
3. Add the following import at the top of the Activator class: import
org.eclipse.jface.resource.ImageDescriptor;. Save and debug any errors in the source.
4. Next, you want to create the CustomLabelProvider class. In the Package Explorer view, expand
the com.ibm.carma.plugin.view plug-in project. Right click the view package you created in
Exercise 5, and select New > Class. The New Java Class dialog box opens.
5. In the Name text field, enter CustomLabelProvider.
6. Select the Browse button to the right of the Superclass text field. In the Superclass Selection
dialog box that opens, type CARMALabelProvider as the filter text, select the class from the list of
matching items, and click OK.
7. Mark the Constructors from superclass and Inherited abstract methods checkboxes. Click Finish to
close the New Java Class dialog box and create the Java class.

Lesson 3: Develop the code for the CustomLabelProvider class

In this lesson, you develop the code for the CustomLabelProvider class, which controls how the items
in the CARMA Developer View are displayed.
To develop this code:
1. Open the ContextLabelProvider class. From the Package Explorer view, navigate
com.ibm.carma.plugin.view > src > view, and double-click on the CustomLabelProvider
class.
2. First, you want to override the getText() method. This method should check to see if a repository
manager is connected and add a label to the repository manager that shows the connected/
disconnected state.
The following is example pseudocode for the getText() method:

if(the element passed to getText is a repository manager)

{
if(the repository manager is connected)
{
add connected label to the repository manager;
}
else
{
add disconnected label to the repository manager;
}
}

Use the following example source to override the getText() method:

public String getText(Object element)

{
String textLabel = super.getText(element);
if(element instanceof RepositoryManager)
{
if( ((RepositoryManager)element).isConnected())
{
textLabel += " - (Connected)";
}
else
{
textLabel += " - (Disconnected)";
}
}

return textLabel;
}

3. The next method that you will want to override is the getImage() method. This method should
change the icon display for COBOL members.

152 Developer for z/OS: Welcome and Getting Started

 The following is pseudocode for the getImage() method:

if( the element passed getImage is a CARMA Member)

{
if( the CARMA Member's extension is "cbl" )
{
decorate the CARMA Member;
}
}

The following is example source code for the getImage() method:

public Image getImage(Object element)

{
if(element instanceof CARMAMember)
{
if(((CARMAMember) element).getLocalExtension().equalsIgnoreCase("cbl"))
{
//replace the parameter of getImageDescriptor() with the path to your particular
icon
ImageDescriptor myDescriptor = Activator.getImageDescriptor("icons/cobol.gif");
return myDescriptor.createImage();
}
}
return super.getImage(element);
}

Note: The path name passed as a parameter to the getImageDescriptor method should match
your directory and image name.
4. Finally, make sure that you have the following packages that are listed in your import statements at the
top of your Java class. Add any that are missing:

import com.ibm.carma.plugin.view.Activator;

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.swt.graphics.Image;

import com.ibm.carma.model.*;
import com.ibm.carma.ui.view.*;

5. Save the source and debug any errors.

Lesson 4: Edit the CARMADeveloperView class to use the CustomLabelProvider

Now that you have created the CustomLabelProvider, you want the CARMADeveloperView class to
use it. You have to edit the createViewer method to add the CustomLabelProvider object to the
viewer.
To edit the CARMADeveloperView:
1. Open the CARMADeveloperView, by double-clicking on the class in the view package of the
com.ibm.carma.plugin.view Eclipse plug-in project. It opens in the editor.
2. You want to modify the createViewer method so that it creates the view from the content provider
and then adds the CustomLabelProvider to the viewer.
Ensure that your method looks the same as the source code below.

protected StructuredViewer createViewer(Composite parent)

{
/*
* Create the structure you want to be present in the view here.
* For this tutorial, the CARMA tree model will be used, similar to what is used in the
CARMA Repositories view.
*/
CARMATreeViewer viewer = new CARMATreeViewer(parent);
viewer.setLabelProvider(new CustomLabelProvider());
return viewer;
}

3. Save the source and debug any errors.

Getting started 153

 Summary: Module 6
In this module, you have modified the Eclipse plug-in project from Module 5 to customize the view of
COBOL container members with a decorator, and label each RAM with either Connected or Disconnected
tags.

Results
You can run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Open the z/OS Projects perspective.
2. Open the CARMA Developer view by selecting from the main file menu, Window (on Windows) or IBM
Developer for z/OS (on macOS) > Show View > CARMA Developer. The view should open.
3. Expand the host system. You should see each of the RAMs on the host system marked with a label " -
(Disconnected)."
4. Right click one of the RAMs containing .cbl files and select Connect. When CARMA has connected to
the RAM, you should see the label change to " - (Connected)."
5. Lastly, expand the RAM until you see the individual COBOL members within the RAM. The icon for
these members should be the particular image that you specified.

Module 7: Creating a new view using a custom context provider

This module takes you through the steps of creating and using a custom context provider to customize a
CARMA view. The ContextProvider, which you create, controls how the context of the CARMA model
is displayed in the view. This module demonstrates how to customize the context provider to filter out
repository instances that are PDS part of the build process (that is, the listing, object, and load PDS). It
will also only show PDS that are associated with CARMA, the PDS that have a CARMA token in the name.

Learning objectives
After completing the lessons that make up this module, you should be able to:
• Modify an existing Eclipse plug-in project
• Create and modify a Java class to perform the enhancements that are offered by the plug-in
• Run or debug the plug-in project

Time required
This module should take approximately 30 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Successfully completed Exercise 5 and Exercise 6

Lesson 1: Create the CustomContextProvider class

This lesson builds on top of the plug-in project you created in Exercise 5, and modified in Exercise
6. In this lesson, you create the CustomContextProvider class, which can be customized to fit
any viewer you want. For example, if you want the field viewer, the context provider can extend the
CarmaFieldsContentProvider.
To create the CARMAContextProvider class:
1. Make sure that you are in the Plug-in Development perspective. In the Package Explorer view,
expand the com.ibm.carma.plugin.view plug-in project that you used for Exercises 5 and 6.
2. Right click the view package containing the CARMADeveloperView and CustomLabelProvider
classes, and select New > Class.
3. In the New Java Class dialog box that opens, enter CustomContextProvider in the Name text
field.

154 Developer for z/OS: Welcome and Getting Started

4. Click the Browse button to the right of the Superclass text field. In the Superclass Selection dialog
box that opens, enter the filter text, CARMATreeContentProvider. Select the matching class, and
click OK.
5. Mark the checkbox, Constructors from superclass, and click Finish. The New Java Class dialog
closes and the CustomContentProvider class is created.
6. Start by ensuring the following imports are included in the Java class. Add any that are missing.

import java.util.Vector;

import com.ibm.carma.model.RepositoryInstance;
import com.ibm.carma.ui.view.CarmaTreeContentProvider;

7. You want to modify the getChildren method to change the content that is provided to the viewer.
This method is where the provider can control which items are sent to the viewer when expanding the
RAM. For this tutorial, you implement the getChildren method to return only repository instances
that have a CARMA token in the name and are not a listing, object, or load repository instance.
The following pseudocode demonstrates what the getChildren method should do:

get the children of the object that would normally be returned;

for each child
{
if(the child is a repository instance)
{
if(the repository instance has a CARMA token and is not a listing, object, or load
repository instance)
add the child to the list of displayable children;
}
}

Use the following is sample code for the getChildren method:

public Object[] getChildren(Object parent)

{
Object[] children = super.getChildren(parent);

//Do not parse non-existant children

if(children == null)
{
return children;
}

Vector<Object> displayChildren = new Vector<Object>();

for(int i = 0; i < children.length; i++)
{
if(children[i] instanceof RepositoryInstance)
{
RepositoryInstance myContainer = (RepositoryInstance) children[i];
if (myContainer.getName().contains("CARMA"))
{
displayChildren.add(children[i]);
}
}
else
{
displayChildren.add(children[i]);
}
}
return displayChildren.toArray();
}

8. Save the source and debug any errors.

Lesson 2: Include the CustomContextProvider in the CARMADeveloperView class

In this lesson, you rewrite the createViewer method to include the CustomContentProvider.
To modify the CARMADeveloperView class:
1. Open the CARMADeveloperView class by double-clicking it in its package. The source should open in
the editor.

Getting started 155

 2. Scroll down to the createViewer method and change it so that it uses the
CustomContextProvider. It is helpful to note that the CARMATreeViewer constructor allows for a
context provider to be specified to the viewer.
The following is example sample code:

protected StructuredViewer createViewer(Composite parent)

{
/* Create the structure that you want to be present in the view here.
* For this tutorial, you will use the CARMA tree model, like the repositories view.
*/
CARMATreeViewer viewer = new CARMATreeViewer(parent, new CustomContextProvider());
viewer.setLabelProvider(new CustomLabelProvider());
return viewer;
}

3. Save the source and debug any errors.

Summary: Module 7
In this module, you have modified the Eclipse plug-in project from Modules 5 and 6 to only show those
PDS that are not object, listing, or load repository instances, and those that have to do with CARMA.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Open the z/OS Projects perspective
2. Open the CARMA Developer view by selecting from the main file menu, (on Windows) or IBM
Developer for z/OS (on macOS) > Show View > CARMA Developer. The view should open.
3. In the CARMA Developer view, expand the host system. You should see each of the RAMs on the host
system marked with a label.
4. Right click a particular RAM, select Connect, and expand the RAM once it is connected.
5. When you expand the RAM, you should only see PDS that contain CARMA in their name.

Module 8: Creating a custom menu for a custom view

This module teaches you how to create a custom menu for a custom view.
Note: This module assumes that you have completed Modules 5-7. You are using the Eclipse plug-in
project that you created in those exercises as the foundation for this module.

Learning objectives
After completing the lessons in this module, you should be able to:
• Modify an existing Eclipse plug-in project
• Create and modify Java classes that handle the plug-in enhancement
• Run or debug the plug-in project

Time required
This module should take approximately 30 minutes to complete.

Prerequisites
To successfully complete the lessons in this Module, you should have:
• Successfully completed Exercise 5, Exercise 6, and Exercise 7

156 Developer for z/OS: Welcome and Getting Started

Lesson 1: Create the CustomOpenActionGroup Java class
This lesson guides you through the steps of creating the Java class that is needed to handle the
customized open menu.
The menu you will create is a collection of actions, separators, and action groups that contain a smaller
collection of actions. For this exercise, you will create a class, MainActionGroup that makes up the
menu. You will also create another class, OpenActionGroup that overrides the default open group
option.
To create these classes:
1. You start with the OpenActionGroup class, since the MainActionGroup class needs a custom
open group. In the Package Explorer view, right-click on thecom.ibm.carma.plugin.view Eclipse
plug-in project that you have modified from Exercise 5, and select New > Package.
2. In the New Java Package dialog box that opens enter, menu, as the name of the package, and click
Finish.
3. Now, create the Java class. Right click the menu package, and select New > Class. The New Java
Class dialog box opens.
4. Enter CustomOpenActionGroup as the name of the class.
5. Click the Browse button to the right of the Superclass text field. In the Superclass Selection
dialog box that opens, enter the filter text, OpenActionGroup. Select the class that is part of the
com.ibm.carma.ui.view package, and click OK.
6. Click Finish to close the New Java Class dialog box and create the class.
7. You want to override the fillContextMenu method to provide the custom content of the open
section of the menu. For the open section of the menu, you need to display everything but the
Open and Open With menu selections. The easiest way to do this is to get the default from
OpenActionGroup section and remove the Open and Open With menu selections.
The following pseudocode demonstrates this:

get the default items;

for each item
{
if(item is open or open with)
{
remove it from the list;
}
}

Use the following sample code to implement this functionality:

public void fillContextMenu(IMenuManager menu)

{
super.fillContextMenu(menu);
IContributionItem[] myItems = menu.getItems();
for(int i = 0; i < myItems.length; i++)
{
IContributionItem item = myItems[i];
if(item.getId() != null)
{
if(item.getId().equals(OpenAction.ID) ||
item.getId().equals("com.ibm.carma.ui.openWithSubMenu"))
{
menu.remove(item);
}
}
}
}

8. Automatically import any needed packages and classes. Ensure that all of the following are imported:

import org.eclipse.jface.action.IContributionItem;
import org.eclipse.jface.action.IMenuManager;

import com.ibm.carma.ui.action.OpenAction;
import com.ibm.carma.ui.view.OpenActionGroup;

Getting started 157

 9. Save the source and debug any errors.

Lesson 2: Create the CustomMainActionGroup Java class

This lesson guides you through the steps to create a CustomMainActionGroup class. This class
emulates the functionality of the CARMA default MainActionGroup class. However, instead of
using the default OpenActionGroup, the CustomMainActionGroup class that you create uses the
CustomOpenActionGroup class that you created .
To create the CustomMainActionGroup class:
1. Create a new class by right-clicking on the menu package in the Package Explorer view, and selecting
New > Class.
2. In the New Java Class dialog box that opens, enter CustomMainActionGroup as the name. Click the
Browse button to the right of the Superclass text field. In the Superclass Selection dialog box that
appears, enter the filter, CarmaBrowserActionGroup. Select the matching class that is contained in
the com.ibm.carma.ui.view package, and click OK.
3. Select the Constructors from superclass check box.
4. Click Finish to close the New Java Class dialog and create the class.
5. The first thing that you will want to do is create global variables for a NewMenuActionGroup,
a NavigationActionGroup, a OpenActionGroup, a ConnectionActionGroup, a
DisplayActionGroup, and a PropertyDialogAction, similar to the following sample code:

private NewMenuActionGroup _newMenuActionGroup;

private NavigationActionGroup _navigationActionMenu;
private OpenActionGroup _openActionGroup;
private ConnectionActionGroup _connectionActionGroup;
private DisplayActionGroup _displayActionGroup;
private PropertyDialogAction _propertyAction;

Tip: These variables should be declared at the top of the class before any method declarations.
6. Now you want to override the makeActions method to instantiate the groups and actions
that are needed to fill the menu. With the OpenActionGroup, be sure to instantiate your
CustomOpenActionGroup class instead of the default. Use the following source code:

protected void makeActions()

{
_newMenuActionGroup = new NewMenuActionGroup();
_navigationActionMenu = new NavigationActionGroup(getBrowser());
_openActionGroup = new CustomOpenActionGroup();
_connectionActionGroup = new ConnectionActionGroup(getBrowser());
_displayActionGroup = new DisplayActionGroup(getBrowser());
_propertyAction = new PropertyDialogAction(getBrowser().getViewSite(), getViewer());
}

7. Override the fillContextMenu() method with the updated list of groups, actions, and separators.
To make it look like a pop-up menu, use the same order for adding items to the menu using the
following example code:

public void fillContextMenu(IMenuManager menu)

{
ActionContext myContext = new ActionContext(getViewer().getSelection());
_newMenuActionGroup.getContext();

_newMenuActionGroup.setContext(myContext);
_newMenuActionGroup.fillContextMenu(menu);

_navigationActionMenu.setContext(myContext);
_navigationActionMenu.fillContextMenu(menu);

menu.add(new Separator("open"));
_openActionGroup.setContext(myContext);
_openActionGroup.fillContextMenu(menu);

menu.add(new Separator("refractor"));

menu.add(new Separator("connect"));

_connectionActionGroup.setContext(myContext);

158 Developer for z/OS: Welcome and Getting Started

 _connectionActionGroup.fillContextMenu(menu);
_connectionActionGroup.updateActionBars();

menu.add(new Separator("display"));

_displayActionGroup.setContext(myContext);
_displayActionGroup.fillContextMenu(menu);

menu.add(new Separator(IWorkbenchActionConstants.MB_ADDITIONS));
menu.add(new Separator("project"));
menu.add(new Separator("properties"));
menu.add(_propertyAction);
}

8. Import all needed classes and packages. Ensure that all of the following are included in the import
statements:

import org.eclipse.jface.action.IMenuManager;
import org.eclipse.jface.action.Separator;
import org.eclipse.ui.IWorkbenchActionConstants;
import org.eclipse.ui.actions.ActionContext;
import org.eclipse.ui.dialogs.PropertyDialogAction;

import com.ibm.carma.ui.view.BaseCarmaBrowser;
import com.ibm.carma.ui.view.CarmaBrowserActionGroup;
import com.ibm.carma.ui.view.ConnectionActionGroup;
import com.ibm.carma.ui.view.DisplayActionGroup;
import com.ibm.carma.ui.view.NavigationActionGroup;
import com.ibm.carma.ui.view.NewMenuActionGroup;
import com.ibm.carma.ui.view.OpenActionGroup;

9. Save the source and debug any errors.

Lesson 3: Adding the custom menu to the CARMADeveloperView

This brief lesson walks you through adding the custom menu you created, to the CARMADeveloperView.
You do this by overriding the createAction method.
To add the custom menu to the CARMADeveloperView:
1. Open the CARMADeveloperView class by opening the view package and double-clicking on the
source file. It opens in the editor.
2. Scroll down and create the following method

protected void createActions()

{
setActionGroup(new CustomMainActionGroup(this));
}

This code sets the default action group to the CustomMainActionGroup you created.
3. Add import menu.CustomMainActionGroup; to your list of import statements at the top of the
CARMADeveloperView class.
4. Save the source and debug any errors.

Summary: Module 8
You have modified the Eclipse plug-in project from Module 5-7 to add a custom menu.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Open the CARMA Developer and CARMA Repositories view
2. In one of the views, connect to a particular RAM.
3. Expand the RAM until you can see each of the particular members.
4. Right click any CARMA member in the CARMA Repositories view and in the menu that appears there
should be options to both Open and Delete.

Getting started 159

 5. Right click the same CARMA member in the CARMA Developer view, and in the menu that appears
there should be no option to Open or Delete.

Module 9: Introduction to parameter and action extension points

This module explores the capabilities of CARMA extension points in providing customization to
parameters and actions that are associated with a custom action on a particular RAM.
This module updates and uses the Sample PDS RAM to create a HowTo custom action and associate four
parameters to it.

Learning objectives
After completing the lessons in this module you should be able to:
• Create an Eclipse plug-in project
• Create and define actionValidators, parameterValidators, and customParameterControl
extension points
• Create and develop the necessary classes to add the enhanced functionality to the custom actions
• Run and debug the plug-in project
• Understand the end-result in the plug-in project of using each of the extension points

Time required
This module should take approximately 60 minutes to complete.

Prerequisites
To successfully complete the lessons in this module, you should have:
• Access to modify the Sample PDS RAM on your host system or a systems administrator who can do this
for you
• Basic understanding of RAM Development, found in the CARMA Developer's Guide
• Basic understanding of C coding and debugging is recommended
• Experience submitting JCL jobs to REPRO files

Lesson 1.0: Configure the Sample PDS RAM on the host

The extension points used in this sample ensures that the input is in the permitted format, ensures that
the input will not cause errors, and modifies the view of the custom actions pertaining to a particular RAM.
For this sample, you use the PDS RAM. However, because there are no custom actions that are already
integrated into the Sample PDS RAM, you have to configure the RAM with a new custom action and its four
parameters.
Tip: The lessons pertaining to modifying the Sample PDS RAM might require special permissions on your
host system to access and modify some of the files.

Learning objectives
Though this is not a focal point of the exercise, you should be able to configure a RAM to add custom
actions and parameters.

Time required
This portion of lessons should take approximately 30 minutes to complete.

Prerequisites
A basic understanding of the content in the CARMA Developers Guide is recommended.

160 Developer for z/OS: Welcome and Getting Started

Lesson 1.1: Customize the PDS RAM by adding a custom action and parameters to the model
This lesson will briefly step you through adding the HowTo custom action and its four parameters: value,
string1, string2, and option, to the PDS RAM.
These parameters and actions are added to the PDS RAM by supplying the appropriate information to
the CRA0VDEF file. For more information on the steps in this lesson, see the CARMA Developer's Guide,
Chapter 4. Customizing a RAM API using the CAF.
1. Start by listing the action or actions that you want to extend to the RAM's API. For this sample, you will
add a custom action, HowTo, with the following attributes:
• Name: HowTo
• Description: Provides an example of implementing plug-in projects with extension points
• ActionID: 100
• RAM ID: 00
• Parameter list: value, string1, string2, option
• Return Value list:
Tip: If you are using the shipped Sample PDS with no customization, then the following values for
action id and RAM id should be correct; however, if you have added or removed RAMs, custom actions,
or parameters check to make sure that the action id is the next available action id and the RAM id
corresponds to the Sample PDS RAM. .
2. In the description of the HowTo custom action above, there are parameters and return values listed.
Each of these must be defined within the RAM as well. The descriptions of each are as follows:
• Name: value
• Description: a one-digit numerical value
• Parameter ID: 000
• Ram ID: 00
• Type: string
• Length: 1
• Constant: no
• Default value: none
• Prompt: Enter a one-digit value:
• Name: string1
• Description: a string of text
• Parameter ID: 001
• RAM ID: 00
• Type: string
• Length: 10
• Constant: no
• Default value: none
• Prompt: Enter a short string of text:
• Name: string2
• Description: a string of text
• Parameter ID: 002
• RAM ID: 00
• Type: string
• Length: 10
• Constant: no

Getting started 161

 • Default value: none
• Prompt: Enter a short string of text:
• Name: option
• Description: yes or no option
• Parameter ID: 003
• RAM ID: 00
• Type: string
• Length: 1
• Constant: no
• Default value: none
• Prompt: Yes or No?
3. Knowing the actions, parameters, and descriptions of each helps you create the declarations to include
into the configurations file. Each action and parameter is defined on its own line and its particular
metadata is specified within a predefined byte length.
Tip: You can also define the actions and parameters without using the predefined byte sizes for
metadata by using tabs as a delimiter. Be sure to consult the CARMA Developer's Guide, Chapter 4.
Customizing a RAM API using the CAF for the details of this alternative format.
For this sample, using the predefined byte sizes, the custom HowTo action is declared as:
A00100 000,001,002,003|

For each of the respective parameters, the declaration is:

P00000 STRING 1 N
P00001 STRING 10 N
P00002 STRING 10 N
P00003 STRING 1 N

Note: For both actions and parameters, the first 8 bytes of the record is called the record key.
4. Make sure that there are no active connections between the Sample PDS RAM, CARMA, and the host
system before continuing.
5. You should add this information to FEL.SFELVSM2(CRA0DEF) and ensure that all record keys are
in alphanumeric order. Use the JCL script that is located at FEL.#CUST.JCL(CRA$VDEF) to REPRO
FEL.SFELVSM2(CRA0DEF).
6. Next, for each action and parameter you define in the CRA0VDEF file you must define a corresponding
definition in the CRA0VSTR file containing any language-dependent information about the action or
parameter.
For this sample, the custom action would be defined in the CRA0VSTR like the following:
EN_US 00037A00100 HowTo For demonstration. Does nothing.

For each respective parameter in the sample, the definitions are:

EN_US 00037P00000 value Enter a one-digit numerical value.
EN_US 00037P00001 string1 Enter a short string of text.
EN_US 00037P00002 string2 Enter a short string of text.
EN_US 00037P00003 option Y/N?

Note: For both actions and parameters, the first twenty-one bytes of the record is called the record
key.
7. You should add this information to the FEL.SFELVSM2(CRA0VSTR) file and ensure that all records
are in alphanumeric order. Use the JCL script that is located at FEL.#CUST.JCL(CRA$VSTR) to
REPRO FEL.SFELVSM2(CRA0VSTR).

162 Developer for z/OS: Welcome and Getting Started

Lesson 1.2: Add the performAction function to the PDS RAM to correspond with the custom HowTo action
In the last lesson, you configured the Sample PDS RAM with a HowTo custom action and its four
parameters. In this lesson, you create or modify the function on the host that handles the HowTo action.
The HowTo action was created for demonstrational purposes to display the dialog box to which you
will later apply the actionValidators, parameterValidators, and customParameterControl
extension points. However, for the purposes of this sample, you do not need this action to perform any
action on the host. Therefore, the function that is provided for the HowTo action id on the Sample PDS
RAM does nothing.
1. Open the C file on the host containing the Sample PDS RAM source; it should be
FEL.SFELSAMP(CRASPDS). You can open this file directly in Developer for z/OS.
2. If you have custom actions that are already implemented on the Sample PDS RAM, you want to modify
the performAction function to do nothing if it is passed the HowTo action id and return successful.
Use the following sample code snippet to add this to your performAction function:

if(actionID == 100)
{
return 0;
}

If the HowTo custom action calls the performAction function it will now return successful without
performing any action on the host. Skip steps 3 and 4.
Note: If you have already implemented the performAction function, you should check and make
sure that the actionId 100 has not already been set to another custom action.
3. If you have not implemented any custom actions for the Sample PDS RAM, you will want to implement
the performAction function and have it do the same thing as the snippet of code above does.
Start by adding the following export statement to the preprocessor directives at the top of the C
source: #pragma export(performAction).
4. Next, add the following method to the PDS RAM:

int performAction(int actionID,

char instanceID[256],
char memberID[256],
void** params,
void** customReturn,
char error[256])
{
/*Accept any actionID and return successfully*/
return 0;
}

Note: If you add more custom actions to the PDS RAM later, you will want to specify for each custom
action id what action should be performed, similar to the snippet of code in step 2.
5. Save the source and debug any errors.

Lesson 1.3: Recompile the PDS RAM and verify the HowTo custom action
This lesson guides you through the final steps in adding the custom action and parameters to the Sample
PDS RAM.
1. Be sure that there are no active connections between the Sample PDS RAM, CARMA, and the host
system. Any active connections could cause CARMA or the RAM to act abnormally.
2. Recompile the FEL.SFELSAMP(CRASPDS) member.
3. Restart the server.
4. In the client, reconnect to CARMA and to the Sample PDS RAM.
5. Now, expand the Sample PDS RAM down to a particular CARMA member.
6. When you right-click on the CARMA member, you should be able to select Custom > HowTo.
7. The HowTo action dialog box opens and should have empty text fields and prompts for the four
parameters you defined on the Sample PDS.

Getting started 163

 Lesson 2: Define the dependency and extensions for the plug-in project
In this lesson, you define the dependencies and the three extension points: actionValidators,
parameterValidators, and customParameterControl.
Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:
• Project Name: com.ibm.carma.plugin.howto
• ID: com.ibm.carma.plugin.howto
• Name: HowTo Action
1. Open the Plug-in Manifest Editor by right-clicking on the com.ibm.carma.plugin.howto plug-in
project, and selecting PDE Tools > Open Manifest.
2. Start by adding the dependency. Select the Dependencies tab at the bottom of the Plug-in Manifest
Editor.
3. Click the Add button under the Required Plug-ins panel. The Plug-in Selection dialog box opens.
4. Filter for the com.ibm.carma.ui plug-in, select it when it appears, and click OK.
5. Next, add the extensions to the plug-in project. Select the Extensions tab and filter for each of the
following:
• com.ibm.carma.ui.parameterValidators,
• com.ibm.carma.actionValidators,
• com.ibm.carma.customParameterControls
In the next three lessons, you configure each of the extensions to be associated with the HowTo custom
action and its parameters.

Lesson 3: Configure the com.ibm.carma.ui.parameterValidators Extension

In this lesson, you configure the parameterValidator extension that you defined in the previous
lesson for the plug-in project.
The parameterValidator extension point allows for contributing extensions to validate the value of a
particular parameter as it is being entered by the user. For this sample, the value parameter accepts a
single digit numeric character less than four. You will use the different possible values that the user can
input into the value parameter to display different informational messages to the user and to ensure that
the user enters only numeric characters.
1. Start by first configuring the parameterValidators extension. In the Plug-in Development
perspective, right click the com.ibm.carma.plugin.howto plug-in project and select PDE Tools
> Open Manifest. The Plug-in Editor opens.
2. From the bottom list of tabs select Extensions. On this page, you should see the extensions that
are associated with your plug-in project. Select the (parameterValidator) option below the
com.ibm.carma.ui.parameterValidators extension point. To the right, the Extension Element
Details is listed.
3. Use the Sample PDS RAM for this sample, as this is the RAM you added the custom action to and the
appropriate parameters to in the configuration file you created in Lesson 1. In the uniqueId text field
enter, com.ibm.carma.sample.PDSRAM.
a) Open the CARMA Repositories view and connect to the remote system.
b) Expand the host system with the RAM you want to use, right-click on the particular RAM, and select
Properties.
c) In the Properties for RAM dialog box that opens, you should see the unique identification listed.
This is the uniqueId you use when configuring the extension points.
4. In the class text field, enter the name of the class that contains the code
that specifies the details of the parameter validation. Enter the class name,
com.ibm.carma.plugin.howto.action.ValueParamValidationAction. You create this class
later in this exercise.

164 Developer for z/OS: Welcome and Getting Started

5. In the parameterId text field, enter the parameter that is defined in the PDS RAM to which the
parameter validation applied. For this sample, use the value parameter, which you defined on the PDS
RAM with a parameterId of 000 in Lesson 1.
6. Finally, in the actionId text field, enter the action that is defined on the PDS RAM to which the
parameter validation should be applied. For this sample, use the HowTo custom action, which you
defined on the PDS RAM with an actionId of 100 in Lesson 1.
You have now configured a parameterValidator to validate the value parameter on the HowTo
custom action for the PDS RAM.

Lesson 4: Configure the com.ibm.carma.ui.actionValidators extension

In this lesson, you configure the actionValidator extension that you defined for this plug-in project.
The actionValidators extension point allows contributing extensions to validate the values and the
relationships between values of all parameters that are associated with an action. If invalid combinations
of parameters are detected, the OK button is disabled and the user is unable to submit the information.
For example, in this sample either the string1 or string2 fields are considered required but not both.
You use the actionValidator extension to check the valid combination of parameters.
1. You should be working in the Plug-in Development perspective and have the Plug-in Editor for your
com.ibm.carma.plugin.howto plug-in project open.
2. On the Extensions page, select the (actionValidator) option below the
com.ibm.carma.ui.actionValidators extension point. To the right you see the Extension
Element Details listed.
3. In the actionId text field, enter the action that is defined on the PDS RAM to associate this validator to.
For this sample, use the HowTo custom action on the PDS RAM, actionId 100.
4. In the uniqueId text field, enter the unique identification that is associated with the PDS RAM,
com.ibm.carma.sample.PDSRAM.
5. Finally, in the class text field, enter the class that contains the code to apply the
actionValidator to the parameters of the HowTo custom action. For this sample, the class is,
com.ibm.carma.plugin.howto.action.ActionValidationAction. You create this class later
on in this exercise.
You have now defined a parameterValidator extension for the PDS RAM on the HowTo action using
the ActionValidationAction Java class.

Lesson 5: Configure the com.ibm.carma.ui.customParameterControl extension

point
In this lesson, you configure the customParameterControl extension that you defined for this plug-in
project.
The customParametercontrol extension point allows for the values of the parameter to be presented
to the user in a format other than a text field. For this sample, the option parameter is changed from a
single-character text field to a checkbox. You start working in the Plug-in Development perspective with
the Plug-in Editor for your com.ibm.carma.plugin.howto plug-in project open.
1. On the Extensions page, select the (customParameterControl) option below the
com.ibm.carma.ui.customParameterControl extension point. To the right you see the
Extension Element Details listed.
2. In the uniqueId text field, enter com.ibm.carma.sample.PDSRAM for the Sample PDS RAM.
3. In the class text field, enter com.ibm.carma.plugin.howto.action.CheckboxOptionControl.
You create this class later in this exercise.
4. In the parameterId text field, enter the parameter id for the option parameter. For the sample, this is
003.
5. Finally, in the actionId text field, enter 100 for the HowTo action.
6. Save the changes and debug any errors.
You have now defined a customParameterControl extension in the HowTo action on the PDS RAM.

Getting started 165

 Lesson 6: Create the appropriate Java classes to handle the verification and validation
In the previous lessons you configured the extension points; now you create the Java classes that are
needed to handle the validation of the parameters and actions.
Tip: As you create these Java classes, they will each have to implement or extend certain interfaces or
classes respectively. To determine what classes or interfaces need to be included, you can right-click on
the extension in the Plug-in Editor and select Show Description. The description of the extension will
open in the editor. If you scroll down to the API Information heading, you find the classes or interfaces
the class needs to use in conjunction with the extension point.
1. Start by creating the class that is used with the parameterValidator extension point. This class
is responsible for checking to make sure the value that is entered into the value parameter follows
the specifications that are outlined in this sample. In the Package Explorer view, right click the
com.ibm.carma.plugin.howto plug-in project, and select New > Package.
2. In the New Java Package dialog box that opens, enter com.ibm.carma.plugin.howto.action as
the name for the package. Click Finish. You should see the package that is created under your Eclipse
plug-in project.
3. Now, right click the com.ibm.carma.plugin.howto.action package you created, and select New
> Class. The New Java Class dialog box opens.
4. Enter ValueParamValidator in the Name text field.
5. To the right of the Interfaces click the Add button. In the Implemented Interfaces Selection dialog
box that opens, filter for the interface IParameterValidator. Click Finish to close the New Java
Class dialog box and open the class in the editor.
6. Now, you create the second Java class that is responsible for handling the verification of the HowTo
action. Right click the com.ibm.carma.plugin.howto.action package and select New > Java
Class.
7. In the New Java Class dialog box that opens enter the name of the class to be, ActionValidator
and add the interface IActionValidator. Click Finish to close the dialog box and create the class.
8. Finally, create the last Java class following the above steps and by defining a name
of CheckboxOptionControl. Click the Browse button to the right of the Superclass
text field. The Superclass Selection Dialog Box should open. Filter for the class,
AbstractCustomParameterControl, select it, and click OK.
9. Click Finish to close the New Java Class dialog box and open the class in the editor.
You have now created the classes that handle the verification features offered by the extension points.

Lesson 7: Create the code for the ValueParamValidator class

The ValueParamValidator class handles the verification of the Value parameter in the HowTo action.
This lesson describes in detail how to create the code to demonstrate the parameter verification and
validation features of the com.ibm.carma.ui.parameterValidators extension point.
For this sample, the following are a list of possible inputs from the user and the informational messages
that are displayed.
• When the user enters a 0, an informational message is displayed
• When the user enters a 1, a warning message is displayed
• When the user enters a value of 2 or greater, an error message is displayed
• When the user enters a non-numeric character, the input will not be allowed
1. In the Package Explorer view, open the ValueParamValidator class by navigating
com.ibm.carma.plugin.howto > src > com.ibm.carma.plugin.howto.action and double-
clicking on the class to open it in the editor.
2. You will first implement the verifyInput method. This method checks for any invalid characters
in the input text. For this sample, this method will only accept numeric characters. The following
pseudocode demonstrates this:

if the length of input is greater than 0

then allow input if the input characters are 0-9

166 Developer for z/OS: Welcome and Getting Started

 else
do not allow input

Use the following example sample code to implement the verifyInput method:

/*Accept only numeric characters as valid. */

public void verifyInput(ParameterValidationEvent event)
{
if(event.text.length() > 0)
event.allowInput = (event.text.matches("[0-9]"));
}

3. Next, you will override the validateParameter method to display the appropriate methods
depending on the values entered, as described above.
The following pseudo code demonstrates this:

if input = 0
return an informational message
else if input = 1
return a warning message
else
return an error message

Use the following example sample code to override this method:

/* Returns an informational message if 0 is entered,

* Returns a warning message if 1 is entered,
* Returns an error message if a numeric value greater than 1 is entered
*/
public ValidationResult validateParameter(ParameterValidationevent event)
{
ValidationResult result = new ValidationResult();
if(event.text.contains("0"))
{
//Display informational message.
result.severity = ValidationResult.INFO;
result.message = "You entered a 0!";
}
else if(event.text.contains("1"))
{
//Display a warning message
result.severity = ValidationResult.WARNING;
result.message = "Values greater than 1 will result in an error!";
}
else
{
//Display an error message.
result.severity = ValidationResult.ERROR;
result.message = "Value is too great, enter a lower value.";
}

return result;
}

4. Save the source and debug any errors.

Lesson 8: Create the code for the ActionValidator class

The ActionValidator class verifies that at least one of the string parameters has a value, but not both.
You will also make the Value parameter a required parameter, and codes the ActionValidator class to
mark the parameter with an asterisk.
1. In the Package Explorer view, open the ActionValidator class by navigating
com.ibm.carma.plugin.howto > src > com.ibm.carma.plugin.howto.action and double-
clicking on the class to open it in the editor.
2. You start by overriding the isParameterRequired method. For this sample, you will code for only
the Value parameter to be required. The following pseudo code demonstrates this:

if paramID = paramID of value parameter

return true
else
return false

Getting started 167

 Use the following example source code to override the isParameterRequired method:

/( Mark the value parameter as required.*/

public boolean isParameterRequired(Action action, Parameter param)
{
//The value parameterID is 000
if(param.getParameterID().equals("000"))
{
return true;
}

return false;
}

3. Next, you override the validateAction method to allow only one value in the input strings
parameter, but not both. The following pseudocode demonstrates this:

Collect all the Parameter objects associated with the action

Iterate through the Parameter objects and get the string1 and string2 Parameter objects
Retrieve the string value of string1, check to see if it's null or has a length of 0
Retrieve the string value of string2, check to see if it's null or has a length of 0
Determine if both the parameters have values
Return an error message
Determine if neither of the parameters have values
Return an informational message

Use the following example sample code to override this method:

public ValidationResult validateAction(ActionValidationEvent event)

{
Parameter string1Param = null;
Parameter string2Param = null;
ValidationResult result = new ValidationResult();

//Iterate through and retrieve the parameter objects

for (Object o : event.action.getParameters())
{
if (((Parameter) o).getParameterId().equals("001"))
{
string1Param = (Parameter) o;
}
else if (((Parameter) o).getParameterId().equals("002"))
{
string2Param = (Parameter) o;
}
)

//Retrieve the parameter value for string1, and determine if there was input
String string1Val = (String) event.parameterValueMap.get(string1Param);
boolean string1IsThere = !(string1Val == null || string1Val.length() == 0);

//Retrieve the parameter value for string2, and determine if there was input
String string2Val = (String) event.parameterValueMap.get(string2Param);
boolean string2IsThere = !(string2Val == null || string2Val.length() == 0);

//Determine if both string1 and string2 are provided.

//Returns an error message.
if (string1IsThere && string2IsThere)
{
result.severity = ValidationResult.ERROR;
result.message = "Provide either String1 or String2.";
}

//Determine if neither string1 nor string2 is provided

//Returns an info message.
else if(!string1IsThere && !string2IsThere)
{
result.severity = ValidationResult.INFO;
result.message = "Enter a value for String1 or String2.";
}

return result;
}

4. Save the source and debug any errors.

168 Developer for z/OS: Welcome and Getting Started

Lesson 9: Create the code for the CheckboxOptionControl class
The CheckboxOptionControl class changes the CARMA default text field to a checkbox on the Option
parameter. Since this parameter is a yes or no parameter, a checkbox is more convenient for the user.
1. In the Package Explorer view, open the CheckboxOptionControl class you created by navigating
com.ibm.carma.plugin.howto > src > com.ibm.carma.plugin.howto.action and double-
clicking on the class.
2. You will first add the checkbox button object as instance data for the class. This allows the checkbox
button and all its metadata to be available to the CheckboxOptionControl class. Add the following
line of code: Button theButton;
3. Next, you override the createControl method to create the checkbox button and return it instead of
the default text field. The following pseudocode demonstrates what you want this method to do:

Create theButton with the checkbox style

Give the theButton some text
Return the theButton

Use the following sample code to override this method:

/* Create a checkbox for the yes/no option */

public Control createControl(Composite parent,
RepositoryManager repositoryManager,
Parameter param,
Action action,
CustomActionAccepter custActionAccepter,
Object defaultValue)
{
theButton = new Button(parent, SWT.CHECK);
theButton.setText("Check me!");
return theButton;
}

4. Now, you override the getValue method. This method returns the value of the parameters. Since
you are using a checkbox instead of a text field, the code you write will have to translate the check
or unchecked status of the checkbox into the expected string format. The following pseudocode
demonstrates this:

if the checkbox is checked

return "Y" for yes
else
return "N" for no

Use the following sample code to override this method:

public Object getValue() {

if(theButton.getSelection())
return "Y";
else
return "N";
}

5. The last method that you need to override is the isUsingDefaultLabel method. If set to false, this
method will not display the default label that you provided when you added the parameter to the RAM.
If set to true, then the label is displayed like normal. For this sample, the code will use the default
label.
Use the following sample code to override the method:

public boolean isUsingDefaultLabel()

{
return true;
}

6. Finally, you need to ensure that all required imports are listed. Add any of the following import
statements that are not listed in your class:

import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.*;

Getting started 169

 import com.ibm.carma.model.*;

import com.ibm.carma.ui.action.custom.AbstractCustomParameterControl;

7. Save the source and debug any errors.

Your completed code for the CheckBoxOptionControl should look like:

package com.ibm.carma.plugin.howto.action;

import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.*;

import com.ibm.carma.model.*;

import com.ibm.carma.ui.action.custom.AbstractCustomParameterControl;

public class CheckboxOptionAction extends AbstractCustomParameterControl {

//Add the button to the instance data
Button theButton;

/* Create a checkbox for the yes/no option */

public Control createControl(Composite parent,
RepositoryManager repositoryManager,
Parameter param,
Action action,
CustomActionAccepter customActionAccepter,
Object defaultValue) {
theButton = new Button(parent, SWT.CHECK);
theButton.setText("Check me!");
return theButton;
}

@Override
public Object getValue() {
if(theButton.getSelection())
return "Y";
else
return "N";
}

@Override
public boolean isUsingDefaultLabel() {
return true;
}
}

Summary: Module 9
In this module, you have created a plug-in project that demonstrates the use of the actionValidators,
parameterValidators, and customParameterControl extension points.

Results
You should run or debug your plug-in project now. Do the following while still in the testing workspace to
verify the functionality of your plug-in:
1. Be sure that you are in the zOS Projects perspective and are connected to your host system. Use the
port numbers that are associated with the updates you did on the PDS RAM in Lesson 1.
2. Open the CARMA Repositories view and connect to the PDS RAM you modified in Lesson 1.
3. Expand the RAM down to an individual CARMA Member. Right click this member, and select Custom >
HowTo. The HowTo dialog box opens.
Tip: If you have trouble getting this dialog box to open or for the custom option to be available, check
back through the steps you followed in Lesson 1 or consult the CARMA Developer's Guide.
4. The first thing that you will check for is that the parameterValidator extension is working correctly.
a. In the first text field, enter 0. An informational message should appear in the header of the dialog
box.
b. Now enter 1 in the text field. The message should change to a warning message.

170 Developer for z/OS: Welcome and Getting Started

 c. Entering 2 or other numerical value should result in a displayed error message and the OK button
disabled.
d. The final test for the parameterValidator extension is attempting to enter a nonnumeric
character, such as a. The input should not be allowed and will not even appear within the text
field.
5. Next, you check the actionValidator extension.
a. The first test is to see if the appropriate parameter you coded to be required is marked with an
asterisk. For this sample, the first parameter should be marked with the asterisk, but no other
parameters.
b. The second test is to ensure that the form will not be accepted if both strings are provided. For
this sample, when you enter a value into both string fields, you should see an error message that is
displayed and the OK button should be disabled.
6. Finally, you will test the customParameterControl extension.
a. The first test is to check to see if a checkbox has replaced the default text field and that selecting
and clearing the checkbox does not cause any errors.
b. The second test is to see if the default label provided, Y/N? was kept.

Samples
Review samples that provide usable data from the product.

A simple COBOL application on a remote system

This sample guides you through the process of building, and running a simple COBOL application on
a remote system. The sample contains two simple COBOL files. The programs request input through a
command-line interface and writes back a response.
This sample leads you through the following tasks:
• Create a remote project from a sample shipped with Developer for z/OS
• Allocate a partitioned data set, create a z/OS project
• Build executable code from COBOL source
• Run an application on the remote system
Note: This sample requires a connection to the host system.
Make sure that the z/OS Build and Remote System Explorer servers are configured and started. You also
need a connection to the z/OS host system defined in your workspace. To create the connection, the
following connection information is needed from your system administrator.
• The name or TCP/IP address of the host system.
• The port number for the connection.
• The method used in your environment to launch the server and information. The information that is
needed is different based on the method. See Connecting to a z/OS system for the specific information
needed and instructions on creating a host connection

Import the sample code

Make sure that the z/OS Build and Remote System Explorer servers are configured and started and you
are connected to the host system.
Before you can copy the sample application code, a partition data set must be allocated on the host
system. The five partition data sets needed for this sample are listed in Table 18 on page 172. The table
also contains the information to allocate each partition data set.

Getting started 171

 Table 18. Partition data sets needed for the sample
Data set name Category Type
<HLQ>.REMOTE.COBOL SOURCE COBOL
<HLQ>.COBOL.OUTPUT* LISTING COBOL
<HLQ>.COBOL.SYSDEBUG* LISTING COBOL
<HLQ>.COBOBJS.OBJ* SOURCE COBOL
<HLQ>.COBOL.COPYLIB* SOURCE COBOL

Note: The data sets marked with an asterisk (*) are required by the COBOL step of the ELAXFCOC
procedure described in a later step. The data set names must match the data set names referred to in the
COBOL step options.
1. Complete the following steps for each of the data sets listed in Table 18 on page 172 to allocate the
partition data sets.
The <HLQ> variable represents the user ID that you used to log on to the host system. You do not need
to change this variable when allocating the partition data set.
a) In the Remote System view, right-mouse click MVS Files and click New > Allocate Partitioned
Data Set.
b) On the Allocate Partitioned Data Set page, complete the Data Set Name field.
There are two parts to the data set name.
• The first part is the high-level qualifier. Use the drop-down menu to select a predefined name or
type in a name. The predefined name is the user ID used to log on to the host system.
• The second part is the data set name. Use the names defined in the table.
For example, for the first data set in the table, the value for the Data Set Name could look like
MYFILES.REMOTE.COBOL where MYFILES is the high-level qualifier.
c) Click Next.
d) On the Data Set Allocation page, select Specify characteristics by usage type and then select the
corresponding value for each field as shown in the table.
e) Click Finish.
After you create all the partition data sets, you should see them listed under MVS files in the Remote
System view.

The sample data can now be moved to the host system.

2. From the workbench, click File > New > Example.
3. Expand Workstation COBOL and click COBOL Sample 1 > Next.
4. On the z/OS Local Project window, type LocalCOBOLSample in the Project name field and click
Finish.
The data is now in a local project on your computer.
5. Copy the COBOL source files, PrintApp.cbl and StartApp.cbl, to the <HLQ>.REMOTE.COBOL
partitioned data set. You can copy and paste or drag the files from the Local Project view to the
Remote System view.

172 Developer for z/OS: Welcome and Getting Started

Work with the sample code
You are now ready to create the z/OS Project and MVS subproject, create a property group, and set the
build options.
1. From the Developer for z/OS workspace File menu, click New > Other.
2. Expand z/OS Development and select z/OS Project and click Next.
3. On the z/OS Project Name window, type SampleProject in the Project name field and select Create
an MVS subproject. Click Finish.
4. On the MVS Subproject Name and Location window, complete the following fields and then click
Finish.
SubProject Name
Type RemoteCOBOLSample.
High-level Qualifier
Use the default value which is the user ID with which you logged on to the remote system.
Property Group
Click Create a property group and associate it with the subproject. Specify a property group
name in the name field and click Finish.
5. The Property Group Editor opens and you can define the build options for the new property group:
a) Click the COBOL tab and then click Procedures and Steps.
b) Expand the ELAXFCOC procedure and double-click COBOL to edit the COBOL step. Make sure your
specified data set names were created or replace them with existing ones.
c) Click the Link tab and then click Procedures and Steps.
d) Expand the ELAXFLNK procedure and double-click LINK to edit the LINK step. Make sure the Load
module location data set has been created, or replace the data set with an existing one.
e) Click the Run tab and expand the ELAXFG0 procedure. Copy and paste the following JCL into the
Additional JCL text box.

//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
Ben
Q
/*
//

f) Click the JCL tab in the property group editor. Verify that the default JOB card includes a PROCS
statement and that the PROCS statement points to the procedure library on the remote system.
If you do not know the location of the procedure library, ask your system administrator.
g) Close and save the new property group.
6. Add the <HLQ>.REMOTE.COBOL partitioned data set to the RemoteCOBOLSample subproject:
a) Select the data set in the Remote Systems view.
b) Right-click and select Add to Subproject.
c) Type or select the subproject name and click Finish.
You can now build and run the application on the remote system.
7. In the RemoteCOBOLSample subproject, right-mouse click STARTAPP.cbl and click Nominate as
Entry Point.
8. Right-mouse click RemoteCOBOLSample and then click Rebuild Subproject.
9. Select the generated load module, and click Run > Run to run the application.

Getting started 173

174 Developer for z/OS: Welcome and Getting Started
Documentation notices
© International Business Machines Corporation 1992, 2024.

This information was developed for products and services offered in the US. This material might be
available from IBM in other languages. However, you may be required to own a copy of the product or
product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to [email protected].
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in
any manner serve as an endorsement of those websites. The materials at those websites are not part of
the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you provide in any way it believes appropriate without
incurring any obligation to you.
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
[email protected].
Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Any performance data and client examples cited are presented for illustrative purposes only. Actual
performance results may vary depending on specific configurations and operating conditions.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,
and represent goals and objectives only. Such statements should not be relied upon when making
purchasing decisions.

© Copyright IBM Corp. 1992, 2024 175

 This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by actual
people or business enterprises is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform
for which the sample programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work must include a copyright notice
as follows:

© (your company name) (year).

Portions of this code are derived from IBM Corp. Sample Programs.
© International Business Machines Corporation _enter the year or years_.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corporation, registered in many jurisdictions worldwide. Other product and service names
might be trademarks of IBM or other companies. A current list of IBM trademarks is available at
"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the following terms and conditions.

Applicability
These terms and conditions are in addition to any terms of use for the IBM website.

Personal use
You may reproduce these publications for your personal, noncommercial use provided that all proprietary
notices are preserved. You may not distribute, display or make derivative work of these publications, or
any portion thereof, without the express consent of IBM.

Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided
that all proprietary notices are preserved. You may not make derivative works of these publications, or
reproduce, distribute or display these publications or any portion thereof outside your enterprise, without
the express consent of IBM.

Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either
express or implied, to the publications or any information, data, software or other intellectual property
contained therein.

176 Developer for z/OS: Welcome and Getting Started

IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use
of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not
being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable
laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS
ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,
AND FITNESS FOR A PARTICULAR PURPOSE.

Documentation notices 177

178 Developer for z/OS: Welcome and Getting Started
Security considerations
This topic highlights some of the security limitations that you might encounter with this application. To
help ensure the security of your installation, customize your security settings and set up user access
controls.

Enabling security during the installation process

Security configuration for Developer for z/OS is addressed in Security definitions. More details on all
security aspects can be found in Security considerations.
Security considerations for Developer for z/OS:
• Installing Developer for z/OS results in a basic configuration with default settings for a basic, secure
setup. Extra configuration tasks, such as configuring SSL, allow for tighter controls. This information is
covered in detail in Security considerations.
Note: Security is not fully enabled during the installation process and must be enabled during
customization after installation is complete. The customization of some security-related aspects must
be completed for the product to work and for certain security features to be enabled. This limitation
applies to silent installations.
• Security for Developer for z/OS on the host is configured through a combination of Developer for z/OS
configuration files and RACF® commands (or other similar security products).
• Developer for z/OS does not provide a login option when the Developer for z/OS host is used as an LDAP
client that accesses a customer-specific LDAP server to get group membership information that is used
to enforce wanted client behavior. LDAP logon information can be provided in a configuration file when
the Developer for z/OS host is used as an LDAP client that accesses public certificate revocation lists
(CRLs).
• Security for Developer for z/OS database authentication is enabled through RACF commands.
• For information about setting up SSL and installing a custom certificate, see these topics in the IBM
Explorer for z/OS documentation: (Optional) ssl.properties, the RSE encrypted communication, RSE -
ssl.properties, and Setting up encrypted communication and X.509 authentication.
• For information about enabling security between the client and server or web client and server, see
Connection flow.
• To configure the security settings of other applications that communicate with Developer for z/OS (Db2
Connect, Debug Tool, Fault Analyzer, File Manager), use the security configuration options available in
those products.
• To verify that you correctly configured the security settings, see Verify the security settings.
• More information:
– With the host connection in Enterprise Service Tools, you can set up a terminal session with a remote
z/OS system. You can configure the session to use SSL, client authentication, and host authentication.
You can use the IBM Key Management tool iKeyman to create a key database file, to create or request
certificates, and to import and export certificates.
Note: Developer for z/OS also uses REXEC, or the more secure SSH, to compile UNIX System Services
projects. For more information, see z/OS UNIX subprojects.

Enabling secure communication between multiple applications

For integrated products, Developer for z/OS provides security for the communications between the
products through the Developer for z/OS communication configuration by using Developer for z/OS tools.
The communication is host only, so there is no encryption.

© Copyright IBM Corp. 1992, 2024 179

 To handle user access controls between products in Developer for z/OS, the receiving application (for
example, JMON) requires authentication, which is done by the calling application (RSE) on the user’s
behalf. Where possible (for example, JMON or CARMA), Developer for z/OS binds to the loopback stack
only, which can be reached only from the same system.
For single-sign on, the user authenticates with RSE. RSE then does authentications on the user’s behalf
for other servers. While the user stays within Developer for z/OS, it all looks like one server, but this
situation is not true for other servers. Users must manually authenticate for other servers outside of
Developer for z/OS.

Ports, protocols, and services

Developer for z/OS internal processes, tasks, or services do not require a fixed user ID. You can create
your own user ID for these processes, tasks, or services, and associate the user ID with them by using
RACF commands. For more information about what ports, protocols, and services Developer for z/OS
uses, see Planning and TCP/IP considerations.
Before you can connect to a remote system from the Developer for z/OS client, you must define
a connection for the remote system and specify connection properties. For more information about
connecting to a remote system and the ports that are used for a connection, see Creating a connection to
a z/OS system.

Customizing your security settings

Customizing your security settings is covered in Security considerations. For more information about
setting and changing passwords, and client certificate authentication, see these topics:
• Connecting to a remote system
• Changing your password
• Creating a connection by using client certificate authentication
• Setting preferences for client certificate authentication
Note: Developer for z/OS uses generated PassTickets and does not store passwords on the host. The
Remote Connection Emulator (RCE) stores SSL-related passwords in the Eclipse Secure Storage. For more
information, see Secure storage in the Eclipse documentation. Clients mask password fields with ***, and
a password that is provided by a client during logon is always transmitted in a masked format, even for
SSL encrypted communication.
To enable multiple levels of security, and determine the implications of each, see the various chapters
about security in the host configuration documentation. Each chapter addresses a specific aspect of
security configuration.
Developer for z/OS relies on the options that are offered by TCP/IP to set up notifications of security
breaches or attempts.
Note: Information about login attempts is stored in the Developer for z/OS server logs, and in various
other places (for example, server log, user logs, audit log, syslog).

Multi-Factor Authentication
Developer for z/OS relies on IBM Explorer for z/OS for multi-factor authentication (MFA) support. For
information about configuring MFA in IBM Explorer for z/OS, see Using Multi-Factor Authentication.

Setting up user roles and access

RACF commands are used for the following purposes:
• Create and delete users and set their access levels.
• Create groups and assign them privileges.
• Establish password rules for users (such as no reuse, minimum length, or character requirements).

180 Developer for z/OS: Welcome and Getting Started

• Setup superuser IDs or IDs with special security privileges.
For more information about RACF, see the Security Server RACF Security Administrator's Guide,
SA23-2289.

Privacy policy considerations

This software offering does not use cookies or other technologies to collect personally identifiable
information.

Security considerations 181

182 Developer for z/OS: Welcome and Getting Started
IBM®

Product Number: 5755-A05

5724-T07