IBM Developer for z/OS

IBM Developer for z/OS Enterprise Edition

16.0

Managing and Extending the Eclipse

Environment
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 [Link]
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.
Managing the development environment for a team
Host-based projects and the push-to-client function provide a way to centralize, standardize, and
distribute Eclipse workspace configurations so that your organization has greater control over resource
access and development processes.
To learn more about these tools, see these topics:
• “Host-based projects” on page 1
• “Planning a push-to-client environment” on page 22

Host-based projects
A host-based project is defined on a z/OS system and downloaded to the workstation automatically when
you connect to the remote system. Host-based projects enable an installation to define and automatically
propagate projects on client workspaces from a central location. They provide a means for standardizing
project definitions. A host-based project includes the project, its properties, and its member resources.
Use of host-based projects allows an administrator to tightly control project structure and behavior on the
remote system, since certain actions are disabled for host-based projects. Renaming or deleting projects
and subprojects, for example, adding or removing subproject members, and creating new remote projects
or subprojects associated with host-based project systems are actions that are disabled for host-based
projects.
Because host-based projects are defined in a central location and downloaded to a workstation, there
are some differences between how you use host-based projects and how you use workstation-based
projects:
• Only the creator or authorized users of host-based projects can alter project properties and project
structure. Their properties are defined and controlled on the remote system on which they are created.
Note: Although properties for host-based subprojects can be changed in the user interface, they are not
saved on the client after you disconnect from the remote system.
• You cannot control whether host-based projects are downloaded to your workstation when you connect.
Host-based projects are defined so that they are automatically downloaded when you connect.
• Host-based projects cannot contain resources from multiple remote systems. All resources are on a
single remote system.
• When you disconnect from a remote system, the host-based projects are removed from your z/OS
Projects view.
Whether projects are host- or workstation-based is controlled by the z/OS system. If you connect to
multiple remote systems, your workspace might contain both host- and workstation-based projects.
For instructions on configuring and using host-based projects, see the following topics:
• “Configuring host-based projects” on page 1
• “Using host-based projects” on page 21
• “Solving problems with host-based projects” on page 22

Configuring host-based projects

You configure host-based projects for a remote system by creating a set of configuration files on that
system.
When you connect to a remote system on which host-based project configuration files are present and
set up correctly, the z/OS Projects view is populated with host-based projects. You are not able to create
workstation-based projects that are associated with that system. On systems where the configuration
files are not present, clients do not have access to host-based projects. They can create their own
workstation-based projects that are associated with the system.

© Copyright IBM Corp. 1992, 2024 1

 To configure host-based projects on a remote system, you must define four types of configuration files.
See the related topics for instructions and examples.
• Project instance files that are specific to a single user ID and point to reusable project definition files.
• Project definition files that define the structure and contents of the project and that multiple users can
reuse.
• Subproject definition files that define the structure and contents of the subproject and that multiple
users can reuse.
• Properties files that define the subproject properties and that multiple subprojects can reuse.
Unlike other push-to-client configurations, you cannot create host-based projects on a model workspace
and export them. Host-based projects must be created manually on the remote system.
1. Ensure that push-to-client is enabled on the remote system on which you want to create host-based
projects.
2. In the remote system folder that is identified in the [Link] parameter of the
[Link] file, create a subfolder that is named projects.
For example, if you use the default folder name /var/zexpl/pushtoclient, then the folder for
host-based project configuration files is /var/zexpl/pushtoclient/projects.
3. Add an entry to the [Link] file that defines the location of host-based project configuration
files on the remote system.
For example, to define/var/zexpl/pushtoclient/projects as the location for host-based
project configuration files, add the following entry to the [Link] file:

<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/projects</containerPath>
<fileMask></fileMask>
<encoding>UTF-8</encoding>
</location>

For more information about the [Link] file and an example of the file, see “Key mapping
file” on page 37.
4. Create project instance files, project definition files, subproject definition files, and subproject property
files in the host-based project configuration file folder.
For example, in the /var/zexpl/pushtoclient/projects folder on the remote system, create the
project instance files, project definition files, subproject definition files, and subproject property files.
For more information about how to tag these configuration files and for sample files, see the related
topics.
Related concepts
“Host-based projects” on page 1
A host-based project is defined on a z/OS system and downloaded to the workstation automatically when
you connect to the remote system. Host-based projects enable an installation to define and automatically
propagate projects on client workspaces from a central location. They provide a means for standardizing
project definitions. A host-based project includes the project, its properties, and its member resources.
Related tasks
“Creating a project instance file” on page 3
Project instance files define the set of projects to be downloaded when a user connects to the remote
system.
“Creating a project definition file” on page 5
Project definition files list the subprojects that are contained by the project and are in the root project
definition folder or one of its subfolders.
“Creating a subproject definition file” on page 7
Subproject definition files define the set of resources that are required to build a single load module and
are in the root project definition folder or one of its subfolders.
“Creating a subproject property file” on page 13

2 Developer for z/OS: Managing and Extending the Eclipse Environment

Subproject property files are in the PROJECT-HOME directory or one of its subfolders.

Creating a project instance file

Project instance files define the set of projects to be downloaded when a user connects to the remote
system.
Each user who works with host-based projects must have a folder on the remote
system that contains a set of project instance files. These folders must be
direct subfolders of the path that is defined in the <containerPath> tag for
[Link] in the key mapping
file. Each folder name must match the user ID of the particular user for whom the projects are defined.
For more information about the key mapping file, see the related topics.
The user folders contain one project instance file for each project to be downloaded. The instance files
must be encoded in UTF-8 and have an extension of *.hbpin.
Note: To activate host-based projects for a particular user, at least one project instance file must exist in
the user's folder.
The project instance file is an XML file that contains the following tags. For the project instance schema,
see the related links.

<PROJECT-INSTANCE>
<WSED-VERSION>[Link]</WSED-VERSION>
<PROJECT>
<PROJECT-NAME>overrideName</PROJECT-NAME>
<PROJECT-DEF-PATH>pathName</PROJECT-DEF-PATH>
</PROJECT>
</PROJECT-INSTANCE>

<WSED-VERSION>
The version of the schema syntax. This tag must contain [Link], as shown.
<PROJECT-NAME>
Is optional and specifies an override to the project name.
<PROJECT-DEF-PATH>
Refers to a project definition file with a path relative to the PROJECT-HOME folder, not the folder that
contains the instance file that is being parsed.
The following figure illustrates how to set up a project instance file:
• The editor shows a project instance file called [Link]. In this file, the <PROJECT-
NAME> tag overrides the project name, and the <PROJECT-DEF-PATH> tag refers to the project
definition file PROJDEFFOLDER/mvsproject1def.
• To the right of the editor, the Remote Systems view shows a folder that is called PROJDEFFOLDER
containing the project definition file [Link]. Notice that the <PROJ-FULL-PATH> tag
does not include the file extension .hbppd when it refers to this file.
• To the left of the editor, the z/OS Projects view shows the host-based project corresponding to the
instance file [Link]. Notice that the <PROJECT-NAME> tag is used to give the project a
new name that contains German characters. The German UTF-8 characters are not displayed correctly
in the text editor but are correct in the z/OS Projects view. Had the <PROJECT-NAME> tag not been
used to override the project name, it would be called mvsproject1def.

Managing the development environment for a team 3

 Next: “Creating a project definition file” on page 5
Related reference
“Project instance schema” on page 4
The project instance schema defines tags that are used to define a project instance file.
“Key mapping file” on page 37
The key mapping file is generated when you export configuration files. It stores the names, locations, and
character encodings of configuration files that are used in a push-to-client configuration environment.

Project instance schema

The project instance schema defines tags that are used to define a project instance file.

<xsd:schema xmlns:xsd="[Link]

<xsd:element name="PROJECT-INSTANCE">
<xsd:annotation>
<xsd:documentation>
Defines a specific instance of a project
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="WSED-VERSION" minOccurs="1"></xsd:element>
<xsd:element ref="PROJECT" minOccurs="1"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="WSED-VERSION" type="xsd:string"></xsd:element>

<xsd:element name="PROJECT">
<xsd:annotation>
<xsd:documentation>
The project instance consists of a pointer to a reusable
project definition file and an optional override of the
default name
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="PROJECT-NAME" minOccurs="0"></xsd:element>
<xsd:element ref="PROJECT-DEF-PATH" minOccurs="1"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PROJECT-NAME" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
Optional override of the project name in the project
definition file
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="PROJECT-DEF-PATH" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The path to the project definition file to be used by
this instance. The path is relative to the root project
configuration folder on the remote system.
</xsd:documentation>
</xsd:annotation>
</xsd:element>

</xsd:schema>

Related tasks
“Creating a project instance file” on page 3

4 Developer for z/OS: Managing and Extending the Eclipse Environment

Project instance files define the set of projects to be downloaded when a user connects to the remote
system.

Creating a project definition file

Project definition files list the subprojects that are contained by the project and are in the root project
definition folder or one of its subfolders.
Prerequisite: “Creating a project instance file” on page 3
Unlike workstation-based projects, all subprojects that are contained by a host-based project must be
associated with the same system.
Project definition files can be reused by referring to them from multiple project instance files. Using the
name override capability of the instance file, the same project structure can be given a different name for
each instance file.
Project definition files must be encoded in UTF-8 and have an extension of *.hbppd. They are XML files
that contain the following tags:

<PROJECT-STRUCTURE>
<WSED-VERSION>[Link]</WSED-VERSION>
<PROJECT>
<PROJECT-NAME>overrideName</PROJECT-NAME>
<PROJECT-TYPE>zos-project</PROJECT-TYPE>
<SUBPROJECT-LIST>
<SUBPROJECT>
<SUBPROJECT-FULL-PATH>pathName</SUBPROJECT-FULL-PATH>
</SUBPROJECT>
</SUBPROJECT-LIST>
</PROJECT>
</PROJECT-STRUCTURE>

<PROJECT-NAME>
Is optional and specifies an override to the project name. If this tag is omitted, the project name is the
same as the project definition file name.
Note: If the <PROJECT-NAME> tag is used in the project instance file, that name overrides the name
that is specified here.
<PROJECT-TYPE>
Is required and must be zos-project, as shown.
<SUBPROJECT-LIST>
Is required and contains one or more <SUBPROJECT> tags.
<SUBPROJECT>
Is required and contains one or more <SUBPROJECT-FULL-PATH> tags.
<SUBPROJECT-FULL-PATH>
Is required and specifies the path to a subproject definition file, relative to the PROJECT-HOME
directory.
“Creating a subproject definition file” on page 7
Related reference
“Project definition schema” on page 5
The project definition schema defines tags that are used to define a project definition file.

Project definition schema

The project definition schema defines tags that are used to define a project definition file.

<xsd:schema xmlns:xsd="[Link]

<xsd:element name="PROJECT-STRUCTURE">
<xsd:annotation>
<xsd:documentation>
Top level element of a host-based project definition
file
</xsd:documentation>

Managing the development environment for a team 5

 </xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="WSED-VERSION"></xsd:element>
<xsd:element ref="PROJECT"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="WSED-VERSION" type="xsd:string"></xsd:element>

<xsd:element name="PROJECT">
<xsd:annotation>
<xsd:documentation>
Defines the structure of a host-based project
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="PROJECT-NAME"></xsd:element>
<xsd:element ref="PROJECT-TYPE"></xsd:element>
<xsd:element ref="SUBPROJECT-LIST"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PROJECT-NAME" type="xsd:string"></xsd:element>

<xsd:element name="PROJECT-TYPE" type="projectType">

<xsd:annotation>
<xsd:documentation>
Currently only the zOS project type is defined.
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:simpleType name="projectType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="zos-project"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:element name="SUBPROJECT-LIST">
<xsd:annotation>
<xsd:documentation>
The list of subprojects contained by this project. All
subprojects must be associated with this remote system.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" ref="SUBPROJECT"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="SUBPROJECT">
<xsd:annotation>
<xsd:documentation>
Pointer to a subproject definition file. A possible
future enhancement would be to allow for overriding the
project name. Currently, the subproject name must be
identical to the subproject definition file name.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="SUBPROJECT-FULL-PATH"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="SUBPROJECT-FULL-PATH" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The path to the subproject definition file. The path is
relative to the root project configuration folder on the
host.
</xsd:documentation>
</xsd:annotation>
</xsd:element>

6 Developer for z/OS: Managing and Extending the Eclipse Environment

 </xsd:schema>

Related tasks
“Creating a project definition file” on page 5
Project definition files list the subprojects that are contained by the project and are in the root project
definition folder or one of its subfolders.

Creating a subproject definition file

Subproject definition files define the set of resources that are required to build a single load module and
are in the root project definition folder or one of its subfolders.
Complete the tasks in “Creating a project definition file” on page 5.
Subproject definition files must be encoded in UTF-8 and have an extension of *.hbpsd. They are XML
files that contain the following tags:

<SUBPROJECT-STRUCTURE>
<WSED-VERSION>[Link]</WSED-VERSION>
<SUBPROJECT>
<SUBPROJECT-NAME>mySubproject</SUBPROJECT-NAME>
<SUBPROJECT-NATURE-LIST>
<SUBPROJECT-NATURE>[Link]</SUBPROJECT-NATURE>
</SUBPROJECT-NATURE-LIST>
<SUBPROJECT-PROPERTIES-LOCATION>pathName</SUBPROJECT-PROPERTIES-LOCATION>
<SUBPROJECT-TYPE>zos-subproject</SUBPROJECT-TYPE>
<FOLDER-LIST>
<FOLDER>
<FOLDER-NAME>[Link]</FOLDER-NAME>
<FOLDER-TYPE>pds</FOLDER-TYPE>
<FOLDER-STATE>
<STATE-IS-OFFLINE>false</STATE-IS-OFFLINE>
<PHYSICAL-FOLDER>
<FOLDER-NAME>[Link]</FOLDER-NAME>
<FOLDER-PHYSICAL-PATH>[Link]</FOLDER-PHYSICAL-PATH>
<FOLDER-TYPE>pds</FOLDER-TYPE>
</PHYSICAL-FOLDER>
</FOLDER-STATE>
</FOLDER>
</FOLDER-LIST>
<FILE-LIST>
<FILE>
<FILE-NAME>[Link]</FILE-NAME>
<FILE-EXTENSION>ext</FILE-EXTENSION>
<FILE-NAME-NO-ENTENSION>name</FILE-NAME-NO-EXTENSION>
<FILE-TYPE>pds | sequential</FILE-TYPE>
<FILE-STATE>
<STATE-IS-OFFLINE>false</STATE-IS-OFFLINE>
<PHYSICAL-FILE>
<FILE-NAME>name</FILE-NAME>
<FILE-PHYSICAL-PATH>[Link]/[Link]</FILE-PHYSICAL-PATH>
<FILE-TYPE>pds-member | sequential</FILE-TYPE>
</PHYSICAL-FILE>
</FILE-STATE>
</FILE>
</FILE-LIST>
</SUBPROJECT>
</SUBPROJECT-STRUCTURE>

The subproject definition file contains three kinds of tags:

• Subproject tags define parameters for the subproject itself.
• Folder tags define partitioned data sets contained in the subproject.
• File tags define partitioned data set members and sequential data sets contained in the subproject.
Note: The following list defines tags for which you must set specific required or optional values. For
a complete description of the subproject definition tags, see the subproject definition schema under
Related References.
<WSED-VERSION>
The version of the schema syntax. This tag is required and must be [Link] as shown.

Managing the development environment for a team 7

 <SUBPROJECT-NAME>
Is required and specifies the name of the subproject, such as MYSUB.
<SUBPROJECT-NATURE>
Is required and must be [Link], as shown.
<SUBPROJECT-PROPERTIES-LOCATION>
Is optional and points to the subproject properties definition file for this subproject. Specify a path
name relative to the PROJECT-HOME directory. If this tag is included, the properties file it refers to
overrides the default properties defined for the system connection. If this tag is omitted, the default
properties for the system are used. Default system properties are set by selecting the MVS™ Files
node for a system in the Remote Systems view and clicking Properties from the menu.
<SUBPROJECT-TYPE>
Is required and must be zos-subproject, as shown.
<FOLDER-LIST>
Contains one or more <FOLDER> tags, which define partitioned data sets in the subproject:
<FOLDER-NAME>
Is required and must specify the fully qualified name of a partitioned data set on the remote
system, such as [Link].
Note: For any file name in the subproject definition file, you can specify the substitution variable
<;HLQ> for the high-level qualifier. This variable is replaced by the user's user ID at connect time.
By using the <HLQ> substitution variable in the file references of a subproject, a single subproject
can contain a different set of files according to which project instance file refers to its parent
project. For an example of how to use this substitution variable in a subproject definition file, see
Figure 1 on page 9.
<FOLDER-TYPE>
Is required and must be pds, as shown.
<FOLDER-STATE>
<STATE-IS-OFFLINE>
Is required and must be false, as shown.
<PHYSICAL-FOLDER>
<FOLDER-NAME>
Is required and specifies the fully qualified name of the partitioned data set on the remote
system, such as [Link].
<FOLDER-PHYSICAL-PATH>
Is required and specifies the fully qualified name of the partitioned data set on the remote
system, such as [Link].
<FOLDER-TYPE>
Is required and must be pds, as shown.
<FILE-LIST>
Contains one or more <FILE> tags, which define partitioned data set members or sequential data sets
in the subproject:
<FILE-NAME>
Is required and specifies the fully qualified name of the file resource on the remote system,
including the mapped extension, such as [Link]/[Link] for a partitioned data set
member on MVS where [Link] is the partitioned data set name and HELLO is the member
name.
<FILE-EXTENSION>
Is required and specifies the extension that is defined by the file system mapping. **COBOL data
sets, for example, have a .cbl extension.
<FILE-NAME-NO-EXTENSION>
Is required and specifies the fully qualified file name without the extension, such as HELLO.

8 Developer for z/OS: Managing and Extending the Eclipse Environment

 <FILE-TYPE>
Is required and must be either pds-member or sequential, as shown.
<FILE-STATE>
<STATE-IS-OFFLINE>
Is required and must be false, as shown.
<PHYSICAL-FILE>
<FILE-NAME>
Is required and specifies the file name, such as [Link].
<FILE-PHYSICAL-PATH>
Is required and specifies the fully qualified file path, such as [Link]/
[Link].
<FILE-TYPE>
Is required and must be either pds-member or sequential, as shown.
The following figure illustrates how to set up a subproject definition file:
• The subproject definition file in the editor shows that the path to the project properties file is set to
[Link] and the <HLQ> substitution variable is used when you specify the first
partitioned data set that the subproject contains.
• To the right of the editor, the Remote Systems view shows the subproject properties file referred to by
the subproject definition file.
• To the left of the editor, the z/OS Projects view shows that the HLQ of the partitioned data set referred
to by the subproject definition file is resolved to the user ID used to connect to the remote system.

Figure 1. Sample subproject definition

“Creating a subproject property file” on page 13

Related reference
“Subproject definition schema” on page 9
The subproject definition schema defines tags that are used to define a subproject definition file.

Subproject definition schema

The subproject definition schema defines tags that are used to define a subproject definition file.

<xsd:schema xmlns:xsd="[Link]

<xsd:element name="SUBPROJECT-STRUCTURE">
<xsd:annotation>
<xsd:documentation>
Top level element of a host-based subproject definition
file. Note: any string representing a file can contain
the substitution variable <HLQ> which will be
replaced by the user's user ID at system connect time
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="WSED-VERSION"></xsd:element>
<xsd:element ref="SUBPROJECT"></xsd:element>
</xsd:sequence>

Managing the development environment for a team 9

 </xsd:complexType>
</xsd:element>

<xsd:element name="WSED-VERSION" type="xsd:string"></xsd:element>

<xsd:element name="SUBPROJECT">
<xsd:annotation>
<xsd:documentation>
Defines the structure of a host-based subproject
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="SUBPROJECT-NAME"></xsd:element>
<xsd:element ref="SUBPROJECT-NATURE-LIST"></xsd:element>
<xsd:element ref="SUBPROJECT-PROPERTIES-LOCATION"></xsd:element>
<xsd:element ref="SUBPROJECT-TYPE"></xsd:element>
<xsd:element ref="FOLDER-LIST"></xsd:element>
<xsd:element ref="FILE-LIST"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="SUBPROJECT-NAME" type="xsd:string">

<xsd:annotation>
<xsd:documentation></xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="SUBPROJECT-NATURE-LIST">
<xsd:annotation>
<xsd:documentation>
A list of Eclipse project natures to be associated with
this subproject
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="SUBPROJECT-NATURE" minOccurs="0"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="SUBPROJECT-NATURE" type="subprojectNatureType">

<xsd:annotation>
<xsd:documentation>
Currently only one nature is supported
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:simpleType name="subprojectNatureType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="[Link]"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:element name="SUBPROJECT-PROPERTIES-LOCATION" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The path to the subproject properties file. The path is
relative to the root project configuration folder on the
remote system.
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="SUBPROJECT-TYPE" type="subprojectType">

<xsd:annotation>
<xsd:documentation>
Currently only zos-subproject type is supported
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:simpleType name="subprojectType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="zos-subproject"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:element name="FOLDER-LIST">

10 Developer for z/OS: Managing and Extending the Eclipse Environment

 <xsd:annotation>
<xsd:documentation>
A list of folder resources contained by this subproject.
For MVS, this would be a partitioned data set
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="FOLDER" minOccurs="0"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="FOLDER">
<xsd:annotation>
<xsd:documentation>
Information related to the folder resource
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="FOLDER-NAME"></xsd:element>
<xsd:element ref="FOLDER-TYPE"></xsd:element>
<xsd:element ref="FOLDER-STATE"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="FOLDER-NAME" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The fully qualified name of the folder resource on the
remote system e.g. A.B.C on MVS
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="FOLDER-TYPE" type="folderType">

<xsd:annotation>
<xsd:documentation>
Currently the folder type must be "pds"
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:simpleType name="folderType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="pds"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:element name="FOLDER-STATE">
<xsd:annotation>
<xsd:documentation>
Information related to the state of the folder resource
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="STATE-IS-OFFLINE"></xsd:element>
<xsd:element ref="PHYSICAL-FOLDER"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="STATE-IS-OFFLINE" type="isOfflineType">

<xsd:annotation>
<xsd:documentation>
Currently the state must be online
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:simpleType name="isOfflineType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="false"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:element name="PHYSICAL-FOLDER">
<xsd:annotation>
<xsd:documentation>

Managing the development environment for a team 11

 Information related to the physical folder on the remote
system
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="FOLDER-NAME"></xsd:element>
<xsd:element ref="FOLDER-PHYSICAL-PATH"></xsd:element>
<xsd:element ref="FOLDER-TYPE"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="FOLDER-PHYSICAL-PATH" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The fully qualified name of the folder resource on the
remote system e.g. A.B.C on MVS
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="FILE-LIST">
<xsd:annotation>
<xsd:documentation>
A list of file resources contained by this subproject.
For MVS, this would be a partitioned data set member or a sequential
data set
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="FILE" minOccurs="0"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="FILE">
<xsd:annotation>
<xsd:documentation>
Information related to the file resource
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="FILE-NAME"></xsd:element>
<xsd:element ref="FILE-EXTENSION"></xsd:element>
<xsd:element ref="FILE-NAME-NO-EXTENSION"></xsd:element>
<xsd:element ref="FILE-TYPE"></xsd:element>
<xsd:element ref="FILE-STATE"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="FILE-NAME" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The fully qualified name of the file resource on the
remote system, including mapped extension e.g.
[Link]/[Link] for a partitioned data set member on MVS where
[Link] is the partitioned data set name and HELLO is the member name
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="FILE-EXTENSION" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
This should correspond to the extension defined by the
file system mapping for this system. E.g. **COBOL
data sets would have a .cbl extension
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:element name="FILE-NAME-NO-EXTENSION" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The fully qualified file name without the extension
</xsd:documentation>
</xsd:annotation>
</xsd:element>

12 Developer for z/OS: Managing and Extending the Eclipse Environment

 <xsd:element name="FILE-TYPE" type="fileType">
<xsd:annotation>
<xsd:documentation>
For MVS this would be partitioned data set member or sequential data set
</xsd:documentation>
</xsd:annotation>
</xsd:element>

<xsd:simpleType name="fileType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="pds-member"/>
<xsd:enumeration value="sequential"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:element name="FILE-STATE">
<xsd:annotation>
<xsd:documentation>
Information related to the state of the file resource
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="STATE-IS-OFFLINE"></xsd:element>
<xsd:element ref="PHYSICAL-FILE"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PHYSICAL-FILE">
<xsd:annotation>
<xsd:documentation>
Information related to the physical file on the remote
system
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="FILE-NAME"></xsd:element>
<xsd:element ref="FILE-PHYSICAL-PATH"></xsd:element>
<xsd:element ref="FILE-TYPE"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="FILE-PHYSICAL-PATH" type="xsd:string">

<xsd:annotation>
<xsd:documentation>
The fully qualified name of the file resource on the
remote system e.g. A.B.C on MVS
</xsd:documentation>
</xsd:annotation>
</xsd:element>

</xsd:schema>

Related tasks
“Creating a subproject definition file” on page 7
Subproject definition files define the set of resources that are required to build a single load module and
are in the root project definition folder or one of its subfolders.

Creating a subproject property file

Subproject property files are in the PROJECT-HOME directory or one of its subfolders.
You must complete the steps in creating a subproject definition file.
Subproject property files must be encoded in UTF-8 and have an extension of *.hbppr.
Subproject properties files support the substitution variable <HLQ>, which is replaced by the user's user
ID at connect time. This substitution variable allows sharing of property files between team members.
Although properties for host-based subprojects can be changed in the user interface, they are not saved
on the client after you disconnect from the remote system.

Managing the development environment for a team 13

 Related reference
“Subproject property schema” on page 14
The subproject property schema defines tags that are used to define a subproject property file.

Subproject property schema

The subproject property schema defines tags that are used to define a subproject property file.

<xsd:schema xmlns:xsd="[Link]
<xsd:element name="ENTRYPOINT-LANG" type="xsd:string"/>
<xsd:element name="LINK">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="LINK-PROC"></xsd:element>
<xsd:element ref="LINK-STEP"></xsd:element>
<xsd:element ref="LINK-OPTIONS"></xsd:element>
<xsd:element ref="LINK-LIBRARIES"></xsd:element>
<xsd:element ref="LINK-APPEND-CHECKBOX"></xsd:element>
<xsd:element ref="LINK-LOCATION"></xsd:element>
<xsd:element ref="USER-SPEC-LINK-INST"></xsd:element>
<xsd:element ref="INST"></xsd:element>
<xsd:element ref="LOAD-MODULE"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
<xsd:element ref="LINK-USERVARS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-COMPILE">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="LISTINGOUTPUT"></xsd:element>
<xsd:element ref="SYSDEBUG"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="COPYLIBRARIES"></xsd:element>
<xsd:element ref="SUPPORTERRORFEEDBACK"></xsd:element>
<xsd:element ref="XMLOUTPUT"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="RUNTIME-PROGRAMPARMS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="C-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="BMS-STEP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="DBRMLOCATION" type="xsd:string"></xsd:element>
<xsd:element name="SYSEVENT" type="xsd:string"></xsd:element>
<xsd:element name="PLI-EMBEDDED-SQL" type="xsd:string"></xsd:element>
<xsd:element name="LINK-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="USER-SPEC-LINK-INST" type="xsd:string"></xsd:element>
<xsd:element name="USEIMS" type="xsd:string"></xsd:element>
<xsd:element name="STEP2" type="xsd:string"></xsd:element>
<xsd:element name="DATASETNAME" type="xsd:string"></xsd:element>
<xsd:element name="CPP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ADDED-STEPS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="COBOL-STEP-OPTIONS"></xsd:element>
<xsd:element ref="COBOL-STEP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="COBOL-STEP-SUPPORT-ERRFDBK"></xsd:element>
<xsd:element ref="COBOL-STEP-XML-LOCATION"></xsd:element>
<xsd:element ref="PLI-STEP-OPTIONS"></xsd:element>
<xsd:element ref="PLI-STEP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="PLI-STEP-SUPPORT-ERRFDBK"></xsd:element>

14 Developer for z/OS: Managing and Extending the Eclipse Environment

 <xsd:element ref="PLI-STEP-XML-LOCATION"></xsd:element>
<xsd:element ref="BMS-STEP-OPTIONS"></xsd:element>
<xsd:element ref="BMS-STEP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="ASM-STEP-OPTIONS"></xsd:element>
<xsd:element ref="ASM-STEP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="ASM-STEP-SUPPORT-ERRFDBK"></xsd:element>
<xsd:element ref="ASM-STEP-XML-LOCATION"></xsd:element>
<xsd:element ref="LINK-STEP-OPTIONS"></xsd:element>
<xsd:element ref="LINK-STEP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="RUN-STEP-OPTIONS"></xsd:element>
<xsd:element ref="RUN-STEP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="CPP-OPTIONS"></xsd:element>
<xsd:element ref="CPP-ADDITIONALJCL"></xsd:element>
<xsd:element ref="C-OPTIONS"></xsd:element>
<xsd:element ref="C-ADDITIONALJCL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="MFS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MFS-COMPILE"></xsd:element>
<xsd:element ref="MFS-USERVARS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="SUBPROJECT">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="WSED-VERSION"></xsd:element>
<xsd:element ref="PROJECT-TYPE"></xsd:element>
<xsd:element ref="JOB"></xsd:element>
<xsd:element ref="ASM"></xsd:element>
<xsd:element ref="BMS"></xsd:element>
<xsd:element ref="COBOL"></xsd:element>
<xsd:element ref="PLI"></xsd:element>
<xsd:element ref="MFS"></xsd:element>
<xsd:element ref="CPP"></xsd:element>
<xsd:element ref="LINK"></xsd:element>
<xsd:element ref="ENTRYPOINT"></xsd:element>
<xsd:element ref="RUNTIME"></xsd:element>
<xsd:element ref="ADDED-STEPS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="SEPTRANSLATOR" type="xsd:string"></xsd:element>
<xsd:element name="LOCAL-PREPROC">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="GENERATED-JCL" type="xsd:string"></xsd:element>
<xsd:element name="USER-VARIABLES">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="BMS-ASSEMBLE-DSECT" type="xsd:string"></xsd:element>
<xsd:element name="PLI">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="PLI-COMPILE"></xsd:element>
<xsd:element ref="PLI-CICS"></xsd:element>
<xsd:element ref="PLI-DB2"></xsd:element>
<xsd:element ref="PLI-IMS"></xsd:element>
<xsd:element ref="PLI-USERVARS"></xsd:element>
<xsd:element ref="PLI-LOCAL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CPP-COMPILE">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="MACROS"></xsd:element>
<xsd:element ref="LISTINGOUTPUT"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
<xsd:element ref="USERLIB"></xsd:element>
<xsd:element ref="SYSEVENT"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Managing the development environment for a team 15

 <xsd:element name="COBOL-STEP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-EMBEDDED-SQL" type="xsd:string"></xsd:element>
<xsd:element name="BMS-STEP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="RUNTIME-STEP" type="xsd:string"></xsd:element>
<xsd:element name="LINK-STEP" type="xsd:string"></xsd:element>
<xsd:element name="USEC" type="xsd:string"></xsd:element>
<xsd:element name="USERLIB">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="XMLOUTPUT" type="xsd:string"></xsd:element>
<xsd:element name="RUNTIME">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="RUNTIME-PROGRAMPARMS-RUNTIMEOPTIONS"></xsd:element>
<xsd:element ref="RUNTIME-RUNTIMEOPTIONS-PROGRAMPARMS"></xsd:element>
<xsd:element ref="INBATCH"></xsd:element>
<xsd:element ref="DEBUG"></xsd:element>
<xsd:element ref="RUNTIME-PROC"></xsd:element>
<xsd:element ref="RUNTIME-STEP"></xsd:element>
<xsd:element ref="RUNTIME-OPTIONS"></xsd:element>
<xsd:element ref="RUNTIME-PROGRAMPARMS"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
<xsd:element ref="RUN-USERVARS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="COBOL-COMPILE"></xsd:element>
<xsd:element ref="COBOL-CICS"></xsd:element>
<xsd:element ref="COBOL-DB2"></xsd:element>
<xsd:element ref="COBOL-IMS"></xsd:element>
<xsd:element ref="COBOL-USERVARS"></xsd:element>
<xsd:element ref="COBOL-LOCAL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-LOCAL">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
<xsd:element ref="LOCAL-PRE-CICS"></xsd:element>
<xsd:element ref="LOCAL-PREPROC"></xsd:element>
<xsd:element ref="ENV-VAR"></xsd:element>
<xsd:element ref="COBOL-EMBEDDED-SQL"></xsd:element>
<xsd:element ref="COBOL-DB2CONN"></xsd:element>
<xsd:element ref="COBOL-DB2-OTHERSQLOPTS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ASM-STEP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="PLI-IMS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USEIMS"></xsd:element>
<xsd:element ref="LIBRARY"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="USEDB2" type="xsd:string"></xsd:element>
<xsd:element name="ADDITIONALJCL" type="xsd:string"></xsd:element>
<xsd:element name="LINK-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ASM-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="SYSDEBUG" type="xsd:string"></xsd:element>
<xsd:element name="COPYLIBRARIES" type="xsd:string"></xsd:element>
<xsd:element name="C-ADDITIONALJCL">

16 Developer for z/OS: Managing and Extending the Eclipse Environment

 <xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="LOCAL-PRE-CICS" type="xsd:string"></xsd:element>
<xsd:element name="PLI-DB2CONN">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="RUN-STEP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="JOB">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="JOB-CARD"></xsd:element>
<xsd:element ref="GENERATED-JCL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="LIBRARY" type="xsd:string"></xsd:element>
<xsd:element name="RUN-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="SYSLIB" type="xsd:string"></xsd:element>
<xsd:element name="BMS-ASSEMBLE">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="BMS-ASSEMBLE-MAP"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="BMS-ASSEMBLE-DSECT"></xsd:element>
<xsd:element ref="COPYLIBRARIES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="PLI-DB2-OTHERSQLOPTS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-IMS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USEIMS"></xsd:element>
<xsd:element ref="LIBRARY"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-STEP-XML-LOCATION">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="PROJECT-TYPE" type="xsd:string"></xsd:element>
<xsd:element name="C-COMPILE">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="MACROS"></xsd:element>
<xsd:element ref="LISTINGOUTPUT"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
<xsd:element ref="USERLIB"></xsd:element>
<xsd:element ref="SYSEVENT"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
<xsd:element ref="USEC"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-DB2CONN">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="CPP">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="CPP-COMPILE"></xsd:element>
<xsd:element ref="C-COMPILE"></xsd:element>
<xsd:element ref="CPP-USERVARS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CPP-USERVARS">

Managing the development environment for a team 17

 <xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="OPTIONS" type="xsd:string"></xsd:element>
<xsd:element name="PLI-STEP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="INCLIBRARIES" type="xsd:string"></xsd:element>
<xsd:element name="PLI-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="PLI-DB2">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USEDB2"></xsd:element>
<xsd:element ref="PRECOMPILER"></xsd:element>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
<xsd:element ref="DBRMLOCATION"></xsd:element>
<xsd:element ref="SYSTSIN"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-DB2-OTHERSQLOPTS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="LINK-STEP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="PLI-STEP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="RUNTIME-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="OBJECTDECK" type="xsd:string"></xsd:element>
<xsd:element name="BMS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="BMS-ASSEMBLE"></xsd:element>
<xsd:element ref="BMS-USERVARS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="WSED-VERSION" type="xsd:string"></xsd:element>
<xsd:element name="LINK-LIBRARIES">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="LISTINGOUTPUT" type="xsd:string"></xsd:element>
<xsd:element name="MAINMODULE" type="xsd:string"></xsd:element>
<xsd:element name="ASM-STEP-SUPPORT-ERRFDBK">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ENTRYPOINT">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="ENTRYPOINT-COBOL-NAME"></xsd:element>
<xsd:element ref="ENTRYPOINT-PLI-NAME"></xsd:element>
<xsd:element ref="ENTRYPOINT-ASM-NAME"></xsd:element>
<xsd:element ref="ENTRYPOINT-CPP-NAME"></xsd:element>
<xsd:element ref="ENTRYPOINT-LANG"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ASM">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="ASM-ASSEMBLE"></xsd:element>
<xsd:element ref="ASM-USERVARS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-DB2">

18 Developer for z/OS: Managing and Extending the Eclipse Environment

 <xsd:complexType>
<xsd:sequence>
<xsd:element ref="USEDB2"></xsd:element>
<xsd:element ref="PRECOMPILER"></xsd:element>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
<xsd:element ref="DBRMLOCATION"></xsd:element>
<xsd:element ref="SYSTSIN"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-STEP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="STEPNAME" type="xsd:string"></xsd:element>
<xsd:element name="PLI-CICS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USECICS"></xsd:element>
<xsd:element ref="SEPTRANSLATOR"></xsd:element>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ENTRYPOINT-ASM-NAME" type="xsd:string"></xsd:element>
<xsd:element name="PLI-LOCAL">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
<xsd:element ref="LOCAL-PRE-CICS"></xsd:element>
<xsd:element ref="LOCAL-PREPROC"></xsd:element>
<xsd:element ref="ENV-VAR"></xsd:element>
<xsd:element ref="PLI-EMBEDDED-SQL"></xsd:element>
<xsd:element ref="PLI-DB2CONN"></xsd:element>
<xsd:element ref="PLI-DB2-OTHERSQLOPTS"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="RUNTIME-PROC" type="xsd:string"></xsd:element>
<xsd:element name="LINK-PROC" type="xsd:string"></xsd:element>
<xsd:element name="INST" type="xsd:string"></xsd:element>
<xsd:element name="LINK-APPEND-CHECKBOX" type="xsd:string"></xsd:element>
<xsd:element name="JOB-CARD" type="xsd:string"></xsd:element>
<xsd:element name="USECICS" type="xsd:string"></xsd:element>
<xsd:element name="BMS-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="RUNTIME-PROGRAMPARMS-RUNTIMEOPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ASM-STEP-XML-LOCATION">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="CPP-OPTIONS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ENTRYPOINT-COBOL-NAME">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="LOAD-MODULE" type="xsd:string"></xsd:element>
<xsd:element name="DEBUG" type="xsd:string"></xsd:element>
<xsd:element name="COBOL-CICS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USECICS"></xsd:element>

Managing the development environment for a team 19

 <xsd:element ref="SEPTRANSLATOR"></xsd:element>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="SYSLIB"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="PLI-STEP-SUPPORT-ERRFDBK">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="PLI-STEP-XML-LOCATION">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="MACLIBRARIES" type="xsd:string"></xsd:element>
<xsd:element name="LINK-LOCATION">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="MACROS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ENTRYPOINT-CPP-NAME" type="xsd:string"></xsd:element>
<xsd:element name="PRECOMPILER" type="xsd:string"></xsd:element>
<xsd:element name="MFS-COMPILE">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="LISTINGOUTPUT"></xsd:element>
<xsd:element ref="STEPNAME"></xsd:element>
<xsd:element ref="STEP2"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="LINK-STEP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="SUPPORTERRORFEEDBACK" type="xsd:string"></xsd:element>
<xsd:element name="ASM-STEP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ENTRYPOINT-PLI-NAME" type="xsd:string"></xsd:element>
<xsd:element name="RUNTIME-RUNTIMEOPTIONS-PROGRAMPARMS">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="INBATCH" type="xsd:string"></xsd:element>
<xsd:element name="PLI-COMPILE">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="LISTINGOUTPUT"></xsd:element>
<xsd:element ref="SYSDEBUG"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="INCLIBRARIES"></xsd:element>
<xsd:element ref="SUPPORTERRORFEEDBACK"></xsd:element>
<xsd:element ref="XMLOUTPUT"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="SYSTSIN" type="xsd:string"></xsd:element>
<xsd:element name="RUN-STEP-ADDITIONALJCL">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="MFS-USERVARS">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="USER-VARIABLES"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="COBOL-STEP-SUPPORT-ERRFDBK">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="ENV-VAR">
<xsd:complexType></xsd:complexType>
</xsd:element>
<xsd:element name="BMS-ASSEMBLE-MAP" type="xsd:string"></xsd:element>
<xsd:element name="ASM-ASSEMBLE">
<xsd:complexType>

20 Developer for z/OS: Managing and Extending the Eclipse Environment

 <xsd:sequence>
<xsd:element ref="MAINMODULE"></xsd:element>
<xsd:element ref="DATASETNAME"></xsd:element>
<xsd:element ref="OPTIONS"></xsd:element>
<xsd:element ref="LISTINGOUTPUT"></xsd:element>
<xsd:element ref="OBJECTDECK"></xsd:element>
<xsd:element ref="MACLIBRARIES"></xsd:element>
<xsd:element ref="SUPPORTERRORFEEDBACK"></xsd:element>
<xsd:element ref="XMLOUTPUT"></xsd:element>
<xsd:element ref="ADDITIONALJCL"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Related tasks
“Creating a subproject property file” on page 13
Subproject property files are in the PROJECT-HOME directory or one of its subfolders.

Using host-based projects

After host-based projects are configured on the remote system, they are automatically available to any
user who logs on to that system with a user ID corresponding to one of the user folders on the remote
system.
For each instance file in the user folder, a host-based project is created on the user's workstation, along
with its subprojects and their properties.
Host-based projects behave similarly to workstation-based projects, with the following exceptions:
• You cannot rename or delete the projects or subprojects.
• You cannot add or remove resources from the subprojects or subprojects from the project.
• You cannot create new remote projects or subprojects associated with host-based project systems.
• Any actions that allow the user to alter the structure or contents of a host-based project are disabled.
• Although properties for host-based subprojects can be changed in the user interface, they are not saved
on the client after you disconnect from the remote system.
If changes to the structure of the project are required, the definitions on the remote system must be
updated and the projects on the workstation refreshed. To refresh projects on the workstation, you must
disconnect and reconnect to the system that contains the project definitions.
Because project definitions are on the remote system, host-based projects are not persisted on
the workstation. They are removed when you disconnect from the system that contains the project
definitions.
Each system that you connect to might or might not have host-based projects enabled. For a system with
host-based projects enabled, no projects that are associated with that system are visible in the z/OS
Projects view until you connect. For a system without host-based projects, any existing projects that are
associated with that system are visible as soon as you open the z/OS Projects perspective.
If you require projects that persist after you disconnect and contain resources on a system with host-
based projects enabled, you can set up a user ID on that system that does not have a corresponding
user folder. If you connect with that user ID, you can create workstation-based remote projects that are
persisted after you disconnect.
Related concepts
“Host-based projects” on page 1
A host-based project is defined on a z/OS system and downloaded to the workstation automatically when
you connect to the remote system. Host-based projects enable an installation to define and automatically
propagate projects on client workspaces from a central location. They provide a means for standardizing
project definitions. A host-based project includes the project, its properties, and its member resources.
Related tasks
“Configuring host-based projects” on page 1

Managing the development environment for a team 21

 You configure host-based projects for a remote system by creating a set of configuration files on that
system.
“Solving problems with host-based projects” on page 22
Most problems with host-based projects are the result of improper configuration on the remote system,
such as incorrect paths to definition files or errors in the syntax of the definition files themselves. Because
these problems usually show up as missing host-based projects, subprojects, or files, which are easily
overlooked, error messages help with problem determination.

Solving problems with host-based projects

Most problems with host-based projects are the result of improper configuration on the remote system,
such as incorrect paths to definition files or errors in the syntax of the definition files themselves. Because
these problems usually show up as missing host-based projects, subprojects, or files, which are easily
overlooked, error messages help with problem determination.
For severe problems, a window box opens with a detailed message of the error condition and the
host-based project stops loading. Project creation actions that precede the error are not rolled back,
but, disconnecting from the remote system removes the projects from the workstation. For less
severe problems, such as a file listed in a subproject not being found, the message is logged in the
CommonBaseEvents log file. Users might not be aware of any such problem until they notice the missing
file and look into the log.
Problems with references to definition files
If a definition file contains an error in a reference to another definition file or to a folder, such as
typographical error or an error in a file path name, an error message indicates which file was not found
and which file contained the error.
Problems with syntax in definition files
If a definition file contains an error in the XML tags, such as a typographical error or a missing end tag,
the XML parser throws an exception and an error message indicates the definition file that contains
the error.
Problems with references to resources
If a definition file refers to a partitioned data set, data set member, or sequential data set that cannot
be found, either because the definition file contains a typographical error or the file does not exist,
the subproject is created, but the file in error is not. An error message in the CommonBaseEvents
log (provided the logging level is set to SEVERE or lower for the [Link] logger)
indicates which file was not found.

Planning a push-to-client environment

The Developer for z/OS product offers the push-to-client feature for administering and sharing
connections, preferences, properties, and configurations so that developers have a consistent and
centralized development environment.
You can take either of two approaches to creating a development environment with the Developer for
z/OS product:
• You can allow a decentralized environment in which developers create their own connections to remote
systems, CICS®, or Db2®; set preferences for their workspaces; and create and manage their own
property groups and debug and run configurations.
• You can centralize and automate the creation and distribution of connections, preferences, properties,
and configurations so that developers’ workspaces are consistent across the site and settings are
downloaded to workspaces automatically when developers connect to a remote system. The push-to-
client feature provides the tools that you need to create a centralized and automated development
environment.
By using the push-to-client feature, you can distribute the following configuration files:
• Global configuration files:
– Eclipse preferences

22 Developer for z/OS: Managing and Extending the Eclipse Environment

 – Remote system connections
– Menu Manager files
– Software Analyzer Configurations
– Snippets
• System configuration files
– Remote index locations
– z/OS file system mappings
– Property groups
– Default values
– Host-based projects
In a push-to-client environment, these configuration files are stored on a remote system. When a
workspace connects to the remote system, the configuration files are downloaded to the workspace.
In this way, you can define a set of property groups, for example, that is automatically downloaded when
a connection is made. If you update the configurations between connections, developers are prompted to
update their workspaces when they connect.
In a decentralized environment, developers still have the opportunity to share configurations by exporting
them from one workspace and importing them into another workspace.
For more information about the push-to-client feature and about migrating configurations from one
workspace to another, see the related topics.
Related concepts
“Distributing updates by using push-to-client” on page 23
You can configure Developer for z/OS to automatically distribute updates to configuration files, preference
settings, and remote system connections when client workstations connect to a remote system. This
feature is called push-to-client. By using it, you can store workspace configurations in a central location
and push them to client workstations so that your developers have a consistent workspace environment.
Related tasks
Migrating resources and settings to another workspace

Distributing updates by using push-to-client

You can configure Developer for z/OS to automatically distribute updates to configuration files, preference
settings, and remote system connections when client workstations connect to a remote system. This
feature is called push-to-client. By using it, you can store workspace configurations in a central location
and push them to client workstations so that your developers have a consistent workspace environment.

Push-to-client overview
Implementing a push-to-client environment involves several tasks: some on the z/OS system and some
on a client workstation. The following is an overview of how to implement a push-to-client environment. It
defines some of the terms and resources that are used in this environment. The details for implementing
push-to-client are described in subtopics.
1. Configure push-to-client on z/OS.
Each remote system from which you intend to distribute product updates and configurations must be
set up to support push-to-client.
a. One z/OS system must be defined as the primary system. The primary system is the controlling
system in a push-to-client environment. Only one z/OS system can be defined as primary. The
primary system stores global configuration files, which apply to all systems in the push-to-client
environment, and system configuration files, which apply only to the primary system itself. The
global configurations are product updates, Eclipse preferences, Menu Manager files, and remote
system connections.

Managing the development environment for a team 23

 b. Other z/OS systems can be enabled for push-to-client as non-primary systems. Non-primary
systems define only system configurations, which apply only to the non-primary system itself.
System configurations are host-based projects, property groups, default values, file mappings, and
remote index search.
The starting point for configuring push-to-client on a z/OS system is a root file that is called
[Link], which is in the /etc/zexpl/ directory on the z/OS system. This file
contains entries that specify configuration parameters, such as:
• Whether the function is enabled for product updates: indicated by setting
[Link]=true.
• Whether the function is enabled for configuration updates: indicated by setting
[Link]=true.
• Whether the current system is the primary system, that is, the system that controls the push-to-
client feature: indicated by specifying [Link]=true|false.
• Where to find the main configuration file, [Link]: indicated by setting
[Link]=/var/zexpl/pushtoclient, the default location. The key mapping file
contains pointers to a set of files that contain the application-related settings. These pointers are
created from a Developer for z/OS client as part of the configuration file export process, described in
step “4” on page 24.
• Whether group-level control of product and configuration updates is enabled: indicated by setting an
access control attribute for certain configuration parameters in the [Link]
file. This feature allows a system administrator to create client groups and provide updates
that are specific to each group. For example, to enable group control of configuration updates
through RACF®, specify [Link]=saf. To enable group control of configuration updates
through LDAP, specify [Link]=ldap. In the directory identified by the setting of
[Link]=/var/zexpl/pushtoclient, you must also create a folder named grouping. In the
grouping folder, you must create a folder for each RACF or LDAP security group that is defined for
use. The folder name must match the name of the security group exactly.
For information about setting up LDAP access groups and SAF-based access groups, see Push-to-
client considerations in the Host Configuration Reference.
2. Configure a model workspace with settings that you want to push out to other workspaces when
access groups, see Push-to-client considerations in the Host Configuration Reference.
3. Configure a model workspace with settings that you want to push out to other workspaces when they
connect to the z/OS system.
After the remote system is set up, you can begin configuring the Developer for z/OS settings you want
to push out to the rest of the organization. For most settings, such as Eclipse preferences, remote
system connections, property groups, and file system mappings, this task is accomplished by updating
the settings locally on a client. Some settings, such as product updates, host-based projects, and
default values, must be configured manually on the z/OS system.
If group-level control of updates is enabled for the push-to-client servers, then the model workspace
is bound to a particular group when you export configurations to the server. Binding a workspace to
a group means that the workspace defines configuration and preferences settings for that group only.
Therefore, you need to define one model workspace for each push-to-client group defined on the
servers.
4. Export the workspace settings to the z/OS system by using the Developer for z/OS configuration export
wizard.
The export wizard uploads the local configuration files (Eclipse preferences, remote system
connections, property groups, and file system mappings) from the model workspace to the z/OS
system. Only users who have authority to write files to the folder that contains the key mapping file on
the remote system can export settings. After the settings are exported, users who connect to the z/OS
system are prompted to update their workspaces with these settings.
For information about configuring and exporting the Developer for z/OS settings you want to push out to
client workstations, see the remaining topics that are linked to in this section.

24 Developer for z/OS: Managing and Extending the Eclipse Environment

Creating and distributing configuration files
The push-to-client feature provides tools for system administrators to define remote system connections,
define configuration files, and set client workstation preferences from a central location. These
connection definitions, configuration files, and preferences can be distributed to individual client
workstations automatically when they connect to a remote system.
To create and distribute remote connection definitions, configuration files, and preferences from a central
location, the server must be configured to enable push-to-client updates.
When a user connects to the primary remote system or to another remote system for which system
configuration files are defined, the configuration files that are stored on that system are compared to the
configuration files on the workstation. If updates are available, users are prompted to install them.
By using the push-to-client feature, you can distribute the following configuration files:
• Global configuration files:
– Eclipse preferences
– Remote system connections
– Menu Manager files
– Software Analyzer Configurations
– Snippets
• System configuration files
– Remote index locations
– z/OS file system mappings
– Property groups
– Default values
– Host-based projects
To create and distribute configuration files, do these steps. Each of these steps links to more information
about completing the step.
1. Create a workspace that serves as the model workspace for the configurations and preferences to be
distributed.
2. From the model workspace, create connections to the primary remote system from which you intend
to distribute global and system configurations and to each remote system from which you intend to
distribute system configurations.
3. Configure remote system connections, configuration files, and preferences in the model workspace.
4. Export the configuration files that are to be distributed to other client workspaces.
Related concepts
“Distributing updates by using push-to-client” on page 23
You can configure Developer for z/OS to automatically distribute updates to configuration files, preference
settings, and remote system connections when client workstations connect to a remote system. This
feature is called push-to-client. By using it, you can store workspace configurations in a central location
and push them to client workstations so that your developers have a consistent workspace environment.

Creating a model workspace for push-to-client configuration

A model workspace is a Developer for z/OS workspace from which you create the remote system
connections, configuration files, and preference settings to be distributed to other client workstations.
Creating a model workspace for push-to-client configurations is no different from creating any other
Developer for z/OS workspace. It is good practice to dedicate a workspace to configuration so that other
development activities do not alter the remote system connections, configuration files, and preference
settings that are intended for general distribution. The purpose of using a model workspace is for
the workspace owner (or push-to-client administrator) to set up preferences, system connections, and

Managing the development environment for a team 25

 configurations the way ordinary users must have them in their workspaces. Set up the workspace by using
the product user interface and then export those settings by using the Developer for z/OS configuration
export wizard.
If group-level control of updates is enabled for the push-to-client servers, then the model workspace is
bound to a particular group when you export configurations to the server. Binding a workspace to a group
means that the workspace defines configuration and preferences settings for that group only. Therefore,
you need to define one model workspace for each push-to-client group defined on the servers.
• For information about creating a workspace, see Switching workspaces.
• For information about group-level control of configurations, see Push-to-client considerations in the
Host Configuration Reference.

Defining connections, configuration files, and preferences for push-to-client

configuration
To set up connections, configuration files, and preferences for distribution in a push-to-client
environment, define global and system configuration files.

Global configuration files

Global configuration files are managed on the primary remote system. The primary remote system is
a z/OS system that is defined during host installation and configuration as the controlling system for
push-to-client configuration.

Table 1. Global configuration files. The global configuration files include these settings.
File Type Description More Information
Eclipse Preferences These configuration files are Eclipse Preferences
exported from the settings in z/OS Preferences
the Preferences window of a
workspace that is connected
to the primary remote system.
The push-to-client feature
uses the base Eclipse export
mechanism for preferences,
which saves only changes to
default values. Eclipse also
exports different preferences to
various discrete .pref files. The
result is that the push-to-client
feature exports and distributes
only those Eclipse preference
files that contain nondefault
values.
Remote System Connections These configuration files are Connecting to a z/OS system
exported from the Remote
Systems view of a workspace
that is connected to the primary
remote system. They include all
remote system connections that
are defined in this view.

26 Developer for z/OS: Managing and Extending the Eclipse Environment

Table 1. Global configuration files. The global configuration files include these settings. (continued)
File Type Description More Information
Menu Manager Files These configuration files are “Creating menu actions in Menu
exported from the files and Manager” on page 39
settings that are created by using
the Menu Manager preference
pages in a workspace that is
connected to the primary system.
The configuration files include
all user-defined Menu Manager
menu and action files in the
workspace.
Restriction: By using push-to-
client, you can export only user-
defined actions and menus. You
cannot export any of the base
file actions that are included with
Menu Manager.

Software Analyzer Configurations These configuration files are Creating software analysis
exported from the Software configurations
Analyzer configurations that are
defined on a workspace that is
connected to the primary remote
system. They include all software
analysis configurations that are
defined for each remote system.
Snippets Configuration File This configuration file is exported Snippets
from the Snippets view in a
workspace that is connected to
the primary system. The code
snippets are compressed into an
archive file and uploaded to the
primary remote system.
Important: When snippets
are downloaded to a client
workstation, all snippets are
replaced by those that are
downloaded from the remote
system. The push-to-client
feature cannot merge local
snippets with those downloaded
from the remote system.

System configuration files

System configuration files are managed on the primary remote system and on other remote systems to
which users can connect.

Managing the development environment for a team 27

 Table 2. System configuration files. The system configuration files include these settings.
File Type Description More Information
Remote Index Locations These configuration files are Using the remote index search
exported for each remote system
connection that is defined on a
workspace that is connected to
the primary remote system. They
include all remote index search
locations that are defined for
each remote system.
z/OS File System Mapping These configuration files are Mapping data sets and
Configuration Files exported from the z/OS File partitioned data set members
System Mapping view of a
workspace that is connected
to the primary remote system.
They include all z/OS file system
mappings that are defined
for each remote system that
is defined in the Remote
Systems view. The push-to-client
feature can export three types
of z/OS file system mapping
configuration files:
• MVS Files - System Mapping
files are defined for a remote
system.
• MVS Files - Bidi Conversion
Table files are defined for
systems that use bidirectional
conversion tables.
• MVS Files - Resource Mapping
files are defined for specific
data sets on a remote system.

Property Group Configuration These configuration files are Creating and editing property
Files - Property Groups exported from the Property groups
Group Manager for each remote
system connection that is defined
on a workspace that is connected
to the primary remote system.
They include all property groups
that are defined for each remote
system.
Property Group Configuration These configuration files are Configuring default property
Files - Default Values created manually. They define values
the default property group values
to be downloaded to the client
workstation when it connects to a
remote system.

28 Developer for z/OS: Managing and Extending the Eclipse Environment

Table 2. System configuration files. The system configuration files include these settings. (continued)
File Type Description More Information
Host-based Project Configuration These configuration files are “Configuring host-based
Files created manually. They define projects” on page 1
z/OS projects and MVS
subprojects to be loaded into the
z/OS Projects view when the
client workstation connects to a
remote system.

Related information
Preferences

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, [Link]. 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.

Managing the development environment for a team 29

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

30 Developer for z/OS: Managing and Extending the Eclipse Environment

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
Related reference
RSE returns message RSEG1242 on connection attempt
Related information
Defining extra Java startup parameters with _RSE_JAVAOPTS

The system property group file

The system property group file defines property groups that are available to users when they connect to
a remote system. This file is generated when an administrator exports property groups for distribution to
client workspaces. It is not necessary to create this file; information about its content and structure are
included here for reference only.
When a user connects to a system for the first time, the Developer for z/OS product determines whether a
system property group file exists on the remote system. If so, the property groups that are defined in that
file are loaded from the system file, and users see them in the Property Group Manager view. If a current
property group is specified in the file, that property group is associated with the MVS Files node in the
Remote Systems view. The property groups are persisted in the workspace just like the property groups
the user creates. If the system property group file is updated, users are prompted to replace the property
groups that were originally loaded from the system with the updated property groups.
The system property group file is [Link] and contains the following tags. It is encoded in
UTF-8. For the system property group schema, see the related topics.

<?xml version="1.0" encoding="UTF-8"?>

<PROPERTY-GROUPS>
<PROPERTY-GROUP>
<NAME>property group name</NAME>
<DESCRIPTION>property group description</DESCRIPTION>

Managing the development environment for a team 31

 <APPLICATION-LANGUAGE>application language</APPLICATION-LANGUAGE>
<CATEGORY-INSTANCE>
<CATEGORY>category name</CATEGORY>
<PROPERTY>
<NAME>property name</NAME>
<VALUE>property value</VALUE>
</PROPERTY>
</CATEGORY-INSTANCE>
</PROPERTY-GROUP>
</PROPERTY-GROUPS>

<PROPERTY-GROUPS>
Contains one or more <PROPERTY-GROUP> tags.
<PROPERTY-GROUP>
Defines a property group and the property categories for the group. This tag can contain one <NAME>
tag, one <DESCRIPTION> tag, and one or more <CATEGORY-INSTANCE> tags.
<NAME>
Specify the name of the property group, such as COBOL property group.
<DESCRIPTION>
A description of the property group, such as Contains properties for compiling COBOL
programs to run in debug mode. This tag is optional.
<APPLICATION-LANGUAGE>
Specify the application language, such as "COBOL" or "PL/I". This tag is optional.
<CATEGORY-INSTANCE>
Specify the property categories to be included in the property group. This tag can contain one
<NAME> tag and one or more <PROPERTY> tags.
<CATEGORY>
Specify the name of a property category to include in the property group. See the Related References
for a list of valid category names.
<PROPERTY>
Specify one or more property <NAME> and <VALUE> pairs to include for the category. For a list of valid
property names, see the related topics.
Related reference
“System property group schema” on page 32
The system property group schema defines tags that are used to define a system property group file.
“Sample system property group file” on page 33
This example illustrates a system property group file.
Category and property names

System property group schema

The system property group schema defines tags that are used to define a system property group file.

<xsd:schema xmlns:xsd="[Link]
<xsd:element name="PROPERTY-GROUPS">
<xsd:annotation>
<xsd:documentation>
These property groups will be available when users connect
to this system for the first time.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0" ref="PROPERTY-GROUP"></xsd:element>
<xsd:element name="SYSTEM-CURRENT-PROPERTY-GROUP" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
The name of the property group that will be the current property group
for MVS files when the user connects to the system for the first time.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>

32 Developer for z/OS: Managing and Extending the Eclipse Environment

 </xsd:element>
<xsd:element name="PROPERTY-GROUP">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="NAME" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
The name must be unique among the property groups for the system.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element minOccurs="0" name="DESCRIPTION" type="xsd:string"></xsd:element>
<xsd:element minOccurs="0" name="APPLICATION-LANGUAGE" type="xsd:string">
<xsd:element maxOccurs="unbounded" minOccurs="0" ref="CATEGORY-INSTANCE"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CATEGORY-INSTANCE">
<xsd:annotation>
<xsd:documentation>
A category instance has property values for properties defined in
a particular category.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="CATEGORY" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
The name of the category for the category instance.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element maxOccurs="unbounded" ref="PROPERTY"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="PROPERTY">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="NAME" type="xsd:string"></xsd:element>
<xsd:element name="VALUE" type="xsd:string"></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Sample system property group file

This example illustrates a system property group file.

<?xml version="1.0" encoding="UTF-8"?>

<PROPERTY-GROUPS>
<PROPERTY-GROUP>
<NAME>COBOL PROPERTY GROUP</NAME>
<APPLICATION-LANGUAGE>COBOL</APPLICATION-LANGUAGE>
<CATEGORY-INSTANCE>
<CATEGORY>COBOL_SETTINGS</CATEGORY>
<PROPERTY>
<NAME>HOST_COMPILE_OPTIONS</NAME>
<VALUE>TEST</VALUE>
</PROPERTY>
<PROPERTY>
<NAME>COMPILE_JCL_PROCEDURE_NAME</NAME>
<VALUE>ELAXFCOC</VALUE>
</PROPERTY>
</CATEGORY-INSTANCE>
</PROPERTY-GROUP>
</PROPERTY-GROUPS>

Exporting push-to-client configuration files

After you configure remote system connections, configuration files, and preferences for push-to-client
configurations, you can export them to the remote system for distribution to client workspaces.
To export system or global configuration settings to the remote system, you must have write access to
the push-to-client configuration files on the remote system. File permissions can be set for three types

Managing the development environment for a team 33

 of users: owner, group, and other. File permissions for the push-to-client directory on the remote system
are set by using the [Link] directive in the [Link] file. The default
setting allows read and write for owner (the user ID who created a file) and group, and read for other.
Exporting configurations for push-to-client distribution generates configuration files and transfers them to
the remote system. After the files are exported, they are automatically downloaded to client workstations
when they connect to the remote system.
By using the push-to-client feature, you can distribute the following configuration files:
• Global configuration files:
– Eclipse preferences
– Remote system connections
– Menu Manager files
– Software Analyzer Configurations
– Snippets
• System configuration files
– Remote index locations
– z/OS file system mappings
– Property groups
– Default values
– Host-based projects
Note: Some configuration files, such as installation configuration files, host-based projects, and default
values, are created manually on the remote system and not exported from the workstation.
To export push-to-client configuration files:
1. Switch to the model workspace as described in “Creating a model workspace for push-to-client
configuration” on page 25.
If group-level control of updates is enabled for the push-to-client servers, then the model workspace
is bound to a particular group when you export configurations to the server. Binding a workspace to
a group means that the workspace defines configuration and preferences settings for that group only.
Therefore, you need to define one model workspace for each push-to-client group defined on the
servers.
2. Connect to the remote system to which you want to export configuration files:
a) Select the remote system in the Remote Systems view.
b) Click Connect on the menu.
Remember: The push-to-client function supports only one primary system. Before you attempt to
export configuration files, verify that you are connected to only one primary system. If you are
exporting to a primary system that is different from the primary system to which you last exported
configuration files (for example, if your site uses one primary system for testing and another for
production), a window prompts you to verify that you are connected to the correct primary system.
3. From the workspace menu bar, click File > Export.
The Export window opens.
4. In the Export window, click + to expand IBM z/OS Explorer.
5. Select Configuration Files.
6. Click Next.
• If the remote system is the primary system, the Global Configuration Files window opens.
• If the remote system is not the primary system, the System Configuration Files window opens.
Each of these windows contains two sections:

34 Developer for z/OS: Managing and Extending the Eclipse Environment

 • Global configuration or System configuration lists configuration files that can be exported from
the workstation to the remote system.
• Key mapping update lists configuration files that are created on the remote system. You cannot
export these files from the workstation.
If the product is configured to support configuration groups, this window might also include a
Configuration group list. Configuration groups are controlled on the remote system..
7. If the push-to-client environment is configured to support configuration groups, select the
configuration group to which you want to export the configuration files.
If the model workspace is not bound to a group, you can select a group from this list. If the
workspace is bound to a group, the group name is displayed in this field and you cannot select a
different group.
Some configurations, such as Eclipse Preferences, offer you the opportunity to select specific
configuration files to export.
8. Optional: To see the list of configuration files, expand the configuration.
9. Optional: To display the default locations and names of the configuration files on the remote system,
select Show export properties.
The following export properties are displayed:
• Export Path: The location on the remote system to which the configuration file is to be exported.
• File Mask: The file name pattern for the configuration file, which is useful when many configuration
files are saved in the same container.
• Encoding: The encoding of the configuration file on the remote system.
10. Select the checkbox next to the configuration files you want to export and click Next or Finish.
The configuration files are uploaded to the remote system. Some configurations, such as Software
Analyzer Configurations, might offer you the opportunity to select specific configuration files to
export. If you selected a configuration that provides this option, a window that lists available
configuration files opens.
11. Optional: Select the files that you want to export and click OK.
Related concepts
“Distributing updates by using push-to-client” on page 23
You can configure Developer for z/OS to automatically distribute updates to configuration files, preference
settings, and remote system connections when client workstations connect to a remote system. This
feature is called push-to-client. By using it, you can store workspace configurations in a central location
and push them to client workstations so that your developers have a consistent workspace environment.
Related reference
“Key mapping file” on page 37
The key mapping file is generated when you export configuration files. It stores the names, locations, and
character encodings of configuration files that are used in a push-to-client configuration environment.

Resetting workspace configuration files

You can reset the workspace configuration files that you downloaded from the remote system by clearing
the cached files.
Remote configuration files are stored in your workspace in a folder named
workspacePath\RemoteConfigurationFiles. This folder contains the following subfolders:
• A folder that is named global, which contains global configurations. Global configurations are defined
on the primary push-to-client server.
• One folder for each remote system to which you connect and that is enabled for push-to-client.
Clear Cached Files on the Configuration Files preference page deletes some of the contents of the
RemoteConfigurationFiles folder.
You might consider clearing the cached files in the following circumstances:

Managing the development environment for a team 35

 • If you are the push-to-client administrator, and you discover that you set preferences or configured
features in a way that you did not intend to export to the remote system or group with which the
workspace is associated.
If you discover that you exported configurations that you did not intend to export, then you can clear the
cached files, reconfigure the workspace, and then export the configurations again. Clear Cached Files
provides a way to start over with workspace configurations.
• If you downloaded configurations that you did not intend to download when you connected to a remote
system.
When you connect to a remote system, the push-to-client feature prompts you with a list of recent
configuration updates. From this list, you can select the specific configurations that you want to
download. If you select a configuration by mistake, you can clear the cached files, disconnect from
the remote system, and then connect again to choose the configurations you want to download.
Important: If you changed configurations that are downloaded from a remote system and you clear the
cached files, then any local changes you made to the downloaded configurations are overwritten the next
time you connect to the remote system.
Configurations that you create locally, such property groups, are saved in a folder that is called client
and are not deleted when you clear the cached files.
To reset downloaded configuration files:
1. On the Preferences window, navigate to Remote Systems > Configuration Files.
2. Click Clear Cached Files.
The next time that you connect to any of the remote systems that are enabled for push-to-client, you
are prompted to accept configuration changes.
Clearing the cached files affects your workspace in the following ways:
• Eclipse preferences: No change. The preferences that you set are left as they were even after the
cache is cleared. The Eclipse preferences are managed by the Open RSE base program, which has
its own repository for the preferences. Clearing the cached files deletes only the local files in the
RemoteConfigurationFiles folder.
• Remote connections: No change. The remote connections are managed by the Open RSE base program,
which has its own repository for the remote connections.
• Property Groups: The imported property groups are deleted. Property groups use the
RemoteConfigurationFiles folder as its repository and do not have another repository.
• Mappings: The imported mappings are deleted.
• Software Analyzer Configurations: No change. The software analyzer has a different repository from the
RemoteConfigurationFiles folder.
Related concepts
“Distributing updates by using push-to-client” on page 23
You can configure Developer for z/OS to automatically distribute updates to configuration files, preference
settings, and remote system connections when client workstations connect to a remote system. This
feature is called push-to-client. By using it, you can store workspace configurations in a central location
and push them to client workstations so that your developers have a consistent workspace environment.
Related tasks
Setting preferences for configuration updates
Updating workspace configurations and preferences
Related information
Connecting to a z/OS system

36 Developer for z/OS: Managing and Extending the Eclipse Environment

Key mapping file
The key mapping file is generated when you export configuration files. It stores the names, locations, and
character encodings of configuration files that are used in a push-to-client configuration environment.
The key mapping file is a UTF-8 encoded XML file that is named [Link]. Its default
location on the z/OS system is /var/zexpl/pushtoclient/[Link]. This location is defined
in the [Link] property of the /etc/zexpl/[Link] file. For
more information about the [Link] file, see the IBM Developer for z/OS Host
Configuration Guide (SC23-7658).
The key mapping file contains the following tags for each configuration file:
<fileId>
Identifies the configuration file. This tag can contain the following values, described here by using the
label that is displayed on the Export window for each file:
• [Link] Install Configuration Files - Version
Configuration
• [Link] Install Configuration Files - Response Files
• [Link] Remote System Connections
• [Link] Eclipse Preferences
• [Link] Host-based
Project Configuration Files
• [Link] z/OS File System Mapping
Configuration Files - MVS Files - Resource Mapping
• [Link] z/OS File System Mapping Configuration Files -
MVS Files - Bidi Conversion Table
• [Link] z/OS File System Mapping
Configuration Files - MVS Files - System Mapping
• [Link] Property Group Configuration Files -
Property Groups
• [Link] Property Group Configuration Files - Default
Values
Note: Installation, Remote System Connections, and Eclipse Preferences configuration files are stored
only on the primary system.
<containerPath>
Specifies the location of the configuration file on the z/OS system. The default container path for each
configuration file is either the folder that contains the key mapping file or a subfolder. Subfolders are
used to reduce the number of files in the parent folder and to group similar sets of files, such as
Eclipse preference files.
<fileMask>
Specifies the name of the configuration file. Some export operations, such as Eclipse Preferences
and RSE Connections, generate multiple files. For these operations, the value for the file mask uses
wildcard characters such as *.xml and *.zip.
<encoding>
Specifies the character encoding of the configuration file.

Sample key mapping file

The following sample key mapping file points to configuration files stored in the /var/zexpl/
pushtoclient path of the z/OS system.

<?xml version="1.0" encoding="UTF-8"?>

<configuration-system>
<location-list>

Managing the development environment for a team 37

 <location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/install</containerPath>
<fileMask>[Link]</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/install/responsefiles</containerPath>
<fileMask>*.xml</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/preferences</containerPath>
<fileMask>*.pref</fileMask>
<encoding>IBM-1047</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/connections</containerPath>
<fileMask>*.zip</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/projects</containerPath>
<fileMask></fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/mappings</containerPath>
<fileMask>[Link]</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/mappings</containerPath>
<fileMask>zoshlq_*.xml</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/mappings</containerPath>
<fileMask>*.bct</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/properties</containerPath>
<fileMask>[Link]</fileMask>
<encoding>UTF-8</encoding>
</location>
<location>
<fileId>[Link]</fileId>
<containerPath>/var/zexpl/pushtoclient/properties</containerPath>
<fileMask>[Link]</fileMask>
<encoding>UTF-8</encoding>
</location>
</location-list>
</configuration-system>

Related information
IBM Developer for z/OS Host Configuration Guide (SC23-7658)

38 Developer for z/OS: Managing and Extending the Eclipse Environment

Extending product functions

Creating menu actions in Menu Manager

Menu Manager is a tool for adding new menu commands to pop-up menus for projects, subprojects,
data sets, files, and JES jobs. The commands can range in complexity from simple local executable files
to complex commands that prompt for user input and run multiple commands and scripts on a remote
system.

What you can do

By using Menu Manager, you can customize pop-up menus in the following ways:
• Create actions that are added to the pop-up menus for these views and resources:
– Remote Systems and Remote System Details views: data sets, partitioned data set members, JES
jobs and job spool files, and z/OS UNIX System Services files
– Remote z/OS Search view: All files listed in the view
– MVS subprojects in the z/OS Projects view: Remote data sets and data set members, and local files
– COBOL, JCL, PL/I, or z Systems LPEX Editors: A local or remote file that is open in the editor
– z/OS Projects: A z/OS UNIX subproject in the view

• Integrate z/OS resources such as TSO/E commands, CLISTs, REXX execs, and ISPF edit macros into the
IBM Developer for z/OS client user interface.

© Copyright IBM Corp. 1992, 2024 39

 • Redefine existing actions to override or supplement their function: when a user requests the original
action, the redefined action is called instead.
• Create actions that prompt users for input.
• Use substitution variables in command strings.
• Create menus and submenus, and reorganize items within a menu, to group functions.

How it works
A Menu Manager action sends a command from your workstation to the ISPF Gateway on z/OS, which
then executes the command and returns the command output to your workstation. Commands can be
constructed to run on any remote system to which you are connected.

40 Developer for z/OS: Managing and Extending the Eclipse Environment

Opening Menu Manager
To access the Menu Manager tools, open the workbench Preferences window, and expand Menu
Manager. The tools consist of three pages of preferences:
• Menu Manager: Use this page to set tool-wide options.
• Actions and Menus: Use this page to create, organize, and deploy actions.
• Menu Selection: Use this page to set default menu locations for the various folder and file types that
you can create menu actions for.

Extending product functions 41

 Terminology
These terms are used to describe the Menu Manager functions and results:
action
The menu item that you select from a menu, such as Cut, Copy, and Paste in this illustration.

command
The function that an action performs, such as running a build or executing a TSO command with
specific parameters.
command processor
The product-supplied engine that processes a command that is defined for an action, such as
the [Link] class that processes Dependency

42 Developer for z/OS: Managing and Extending the Eclipse Environment

 Based Build user builds, or the [Link] class that processes
TSO commands.
context
The specific resource and location that a menu action is associated with, such as an MVS file in the
Remote Systems view, or a JES job in the Remote System Details view.
menu
A pop-up menu. In Menu Manager, all actions that you create are added to pop-up menus.
menu action
Another term for action.
menu file
An .xml file that stores menu and menu action definitions. The product provides several menu files
that you can add to, or you can create your own menu files.
pop-up menu
The menu that opens at the location of the cursor when you right-click a mouse button or keyboard
touchpad button.
target resource
The object that an action acts on. These types of resources can be targets for Menu Manager actions:
• Files, including local files and remote data sets and data set members
• Projects and subprojects, which are specialized folders
• JES jobs and job data sets, which are specialized types of folders and files

Creating menu actions

Menu Manager provides two wizards that guide you through the process of creating a menu action. This
topic explains the types of actions you can create with each wizard. The remaining topics in this section
explain how to run these wizards to create actions that process a file.
Limitation: The New Complex Action Wizard is currently not supported. The documentation does not
include help or examples for complex actions.

Opening the Menu Manager wizards

Table 3. Menu Manager New Action Wizards
Wizard title How to start it Use it for these actions Links to instructions
and examples
New Action Wizard On the Actions tab • Dependency Based • “Running a DBB user
of the Menu Manager Build user build build” on page 53
> Actions and Menus
• TSO/E commands, • “Running a TSO
preference page, click
CLISTs, or REXX execs command, REXX exec,
New Local/Remote
• ISPF edit macro or CLIST command
Action.
sequence” on page
• z/OS UNIX System 54
Services commands
• “Adding variables to
• Run or modify core an action” on page
file actions, such as 57
copy/paste, open, or
compare • “Creating user-input
variables for TSO
• Run a script or a commands” on page
user exit on a remote 60
system
• Submitting JCL with
dynamic variable
substitution

Extending product functions 43

 Table 3. Menu Manager New Action Wizards (continued)
Wizard title How to start it Use it for these actions Links to instructions
and examples
New Complex Action On the Actions tab • A remote multisystem This wizard is not
Wizard of the Menu Manager script currently supported and
> Actions and Menus no instructions or
• An interactive action
preference page, click examples are provided.
composed of multiple
New Complex Remote
remote actions that
Action.
interact with each
other based on
defined conditions

Example: Creating an action for a data set

This procedure creates a menu action that issues a TSO LISTDS command for a data set from any of the
available contexts. It describes the minimal steps for using the Menu Manager New Action Wizard to
create an action for a data [Link] describes variations on the minimum or default options in note boxes
labeled "Variations." For descriptions of all of the fields and options on the Menu Manager New Action
Wizard, see the context-sensitive helps. For more examples of Menu Manager actions, see “Examples
and tutorials” on page 65.
1. In the Preferences window, expand Menu Manager and click Actions and Menus.
2. On the Actions tab, click New to create a file for the action, and then choose Data set as the resource
type and Browse to select a file location.
Variations: If you already have a file for storing data set actions, you can select it from the File
Selection list or click Import or Find to locate an action storage file. Files can contain actions for only
one resource type. You cannot mix actions for files, data sets, and projects in the same file. To learn
more about storing actions in files, see “Creating files to store menus and actions” on page 96.
3. Click New Local/Remote Action. The Menu Manager New Action Wizard opens.
4. In the Name field, type the action name as you want it to appear on the pop-up menu. For this
example, type LISTDS.
5. Click Next.
6. If you want to restrict the action to certain data set name patterns, type a filter in the Data set filter
field and click Add. If you want the action to apply to any data set name, leave this page blank.
7. Click Next. The Run Options page opens.
8. In the Command text entry field of the Run Options page, type or copy and paste this command. In
this command, $name is a substitution variable that obtains the fully qualified name of the selected
resource. Because the variable is enclosed in single quotes, it is processed by the LISTDS command
as-is, without being prefixed with a high-level qualifier.

listds ('$name') members

Variations: To see a list of all available substitution variables and their definitions, click Variables. To
learn more about substitution variables, see “Adding variables to an action” on page 57.
9. In the Action Properties group box:
a. Choose Use existing action, and then do these steps:
i) Click Select.
ii) In the Action Selection window, expand [Link] and select
[Link].
Variations: The [Link] action is a Java™ class that
processes TSO commands. To learn more about the other command processors that are

44 Developer for z/OS: Managing and Extending the Eclipse Environment

 available with Menu Manager, see “Constructing the command for a menu action” on page
47.
iii) Click OK.
b. Choose Show on generic menu.
Variations: This option places the action on the main pop-up menu of the view you are working
in. You can also add actions to new or existing Menu Manager menus and associate them with
resources and views:
• To learn more about creating other menus and adding actions to them, see “Creating a menu for
an action” on page 88.
• To learn more about associating menus and actions with resources and views, see “Associating
menus with resources and views” on page 100
10. Click Finish. The new action is added to the Actions list of the Actions and Menus page. If it is a
[GENERIC] action, you can test it right away. Otherwise, you can add it to a new or existing menu and
then test it. For more information about adding actions to menus, see “Creating a menu for an action”
on page 88.
11. Click Apply and Close.

Testing the action

1. In the Remote Systems view, connect to a z/OS system and expand MVS Files > My Data Sets.
2. Select a partitioned data set.
3. Right-click a data set member and click LISTDS. The TSO command runs and output similar to the
following is added to the Remote Console view:

----------------------------------------
> listds ('[Link]') members
[Link]
--RECFM-LRECL-BLKSIZE-DSORG
FB 80 32720
PO
--VOLUMES--
V3S936
--MEMBERS--
CKPA303
DANISH
DANISHL
DB2008A
DCLEND

Modifying an action
You can use the Menu Manager Actions and Menus preference page to edit, duplicate, or move an
existing action.
You can edit the following types of actions:
• Simple local
• Simple remote
• Complex remote
You can edit an existing simple local, simple remote, or complex remote action by doing one of the
following tasks:
• Modifying the properties of the action
• Creating a copy of the action
• Moving the action to a different file
To modify an action, complete the following steps:
1. In the Actions and Menus preference page, click the Actions tab.

Extending product functions 45

 2. In the Actions tab, right-click the action that you want to edit to open the pop-up menu.
3. Select the action that you want to use to edit the selected simple local, simple remote, or complex
remote action.
For example, to modify the properties of the selected action, select Edit from the pop-up menu.

Editing an action
You can use the Menu Manager Actions and Menus preference page to edit actions.
You can use this procedure to edit any type of Menu Manager action.
To edit an action, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Actions tab, do one of the following steps:
• Double-click the action that you want to edit.
• Right-click the action that you want to edit and select Edit.
The Properties window opens and shows the information that you specified when you created the
action.
4. Use the following properties pages to modify information for the selected action:
• File Associations - Modify the file types that are associated with the selected action.
Note: This properties page is available only for file actions.
• General - Modify the name of the selected action or the description that is displayed as tooltip text
when you hover over this action in the pop-up menu.
• Override Info - Override actions that are contained in Menu Manager protected files that you do not
have permissions to change. For example, you can override actions that are contained in read-only
protected files. In the Choose Actions to be overriden by current action section, select the actions
that you want to override with the current action.
Note: This properties page is not available for complex remote actions.
• Run Options - Modify the options that apply when the selected action is run.
5. To close the window without saving your changes, click Cancel. To close the window and save your
changes, click OK.
The action is updated to reflect your changes.

Creating a copy of an action

You can create a copy of an existing action by using the Menu Manager.
To modify an existing action that is provided by IBM or your administrator, create a copy of the action and
apply your changes to the copy. You can specify that you want the copy to override the original action by
editing the copied version of the action.
To create a copy of an action, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Actions tab, right-click the action that you want to copy.
4. Select Create New Copy
The Copy Action wizard opens.
5. In the New Name field, type the name that you want to display for the copy of the action.

46 Developer for z/OS: Managing and Extending the Eclipse Environment

 6. In the Storage Options section, do one of the following steps:
a) To store the copy of the action in an existing action file:
• Click Choose from Available Files.
• From the list, select the existing action file in which you want to store the copy of the action.
Tip: Do not modify any of the action files that are supplied by IBM. Instead, save the copy of the
action in your own action file.
b) To create an action file in which to store the copy of the action:
• Click Create a New File.
• In the Location field, type the location where you want to create the action file or to browse for
the location, click Browse.
7. Optional: To open the file that contains the copy of the action after the copy is created, select Open
the selected file.
8. Optional: To override the existing action with the copy that is being created, select Override original
action.
9. Click Finish.
The copy of the action is added to the Actions tab of the Actions and Menus preference page.

Constructing the command for a menu action

Use the Run Options page of the Menu Manager New Action wizard to create the command that a menu
action runs.

Components of a command
You construct a menu action command from two main components:
• A command string, including parameters, substitution variables, or input prompts. A command string
can be a local executable file; a remote command, such as a TSO/E command or a REXX exec, that is
transmitted to a z/OS system and runs on that system, or a user-written program that operates on local
or remote resources.
• Action properties that control how the command is processed, where its output or results are displayed,
and where any files that the command uses are located.
You define the command string and properties for a menu action on the Run Options page of the Menu
Manager New Action Wizard.

Shipped command processors

Menu Manager provides a set of Java classes that implement the IAction class to handle the processing
of commands that you can define as menu actions. These actions are available when you select Use
existing action and then click Select from the Run Options page of the Menu Manager New Action
wizard or action properties page.

Extending product functions 47

 The following command processors are available on the Run Options page of the Menu Manager New
Action Wizard. These command processors provide the engine that runs the commands you enter into
the Command field of the Run Options page.
[Link]
Submits JCL for execution with substitution variables. For more information about submitting JCL with
substitution variables, see Submitting JCL with dynamic variable substitution.
[Link]
Runs a Dependency Based Build user build script. For more information about creating a Menu
Manager action to run a DBB user build, see “Running a DBB user build” on page 53.
[Link]
Runs any command that you can issue from the TSO command area, such as a TSO/E command, a
REXX exec, or a CLIST command procedure. For more information about creating a Menu Manager
action to run a TSO command, see “Running a TSO command, REXX exec, or CLIST command
sequence” on page 54
[Link]
[Link]
[Link]
The remaining topics in this section explain how to use these actions. For more examples of using these
actions, see “Examples and tutorials” on page 65. You can also create your own implementations of the
IAction class and add them to the Action Selection window. This process is explained in “Writing a
command that implements the Java IAction” on page 62.

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

48 Developer for z/OS: Managing and Extending the Eclipse Environment

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:
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 [Link](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 *
//* *

Extending product functions 49

 //*************************************************************
//* *
//* 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=[Link],DISP=SHR
// DD DSN=[Link],DISP=SHR
//DFHCSD DD DSN=[Link],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.
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\[Link]. 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.

50 Developer for z/OS: Managing and Extending the Eclipse Environment

 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,[Link](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,[Link](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
variable is substituted with an uppercase value. The other two variables are substituted with
mixed-case values.

Submit,[Link](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 [Link].
18. Select [Link] 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:

Extending product functions 51

 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

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

52 Developer for z/OS: Managing and Extending the Eclipse Environment

3. To submit the JCL with the variable substitutions, click Submit.
A job submission window opens.

Running a DBB user build

You can start IBM Dependency Based Build (DBB) scripts in IBM Developer for z/OS. The DBB scripts are
executed in the z/OS UNIX System Services environment. You can also create Menu Manager actions to
run commands in z/OS UNIX System Services environments.
The following procedure illustrates how to create an action for this command to start a DBB user build
script.
sh -c "$DBB_HOME/bin/groovyz /u/user1/dbbsandbox/Samples/build/[Link]
--sourceDir /u/user1/dbbsandbox --workDir /u/user1/dbbsandbox/work --hlq
[Link] --userBuild Samples/COBOL_Sample/[Link] --dbbLog /u/user1/
dbbsandbox/work"

Extending product functions 53

 Note:
• In this command, the --dbbLog parameter is specific to the DBB action. It is used to indicate where to
locate the DBB log output after the DBB script execution is completed. In this example, it is the location
of the work folder. When this parameter is specified, the DBB action shows the same results from the
DBB action that are shown when starting a DBB user build from IBM Developer for z/OS outside of Menu
Manager.
• When creating the Menu Manager DBB action, the Show output in dialog option must be selected if the
log output window is to be shown. When selected, the DBB console output is also shown in a separate
window. If that option is not selected, when the command is executed, the DBB log output is not shown.
Instead, the DBB console output is shown in the Remote Console view.
Follow these steps to create a simple Menu Manager DBB action.
1. On the Preferences page, expand Menu Manager and select Actions and Menus.
2. On the Actions and Menus Preferences page, click New Local/Remote Action.
3. On the New Action Page, specify the name of the action, for example, DBB Demo Action. This name
is used as the context menu label that is shown when the action is requested.
4. On the File Association page, select the file type to associate with the action, and click Add. Click
Next.
5. Optional: On the Data Set Filters page, specify any data set filter. Click Next.
6. On the Run Options page, fill in the following information.
a. In the command text area, specify the DBB command.
sh -c "$DBB_HOME/bin/groovyz /u/user1/dbbsandbox/Samples/build/
[Link] --sourceDir /u/user1/dbbsandbox --workDir /u/user1/
dbbsandbox/work --hlq [Link] --userBuild Samples/COBOL_Sample/
[Link] --dbbLog /u/user1/dbbsandbox/work"
b. In the Action Properties section, select Show on generic menu.
c. Select Use existing action, and click Select. Variables are also available for use in a command. If
you want to see the available variables, click Variables.
d. On the Action Selection page, select [Link] and click
OK.
e. Select the Show output in dialog checkbox.
f. On the Run Options page, click Finish.
7. On the Actions and Menus page, click OK to save what you have configured.

Testing the action

To use the Menu Manager DBB action you created, in the Remote Systems view, right-click a file under
z/OS UNIX Files and select the DBB action with the name you specified when creating it.
The output window opens with the running results.
Related information
“Adding variables, user input, and other variations to a DBB user build ” on page 67

Running a TSO command, REXX exec, or CLIST command sequence

To integrate the functions provided by TSO commands into the user experience for Developer for z/OS,
you can create menu actions by using the Menu Manager New Action Wizard.

Before you start

Using Menu Manager to run TSO commands has several requirements and limitations:

54 Developer for z/OS: Managing and Extending the Eclipse Environment

• The TSO command must be available and APF-authorized. For mu information about configuring the
product, see the Developer for z/OS Host Configuration Guide. If you use Menu Manager to submit a
REXX exec or CLIST, then the action the script is requesting must also be authorized.
• A REXX exec, JCL, or CLIST that you want to run by using a Menu Manager action must be located in the
data set that you specify in the command string.
• REXX execs or C Lists must not use the ISPF dialog manager or ISPF screens.
• Conversational or multistep actions that run REXX execs and CLISTS are one-trip only: they collect user
input and pass them into the REXX EXEC or CLIST, which can respond iteratively, but only by using read
and write syntax to pipe text back and forth.

Procedure
To create an action that runs a TSO command, REXX exec, or CLIST:
1. In the left pane of the Preferences window, expand Menu Manager and select Actions and Menus.
2. Select, create, or import a file to create the action in.
3. On the Actions tab, click New Local/Remote Action. The Menu Manager New Action Wizard opens.
4. In the Name field of the New Action Page, type the name that you want to be displayed for the action
in the pop-up menu.
5. In the Context drop-down list, select the context in which this action is visible.
For example, if you choose z/OS UNIX Subprojects, this action shows up only on z/OS UNIX System
Services files. If you choose MVS files in z/OS Projects, this action shows up only for data sets in a
z/OS project. The default is All.
Note: Depending on the context that is chosen, properties that are available on subsequent panels of
the new action wizard might be different.
6. On the File Associations page, select the file types to associate with the action.
7. On the Data Set Filters page, to add a data-set filter, type a filter pattern, such as INPT*, in the Data
set filter field, and click Add.
8. On the Basic tab of the Run Options page, type a TSO command string, a REXX EXEC command
string, or a CLIST command string in the Command field.
Tip: For sample commands, see the links listed in “Examples” on page 55.
If the remote system uses Interactive ISPF Gateway, then you must begin the command string with
TSO and enter it in upper case.
Use a TSO command shell or the Remote Connection Emulator to test a command before adding it to
a Menu Manager action. For more information about these tools, see:
• Issuing TSO commands
• Remote Connection Emulator
9. Select Use existing action, and then click Select and, in the Action Selection window, expand
[Link] and select [Link].
Variations: The [Link] action is a Java class that processes
TSO commands. To learn more about the other command processors that are available with Menu
Manager, see “Constructing the command for a menu action” on page 47.
10. Select Show on generic menu.
Note: If you do not select Show on generic menu, you must add the action to a menu and attach that
menu to one or more resources.
11. Click Finish.

Examples
For examples of TSO commands for a Menu Manager action, see these topics:

Extending product functions 55

 • “Example: Creating an action for a data set” on page 44 illustrates a TSO LISTDS command that returns
allocation and volume data and a member list for a selected data set.
• “Starting a REXX exec or CLIST” on page 65
Related reference
List of TSO/E Commands

Running an edit macro

Use the [Link] action to create a menu command
that runs an ISPF edit micro on an MVS file or data set member.

Before you start

1. Open the Menu Manager New Action Wizard as described in “Creating menu actions” on page 43.
2. Complete the wizard pages until you reach the Run Options page. The following instructions begin on
the Run Options page.

Creating an edit macro command

To create a menu command that runs an ISPF edit macro:
1. On the Basic tab of the Run Options page, enter a command string that follows this format in the
Command field.

EDIT,$[Link]($name), [Link](EDTMACRO), [Link] MACROMBR

The command and parameters are described in this list:

EDIT
Indicates whether to open the data set member in the editor if it is not already open when the
action is selected from the menu.
$[Link]($name)
Represents the name of a temporary data set that contains the results of the processing of the
input data set or data set member by the edit macro. The $userid substitution variable supplies
the logon ID of the remote connection as a high-level qualifier. The $name variable supplies the
name of the selected data set or data set member that is the input to the command.
[Link](EDTMACRO)
Represents the name of the edit macro REXX or CLIST program that is to be started to process the
input data set or data set member.
[Link] MACROMBR
Represents the parameter that is to be passed to the edit macro REXX or CLIST program. Typically,
it is the data set and member for the ISPF edit macro.
If the menu action starts REXX, use this format for the command string instead:

EXEC '[Link](EDTMACRO)' '[Link] SELCTMBR [Link]

STAGEMBR [Link] MACROMBR'

2. In the Action Properties group box, select Use existing action and then click Select and choose
[Link] > [Link] from the Action
Selection window.
3. Choose any additional action properties that you want, complete the remaining pages of the wizard,
and click Finish.

56 Developer for z/OS: Managing and Extending the Eclipse Environment

Adding variables to an action
Menu Manager provides z/OS variables that you can use to gather information from users or from the
objects your actions operate on.
The Menu Manager z/OS variables are available when you create an action that operates on a data set,
data set member, or file.
To see available z/OS variables, complete the following steps:
1. Create or open a local or remote action.
For more information, see “Creating a local action for a file” on page 68 or “Example: Creating an
action for a data set” on page 44.
2. Open the Run Options page of the wizard.

3. Click Variables.
The Substitution Variables window opens. This window can have two formats:

Extending product functions 57

 • If the action was created for a specific context, then the window contains a list of variables you can
use in that context.
• If the action was created for all contexts, by specifying Context: All in the New Action Page, then
the window contains a list of contexts. For a complete list of z/OS contexts, see the related links.
4. Choose a context from the list to see the available variables.
The list of variables is specific to each context. The list also includes variable descriptions. For some
examples of using substitution variables with Menu Manager actions, see the related links.

Related concepts
“z/OS contexts in Menu Manager” on page 101
Menu Manager provides predefined z/OS contexts to which you can add the actions or menus you create
by using it.
Related tasks
“Creating user-input variables for TSO commands” on page 60
You can add user-input variables and text to a custom action that runs a TSO command. A user-input
variable prompts users to specify or select a parameter value for a TSO command after selecting a custom
action from the menu.
Related information
Submitting JCL with dynamic variable substitution

58 Developer for z/OS: Managing and Extending the Eclipse Environment

Learn how to use Menu Manager and the JCL substitution mechanism to submit JCL with dynamic variable
substitution.

z/OS substitution variables in the Menu Manager

z/OS substitution variables depend on the context that is chosen from the Context list on the
Substitution Variables window.
The Table 4 on page 59 table shows the list of defined substitution variables that can be used for
constructing a command.

Table 4. z/OS substitution variables

Variable Description
$clientaddress The address of the client that is contacting the remote system
$datasetname The name of the data set that contains the selected resource
$ddname The JES job data set DD name of the selected resource
$dsname The JES job data set DS name of the selected resource
$fullname The fully qualified name of the selected resource in the form
DATASETNAME(MEMBERNAME)
$input Input from the user for an interactive action (syntax: $input(prompt_string,
default_value, $List{A,B,C})). The List parameter is optional.
$inputfile The name of the selected file. It can be a z/OS UNIX file, an MVS dataset member,
a local file, or a workspace file.
$inputfileandf The full path name of the selected file or folder. The file or folder can be in z/OS
older UNIX, MVS, a local system, or a workspace.
$inputfilefull The name and the full path of the selected file. It can be a z/OS UNIX file, an MVS
name dataset member, a local file, or a workspace file.
$inputfolder The full path of the selected directory. It can be a z/OS UNIX directory, an MVS
dataset, a local folder, or a workspace folder.
$jobid The JES job ID of the selected resource
$jobname The JES job name of the selected resource
$jobowner The JES job owner of the selected resource
$list Used with $input to list the options that are available for interactive actions
$name The name of the selected resource
$procstepname The JES job data set proc step name of the selected resource
$openfileafter Opens the selected file in the default editor after the action.
$projectname The name of the project that is associated with the selected resource
$refreshselect Refreshes the selected view after the action.
ionafter
$stepname The JES job data set step name of the selected resource
$systemhostnam The host name or IP address of the system that contains the selected resource
e
$userid The ID of the user that is connected to the system associated with the selected
resource

Extending product functions 59

 Related tasks
“Adding variables to an action” on page 57
Menu Manager provides z/OS variables that you can use to gather information from users or from the
objects your actions operate on.
“Creating user-input variables for TSO commands” on page 60
You can add user-input variables and text to a custom action that runs a TSO command. A user-input
variable prompts users to specify or select a parameter value for a TSO command after selecting a custom
action from the menu.

Creating user-input variables for TSO commands

You can add user-input variables and text to a custom action that runs a TSO command. A user-input
variable prompts users to specify or select a parameter value for a TSO command after selecting a custom
action from the menu.
To enable users to specify input to TSO commands, you must create a custom action.
To add user-input variables to a TSO command:
1. From the Menu Manager New Action wizard, click Variables.
The Substitution Variables window opens. This window contains three options that you can use to
create a user-input variable for a TSO command:
$input
Collects input from the user who performs the custom action. When you add this variable to a
custom action, the action prompts the user with a window for specifying input or for selecting input
from a list.
$list
Provides the option of including a list of values from which the user can select one.
$text
Specifies a text string, such as instructions, that you can include on the window prompt before or
after the input or list field. This field is positional. If you include it before a $input or $list option, it
appears above the input or list field on the window prompt. If you include it after the $input or $list
option, it appears below the input or list field.
2. Select $input from the Substitution Variables window and click Insert.
3. To include a list of possible values from which the user can select one, select $list from the
Substitution Variables window and click Insert.
This variable is optional and is used to construct a list of possible values for the action input.
4. To use this variable in a custom action, specify it as follows:

$text(InstructionString), $input(PromptString, DefaultValue,

$list{string1,string2,string3, . . .,stringn})

InstructionString
Specify a string of text or instructions for the user.
PromptString
Specify the window label that prompts the user for input. The prompt string can contain spaces but
no commas (,) or dollar signs ($). The prompt string is required.
DefaultValue
Specify the value to be used as the default if the user does not enter a value when prompted.
The default value can contain spaces but no commas (,) or dollars signs($). The default value is
required.
string1,string2,string3, . . .,stringn
Specify a list of strings from which the user can select a value. This variable is optional. If you
include it, the window prompts the user to select one of these strings from a list. If you omit it, the
window prompts the user to type a value. Each value in the list can contain spaces but no commas
(,) or dollar signs ($).

60 Developer for z/OS: Managing and Extending the Eclipse Environment

The following examples show the prompts that open when you create menu items with user-input
variables. The examples illustrate a window with a field and a window with a list.
The following example creates a window with a list labeled Parameter from which a user can select either
SMSINFO or DIRECTORY. The default value is SMSINFO.

FEKFLDSI '$datasetname' $text(Choose one parameter from the list.),

$input(Parameter,SMSINFO,$list{SMSINFO,DIRECTORY})

The following example creates a window with a field labeled Parameter, into which a user can enter data.
The default value for the field is SMSINFO.

FEKFLDSI '$datasetname, $text(Type one parameter into the text entry field.),
$input(Parameter,SMSINFO)'

The following example creates a window with a list labeled Data Set Name, from which a user can select
either the data set name [Link] or the name of the currently selected data set. The default is
the name of the currently selected data set.

FEKFLDSI '$text(Select a data set.), $input(Data Set Name, $datasetname,

$list{[Link],$datasetname})'

Extending product functions 61

 Related tasks
“Adding variables to an action” on page 57
Menu Manager provides z/OS variables that you can use to gather information from users or from the
objects your actions operate on.
Adding user variables and variable values for JCL substitution
Related information
Submitting JCL with dynamic variable substitution

Writing a command that implements the Java IAction

The Menu Manager provides the [Link] extension point so that you
can contribute your own Java actions to the Menu Manager. These actions must be action objects (Java
classes) that implement the [Link] interface.
You can use this extension point to enable the Menu Manager to recognize Java actions, such as
action classes that implement the [Link] interface. By creating a
Java action, you can run more complex operations. For example, you can write a Java action that searches
or manipulates the selected file.
After you create the Java actions, you can contribute them through this extension point so they can be
added to menus by using the Menu Manager. You can contribute actions to the Menu Manager by adding
action elements.
Each action element consists of ID, class, and separateThread attributes. The ID is a unique identifier for
the action and the class is a Java class that implements the [Link]
interface. The separateThread attribute determines whether the action that is contributed runs on a
separate thread when it is started from the pop-up menu.
Note: Actions that run on a thread other than the main thread must make special calls (such as the
syncExec method in [Link]) to use any of the functions in the GUI.
When you create an action to contribute to the extension point, you can implement more interfaces
for extra function. For example, you might want to create an action that is notified when the selection
changes, with the following interfaces:
• [Link] - notifies your action when the
selection changes so that you can enable and disable your action according to the selection in the
view.
Tip: If your action extends [Link], it
automatically implements IAction and ISelectionChangedListener.
• [Link] - ensures that your
action always has a reference to the current ViewPart when it is run. This interface allows your action
to get a reference to the shell and display windows by using the ViewPart shell as the parent.

62 Developer for z/OS: Managing and Extending the Eclipse Environment

 Note: When actions are started from the pop-up menu, the Menu Manager runs these actions by using
the runWithEvent method. The event that is passed to the actions contains the selection, unless
the actions must be enabled and disabled based on the selection. You do not need to implement
ISelectionListener.
• [Link] - displays your action in the Progress Monitor
view. You can cancel a long running job in the Progress view; if your action is canceled, you can clean up
if necessary.
The following is an example of some actions that are contributed to the Menu Manager by using the
extension point.

The following example shows the properties of the action element:

The following example shows the XML source code for the rename action:

<extension
id="[Link].f"
name="%[Link]"
point="[Link]">
<action
separateThread="false"
class="[Link]"
id="[Link]">
</action>
</extension>

Creating an action element

You can inform the Menu Manager that actions exist by adding action elements for each action in the
[Link] extension point, and then referencing these actions in the Menu
Manager.
Each action element must consist of an ID and a class.
To create an action element, complete the following steps:
1. Create a plug-in project. For information about creating a plug-in project, see the related topics.
2. In the plug-in project, right-click the [Link] file and select Open With > Plug-in Manifest
Editor.
The file opens in the manifest editor.
3. In the Plug-in Manifest Editor, click the Dependencies tab and complete the following steps:
a) In the Required Plug-ins section, click Add.
The Plug-in Selection window opens.
b) In the Select a Plug-in field, type [Link], and then click OK.

Extending product functions 63

 4. In the Plug-in Manifest Editor, click the Extensions tab and complete the following steps:
a) Click Add.
The New Extension wizard opens.
b) Click the Extension Points tab.
c) From the list of available extension points, select [Link], and then
click Finish.
5. In the Extensions tab, right-click the [Link] extension point and
select New > action from the pop-up menu.
An action element is added as a child of the [Link] extension
point.
6. Select the action element.
The Extension Element Details section displays the following information for the action element:
• id - this value is displayed in the Use existing action list when you create an action in the Menu
Manager. This ID must be unique. It cannot be the same as the ID of any other actions that are
contributed from this plug-in or a different plug-in.
• class - the name of a class that implements [Link]. The class
also specifies cosmetic properties for the action, such as icons.
Note: The run method of the specified class provides the code that is run when the action is
selected from a pop-up menu.
• separateThread - specify whether you want to run this action on a separate thread of execution.
By default, it is set to false. To run the action on a separate thread of execution, set the value to
true.
7. In the Extension Element Details section, do one of the following to select a Java class for the action
element:
• To use an existing Java class, click Browse to open the Select Type window. In the Select entries
field, type the name of the Java class that you want to use. From the list of Matching types, select
the Java class, and then click OK.
• To generate a Java class for the action element, click class to open the New Java Class wizard.
In the Source folder field, type the name of the folder in which you want to store the Java class
or click Browse to browse for the location of the folder. In the Package field, type the name of the
package in which you want to store the Java class or click Browse to browse for the package. In
the Name field, type the name of the Java class, and then click Finish.
Note: You must select a Java class that implements the [Link]
interface. The Java class can extend the [Link] class instead
which provides defaults for several of the methods in the IAction interface.
8. In the id field, type a unique identifier for this action.
9. From the separateThread list, select true to run this action on a separate thread of execution.
By default, this value is set to false.
Note: Calls to the GUI can be run only from the main thread. If you are running in a separate thread,
you must wrap all GUI calls in an [Link] call.
10. In the Extensions tab, right-click to open the pop-up menu and select Save.
The action element is created.
Related information
New Project Creation Wizards
Plug-in Extensions

64 Developer for z/OS: Managing and Extending the Eclipse Environment

Referring to an action element
After you contribute an action element, you can reference it in the Menu Manager.
You can write a Java action class that completes a series of complicated steps when you rename a file.
After you contribute this action object to the Menu Manager by using the extension point, you can create a
custom action that is called My Complicated Rename that references this IAction class. When you run
this custom action, it starts your action object.
When you create an action that references an action contributed by using the
[Link] extension point, you can specify that you want to use an
existing action:
1. In the Action Properties section of the Run Options page, select Use existing action.
2. To open the Action Selection window, click Select.
3. From the list of actions, select the unique ID of the contributed action, and then click OK.
For example, [Link].
The selected action is displayed in the ID field.
When this action is selected from a pop-up menu, the referenced action is run by calling its
runWithEvent method. By using this method, you can add actions with GUI elements (such as wizards)
to the Menu Manager apart from simple command-based actions. It also allows these actions to use all of
the features of the Menu Manager, such as the overriding mechanism, user exits, and the events file.

Examples and tutorials

Find sample commands and code that you can use to learn about Menu Manager and as a starting point
for your own commands.

Before you start

The examples in this section include commands that you can copy into the Menu Manager New Action
Wizard Command field and sample code that you can copy into a partitioned data set member. The
partitioned data set (PDS) name that is used in the examples is $[Link], where
$userid is the logon user ID and high-level qualifier of the PDS. To allocate a PDS for the sample code, see
the instructions in Allocating data sets.

Starting a REXX exec or CLIST

Use the Run Options page of the Menu Manager New Action Wizard to construct a menu action
command that starts a REXX exec or CLIST.
1. The partitioned data set (PDS) name that is used in the examples is $[Link],
where $userid is the logon user ID and high-level qualifier of the PDS. To allocate a PDS for the sample
code, see the instructions in Allocating data sets.
2. Follow the instructions in “Running a TSO command, REXX exec, or CLIST command sequence” on
page 54 to open the Menu Manager New Action Wizard, select or create a file for storing the action,
and set the context for the action.
3. On the Run Options page of the wizard, choose these options:
• Use existing action > ID: [Link]: Every TSO command, REXX
exec, or CLIST uses this action ID to process the command.
• Show output in dialog: Since many REXX execs and CLISTS include WRITE or SAY statements for
messages, choose this property to display command output.

Extending product functions 65

 The following examples illustrate sample command strings, run options, and output for starting REXX
execs or CLISTs.

Example 1: A REXX exec with no parameters

This command string runs the HELLO REXX exec, which displays a "Hello World" message in an output
window. It substitutes the current logon ID for the $userid variable.

EX '$[Link](HELLO)'

To try this command string, do these steps:

1. Create a PDS member named <HLQ>.[Link]([Link]).
2. Copy this code into the PDS member.

/* REXX Hello Exec */

SAY "Hello World"
SAY "Take care now, y'all!"
exit

3. Copy the command string into the Run Options page of the new action wizard with these action
properties.

66 Developer for z/OS: Managing and Extending the Eclipse Environment

4. Right-click the context that you defined for the menu action and select it from the menu. The REXX
exec displays this output.

Adding variables, user input, and other variations to a DBB user build
The example in “Running a DBB user build” on page 53 specifies a hardcoded value for the program
that is to be built. This topic expands on the sample DBB user build menu command by incorporating
substitution variables, additional build scripts, and user input prompts.

Specifying variables and running additional scripts in the DBB action

This is not practical since the same DBB script can be used for building other programs. At times, it may
be desirable to run some commands prior to the execution of the DBB script.
The DBB command script from the previous example needs to be modified to specify the selected
program instead of a hardcoded value.
To modify the DBB action, on the Menu Manager preferences page, double-click the DBB action you
created to open its properties.
1. Select Run Options on the left pane.
2. Select the hardcoded program name in the command box and click Variables.
3. From the context list, select z/OS Unix Files in Remote Systems view.
4. In the variables table, select $fullname and click Insert. Then, click Close.
Now the $fullname variable is used for the program name. Other variables such as $userid can also be
used in the command.
When starting the action, the selected program is used when starting the build.

Prompting the user for input and displaying the command output in a window
Using the same script, you can prompt the user for some of the information. For example, the user may
want to be able to specify the location of the work folder instead of having a hardcoded value for the
location. In this case, the variable $inputfolder can be used to specify that the user is to be prompted
for the location. The variable $userid can be used to specify that the user ID of the current logged on
user needs to be placed there.
The updated command now looks like this:
sh -c "$DBB_HOME/bin/groovyz /u/$userid/dbbsandbox/Samples/build/[Link]
--sourceDir /u/$userid/dbbsandbox --workDir $inputfolder(Work directory,/u/
$userid/dbbsandbox/work), --hlq $[Link] --userBuild $fullname --
dbbLog /u/$userid/dbbsandbox/work"
Additional commands may be specified that are to be executed ahead of the DBB script. For this example,
the following two commands are to be issued before the script is run.

Extending product functions 67

 echo The following is the DBB User Build script. The location of $DBB_HOME is also displayed
echo $DBB_HOME

When executed, the user is now prompted for the location of the work folder.
Once all input is collected from the end user, the Menu Manager action is executed.

(Optional) Changing the save location of Menu Manager actions

By default, the Menu Manager actions are saved at the location specified by the %TPFSHARE%
environment variable, which points to <Installation-directory>\Config\TPFSHARE, where
<Installation-directory> is the location where the current IBM Developer for z/OS is installed.
To change the location where the Menu Manager actions are to be saved, click New and then on the New
File page, specify a different file location for saving the actions. Click Finish to save the setting.
Related information
Opening the Preferences window
“Running a DBB user build” on page 53
You can start IBM Dependency Based Build (DBB) scripts in IBM Developer for z/OS. The DBB scripts are
executed in the z/OS UNIX System Services environment. You can also create Menu Manager actions to
run commands in z/OS UNIX System Services environments.

Creating a local action for a file

This procedure creates a menu action that issues a TSO LISTC command in any of the available contexts.
It describes the minimal steps for using the Menu Manager New Action Wizard to create a local action
for a [Link] describes variations on the minimum or default options in note boxes labeled "Variations."
For descriptions of all of the fields and options on the Menu Manager New Action Wizard, see the
context-sensitive helps.
1. In the Preferences window, expand Menu Manager and click Actions and Menus.
2. On the Actions tab, click New to create a file for the action, and then choose File as the resource type
and Browse to select a file location.
Variations: If you already have a file for storing file actions, you can select it from the File Selection
list or click Import or Find to locate an action storage file. Files can contain actions for only one
resource type. You cannot mix actions for files, data sets, and projects in the same file. To learn more
about storing actions in files, see “Creating files to store menus and actions” on page 96.
3. Click New Local/Remote Action. The Menu Manager New Action Wizard opens.
4. In the Name field, type the action name as you want it to appear on the pop-up menu. For this
example, type LISTC Level.
5. Click Next.
6. On the File Associations page, select one or more file types to associate with the action and click
Add, or, to select all available file types, click Add All.
Variations: If a file type you want to associate with an action is not in the list, click File Types on the
File Associations page to add it.
7. Click Next.
8. If you want to restrict the action to certain data set name patterns, type a filter in the Data set filter
field and click Add. If you want the action to apply to any data set name, leave this page blank.
9. Click Next.
10. In the Command text entry field of the Run Options page, type or copy and paste this command.
In this command, $userid is a substitution variable that obtains the user ID of the current z/OS
connection.

listc level ($userid

68 Developer for z/OS: Managing and Extending the Eclipse Environment

 Variations: To see a list of all available substitution variables and their definitions, click Variables. To
learn more about substitution variables, see “Adding variables to an action” on page 57.
11. In the Action Properties group box:
a. Choose Use existing action, and then do these steps:
i) Click Select.
ii) In the Action Selection window, expand [Link] and select
[Link].
Variations: The [Link] action is a Java class that
processes TSO commands. To learn more about the other command processors that are
available with Menu Manager, see “Constructing the command for a menu action” on page
47.
iii) Click OK.
b. Choose Show on generic menu.
Variations: This option places the action on the main pop-up menu of the view you are working
in. You can also add actions to new or existing Menu Manager menus and associate them with
resources and views:
• To learn more about creating other menus and adding actions to them, see “Creating a menu for
an action” on page 88.
• To learn more about associating menus and actions with resources and views, see “Associating
menus with resources and views” on page 100
12. Click Finish. The new action is added to the Actions list of the Actions and Menus page. If it is a
[GENERIC] action, you can test it right away. Otherwise, you can add it to a new or existing menu and
then test it. For more information about adding actions to menus, see “Creating a menu for an action”
on page 88.
13. Click Apply and Close.

Testing the action

1. In the Remote Systems view, connect to a z/OS system and expand MVS Files > My Data Sets.
2. Expand a partitioned data set.
3. Right-click a data set member and click LISTC Level. The TSO command runs and output similar to the
following is added to the Remote Console view:

----------------------------------------
> listc level (useribm)
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932
NONVSAM ------- [Link]
IN-CAT --- CATALOG.V3S932

Extending product functions 69

 Creating an MVS TSO menu action for a local file
Complete the steps in this tutorial to create a menu action for a file in a local z/OS project.
This tutorial uses the sample files in the Dependency Based Build GitHub repository to show how you can
use Menu Manager to process mainframe files that are stored in a GitHub repository clone and imported
into a local z/OS project. If you are not familiar with the Dependency Based Build samples, you can review
the information in Integrating IBM Dependency Based Build and Developer for z/OS.
This tutorial guides you through the process of creating a menu action for a file in a local z/OS project. It
teaches you how to:
1. Connect to the Dependency Based Build example repository on GitHub.
2. Import the sample files into a z/OS project.
3. Create a Menu Manager action that executes an MVS TSO command.

Connect to the Dependency Based Build repository

Verify that the Git Integration for Eclipse is installed:
1. Select Help > About IBM Developer for z/OS.
2. On the About window, click Installation Details.
3. Expand the entry for IBM Developer for z/OS and look for Git Integration for Eclipse.
Tip: You can also type the name or a portion of it into the filter text box and press Enter.
If the feature is not installed, follow the instructions in EGit Download.
This tutorial uses sample files from the IBM Dependency Based Build repository on GitHub at https://
[Link]/IBM/dbb. The following procedure explains how to clone this repository from Developer for
z/OS.
1. Click this link to navigate to the IBM Dependency Based Build repository on GitHub: https://
[Link]/IBM/dbb.
2. Sign in to GitHub and then, in the GitHub web interface, click Fork to fork a copy of the repository to
your account.

3. From your forked copy, click the Code menu and then click Use SSH.
If you do not have a public SSH key, GitHub prompts you to create one. Click the link in the prompt and
follow the instructions.

4. Copy the URI.

70 Developer for z/OS: Managing and Extending the Eclipse Environment

5. In the Developer for z/OS Git Repositories view, click Clone a Git repository.
6. In the URI field of the Clone Git Repository window, paste the copied URI and type the passphrase for
your public SSH key into the Password field.

7. Click Next.
If prompted to accept and store the key, click Accept.
8. Select the branches you want to clone and then click Next.

Extending product functions 71

 9. Choose a location for the clone and click Finish.

The sample files are added to the Git Repositories view.

72 Developer for z/OS: Managing and Extending the Eclipse Environment

Import sample files into a z/OS project
The Dependency Based Build repository contains source files for several applications. This procedure
imports the source files for the MortgageApplication into a local z/OS project.
1. In the Git Repositories view, expand the Working Tree node of the dbb repository.
2. Expand the Build folder.
3. Right-click MortgageApplication and click Create a z/OS project.
The MortgageApplication folder is imported into the z/OS Projects view.

Create a Menu Manager action

This procedure creates a Menu Manager action that executes the following TSO command against a
selected folder in the local z/OS project:

LISTDS '$datasetname' $input(LISTDS $datasetname,,$list{LABEL,HISTORY,MEMBERS})

Extending product functions 73

 1. From the Developer for z/OS menu bar, select Window > Preferences, and then expand Menu
Manager and select Actions and Menus.
2. From the File Selection area, choose a location for the new menu action.
If you do not have a file for storing menu actions, you can create one by following the instructions in
“Creating files to store menus and actions” on page 96.
3. Click New Local/Remote Action.
4. In the New Action Wizard, enter the following values in these fields. For all other fields, accept
default values.
Field Value
Name Local Project MVS Command
Chosen File Types Add All
Command LISTDS '$datasetname' $input(LISTDS
$datasetname,,$list{LABEL,HISTORY,ME
MBERS})
Use existing action Select and choose the
[Link] action
Add to generic menu Select
5. To close the wizard, click Finish.
6. To save the new menu action, click Apply and Close.
7. In the z/OS Projects view, expand the MortgageApplication project and the cobol folder.
8. Select a file, right-click, and select Local Project MVS Command.
Menu Manager prompts you to associate the local file with a remote resource.

9. Click Browse.
The Browse for File window opens.

74 Developer for z/OS: Managing and Extending the Eclipse Environment

 This window lists remote resources in remote system connections and in remote z/OS projects. If you
find that the remote connections take a long time to expand, then you can add the data sets you need
to a remote z/OS project. Because z/OS projects usually contain a small subset of the resources in a
remote connection, you can navigate them more quickly.
10. In the Browse for File window, choose a remote resource to associate with the local file and then
click OK.
The Local Project MVS Command runs and prompts for a data set information selection.

11. Select an item from the list and click OK.

The command output displays in the Remote Console.

Summary
In this tutorial, you learned the following:
• How to clone to a GitHub repository.

Extending product functions 75

 • How to import files from a GitHub clone to a local z/OS project.
• How to create a Menu Manager action that operates on a file in a local z/OS project.

Creating a Menu Manager action and menu on JES jobs

You can create a Menu Manager action and menu on JES jobs that are listed in the Remote Systems view.
1. In Preferences window, complete the following steps:
a) Double-click Menu Manager, and click Actions and Menus.
b) In the Actions and Menus pane, specify the path name of an XML file.
For example, specify C:\local_files\rdz\jes_actions.xml.
2. In the Actions and Menus pane, click the Actions tab, and click New Local/Remote Action.
3. In the New Action Page page of the Menu Manager New Action Wizard window, do these steps:
a) Type a name for the action that you are creating.
b) Optional: Type a comment.
c) Select the JES Jobs in Remote Systems view or the JES Jobs in Remote Systems Details view
context.
d) Click Next.
4. In the Actions and Menus pane, click the Menus tab and click New Menu.
5. In the New Menu wizard, create a custom menu by doing the steps that are described in “Creating a
custom data set menu” on page 91.
Go to “Attaching a menu to JES jobs by using Menu Manager” on page 103.
Related tasks
“Attaching a menu to JES jobs by using Menu Manager” on page 103
You can attach a base menu to all JES jobs. You can also attach a default menu to all JES jobs that do not
have a menu that is assigned to them.
“Creating a custom menu” on page 90
You can use the Menu Manager Actions and Menus preference page to create custom menus for projects,
subprojects, data sets, and files.
“Adding variables to an action” on page 57
Menu Manager provides z/OS variables that you can use to gather information from users or from the
objects your actions operate on.
Related information
Preferences

Creating a Menu Manager action and menu on JES job data sets
You can create a Menu Manager action and menu on JES job data sets that are listed in the Remote
Systems view.
1. In Preferences window, do these steps:
a) Double-click Menu Manager, and click Actions and Menus.
b) In the Actions and Menus pane, specify the path name of an XML file.
For example, specify C:\local_files\rdz\jes_actions.xml.
2. In the Actions and Menus pane, click the Actions tab, and click New Local/Remote Action.
3. In the New Action Page page of the Menu Manager New Action Wizard window, do these steps:
a) Type a name for the action that you are creating.
b) Optional: Type a comment.
c) Select the JES Job Data Sets in Remote Systems view or the JES Job Data Sets in Remote
Systems Details view context.
d) Click Next.
4. In the Actions and Menus pane, click the Menus tab and click New Menu.

76 Developer for z/OS: Managing and Extending the Eclipse Environment

5. In the New Menu wizard, create a custom menu by doing the steps that are described in “Creating a
custom data set menu” on page 91.
Go to “Attaching a menu to JES job data sets” on page 104.
Related tasks
“Attaching a menu to JES job data sets” on page 104
You can attach a base menu to all JES job data sets. You can also attach a default menu to all JES job data
sets that do not have a menu that is assigned to them.
“Creating a custom data set menu” on page 91
You can use the Menu Manager to create a custom data set menu.
“Adding variables to an action” on page 57
Menu Manager provides z/OS variables that you can use to gather information from users or from the
objects your actions operate on.
Related information
Preferences

Creating a member and refreshing a view

Use the $refreshselectionafter variable to refresh the selected resource after an action.
In this example procedure, the <HLQ>.CLIST(UPDATEDS) file represents a CLIST program that can do
these tasks:
• Create a member in a selected data set.
• Update an existing data set member with additional data.
The <HLQ>.[Link] data set represents a partitioned data set for COBOL source files.
1. To create a file to contain data set actions, click New on the Actions tab of the Actions and Menus
page of the Menu Manager preferences, select the Data set resource type option, and specify a file
name and location.

Extending product functions 77

 2. Click Next, and then select Create a new local/remote action and click Finish.

3. On the New Action Page, type a name for the action, such as Create Member and Refresh View,
and then select a context for the action.

78 Developer for z/OS: Managing and Extending the Eclipse Environment

 The $refreshselectionafter variable is available in the following contexts:
• MVS Files in Remote Systems view
• MVS File in Remote z/OS Search view
• MVS Files in z/OS Projects
4. Click Next, and on the Data Set Filters window, click Next again.
5. In the Command field of the Run Options window, type a command to execute the CLIST program
with the $refreshselectionafter variable.
This example executes the CLIST program for the selected data set and prompts the user for a
member name:

ex '<HLQ>.CLIST(UPDATEDS)' '$datasetname($input(Name,MEMBER1))' $refreshselectionafter

6. Select the Show on generic menu action property and click Finish.

Extending product functions 79

 7. On the Preferences window, click OK to save the action.
8. To test the sample action that was created in this procedure, in the Remote Systems view, select the
<HLQ>.[Link] data set and right-click.
The pop-up menu contains the new action:

80 Developer for z/OS: Managing and Extending the Eclipse Environment

9. When you select the action, a window prompts you for a member name. Type a member name and
click OK.

Extending product functions 81

 The new member is added and the Remote Systems view is refreshed:

Updating a member and opening it in an editor

Use the $openfileafter variable to open a file after an action.
In this example procedure, the <HLQ>.CLIST(UPDATEDS) file represents a CLIST program that can do
these tasks:
• Create a member in a selected data set.
• Update an existing data set member with additional data.
The <HLQ>.[Link] data set represents a partitioned data set for COBOL source files.
1. To create a file to contain file actions, click New on the Actions tab of the Actions and Menus page
of the Menu Manager preferences, select the File resource type option, and specify a file name and
location.

82 Developer for z/OS: Managing and Extending the Eclipse Environment

2. Click Next, and then select Create a new local/remote action and click Finish.

3. On the New Action Page, type a name for the action, such as Update Member and Open, and then
select a context for the action.

Extending product functions 83

 The $openfileafter variable is available in the following contexts:
• MVS Files in Remote Systems view
• MVS File in Remote z/OS Search view
• MVS Files in z/OS Projects
4. Click Next, and on the File Associations window, select *.* and click Add.

5. Click Next, and on the Data Set Filters window, click Next again.
6. In the Command field of the Run Options window, type a command to execute the CLIST program
with the $openfileafter variable.

84 Developer for z/OS: Managing and Extending the Eclipse Environment

 This example executes the CLIST program for the selected data set member:

ex '<HLQ>.CLIST(UPDATEDS)' '$fullname * testing add data' $openfileafter

7. Select the Show on generic menu action property and click Finish.

8. On the Preferences window, click OK to save the action.

9. To test the sample action that was created in this procedure, in the Remote Systems view, select a
member in the <HLQ>.[Link] data set and right-click.
The pop-up menu contains the new action:

Extending product functions 85

 10. When you select the action, the command adds data to the member and opens it in the default editor.

86 Developer for z/OS: Managing and Extending the Eclipse Environment

Defining a HATS rich client Application Command Action detail
If you want to define an action that starts a specific HATS rich client application, the format of the
command is determined by whether your HATS rich client application is designed to support single
sign-on or not.
• Complete one of the following steps:
• If your application does not support automated sign-on, the format of the command is just the URL of
the HATS application. For example: HATSRCP=appname where appname is the name of the HATS rich
client application. Or, if the application has parameters, the command might be similar to the following
example: HATSPCP=appname hatsgv_userid hatsgv_password
• If your application does support automated sign-on, specify the name of the variables for the user
ID and password that are to be added to the HATS command. For HATS, the global variables
are specified in the following format on the HATS command: HATSPCP=appname hatsgv_userid
hatsgv_password
In addition to the user ID and password parameters, you can also specify additional parameters to be
passed to HATS. In this example, the HATS Web application is invoked and the user ID and password
are passed. Additionally, three other parameters (hatsgv_var1, hatsgv_var2, and hatsgv_var3)
are passed, along with their corresponding values. More than three parameters can be passed.

HATSRCP=HCmvs211Parms hatsgv_userid hatsgv_password hatsgv_var1=value1 hatsgv_var2=value2

hatsgv_var3=value3

• If your application does support automated signon, Developer for z/OS substitutes your user ID and
password, if you specify the name of the variables for the user ID and password that are to be added to
the HATS command.
For HATS, the global variables are specified in the following format on the HATS command:

[Link] hatsgv_userid hatsgv_password

There must be a space between the HATSRCP=appname and hatsgv_userid and between hatsgv_userid
and hatsgv_password. The name of the global variables for user ID and password are not important
(except that HATS does require the hatsgv_ prefix to know that a specified parameter is a global
variable). What is important is that hastgv_userid is interpreted as the user ID and hatsgv_password will
be interpreted as the password.
In addition to the user ID and password parameters, you can also specify additional parameters to be
passed to HATS. In this example, the HATS web application is started and the user ID and password are
passed. Additionally, three other parameters (hatsgv_var1, hatsgv_var2, and hatsgv_var3) are
passed, along with their corresponding values. More than three parameters can be passed.

[Link] hatsgv_userid hatsgv_password var1=value1 var2=value2

var3=value3

The following URL results from this example:

[Link]
tabs1=structures&hatsgv_userid=userid&hatsgv_password=password&var1=value1&var2=value2&var3=va
lue3

For the web interface, the URL specified in the command can be with or without parameters in the URL
itself. Host Connection Emulator correctly detects the presence or absence of parameters and adjusts
accordingly. For example, without any parameters the following URL is generated:

[Link] hatsgv_userid hatsgv_password var1=value1 var2=value2 var3=value3

With parameters, the following URL is generated:

[Link] hatsgv_userid hatsgv_password var1=value1

var2=value2 var3=value3

Extending product functions 87

 Passing host variables to a TSO command
You can use the $hostvariable substitution variable in conjunction with the $input and $list
variables to pass a host variable as input to a TSO command.
By using the $hostvariable substitution variable in conjunction with the $input and $list variables,
you can construct a menu item that prompts the user to choose from a list of host variables, and passes
the selected value to a TSO command.
To add user-input variables to a TSO command:
1. From the Menu Manager New Action wizard, click Variables.
The Substitution Variables window opens. This window contains three options that you can use to
create a user-input variable for a TSO command:
$input
Collects input from the user who performs the custom action. When you add this variable to a
custom action, the action prompts the user with a window for specifying input or for selecting input
from a list.
$list
Provides the option of including a list of values from which the user can select one.
$text
Specifies a text string, such as instructions, that you can include on the window prompt before or
after the input or list field. This field is positional. If you include it before a $input or $list option, it
appears above the input or list field on the window prompt. If you include it after the $input or $list
option, it appears below the input or list field.
2. Select $list from the Substitution Variables window and click Insert.
3. To include a list of possible values from which the user can select one, select $list from the
Substitution Variables window and click Insert.
This is used to construct a list of possible values for the action input.
4. To use this variable in a custom action, specify it as follows:

$text(InstructionString), $input(PromptString,
$list{$hostvariable(string1,string2,string3, . . .,stringn})

InstructionString
Specify a string of text or instructions for the user.
PromptString
Specify the window label that prompts the user for input. The prompt string can contain spaces but
no commas (,) or dollar signs ($). The prompt string is required.
DefaultValue
Specify the value to be used as the default if the user does not enter a value when prompted.
The default value can contain spaces but no commas (,) or dollars signs($). The default value is
required.
string1,string2,string3, . . .,stringn
Specify a list of strings from which the user can select a value. This variable is optional. If you
include it, the window prompts the user to select one of these strings from a list. If you omit it, the
window prompts the user to type a value. Each value in the list can contain spaces but no commas
(,) or dollar signs ($).

Creating a menu for an action

A pop-up menu opens when you right-click a project, subproject, filter, folder, data set, or file. By using
the Menu Manager, you can select base, custom, and generic menus to add to the pop-up menus for
projects, subprojects, data sets, and files.
A pop-up menu is constructed from the following elements:
• Actions - can be local or remote.

88 Developer for z/OS: Managing and Extending the Eclipse Environment

• Separators - provide a visual line separation between different groups of actions.
• Cascaded submenus - cascade from their parent menus to show more actions when you select the
submenu.
The pop-up menu that opens when you right-click a project, subproject, or file is composed of base,
custom, and generic menus. In the following example, the green portions of the pop-up menu represent
actions that are contained in the base menu. The blue section represents actions that are contained in the
custom portion of the menu.

Base menus
A base menu contains general actions that apply either to all projects and subprojects or to all files. You
can use only two base menus - one for projects and subprojects and one for files. The base portion of
a project or subproject pop-up menu is identical for all projects and subprojects. The base portion of a
file pop-up menu is identical for all files. If a base menu is set, then the base menu always displays in a
pop-up menu, even when a project, subproject, or file has a custom menu.

Custom menus
A custom menu contains actions that apply to projects and subprojects or to files. The custom portion of a
pop-up menu can be different for each project, subproject, and file. You can use the Menu Selection
preference page to specify custom menus for projects, subprojects, and files. On the Preferences
window, navigate to Menu Manager > Menu Selection. You can specify the menu for the custom portion
of a pop-up menu by using one of the following methods:
• Default menu: You can specify one menu that is used by default for all files, and another menu that is
used by default for all projects and subprojects. All files use the same default menu and all projects and
subprojects use the same default menu. Default menus display in a pop-up menu only when a project,
subproject, or file does not have a custom menu that is assigned to it. If a project, subproject, or file
does not have a custom menu that is assigned to it, the default menu is used.
• Custom menu: You can assign a custom menu to individual projects, subprojects, and files. You can also
assign the same custom menu to all files within a specific project or subproject. This method is useful if
you use different projects or subprojects for different purposes and want to display different actions on
their pop-up menus.

Extending product functions 89

 Generic menus
When you create an action by using the Menu Manager, you can select the Show on generic menu option
to indicate that you want the action you are creating to be displayed on the generic menu. All of these
marked actions are combined automatically at run time when you right-click a resource to create the
generic menu.

Finding your Menu Manager actions and submenus

For a quick display of all your Menu Manager actions and submenus in a context menu, you can press
Ctrl+Alt+E (on Windows) or Command+Option+E (on macOS). You can change the key binding for this
combination in the Preferences menu.
Related information
Preferences

Creating a custom menu

You can use the Menu Manager Actions and Menus preference page to create custom menus for projects,
subprojects, data sets, and files.
Custom menus can contain the following resources:
• Local actions
• Remote actions
• Other menus
• Separators

Creating a custom menu for a project or subproject

You can use the Menu Manager to create a custom menu for a project or subproject.
To create a custom menu for a project or subproject, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Actions and Menus window, complete the following steps:
a) To select the file to create the menu in, do one of the following steps:
• From the File Selection list, select the file that you want to create the menu in.
• To create a file for the menu, click New.
• To import a file for the menu, click Import.
Remember: You can create the menu only in a file that contains action and menu definitions that
apply to projects and subprojects. The icon beside the File Selection list indicates whether the file
contains action and menu definitions that apply to projects and subprojects, to data sets, or to files.
b) In the Menus page of the Actions and Menus notebook, click New Menu
The New Menu wizard opens.
4. In the Name field, type the name of the menu that you want to add to the pop-up menu, and then click
Next
5. On the Add Actions page, select the checkbox for each action that you want to add to the menu, or, to
select all of the available action elements, click Select All.
Tip: If the list of actions does not contain the specific action that you want to add to the menu, click
New Simple Action to create a simple action, or click New Complex Action to create a complex
action. If you want to edit one of the actions in this list, select the action, and then click Edit.
6. To proceed to the Add Menus page, click Next.

90 Developer for z/OS: Managing and Extending the Eclipse Environment

7. Select the checkbox for each menu that you want to add to the existing menu, or, to select all of the
available menu elements, click Select All.
8. Click Finish.
The menu is added to the Menus tab of the Actions and Menus preference window.

Creating a custom file menu

You can use the Menu Manager to create a custom file menu.
To create a custom file menu, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Actions and Menus window, complete the following steps:
a) To select the file to create the menu in, do one of the following steps:
• From the File Selection list, select the file that you want to create the menu in.
• To create a file for the menu, click New.
• To import a file for the menu, click Import.
Remember: You can create a file menu only in a file that contains action and menu definitions that
apply to files. The icon beside the File Selection list indicates whether the file contains action and
menu definitions that apply to projects and subprojects, to data sets, or to files.
b) In the Menus page of the Actions and Menus notebook, click New Menu
The New Menu wizard opens.
4. In the Name field, type the name of the menu that you want to add to the pop-up menu, and then click
Next
5. On the Add Actions page, select the checkbox for each action that you want to add to the menu, or, to
select all of the available action elements, click Select All.
Tip: If the list of actions does not contain the specific action that you want to add to the menu, click
New Simple Action to create a simple action, or click New Complex Action to create a complex
action. If you want to edit one of the actions in this list, select the action, and then click Edit.
6. To proceed to the Add Menus page, click Next.
7. Select the checkbox for each menu that you want to add to the existing menu, or, to select all of the
available menu elements, click Select All.
8. Click Finish.
The menu is added to the Menus tab of the Actions and Menus preference window.

Creating a custom data set menu

You can use the Menu Manager to create a custom data set menu.
To create a custom data set menu, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Actions and Menus window, complete the following steps:
a) To select the file to create the menu in, do one of the following steps:
• From the File Selection list, select the file that you want to create the menu in.
• To create a file for the menu, click New.
• To import a file for the menu, click Import.

Extending product functions 91

 Remember: You can create a data-set menu only in a file that contains action and menu definitions
that apply to data sets. The icon beside the File Selection list indicates whether the file contains
action and menu definitions that apply to projects and subprojects, to data sets, or to files.
b) In the Menus page of the Actions and Menus notebook, click New Menu
The New Menu wizard opens.
4. In the Name field, type the name of the menu that you want to add to the pop-up menu, and then click
Next
5. On the Add Actions page, select the checkbox for each action that you want to add to the menu, or, to
select all of the available action elements, click Select All.
Tip: If the list of actions does not contain the specific action that you want to add to the menu, click
New Simple Action to create a simple action, or click New Complex Action to create a complex
action. If you want to edit one of the actions in this list, select the action, and then click Edit.
6. To proceed to the Add Menus page, click Next.
7. Select the checkbox for each menu that you want to add to the existing menu, or, to select all of the
available menu elements, click Select All.
8. Click Finish.
The menu is added to the Menus tab of the Actions and Menus preference window.
Related tasks
“Attaching menus to data sets” on page 102
You can attach a base menu to all data sets or you can attach a default menu to all data sets that do not
have a menu that is assigned to them.

Editing menus
You can use the Menu Manager to edit existing menus to meet your specific requirements.
Using the actions that are available in the Menu Manager, you can edit menus by:
• Adding submenus
• Adding separators
• Adding an action to a menu
• Adding a menu to a menu
• Duplicating and adding menus or actions
• Deleting menus or actions from menus
• Renaming menus
• Moving items within a menu
• Moving menus to different files
• Copying menus to different files
• Cutting and pasting actions or menus
To edit a menu, complete the following steps:
1. In the Actions and Menus preference page, click the Menus tab.
2. In the Menus tab, right-click the menu that you want to edit and then select the action that you want to
use to edit the selected menu.
For example, to add a submenu to the selected menu, select Add Submenu from the pop-up menu.
3. To change the position of the items in the menu, expand the menu and use the drag function that
is provided in the Menus tab. To move items, such as actions, menus, and separators, to a different
position in a menu or to another menu:
a) Select the item.
b) Drag it to the new location.

92 Developer for z/OS: Managing and Extending the Eclipse Environment

Adding an action to a menu
Only generic actions display on pop-up menus by default. You can add custom actions to pop-up menus
by using the Menu Manager.
To add an action to a menu, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Action tab, right-click the menu that you want to add an action to and select Add Actions from
the pop-up menu.
The Action Selection window opens, listing all of the available actions that you can add to the selected
menu.
4. Select the checkbox for each action that you want to add to the menu, or, to select all of the available
action elements, click Select All.
Tip: If the list of actions does not contain the specific action that you want to add to the menu, click
New Local/Remote Action to create a local or remote simple action, or click New Complex Remote
Action to create a remote complex action. If you want to edit one of the actions in this list, select the
action, and then click Edit.
5. To add the selected actions to the menu, click OK.
The selected actions display at the bottom of the menu in the Menus tab.
6. To save your selections and close the Preferences window, click OK.

Adding a menu to a menu

You can use the Menu Manager to add a menu to an existing menu.
When you add one menu to another menu, the actions from the menu are inserted into the parent
menu. You can add separators to the resulting menu to provide a visual separation (in the pop-up menu)
between actions that are contributed from different menus.
To add a menu to an existing menu, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, right-click the menu that you want to add a menu to and select Add Menus from the
pop-up menu.
The Menu Selection window opens, listing all of the available menus that you can add to the selected
menu.
4. Select the checkbox for each menu that you want to add to the existing menu, or, to select all of the
available menu elements, click Select All.
5. To add the selected menus to the existing menu, click OK.
The selected menus display within the existing menu in the Menus tab.
6. To preview the resulting menu, right-click the menu and select Preview. Right-click anywhere in the
Preview window to display the menu.
7. To save your selections and close the Preferences window, click OK.

Duplicating and adding an action

You can use the Menu Manager to duplicate an existing action and add it as a new action with a different
name.
To duplicate and add an action, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.

Extending product functions 93

 The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, expand the menu that contains the action you want to duplicate and add, right-click
the action, and then select Duplicate and Add.
The Duplicate Item window opens.
4. In the Choose a name for the duplicate item field, type the name that you want to display for the
copy of the action.
Note: You must specify a new name for the copy of the action; you cannot use the name of the original
action.
5. To create the copy and close the Duplicate Item window, click OK.
The copy of the action is displayed in the menu that contains the original action.
You can move this new action to another menu by dragging it to the menu that you want it to display in.

Duplicating and adding a menu

You can use the Menu Manager to duplicate an existing menu and add it as a new menu with a different
name.
To duplicate and add a menu, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, right-click the menu that you want to duplicate and add, and then select Duplicate
and Add from the pop-up menu.
The Duplicate Item window opens.
4. In the Choose a name for the duplicate item field, type the name that you want to display for the
copy of the menu.
Note: You must specify a new name for the copy of the menu; you cannot use the name of the original
menu.
5. To create the copy and close the Duplicate Item window, click OK.
The copy of the menu is created in the same file as the original menu and is added to the Menus tab.

Moving a menu
You can move an existing menu to a different XML file.
You can move a menu only to a file of the same type. For example, if the menu that you want to move is
in an XML file that contains file actions, you must move the menu to a different XML file that contains file
actions. You cannot move the menu to a file that contains actions for projects or subprojects.
To move a menu to another file, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, right-click the menu that you want to move to another file and select Move Menu to
Another File.
The Move Menu window opens.
4. In the Storage Options section, do one of the following steps:
• Click Choose from Available Files, and then select the file that you want to move the menu to from
the list.

94 Developer for z/OS: Managing and Extending the Eclipse Environment

 • Click Create a New File. In the Location field, type the path where the file is, or, to browse for
the location of the file that you want to move the menu to, click Browse. You can use environment
variables to specify the path where the file is. Ensure that you enclose environment variables with
the % sign. For example, %TPFSHARE%.
5. Optional: To view the file that you selected to copy the menu to, select Open the selected file.
6. To move the menu to the selected file and close the Move Menu window, click Finish.
The menu is removed from the original file, but the actions that are contained in the menu remain in this
file. The file that you moved the menu into is added to the File list in the Actions and Menus preference
page.

Copying a menu
You can use the Menu Manager to copy an existing menu to a different XML file.
If you want to modify a menu that is stored in a read-only file (or file that is provided by IBM and that you
do not want to modify), you can copy the menu to another file and make your changes in that file.
You can copy a menu only to a file of the same type. For example, if the menu that you want to copy is
in an XML file that contains file actions, you must copy this menu to a different XML file that contains file
actions. You cannot copy this menu to a file that contains actions for projects or subprojects.
To copy a menu to a different file, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, right-click the menu that you want to copy to another file and select Create New
Copy.
The Copy Menu window opens.
4. In the Storage Options section, do one of the following steps:
• Click Choose from Available Files and choose the file that you want to copy the menu to from the
list.
• Click Create a New File. In the Location field, type the path where the file is, or, to browse for the
location of the file that you want to copy the menu to, click Browse. The file cannot exist. You must
specify remote files with UNC paths. For example, \\HOSTNAME\FolderA\FolderB\[Link].
You can also use environment variables to specify the path where the file is. Ensure that you
enclose environment variables with the % sign. For example, %TPFSHARE%.
5. Optional: To view the file that you chose to copy the menu to, select Open the selected file.
6. To copy the menu to the selected file and close the Copy Menu window, click Finish.
The file that you copied the menu into is added to the File list in the Actions and Menus preference page.

Cutting and pasting actions or menus

You can use the Menu Manager to cut existing actions or submenus from a menu and paste them into
different menus.
To cut an action or submenu from a menu and paste it in to another menu, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, right-click the action or submenu that you want to cut and paste into another menu.
4. From the pop-up menu, select Cut.
5. Right-click the menu into which you want to paste the selected action or submenu.

Extending product functions 95

 Note: The type of paste action that is available depends on the location into which you are pasting the
selection.
6. From the pop-up menu, select one of the following available paste actions:
• Paste - pastes the selection into the new location. Attempting to paste the selected action or
submenu into an action or a separator pastes the item below the selected action or separator.
Pasting the selection into a menu or submenu pastes the selected item within the menu or
submenu.
• Paste At Top - pastes the selection as the first child of the top-level menu in which the selection is
located. This paste action is only available for top-level menus.
• Paste Below - pastes the selection below the selected submenu; it does not paste it within the
submenu. This paste action is only available for submenus.
The selected item is pasted into the new location.

Creating files to store menus and actions

You can create files in the Menu Manager to store action and menu definitions.
A file can contain actions and menus for only one type of resource. For example, a file that contains
actions that operate on files cannot also contain actions that operate on projects and subprojects. The
contents of a file (such as action and menu definitions) are displayed in the Actions and Menus tabs on
the Actions and Menus preference page in the Menu Manager.
To create a file in the Menu Manager, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. To open the New File wizard, click New.
4. In the Resource Type section, do one of the following actions:
• To create a file that contains action and menu definitions that apply to projects and subprojects,
select Project/Subproject.
• To create a file that contains action and menu definitions that apply to MVS data sets, select Data
set.
• To create a file that contains action and menu definitions that apply to files, select File.
Tip: In Menu Manager, use the resource type File for sequential data sets, partitioned data set
members, and JES files. Use the resource type Data set for partitioned data sets and VSAM files.
5. In the File field, type the path where you want to store the file or to browse for a location in which to
create the file, click Browse.
Note: You can create only XML files. If you do not specify a file name extension, .xml is appended to
the file name by default.
6. Do one of the following actions:
• To proceed to the Create file content page to create menus or actions that you want to include in
the file, click Next.
• To create the file in the Menu Manager and close the New File wizard, click Finish.
7. Optional: In the Create file content page, do one of the following actions:
• To create a menu to include in the file, click Create a new menu, and then click Finish. The New
Menu wizard opens.
• To create a simple local or remote action to include in the file, click Create a new local/remote
action, and then click Finish. The Menu Manager New Action wizard opens.

96 Developer for z/OS: Managing and Extending the Eclipse Environment

 • To create a complex action to include in the file, click Create a new complex action, and then click
Finish. The Menu Manager New Complex Action wizard opens.
Note: Create a new complex action is available only when you create a file that contains action
and menu definitions that apply to files.
• To specify that you do not want to create any content for the file now, click Create content later,
and then click Finish.
The file is added to the File list.

Moving an action
You can move an existing action definition to a different XML file.
To move an existing action to another file, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Actions tab, right-click the action that you want to move to another file and select Move Action
to Another File.
The Move Action wizard opens.
4. In the Storage Options section, do one of the following steps:
a) To move the action to an existing action file:
• Click Choose from Available Files.
• From the list, select the existing action file that you want to move the action to.
b) To create an action file in which to store the selected action:
• Click Create a New File.
• In the Location field, type the location where you want to create the action file or to browse for
the location, click Browse.
5. Optional: To open the file that contains the action after it is moved, select Open the selected file.
6. Click Finish.
The action is added to the Actions tab of the Actions and Menus preference page.

Importing a file into the Menu Manager

You can import files that are created by another user into the Menu Manager to use the actions and menus
that are defined in those files.
After you import a file into the Menu Manager, the Menu Manager recognizes this file. The action and
menu definitions that are contained in the imported file become available in the Menu Manager.
To import existing files into the Menu Manager, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. Click Import.
The Import File window opens.
4. In the File field, type the path of each file that you want to import, separated by commas. You can also
click Browse to browse for the location of the XML files that you want to import.
You can specify one or more file names. You must specify the location of remote files by using a drive
letter or UNC path, including the remote file name.

Extending product functions 97

 For example, \\HOSTNAME\FolderA\FolderB\[Link]. You can also use environment variables
to specify the path for imported. For example, %TPFSHARE%\[Link].
5. To import the selected files into the Menu Manager and close the Import File window, click Finish.
The import tries to determine the type of file from the contents of the file.
For example, a file that contains actions with filetype information must be a file action file. If this
information cannot be determined, a window opens to prompt you to specify the file type.
The file is added to the File list and the menus and actions that are defined in this file are loaded into the
Actions and Menus tabs.
You can start creating menus or actions from the definitions that are stored in this file.

Searching in the Menu Manager

You can search the Menu Manager Actions and Menus preference page to locate specific actions, menus,
or command strings.
For a quick display of all your Menu Manager actions and submenus in a context menu, you can press
Ctrl+Alt+E (on Windows) or Command+Option+E (on macOS). You can change the key binding for this
combination in the Preferences menu.
To search for an action or menu by name or for a specific command string, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. Click Find.
The Find view opens.
4. In the Enter a search string field, do any of the following steps:
• Type the name of the action that you want to find. For example, Rename.
• Type the name of the menu that you want to find. For example, Web Services Actions.
• Type the command string that you want to find. For example, notepad &DPN.
You can use wildcard characters in your search string. For example, Load* to find all entries that begin
with Load.

A list of search results is displayed. To clear the list of search results, click Clear ().
5. From the list of search results, select the result that you want to view, and then click Open.
If you select a menu, the contents of that menu are displayed in the Actions and Menus tabs. If you select
an action or command string, the Properties window opens, displaying the properties for the selected
item.

Files
Menu Manager provides DTD files to validate action and menu XML files and to validate the
[Link] file.

[Link] file
The Menu Manager uses the [Link] document type definition (DTD) file to validate
action and menu XML files and check for errors.
The structure of the [Link] is provided here for reference only; you cannot modify the
contents of this file. The [Link] file has the following structure:

<?xml version='1.0' encoding="UTF-8"?>

<!ELEMENT action
((filetype*| override*| datasetfilter*)* , command)

98 Developer for z/OS: Managing and Extending the Eclipse Environment

>
<!ATTLIST action
collectnames (true|false) #REQUIRED
foregroundrun (true|false) #IMPLIED
comment CDATA #REQUIRED
eventsfile CDATA #REQUIRED
id CDATA #REQUIRED
lengthlimit CDATA #REQUIRED
name CDATA #REQUIRED
remotecommand (true|false) #REQUIRED
showgeneric (true|false) #REQUIRED
clearconsole (true|false|pref) #IMPLIED
outputindialog (true|false) #IMPLIED
userexit CDATA #REQUIRED
iaction_id CDATA #REQUIRED
refresh CDATA #IMPLIED
propagate CDATA #IMPLIED
actionType CDATA #IMPLIED
>
<!ELEMENT datasetfilter
(#PCDATA)
>
<!ELEMENT filetype
(#PCDATA)
>
<!ELEMENT root
(complex-action*| action*| entity*)*>
<!ELEMENT command (headerfile?| footerfile?| commandheaderfile?| commandfooterfile?)*>
<!ATTLIST command
cmd CDATA #REQUIRED>
<!ELEMENT headerfile (headervars?)>
<!ATTLIST headerfile
value CDATA #REQUIRED>
<!ELEMENT footerfile (footervars?)>
<!ATTLIST footerfile
value CDATA #REQUIRED>
<!ELEMENT commandheaderfile (commandheadervars?)>
<!ATTLIST commandheaderfile
value CDATA #REQUIRED>
<!ELEMENT commandfooterfile (commandfootervars?)>
<!ATTLIST commandfooterfile
value CDATA #REQUIRED>
<!ELEMENT headervars (#PCDATA)>
<!ELEMENT footervars (#PCDATA)>
<!ELEMENT commandheadervars (#PCDATA)>
<!ELEMENT commandfootervars (#PCDATA)>
<!ELEMENT complex-action ((success| script+)|filetype+|datasetfilter*)+>
<!ATTLIST complex-action
type CDATA #REQUIRED
id CDATA #REQUIRED
name CDATA #REQUIRED
comment CDATA #REQUIRED
userexit CDATA #REQUIRED
showgeneric (true|false) #REQUIRED
clearconsole (true|false) #IMPLIED
actionType CDATA #IMPLIED
>
<!ELEMENT success (actionid, condition)>
<!ELEMENT failure (actionid, condition)>
<!ELEMENT script (actionid, host)>
<!ELEMENT actionid (#PCDATA)>
<!ELEMENT host (name, path, username, password?)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT path (#PCDATA)>
<!ELEMENT username (#PCDATA)>
<!ELEMENT password (#PCDATA)>
<!ELEMENT condition (constraint, (reference-val, success?, failure?)?)>
<!ELEMENT constraint (#PCDATA)>
<!ELEMENT reference-val (#PCDATA)>
<!ELEMENT entity (entity*)>
<!ATTLIST entity
id CDATA #REQUIRED
includedas CDATA #REQUIRED
location CDATA #REQUIRED
name CDATA #REQUIRED
type (complex-action | separator | menu | action | dynamicGroup) "separator" >
<!ELEMENT override EMPTY>
<!ATTLIST override
id CDATA #REQUIRED
name CDATA #IMPLIED
filename CDATA #IMPLIED>

Extending product functions 99

 [Link] file
The Menu Manager uses the [Link] document type definition (DTD) file to validate the
[Link] file and check for errors.
The structure of the [Link] is provided here for reference only; you cannot modify the contents of
this file.

<?xml version='1.0' encoding="UTF-8"?>

<!ELEMENT project
(#PCDATA)
>
<!ELEMENT file
(#PCDATA)
>
<!ELEMENT dataset
(#PCDATA)
>
<!ELEMENT root
(project| file | dataset)*
>

[Link] file
The [Link] file stores the location of menu and action files that are recognized by
the Menu Manager.

Purpose
The Menu Manager adds references for each menu and action file that you create to the
[Link] file. It also reads this configuration file for information about all existing
menus and actions. Each time that you create a file or import an existing file into the Menu Manager, it
updates the [Link] file with a reference to the newly created or imported file.
The [Link] file maintains a list of the files that are recognized by the Menu Manager;
you can edit only the files in the Menu Manager that are in this list. If you do not import a file into the
Menu Manager, you cannot edit it through the Actions and Menus preference page.
Each menu and action file in the [Link] file is marked to specify whether the actions
and menus within the file apply to file or subproject resources.

Sample
The following example shows the structure of a sample [Link] file:

?xml version='1.0' encoding="UTF-8"?>

<!DOCTYPE root (View Source for full doctype...)>
<root>
<project>c:\[Link]</project>
<file>c:\[Link]</file>
</root>

Note: If the file that is being referenced is in a remote location, a UNC path is used to reference that file.
The Menu Manager uses the [Link] file to validate the [Link] file and check
for errors.

Associating menus with resources and views

You can attach menus and actions to projects, subprojects, files, data sets, JES jobs, and JES job data
sets.
When you use this process to attach menus and actions to data sets, the data sets can include migrated
and offline data sets.
To attach menus to projects, subprojects, files, data sets, JES jobs, and JES job data sets, select the Show
on Generic menu checkbox when you create an action or edit an action.

100 Developer for z/OS: Managing and Extending the Eclipse Environment
If a project, subproject, data set, or file does not have a custom menu that is associated with it, the
generic menu is always displayed.
Related tasks
“Modifying an action” on page 45
You can use the Menu Manager Actions and Menus preference page to edit, duplicate, or move an
existing action.

z/OS contexts in Menu Manager

Menu Manager provides predefined z/OS contexts to which you can add the actions or menus you create
by using it.
When you create a menu or action by using Menu Manager, you assign it to a context. The context
determines where in the user interface the new menu or action is available for use. You can create menus
and actions for the following z/OS contexts:
• JES Job Data Sets in Remote Systems view
• JES Job Data Sets in Remote System Details view
• JES Jobs in Remote Systems view
• JES Jobs in Remote System Details view
• MVS Files in COBOL Editor (local and remote files)
• MVS Files in JCL Editor (local and remote files)
• MVS Files in PL/I Editor (local and remote files)
• MVS Files in Remote Systems view
• MVS Files in Remote System Details view
• MVS Files in Remote z/OS Search view
• MVS Files in z Systems LPEX Editor (local and remote files)
• MVS Files in z/OS Projects (local and remote files)
• z/OS UNIX Files in Remote Search view
• z/OS UNIX Files in Remote Systems view
• z/OS UNIX Files in Remote System Details view
• z/OS UNIX Subprojects
Related tasks
“Creating user-input variables for TSO commands” on page 60
You can add user-input variables and text to a custom action that runs a TSO command. A user-input
variable prompts users to specify or select a parameter value for a TSO command after selecting a custom
action from the menu.
Related information
Submitting JCL with dynamic variable substitution
“Creating an MVS TSO menu action for a local file” on page 70
Complete the steps in this tutorial to create a menu action for a file in a local z/OS project.

Attaching menus to projects and subprojects

You can attach a base menu to all projects and subprojects or you can attach a default menu to all
projects and subprojects that do not have a menu that is assigned to them.
To attach a menu to projects and subprojects, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Menu Selection.

Extending product functions 101

 The Menu Selection preference window opens.
3. From the Base Project/Subproject Menus list, select the menu that you want to attach as the base
menu to all projects and subprojects.
The list contains all of the menus for projects or subprojects that are available in the Menu Manager.
After you assign a base menu, this menu is displayed for all projects and subprojects. Actions on the
base menu display first in the pop-up menu, followed by actions from the default or custom menu.
4. From the Default Project/Subproject Menus list, select the menu that you want to attach as the
default menu for projects and subprojects.
The list contains all of the menus for projects and subprojects that are available in the Menu Manager.
Note: All projects and subprojects share a default menu. To override the default, assign a custom
menu to projects and subprojects on an individual basis through the Menu Selection properties page.
When a default menu is assigned to all projects and subprojects, the generic menu does not display in
the pop-up menu for projects and subprojects.
5. To save your selections and close the Preferences window, click OK.
The selected base and default menus are now attached to project and subproject pop-up menus.

Attaching menus to files

You can attach a base menu to all files or you can attach a default menu to all files that do not have a
menu that is assigned to them.
To attach a menu to a file, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Menu Selection.
The Menu Selection preference window opens.
3. From the Base File Menus list, select the menu that you want to attach as the base menu to all files.
The list contains all of the file menus that are available in the Menu Manager.
After you assign a base file menu, this menu is displayed for all files. Actions on the base file menu
display first in the pop-up menu, followed by actions from the default or custom menu.
4. From the Default File Menus list, select the menu that you want to attach as the default menu for files.
The list contains all of the file menus that are available in the Menu Manager.
Note: All files share a default file menu. To override the default, assign a custom menu to files on an
individual basis or to all files within a subproject. You can assign a custom menu through the Menu
Selection properties page.
When a default menu is assigned to all files, the generic menu does not display in the pop-up menu for
files.
5. To save your selections and close the Preferences window, click OK.
The selected base and default menus are now attached to file pop-up menus.

Attaching menus to data sets

You can attach a base menu to all data sets or you can attach a default menu to all data sets that do not
have a menu that is assigned to them.
When you use this process to attach menu and actions to data sets, the data sets can include migrated
and offline data sets.
To attach a menu to a data set, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Menu Selection.

102 Developer for z/OS: Managing and Extending the Eclipse Environment
 The Menu Selection preference window opens.
3. From the Base Data Set Menus list, select the menu that you want to attach as the base menu to all
data sets. The list contains all of the data set menus that are available in the Menu Manager.
After you assign a base data set menu, this menu is displayed for all data sets. Actions on the base
data set menu display first in the pop-up menu, followed by actions from the default or custom menu.
4. From the Default Data Set Menus list, select the menu that you want to attach as the default menu for
data sets. The list contains all of the data set menus that are available in the Menu Manager.
Note: All data sets share a default data set menu. To override the default, assign a custom menu to
data sets on an individual basis or to all data sets within a subproject. You can assign a custom menu
through the Menu Selection properties page.
When a default menu is assigned to all data sets, the generic menu does not display in the pop-up
menu for data sets.
5. To save your selections and close the Preferences window, click OK.
The selected base and default menus are now attached to data set pop-up menus.
Related tasks
“Creating a custom data set menu” on page 91
You can use the Menu Manager to create a custom data set menu.

Attaching a menu to JES jobs by using Menu Manager

You can attach a base menu to all JES jobs. You can also attach a default menu to all JES jobs that do not
have a menu that is assigned to them.
Before you can do this task, you must create a menu that contains actions.
JES jobs are listed in the Remote Systems view.
To attach a menu to JES jobs, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Menu Selection.
The Menu Selection preference window opens.
3. Select the JES Jobs in Remote Systems view context.
4. From the Base File Menus list, select the menu that you want to attach to all JES jobs as the base
menu.
The list contains all of the menus that are available in the Menu Manager.
After you assign a base file menu, this menu is displayed for all JES jobs. Actions on the base JES job
menu display first in the pop-up menu, followed by actions from the default or custom menu.
5. To save your selections and close the Preferences window, click OK.
The selected base and (optionally) default menus are now attached to pop-up menus for JES jobs.
In the Remote Systems view, select a JES job and check the menu to make sure that the expected Menu
Manager actions are available.
Related tasks
“Creating a Menu Manager action and menu on JES jobs” on page 76
You can create a Menu Manager action and menu on JES jobs that are listed in the Remote Systems view.
“Attaching a menu to JES job data sets” on page 104

Extending product functions 103

 You can attach a base menu to all JES job data sets. You can also attach a default menu to all JES job data
sets that do not have a menu that is assigned to them.

Attaching a menu to JES job data sets

You can attach a base menu to all JES job data sets. You can also attach a default menu to all JES job data
sets that do not have a menu that is assigned to them.
Before you can do this task, you must create a menu that contains actions.
JES jobs are listed in the Remote Systems view.
To attach a menu to a JES job data set, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Menu Selection.
The Menu Selection preference window opens.
3. Select the JES Job Data Sets in Remote Systems view context.
4. From the Base File Menus list, select the menu that you want to attach to all JES job data sets as the
base menu.
The list contains all of the menus that are available in the Menu Manager.
After you assign a base file menu, this menu is displayed for all JES job data sets. Actions on the base
JES job data set menu display first in the pop-up menu, followed by actions from the default or custom
menu.
5. To save your selections and close the Preferences window, click OK.
The selected base and (optionally) default menus are now attached to pop-up menus for JES job data
sets.
In the Remote Systems view, select a JES job data set and check the menu to make sure that the
expected Menu Manager actions are available.
Related tasks
“Creating a Menu Manager action and menu on JES job data sets” on page 76
You can create a Menu Manager action and menu on JES job data sets that are listed in the Remote
Systems view.
“Attaching a menu to JES jobs by using Menu Manager” on page 103
You can attach a base menu to all JES jobs. You can also attach a default menu to all JES jobs that do not
have a menu that is assigned to them.

Customizing the Actions and Menus preference page

Several aspects of the display and behavior of the Menu Manager Actions and Menus preference page
can be customized to suit your individual needs.
You can customize the Actions and Menus preference page to:
• Filter by menus.
• Filter actions by file type.
• Attach or detach label decorations from read-only, overridden, or unavailable actions and menus.
These customizations (excluding label decorations) apply only to the current session of the Menu
Manager, and are not saved when you close the preference page. Changes to label decorations are made
and saved at the workbench level; these changes persist when you close the workbench Preferences
window.

104 Developer for z/OS: Managing and Extending the Eclipse Environment
Filtering by menus
You can customize the Menus tab in the Actions and Menus preference page to filter the available menus
and display only specific menus that you want to view.
To filter by menus, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the Menus tab, click Filter Menus.
The Filter Selection window opens.
4. Select the menus that you want to display by doing one of the following steps:
• Select the checkbox for each menu that you want to display.
• Clear the checkbox for any menu that you do not want to display.
• To display all of the listed menus, click Select All.
• To display none of the listed menus, click Deselect All.
5. To save your selections and close the Filter Selection window, click OK.
Your selections are saved for the current session only; changes are not saved when you close the
Actions and Menus preference page.
The selected menus display in the Menus tab in the Actions and Menus preference page.

Filtering actions by file type

You can customize the Actions and Menus tabs in the Actions and Menus preference page to filter the
available actions by file type. You can filter actions by file type only for files that contain action and
menu definitions for files. You cannot use the Menu Manager to filter files that contain action and menu
definitions for projects and subprojects.
To filter actions by file type, complete the following steps:
1. Click Window (on Windows) or IBM Developer for z/OS (on macOS) > Preferences.
The Preferences window opens.
2. In the Preferences window, double-click Menu Manager, and select Actions and Menus.
The Actions and Menus preference window opens.
3. In the tab where you want to filter the actions by file type, click Filter by File Types
The Filter Selection window opens.
4. Select the file types that you want to display by doing one of the following steps:
• Select the checkbox for each file type that you want to display.
• Clear the checkbox for any file type that you do not want to display.
• To display all of the listed file types, click Select All.
• To display none of the listed file types, click Deselect All.
5. To save your selections and close the Filter Selection window, click OK.
Your selections are saved for the current session only; changes are not saved when you close the
Actions and Menus preference page.
Actions with the selected file types display in the Actions or Menus tab of the Actions and Menus
preference page.

Extending product functions 105

 Attaching and detaching label decorations
To show or hide label decorations in the Actions and Menus preference page, attach or detach label
decorations from read-only, overridden, or unavailable actions and menus. Changes to label decorations
are managed at the workbench level.
To attach or detach label decorations from actions and menus in the Menu Manager, complete the
following steps:
1. In the Preferences window, navigate to General > Appearance > Label Decorations.
2. In the Available label decorations section, do one of the following steps:
• To display the label decorations for read-only, overridden, or unavailable actions and menus, select
the Menu Manager check box.
• To hide the label decorations for read-only, overridden, or unavailable menus and actions, clear the
Menu Manager check box.
3. To save your changes and close the Preferences window, click Apply, and then OK.
Label decorations are displayed or not displayed for read-only, overridden, or unavailable menus and
actions in the Actions and Menus preference page.
Related information
Preferences

Common Access Repository Manager

Supporting other SCMs with CARMA
Many mainframe user organizations store their source code in proprietary software configuration
management systems, also known as software configuration managers (SCMs). The source code is locked
in the SCM, in a native format that Developer for z/OS cannot access in an integrated manner. The
Common Access Repository Manager (CARMA) toolkit for Developer for z/OS facilitates customer access
to SCMs from within Developer for z/OS by providing a common interface for accessing SCMs.

Overview
The following topics provide information about the Common Access Repository Manager (CARMA). They
describe the steps necessary for accessing, using, and extending the CARMA toolkit.
• “Accessing SCMs using CARMA” on page 107
• “Working with CARMA” on page 109
• “Extending the CARMA plug-in” on page 132

Getting started
The following topics provide instructions for completing some of the basic tasks you need to do to start
accessing SCMs using the CARMA toolkit.
• “Using CARMA views” on page 109
• “Connecting to a CARMA host” on page 115
• “Working with CARMA Resources” on page 119
• “Working with CARMA associated projects” on page 123

Samples and tutorials

The following sample RAMs allow you to access a PDS associated with TSO users or, to access Software
Configuration Library Manager (SCLM) assets that are stored in SCLM projects.
• “PDS RAM” on page 129
• “SCLM RAM” on page 129

106 Developer for z/OS: Managing and Extending the Eclipse Environment
Note: The sample RAMs are provided for testing the configuration of your CARMA environment. These
RAMs are NOT supported in a production-level environment.

Resources for learning available on the web

Many resources for learning and using the CARMA toolkit are available. Use the following links to learn
more about how to put CARMA to work:
• IBM Developer for z/OS Using SCLM DT Technology to Provide CARMA Services without Submitting
Batch Jobs
• Accessing SCMs using the WebSphere® Developer for zSeries CARMA plug-in
• Integrating Source Code Management Systems into WebSphere Developer for zSeries CARMA
• IBM Developer for z/OS product Web site
• IBM Developer for z/OS Information Roadmap

Accessing SCMs using CARMA

The Common Access Repository Manager (CARMA) toolkit for Developer for z/OS facilitates customer
access to SCMs from within Developer for z/OS by providing a common interface for accessing SCMs.

To leverage this common access framework, a CARMA client (such as Developer for z/OS, when
enhanced by the CARMA plug-in) must connect to a CARMA host, which manages SCM access using
repository access managers (RAMs). RAMs are host-resident modules that help the CARMA host system
communicate with individual SCMs. In order to access a given SCM through CARMA, the CARMA host
must first have the appropriate RAM installed on it. CARMA currently ships with four sample RAMs: the
PDS RAM, SCLM RAM, COBOL RAM, and skeleton RAM. Access to other SCMs through CARMA can be
achieved if the appropriate RAM is obtained or developed.
Note: The sample RAMs are provided for testing the configuration of your CARMA environment. These
RAMs are NOT supported in a production-level environment.
Related concepts
Accessing source files in the CA Endevor Software Change Manager (SCM)
Related information
“PDS RAM” on page 129
The PDS RAM allows you to access a PDS associated with TSO users by using ISPF services. In this case,
the TSO/ISPF services are the SCM and the repository is user's PDS.
“SCLM RAM” on page 129
The Software Configuration Library Manager (SCLM) RAM allows you to access and edit software assets
that are stored in SCLM projects. If the SCLM RAM is available on your CARMA host, then you can connect
to an SCLM project using the CARMA plug-in. For detailed information regarding SCLM operations, refer to
the Software Configuration Library Manager Reference.

CARMA host
A CARMA host is a host machine that runs a CARMA server.

CARMA hosts have a set of repository access managers, which define the types of repository connections
the host is capable of making.

Repository access manager

A repository access manager (RAM) provides connections to a specific type of SCM, such as SCLM.

Extending product functions 107

 Repository instance
A repository instance (RI) represents a project or component that exists in an SCM. The connection to
each repository instance is based on a RAM.

You can perform the following actions on repository instances:

• Extract a repository instance to a project
• Add a repository instance to project
Related tasks
“Extracting repository content” on page 124
Any content from CARMA can be extracted to a Developer for z/OS project to provide a copy of the content
that users can manipulate locally without updating host contents.
“Adding content to projects” on page 126
CARMA content can be added to an existing project to provide a copy of the content that users can
manipulate locally without having to update the host contents.

Repository content
Repository content represents members that are held by an SCM.

Content can be individual files or containers that contain other content. The nature of repository content
depends on the SCM it originates from and the RAM used to connect to the SCM. For example, in a PDS
RAM, the repository content can consist of individual PDS members. The nature of repository content
depends on the SCM and the RAM used to connect to the SCM.
You can perform the following actions on repository content:
• Refresh the content
• Lock the content to prevent access by other users
• Unlock the content to allow access by other users
• Check the content into the repository
• Check the content out of the repository
Related tasks
“Refreshing resources” on page 120
Users can refresh any item that is displayed in the CARMA Repositories view.
“Locking repository content” on page 121
The Lock action makes repository content read-only for all users except for the user who locked the
content.
“Unlocking repository content” on page 121
The Unlock action makes repository content editable for all users.
“Checking in repository content” on page 121
The Check In action updates content in the CARMA repository, marks the content as checked into the
repository, and allows other users to check out that content.
“Checking out repository content” on page 122
The Check Out action downloads content from the CARMA repository, marks the content as checked out
of the repository, and prevents other users from checking out that content.

Filters
CARMA filters represent a selected set of CARMA content or Repository Instances.

The filter is defined by a filter string, for example “A*”. The filter string is passed to the RAM, which passes
back a group of content. The content is determined by the RAM, but it is suggested that the filter contents

108 Developer for z/OS: Managing and Extending the Eclipse Environment
name match the filter string. For example, for the filter string “A*” it is suggested that the contents passed
back from the RAM all start with “A”.
There is a connection between the filter that is specified in the UI and the filter received by the RAM
functions. For additional information, refer to the Common Access Repository Manager Developer's Guide
(SC23-7660-00).
Additionally, CARMA developers can define the default filter to be used when a user expands a RAM,
Repository Instance, or Container in the CARMA Repositories or CARMA Fields Table View with the
[Link] extension point. CARMA developers can also specify whether to
have the default view appear automatically at expansion of the associated level.
You can perform the following actions on filters:
• Create a new filter
• Delete a filter
• Edit a filter

Versions
CARMA versions represent a previous copy of a member that is held by an SCM.

Versions in CARMA can only be created for CARMA members. The actions available on versions depend on
the SCM it originates from and the RAM used to connect to the SCM. Some RAMs can allow you to alter
versions, while other RAMs can make the versions read-only.
You can perform the following actions on versions:
• Open the version in an editor
• Make changes to a version
• Extract a version to a project
• Lock a version
• Unlock a version
• Check in a version
• Check out a version

Working with CARMA

CARMA actions are available in the menus for the CARMA Repositories view as well as for Developer for
z/OS projects that have been extracted from CARMA repositories.

Several actions might require extra parameters to be specified, in which case a dialog opens requesting
values for each of the parameters. You should complete the requested information in each dialog and
click OK. If a default value is available for a parameter, it will automatically be placed in the appropriate
field. Some fields can be disabled, indicating that the corresponding parameter requires a value that
cannot be modified. CARMA will also attempt to complete the fields in these dialogs using information
from the following sources:
• Member information with matching keys
• Cached values from previous entries
• User-specified values
The order in which these sources are checked can be configured in the CARMA preferences dialog.

Using CARMA views

Using CARMA begins with accessing the CARMA hierarchy from one of the CARMA views.
CARMA offers two views by default to work with:

Extending product functions 109

 The Repositories view
The Repositories view shows a hierarchical representation of the CARMA navigation hierarchy as
retrieved from the RAM. For additional information, see “Opening the Repositories view” on page 110
The Fields view
The Fields view shows a flat representation of the CARMA navigation hierarchy as retrieved from the
RAM. The Field view can be configured to show various member information along with the members
being shown. For additional information, see “Opening the Fields view” on page 110

Opening the Repositories view

Users access the CARMA system in IBM Developer for z/OS from the CARMA Repositories view.

In order to access CARMA, it is necessary to create a connection to the CARMA host. Once the host
connection is established, users can view the available repository access managers, repository instances,
and repository content.
To open the CARMA Repositories view, follow these steps:
1. From the Window menu on Windows or the IBM Developer for z/OS menu on macOS, click Show
View > Other.
The Show View dialog opens.
2. In the Show View dialog, expand the CARMA folder, select CARMA Repositories, and click OK.
The CARMA view opens in the lower-right corner of the current perspective. This view lists the existing
connections to CARMA hosts and can be included in any perspective available within Developer for
z/OS.

Opening the Fields view

Users access the CARMA system in the CARMA Fields view.
In order to access CARMA, it is necessary to create a connection to the CARMA host. Once the host
connection is established, users can view the available repository access managers, repository instances,
and repository content.
To open the CARMA Fields view, follow these steps:
1. From the Window menu on Windows or the IBM Developer for z/OS menu on macOS, click Show
View > Other. The Show View dialog opens.
2. In the Show View dialog, expand the CARMA folder, select CARMA Fields, and click OK.
The CARMA Fields view opens in the lower-right corner of the current perspective. This view lists
the existing connections to CARMA hosts and can be included in any perspective available within
Developer for z/OS.

Using the Fields view

The CARMA Fields Table view displays a single level of the CARMA hierarchy along with columns of
information for the displayed CARMA items.
The information that is displayed depends on the CARMA type being displayed. For example, RAM items
are displayed with RAM ID, RAM Version, RAM Level, Description, and Refresh Time. The information
displayed with Repository Instances or CARMA content is pulled from the member information for the
item. The particular member information displayed is determined based on the RAM. The items are
retrieved from and can be configured by the RAM as explained in the CARMA RAM Developer's Guide.
While the CARMA Fields table view only displays a single level of the CARMA hierarchy, it is possible to
change the level that is displayed. The levels of the hierarchy can be navigated down using the Go Into
action on the menu. You can also Go Into by double-clicking a CARMA item, which contains children
(Connection, RAM, Repository Instance, Filter, or container). In order to move up the hierarchy, you can
use the Go Up action on the toolbar. This sets the current level to be one level up from the current level. It
is also possible to use the forward and back buttons on the toolbar to move between previous levels.

110 Developer for z/OS: Managing and Extending the Eclipse Environment
Using the History view
Users access previous versions of CARMA members from the CARMA History view.
The History view will ONLY display CARMA versions and can be included in any perspective available
within Developer for z/OS.
1. From the Window menu on Windows or the IBM Developer for z/OS menu on macOS, click Show
View > Other. The Show View dialog opens.
2. In the Show View dialog, expand the CARMA folder, select CARMA History, and click OK.
The CARMA History view opens in the lower-right corner of the current perspective. This view might
initially appear empty, but can be populated from either the CARMA Repositories view or the CARMA
Fields view. On any CARMA member in the views, you can right-click on the member and select Show
History. The history view displays the list of versions for the member as retrieved from the RAM.
Note: The RAM might not support versions, and as such will not return a list of versions. For additional
information, see “Versions” on page 109

Using CARMA Fields Table view

The CARMA Fields Table View can be used to display a single level of the CARMA hierarchy. For each
type of CARMA element that is displayed, different properties or fields are provided in columns.

Types of CARMA Content Displayed

The properties that are displayed in the CARMA Fields Table View depend on the type of CARMA element
open in the view. For example, RAM items are displayed with the RAM ID, RAM version, RAM level,
description, and refresh time provided as fields. Repository instances and CARMA content have field
information that is retrieved from each member. For individual CARMA members, fields are provided
based on the RAM as CARMA Developers can customize the information that is retrieved for members.

Navigation in CARMA Fields Table View

Only one level of the CARMA hierarchy is active at a time in the CARMA Fields Table View; however, you
can navigate through different levels using the following controls.
• To navigate down into a CARMA item one level, either double-click the item or right-click the item and
select Go into.
• To navigate up the hierarchy one level, click the Go Up action on the toolbar.
• To navigate to the previous level, click the backward button.
• To expand and view CARMA items below the active level, select the arrow to the left of the CARMA item
to expand the item.

To view the children of the currently active level, select the arrow icon, . This expands the currently
active level and display the children of the CARMA item.

Sorting CARMA Items

CARMA items in the CARMA Fields Table View can be sorted according to the fields listed. Sorting is
based on the following constraints:
• Sorting is done by selecting the column header for a particular field. The first sort is ascending. The
second sort is descending.
• Sorting is done based on a comparison of the string value for the selected field.
• Sorting output conforms to any predefined filters. Any CARMA items that do not fall within defined filters
are not displayed in sorting output.
• Sorting maintains the tree structure of the CARMA Fields Table View. Sorting is performed at the
currently active level. Any expanded children are not sorted.
• Sorting is done only on the selected column header. For any CARMA items that have the same field
value; there is no additional sort; they are returned in their original order.

Extending product functions 111

 Customizing the CARMA Fields Table View
The columns in the CARMA Fields Table View can be customized by reordering, resizing, or hiding. Any
customization that is done is saved on a per RAM basis. If you customize any column, at the RAM level,
then the same customization persists after navigating into the containers and members within the RAM.
You can reorder columns by selecting, dragging, and dropping the column in the new location. Any column
can be reordered except for the CARMA Resources column, which always remains in column 1. If you
attempt to reorder a column before the CARMA Resources column, it will automatically be placed in
column 2, after CARMA Resources.
If new columns are added to the host configuration, then these updates are reflected in one of two ways.
If the CARMA Fields Table View is customized by reordering the columns, then these new columns
appear at the end. Otherwise, the new columns are added so that they maintain the same order as the
host.
You can resize columns by dragging the edges either in to make the column narrower, or out to make the
column wider. Resizing a column to width 0 is the same as hiding the column. You can resize any column
to any size except for the CARMA Resources column, which cannot be resized to width 0.
Alternatively, to hide, restore, and reorder columns you can use the Customize Table window.
If you want to reset the CARMA Fields Table View back to the original, default settings, select the Reset
Table action from the view menu. This restores all hidden columns and return any customized ordering
back to the default.
Related concepts
“Using Customize Table” on page 112
Use Customize Table window to customize the view of the CARMA Fields Table view columns. This
window eliminates the need to scroll back and forth to reorder and hide columns.

Using Customize Table

Use Customize Table window to customize the view of the CARMA Fields Table view columns. This
window eliminates the need to scroll back and forth to reorder and hide columns.

The Customize Table Window

The Customize Table window is divided into two separate lists of columns, Available contents and
Displayed contents. Column names that are listed in Available contents are hidden columns and do not
appear in the CARMA Fields Table view. Column names that are listed in Displayed contents are the
columns that make up the CARMA Fields Table view.
You can use the Customize Table window to hide, restore, and rearrange columns.

Hiding Columns
You can prevent columns from displaying in the CARMA Fields Table view by hiding them. To hide
displayed columns withCustomize Table:
1. Select one or more columns from the Displayed contents list.
2. Click <Remove to remove those columns from the Displayed contents list. They are added to the
Available contents list.
3. Click OK. The CARMA Fields Table view is updated.

Restoring Columns
You can display previously hidden columns by restoring them to the CARMA Fields Table view. To restore
hidden columns with Customize Table:
1. Select one or more columns from the Available contents list.
2. Click Add> to add those columns to the Displayed contents list.
3. Click OK. The CARMA Fields Table view is updated.

112 Developer for z/OS: Managing and Extending the Eclipse Environment
Alternatively, you can select the Reset Table option in the CARMA Fields Table view to reset the table
and restore any hidden columns.

Reordering Columns
You can reorder long lists of columns by using Move up and Move down in the Customize Table. To
reorder columns in the Customize Table view:
1. Select the column name to reorder.
2. Select the Move up to move up the column name in the list. The column name is moved to the left in
the CARMA Fields Table view.
3. Select the Move down to move the column name down in the list. The column name is moved to the
right in the CARMA Fields Table view.

Importing and exporting CARMA views

User-defined CARMA views can be imported and exported from the CARMA Repositories view.
To export all CARMA views, follow these steps:
1. From the CARMA Repositories view, right-click on a CARMA repository and select Export Views from
the menu.
2. Enter a name and location to save the exported views to and then select OK to export the views.
To export only selected CARMA views, follow these steps:
1. Using Ctrl + click, select each view that you would like to export from the CARMA Repositories
view.
2. Right-click on one of the selections and then select Export Views from the menu.
3. Enter a name and location to save the exported views, and then select OK to export the views.
Note: A separate schema is used for exporting Package views versus SCM views, so two different files
need to be created if exporting Package views and SCM views.
To import CARMA views, follow these steps:
1. From the CARMA Repositories view, right-click on the CARMA repository from which the views were
exported and select Import Views from the menu.
2. Using the file browser, navigate to where the exported CARMA views file is located and select it. Press
OK to import the views.

CARMA icons
This topic describes icons that are commonly used in the CARMA Repositories view, CARMA Version
History view, and CARMA Fields Table view.

CARMA Repositories View

The following are icons that are commonly used in the CARMA Repositories view.

Table 5. CARMA Repositories View

Icon Description Icon Description
CARMA Repository view Launch a wizard to
or an unconnected create a new CARMA
CARMA connection connection
A connected CARMA A repository instance
connection
A connected RAM An unconnected RAM
(Repository Access (Repository Access
Manager) Manager)

Extending product functions 113

 Table 5. CARMA Repositories View (continued)
Icon Description Icon Description
Create a new folder, Create a new file,
available in the menu available in the menu.
Refresh the currently Refresh is disabled
selected items in the
CARMA Repositories
view
Create a new view or Create a new view or
filter, available in the filter is disabled
menu

CARMA Fields Table View

The following are icons that are commonly used in the CARMA Fields Table view.

Table 6. CARMA Fields Table view

Icon Description Icon Description
CARMA Fields Table Launch a wizard to
view create a new CARMA
connection
A CARMA connection A connected CARMA
connection
A RAM (Repository A connected RAM
Access Manager) (Repository Access
Manager)
Create a new folder, Create a new file,
available in the menu available in the menu
Refresh the table Refresh table is disabled

Refresh children, Refresh children is

available in the menu disabled
Refresh fields, available Refresh fields is
in the menu disabled
Create a new view or Create a new view or
filter, available in the filter is disabled
menu
A repository instance

CARMA Version History View

The following are images that are commonly used in the CARMA Version History view.

Table 7. CARMA Version History view

Icon Description Icon Description
CARMA Version History Refresh is disabled
view

114 Developer for z/OS: Managing and Extending the Eclipse Environment
Table 7. CARMA Version History view (continued)
Icon Description Icon Description
Refresh the CARMA
version history

Connecting to a CARMA host

The first step in accessing CARMA is to define a connection to a CARMA host. The CARMA host is the
connection point for gaining access to repository source code, data, and functions. Multiple CARMA
connections can be defined and configured for each user to a single host machine.

Connecting to CARMA
CARMA requires a connection to a CARMA host in order to retrieve SCM information from the host.

CARMA uses the connection services of the Developer for z/OS Remote System Explorer (RSE) to connect
to the host. To create a new CARMA connection, follow these steps:
1. In the CARMA Repositories view do one of the following steps:

• Click the New Connection button .

• Right-click inside the view and click New Connection.
The New CARMA Connection wizard opens.
2. Choose one of the options from the list and click Next.
3. If you chose to create a new CARMA connection from an existing RSE connection, the New CARMA
Connection dialog opens.
4. If you chose to create a new RSE and CARMA connection, the New Remote z/OS System Connection
dialog opens.
Note: If this is the first time that you have attempted to create a connection in RSE, you will not
see the dialog yet, but will instead be prompted to create a profile before you can create the new
connection.
5. Complete the following fields in the dialog:
Parent profile
The profile that is named after your workstation appears by default. To choose a different profile,
select a predefined profile from the drop-down list. After you create the connection, you can
share this profile to allow other users to have this connection in their RSE perspective.
Connection name
A unique name to identify your connection in the Remote Systems view. For example,
Development System or Test System. The label that you assign to this connection helps you
to differentiate between multiple connections to the same type of remote system.
Host name
The host name or IP address of the z/OS system that your RSE server is installed on.
Description
A short description of the z/OS system that you want to connect to, for example, Development
System or Test System. The description that you assign to this remote system helps you to
differentiate between multiple remote systems of the same type.
Verify host name (optional)
To verify that the host name or IP address in the host name field is valid, select the Verify host
name check box.
6. The next dialog window is the Connection Configuration window.
• In the Daemon Port field, type the port number that is used by the server daemon on the remote
host. By default, port 4035 appears.

Extending product functions 115

 • Select the Authentication method.
7. If you do not need to configure any MVS files subsystem properties, click Next to proceed to the next
step.
• Select the default method for starting the RSE host server.
– To automatically start the RSE host server using a server daemon:
a. Click the Remote daemon radio button.
Note: You must start the server daemon using the root user ID. If you do not start the server
using the root user ID, it cannot authenticate users who are trying to connect to the server.
b. In the Daemon Port field, type the port number that is used by the server daemon on the
remote host. By default, port 4035 appears.
c. Select the Authentication method.
– To automatically start the RSE host server using an REXEC command:
a. Click the REXEC radio button.
b. In the Path to installed server on host field, type the path where the RSE host server is
installed on the remote host. You can specify a path that is relative to the directory where
you run the REXEC command or the full path to the location where the server is installed. For
example, dstore or /usr/bin/dstore.
c. In the Server launch command field, type the name of the script file to run when you use the
REXEC command to start the RSE host server. By default, [Link] appears; this is the
sample script file that is shipped with IBM TPF Toolkit for WebSphere Studio to start the RSE
host server.
d. In the Port field, type the port number that is used by the REXEC daemon on the remote host.
By default, port 512 appears.
– To connect to an RSE host server that you start manually:
a. Click the Connect to running server radio button. If your remote system is not configured
to use REXEC to start the RSE host server, this option allows you to connect to an RSE host
server that you start manually.
Note: When you start the RSE host server manually on the remote host, you can configure
it to receive connection requests at a specified port or to use the next available port on the
system. The port number that is used by the server is displayed when you start the server.
After you start the server, you must specify that port number in the Subsystem properties
page before you can connect. To access the Subsystem properties page:
i) Switch to the RSE perspective.
ii) In the Remote Systems view, double-click the z/OS connection to expand it and reveal the
z/OS UNIX Files subsystem.
iii) Right-click the z/OS UNIX Files node and select Properties from the menu to open the
Properties for z/OS UNIX Files dialog box.
iv) In the left navigation pane, click Subsystem to open the Subsystem properties page.
– To connect to an RSE host server through a secure connection:
a. Click the SSH radio button (Secure Shell).
b. In the Path to installed server on host field, type the path where the RSE host server is
installed on the remote host. You can specify a path that is relative to the directory where
you run the REXEC command or the full path to the location where the server is installed. For
example, dstore or /usr/bin/dstore.
c. In the Server launch command field, type the name of the script file to run when you use the
REXEC command to start the RSE host server. By default, [Link] appears; this is the
sample script file that is shipped with IBM TPF Toolkit for WebSphere Studio to start the RSE
host server.

116 Developer for z/OS: Managing and Extending the Eclipse Environment
 d. In the Port field, type the port number that is used by the REXEC daemon on the remote host.
By default, port 512 appears.
e. Select the Authentication method.
8. If you do not need to configure any JES subsystem properties, click Next to proceed to the next step.
• In the JES tab:
a. In the JES Job Monitor port field, type the port on which the Remote Job Monitor is listening.
b. In the Max Number of Lines to Download field, type the number of lines to download before
prompting you to specify whether you want to download all of the lines in the data set.
9. Click Finish to create the new CARMA connection and add it to the CARMA Repositories view.
10. To activate the connection, do one of the following:
• Right-click on the connection and select the Connect menu item.
• Alternatively, you can activate a connection by expanding the connection by clicking the + next to
the connection name. Note that this method will only work the first time that you are connecting
to this CARMA host. Use the previous method to explicitly connect to the CARMA host for
subsequent connection attempts.
Note: Attempting to perform any action on the elements under a CARMA connection will
automatically activate the connection.
11. In the Enter Password dialog, type a valid user name and password and click OK.
A list of repository access managers (RAMs) appears under the CARMA host in the CARMA
Repositories view.
Related tasks
“Disconnecting from CARMA” on page 117
It is possible to disconnect from a CARMA host after connecting to it.
“Connecting to a RAM” on page 118
Before you can perform actions on repository content, you must connect to the RAM used to access that
repository content.
“Disconnecting from a RAM” on page 118
It is possible to disconnect from individual RAMs within a CARMA host.

Disconnecting from CARMA

It is possible to disconnect from a CARMA host after connecting to it.
To disconnect from a CARMA host, follow these steps:
1. Right-click on the CARMA host in the CARMA Repositories view.
2. Click Disconnect in the menu.
The icon next to the CARMA host name should change to .
Related tasks
“Connecting to CARMA” on page 115
CARMA requires a connection to a CARMA host in order to retrieve SCM information from the host.
“Connecting to a RAM” on page 118
Before you can perform actions on repository content, you must connect to the RAM used to access that
repository content.
“Disconnecting from a RAM” on page 118

Extending product functions 117

 It is possible to disconnect from individual RAMs within a CARMA host.

Connecting to a RAM
Before you can perform actions on repository content, you must connect to the RAM used to access that
repository content.
The CARMA system automatically attempts to connect to the appropriate RAM whenever an operation
on repository content is performed. Alternatively, you can explicitly connect to a RAM by following these
steps:
1. Right-click on the RAM in the CARMA Repositories view.
2. Click Connect in the menu.
If you are not already connected to the CARMA host for the RAM, the Enter Password dialog opens.
3. In the Enter Password dialog, type a valid user name and password and click OK.
4. The icon next to the RAM name should change to .
5. Expand the RAM to see the repository instances. Your CARMA developer may have specified a filter to
automatically open upon expansion of the RAM or repository instance. This allows CARMA to retrieve
only the repository instances and elements you are most likely to use.
Related tasks
“Connecting to CARMA” on page 115
CARMA requires a connection to a CARMA host in order to retrieve SCM information from the host.
“Disconnecting from CARMA” on page 117
It is possible to disconnect from a CARMA host after connecting to it.
“Disconnecting from a RAM” on page 118
It is possible to disconnect from individual RAMs within a CARMA host.

Disconnecting from a RAM

It is possible to disconnect from individual RAMs within a CARMA host.
To disconnect from a RAM, follow these steps:
1. Right-click on the RAM in the CARMA Repositories view.
2. Click Disconnect in the menu.
The icon next to the RAM name should change to .
Related tasks
“Connecting to CARMA” on page 115
CARMA requires a connection to a CARMA host in order to retrieve SCM information from the host.
“Disconnecting from CARMA” on page 117
It is possible to disconnect from a CARMA host after connecting to it.
“Connecting to a RAM” on page 118
Before you can perform actions on repository content, you must connect to the RAM used to access that
repository content.

Deleting a CARMA connection

Learn how to delete a CARMA connection.

To delete a CARMA connection, do one of the following in the CARMA Repositories view:
• Select the connection that you want to delete and press the Delete key.
• Right-click the connection name and click Delete.
The connection is removed from the CARMA Repositories view.

118 Developer for z/OS: Managing and Extending the Eclipse Environment
Working with CARMA Resources
You can work with CARMA resources in any of the CARMA views.
CARMA resources can be accessed or altered directly in the SCM from any CARMA view.

Browsing/editing a member
CARMA resources can be edited on a file by file basis without the need to extract them into a project in the
workspace.
The process of browsing or editing an individual file is simple and can be performed on any CARMA
member that is located within a CARMA enabled view. To browse or edit a CARMA member, follow these
steps:
1. Simply double-click the member or right-click the member to be browsed/edited from the CARMA
Repositories View or any other CARMA enabled view.
2. Select Open from the menu to use the default editor that is associated with that particular file type.
3. To choose the editor you would like to open the file with, select Open With from the menu and choose
the wanted editor.
The resource is pulled from the host machine and opened in either the default editor that is associated
with the file-extension or the editor that you choose to use.
Saving the member in the editor uploads any changes made back to the host.

Content views
CARMA provides advanced filtering capabilities for RAMs, RAM Instances, and containers in CARMA
enabled environments by allowing users to pass filter arguments to the RAM.
Using filter/views can help expedite performing navigational functions by allowing the RAM to return a
smaller set of content for a RAM or container. By default, a CARMA client requests all available resources
in a selected RAM, RAM Instances, or container. To narrow the results, one or more filter/views can be
specified to help sort the content. To set a filter/view, follow these steps:
1. Select the RAM, RAM Instance, or container that you want to apply a filter/view to.
2. Right-click on the object to display the menu. Select New followed by New View to activate the New
Filter/View wizard.
3. Enter a string to be filtered and select Finish.

Identifying CARMA views

Once filter/views are specified in CARMA, they become visible to the user in the CARMA Repositories
View. Filter/Views are displayed in two ways.
When only one filter/view is specified on a RAM, RAM Instance, or container, the filter string argument
will be displayed directly after the object the filter/view was applied to in {} braces. The following image
depicts a RAM that has only one filter/view applied to it:

It is important to note that in this particular example, the "*" notation that is used to define the filter/view
is a default that is specified within the RAM. If a different filter/view is specified such as "foo.123", and it
is the only filter/view defined for that particular object, it is displayed in the same manner depicted in the
example. (example: {foo.123})

Extending product functions 119

 When multiple filter/views are defined for a single object, they are displayed like the following:

When multiple filter/views are defined, each individual filter/view is displayed beneath the object it was
defined for. This example depicts three filter/views that are defined on the RAM named "SKELETON RAM".
To view the content that is created by each filter/view simply expand the filter/view by pressing the "+"
next to it.
Unwanted filter/views can be removed by selecting them and deleting them via the keyboard, menu, or
menu bar.

Viewing member information (metadata)

CARMA allows you to query the CARMA repository for metadata that is related to members.

To view metadata properties that are related to repository content, follow these steps:
1. Right-click the CARMA resource (Member, Container, or Repository Instance).
2. Click Properties.
The Properties dialog opens.
Note: The first time that the properties dialog is opened, the member information is automatically
retrieved.
3. Optional: To retrieve the most recent property values from the repository, click the Refresh Properties
button.

Refreshing resources
Users can refresh any item that is displayed in the CARMA Repositories view.

The Refresh action contacts the CARMA host to obtain the most recent information relating to:
• List of repository access managers
• List of repository instances
• New repository content
The Refresh action adds and removes any content that has been changed in the SCM by other users since
the last refresh action, and refreshes the names and properties of the content.

Creating members and containers

You can create members and containers by dragging and dropping resources directly into a CARMA
repository or into a container within the repository.
When a resource is dragged from one location and dropped into another, CARMA automatically calls the
appropriate create function to carry out the task. In doing so, a new member or container is created in the
new location and the resource is copied from the original location.
Note: You can drag items into the CARMA Repositories View, but not vice versa
In addition to drag, members and containers can also be created from the menu within the CARMA
Repositories view. To create a member or container from within the CARMA Repositories view, follow
these steps:

120 Developer for z/OS: Managing and Extending the Eclipse Environment
1. Expand a RAM within the CARMA Repositories view.
2. Right-click on a member or container within the RAM to open the menu.
3. Select New.
4. Select either a New Member or a New Container.
The New CARMA Member/Container dialog window opens.
5. Within the dialog, select the parent container that you want to use, and enter a name for the member
or container.
6. Once finished, select Finish to complete the process.

Deleting members and containers

In addition to being able to create members and containers from the menu, you can also delete them.
To do this:
1. Expand a RAM within the CARMA Repositories view.
2. Right click a member or container within the RAM to open the menu.
3. From the menu, select Delete.
Note: If the delete fails, the user is prompted if they would like to force the delete by setting the
force parameter to true. If the resource being deleted is a container, CARMA attempts to delete the
container as a whole first. If it fails, CARMA can then attempt to delete all of the contents within the
container first before deleting the container itself.

Locking repository content

The Lock action makes repository content read-only for all users except for the user who locked the
content.
To lock repository content, follow these steps:
1. Right-click the content to be locked.
2. Click Team > Lock.
The lock action is sent to the CARMA host and a request is submitted to the repository to lock the
selected content.

Unlocking repository content

The Unlock action makes repository content editable for all users.

The Unlock action is only available for repository content that is locked by the user. To unlock repository
content, follow these steps:
1. Right-click the content to be unlocked.
2. Click Team > Unlock.
The Unlock action is sent to the CARMA host and a request is submitted to the repository to unlock the
selected content.

Checking in repository content

The Check In action updates content in the CARMA repository, marks the content as checked into the
repository, and allows other users to check out that content.

The Check In action is only available for repository content that is checked out by the user. To check in
repository content, follow these steps:
1. Right-click the content to be checked in.
2. Click Team > Check In.

Extending product functions 121

 The Check In action is sent to the CARMA host and a request is submitted to the repository to check in
the selected content.

Checking out repository content

The Check Out action downloads content from the CARMA repository, marks the content as checked out
of the repository, and prevents other users from checking out that content.
The Check Out action is only available for repository content that is not already checked out. To check out
repository content, follow these steps:
1. Right-click the content to be checked out.
2. Click Team > Check Out.
The Check Out action is sent to the CARMA host and a request is submitted to the repository to check
out the selected content.

Enabling binary file transfer

Individual CARMA resources can be defined within the properties dialog window as being binary files.
This specification allows CARMA to recognize files that contain binary data and also modifies the way that
these files are handled within the file system, negating any possible corruption due to mishandling. To
change the transfer mode of a CARMA Resource:
1. Right-click the resource that you wish to define as binary.
2. Click Properties from the menu.
3. Select "binary" from the selection box labeled Transfer Type from the Properties dialog window.
4. Select OK.

Performing RAM-specific custom actions

RAMs can provide extra actions if the standard set of CARMA actions is not sufficient for supporting all
the features of an SCM. These additional actions are known as custom actions. To access a custom action,
follow these steps:

1. Right-click on the repository content you want to start the action on.
2. Click Team > Custom, and then select the menu item corresponding to the action you want to start.
For example, if you wanted to start an action that is called "Build", you would click Team > Custom >
Build.
The custom action is sent to the CARMA host and a request is submitted to the repository to perform the
custom action on the selected content.

RAM-specified file extensions

CARMA allows you to have the RAM specify file extensions that are based on metadata, eliminating the
need to specify extensions on every resource.

The RAM can provide a file extension recommendation for a CARMA member, which is used as the file
extension by default. If the RAM does suggest a file extension, you can either accept the recommended
extension as is, or choose to override the recommendation by using an extension of your own via the
CARMA member properties dialog. If a member does not have a predefined RAM specified file extension,
and one is not set by the user in the client, the member inherits the file extension of its parent.
In order to allow inheritance, the file extension property can be specified at any level (container or
member), however, it can only be displayed on CARMA members, not CARMA containers. Containers only
have a file extension that is specified to allow inheritance to child members when a file extension is not
specified anywhere else. To view metadata properties that are related to repository content, follow these
steps:
1. Right-click the content.
2. Click Properties.

122 Developer for z/OS: Managing and Extending the Eclipse Environment
 The Properties dialog opens.
3. Optional: To retrieve the most recent property values from the repository, click the Refresh Properties
button.

Client defined file extensions

To set your own file extension for a CARMA member:
1. Select a container or member and open the properties dialog window.
2. Locate the Local file extension section of the properties dialog window.
3. Select the second bullet in the list.
4. Choose a new file extension from the drop-down menu.
5. Select OK.

Disabling unsupported actions

Certain SCMs, due to their limitations, might not support all the actions that are offered by CARMA.

When users attempt to perform one of these actions, an information message states that the action is
unsupported on the RAM and the action is then disabled. For example, if you attempt to execute the Lock
action on a PDS data member (since the Lock action is not supported by the PDS RAM) the Unsupported
Operation dialog opens with the following error message: The attempted action is unsupported on
resources of this type by PDS RAM. Would you like to disable this action in the future?
Clicking Yes in the dialog disables the Lock action for all repository instances that use the PDS RAM. The
Lock action will still be displayed in CARMA menus for PDS RAM content, but it is disabled.
Related tasks
“Re-enabling unsupported actions” on page 123
It is possible to re-enable unsupported actions once they have been disabled.

Re-enabling unsupported actions

It is possible to re-enable unsupported actions once they have been disabled.

Follow these steps to enable those actions that have been disabled:
1. In the navigation pane of the Preferences window, click Version Control (Team) > CARMA.
The CARMA preferences pane is displayed on the right.
2. Clear Disable known unsupported actions.
Related tasks
“Disabling unsupported actions” on page 123
Certain SCMs, due to their limitations, might not support all the actions that are offered by CARMA.

Working with CARMA associated projects

CARMA resources can be extracted to a local or a remote project.
CARMA resources can be extracted to a local or a remote project. When extracted to a project, an
association back to the repository resource is maintained. CARMA-specific actions are added to CARMA
associated projects under the team menu. When the actions on the team menu are run, they run against
the associated repository resource.

Retrieving z/OS project properties

The project property retrieval option is available only on z/OS remote projects.
CARMA inspects the selected CARMA content member information for specific z/OS project properties
and then sets the properties in the project that is based on information that is retrieved from the RAM.
To retrieve z/OS project properties, follow these steps:

Extending product functions 123

 1. Right-click on the content that has properties set in the z/OS project.
2. Click Team > Retrieve Project Properties.
The member information for the resource is retrieved from the RAM using the Get All Member Info action.
The Get All Member information action is sent to the CARMA host and a request is submitted to the
repository to retrieve member information for the selected content. The member information is inspected
for project property keys, which are then set on the members that are held by the project. For additional
information, see “Viewing member information (metadata)” on page 120
Note: For more information on specific property keys, reference the Remote Resource Access API guide.
The Remote Resource Access API guide is available in the Developer for z/OS Help contents only if the
API has been installed

Extracting repository content

Any content from CARMA can be extracted to a Developer for z/OS project to provide a copy of the content
that users can manipulate locally without updating host contents.

To extract CARMA content to a project follow these steps:

1. Right-click the item in the CARMA repositories view.
2. Select Extract to on the menu then select Local Project.
The Extract dialog opens.
3. Type the name of the project to create and the directory in which the files are stored locally.
4. Click Finish.
The directory structure and file contents are copied to the local file system. The project containing the
newly downloaded content is available in the Navigator view.

Extracting files to a z/OS project

In order to add more editing functionality to CARMA resources, they can be extracted into a z/OS project
in your workspace.

Doing so allows you to take full advantage of the z/OS Integrated Development Environment. To extract
CARMA resources into a z/OS project:
1. Right-click the subset of files you would like to extract from within the CARMA Repositories view.
2. Select Extract to from the menu followed by Remote Project to open the extract to remote z/OS
project dialog.
3. Choose to use an existing z/OS Project/sub-project or create a new one. Clicking the Advanced >>
button displays other options that are available. The only option available in Developer for z/OS is z/OS
project property retrieval. Once all information for the extract project is entered select the next button.
4. Select a host location to extract to. This can be a PDS or a sequential file depending on the items that
are selected in the CARMA Repositories view. A single member can be extracted to a Sequential file or
PDS Member, and multiple items or a container can only be extracted to a PDS.
5. Select OK.
The selected CARMA items are copied to the host location and the project structure is set up on the
client for use as a normal z/OS project. All of the actions available for CARMA can be found under
the team menu (e.g., lock, unlock, checkin, and so on) which also include methods to move the
resources back into CARMA. The items that are extracted into the remote project work as if they are
disconnected from the SCM. Changes made to the items in the project will not be reflected in the SCM
until the item is copied back into the SCM.

Associating project resources with CARMA

Project resource must first be associated with a CARMA resource in order to perform CARMA actions,
such as check-in or upload. For example, when an upload action is performed the workspace resource
is uploaded to the associated repository resource. If a project resource is not associated with CARMA,

124 Developer for z/OS: Managing and Extending the Eclipse Environment
then no CARMA actions will appear under the team menu. The only action available will be the association
action.
To associate project content, follow these steps:
1. Right-click the content to be associated.
2. Click Team > Associate with CARMA. This launches the association wizard.
3. The association wizard displays the list of the valid CARMA content to which the project resource can
associate. Select a resource to associate with.
4. Click the Finish button to complete the association.
The association should now enable the valid CARMA actions on the Team menu for the associated project
resource.
Note: When a z/OS subproject is associated with CARMA at the RAM level, CARMA loses the ability to
update project properties at the subproject level. CARMA will still retain the ability to update project
properties at the data set and member levels.

Sharing a project with CARMA

Sharing a project with CARMA allows resources that exist within Eclipse and z/OS to be associated with
CARMA or included into the CARMA navigation structure.
You can use the added integration of CARMA into the Eclipse and z/OS project structure to take advantage
of CARMA functions from any type of project that is located within the Developer for z/OSframework.
To share a project with CARMA, follow these steps:
1. Select a project to share with CARMA and open the menu by right-clicking.
2. From the menu, select Team > Share Project
The Share Project dialog opens.
3. To share a project with CARMA, select CARMA from the list and then select Next.
Note: If you are working with a z/OS project, CARMA is selected by default.
4. Select the CARMA connection that you want to share your project with, and then select Next. If only
one connection exists, that connection is selected by default and the wizard skips to the next dialog
automatically.
Based on the connection that is chosen, the wizard displays a list of RAMs that exist on that connection
and the Repository Instances that are within each of those RAMs.
5. Select the RAM and corresponding Repository Instance that you want to share your project with, and
then select Next.
The share to CARMA function provides users with two options to help integrate their content with
CARMA:
Associate Project with Instance
Associating project resources with CARMA allows the project content to have CARMA functions
outside of the CARMA navigation structure. After it is enabled, the user can access the CARMA
functions through the Team menu.
Transfer Existing structure to CARMA
Choosing to transfer an existing project into CARMA copies the project structure and content into
a location within the CARMA navigation structure that the user specifies. The location that is
specified must be a type of container (RI, container) for the transfer option to work. If a container
does not exist in the location that you want, it is up to the RAM to decide whether to create
a container for the project or to reject the choice of location. After a project is transferred into
CARMA, it is treated like any other CARMA project.
6. Choose a configuration option and select Finish.
7. If you choose to associate the project with a CARMA instance, no further action is required. Select
Finish.

Extending product functions 125

 8. If you choose to transfer your existing project into CARMA, select the parent container of the
Repository Instance you would like to transfer the project to and then select Finish.

Adding content to projects

CARMA content can be added to an existing project to provide a copy of the content that users can
manipulate locally without having to update the host contents.

To add CARMA content to a project follow these steps:

1. Right-click the item in the CARMA repositories view.
2. Click Add to Project.
The Add to Project dialog opens.
3. Select the project to add the content to from the drop-down list.
4. Click Finish.
The file hierarchy structure and file contents are copied to the local storage location for the specified
project. The project containing the newly downloaded content is available in the Navigator view.
Note: The list of available projects displays LOCAL projects that are currently associated with CARMA.
This means previously extracted projects, or projects that have been "shared" (“Sharing a project with
CARMA” on page 125).

Uploading workspace resources to the repository

The Upload Local File action updates the selected content in the CARMA repository.
The Upload Local File action is available on any repository content that has been extracted from CARMA.
In order to upload repository content:
1. Right-click the content to be uploaded.
2. Click Team > Upload Local File.
The local contents are sent to the CARMA host and stored in the associated repository.

Replacing workspace resources with the latest version

The Replace with Latest from <RAM NAME> action updates the selected content in the local workspace.

<RAM Name> is the name of the CARMA RAM the project is associated with. Replace with Latest from
<RAM NAME> action is available on any repository content that has been extracted from CARMA. To
replace the local version of repository content, follow these steps:
1. Right-click the content to be replaced.
2. Click Team > Replace with > Latest from... <RAM NAME>
The repository content is retrieved from the CARMA host and overwrites the local version of the
selected content. Any synchronization information that is associated with the replaced item is
updated.

Comparing workspace resources with the repository

The Compare with SCM action downloads the current version of the SCM Member from CARMA and
compares the contents to the file in the local workspace.
The local workspace version and the newly downloaded version are opened in a compare editor, which
points out differences between the two files. The compare editor also allows you to copy individual
changes that have occurred to the SCM file into the workspace file.
Note: The compare also works for members in a remote project.
To perform a compare between local workspace version and the SCM version:
1. Right-click on the member to be compared in the project.

126 Developer for z/OS: Managing and Extending the Eclipse Environment
2. Click Compare with > Latest From <RAM NAME>, where the <RAM NAME> is the name of the CARMA
RAM the project is working with.
The repository version is downloaded from the host and compared with the copy in the local workspace.

Managed synchronization
Developer for z/OS offers a Managed Synchronization wizard that allows users to set up projects so
that they can be easily synchronized with a host without the need to manually set mappings for each
file. The Managed Synchronization wizard page offers the ability to enable automatic mapping. When
enabled, specified project files are automatically mapped to remote MVS locations based on the type of
file extension.
Attention: The push-to-host (remote synchronization) function is deprecated.

When you enable Remote Synchronization, the Enable Remote Synchronization wizard contains a
Managed Synchronization wizard page. To access the wizard, perform the following steps.
1. Enable the local project by Right-clicking on it and then selecting Remote > Enable Remote
Synchronization from the menu.
2. The Remote Synchronization wizard is displayed.
The Remote Synchronization wizard consists of three main parts. At the top of the window is a checkbox
labeled Automatic Mapping. To enable automatic mapping, simply select this checkbox. Located just
below that are two drop-down boxes that are labeled Host Short Name and High Level Qualifier. The
Host Short Name box allows you to select the host system that you would like to use for your mappings.
If you want to define a High-Level Qualifier, you must be connected to the host system before starting
the wizard. Once a connection is made, the wizard allows you to select a High-Level Qualifier from a list
of defined filters for your connection. Selecting a High-Level Qualifier allows your mappings to use the
<HLQ> variable, which are replaced with the selected High-Level Qualifier.
Note: If you are enabling remote synchronization on a Local z/OS Project, such as a Local COBOL Project,
the Host Short Name and High-Level Qualifier are set in a previous wizard page, and will not be editable
on the Managed Synchronization wizard page.
The wizard, by default, provides an editable list of available mappings that can be used to synchronize
your local files to the host. If the list of mappings that is provided is not sufficient, the remote
synchronization wizard also provides you with the ability to add your own mappings.

Table 8. The following variables are supported within the Mapping location.
Variable Name Description Example
<HLQ> The High-Level Qualifier <HLQ>.SRC>COBOL might be
selected. This allows for mapped to [Link]
mappings to be easily changed
between users and systems.
<PROJ> This variable maps to the FEL.<PROJ>.[Link] might
truncated name of the local be mapped to
project. [Link] for a
project named “Local Project”.

To manually add a mapping to the list, perform the following steps:

1. Select the Add button that is located to the right of the mappings area.
2. When the mapping editor appears, it requests a file extension as well as mapping location.
• File extension: The extension for which you want to map.
• Mapping location: The location where files with the specified extension is mapped to.
3. Select OK to finish.
4. Repeat steps 1 - 3 to add any additional mappings.

Extending product functions 127

 After managed synchronization has been enabled and configured for your projects, CARMA will map your
files for you. Part of this process involves the truncation of file names to ensure that they fit the mapping
location properly. File names are truncated to a maximum length of 8 characters. In addition, all spaces
and invalid MVS characters are removed and the names are converted to all uppercase. These default
mappings are visible in the Pushable Manifest Editor, and are green. If two or more files are mapped
to the same location with an identical truncated file name, an error occurs. When this happens, you are
forced to manually change the mapped location of the files that have been mapped to the same location.
These locations can be changed in the Pushable Manifest Editor. See below for an example.

File File name Truncated file name Error Caused

File 1 Super big [Link] [Link](SUPERBIG) Yes
File 2 Not so [Link] [Link](NOTSOBIG) No
File 3 Supper Big file for [Link] [Link](SUPERBIG) Yes

After a project has enabled Remote Synchronization, you can view and edit its properties and settings by
Right-clicking the enabled project and selecting Remote Properties from the menu.
You can modify the initial list of mappings that are presented by the Managed Synchronization wizard
page through the Remote Synchronization page of the Preferences window at Remote Systems >
Remote Synchronization.

Synchronizing with the repository

The Synchronize with Repository action compares the structure of the project in the workspace with the
version of the associated SCM contents on the host.
To perform a CARMA synchronization:
1. Right-click on the project content to be synchronized. This could be a single member, a container, or an
entire project.
2. Click Team > Synchronize with Remote.
3. The Synchronize perspective opens indicating the changes that have been made to the selected
project content.
For additional information, see “Defining criteria for CARMA compare” on page 177. Based on the
compare criteria that are defined by the RAM developer, the synchronize action can determine if:
• Changes are made to the local workspace and need to be sent to the SCM indicated by a gray right
facing arrow.
• Changes are made to the SCM and need to be brought local indicated by a blue left facing arrow.
• Changes have been made to both the local workspace and the SCM and the changes need to be merged
indicated by a red arrow pointing both left and right.

Committing changes to the repository

Committing changes to the repository uploads the current local workspace contents to the SCM.
The current version's contents change to match the version in the local workspace.
Note: This is equivalent to the Upload local file action.

Updating the workspace with changes

Updating changes in the local workspace downloads the current SCM contents and replaces the copy in
the local workspace.
The file in the workspace changes to match the version that is current in the SCM.
Note: This is equivalent to the Replace with latest from repository action

128 Developer for z/OS: Managing and Extending the Eclipse Environment
Sample RAMs
The following sample RAMs allow you to access a PDS associated with TSO users or, to access Software
Configuration Library Manager (SCLM) assets stored in SCLM projects.
• “PDS RAM” on page 129
• “SCLM RAM” on page 129
Note: The sample RAMs are provided for the purpose of testing the configuration of your CARMA
environment. These RAMs are NOT supported in a production-level environment.

PDS RAM
The PDS RAM allows you to access a PDS associated with TSO users by using ISPF services. In this case,
the TSO/ISPF services are the SCM and the repository is user's PDS.

Unsupported actions

The following CARMA actions are unsupported by the PDS RAM, since it does not have version control
capabilities:
• Lock
• Unlock
• Check Out
• Check In

Actions with limited support

The following actions are currently only available for files with a record format of "Fixed Block".
• Extract
• Upload Local File
• Replace with Latest from <RAM NAME>
Related tasks
“Disabling unsupported actions” on page 123
Certain SCMs, due to their limitations, might not support all the actions that are offered by CARMA.

SCLM RAM
The Software Configuration Library Manager (SCLM) RAM allows you to access and edit software assets
that are stored in SCLM projects. If the SCLM RAM is available on your CARMA host, then you can connect
to an SCLM project using the CARMA plug-in. For detailed information regarding SCLM operations, refer to
the Software Configuration Library Manager Reference.

Unsupported actions

The SCLM RAM does not support the following actions. Attempting to execute any of these actions result
in an error dialog.
Check in
To allow another user to edit a source file, use the Unlock action.
Check out
To gain exclusive access to a source file for editing, use the Lock action. Other users will still be able
to access the source file by extracting it from the repository, but they will not be permitted to check in
their updates to this file until you have unlocked the file.

Extending product functions 129

 Connecting to the SCLM RAM

You can connect to the SCLM RAM just as you would connect to any generic CARMA RAM, except that
when authenticating you will also be prompted for a valid SCLM project name.

Locking an SCLM member

Using the Lock action marks an SCLM member as read-only for all other users. The SCLM-specific Lock
action requires that a project definition and access key be specified. If no project definition is specified,
the project name is used by default. The access key is used to provide extra security for the locked
member. If no access key is specified, your user ID is used by default. If you decide to specify an access
key, you must use the same access key to unlock the member.

Unlocking an SCLM member

The Unlock action marks a locked SCLM member available for updates by another user. The Unlock action
requires that a project definition and access key be specified. If no project definition is specified, the
project name is used by default. The access key is used to provide extra security for the locked member
and must match the key that is used to lock that SCLM member. For security reasons, this key cannot
be saved; you must reenter it every time that you wish to unlock the SCLM member. If no access key is
specified, your user ID is used by default.

Building and promoting an SCLM member

The Build and Promote actions allow SCLM-controlled projects to respectively be built and promoted in
the build chain. Both of these actions request a project definition to be specified. If you choose not to
specify a project definition, the name of your SCLM project is used by default.
Additionally, you can specify a mode and scope for both the build and promote actions. The mode
controls the execution of the build or promote operation on the host. Valid values for the build mode are:
C (the default value), F, R, and U (Conditional, Forced, Report, and Unconditional). Valid values for the
promote mode are C (the default value), R, and U (Conditional, Report, and Unconditional).
The scope controls what is built or promoted. Valid values for the build scope are E, L, N (the default
value), and S (Extended, Limited, Normal, and Subunit). Finally, valid values for the promote scope are E,
N, and S (Extended, Normal, and Subunit).

Troubleshooting

Error messages for the last SCLM-specific action are stored (by default) in the [Link] data set.
Note: Depending on how your CARMA host has been configured, this data set may actually have a
different file name. The CRA in the data set name can be replaced with some other string. Contact your
system programmer to determine where this data set is located on your host system.
Related tasks
“Disabling unsupported actions” on page 123
Certain SCMs, due to their limitations, might not support all the actions that are offered by CARMA.

CARMA preferences
CARMA has several settings that can be modified through preferences. To access these settings, in
the Preferences window, expand the Version Control (Team) node, and select CARMA. The CARMA
preferences can also be accessed by selecting Preferences from the menu bar of each of the three
CARMA views. Each of the checkboxes in this menu modifies some setting in CARMA.

130 Developer for z/OS: Managing and Extending the Eclipse Environment
Disable known unsupported actions
Selecting this checkbox disables any actions a RAM reports as unsupported. For example, the sample
PDS RAM does not support the Check-out action. When you try to use this option, a message appears
stating that the particular action is not supported and disable the action from selection.
Custom parameter search order
Selecting this checkbox sets the order of where to look for values for custom parameters. When
a custom action is run that requires custom parameters, Developer for z/OS searches through the
metadata in an attempt to find values for the parameters. You can adjust the order of this search by
moving each metadata location up or down in the list using the buttons to the right. User Entered
values are values that are previously entered by the user on the same action but not necessarily on
the same member. For example, if User Entered was set at the highest level in the Custom Parameter
Search Order and Action 1 was called on Member 1 and then Action 1 was called on Member 2, then
the user entered values for custom parameters would be pre-filled in for the user to update, change,
or resubmit. A similar example of this is if Action 1 was called on Member 1 and then Action 2 was
called on Member 2 and Action 2 requests a parameter that is requested by Action 1, the values for
this custom parameter will not be pre-filled for the user.
Property Values are metadata, or member information, with the same name as the parameter. For
each CARMA member, there is a list of property values that are associated with the member. If a
custom action requests a parameter with the same name as a key in the property value list, then it will
automatically fill the custom parameter with the value associated with the key.
Finally, the Server Specified Defaults are the default values set up for the parameter in the VSAM
configuration files. These defaults are created when a custom parameter is created for use with a
particular custom action on some RAM.
Always prompt for parameter values
Selecting this checkbox shows the prompt to enter parameter values, even if the values have been
stored in the metadata from a previous call. When the checkbox is cleared, the first time a user calls
an action, the prompt to enter parameter values is shown, but for any subsequent call on the action,
the previously entered values are sent without prompting the user for updates.
Prompt for confirmation when deleting
Selecting this checkbox ensures that a prompt is shown to the user verifying that the delete was
intentional. When the checkbox is cleared, the prompt to verify with the user will not be displayed
Prompt for confirmation when moving project association to RAM
Selecting this checkbox ensures that a prompt is shown to the user when they do something that
would cause a local or z/OS project to be associated with multiple repository instances. When this
happens, the association changes from the original repository instance to the RAM itself. The prompt
notifies the user that the association is changing to the RAM and gives the user the option to cancel
the action and the change in association. Users can be notified of this association change as CARMA
actions can be called only against what a particular member or container is associated to, and
behavior can vary between a repository instance and a RAM. Clearing the checkbox turns off this
prompting.
Check for host modifications before replacing the member
Selecting this checkbox prompts the user if changes have occurred in the CARMA member before
checking it in. For example, if a CARMA member checked out to a local project has unchecked in
modifications and the version of the CARMA member in the repository has already been modified,
then when a user attempts to check in his or her changes to the CARMA member a notification is
displayed informing that the checked-out CARMA member is not the most up to date and checking in
changes might cause the already checked in changes to be lost.
Prompt for confirmation before overwriting members
Selecting this checkbox ensures that a prompt is shown to the user verifying that members will be
overwritten. When the checkbox is cleared, the prompt to verify is not opened.
Refresh affects only direct children
Selecting this checkbox only allows the refresh of CARMA containers and members to go one level
deep. Clearing this checkbox allows for a recursive refresh of the CARMA containers and members.
However, a recursive refresh is expensive and time consuming, so generally keeping the checkbox
marked is a good thing.

Extending product functions 131

 Show the resource display metadata in the CARMA view
Selecting this checkbox sets CARMA to display metadata, such as file extensions, in the CARMA view.
The metadata has to be downloaded from the RAM in order for it to be displayed which is what the
following two settings address. Clearing this checkbox keeps the metadata from downloading from
the host and as a result no file extensions are shown on CARMA members.
Retrieve the resource display metadata automatically
Selecting this checkbox sets CARMA to automatically download the metadata from the RAM for each
CARMA member and the file extensions show up automatically. For metadata to show up when
this checkbox is cleared, the user must select the CARMA member at least once at which time the
particular metadata is downloaded from the RAM.
Retrieve resource display metadata on containers
This setting is not available to mark if the checkbox, Retrieve the resource display metadata
automatically is not selected. Selecting this checkbox sets the metadata that is downloaded from
the RAM to be downloaded from the containers rather than each individual CARMA member. This ends
up grabbing a smaller amount of metadata from the host, and as a result all CARMA members contain
the same file extension and metadata that is associated with CARMA. The exception to this is when a
specific CARMA member has a different extension set and the metadata for that member is retrieved
separately, such as when a user views the member's properties.
Clear all CARMA 'do not show again' settings and show all hidden dialogs again
Selecting Clear resets all of the CARMA dialog windows that feature a 'do not show again' option. After
the settings are cleared, these dialog windows will be displayed again in the future.

Extending the CARMA plug-in

The CARMA plug-in has been designed for extensibility so you can easily add custom actions. By
extending the CARMA plug-in, you can use many of the built-in features of CARMA. Alternatively, you
can make use of only the core API functionality to develop your own user interface for accessing a CARMA
host.

For most purposes, extending the CARMA plug-in should be sufficient, which has the following
advantages over creating your own user interface:
• Dialogs automatically prompt the user for return values, custom parameters, and login information as
necessary.
• It features a built-in CARMA hierarchy navigator.
• You can easily provide access to custom RAM actions through menus with minimal effort.
If you would like to extend the CARMA plug-in and are new to Developer for z/OS plug-in development,
you may want to refer to the Eclipse Platform Plug-in Developer Guide. If you would instead like to create
your own user interface for CARMA using the core API, refer to the CARMA plug-in API specification.
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.
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.
Before you begin development, you should understand the architecture of CARMA. For additional
information, see “CARMA architecture” on page 133.

132 Developer for z/OS: Managing and Extending the Eclipse Environment
Related concepts
“CARMA architecture” on page 133
A CARMA system requires three components in order to function properly: a CARMA hierarchy, a CARMA
transport, and a CARMA host.

Client programmer's guide

The following topics provide information for the CARMA client programmer.
• “Concepts” on page 133
• “Tasks” on page 135
• “Reference” on page 137

Concepts
The following topics provide information about the Common Access Repository Manager (CARMA)
architecture and custom parameters.
• “CARMA architecture” on page 133
• “Dealing with custom parameters” on page 134

CARMA architecture
A CARMA system requires three components in order to function properly: a CARMA hierarchy, a CARMA
transport, and a CARMA host.
A CARMA hierarchy is a client-side data structure that provides support for CARMA content navigation
and the execution of CARMA operations. CARMA operation requests are sent via a CARMA transport to a
CARMA host. A CARMA transport is a client-side communication service between CARMA hierarchies and
CARMA hosts. CARMA hosts contain the host-side CARMA service, CARMA-390, which is responsible for
managing the available content.

Figure 2. Components of a CARMA system

CARMA hierarchy
A CARMA hierarchy is a special type of tree data structure that is used to manage CARMA content. Each
CARMA hierarchy is connected with exactly one CARMA transport and exactly one CARMA host (it uses its
CARMA transport to communicate with its CARMA host). The CARMA plug-in acts as a workstation client
and provides a graphical representation of CARMA hierarchies using the CARMA Repositories view. Each
top-level node in this view represents a CARMA hierarchy.

CARMA transport
The CARMA transport is a service plug-in forDeveloper for z/OS that manages the connection between a
CARMA hierarchy and its CARMA host. Thus, the CARMA transport packages send commands from the
CARMA hierarchy and returns responses from the CARMA host. The CARMA RSE transport is used for this
purpose by the CARMA plug-in.

CARMA host
A CARMA host is a host system that provides the CARMA-390 service. Each CARMA host generally has a
set of repository access managers (RAMs), which CARMA-390 uses to manage access to content.

Extending product functions 133

 Related concepts
“Extending the CARMA plug-in” on page 132
The CARMA plug-in has been designed for extensibility so you can easily add custom actions. By
extending the CARMA plug-in, you can use many of the built-in features of CARMA. Alternatively, you
can make use of only the core API functionality to develop your own user interface for accessing a CARMA
host.

Dealing with custom parameters

RAM developers have the ability to either customize existing CARMA actions or to create entirely new
actions. These actions can have custom parameters or return values as defined by the configuration of the
CARMA host.

There are several helper classes available so that you can easily make use of these custom actions:
CustomActionParameterManager
Queries the default, which is stored, and link values (retrieved in the order that is specified in the
CARMA preferences) against the metadata.
CustomActionParameterDialog
A convenience dialog that simply asks users to enter values for custom parameters.
CustomActionUtil
A helper class providing various convenience methods.

Using the custom action helper classes

The simplest way to obtain values for a custom parameter is to use one of the methods in
CustomActionUtil; for example, getCustomParameters:

[Link](resource, "101");

This retrieves the custom parameters for the action with an action ID of 101 for the given resource.
If you plan on using the same task repeatedly for different, but similar, resources, you can use
getCustomParametersForTask like so:

CARMAContent[] resources = getResources();

CarmaTaskMemento taskMemento = new CarmaTaskMemento();
for (int i = 0; i < [Link]; i++) {
[Link](taskMemento, resources[i], "101");
}

In this example, taskMemento is used to store information the user has entered for use between action
invocations. If taskMemento were not to be used here, the user would be queried with the same prompts
for every resource.
If you would rather use a different mechanism to fetch parameter values (such as a different user
interface), you could interact directly with the CustomActionParameterManager class, as illustrated in the
following example:

CustomActionParameterManager manager = [Link]();

Object[] paramsToPass = [Link](resource, actionId); // parameters to pass
to the command
//this method will tell us whether or not the manager has all the information it needs
if ([Link](resource, actionId)) {
final Action action = [Link](actionId);

Iterator parameters = [Link]().iterator();

//find the parameter you want to change this way, or look for it to be null in
paramsToPass
int index = 0;
while ([Link]()) {
Parameter param = (Parameter) [Link]();
if ([Link]().equals(targetName))
break;
index++;

134 Developer for z/OS: Managing and Extending the Eclipse Environment
 }

paramsToPass[index] = new Boolean(false);

//optionally store the parameter for later

Object[] paramsToStore = new Object[[Link]];
for (int i = 0; i < [Link]; i++) {
paramsToStore[i] = null;
if (i == index)
paramsToStore[i] = new Boolean(false);
}
[Link]([Link](), paramsToStore);
}

In this example, targetName is the name of the parameter as defined by the RAM developer.
Related tasks
“Contributing an action” on page 135
You can add an action to the CARMA Repositories view menu so that the action can be run on CARMA
resources.

Tasks
The following topics provide information about the contributing actions and creating CARMA connections.
• “Contributing an action” on page 135
• “Creating a CARMA connection programmatically ” on page 137

Contributing an action
You can add an action to the CARMA Repositories view menu so that the action can be run on CARMA
resources.

Before you can contribute a CARMA action, you must have the proper foundation for extending the
Developer for z/OS CARMA plug-in. Refer to the Eclipse Platform Plug-in Developer Guide for information
on how to begin developing a plug-in extension.
To contribute a CARMA action to the Developer for z/OS CARMA plug-in, follow these steps:
1. Update your [Link] file to use the [Link] extension point to define an
object delegate class for resources that implement either the IResource or CARMAContent interface.
Two common resource interfaces you might specify are IFile (which extends the IResource
interface) and CARMAContent. Specifying IFile as the resource object class causes your menu item
to appear on the menu in the Navigator view, on local project content, while specifying CARMAContent
as the resource object class causes your menu item to appear on the menu in the CARMA Repositories
view.
Example markup to add a menu item to the Navigator view:
You could include the following markup in your [Link] file if you were to define a menu item to
appear for files that are managed by CARMA in the Navigator view:

<extension point="[Link]">
<objectContribution
id="[Link]"
objectClass="[Link]"
adaptable="true">
<filter
name="projectPersistentProperty"
value="[Link]=[Link]">
</filter>
<action
label="ABC Action"
class="[Link]"
id="[Link]">
</action>
</objectContribution>
</extension>

Extending product functions 135

 Notice that the objectClass attribute of the objectContribution tag is specified to be
[Link], indicating that this menu item should appear on the menu
for the Navigator view. The id attribute of the objectContribution tag is simply a unique identifier
for your action. The specified filter tag limits the menu item to appear only for those files in the
Navigator view that are managed by CARMA. You can also add extra filter tags if necessary. Finally,
the action tag specifies the object delegate class in its class attribute.
Example markup to add a menu item to the CARMA Repositories view:
You could include the following markup in your [Link] file if you were to define a menu item to
appear for resources in the CARMA Repositories view:

<extension point="[Link]">
<objectContribution
id="[Link]"
objectClass="[Link]
adaptable="true">
<filter
name="repositoryManager"
value="My RAM">
</filter>
<action
label="ABC Action"
class="[Link]"
id="[Link]">
</action>
</objectContribution>
</extension>

Here, the objectClass attribute of the objectContribution tag is instead specified to be

[Link], indicating that this menu item should appear on the menu
for the CARMA Repositories view. Notice that a different filter is used in this example: This filter limits
the menu item to appear only for resources under a RAM named "My RAM". The name attribute of
the filter tag is used to specify the type of filter being applied. Refer to CarmaActionFilter for other
relevant values for the name attribute. Finally, the action tag specifies the object delegate class in its
class attribute.
2. Define your object delegate class by either implementing the IObjectActionDelegate
interface or extending CarmaObjectActionDelegate (a convenience class that implements the
IObjectActionDelegate interface).
It is recommended that your object delegate class extend CarmaObjectActionDelegate, since this
class contains many useful helper functions.
Example code for ABCDelegate:
You can use the following code as a starting point for developing your own object delegate:

public class ABCDelegate extends CarmaObjectActionDelegate {

public void run(IAction action) {

CARMAContent[] members = (CARMAContent[])
getSelectedCarmaResources().toArray(new CARMAContent[0]);

//perform task, schedule job, etc.

}

public void selectionChanged(IAction action, ISelection selection) {

[Link](action, selection);

//this is the ID assigned by the installation of the action

[Link](!isUnsupported("101"));
}
}

The first line in the run method above obtains an array of the selected CARMA resources, which you
can then use to perform your action. You might, for example, loop through all of the selected resources
and set certain metadata properties. Although you only really need to override the run method, you
may also find it useful to override the selectionChanged method to update the availability of your
action as shown in the example above.

136 Developer for z/OS: Managing and Extending the Eclipse Environment
 As defined in the example, selectionChanged uses the isUnsupported helper function of
CarmaObjectActionDelegate to enable the action with an action ID of 101 if the new selection of
objects supports the action. Although a value of 101 is hardcoded into the example code, it is possible
to resolve the action ID dynamically if the name of the action is known. Simply use the getActions
method of the appropriate RepositoryManager object to retrieve a list of the actions available for that
RAM, search through the list to find the appropriate action that is based on the name the action, and
then use the getActionId method to retrieve the action ID from corresponding Action object. You
might resolve the ID using this more dynamic method if you are unsure what the action ID of your
action is.
Related concepts
“Dealing with custom parameters” on page 134
RAM developers have the ability to either customize existing CARMA actions or to create entirely new
actions. These actions can have custom parameters or return values as defined by the configuration of the
CARMA host.

Creating a CARMA connection programmatically

CARMA connections are established during the creation of the root node of a CARMA hierarchy.
The root node of a CARMA hierarchy is a CARMA object, which must be configured to use a CARMA
transport during creation. To create a root node for a CARMA hierarchy and configure its CARMA transport,
follow these steps:
1. Use the factory class [Link] to create a CARMA object with the
getInstance method as illustrated in the following example code:

String identifier = "ConnectionIdentifier";

Map connectionProperties = new TreeMap();
// insert your code to configure the connection properties here
CARMA carma = [Link]().getCARMAInstance(identifier,
connectionProperties);

The identifier string must be unique to your CARMA hierarchy. Currently, the only valid transport is
the RSE transport service, which is used by default (if you are using the alternative method call that
requires a backend ID to be specified, you can select the RSE transport service by passing a backend
ID value of "[Link]").
The connection properties map stores key-value pairs for transport configuration options. If
the required parameters for the transport you are using are not specified in the map, the
getCARMAInstance method throws a CARMAException. The RSE transport service requires that
you specify a value for the key "aliasName" in the connection properties map. For the value of the
key "aliasName", provide a name for the RSE connection to use when communicating with the CARMA
host.
2. Store a reference to your CARMA hierarchy for later retrieval in the CARMA registry:

[Link]().addCarma(carma);

The singleton CarmaRegistry object is used by a CARMABrowser object to maintain a list of known
CARMA connections. Events are sent to registered listeners when objects are added or removed from
the CARMA hierarchy. You can retrieve a CARMA hierarchy from the CARMA registry by passing its
identifier into the getCARMA method of the CARMA registry.
You can now connect to your CARMA object's CARMA host by using the connect method.

Reference
The following topics provide CARMA reference information.
• Client API reference
• “Other reference information” on page 138

Extending product functions 137

 Other reference information
The following topics provide information on CARMA API rules of engagement and a mapping of which API
packages are found in which plug-ins.
• “API rules of engagement” on page 138
• “Map of plugins” on page 139

API rules of engagement

• Only the APIs exposed in the Javadoc reference are supported for programming unless otherwise noted
in the API documentation. The APIs in the Javadoc are stable and will not be removed across version
boundaries. CARMA APIs can be deprecated in future releases but should continue to be available and
usable by programmers in the future as defined by the documentation. Other APIs might be found in the
CARMA plug-ins but should be considered unsupported and subject to change in future releases.
• The CARMA model APIs ([Link] package) are meant to be read-only from the
programmer’s point of view, e.g., the programmer should not attempt to create/add/move items
in the CARMA model manually. The objects in the hierarchy are meant to be updated through the
refreshXXX() and createXXX() methods. Model object creation outside of using API methods is
not supported. If model objects are created outside of using API methods, then inconsistencies can
arise.
• All repository resource lists in the model are associated with a filter string. The default filter string is “*”.
• Most CARMA model methods require the connection to the CARMA host to be active when the method
is run. If the connection is not active, then a [Link] exception
is thrown.
• CARMA methods, which need to activate the CARMA host connection have an
[Link] parameter in the method signature. In order to
cancel execution of the method, we respect the [Link]() method, which
is checked during long-running method execution.
• The CARMA model serves as a cache of data for the CARMA hierarchy. It is the responsibility of the
programmer to keep the cache fresh using the refreshXXX() methods on the model.
• The CARMA model cache must be initialized. If a portion of the CARMA hierarchy which is not cached
is accessed, then a [Link] is thrown. To repair
the exception, run a refreshXXX() method on the object.
• The objects in the CARMA Model cache are available when disconnected from the CARMA host. The
CARMA host needs to be actively connected in order to run methods against the cache objects, which
access the CARMA host.
• Model changes are communicated out to listeners via notification. The notification goes out to any
adapter listening to the model object. Listeners should be added to the model using a class which
extends [Link]. This is an Eclipse Modeling Framework
(EMF) notification method. Reference the EMF documentation for more information on adapter
notification.
• The default CARMA UI (including the externalized [Link].* APIs) use a combination
of actions and jobs to run methods on the CARMA model. The Action (extending
[Link] or [Link]) is responsible for gathering
the needed data to run the model method. The gathered data is handed off to a CARMA UI job, which is
scheduled to run in the background when resources are available. If the model method cause updates
to the CARMA hierarchy then notifications are sent from the model to listeners, which update the UI as
needed.

138 Developer for z/OS: Managing and Extending the Eclipse Environment
 Map of plugins
The CARMA Plug-in API is divided into a series of plug-ins. The following table shows which API packages
are found in which plug-ins. This table is useful for determining which plug-ins a given plug-in should
include as prerequisites.

API Package Required plug-in Id Notes®

[Link] These are the main CARMA API
[Link]
packages that are used in talking
[Link]
to the CARMA host
[Link]

[Link][.*] [Link] These packages are useful for

working with CARMA objects in
an eclipse UI

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 [Link] 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.
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.

Extending product functions 139

 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.
Return to the exercise summary for steps on how to determine if your CARMA plug-in ran successfully.

140 Developer for z/OS: Managing and Extending the Eclipse Environment
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 [Link] file to provide the [Link] 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: [Link]
• ID: [Link]
• Name: Decorators
To create the icons folder and import the graphics:
1. In the Package Explorer view, right-click on the [Link] plugin-
project you created, and select New > Folder.
2. In the New Folder dialog box that opens, select [Link] 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 [Link] 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.
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.

Extending product functions 141

 In the Package Explorer view, expand [Link] >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
[Link] > src > [Link], and
double-click on the [Link] 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 [Link];
import [Link];
import [Link];

4. Save the [Link] 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
[Link] 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:
• [Link]
• [Link]
• [Link](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
[Link] 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.
7. Right click the decorator package you created, and select New > Class.
8. In the Name text field, enter Decorator.

142 Developer for z/OS: Managing and Extending the Eclipse Environment
 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 [Link] 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 = [Link]("icons/[Link]");
question = [Link]("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([Link]())
{
try
{
EMap myMap = [Link]();
if([Link]("locked"))
{
String value = [Link]("locked").toString();
if( ![Link](""))
{
[Link](lock);
if(myResource instanceof CARMAMember)
[Link](" - (Member Locked)");
else
[Link](" - (Container Locked)");

Extending product functions 143

 }
}
}
catch(NotSynchronizedException e)
{
//TODO handle exception
}
}
else
{
[Link](question);
[Link](" - (Not Syncronized)");
}
}
}

3. Automatically import the classes and types.

Ensure that the following imports are included:

import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];

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

Lesson 5: Modify the [Link] file

In this lesson, you modify the [Link] file to provide the [Link] extension
point and attributes.
To modify the [Link] 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 [Link] 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 [Link] 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 [Link] tab from the bottom
menu of items. You might have to select the >> button to make this option visible. The [Link]
file should open in the Plug-in Editor.
6. The following skeleton code is provided already:

<plugin>
<extension
point="[Link]">
</extension>
</plugin>

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

<description
adaptable="true"
class="[Link]"
id="[Link]"
label="Sample Decorator"
lightweight="true"
location="BOTTOM_RIGHT"
state="true">
</description>
<enablement>
<or>

144 Developer for z/OS: Managing and Extending the Eclipse Environment
 <objectClass name="[Link]"/>
<ObjectClass name="[Link]"/>
</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.
Note: Before you complete this lesson, you should create an Eclipse plug-in project with the following
attributes:

Extending product functions 145

 • Project Name: [Link]
• Plug-in ID: [Link]
• 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, [Link] 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 [Link] 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
[Link] 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.
b) The values available for state correspond to the three states that these actions can be in:
enabled, disabled, and hidden.

146 Developer for z/OS: Managing and Extending the Eclipse Environment
 8. With the first action item under the RAM highlighted, use the dropdown actionId menu to
select: [Link]. 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
[Link]. 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
[Link]. 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

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:

Extending product functions 147

 • Project Name: [Link]
• ID: [Link]
• 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 [Link],
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, [Link]
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 [Link] 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 [Link] > src >
[Link]. Double-click on the [Link]
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 = [Link]();
[Link]("[Link]",
"[Link]",
[Link]);
}

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

[Link]("ramId",
"[Link]",
[Link]);

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.

148 Developer for z/OS: Managing and Extending the Eclipse Environment
 Ensure that the following packages were imported, add any to the import commands at the top of the
Activator class if necessary:

import [Link];
import [Link];
import [Link].*;

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:
• Project Name: [Link]
• ID: [Link]
• Name: Browse Menu
To create the BrowseMemberAction Java class:

Extending product functions 149

 1. First, you want to set up the dependencies that are associated with this plug-in project. In the
Package Explorer view, right click [Link], 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:
• [Link]
• [Link]
• [Link]
• [Link]
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
[Link] > 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 [Link] > 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:

public void selectionChanged(IAction action, ISelection selection) {

Iterator i = ((IStructuredSelection) selection).iterator();

// by default assume false

[Link](false);

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

return;

150 Developer for z/OS: Managing and Extending the Eclipse Environment
 }

while ([Link]()) {
Object next = [Link]();
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
[Link] = (CARMAMember) next;
} else {
[Link] = null;
return;
}
}

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

[Link](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 ([Link] != null) {
//Get the name of the CARMA Member
String memberName = [Link]();

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

//local cache of the file
IWorkspace myWorkspace = [Link]();
IWorkspaceRoot myRoot = [Link]();

IProject myResource = [Link]("/BootCampTemp");

//If the temporary directory that holds the temporary files

//does not exist create it
if( ![Link]() ){
try{
[Link](new NullProgressMonitor());
} catch(Exception e){
[Link]();
}
}

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

//open it
if( ![Link]()){
try{
[Link](new NullProgressMonitor());
} catch(Exception e){
[Link]();
}
}

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

//Create the IFile in the temporary location

final IFile myFile = [Link](new Path(memberName));

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

//Run the Job

[Link]();

Extending product functions 151

 try{
InputStream myStream = null;
while( (myStream = [Link]()) == null){
}

//Copy the contents into the IFile

if(![Link]())
[Link](myStream, true, new NullProgressMonitor());
} catch(Exception e){
[Link]();
}

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

Display display = [Link]();
[Link](new Runnable() {
public void run() {
IWorkbenchPage page =
[Link]().getActiveWorkbenchWindow().getActivePage();

try {
ResourceAttributes myAttributes = [Link]();
if(myAttributes == null){
myAttributes = new ResourceAttributes();
}
//setting the attributes to readonly
[Link](true);
try{
[Link](myAttributes);
} catch(Exception e){
[Link]();
}
//opening the file in browse mode
[Link](page, myFile, true);
} catch (PartInitException e) {
//TODO handle exception
[Link](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 [Link];
import [Link];

import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];

import [Link];
import [Link];

5. Save the source and debug any errors.

152 Developer for z/OS: Managing and Extending the Eclipse Environment
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, [Link] 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 [Link] tab from the menu options at the bottom of the Plug-in Editor.
6. Replace the existing code with the following:

<plugin>
<extension
id="[Link]"
point="[Link]">
<objectContribution
id="[Link]"
objectClass="[Link]">
<action
class="[Link]"
id="[Link]"
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
• Create Java classes to implement the enhanced functionality offered by the plug-in
• Run and debug the plug-in project

Extending product functions 153

 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: [Link]
• Plug-in ID: [Link]
• Plug-in Name: New View
To perform the setup for this plug-in:
1. In the Plug-in Development perspective, right-click on the [Link] 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:
• [Link]
• [Link]
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 [Link], 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 [Link] 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 [Link], 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.
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.

154 Developer for z/OS: Managing and Extending the Eclipse Environment
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,
[Link] > 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);
[Link](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 [Link];
import [Link];

import [Link];

import [Link];
import [Link];

import [Link];
import [Link];

5. Save your changes and debug any errors.

Extending product functions 155

 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:
[Link]. When it appears, select it, and click OK. You should see the extension
that is listed in the left panel.
7. Open the [Link] tab from the bottom menu of tabs. Configure the [Link] file as follows:

<plugin>
<extension
point="[Link]">
<category
name="BootCamp"
id="[Link]">
</category>
<view
name="CARMA Developer View"
icon="icons/[Link]"
category="[Link]"
class="[Link]"
id="[Link]">
</view>
</extension>
</plugin>

Note: The attributes that are used in the [Link] 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.
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.

156 Developer for z/OS: Managing and Extending the Eclipse Environment
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 [Link] 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, [Link] 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
[Link] > src > [Link], 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)

{
return imageDescriptorFromPlugin(PLUGIN_ID, path);
}

Extending product functions 157

 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
[Link];. Save and debug any errors in the source.
4. Next, you want to create the CustomLabelProvider class. In the Package Explorer view, expand
the [Link] 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
[Link] > 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 = [Link](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.

158 Developer for z/OS: Managing and Extending the Eclipse Environment
 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 = [Link]("icons/[Link]");
return [Link]();
}
}
return [Link](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 [Link];

import [Link];
import [Link];

import [Link].*;
import [Link].*;

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
[Link] 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);
[Link](new CustomLabelProvider());
return viewer;
}

3. Save the source and debug any errors.

Extending product functions 159

 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 [Link] 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.

160 Developer for z/OS: Managing and Extending the Eclipse Environment
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 [Link];

import [Link];
import [Link];

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 = [Link](parent);

//Do not parse non-existant children

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

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

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

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.

Extending product functions 161

 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());
[Link](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

162 Developer for z/OS: Managing and Extending the Eclipse Environment
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 [Link] 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
[Link] 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)

{
[Link](menu);
IContributionItem[] myItems = [Link]();
for(int i = 0; i < [Link]; i++)
{
IContributionItem item = myItems[i];
if([Link]() != null)
{
if([Link]().equals([Link]) ||
[Link]().equals("[Link]"))
{
[Link](item);
}
}
}
}

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

import [Link];
import [Link];

import [Link];
import [Link];

Extending product functions 163

 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 [Link] 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);

[Link](new Separator("open"));
_openActionGroup.setContext(myContext);
_openActionGroup.fillContextMenu(menu);

[Link](new Separator("refractor"));

[Link](new Separator("connect"));

_connectionActionGroup.setContext(myContext);

164 Developer for z/OS: Managing and Extending the Eclipse Environment
 _connectionActionGroup.fillContextMenu(menu);
_connectionActionGroup.updateActionBars();

[Link](new Separator("display"));

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

[Link](new Separator(IWorkbenchActionConstants.MB_ADDITIONS));
[Link](new Separator("project"));
[Link](new Separator("properties"));
[Link](_propertyAction);
}

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

import [Link];
import [Link];
import [Link];
import [Link];
import [Link];

import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];

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 [Link]; 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.

Extending product functions 165

 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.

166 Developer for z/OS: Managing and Extending the Eclipse Environment
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

Extending product functions 167

 • 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.#[Link](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.#[Link](CRA$VSTR) to
REPRO FEL.SFELVSM2(CRA0VSTR).

168 Developer for z/OS: Managing and Extending the Eclipse Environment
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
[Link](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 [Link](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.

Extending product functions 169

 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: [Link]
• ID: [Link]
• Name: HowTo Action
1. Open the Plug-in Manifest Editor by right-clicking on the [Link] 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 [Link] 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:
• [Link],
• [Link],
• [Link]
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 [Link] 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 [Link] 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
[Link] 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, [Link].
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,
[Link]. You create this class
later in this exercise.

170 Developer for z/OS: Managing and Extending the Eclipse Environment
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 [Link] 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
[Link] plug-in project open.
2. On the Extensions page, select the (actionValidator) option below the
[Link] 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,
[Link].
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,
[Link]. 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 [Link] 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 [Link] plug-in project open.
1. On the Extensions page, select the (customParameterControl) option below the
[Link] extension point. To the right you see the
Extension Element Details listed.
2. In the uniqueId text field, enter [Link] for the Sample PDS RAM.
3. In the class text field, enter [Link].
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.

Extending product functions 171

 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
[Link] plug-in project, and select New > Package.
2. In the New Java Package dialog box that opens, enter [Link] 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 [Link] 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 [Link] 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 [Link] 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
[Link] > src > [Link] 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

172 Developer for z/OS: Managing and Extending the Eclipse Environment
 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([Link]() > 0)
[Link] = ([Link]("[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([Link]("0"))
{
//Display informational message.
[Link] = [Link];
[Link] = "You entered a 0!";
}
else if([Link]("1"))
{
//Display a warning message
[Link] = [Link];
[Link] = "Values greater than 1 will result in an error!";
}
else
{
//Display an error message.
[Link] = [Link];
[Link] = "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
[Link] > src > [Link] 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

Extending product functions 173

 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([Link]().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 : [Link]())
{
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) [Link](string1Param);
boolean string1IsThere = !(string1Val == null || [Link]() == 0);

//Retrieve the parameter value for string2, and determine if there was input
String string2Val = (String) [Link](string2Param);
boolean string2IsThere = !(string2Val == null || [Link]() == 0);

//Determine if both string1 and string2 are provided.

//Returns an error message.
if (string1IsThere && string2IsThere)
{
[Link] = [Link];
[Link] = "Provide either String1 or String2.";
}

//Determine if neither string1 nor string2 is provided

//Returns an info message.
else if(!string1IsThere && !string2IsThere)
{
[Link] = [Link];
[Link] = "Enter a value for String1 or String2.";
}

return result;
}

4. Save the source and debug any errors.

174 Developer for z/OS: Managing and Extending the Eclipse Environment
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
[Link] > src > [Link] 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, [Link]);
[Link]("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([Link]())
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 [Link];
import [Link].*;

Extending product functions 175

 import [Link].*;

import [Link];

7. Save the source and debug any errors.

Your completed code for the CheckBoxOptionControl should look like:

package [Link];

import [Link];
import [Link].*;

import [Link].*;

import [Link];

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, [Link]);
[Link]("Check me!");
return theButton;
}

@Override
public Object getValue() {
if([Link]())
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.

176 Developer for z/OS: Managing and Extending the Eclipse Environment
 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.

CARMA RAM (host) Developer's Guide

The following topics provide information on CARMA API rules of engagement and a mapping of which API
packages are found in which plug-ins.
• “Defining criteria for CARMA compare” on page 177
• “Introduction to CARMA” on page 0

Defining criteria for CARMA compare

CARMA has the ability to compare (associated) resources in the Developer for z/OS workspace (for
example, local or remote projects) with resources in a CARMA RAM. This is useful for determining what
changes have been made to the workspace files before checking the changes into CARMA.
CARMA stores the current criteria values when it downloads a resource into the workspace. Based on
criteria value and workspace changes CARMA can determine what changes have been made to the
version in the RAM and indicate what direction changes should be moved. For example, CARMA can
determine whether a workspace file has been updated locally, in the RAM, or both. Based on the change
information CARMA can indicate what portions of the file that is changed and indicate where changes
should be uploaded to the RAM, copied from the RAM, or if a merge needs to occur because changes have
occurred in the workspace and the RAM.
In order to perform the compare in a flexible manner, CARMA has provided a Compare Criteria
configuration file – [Link]. This syncConfig file is placed in the RSE configuration directory*
and automatically picked up by CARMA when RSE starts**.
The compare configuration file allows the RAM developer to specify a variety of criteria for comparison on
a RAM-by-RAM basis. An example of a compare configuration file is:

<?xml version="1.0" encoding="UTF-8"?>

<CARMACompare xmlns="[Link]
<RAMCompare ramId="00">

<memberinfo key="Last Modified Date" type="date" format="MM/DD/YY"/>

<memberinfo key="Last Modified Time" type="date" format="HH:MM"/>
<memberinfo key="Last Modified Seconds" type="int" />
</RAMCompare>
<RAMCompare ramId="01">
<content />
</RAMCompare>
</CARMACompare>

The XML document must begin with a CARMACompare element. The CARMACompare element can contain
1 or more RAMCompare elements. Each RAMCompare element specifies the comparison criteria for a

Extending product functions 177

 single RAM. The RAM that the criteria apply to is denoted by the ramId attribute. The ramId value should
match up with the RAM id in the CARMA VSAM configuration and is a 2-digit number. 0 s are required to
be added to the beginning of the Id value if the Id is fewer than 2 digits.
Note: You can identify a RAM using either the ramId or uniqueId. If you know the particular ID for
the RAM, use the ramId. If you know the RAM, but do not know the ramID associated with it, use the
uniqueId.
The example above defines compare criteria for 2 RAMs, 01 and 02. Each RAMCompare element contains
the criteria for the RAM. Currently, the criteria available for checking include:
• Member information
• Member contents
Member information
The configuration can define 1 or more memberinfo elements for each RAMCompare. The member
information elements are concatenated together to form a comparison. The member information element
contains a key, type, and optional format attributes. Currently, the type and format attributes are
ignored but an explanation of usage is included. The keys are currently compared directly for string
equivalence.
Key attribute
The key attribute references a member information item that is found in the properties for a resource.
The key attribute should match the key that is returned by the RAM for the resource.
Type attribute
The type attribute specifies how the key value should be treated. The type attribute can be set to
one of the following:
• int
• string
• float
• date
The type defines how the member information should be compared. For example, using the following
criteria

<memberinfo key="Last Modified Seconds" type="int" />

A member information value of 0001 would be equal to 1.

Format attribute
The format attribute is only required for elements that specify a type of “date”. The format attribute
allows the criteria to define how the date value should be parsed and compared. For example, using
the following criteria:

<memberinfo key="Last Modified Time" type="date" format="HH:MM"/>

A member information value of 1:10 PM would be equivalent to 13:10.

Member Contents
The configuration can define one content element for each RAMCompare. The contents element indicates
that CARMA should inspect the byte contents of the resource for changes.
Note: This requires that the entire file is downloaded to the workspace to perform the comparison.
The file contents are downloaded to the workspace and a file hash (MD5) is performed on the file
contents. If the file contents hash differs from the workspace file hash, then a difference is indicated.
Default Compare Criteria
If a RAMCompare element is not defined for a RAM that CARMA is working with, a default compare
criteria set is used. The default compare criteria first looks to see whether a [Link] member
information key is defined for the resource being compared. If the [Link] key is available,

178 Developer for z/OS: Managing and Extending the Eclipse Environment
the single key value is used as the compare criteria. If a [Link] key is not available, then the
comparison is performed based on member contents.
Note: * Please refer to the IBM Developer for z/OS Host Configuration Guide (SC27-9933) for more
information on the RSE configuration directory.
Note: ** The compare configuration file is only picked up when RSE starts. In order for changes to be
detected disconnect RSE and reconnect.

Extending product functions 179

180 Developer for z/OS: Managing and Extending the Eclipse Environment
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 ipemail@[Link].
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
ipemail@[Link].
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 181

 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 [Link] 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 [Link]/legal/[Link].

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.

182 Developer for z/OS: Managing and Extending the Eclipse Environment
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 183

184 Developer for z/OS: Managing and Extending the Eclipse Environment
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) [Link], the RSE encrypted communication, RSE -
[Link], 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 185

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

186 Developer for z/OS: Managing and Extending the Eclipse Environment
• 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 187

188 Developer for z/OS: Managing and Extending the Eclipse Environment
IBM®

Product Number: 5755-A05

5724-T07