Mass import tool mapping file format

You must follow certain formatting rules when you create a mapping file for the mass import tool.

The mapping file is line-delimited, wherein each line must follow this format: <identifier character>: <key> = <value>. The following table indicates possible line combinations.Mass import line combinations
Identifier Key Value Notes
C4,5 zComponent project name Jazz® component name Specifies to which Jazz Component a zComponent project belongs. zComponent projects that do not match project name rules that are specified in the mapping file cannot be imported.
P1,3,4,5 Fully qualified member name (not including HLQ) zComponent project name [:zFolder name] Specifies to which zComponent projects PDS members are imported. You can use wildcards in the key, indicated by an asterisk (*), to specify multiple members to put into the same zComponent project. Any member that does not match a member name rule that is specified in the mapping file cannot be imported.
L1,2,4 Fully qualified member name (not including HLQ) Language definition name [:file suffix] Specifies a language definition to associate with imported members. Remember: The language definition must exist in the project area. You can use wildcards (*) in the key to specify multiple members to associate with a language definition.
U1,4 Fully qualified member name (not including HLQ) User property names and values in the format propertyName:propertyValue separated by a semi-colon (;). Identifies sets of Jazz source control user property pairs (name and value) to associate with the imported data set members. You can use wildcards (*) in the key to specify multiple members to associate with user properties.
X1,4 Fully qualified member name (not including HLQ) none Specifies members to exclude from the mass import. You can use wildcards (*) in the key to specify multiple members to exclude. Any member that matches the key is not imported.
Important:
  1. For the P, L, U, and X identifiers, members are referenced by using pattern-matching strings that consist of the name of the PDS (without the HLQ), followed by a period, followed by the member name. For example, member HELLO in PDS SMITH.TEST.COBOL would be matched by the pattern TEST.COBOL.HELLO. The pattern TEST.COBOL.* would match any members in the data set named SMITH.TEST.COBOL.
    Note: You must be careful if you want to assign a different language definition to two PDS members that include a wildcard (*) and, therefore, match the same mapping rule. Such is the case, for example, with PDS members that are named TEST.OPC and TEST.OPCETT.
    The first solution is to enter the most specific PDS member first. For example, enter the two following lines, in the following order: 
    L:TEST.OPCETT(*)=CFL AAIB OPCETT:txt
L:TEST.OPC(*)=CFL AAIB OPC:txt
    The other solution is to enter a period (.) before the wildcard (*): 
    L:TEST.OPC.(*)=CFL AAIB OPC:txt
L:TEST.OPCETT.(*)=CFL AAIB OPCETT:txt

    You can substitute an alias data set name in place of the name of the PDS. For example, if you define an alias data set name of SMITH.TO.IMPORT, which refers to the actual dataset SMITH.TEST.COBOL, member HELLO in PDS SMITH.TEST.COBOL could be matched by the pattern TO.IMPORT.HELLO.

  2. For the L identifier, by default, members are imported as zFiles with the same name as the member. You can specify a language definition name such as:
    L:TEST.COBOL.*=COBOL:cbl
    When you append such a file extension, like .cbl, for example, two things happen:
    1. Language definition COBOL is associated with any members that match the rule.
    2. .cbl is appended to the file name of the zFiles you imported.
  3. For the P identifier, by default, zimport imports members from a PDS to the specified zComponent project into a zFolder with the same name as the PDS. You can change the name of the zFolder by adding a colon (:) and a different zFolder name after the name of the zComponent project. For example, if you want to import all members from a PDS named MORT.BLD.TEST to zComponent project MortgageApp under a zFolder named MORT.BLD, the mapping file rule is P:MORT.BLD.TEST.*=MortgageApp:MORT.BLD.
  4. For all identifiers, you can also make back references in any line in the mapping file by using parentheses in the key and %n in the value. For example, if you want to import all the members in any PDS named MORT.BLD.TEST to a zComponent project named MORTApp in zFolders named whatever is between MORT. and .BLD, you can write the rule as P:(MORT).(*).BLD.TEST.*=%1App:%2.
  5. For the C and P identifiers, a zComponent Project name cannot contain imbedded blanks.
The following restrictions apply to mapping file rules:
  • The mass import tool ignores blank lines.
  • The mass import tool ignores lines that begin with the number sign (#).
  • Lines must adhere to the following format, where rule-type must either be the character P, the character C, the character L, the character X, or the character U:
    rule-type:key=value
    • P indicates that the rule maps a qualified member name to the zComponent project and, optionally, to the zFolder where it is placed.
      Notes:
      • After the P rule, you have the option of specifying a zFolder to which to import the member. Add [:zFolder] after the P rule, but replace zFolder with the name of the folder where you want to import the member. Such a line might look be written as P:TEST.COBOL.HELLO=MyProject:MyFolder
      • A qualified member name is one that is qualified by the name of the data set you want to contain it; for example, if you want to import member HELLO into data set SMITH.TEST.COBOL, the qualified member name you specify for the P rule would be TEST.COBOL.HELLO.
      Attention: The qualification of the member name in the P rule does not include the high-level qualifier (HLQ).
    • C indicates that the rule maps a zComponent project to the Jazz component to contain it.
      Important: If the zComponent project into which members are imported does not match any C rules, those members are not imported.
      Attention: Do not target the same Jazz component when running multiple instances of the zimport command simultaneously. Doing so could result in a Contents are out of sync with the workspace error.
    • L indicates that the rule maps a qualified member name (without a high-level qualifier) to the name of a language definition to associate with it.
      Note: After the L rule, you have the option of specifying a file suffix to append to the imported zFile. Add [:file suffix] after the L rule, but replace the file suffix with the file extension you want to append to the zFile. Such a line might look similar to L:TEST.COBOL.*=COBOL:cbl.
      Important: The specified language definition must exist in the project area that you specified on the command line. Specifying language definitions for imported members is optional, and members without an associated language definition can still be imported.
    • U indicates that the rule maps a qualified member name (without a high-level qualifier) to a set of Jazz source control user properties to associate with it.
      Important: The set of user properties, which can be reduced to only one user property, to associate to the member in the format propertyName:propertyValue, separated by a semi-colon (;). The user property value is optional, in this case a user property with an empty value is associated to the member. Such a U line might look similar to U:TEST.COBOL.(*)=Property_A:value-for-Property_A;Prop_B;Prop_C:value_C;fileName:%1.
    • X indicates members to exclude from the mass import. The matching for the keys of the X rule works the same as the matching for the P rule. The qualification of the member name in the X rule does not include the high-level qualifier (HLQ).
      Important: Any member that matches the X key rule is not imported.
The contents of a mapping file might look like the following example:
# Member to zComponent project mappings
# Specify the zComponent project and, optionally, the zFolder that will 
# contain the imported members.
# 
# Format:
# P:<member>=<zComponent project>[:<zFolder>] 
P:MORTGAGE.*.(*).*=MortgageApp:%1
P:ALL.COBOL.*CALC=CalcApp:CobolSrc 
P:ALL.COBOL.ATM*=ATMApp:CobolSrc
# zComponent project to Jazz Component mappings
# Specify the Jazz Component that each zComponent project will be shared to. 
# 
# Format: 
# C:<zComponent project>=<Jazz Component> 
C:MortgageApp=Mortgage 
C:CalcApp=Sample Applications
C:ATMApp=Sample Applications  
#
# Member to Language Definition mappings
# Optionally specify the Language Definition to associate with imported members. 
# 
# Format:
# L:<member>=<Language Definition name> 
L:*.COBOL.*=COBOL:cbl
L:*.JCL.*=JCL
#
# User property
# Format:
# U:<member>=<name>[:value>][;<name>[:<value>]]
U:*.COBOL.*=Prop_A:value_A
#
# Exclusion rules
# List members not to import
#
# Format:
# X:<member>
X:*.OBJ.*
If you run the zimport command for a PDS named SMITH.MORTGAGE.BLD.COBOL, indicate SMITH as the --hlq option of zimport, and specify the mapping file rule P:MORTGAGE.BLD.COBOL.*=MortgageApp, all of the contents of SMITH.MORTGAGE.BLD.COBOL is imported into a zComponent project named MortgageApp, inside a zFolder named MORTGAGE.BLD.COBOL. If, instead, you specify mapping file rule P:MORTGAGE.BLD.COBOL.*=MortgageApp:CobolSRC, the zFolder is named CobolSRC.
Note: You can save your mapping file anywhere on your HFS. When you run the zimport command, you specify the file path of the mapping file by using the --mapfile option.