使用 ZAPP 文件配置应用程序

这一早期版本的 ZAPP 旨在提供针对一些想法的第一印象，并收集反馈。 ZAPP 文件当前可用于指定以下配置：

• 用于查找本地或远程包含文件的属性组为 设置属性组一节中描述的设置提供了一个完整的替代方案。

• 用于定义特定于语言的编译器选项的属性组 ，这些选项影响 IBM® 语言服务器解释源代码的方式。

• 用于 RSE API 的代码页映射定义了文件名模式的映射，以及应如何将其上载到 MVS 和从 MVS 下载，在 EBCDIC 代码页和映射文件一节中有详细说明。

• User Build 使用 IBM Dependency Based Build 产品，远程构建当前在 Z Open Editor 中编辑的程序。 (您可以在 使用用户构建构建构建 COBOL ， PL/I 和 HLASM 程序中找到此功能的详细文档)。

• 预处理器支持指定命令行在后台执行预处理器，并将输出与编辑器整合。 请参阅 高级功能: 预处理器支持中的更多详细信息。

• IBM 的 z/OS 测试自动化工具组合使用的测试用例规范。

在 VS Code 工作区首次打开 COBOL、PL/I、HLASM、REX 或 JCL 程序时，如果没有 ZAPP 文件， Z Open Editor 会自动为您创建 zapp.yaml 文件。 该文件可以位于工作空间的顶级文件夹中。 如果使用多根工作区 ，可以在第一个工作区中找到它。 您可以将该文件移至任何其他工作空间，但该文件必须位于顶级文件夹中。 如果是多根工作区，该文件会在所有工作区的所有目录中搜索包含文件。 对于非常大的工作空间，搜索可能会降低编辑器的性能。 因此，建议您在创建文件后编辑该文件，以缩小包含文件的位置，如 设置属性组中所述。

如果使用 Git ，顶层文件夹通常是包含.git 目录的目录，或者是在 VS 代码中使用文件 > Open.... 打开的顶层目录。 此目录通常包含可存储工作空间设置的 .vscode 目录。 以前，此目录也是现在需要存储在 ZAPP 文件中的属性组和用户构建设置的主目录。 对于多根工作空间设置，每个工作空间都可以具有一个 ZAPP 文件，并且可以相互组合使用; 例如，一个工作空间的 ZAPP 文件中定义的包含文件可以由另一个工作空间中的程序文件使用。 请参阅相应部分中的详细信息。

您可以通过将 zopeneditor.zapp.generateZappOnDemand 设置为 false来禁用 ZAPP 文件的自动创建。 您可以通过转至 文件> 新建文本文件在开发工作空间中手动创建 ZAPP 文件。

您可以选择将 ZAPP 文件作为 YAML 文件或 JSON 文件进行编辑，并在顶级目录中创建具有以下任一名称的文件。 该文件的名称必须与此完全相同，以使 YAML 或 JSON 编辑器能够识别要用于验证的模式。

• zapp.yaml

• zapp.json

如果您决定使用 YAML 格式，建议您安装 Red Hat YAML VS Code Extension ，因为这种格式比 JSON 更容易编写。 该 VS Code 扩展提供代码自动补全、文档和格式功能，对 ZAPP 非常有用。 Z Open Editor 可自动识别 YAML 扩展的安装，并在 VS Code 用户设置中为该扩展配置 ZAPP 模式。 Red Hat 注意，如果您还安装了 Red Hat® Ansible® VS Code 扩展，请确保在 VS Code 中为 ZAPP 文件选择的语言是 YAML，而不是 Ansible® ，因为这两种语言都使用.yml 和.yaml 这两种文件扩展名，您需要告诉编辑器编辑的是哪种语言。

此外，还提供了 YAML 中 ZAPP 的代码片段，这使您能够即时生产。 如果使用 JSON ，那么缺省 VS Code JSON 编辑器还会提供代码完成和格式化，但 Z Open Editor中当前没有包含片段。 不过，您也可以创建自己的自定义片段。

当 Z Open Editor 启动时，它会检查是否安装了 Red Hat YAML 扩展。 如果是，编辑器会自动添加用于 YAML 编辑器验证的 ZAPP JSON 模式链接。 如果未安装该扩展， Z Open Editor 只能在 JSON 编辑器中添加模式链接。 要验证 Z Open Editor 是否已将自身配置为使用 Red Hat YAML 扩展或 VS Code JSON，请在 VS Code 用户设置中查找如下所示的条目。 应在打开 Z Open Editor 后添加条目。 此处可能列出了其他模式条目，例如指向 Z Open Editor的 zcodeformat 模式或第三方扩展所使用的 schemata 的链接。

"yaml.schemas": {
  "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-3.0.0/resources/zapp-schema-1.0.0.json": [
    "zapp.yaml"
  ]
},
"json.schemas": [
  {
    "fileMatch": [
      "/zapp.json"
    ],
    "url": "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-3.0.0/resources/zapp-schema-1.0.0.json"
  }
]

您现在已准备好创建第一个 ZAPP 文件。

ZAPP 文件支持变量替换。 您可以在 "VS 代码" 设置中定义变量，并在 ZAPP 文件中使用这些变量。 当在存储库中共享 ZAPP 文件并且用户需要在不修改原始 ZAPP 文件的情况下对其进行个人调整时，这很有用。

要定义 ZAPP 用户变量，请打开 VS 代码用户或工作空间设置，并使用 zopeneditor.zapp.variables下的值指定名称。 您可以使用表在图形编辑器中执行此操作。 搜索 "zapp" 以快速找到它，然后单击 添加项 以插入变量的新行。 或者，您可以在设置的 JSON 表示中添加和编辑变量，如以下示例中所示:

  "zopeneditor.zapp.variables": {
    "PERSONAL_DIR": "/Users/user1/copybooks",
    "USER": "IBMUSER",
  }

要引用 ZAPP 变量，请在 ZAPP 文件中写入 ${variable-name} 。 例如：

  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "**/${PERSONAL_DIR}"
      - name: syslib
        type: mvs
        locations:
          - "${USER}.SAMPLE.COPY"

请注意，所有用户都需要在其用户设置中定义 ZAPP 文件所使用的所有变量以避免错误。 请勿对变量名称和值使用单引号或双引号字符。 您可以将这些属性放入 VS 代码用户以及工作空间设置中。

在工作空间中， Z Open Editor 按以下顺序搜索 ZAPP 文件，并仅使用它找到的第一个文件:

1. 工作空间目录中的 zapp.yaml。

2. 工作空间目录中的 zapp.json。

对于具有以下规则的多根工作空间的 ZAPP 文件支持有限:

• 属性组: 多根工作空间装入位于每个工作空间的顶级目录中的所有 zapp 文件。 Z Open Editor 使用这些 ZAPP 文件中定义的所有属性组，其顺序与多根工作区 文件中定义的工作区顺序一致。 .code-workspace 您可以手动编辑此文件以更改顺序。 这个顺序也是工作区在 VS 代码的文件资源管理器中的显示顺序。 因此，将从上到下使用属性组。

• 基于依赖关系的 User Build ：对于已构建的程序，要使用的 DBB 配置文件是位于程序所在的同一工作区根目录下的 ZAPP 文件。 在该 DBB 概要文件中为其他依赖关系 (例如 application-conf 文件) 指定的所有位置都需要与程序位于同一工作空间中。 包括文件 (例如副本) 可以位于任何其他工作空间中，因为将在先前项目符号点中定义的所有可用属性组中搜索这些文件。

有关单根工作区的更多详情和示例，请参阅 wazi-main 分支中的样本 GitHub 资源库 ，以及 wazi-main 分支 multiroot 文件夹中的多根工作区。

您可以从以下网址克隆包含 ZAPP 文件的 GitHub 示例库，开始使用 ZAPP：

https://github.com/IBM/zopeneditor-sample.

此存储库包含以下设置文件，因此您可以使用 YAML 或 JSON 对其进行尝试，并确定最适合您的设置:

• zapp.yaml 文件

• zapp-example.json 文件

这些文件在分支 main 和 wazi-main中有两个不同的版本。 如果您正在使用其他 IBM Wazi 功能 (例如， IBM User Build ) ，请改为切换到 wazi-main 分支。

注意 ：根据上一节中的优先级规则 ，如果要试用 zapp-example.json 文件，必须先删除或重命名 zapp.yaml 文件，然后将其重命名为 zapp.json。

name: sam
description: Wazi's code samples with COBOL, PL/I, HLASM, and REXX applications
version: 3.0.0
author:
  name: IBM CORPORATION

propertyGroups:
  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "**/COPYBOOK"
      - name: syslib
        type: mvs
        locations:
          - "IBMUSER.SAMPLE.COBCOPY"
      - name: MYLIB
        type: mvs
        locations:
          - IBMUSER.SAMPLE.COPYLIB
      - name: MYLIB
        type: local
        locations:
          - "**/COPYLIB-MVS"
      - name: MYFILE
        type: local
        locations:
          - "**/COPYLIB"

profiles:
  - name: RSE-Mappings
    type: rseapi
    settings:
      mappings:
        - resource: "**.SAMPLE.COB**"
          extension: cbl
          transfer: text
          encoding: IBM-037
          memberMappings:
            - extension: dat
              transfer: binary
              resource: "*DAT"
        - resource: "**PLI*"
          extension: pl1
          transfer: text
          encoding: IBM-037
      default.encoding: IBM-037

profiles:
  - name: dbb-userbuild
    type: dbb
    settings:
      application: SAM
      command: "$DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON"
      buildScriptPath: "${zopeneditor.userbuild.userSettings.dbbWorkspace}/dbb-zappbuild/build.groovy"
      buildScriptArgs:
        - "--userBuild"
        - "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}"
        - "--application ${application}"
        - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
        - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
        - "--dependencyFile ${dependencyFile}"
      additionalDependencies:
        - application-conf
        - "zapp*"
      logFilePatterns:
        - "${buildFile.basename}.log"
        - "BuildReport.*"

代码补全要求您已安装并配置 Red Hat VS Code YAML 扩展，如上所述。 您可以按如下所示试用：

1. 将光标放在带有 language: cobol 的行后面 (绕行 18) ，然后按 Enter 键以启动新行。

2. 按 Ctrl+空格键以打开代码补全下拉列表。

然后，它显示了该属性组中尚未使用的一个属性 compilerOptions ，该属性仍可在此添加。 您可以通过点击项目或键盘上的方向键和回车键来添加。

如果属性值是枚举类型或布尔类型，也同样适用。

1. 将光标移动到行 type: local 的末尾 (绕行 21)。

2. 删除单词 local ，然后执行另一个 Ctrl + Space。

现在，它会在下拉菜单中显示两个已启用的选项 local 和 mvs ，供你选择。

您还可以在下拉菜单中看到可在此处插入的各种代码片段。 不过，你可以看到属性是根据上下文列出的，即下拉菜单只显示允许在此插入的条目。 代码片段不区分上下文，始终显示。 您需要确保在语法上使用它们是正确的。 如果插入错误，YAML 编辑器扩展会提示语法错误。

ZAPP 还提供了代码片段，以便您可以快速输入新的属性组。 仅当您编辑 zapp.yaml 文件时，代码片段才在代码编辑器中可用。 在 VS 代码片段库中找不到它们，因为 VS 代码目前无法在其片段库中区分不同的 YAML 文件类型。

要使用以下代码片段:

1. 将光标置于文件中属性组末尾的空行 (位于第 85 行周围)。

2. 按下 Ctrl+Space 键，你会看到下拉菜单中列出了四个代码片段。

3. 向下浏览并通过按 Enter 键选择 ZAPP Remote MVS Property Groups 。

4. 您可以看到新属性组已插入突出显示的占位符。

5. 在单击或键入任何内容之前，当占位符仍然突出显示时，使用 Tab 键和 Shift+Tab 键在占位符之间导航，并输入名称、语言（使用另一个下拉菜单）和 syslib 条目的值。

6. 在新属性组的末尾，通过添加新行并输入新值 (例如 - USER1.SAMPLE.INCLUDES) 来添加另一个 locations 条目。

请记住，您需要提供有效的 YAML 文件。 由于 locations 条目需要 JSON 格式的字符串数组，因此现在需要在 YAML 中输入该条目作为使用 - 作为每个值的有序列表。

还有一个完整 ZAPP 文件的代码片段模板。 您可以按如下所示试用：

1. 在 zapp.yaml 的当前编辑器窗口中，执行“全选”并删除文件的所有内容。 您可以稍后撤销删除，因为该文件在 Git 中进行管理。

2. 在空文档的第一行和第一列中，按 Ctrl + Space 并选择 ZAPP Template 片段。 您不必一路滚动到底部，而是可以改为输入该片段名称。

3. 您会看到插入了一个片段，其中包含顶部的常规属性以及一个具有本地库条目的属性组。 然后，可以根据需要进行修改，或者使用相应的片段添加更多属性组条目。

您可以在 ZAPP 文件中指定用户构建的所有工作空间设置，如 设置用户构建中所述。 在此发行版中，仍需要将用户设置存储在 VS Code 用户设置文件中，但所有工作空间设置都可作为工具概要文件在 ZAPP 中提供。

您可以在 zopeneditor-sample GitHub 存储库中的样本 ZAPP 文件末尾找到 DBB 概要文件的示例。 如果已按先前部分中所述除去所有内容，那么您可以自行创建工具概要文件，如下所示:

1. 转至最后一个属性组后面的文件末尾以列 1。

2. 输入关键字 profiles: 并按 Enter 键。

3. 由于您可以指定许多概要文件的有序列表，因此请通过缩进并输入 - ，然后输入代码补全所建议的任何属性来启动新列表。

4. 选择必需的 type 属性时，可以使用下拉列表来选择概要文件的类型。 现在，仅支持类型 dbb 。

5. 选择类型 dbb后，您可以添加 settings: 属性，该属性定义了无序属性的对象，您还可以在缩进代码完成后输入该对象。

您还可以使用由 Z Open Editor 提供的代码片段，如下所示，而不是全部手动输入 DBB 概要文件:

1. 在 profiles: 条目后面的列中，按 Ctrl + Space 并选择 ZAPP User Build Profile 片段。

2. 片段包含带有占位符的完整 DBB 概要文件。 然后，您可以通过按 Tab 键进行导航，并将占位符替换为您的特定值。

键入不正确的 YAML 或拼写错误的属性名称而创建无效的 zapp.yaml 文件时， Red Hat YAML 扩展会在 "问题 "视图中显示语法错误。 您可以按如下所示试用：

1. 从任何属性中除去几个字母来做出错误拼写。

2. 切换到 VS Code“问题”视图。 如果看不到该视图，请使用视图 > 问题视图菜单。 该视图现在会显示确切的语法错误以及发生错误的行和列。

如果没有安装 Red Hat® YAML 扩展，仍可在输出视图中找到 Z Open Editor 提供的简单错误列表，如下所示：

1. 切换到“输出”视图。 如果看不到该视图，请使用视图 > 输出视图菜单。

2. 在“输出”视图的右侧，从下拉列表中选择 IBM Z Open Editor。

3. 制造一些语法错误。 请注意， Red Hat 扩展会立即显示错误，而在这里，直到尝试保存时才会显示错误。

4. 使用语法错误保存您的文件。 现在，输出视图会显示错误信息，如 should NOT have additional properties(additionalProperty:lauage)。

如您所见，此处的输出简单得多，并且没有行号。 Red Hat 扩展是迄今为止编辑 ZAPP 文件的最佳解决方案，因为该扩展包含一个完整的 YAML 语言服务器，可生成大纲视图。

Red Hat YAML 扩展的另一功能是能够一致地格式化 ZAPP 文件。 如果在一些地方使用了不同的缩进，那么可以通过使用以下两种格式化方式之一来更正整个文件的格式：

• 使用快捷键 Shift+Option+F (Mac) 或 Shift+Alt+F (Windows)。

• 按 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows)，并输入“格式化”以选择格式化文档。