the carma interface

IDz and CA-Endevor

The CARMA InterfaceChris Sayles: [email protected]

Joel Duquene: [email protected]

Jon Sayles: [email protected]

RDz ➔ IDz ➔ ADFz

©

August, 2019

mailto:[email protected]



Notices and Disclaimers

Copyright © 2019 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission

from IBM.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM.

Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of

initial publication and could include unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS

DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE

USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT OR LOSS OF OPPORTUNITY.

IBM products and services are warranted according to the terms and conditions of the agreements under which they are provided.

Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice.

Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those customers

have used IBM products and the results they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary.

References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in

which IBM operates or does business.

Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials

and discussions are provided for informational purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant or

their specific situation.

It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and

interpretation of any relevant laws and regulatory requirements that may affect the customer’s business and any actions the customer may need to take to comply with such

laws. IBM does not provide legal advice or represent or warrant that its services or products will ensure that the customer is in compliance with any law

1

Course Pre-Requisites and Topics

This course assumes that you have:– Have completed basic IDz education

– Understand basic IDz terms and concepts, including:

• View, Perspective, other terms & vocabulary

• Navigation using the “Context Menu”

– Worked with Endevor for at least 6 months

– Understand basic CA-Endevor terms and concepts, including:

• Element

• Package

– Understand CA-Endevor Functions, including:

• Casting packages

• Generating Elements

2

Course Topics - Disclaimer

This course covers the basics of accessing CA-Endevor within IBM Developer for z

Systems (known from this point on as IDz). The depth of functionality taught in this

class is such that, upon completion, you should be able to complete basic Endevor

development tasks using IDz’s CARMA/Endevor interface

There exist CARMA functionality not covered in this class that will be taught in

advanced technique classes in the future.

If there are features/techniques you would like to learn about that are not covered in

the material feel free to send a note to your IBM technical representative – or if

you’re not sure who they are, to: Chris Sayles: [email protected]

3


IDz CA-Endevor Integration

1) CARMA Terms and Concepts

• CARMA

• CARMA Ram

• CARMA View

• Element support

• Package Support

2) Connecting to a Repository

3) Displaying Elements and Views

4) Working with Elements

4

What is CARMA?

• View lists of Elements or

packages

• Set up filters to narrow

down the content

selections

• Primary interface to take

action on Endevor content

CARMA (Common Access Repository MAnager) is IDz’s gateway into CA-Endevor,

allowing you to access and work with Elements, packages, and do your daily tasks.

<Demo Server>

5

What is a CARMA RAM?

RAM stands for “Repository Access Manager”.

You communicate to the host using the

CARMA infrastructure and it is where you find

Endevor Elements and packages.

There are two types of RAM’s, or Repository

Access Managers in CARMA:

• CA Endevor Packages RAM

• Repository Access Manager used

specifically for Endevor package

support

• CA Endevor SCM RAM

• Repository Access Manager used

specifically for working with

Elements.

For each CARMA connection, there may be

multiple repository connections CARMA RAMs

<Demo Server>

6

CA Endevor SCM RAM {SYS:TRAIN*}

expanded to view Elements under

STUDTEST Environment >

TRAINING System >

TEST Stage >

COURADMN Subsystem

IDz/Endevor Functionality and Support

• Filter and search through environments, systems, subsystems, Elements, and stages based

on queries

– Filters saved across z/OS sessions for easy access to common searches and Elements

– Drill down into subsystems

• Retrieve Elements to z/OS projects

– Access to typical IDz functionality such as syntax check, content assist, debug, etc.

• ADD/UPDATE Elements with single click

– IDz remembers Endevor location for retrieve and add back

• Enhanced Edit Elements from Endevor

• Integration with existing GENERATE configuration

• Support for Endevor PACKAGE actions

7

CARMA Views – 1 of 3

There are three CARMA Endevor views: 1. Repository view, 2. Field view and 3. History view.

1. CARMA Repository – Lists all Endevor Elements associated with their location

CARMA Repositories

CARMA Repository Connection

This is the view you will

be doing most of your

work in, i.e. accessing

Elements,

editing/casting

packages, etc.

8

CARMA/Endevor SCM {}

9

Drill-Down

CARMA will detect your shop's

Endevor Repository design, and will

display the hierarchy structure by:

Environment

System

Stage

Subsystem

Type

Element(s)

Elements are contained within Environments,

Systems, Stages and Subsystems

<Demo Server>

You can Browse an

Element – directly from

the Repository viewEle

me

nts

CARMA Repository view

10

CARMA Fields View

2. CARMA Fields View – Displays expanded Element details in list format.

CARMA Fields View

This view is customizable in terms of the information displayed.

Customization will be covered later on in the course.

11

CARMA History View

3. CARMA History – Provides the full Endevor History version list when an Element is selected.

CARMA History View

Version Version info

12

CARMA/Endevor Context Menu Options

There are a number of common actions that contained within the Context

menu, including but not limited to:

• Adding Elements

• Generating Elements

• Retrieving Elements

• Casting/defining packages

Two common CARMA/Endevor submenus are:

1. Custom: This contains most of the above functions, with the addition of

functions like Backout Package, Move Element, etc.

2. Extract to: Extract Elements to IDz Subprojects & Libraries13

Endevor Context Menu Options

From CARMA views or retrieved

Elements in subprojects:

• Right click and choose either

Custom or Extract to… (covered in later module)

• Choose from the subsequent list

of actions

14

Review – CARMA and IDz

• CARMA = IDz’s window into Endevor

• Endevor Support/Functionality

– Filtering – For searching Endevor for assets/Elements

– Element support – Display, Add/Update, Retrieve, Enhanced Edit, etc.

– Package support – Display, Create, Cast, etc

• CARMA Views

– CARMA Repositories

– CARMA Field

– CARMA History

• Context Menu Options

– Custom submenu

– Extract to… 15

Connect to a Repository

IDz Listener

Started Task

z/OS LPAR

IDz Client SoftwareEndevor Repository

• Environment

• System

• Subsystem

• Element

• Element

• Element

• Element

• …

Connect to Endevor Repository

thru IDz Listener

16

Connecting to Endevor 1 of 4

Open the CARMA Repositories view:

17

Window >

Show View >

CARMA Repositories


The CARMA Repositories view opens. Repositories for each configured connection will appear in the view

The connection shown in this example is a generic training LPAR.

In a full/production-scale implementation of the CARMA/Endevor

interface, there can/will be more connections to more LPARs

available depending on the architecture at your shop.

LPAR

Packages (RAM)

SCM (RAM)

18

Right-click on the Repositories connection, and

select Connect ➔


19


Once connected, expanding the CA Endevor SCM repository will show subfolders which display

Environment, System, and Stage

Expand folders to drill down into Elements

contained within each Environment/System/Stage

Endevor SCM Repository

Environment/System/Stage folders

20

In this section you learned how to:

- Connect to a CARMA Repository

- Explore the CA Endevor SCM RAM

- Drill down to the Element level within subfolders:

Environment

System

Stage

Subsystem

Type

Element

Note that you can use "Change view" to isolate your

work to specific Endevor Repository elements

Connecting to Endevor Review

21

Organizing Element Views

22

In this section, you will learn how to create CARMA filters.

Like MVS File Filters in Remote Systems, CARMA Filters allow

you to organize your files using manageable subsets

CARMA Filters are sometimes referred to as "views" - and they

allow you to access Elements and even Search on, by Endevor:

• Environments

• Systems

• Stages

• Subsystems

CARMA Organize Elements 1 of 5

Organizing your CA Endevor Elements for easy access is often done using

search strings organized within filters. These filters are called “Views” in

CARMA terminology.

To create a new CARMA “View”

Right click on Endevor SCM and select:

New >

→ View

23


The New View dialog appears

2. Enter search strings (filter

values) in the View String boxes

and click Finish

Example: TRAIN*

24

TRAIN*


Expand the new Filter to access the Endevor resources returned

through the Filter:

Folders/subfolders

containing Elements

New CARMA View

25

Right-click on the View and select

Properties to change the Filter criteria


Drilling down to the Subsystem level shows

all Elements organized by type

IDz adds workspace extensions based on

the low-level qualifier (Workstation File Extension)

Example: Show Copybooks through a New

View

Expand View (SYS:TRAIN*) >

Expand COURADM{*} folder >

Expand COBCOPY {*} folder26

*.cpy

<Demo Server>


When an Element is selected in the CARMA repository

tree, the Element’s properties are shown in the

Properties view

27

CARMA Display Elements

• In this section we created a new CARMA “view” used to organize/filter

Elements scoped by a search string specified in the creation of the

view.

• We also utilized the IDz Properties view to see specific information

about Elements that were found within the “view” that was created.

28

Working with Elements

IBM Developer for z Systems

&

CA Endevor

29


CARMA Terms and Concepts

Connecting to a Repository

Displaying Elements and Views


Working with Packages

30


In this section we will learn how to:• Search for an Element

• Browse an Element

• Retrieve an Element

• Extract an Element to a remote subproject

• Use IDz’s “Enhanced Edit” functionality

• Show dependencies

• Compare Elements

• Show history files

31

Searching for an Element

When searching for an Element, we can

take advantage of IDz’s built in Search

Functionality which contains a search

tab called Endevor Search

This gives us options that we would

normally see when searching for an

Element, such as Environment, System,

Subsystem, Type, Element, and so on.

32

Accessing the Endevor Search option

To begin our search, right-click on the

CA Endevor SCM Ram >

Choose Search from the context menu

33

Search options

Once you choose search from the

context menu, the search dialog

box will pop up. From this box

you’ll enter in your search criteria

and hit Search.

Search results are presented in a

separate view.

34

Search view

35

From this search menu, you can use the context

menu to access functionality relevant to your tasks.

Search view – Additional options

Create a

CARMA view

from the

search filter

Export search

results to a

.CSV file

Show

previous

searches

36

Show Previous Searches

When we choose “show previous

searches”, we get a short-list of the

most recent searches and the option

to view history and clear history.

If you choose to

view history, the

history dialog will

show like this:

37

Customizing the Search View

If you want to customize the information that displays in the

search view, click on the drop-down menu icon ( ) in the

upper right-hand corner of the Search view.

The menu will allow you to choose

which columns will show in the view.

You can then organize the information

ascending and descending by clicking

on the column header.

38


Once you’ve navigated to – or searched

to the files you’re interested in, you can

access Element for browsing and editing.

Within the CARMA Repositories view, we

will drill down into the folder containing

an Element for browse or edit using

techniques found in this section.

39

Browsing Endevor Elements – Steps

Double-Click the Element

you would like to browse BETRB002

40

Notes:

• The default action in this workflow is to browse – not retrieve an Element for edit.

• In an upcoming section we will show you several ways of editing Elements.

Browsing Endevor Elements – 2 of 2

When double

clicked, the

Element will open

in the IDz editor

view in Browse

mode

41

Retrieving Endevor Elements – 1 of 4

Once you have browsed an Element and identified a

change to be made, it’s time to retrieve the Element.

From the expanded CARMA

Repositories view:

Right click on the Element >

Custom >

Retrieve Element

To retrieve an Element:

42

Retrieving Endevor Elements –

2 of 4

A dialog box will pop up allowing you to

specify qualifying retrieval information

such as:

• Element Name

• Version information

• Environment/system/subsystem

information

• CCID

• CCID values

43


Specify the target Dataset name to

retrieve the Element and place it in the

Dataset specified in Remote Systems

Retrieved

Element

Destination

44


Once retrieved, double click the Element in Remote Systems view to open it in

edit mode

The Element will open in

the System Z LPEX editor

view as shown here…

45

Adding an Element – Overview

Adding an Element to the repository is a four step

process in which you:

1. Go to the context menu to access the functionality

2. Specify parameters

3. Add the Element

4. Refresh the CARMA view to confirm that the Element has

been added.

46

Adding an Element – 1 of 4

To Add an Element:

• Right click over the

subfolder that you

would like the

Element to be

added to

• Choose Custom

• Add Element

47


• When the Add Element Dialog

pops up, enter parameters as

necessary, making sure to

specify (at minimum) required

fields such as:

– Element name

– Source data set name

– Source PDS member name

48

Adding an Element 3 of 4

Once added, a Results for Add Element box will pop up showing any error messages,

reason codes, and return codes. If something went wrong during the add Element

procedure, your error information will be displayed here.

Click OK to proceed to the last step.

49


Finally, right click over the Element’s destination folder in the CARMA view and select

Refresh (F5). This refreshes the filter and confirms that the Element was added.

• In this example, the Element COPYBOOK.CPY was added to the Subsystem folder ACCTPAY (SUBSYS:ACCTPAY)

50

Adding an Element Review

In this section, we went over how to add an Element through IDz’s

context menu.

• Custom > Add Element

• Specify information in the dialogs

• Viewing the new Element in CARMA Repositories view

51

Extracting Elements to Remote Subprojects

Another means of editing Elements is to extract them to Remote subprojects, otherwise known as MVS Subprojects. When using this feature, you have the choice to either:

A. Extract an Element to a new Remote (MVS) Subproject**

OR

B. Extract an Element to an existing Remote Subproject

52

** If you’re not sure what an MVS Subproject is, Module 7 from the Entry-Level training curriculum

discusses this feature: https://www.ibm.com/developerworks/community/files/app#/file/bb436b92-30e0-47eb-b104-4c083d767f5e

https://www.ibm.com/developerworks/community/files/app#/file/bb436b92-30e0-47eb-b104-4c083d767f5e

Extract to Remote Project – 1 of 5

To edit an Element via this

method, right-click the Element

and:

Extract to… > Remote Project

53

Extract to Remote Project –

2 of 5

From the dialog the New MVS

Subproject dialog, name your new

subproject and either:

– Select an existing property group

– Create a new property group

– Create the subproject without assigning

a property group

Upon completion, click Finish.

54


Choose the target location of the

source folder where you want to

extract your Element to on the host.

– This will tell Endevor where to retrieve

your Element to under the covers

– Make sure to specify a PDS that you

would normally check out source into

Once finished, click Next.

55


The Retrieve Element

dialog will pop up

–Enter information for the

Element you’ve chosen

–Once finished, click OK.

56


The Element will appear in the z/OS Projects view

under the MVS Subproject that was created. This

allows you to work with the Element in edit mode

using the LPEX or COBOL editor.

57

Extract to Remote Project

In this section, we discussed the process of

extracting an Element to a Remote Subproject by:1. Using the context menu option Extract to… Remote project

2. Creating a new remote project

3. Assigning assets/Elements to the subproject

4. Opening the assets/Element in the LPEX editor

58

IDz/Endevor “Enhanced Edit”

In this section, we will look at the IDz/Endevor function of “Enhanced Edit”.

This function allows on-the-fly editing of Elements without having to go through a retrieval or extraction process, making quick editing, abend support, and many other use cases centered around making quick changes much more accessible.

Notes:

• Computer Associates call this functionality: “Quick Edit”59

IDz/Endevor “Enhanced Edit” – 1 of 4

- Right click the Element on which to

perform an “Enhanced Edit”

- Select Edit

This will start the “Enhanced Edit”

retrieve and edit function.

60


The Edit Element dialog will

come up just as it would in

TSO/ISPF.

Fill out the necessary

information and click OK.

61


The Element is opened for edit ➔

62


When you have completed

your edits, use Ctrl+S to

save the Element.

When you do that, the

Add/Update Element

dialog will pop up.

Fill in the necessary

information and click OK.63

Show Dependencies

Show Dependencies is a context menu option

that will open a dialog allowing you to select

dependencies for viewing and add them to a

subproject.

This feature is utilized heavily when extracting

Elements to Remote Projects.

64

Show Dependencies – 1 of 2

Show Dependencies is a context

menu option that will open a dialog

allowing you to select dependencies

for viewing and add them to a

subproject.

From z/OS projects:

1. Drill down to the Element you want to see

the dependencies of

2. Right click on the Element

3. Select Show Dependencies

65

Show Dependencies –

2 of 2

The Show Dependencies dialog

will pop up, showing the build

dependencies for the Element

you selected.

From here:

1. Select which dependencies you want

to view

2. Select “Add to selected subproject”

by clicking the box at the bottom of

the dependencies window

3. Click Finish

66

IDz Compare for Endevor Elements

This section will show IDz compare both:• With the latest in Endevor

• On history files/other files

This functionality is found in the context menu and the options for what to compare against are sensitive to where in the IDE you are accessing the functionality.

Example:

If the functionality is accessed in z/OS Projects view when only one Element is selected, the option to compare with Latest from CA Endevor SCM will be available but the option to compare with Each Other will be greyed out and inaccessible as you don’t have two Elements or source members within z/OS Projects view selected

67

Compare with Latest from Endevor – 1 of 2

To compare with the latest version

from Endevor:

1. Right click on the Element you want to

execute this function on

2. Select Compare With

3. Latest from CA Endevor SCM

68

Compare with Latest from Endevor – 2 of 2

After selecting Latest from CA Endevor SCM, a compare window will appear in the IDz LPEX Editor view.

This compare dialog will show changes and allow you to navigate the source members being compared in the same fashion as when using this functionality to compare source members in non-Endevor PDS’s from Remote Systems view.

Latest in Endevor source

69Remote Subproject source

Compare with History File

1. From CARMA Version History view, select

two Elements

2. Right click > Compare with > Each other

3. Results will show in compare dialog

70

Show Change History

To view the change history of an Element:

1. Right click on the Element

2. Select Show History

The results will show in the CARMA Version History view, organized by version with comments containing information like:

• Inserts

• Deletes

• Comments

71

“Fast/Enhanced Edit”, Dependencies, Compare review

In this section, we discussed more Endevor Element support functionality,

including:

• “Fast Edit” or “Enhanced Edit”

• Show Dependencies

• Compares

– With latest from Endevor

– With History file

• Show Change History

72

Thank you very much for

your time.

73

the carma interface

Documents