EBCDIC code pages and mappings files

Tools such as the RSE CLI plug-in or Z Open Editor find mappings following these precedence rules with some rules applied to CLI only:

1. (CLI only) An encoding | ec parameter provided by the command always have highest precedence, for example --encoding IBM-273.

2. (CLI only) An encoding found in a file that was provided through the parameter mappings-file | maps, for example --mappings-file ~/myproject/zapp.yaml.

3. An encoding found in the current workspace in a file named zapp.yaml or zapp.json.

4. An encoding found in the default mappings file in the user's ~/.zowe/profiles/rse folder that was downloaded through command line.

5. An encoding specified in the Zowe CLI profile itself.

6. No encoding is specified, resulting in the use of the server default mappings file residing on the server.

The JSON schema for defining RSE CLI plug-in profiles simply consists of an array of mappings and a default encoding to be used if none of the mappings provided apply. The mappings can be provided as a simple array called mappings of mappings objects in a JSON file or as part of a ZAPP profile with settings as shown in the diagram below. See examples further below.

Fig.1: ZAPP Schema Model for RSE API

When you read these mappings the following validation and interpretation rules apply:

• There can only be one ZAPP rse-mappings profile of type rseapi in a ZAPP file.

• Member mappings consist of the same properties as the mappings except for the member mappings itself, that is, only one level of nesting.

• When member mappings are matched, they override values of the parent mappings. For example, the parent data set mapping might define a default encoding that is true for members that do not match, but if a member mapping is valid, any encoding value specified there overrides the parent mapping.

• The resource property is a mandatory property for data set and member mappings. Note: Mapping against members in all data sets is not possible for performance reasons.

• The resource of the data set parent represents a pattern on the data set name.

• The resource of the member mapping represents a pattern on the member name.

• If no transfer is specified for a resource mapping, the default is text.

• If no encoding is defined for text, it uses the default specified in the local mappings file. If that is missing, it uses the default of the server.

• If a transfer is specified as binary, the encoding is ignored.

• The extension property is only used to download files to determine which extension to append to the member name, which is to ensure editors can open the file correctly. To upload files, only the mappings to resources are relevant.

• An extension entry can be present either in a member mapping or the data set mapping. If it is in both mappings, the member mapping takes precedence. If it is missing completely in mappings, the first resource match is used.

Resources can be specified following the rules defined in Step 5 of the z/OS Explorer docs for Mapping data sets and partitioned data set members.

There are two wildcards enabled: ** and *

• ** matches in data set names across multiple name hierarchies. It cannot be used for member names. For example: **ERROR** matches:

  • USER.ERROR.TEST

  • USER.A.B.MYERROR.ABC

  • USER.A.B.MYERROR2.ABC

• * matches within a data set name segment or the member name. For example, USER**COB* matches:

  • USER.A.COB

  • USER.A.B.COBOL

  • USER.A.B.ACOBCOPY

The following shows a sample mappings file using JSON that you could place in your ~/.zowe/profiles/rse as conversion-mappings.json:

{
  "mappings": [
    {
      "resource": "**.SAMPLE.COB**",
      "extension": "cbl",
      "transfer": "text",
      "encoding": "IBM-273",
      "memberMappings": [
        {
          "extension": "dat",
          "transfer": "binary",
          "resource": "EIC*"
        }
      ]
    },
    {
      "resource": "**PLI*",
      "extension": "pl1",
      "transfer": "text",
      "encoding": "IBM-500"
    }
  ],
  "default.encoding": "IBM-1047"
}

This file defines that files located in data sets that contain the string .SAMPLE.COB in their fully qualified name such as USER1.SAMPLE.COBOL is transferred as text assuming an IBM-273 EBCDIC code page (Austria/Germany) on MVS. Hence, downloading a data set member with an RSE CLI plug-in command or Zowe Explorer using an RSE profile therefore converts the content by RSE API from IBM-273 EBCDIC to a UTF-8 file, as that is the format Z Open Editor requires files to be in. Uploading such a file converts the UTF-8 back to IBM-273 EBCDIC. The extension property, which is currently only supported by the CLI, specifies that the downloaded data set member is stored as a file with a .cbl file extension.

In addition to the default rule for **.SAMPLE.COB** data sets, you see a nested memberMappings subrule that provides a refinement: If the member name contains EIC as a substring then the file is not converted from IBM-273, but treated as a binary instead. This enables you to use data sets with members of different types.

Furthermore, the example shows how members in data sets that contain PLI in their names are converted using IBM-500 (Belgium/Canada/Switzerland) as well as that in all other cases the default conversion code page is IBM-1047.

In a zapp.yaml file, you can specify the same mapping described in the previous section by defining a ZAPP profile of type rseapi. The zapp.yaml for this particular specification contains text as follows:

name: sam
version: 1.1.0

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

Mappings files are not only used by RSE CLI plug-in commands, but also by Z Open Editor remote include file resolution operations. When you define a property group either in your ZAPP file or Settings, the retrieval of include files or copybooks use mappings files based on the precedence rules defined above. For example, if you define mappings in a zapp.yaml file in your workspace, these mappings are be used. If you do not have a ZAPP file, but have a personal mappings file in ~/.zowe/profiles/rse/conversion-mappings.json, the personal file is automatically used.

Zowe Explorer enables you to navigate your data sets and open data set members in the editor with a simple click. When you use Zowe Explorer with an RSE profile, conversion mappings can be used as well. To enable this, you need specify the absolute location of the mappings file to use in your user settings. The setting is called zopeneditor.zowe.defaultRseConversionMappingsFile. You can find it in the IBM Z Open Editor settings together with the other Zowe-related settings such as the defaultCliProfile. Conversion mappings defined in either a JSON-formatted RSE API user mappings file or a ZAPP file overrides an encoding specified in a Zowe profile.

When using encoding and mappings files with the RSE CLI plug-in commands, logging is written and found at ~/.zowe/zowe/logs/zowe.log. This log file contains the details about the encoding precedence that was used during upload and download of MVS files, the location of the mappings file if available, and the outcome of the encoding or transfer type that was chosen according to the previously-mentioned values.

In addition to the logging, you can also refer to the Upload and Download output to troubleshoot. If binary transfer was used, the output includes a binary value of true. If the file was transferred as text and an encoding value was used, the output includes an encoding value for each file.

1. User Build from VS Code: When you perform a user build on an existing COBOL file that contains double-byte characters, the .gitattributes settings ensure that the file is encoded in IBM-930 when it is checked out to the working directory.

2. Build process: During the build process, the file is uploaded to the specified USS folder with the correct encoding that is mentioned in the .gitattributes.

3. File display in VS Code: When you open the file in VS Code, the double-byte characters are correctly converted from IBM-930 to UTF-8.

1. Update the .gitattributes file located at the root of the repository with the following line. This specifies an encoding of IBM-930 for all files in the repository with the .cbl file extension: *.cbl zos-working-tree-encoding=ibm-930 git-encoding=utf-8.

2. Perform a user build from VS Code on an existing COBOL file that contains double-byte characters using the right-click menu.

3. During the build process, the zos-working-tree-encoding parameter specifies the code page used to encode files that are uploaded to USS or MVS.

4. Wait for the build process to complete. Once finished, the COBOL file is uploaded to the specified USS folder using the encoding from .gitattributes.

5. When opened in VS Code, the Japanese characters is correctly converted from IBM-930 to UTF-8.

こんにちは、世界！ //* Hello world!
これはテストファイルです。 //* This is a test file.
IBM-930エンコーディングを使用しています。 //* Using IBM-930 encoding.