zOSImport Overview

zOSImport is a utility that transfers source files from z/OS® data sets, or libraries, to a Windows® or Unix-based file system and imports them into IBM Engineering Workflow Management® (EWM) source control. The utility runs as an Ant task and uses the contents of a number of files to determine how to migrate the z/OS source files into EWM source control. The files it uses are shown in the table below and are documented in more detail in the zOSImport Task Reference.

File Description
zOSImport.xml Initial build XML that defines various properties such as the location and login credentials of both the z/OS system where the source code resides and the EWM server where the new projects containing the source code will be created.
components.xml Describes the project names that will be created and in which components they reside.
languages.xml Defines characteristics of each unique language type.
hlq.OBJECTS This file resides on the z/OS system where the parts are stored and describes characteristics of each part that will be transferred.
symbols The symbols file describes symbolic replacements that are to be performed on strings in the source code files as they are processed by zOSImport.
magic.properties Describes file properties to EWM during initial check-in of parts.

Setup and usage

The following section describes the steps required to run a zOSImport build to migrate your source code from your z/OS system to EWM source control. To run zOSImport a Jazz Build Engine must be used. This section includes instructions for downloading and installing a Jazz Build Engine and the Build System Toolkit.

In order to test your imports it is a good idea to install a separate, test, Jazz Team Server rather than testing in your main production environment. Jazz Team Server installation documentation can be found in the IBM Knowledge Center topic Installing Jazz Team Server and the IBM Engineering Lifecycle Management applications.

  1. Download and install the Build System Toolkit

    Install the Build System Toolkit as documented in the topic Installing the Build System Toolkit. A toolkit can be downloaded from the jazz.net EWM downloads page IBM Engineering Workflow Management 7.0.3 - Downloads.

  2. Create Jazz Build Engine to run Ant builds

    zOSImport runs as a task in an Ant build. To run zOSImport you will need a Jazz Build Engine defined in your repository for your project. To define the build engine use the following steps:

  3. Create a batch file or shell script to run the build engine

    Create a batch file that will be used to run the build engine, for example, JBE.bat. This file should have the following contents: 

    cd "${commonTxt.c104}install${commonTxt.c105}\buildsystem\buildengine\eclipse"
jbe -vm "${commonTxt.c104}install${commonTxt.c105}\jre\bin\java" -repository ${commonTxt.c104}repository_address${commonTxt.c105} -userId ${commonTxt.c104}userid${commonTxt.c105} -pass ${commonTxt.c104}password${commonTxt.c105} -engineId ${commonTxt.c104}engineId${commonTxt.c105}

    For example: 

    cd "C:\Jazz\buildsystem\buildengine\eclipse"
jbe -vm "C:\Jazz\jre\bin\java" -repository https://localhost:9443/ccm/ -userId USER01 -pass password -engineId "zOSImport JBE"

    Once you have created the the batch file you can double-click on the file to start the Jazz Build Engine which will then wait for work from the Jazz repository.

  4. Create Eclipse® projects to hold the zOSImport files

    The easiest way to get started is to import the sample project and modify it for your needs. Download the sample zip archive to a directory on your machine. In your Eclipse Project Explorer right-click and select "Import". Select "Existing Projects into Workspace":

    Import sample project

    Point to the archive file you downloaded and click "Finish" to import it.

    Import Sample Project

  5. Customize the zOSImport files

    Use the zOSImport Task Reference to assist you in modifying the files for your needs.

    Once you have modified all your XML files and created the OBJECTS file you are ready to test an import. Share the files with the Jazz repository if this is the first time you are registering them with Jazz, or check-in your changes if the build files have already been shared. You may need to deliver your changes depending on how you perform your builds.

  6. Create a build definition

    Create a new build definition in your Jazz repository that will be used to run the import. This should be a Ant - Jazz Build Engine build definition.

  7. Run the build

  8. Debug any issues with the various XML files

    Some common errors are:

    Once the build has run it will:

  9. Run the generated metadata.xml

    The generated metadata.xml is designed to be imported into a controlling Ant build that has the required Enterprise Extensions System Definition init task. This way the metadata.xml for each project can be imported into a single build and run once. In the provided sample project there are two sample controlling Ant builds. The first, Projects.Metadata.Resolve.xml, is the main driving build. This build will set up the list of projects that contain metadata to resolve. It will then call Metadata.Resolve.xml to set the data set definitions for each project. Metadata.Resolve.xml then calls the metadata.xml for each required project.

  10. Deliver the changes once you are happy

Once you have achieved the desired project structure you can deliver the change sets. You can now also change the build definition to remove the check on "Delete directory before loading". This will ensure you are now proving updates to the already delivered source code.