Troubleshooting, known issues and limitations for IBM Z Open Editor and RSE CLI plug-in

The language servers provided with this extension require a valid Java SDK to start correctly. Currently, they will not work with a Java Client Runtime Environment. They require either a Server Runtime Environment or better a full SDK to function correctly.

If the right version of Java cannot be found in the current user's path or if no JAVA_HOME environment variable was defined, you might see error messages in the Output view of VS Code. Such errors could also be caused by other reasons such as not enough free memory for Java on your system.

Go through all the steps described in the Getting Started page for configuring Java to try out different options.

You can enable logging for IBM Z Open Editor to produce detailed logs that can be used to troubleshoot problems. Logs can be valuable inputs when you file defects or contact the technical support (if you are entitled to). You can enable logging via a user preference setting called zopeneditor.logger. In the VS Code Preferences editor, select from the allowed values: DEBUG, INFO, WARNING, ERROR and OFF (default). Once it is enabled, you can find the logging output in two places:

• In the VS Code Output panel, where a drop-down tab called IBM Z Open Editor is created; and

• A log file written to your disk. The Output panel tells you at the top when it is activated for the first time the exact path location of the log file, which is platform dependent, .

If you use IBM Z Open Editor with Eclipse Che or Red Hat CodeReady Workspaces, you can also enable logging by specifying the same user preference setting, zopeneditor.logger. To find the generated log file, open a Terminal window in the container called ibm-wazi???, with the question marks being replaced by randomly generated characters. Do not mistake that with the default user content container called wazi, which you use for coding.

It might happen that the language servers provided by IBM Z Open Editor become inconsistent and do not behave as expected. For example, one language server might stop reporting syntax errors, or it cannot resolve copybooks anymore. Instead of quitting and restarting VS Code completely, you can try pressing the F1 key and type the following commands to reset one or more language servers.

• IBM Z Open Editor: Pause the COBOL Language Server: Stops the COBOL language server and restarts it when you open a COBOL file again.

• IBM Z Open Editor: Pause the PL/I Language Server: Stops the PL/I language server and restarts it when you open a PL/I file again.

• IBM Z Open Editor: Pause the Assembler Language Server: Stops the HLASM language server and restarts it when you open an HLASM file again.

• IBM Z Open Editor: Reload Zowe Profiles: If you have changed the password of your Zowe CLI profile that is used to load your remote include files such as copybooks, you need to run this command to refresh the Zowe profile.

• Developer: Reload Window: Restarts the current VS Code window and all of its extensions. If you have many editor windows open at the same time, you can use this command to reset just the current window in which you run the command.

Currently the editor relies on third party tools such as Zowe CLI for conversions of program files encoded in EBCDIC on z/OS to the format for editing. Only Codepages supported by VS Code natively can be used. The recommended format for all local files is UTF-8.

If you are using Git to manage your sources on your local client as well as z/OS USS, we recommend managing a .gitattributes file that will drive the conversion through Git. See this post and this document for more details.

IBM Z® Open Editor supports VS Code multi-root workspaces; however, be aware that property groups defining path names for COBOL, PL/I, and HLASM resource dependencies are managed as so-called Window-level VS Code settings. This means that these property groups need to be defined for multi-root workspaces for the entire workspace. Project-level settings will be ignored. If you intent to use a project as part of a workspace as well as independent of the workspace, then you need to have two copies of your property groups in each location. When you work in the workspace, the editor will look for property groups in the .code-workspace file. When you work just in a project directory outside of a workspace, it will look for property groups in the workspace .vscode/settings.json file.

See more details about this limitation in this section.

Almost all capabilities described in this documentation are available when you use IBM Z Open Editor with Eclipse Che or Red Hat CodeReady Workspaces. However, be noted about the following limitation.

• Code snippets: The extensive IBM Z Open Editor code snippet library is not supported if you use IBM Z Open Editor with Eclipse Che or Red Hat CodeReady Workspaces. It is available only in VS Code at the moment.

  The Theia editor utilized in Eclipse Che and CodeReady Workspaces does not provide a snippet gallery as VS Code does. Therefore, you cannot define your own custom code snippets with the Theida editor. In VS Code, code snippets provided by VS Code extensions, such as the IBM Z Open Editor, can normally be inserted via the code completion features using the Ctrl+Space shortcut. However, that capability currently has a known defect in Eclipse Che and therefore is not supported in CodeReady Workspaces neither. This defect prevents the code snippets from appearing at all.

If you want to provide feedback that is specific to the VS Code extensions, open an issue in the zopeneditor-about GitHub repository. Any report and feedback is appreciated.