Editing Synchronized Endevor Elements Locally

Introducing Zowe Endevor CLI Workspace Synchronization

You want to edit your mainframe application stored in Endevor from your desktop. Of course, you also need Endevor to stay current with your changes and ensure that, if your colleagues make changes, conflicts can be resolved as easily as possible. Here’s how you can achieve this in any IDE using nothing but the Endevor plugin for Zowe CLI.

Endevor’s Bridge for Git allows you to connect Endevor to Git servers enabling your whole team to collaborate via Git and use their IDE of choice for code that resides in Endevor. However, if you haven’t gotten around to connecting Endevor with Git yet, we have another option! We’re introducing a lightweight Endevor workspace synchronization that can be used via Endevor’s Zowe CLI plugin and, in the future, via the Code4z Explorer for Endevor VS Code extension as well. Read on to learn how to use this new feature via the Zowe CLI Endevor plugin, and keep an eye out for a future blog on another option using the Code4z Explorer for Endevor extension.

CA Endevor Zowe CLI plugin enables easy automation of Endevor processes as well as giving developers a direct way to work with Endevor elements from any platform and editor.

However, the latter came with the caveat that developers needed to retrieve, add or update elements one at a time using individual CLI commands. Modern developers typically don’t work like that — rather, they work with a working directory or workspace that tracks their changes and handles any conflicts with other developers' changes. The workspace synchronization feature provides an easy and powerful way to do just that.

The Basics

The workspace synchronization allows a local folder, dubbed an Endevor workspace, to become a view of a specified Endevor location, with 2-way synchronization done at any time by typing a single command. The filesystem itself then becomes the Endevor interface, allowing any IDE or standalone tool on your workstation to be used for working with Endevor elements.

Let’s see how the new feature works in practice.

To use the workspace sync, you will need Zowe CLI Endevor plugin version 6.2.0 or higher, so update the plugin if needed.

Next, choose a local folder to use as your Endevor workspace and initialize it. In our example, we will use the current workspace folder in VS Code. Open a new terminal, and type:

zowe endevor init workspace

Because the command uses the current working directory by default, it is as simple as that. Now, let’s add some elements to the workspace!

Assuming you have an Endevor profile defined with the server connection details, the command to synchronize all elements from system FINANCE subsystem DEMOVASM at 1st stage of environment SMPLTEST would look like this:

zowe endevor sync workspace — env SMPLTEST — sn 1 — sys FINANCE — sub DEMOVASM — type *

Luckily you don’t need to specify all that every time - the synchronize command inherits settings from the default endevor-location profile like any other command. So if your location profile already specifies the map location you want to work with, the command becomes simply:

zowe endevor sync workspace

NOTE: all of the example commands from now on will be using a location profile defined as environment=SMPLTEST, stage num=1, system=FINANCE, subsystem=DEMOVASM, type=*

When you run the synchronize command for the first time, the sync will retrieve all the elements matching your request:

This will create a directory structure in your workspace based on the environment, stage number, system, subsystem, and type:

Now you can open the elements in your favorite editor, and get to work. When you have made the changes and want to push them back to Endevor to generate and test them, all you need to do is re-run the command:

zowe endevor sync workspace

The sync will now detect your changes and resynchronize the workspace by sending the changes to Endevor. If the system definition in Endevor requires a CCID or Comment, the sync may ask you to specify these on the command when it detects an element update would be needed in such a system:

Add CCID and/or comment and rerun the command.

zowe endevor sync workspace — ccid MYCCID — comment “the feature I’m working on”

This will result in your local changes getting sent to Endevor as Update element actions, using the specified CCID and comment:

What if you’re not alone?

So far so good, but what if there are other users making changes to the same Endevor map location while you’re working?

In the simplest case, each of you has changed different elements. The next time you run the sync, it will retrieve the changes that other users did in Endevor, then update all of the elements you changed:

But maybe both of you changed the same element? Here is where the built-in smarts of the synchronize feature shine. It will detect the conflict and attempt to resolve it. If the changes are in different parts of the code, the sync will still succeed, using an auto-merge algorithm to build a new element version that contains both changes:

What happened here is that first, the sync did a 3-way compare between your version of the element and the remote version found in Endevor, comparing both to the version of the element as it looked during previous successful sync. Since it found there are no conflicting changes, it applied both your and the remote changes to it and triggered an update action to send the result to Endevor.

So what if the changes cannot be resolved without user input? In that case, you will be asked to provide it:

The file inside your workspace will be updated with annotation showing the local and remote versions of any conflicting lines, and you will be asked to resolve the conflict.

The local file will now contain conflict annotation:

The highlighting and clickable options are provided by the Visual Studio Code editor, with the installed HLASM plugin. Other editors may not provide it.

If you use VS Code, the HLASM editor plugin can be found in the Code4z bundle from Broadcom, along with COBOL, JCL and REXX.

After editing the element to reconcile the conflicting changes, use the command the last run of the “synchronize workspace” helpfully provided to confirm the conflict resolution:

zowe endevor confirm resolution “SMPLTEST/1/FINANCE/DEMOVASM/ASM/FAPASM02.ASM”

Now all you need to do is run the synchronize command again to push the merged content into Endevor as the next element version.

The conflict detection is very robust and can handle tricky situations like further element changes happening while you work on the conflict resolution, or the element getting deleted or moved up the map.

Useful Options

The Synchronize command comes with multiple options that you can view in the command help. The 2 most useful ones to know when starting to use the Endevor workspace feature are “dry-run” and “reset”.

The “dry-run” option tells the sync to check for changes and report the actions it would need to take to put your workspace in sync, without actually doing anything:

zowe endevor sync workspace — dry-run

This is very useful when exploring the feature. You can try out different forms of the synchronize command without actually performing any actions.

The “reset” option is used to throw away any local changes and pending conflict resolutions, forcing your workspace to conform to what is in Endevor:

zowe endevor sync workspace — reset

This is the end of the introduction to Endevor workspace synchronization, stay tuned for more Endevor workspace stories coming soon!

Learn more about Zowe at this site; more Zowe blogs here.

Get in touch — if you have any questions or comments about the new CLI feature or just Endevor Zowe CLI in general I’ll be happy to discuss them, leave a comment or email me at Michal.Vasak@broadcom.com.