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 by default follows 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.

Specifying which profile to use in IBM Z Open Editor

You can use RSE profiles for IBM Z Open Editor operations. For example, if you edit a COBOL program and have defined property groups to dynamically retrieve contents of copybooks from MVS, you can use your RSE profile for that access operation instead of the default z/OSMF CLI profile.

The default precedence rules to identify which CLI profile to use are as follows:

  1. Use the profile specified in the zopeneditor.zowe workspace settings.
  2. If not defined, use the profile specified in the zopeneditor.zowe user settings.
  3. If no profile is specified in either location, or if the specified profile name cannot be found, use the default RSE profile if available.
  4. If the default RSE profile is not available, use the default z/OSMF profile if available. If the default z/OSMF profile is not defined, an error is displayed.

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

"zopeneditor.zowe": {
    "defaultCliProfile": "rseCLI",
},

The value of defaultCliProfile is the name of the CLI profile that you specified when creating the profile.

If you have profiles in place but cannot remember the names, run the following command to list all profile names in the team configuration file:

zowe config profiles

Because only the profile name is used to locate a profile, you must assign unique names to profiles of different types. If you use the same name for both an RSE API profile and a z/OSMF profile, the RSE API profile will always be selected when that name is specified in the settings. To switch between z/OSMF and RSE API profiles, you must use unique names.

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: Specifies how many parallel downloads Z Open Editor performs when you request 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, allocate more address spaces for parallel requests, which increases resource usage and logging on the z/OS side. The RSE API protocol do not have this limitation because it achieves scalability in other ways, as outlined in the RSE documentation. The default value for this setting is 5, and the maximum value is 50. Set the value to 1 to disable parallel downloads and request one include file at a time.

  • maximumParallelFileUploads: Specifies how many parallel upload operations Z Open Editor performs when uploading files to z/OS. This setting is used by User Build when uploading include files as well as supplementary files called "additional dependencies" to UNIX System Services. Uploading several files in parallel can significantly improve performance when uploading many files in nested directories. The downside is that some protocols, such as z/OSMF, allocate more address spaces for parallel requests, which increases resource usage and logging on the z/OS side. The RSE API protocols do not have this limitation because they achieve scalability in other ways, as outlined in the RSE documentation. The default value for this setting is 5, and the maximum value is 50. Set the value to 1 to disable parallel uploads and upload one 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 or cmd-clicking the resolved include file inside the program editor. By default, these include files open as read-only to avoid accidental changes. Setting this setting true allows you to edit these include files and save the changes back to MVS.

  • disableRseApiLanguageDetection: Disable the advanced RSE API language detection feature, as documented in Language Detection.

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": 20,
  "maximumParallelFileUploads": 20,
  "defaultRseConversionMappingsFile": "~/wazi-sample/zapp.yaml",
  "readonlyRemoteIncludeFiles": false
}

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

VS Code Settings editor for zopeneditor.zowe

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.

'zowe-no-prof-status''zowe-rse-status'

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

'profile-management-options'

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

Timeout error handling for z/OS connections

Enhanced timeout error handling is now available for z/OS resource operations. Requests that exceed the configured timeout period display a clear connection timeout error instead of a generic HTTP 500 Internal Server Error, improving troubleshooting and error diagnosis.

RSE Password Expiry prompt

When using an RSE profile, a password expiry prompt will appear at the launch and reload of Z Open Editor if the saved profile's credentials are nearing expiration. The prompt will first appear 14 days before expiration and will continue to display daily until either the credentials are updated or the prompt is snoozed. Ensuring the user is repeatedly reminded as the expiration date approaches.*

'password-expiry-prompt'

This prompt features 3 buttons:

Update Credentials: This option will redirect the user to change their credentials on the host for the active RSE profile.

Snooze Notification: This option will temporarily disable the prompt for predefined days. The initial choice of snooze will last until 7 days before expiration of password, and following choice to snooze the reminder for 3 days before expiration of password, and finally 1 day before expiration of password on the host.

Cancel: This option will dismiss the prompt, which will reappear the following day.

Last Updated:
Contributors: Billie Simmons, Hestia Zhang, phaumer, PETER HAUMER, Benjamin Santos, Karan Patel, Karan, Vinithanjali Selvaraj, Esther M, Nimma Likhitha, likhithanimma1