zVMImport Overview

zVMImport is a utility that transfers source files from z/VM^® minidisks 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/VM source files into EWM source control. The files it uses are shown in the table below and are documented in more detail in the zVMImport Task Reference.

Setup and usage

The following section describes the steps required to run a zVMImport build to migrate your source code from your z/VM system to EWM source control. To run zVMImport 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

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

   • In the EWM Team Artifacts view under the desired project area, navigate to the "Builds -> Build Engines node". Right-click and choose "New Build Engine...":

     

   • Choose your project area and "Create a new build engine", then click "Next".

     

   • Specify a name for the build engine. This name will be used when you run the build engine so that it can connect to the EWM repository. For example: "zVMImport JBE". Select "Jazz Build Engine" as the build engine type.

     

   • Click "Finish" and "Save" the build engine definition.

     

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:

   • Change directory to the install location of the build engine sub-directory "/buildsystem/buildengine/eclipse"
   • Issue jbe command to start the build engine specifying the URL of the repository, user ID, and password.

   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 zVMImport-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 zVMImport 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":

   

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

   

5. Customize the zVMImport files

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

   • systemDefinition.xml

     As your source files are going to reference existing system definitions such as data set definitions and language definitions you will need to make sure they exist. Either create the required definitions through the UI or use System Definition XML to define them. Sample system definition XML is provided in the sample project in systemDefinition.xml. Modify this XML file to suit your needs.

     Run the systemDefinition.xml as an Ant build. Right click on the file and select "Run As" then "Ant Build..."

     Ensure that in the JRE tab the Runtime JRE is set to "Run in the same JRE as the workspace". Then click "Run" to run the XML.

   • zVMImport.xml

     This file contains information relating to the location of the z/VM system, the location of the EWM repository as well as various options to be used in the import. You will also need to use the password encryption discussed in the zVMImport Task Reference to encrypt both your z/VM password and your Jazz repository password. Use the sample and reference as a guide to set the information in this XML.

     Depending on the physical location of your engine, your z/VM system, and your Jazz repository, it may be wise to change requestTimeoutInt to 600.

     For ease of use make sure the repository workspace you are using is unique. If you are testing the import and want to rerun, set checkinOnly to true for initial runs until everything is set up. You can then delete the created repository workspace and rerun any number of times.

   • OBJECTS File

     The OBJECTS file contains all the parts you plan to import from your z/VM system into EWM. It will be prefixed with a version that relates to the version of the product you are importing, and this name is referenced by the zvmRelease property in the zVMImport.xml. Transfer the 603.OBJECTS file in the sample project to your z/VM system as a model and modify it using the zVMImport Task Reference as a guide.

   • components.xml

     The components.xml file contains the mapping from your z/VM file system to the Eclipse project structure you will use in EWM. Use the components.xml file in the sample project as a model and refer to the zVMImport Task Reference for specific information.

   • languages.xml

     The languages.xml file contains mapping information to assign file extensions and other information to the files once imported into Jazz. Use the languages.xml file in the sample project as a model and refer to the zVMImport Task Reference for specific information.

   • magic.properties

     This file contains encoding information based on file extension. Use this to automatically set encoding when you run zVMImport. See the zVMImport Task Reference reference for more information.

   • symbols

     Refer to the zVMImport Task Reference for information on the symbols file.

   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.

   • Set the build engine to use to be the one you created in an earlier step.
   • Create a build workspace to be used by the build definition.
   • Set "Delete directory before loading" in the "Jazz Source Control" tab. This ensured the .jazz5 directory is deleted between runs and ensures no complication while testing. However, once you move into update mode rather than full replacement mode you should ensure that this property is not checked.
   • Set the rtc.deliver build property to true, otherwise the source will be moved over but not checked in. By default rtcCheckinOnly is set to true. Use this while you are testing your scripts. Once you are ready to do a real migration you can either set a property rtcCheckinOnly to false or you can perform the deliver manually from the EWM Eclipse Client.
   • When you first run set a property debug set to true. In addition in the Ant arguments in the build set an argument of -debug. This will give you a lot more information if you get some failures.

7. Run the build

8. Debug any issues with the various XML files

   Some common errors are:

   • Incorrect IP address of the z/VM system.
   • Incorrect encoded passwords.
   • Incorrect setting of property rtcScmTool.
   • During testing you do not delete the create Repository Workspaces between runs.

   Once the build has run it will:

   • Copy the source from the z/VM system to the directory you specify in the "load Directory" specified in the build definition.
   • Create the stream you specified, if it does not exist.
   • Create the components you specified, if it does not exist.
   • Create the repository workspace. If it already exists you will get a failure.
   • Check the code in.
   • Create a metadata.xml, per project, that contains metadata relevant to the source code in that project. Such as an mvsCodePage setting for each file.

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.

   • Edit Projects.Metadata.Resolve.xml to add the zProjects you have created.

     For each project you have checked in add an <ant> entry in the <target> element. In the example below there were two projects created. The relative directory address should be correct as all locations are based on the sandbox location.

     <target name="main" description="Create metadata definitions">
       <ant antfile="${basedir}/Metadata.Resolve.xml" target="resolvemetadata" dir="../zos.zvmimport.llamon.jcl"/>
       <ant antfile="${basedir}/Metadata.Resolve.xml" target="resolvemetadata" dir="../zos.zvmimport.llamon.main"/>
     </target>
               

   • Edit Metadata.Resolve.xml to provide the data set definition mapping.

     There is a single data set definition resolve task. This is because many projects may use the same data set definitions. Add a dsdefrule element for each unique data set definition. The match will match the name of the zFolder you created and dataSetDefinition should reference an existing data set definition name.

     <!-- zFolders - work -->
     <ld:dsdefrule match="^ASSEMBLE$"             dataSetDefinition="Source code"/>
     <ld:dsdefrule match="^ASSEMBLE.ALLAFSAM$"    dataSetDefinition="Feature Shipped Assembler Parts"/>
     <ld:dsdefrule match="^C$"                    dataSetDefinition="Source code"/>
     <ld:dsdefrule match="^COBOL$"                dataSetDefinition="Source code"/>
     <ld:dsdefrule match="^CODEGEN.C$"            dataSetDefinition="Source code"/>
     <ld:dsdefrule match="^CODEGEN.H$"            dataSetDefinition="H"/>
     <ld:dsdefrule match="^COPY$"                 dataSetDefinition="PLI Includes"/>
     <ld:dsdefrule match="^DATA.ALLAFED1$"        dataSetDefinition="Feature Data 1"/>
     <ld:dsdefrule match="^DATA.ALLAFED2$"        dataSetDefinition="Feature Data 2"/>
     <ld:dsdefrule match="^DTL$"                  dataSetDefinition="GML Source"/>
     <ld:dsdefrule match="^EXEC$"                 dataSetDefinition="Execs"/>
     <ld:dsdefrule match="^H$"                    dataSetDefinition="H"/>
     <ld:dsdefrule match="^JCL$"                  dataSetDefinition="JCL"/>
     <ld:dsdefrule match="^LMOD$"                 dataSetDefinition="Link-edit control files"/>
     <ld:dsdefrule match="^MAC$"                  dataSetDefinition="Macros"/>
     <ld:dsdefrule match="^MAC.ALLAGMAC$"         dataSetDefinition="FEATURE Macros"/>
     <ld:dsdefrule match="^OPTIONS$"              dataSetDefinition="Options"/>
     <ld:dsdefrule match="^PLI$"                  dataSetDefinition="Source code"/>
     <ld:dsdefrule match="^PLMOD$"                dataSetDefinition="Pre-Link control files"/>
     <ld:dsdefrule match="^PLX$"                  dataSetDefinition="Source code"/>
                 

   • Run Projects.Metadata.Resolve.xml

     Run the Projects.Metadata.Resolve.xml as an Ant build. Right click on the file and select "Run As" then "Ant Build..."

     Ensure that in the JRE tab the Runtime JRE is set to "Run in the same JRE as the workspace". Then click "Run" to run the XML.

     Once the XML has been run all of the metadata will have been updated for the parts. Check these changes in. You can delete the repository workspace and run again from the beginning, until you have the required project structure you need.

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.