Using Zowe profiles in Z Open Editor

Z Open Editor extends Zowe Explorer functionality by making use of the Zowe profiles for z/OS connections to complete certain tasks. The profiles that are used by Z Open Editor are stored in the zopeneditor.zowe settings along with other lower-level settings that deal with connecting to z/OS.

IBM Z Open Editor will by default follow these precedence rules to identify which Zowe profile to use:

1. Use the profile specified by the zopeneditor.zowe user setting.
2. If no profile is defined in the user setting, then use the default RSE profile if available.
3. If the default RSE profile is not available, then use the default z/OSMF profile if available. If the default z/OSMF profile is not defined, errors are shown.

zopeneditor.zowe settings explained

• defaultCliProfile: The value is the name of the Zowe RSE or z/OSMF profile that you want to use. If you cannot remember the names, you can find the profile name using Zowe Explorer GUI or run the following Zowe CLI commands to get the list of all your profiles and your default profile:

  • List all profiles: zowe config profiles
  • List default profiles: zowe config list defaults

• defaultSshCliProfile: The value is the name of the Zowe SSH profile that you want to use. Some functionalities offered by Z Open Editor may require a Zowe SSH profile to be specified.

• defaultRseConversionMappingsFile: discussed in detail in the MVS EBCDIC code pages and mappings files help section.

• listBeforeDownload: The value is boolean and modifies Z Open Editor's behavior when requesting a file from MVS:

  • When the setting is set to true, the editor will first try to confirm whether the requested file exists by performing a list operation for that file. If the requested file exists, the editor will send another request to download it. If the requested file does not exist, the editor will move on to test the next location listed in the property group.
  • When the setting is set to false, the editor will directly try to download the file from MVS without checking whether it exists. If the response from z/OS is a Not Found error, the editor will move on to the next location listed in the property group. In some cases when using z/OSMF as the protocol, this Not Found error will cause entries in z/OS log files, which you can avoid by specifying the value of the setting to true.

  This extra round trip to the server when set to true to check the existence will have a performance impact. Because the logging is not always an issue for all z/OSMF users and not an issue when using the RSE API protocol, and because of the performance advantage, the default value for this setting is false.

• maximumParallelFileDownloads: The value can be used to specify how many parallel downloads Z Open Editor should perform when requesting include files from MVS. Downloading several files in parallel can significantly improve performance, especially when you edit programs with many include files. The downside is that some protocols such as z/OSMF will allocate more address spaces for the parallel requests, which causes more resources to be used and more logging on the z/OS side. The RSE API protocol does not have that problem because it achieves scalability in other ways that are outlined in the RSE documentation. The default value for this setting is 5, and the maximum value is 10. Set it to 1 to disable parallel downloads and request one include file at a time.

• readonlyRemoteIncludeFiles: Controls whether edits to remote include files that were resolved as a result opening a program are written back to MVS. These remote include files can be accessed for editing by ctrl/cmd-clicking the resolved include file inside inside the program editor. By default these include files will be opened as read-only to avoid accidental changes. Setting this setting true will allow you to edit and these include files and save the changes back to MVS.

Changing the Zowe Profile using VS Code settings

The format of the zopeneditor.zowe user setting is as follows:

"zopeneditor.zowe": {
  "defaultCliProfile": "mySandbox.rseapi",
  "defaultSshCliProfile": "mySandbox.ssh",
  "listBeforeDownload": false,
  "maximumParallelFileDownloads": 5,
  "defaultRseConversionMappingsFile": "~/wazi-sample/zapp.yaml",
  "readonlyRemoteIncludeFiles": false
}

These settings can also be edited by using this table in the graphical Settings editor:

Changing the Zowe Profile using status bar button

If no profile is specified in the settings, the default Zowe CLI profile is used by Z Open Editor in the VS Code status bar. You can find the name and type of the currently active Zowe CLI profile in the lower right of the editor window.

Hover over the status bar item for the Zowe profile to see information about the setting, and click the item to view a menu of options. These options are determined by the profile type that is selected when clicking the button. All profile types will show the options to change the Zowe CLI profile used by Z Open Editor.

When choosing a z/OSMF profile for the defaultZoweCli, the user will also see the option to choose the accompanying SSH profile that is needed for some Z Open Editor actions along-side the z/OSMF profile.

RSE profiles also have the option to change their password on the host for the profile. This option not only makes the change on the host side. If the host request is successful, it will update the credentials on the client side as well.

When changing the RSE profile password on the host, the user will be prompted for their original user ID and password for authentication purposes.