Vscode-extension-for-zowe: Create VS Code Extension for CICS

[RASakach]

Many z/OS customers leverage CICS and need to manage CICS definitions, actions etc. Extending the mainframe VS Code interaction to include the CICS Explorer actions would provide a more seamless, richer user experience for the folks who support and use CICS.

Describe the solution you'd like
Build a CICS VS Code Extension capable of performing all of the actions included in CICS Explorer

Describe alternatives you've considered
None

Additional context
This may evolve into its own Zowe component but it needs to start somewhere. Figure this is a great place.

[Joe-Winchester]

Timing of this is great - looking forward to helping and working on this. Before joining Zowe I worked on CICS tools (including the CICS Explorer itself) and being based at the IBM UK Hursley labs where CICS is built (as well as the current CICS Explorer developers) lots of folks locally I can get help from.

[jellypuno]

@RASakach Thank you for suggesting this enhancement. @Joe-Winchester I am glad that you have experience with this. I am a CICS User and I developed Cobol CICS programs but I am having a hard time imagining how the CICS Explorer would look like in VSCode. I would appreciate some help in that area.

@Joe-Winchester @RASakach I am familiar in how you would set up CICS Transactions and Files using 3270 UI but how do you envision this in VSCode? Will this also include the Development for CICS Screens?

[Joe-Winchester]

@jellypuno - for the hills I think they might be something like:

• As a developer of a COBOL/PL1 program after editing my source in VS Code I can submit a JCL job to compile this into a load library. After that I want to have that program installed and able to be executed.
  
  
  
  • If the program hasn't been installed I will need to create a program definition, and install this into a CICS region, or all CICS regions where the program needs to run. For creation of a program definition I may have an existing PROGDEF that I want to copy and use as a template.
  
  
  • If the program is already installed, I will need to do a newcopy of the program in the region, and target all regions where the program is installed.
  
  

Currently to do these steps it is possible using the CICS CLI, and I have a colleague who is putting together a training course for how to do this, but they involve dropping out of the UI. What might be good is to have a call/webex where we look at the steps and do an "as-is" and from that we could think about what set of UI could be created to help streamline the process and make it more integrated into VS Code ? The screens I imagine that would help would be a tree view of CICS regions in the CICS plex, and a way of seeing the installed programs and being able to issue a disable/discard/newcopy - also a list of program definitions and do a Copy/Install.

[VitGottwald]

Hi @Joe-Winchester, for interacting with datasets and jobs ZOWE Explorer is using z/OSMF REST APIs or alternatively ftp or RSE APIs on the target z/OS LPAR. What APIs do you have in mind to facilitate the interaction with CICS regions to create program definitions and running transactions?

[Joe-Winchester]

@VitGottwald - CICS has an API known as CICS Management Client Interface (CMCI) https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html. This is what the CICS CLI plugin uses that has a lot of the commands needed. What I envisage is that the node classes that back the CLI get used by a VS Code plugin to populate views, and this perhaps also becomes the basis for an SDK.
The best way to see the list of available commands for the CICS CLI is to install the plugin and then look at the help, e.g.

[jellypuno]

and I have a colleague who is putting together a training course for how to do this, but they involve dropping out of the UI.

@Joe-Winchester I can also see it being done in this way because defining CICS programs is similar to a CLI.

What might be good is to have a call/webex where we look at the steps and do an "as-is" and from that we could think about what set of UI could be created to help streamline the process and make it more integrated into VS Code ?

A webex would be good so that we could have a clearer understanding of the goal of CICS VSCode Explorer and how it will be used.

The screens I imagine that would help would be a tree view of CICS regions in the CICS plex, and a way of seeing the installed programs and being able to issue a disable/discard/newcopy - also a list of program definitions and do a Copy/Install.

A tree view would be great. Will the list of definitions be displayed in the editor? Or everything is under the treeView? Maybe we could display it as a webView? we can do it as dialog boxes as well or settings as a JSON file. hmmm. I guess the webex call will clear things out.

[VitGottwald]

I see, thank you @Joe-Winchester. Does it have its SDK already?

[MikeBauerCA]

@VitGottwald it is similar to how the Zowe CLI is packaged today. The libraries are not currently published standalone but you could import the package (https://www.npmjs.com/package/@zowe/cics-for-zowe-cli) and leverage the libraries (https://github.com/zowe/zowe-cli-cics-plugin/tree/master/src/api).

[venkatzhub]

@Joe-Winchester - Glad to see the discussion to bring the core CICS Explorer functions to life in VSCode. This is indeed the absolute right next step. My only request would be to not just focus on VSCode, but also keep in mind the hosted/web IDE's when architecting, developing and testing these capabilities.

[EzrielG]

Joe,

I think if you were using the Zowe interface as an example I would like to see a separate tab for Operations and one for Definitions. You can add sub categories as you get it all working.

[jellypuno]

This is just a placeholder for the questions/ideas that I have around this (in case we have a call):

So given this scenario:

As a developer of a COBOL/PL1 program after editing my source in VS Code I can submit a JCL job to compile this into a load library. After that I want to have that program installed and able to be executed.

• If the program hasn't been installed I will need to create a program definition, and install this into a CICS region, or all CICS regions where the program needs to run. For creation of a program definition I may have an existing PROGDEF that I want to copy and use as a template.
• If the program is already installed, I will need to do a newcopy of the program in the region, and target all regions where the program is installed.

For the new CICS Explorer, this is a possible approach:

1. Extend the ZE APIs to pass the profile information.
2. Extend ZE context Menus to add CICS Menus

Scenario 1 (Verify if the program is already installed)

1. After creating the program, the COBOL developer will right-click > Click CICS: Verify Program.
2. It will prompt for a dialog box or maybe check settings.json to get the CICS Region Name and CICSPlex Information
3. It will then fire the CICS getResource API
4. If it Exist, then it will fire the CICS refresh API. It uses the the same Region Name and CICSPlex Information
5. If it doesn't exist, then error message appears "Program is not Defined in CICS RegionName"

Scenario 2 (Defining the Program in CICS)

1. The COBOL developer will right-click > Click Define Program.
2. It will prompt for a dialog box or maybe check settings.json to get the CSD Group, CICS Region Name and CICSPlex Information
3. It will then fire the CICS defineProgram API
4. Show response.

Questions:

1. This scenario extends ZE to handle the program definition. If I want to define transactions should I go to the CICS Explorer ZE extension? How is the process going to be like?
2. Should the CICS Explorer handle multiple CICSplexes and Regions? If yes, then who is the persona? CICS Admin or COBOL Developer or both?
3. How is the profile information going to be handled if it is a multiple CICSplex scenario? Can 1 profile connect to multiple CICSplex? I guess yes.
4. How is the UI going to be like? In the IBM Explorer for z/OS it is displayed as a table. Should it be similar or should all the information be displayed in the tree view only?

[venkatzhub]

@jellypuno - Great set of questions. I will let @Joe-Winchester chime in as he has more hands on and customer experience related to this. My take is there are two personas in play here - and we need to look at each use case to figure out what fits where.

The primary goal in the context of VSCode Zowe Explorer would be to make the life of a developer simple and easy. So, first step would be to focus on that use case. The developer has edited, built their code - now they want to test, so the developer should be able to do activities like New Copy etc..

[Joe-Winchester]

Questions:

1. This scenario extends ZE to handle the program definition. If I want to define transactions should I go to the CICS Explorer ZE extension? How is the process going to be like?

Once the program is compiled and in the load library then yes you should switch to a CICS centric UI which would be the CICS plugin.

1. Should the CICS Explorer handle multiple CICSplexes and Regions? If yes, then who is the persona? CICS Admin or COBOL Developer or both?

A CICS CLI profile connects to a CICS region. In the case of a CICSplex that region is a special region known as a WUI server and that server will have scope to connect to other regions in the CICS plex. For stand-alone CICS regions that won't be the case and the scope will just be for that CICS region. The persona is the developer, all they want to do is deploy their program. The CICS Admin will have already set up the region, the plex, so the only resources the developer is interested in is the program and the transaction. (This is for COBOL - for other languages such as Java or node there are other resource types and for programs that are web services there are others involved, but for now the best scenario to focus on is just COBOL or PL/1).

1. How is the profile information going to be handled if it is a multiple CICSplex scenario? Can 1 profile connect to multiple CICSplex? I guess yes.

Yes if the destination region of the profile is a WUI region, then this will have been configured to connect to all of the regions in the CICS plex. It gets more complex as there is a concept called scope, whereby regions within a plex are categorized, for example the application owning regions (which are the interesting ones where programs are deployed into) may be in a particular scope, so for deploying CICS programs you might select a scope).

What is interesting is the difference between CICS program definitions (also called PROGDEF and accessed traditionally through the CICS CEDA command) that typically reside in a CICS CSD file and the CICS program resources themselves (also called PROGRAM and accessed traditionally through CEMT). Think of the difference as one being a file with the definition of the program (the CSD PROGDEF) and the other the program executable ready to be run (the PROGRAM that is in a region from where it will be launched). As @EzrielG says the two are distinct - the CSD is Definitions, and the region with the installed program is Operations.

1. How is the UI going to be like? In the IBM Explorer for z/OS it is displayed as a table. Should it be similar or should all the information be displayed in the tree view only?

Very good question and I'm not a designer, but I imagine a tree where a user would select a CICS profile similar to how a Zowe Explorer now selects a z/OSMF (or other compatible) profile. What the user is hunting for is a region. If the CMCI connection target was a single CICS region then this was all they could see. If the CMCI connection target was a CICS Plex then the tree showed the plex name, children were the regions showing some special ones (CMAS and WUI) and also the scopes, twistie each scope to see the regions in that scope. Once a region is selected maybe they can favorite that region so it is easy to recall it.

For a given region a user is then looking for a program if it's already installed. If it's already installed it will be enabled or disabled. For a program a user would want to enable/disable/discard/newcopy and phasein. There can be lots of programs so some kind of filter to allow the user to narrow on programs matching a pattern, e.g. AB* or X. The API supports this kind of filtering. Programs in the region might get messy with lots of twistie clicks so maybe another UI element that shows programs and allows filtering, and also allows the user to see whether the program is enabled/disabled as well as a few other attributes (such as program type). I haven't seen any table UI in a VS Code extension explorer widget so not sure of what's possible. Or maybe there is a UI that's in the editor area, so from a region a user would "Operations -> Program" and see programs in a read only editor area that allows actions. I've seen VS Code UI that does that.

[FALLAI-Denis]

Hi,

I think that the CICS functions should be implemented in an extension for VS Code independent of the current Zowe Explorer extension, (all like the functions for Db2, IMS or MQ).

This for the following reasons:

• the installation of a program (or a transaction, because today programs are often managed in auto installation mode) is more a deployment action than a development action,
• often on the site it is not the user (developer) who manages the CICS declarations and their installation: it is a tooled process, possibly connected to the compilation, (on my site it is the role of Endevor: build and deployment),
• many sites would probably not like developers to manually intervene in the CICS configuration,
• not everyone uses CICS necessarily. If the CICS functions were integrated into ZOWE Explorer, they should be disengageable,
• wanting to manage everything in ZOWE Explorer will make this extension more difficult to develop.

The current extension should be limited to "z/OS and USS" functions: access to files and JES queues.

I therefore suggest that a new GitHub project be created to develop a "ZOWE CICS Explorer for VS Code" extension.

In the same way, we could consider projects "ZOWE Db2 Explorer for VS Code", "ZOWE IMS Explorer for VS Code", "ZOWE MQ Explorer for VS Code" ...

PS: plugin CICS for ZOWE CLI don’t use ZOSMF profile but use CICS profile, (plugin has no z/OSMF dependance).

[jellypuno]

Additional Note: ZE FTP extension is a good example of creating a New VSCode Extension that has linked APIs and Context Menus in Zowe Explorer. https://github.com/zowe/zowe-explorer-ftp-extension

[Joe-Winchester]

To get together and discuss this more it'd be great to do a zoom call next week. Slack thread https://openmainframeproject.slack.com/archives/CUVE37Z5F/p1594298834387800 has some suggested times, so please vote on which time(s) work or don't work.

[Joe-Winchester]

Kick off meeting Monday July 20th - 10am EST - https://lists.openmainframeproject.org/g/zowe-dev/viewevent?eventid=861012&calstart=2020-07-20.
20mins: @EzrielG will present background/primer on CICS development - what's a CICS region, CICS program, CICS program definition, what's a new copy command, ...
20 mins: Stew Francis (CICS Explorer dev lead) will present on existing CICS Explorer - what CICS remote APIs exist - CICS Management Client Interface (CMCI) and Graph QL
20 mins: Q&A and discussion to start defining hill(s) that could make a POC / MVP and the beginning of a user playback.

[MikeBauerCA]

@Joe-Winchester could you please record the meeting and provide a link to it here?

[Joe-Winchester]

@MikeBauerCA, @lauren-li and others. The recording of today's call is at https://github.com/zowe/community/tree/master/videos/Zowe%20Explorer%20CICS. I had to split the video into two halves to get under the github 100M limit.
Take aways I captured are:

• Follow up covering web services / CICS Java to show pipeline phasein, bundles currently not in CICS CLI. @EzrielG and @https://github.com/stewartfrancis
• Follow up separate call to look at DB2 developer scenario - @Joe-Winchester to organize.
• Focus on developer operational scenario where region, program, ... already exists. Scenario is "As a developer who has edited a COBOL program I want to submit the compile to get the load library updated, see the region(s) in a plex where the program is already installed and their use count (and other key attributes), perform a new copy".