Preserving integrity of binary files

The Dependency Based Build (DBB) integration uses several preference and user build settings to ensure the integrity of EBCDIC-encoded binary files during transfer to the remote system for a user build operation. These settings offer several options for specifying characteristics of EBCDIC-encoded binary files. Learn how to set up Developer for z/OS® for successful transfer of binary files during a user build operation.

About this task

When tools such as Dependency Based Build and Engineering Workflow Management for z/OS copy source code between a host system and a local repository, the files must be converted from one character encoding to another. There are some situations in which characters do not map correctly between different character encodings. For example, when a new-line character is converted to a brand new line, transferred files have additional empty records compared to the original file. Files that contain such non-roundtrippable characters are modified and marked as binary. For more information about these types of situations, see Managing non-roundtrippable characters in Migrating data sets to git.

To successfully edit or transfer EBCDIC-encoded binary files to the remote system for a user build operation, the Dependency Based Build integration needs the following information about the files:

The content type: text or binary.
The file encoding on the remote system.
The file record length.

The Dependency Based Build user build operation can obtain this information from several sources:

It can traverse a project to obtain file attribute information.
It can obtain file content type and encoding information from a Git attributes file that you specify in the user build configuration wizard or in the Team > Git > Remote Integration preferences page.
Restriction: Record length information for binary files migrated by Dependency Based Build cannot be obtained from the Git attributes file. When Dependency Based Build migrates non-roundtrippable files, it removes the record length information from the files. This data must be provided manually so that the files can be edited in Developer for z/OS.
It can obtain default record length information for a file name pattern that is specified in the Team > Remote Integration preferences page.
It can obtain file attribute information from the file properties. These properties can be specified for each file, or inherited from the folder or project where the file is located.

Use the following procedure to set these options and learn how they work together to provide file attributes to the user build operation.

Procedure

Remember: The Developer for z/OS and DBB functions are available only for Git repositories that are imported into z/OS projects and are accessible in the z/OS Projects view. If you have not yet created a z/OS project from the Git repository contents, follow the instructions in Adding a Git repository to the z/OS Projects view.

To set up Developer for z/OS to obtain file attribute information for user build file transfers:

Set preferences that determine how the user build operation determines the record length of binary file transfers:
1. Open the Preferences window and navigate to Team > Remote Integration.
  The default settings for binary file record length assign a record length of 80 to all file types. To add entries for specific file types:
  1. Click * in the Pattern cell and change the value to a different file name pattern, such as, *.groovy.
  2. Click 80 in the Record length cell and change the value to a number appropriate for the file type.
  3. Click Apply.
  4. Click the second row in the table, and then click Add. A new row with Pattern * and Record length 80 is added to the table.
    Tip: The Add button is not enabled until you click Apply and then click a new row.
  5. Modify the new row as needed, then click Apply, click the third row, and click Add.
  6. Continue these steps until the table contains all of the file patterns and record lengths you need. The last row of the table always contains Pattern * and Record Length 80.
  The result of this procedure is to assign the specified record lengths to the file patterns you add, and then to assign record length 80 to any remaining binary files that do not match any of the defined file patterns.
2. Use this table to define default record lengths for file name patterns on the local system. By default all local binary files have a record length of 80. Click the Add, Remove, Up, and Down buttons to edit and reorder the table rows.
3. Select the Enable local file specification of attribute information option to enable local override of the default record lengths. When this option is enabled, you can use the Local Content Details page of the file Properties window to set the file content type (text or binary), the remote encoding, and the record length for binary files.
Set persistent file transfer attributes for local files on the Local Content Details page:
1. In the z/OS Projects view, right-click a file name and select Properties.
2. Select Local Content Details from the navigation pane.
3. For each attribute, you can use the default value, select a specific value (Other), or derive the value from one of these sources:
  - System Default: the file inherits its attributes from the system defaults.
  - Team Attribute: the content type and remote encoding are determined by the team attribute information, such as the information provided by Git or Engineering Workflow Management.
  - File Type: the content type is determined by matching a file type defined on the Remote Systems > Files Preferences page.
  - Workspace Preference: This option applies to binary file record length only. When this option is selected, the binary file inherits its record length from the table on the Team > Remote Integration Preferences page.
  - Project Setting: This option applies to binary file record length only. When this option is selected, the binary file inherits its record length from the Local Content Details page of the project's Properties window. To navigate to this page, right-click a project, select Properties, and then select Local Content Details in the navigation pane.
Set preferences that determine how the Git attributes file is composed for user build file transfers.
This procedure determines how the Configure User Build Use project traversal to compose attributes option is implemented for a user build.
1. Open the Preferences window and navigate to Team > Git > Remote Integration.
2. In the Attributes file field, specify the name of the Git attributes file to be composed by project traversal.
3. Optional: Select these options for processing the Git attributes file that is created:
  
  Enable scanning of attributes file for changes: When this option is selected, the product monitors the attributes file to detect changes to files and file encoding and content type information in the Git repository. When changes are detected, the product updates the persistent properties of the local files with these changes.
  
  Local encoding and content type attributes take precedence over scanned attributes: When this option is selected, any encoding and content type information that is specified on the Local Content Details page of the local file Properties window takes precedence over settings detected in the attributes file.
To display the file attributes for transferred files when you configure a user build, select the Show file transfer information option in the Configure User Build wizard. For more information about this wizard, see Using the user build wizard (zAppBuild).