Setting preferences

Before using IBM Z Open Editor, you can set preferences to control the characteristics of your environment. Preferences can be defined in various places depending on their scope - from user-specific settings to team project settings for files being edited. Z Open Editor distinguishes between settings provided via VS Code Preferences with settings provided in ZAPP files that are scoped to the application level and stored with your source code files. Application-specific settings, such as build flags, are typically shared with your team in ZAPP files. Personal settings, such as which Zowe profile to use for the user build, are usually in VS Code user settings.

Accessing VS Code settings for IBM Z® Open Editor

To open the settings for IBM Z Open Editor in VS Code, follow the steps below:

1. In VS Code, open Settings.

   • On Windows, click File > Preferences > Settings.
   • On Mac, click Code > Preferences > Settings.

2. To display the setting options for IBM Z Open Editor, expand the Extensions dropdown in the list on the left. Click on the entry IBM Z Open Editor.

3. All the preferences shown in the visual editor are represented as JSON. Complex preferences that are not just simple values must be entered by using the JSON editor itself. To open it, select the scope tab first: User tab or Workspace tab, and then open the JSON view by clicking Edit in settings.json, or by clicking on the Open Settings (JSON) icon on the upper-right of the editor.

VS Code user preferences versus workspace preferences

In the editor panel, a list of preference groups is displayed, along with editor tabs for both the User and Workspace Preferences. Switch between these tabs to decide in which scope you want to add a preference.

User preferences

User preferences apply to the current user across different workspaces. They include not only typical user preferences related to accessibility, such as font sizes and editor behavior for code completion, but also Zowe Profiles defining z/OS® host connection information and personal high-level qualifiers. The settings are stored for the user in their home directory, apply to all the open VS Code windows, and are not shared with other users.

Workspace preferences

Workspace preferences apply to the current workspace and are stored inside the .vscode directory at the root of the workspace. If you share the workspace with other users through Git, you would also share the settings if the intent is for them to be the same across users. For example, preference settings such as tab size or file extensions would apply regardless of who edits the files.

Note: The workspace preferences always override user preferences.

VS Code also supports the concept of multi-root workspaces that can also be utilized for Z Open Editor. Multi-root workspaces allow you to work with multiple folders, each representing a workspace in Visual Studio Code. This is helpful when you are working on several related projects at one time. Each workspace can use a different Git repository and be located anywhere on your development machine. A multi-root workspace basically combines all the individual and independent folders into one tree view in the File Explorer. Settings are defined for the entire multi-root workspace in a .code-workspace file, as well as for each individual workspace. In the case of a conflict, determining which setting has precedence over another depends on the setting type.

For more details and information on types of settings available to VS Code in general, refer to the User and Workspace Settings and Multi-root Workspaces: Settings VS Code documentation pages.

Details about specific Z Open Editor settings and behavior are provided in the following section, and also in the Settings Reference.

VS Code user preferences versus ZAPP files

Some preferences in Z Open Editor are specific to the application under development and should be stored independent of the editor being used to edit the program files. Examples are the search path for folders in which include files such as COBOL copybooks are located, or what compiler options should be used to parse the programs to show syntax errors in the editor. These preferences are stored in a file called ZAPP (Z APPlication) file. The section Configure your applications with ZAPP files provides a full overview.