The task imports files from z/VM^® based source control systems into the IBM Engineering Workflow Management^® (EWM) source control system so that the files are accessible to Enterprise Extensions^® (EE) build facilities.

There are two pairs of functions that can perform: EXTRACT and DELIVER or EXTRACT_UPDATE and DELIVER_UPDATE. An EXTRACT function extracts source code from z/VM and formats it for the EWM source control system. A DELIVER function delivers the extracted code to the specified EWM stream.

`EXTRACT`

The EXTRACT function is used to initially import z/VM based source control into EWM source control. It assumes that the z/VM based source control content is not presently in EWM or that the current copy can be overlaid. It is meant to be used for a complete migration of the z/VM based source control content into EWM. EXTRACT can be run repeatedly, but each time it is run, it will completely replace the previous copy of the imported source. EXTRACT performs the following tasks:

Create a directory structure for the user-specified components and projects
Populate required EE metadata for each component, project, and zFolder
Download the z/VM source code files described in the specified OBJECTS file
Convert the z/VM source code files from EBCDIC to ASCII to UTF-8 encoding
Optionally format each file based on user-specified formatting control options
Create Ant scripts to define EE translator variables and packaging properties
Organize the files into the proper EWM components, projects, and zFolders

`DELIVER`

The DELIVER function is used to deliver the source code data created by the EXTRACT function to the EWM server. DELIVER performs the following tasks:

Share projects created by EXTRACT
Check-in all of the shared projects
Provide a comment for each change set
Deliver all change sets to the EWM server

`EXTRACT_UPDATE`

The EXTRACT_UPDATE function is used to incrementally import z/VM based source control changes into the EWM source control system. It assumes that the z/VM based source has been loaded into EWM and that only incremental updates to the source need to be processed. The EXTRACT_UPDATE function updates the current copy of the source with the specified changes; it does not replace the current copy. EXTRACT_UPDATE performs the following tasks:

Load the workspace containing the source onto the build machine
Accept all incoming changes to the workspace containing the source
Update all required EE metadata for each component, project, and zFolder
Download the z/VM source code files described in the specified OBJECTS file
Convert the z/VM source code files from EBCDIC to ASCII to UTF-8 encoding
Optionally format each file based on user-specified formatting control options
Update EE System Definition Ant scripts that define variables and properties
Update the source files in the proper EWM components, projects, and zFolders

There are two methods for processing updates: complete and incremental. The complete method imports all of the code using the full OBJECTS file used for the original EXTRACT. This method lets EWM determine what parts have changed and what changes to deliver. The incremental method uses two OBJECTS files, the full OBJECTS file used for the original EXTRACT to determine project layout and contents and an updates OBJECTS file which lists the parts that have changed. This method lets the user determine what parts have changed and what changes to deliver. Specify the zvmRelease attribute when using the complete method and both the zvmRelease and zvmUpdates attributes when using the incremental method.

`DELIVER_UPDATE`

The DELIVER_UPDATE function is used to deliver the source code data created by the EXTRACT_UPDATE function to the EWM server. DELIVER_UPDATE performs the following tasks:

Check-in all of the changes
Provide a comment each change set
Deliver all change sets to the EWM server

Attributes

The task supports Build Extensions Debugging Attributes and Build Extensions General Attributes, as well as, its own task specific attributes. Click on a link for more information on the common attributes.

The following table describes the task specific attributes for the task:

Task Specific Attributes

Attribute Description Required

function

The function that is to perform. Specify one of the four valid functions:

EXTRACT
DELIVER
EXTRACT_UPDATE
DELIVER_UPDATE

Yes

root The root directory for the build. The root directory is where components, projects, and zFolders needed for the migration are created. The value of this attribute is typically ${team.scm.fetchDestination} because that property is built-in when using the Jazz Build Engine. If this attribute is not specified, it will default to the "root" sub-directory of the Ant base directory for the project. For example: if the path to the project is C:\MyFolder\MyProject.xml, the root directory will be C:\MyFolder\root\. No

work The work directory for the build. The work directory is used for temporary files created by . If this attribute is not specified, it will default to the ".work" sub-directory of the root directory. For example: if the root directory is C:\MyFolder\root\ the work directory will be C:\MyFolder\root\.work\. No

doCharsNS

This option controls how "carets" (^) and "not-signs" (¬) are converted from host encoding to the UTF-8 encoding that is used by EWM. Valid values are true and false.

If true, all IBM-1047 "caret" and "not-sign" (¬) characters are converted to UTF-8 "caret" and "not-sign" (¬) characters during the extract process. Do not specify true if the host files are encoded in IBM-037, as "caret" and "not-sign" (¬) characters will be reversed.

If false, all IBM-037 "caret" and "not-sign" (¬) characters are converted to UTF-8 "caret" and "not-sign" (¬) characters during the extract process. Do not specify false if the host files are encoded in IBM-1047, as "caret" and "not-sign" (¬) characters will be reversed.

The default is false.

Without conversion
Encoding	EBCDIC Character	Hex	UTF-8 Character	Hex	EBCDIC Character	Hex	UTF-8 Character	Hex
IBM-037	¬	0x5F	¬	0xAC	^	0xB0	^	0x5E
IBM-1047	¬	0xB0	^	0x5E	^	0x5F	¬	0xAC

With conversion
Encoding	EBCDIC Character	Hex	UTF-8 Character	Hex	EBCDIC Character	Hex	UTF-8 Character	Hex
IBM-037	¬	0x5F	^	0x5E	^	0xB0	¬	0xAC
IBM-1047	¬	0xB0	¬	0xAC	^	0x5F	^	0x5E

doCharsSB

This option controls how square brackets characters ([]) are converted from host encoding to the UTF-8 encoding that is used by EWM. Valid values are true and false.

If true, all IBM-1047 square brackets characters are converted to UTF-8 square brackets characters during the extract process. Do not specify true if the host files are encoded in IBM-037, as square brackets characters will be unusable.

If false, all IBM-037 square brackets characters are converted to UTF-8 square brackets characters during the extract process. Do not specify false if the host files are encoded in IBM-1047, as square brackets characters will be unusable.

The default is false.

Without conversion
Encoding	EBCDIC Character	Hex	UTF-8 Character	Hex	EBCDIC Character	Hex	UTF-8 Character	Hex
IBM-037	[	0xBA	[	0x5B	]	0xBB	]	0x5D
IBM-1047	[	0xAD	Ý	0xDD	]	0xBD	¨	0xA8

With conversion
Encoding	EBCDIC Character	Hex	UTF-8 Character	Hex	EBCDIC Character	Hex	UTF-8 Character	Hex
IBM-037	[	0xBA	Ý	0xDD	]	0xBB	¨	0xA8
IBM-1047	[	0xAD	[	0x5B	]	0xBD	]	0x5D

doCreates This option controls whether or not a directory structure for the components and projects defined in the rtcComponents XML is created when processing an EXTRACT_UPDATE function. Valid values are true and false. Code true when the EXTRACT_UPDATE function is used to deliver new projects to a component. The default is false. When doDeletes is set to true, doCreates should also be set to true. No

doDeletes This option controls whether or not the directory structure for the components and projects defined in the rtcComponents XML is deleted when processing an EXTRACT_UPDATE function. Valid values are true and false. Code true when the EXTRACT_UPDATE function is used to deliver new projects to a component. The default is false. No

doFormats This option controls whether or not source formatting takes place and is a master switch that controls doCharsNS, doCharsSB, doNumbers, doReplace, and doSymbols processing. Valid values are true and false. The default is false. This option must be set to true when doCharsNS, doCharsSB, doNumbers, doReplace, or doSymbols is enabled to have the source formatting take place. No

doNumbers This option controls whether or not sequence numbers are removed from source code files. Valid values are true and false. If true, sequence numbers are removed during the extract process. The default is false. No

doReplace This option controls whether or not DTL compiler attributes are replaced in ISPF panel files. Valid values are true and false. If true, DTL compiler attributes are replaced with printable characters during the extract process. The default is false. No

doSymbols This option controls whether or not symbolic replacements are performed on source code files. Valid values are true and false. If true, symbolic replacements are performed during the extract process. The default is false. No

doSymbolsTesting This option controls whether or not test symbols are included in the symbolic replacement process. Valid values are true and false. If true, symbolic replacements, which include test symbols, are performed during the extract process. The default is false. No

doWorkspaceDeliver This option controls whether or not a workspace deliver is issued for the DELIVER_UPDATE function. Valid values are true and false. Code true to deliver the entire workspace when the DELIVER_UPDATE function is processed. The default is false, only changed components will be delivered when processing a DELIVER_UPDATE function. No

failOnCnfError This option controls whether or not the build fails when an error is encountered in the configuration data. Valid values are true and false. Specify true to fail the build when an error in the configuration data is encountered. Specify false (the default) to ignore the error and continue the build. No

fileOnScmError This option controls whether or not the build fails when an SCM error is encountered. Valid values are true and false. Specify true to fail the build when an SCM error is encountered. Specify false (the default) to ignore the error and continue the build. No

requestThreadCnt This option controls the number of files processed by an EXTRACT thread. Specify an integer between 1 and 1000. The default is 100. Values larger than 1000 are limited to 1000. Use the requestThreadCnt and requestThreadMax to tune the EXTRACT process. No

requestThreadMax This option controls the number of concurrent threads used by the EXTRACT process. Specify an integer between 1 and 32. The default is 6. Values larger than 32 are limited to 32. Use the requestThreadCnt and requestThreadMax to tune the import process. No

requestTimeoutInt This option controls the time out interval on a EXTRACT process thread. Specify an integer between 1 and 600. The default is 120. Values larger than 600 are limited to 600. This setting controls how long the EXTRACT process will wait for a thread to complete processing before giving up and ending the process. A thread completes when it has processed all assigned files. The number of files assigned to a thread is controlled by the requestThreadCnt attribute. No

rtcCheckinOnly This option controls whether or not the DELIVER and DELIVER_UPDATE processes actually deliver the changes to the EWM server. Valid values are true and false. Code true to stop the delivery process after the changes are checked in. The default is false. This option should be used only when debugging the deliver process. No

rtcComponents Specifies the fully qualified path on the build engine to the components XML file. Yes

rtcPassword Specifies the encrypted password to use when logging into the EWM server. Yes

rtcProcessArea

Specifies the name of an EWM process area where the source control stream and components are defined.

Process areas are specified in path form: the first segment should be the name of the project area, the following segments should be the names of team areas. In the simplest case, where the process area is the project area, simply specify the project area name. In more complex cases, where the process area is in a project team area, specify the project area name ("zVMImportTests") and the team area name ("zVMImportTests.team.area") in path form with a forward slash separating the names. For example:

zVMImportTests/zVMImportTests.team.area

Yes

rtcScmConfig Specifies the fully qualified path on the build engine to the SCM configuration directory. This attribute is optional. The default location is: user_home/.jazz-scm No

rtcScmTool Specifies the fully qualified path on the build engine to the SCM module. Yes

rtcServer Specifies the address of the team repository to use. The value of this attribute is typically ${repositoryAddress} because that property is built-in when using the Jazz Build Engine. Yes

rtcStream Specifies the name of the EWM stream where components and changes are delivered.
Note: The stream specified here must be owned by the specified rtcProcessArea. Yes^D

rtcUser Specifies the user ID for authentication to the repository. Yes

rtcWorkspace Specifies the name of the workspace to use. The specified workspace name must identify a workspace that exists and is unique.
Note: The workspace specified here must be owned by the specified rtcUser. Yes

zvmCodePage Specifies the name of the z/VM FTP code page to use when retrieving a file. The default is WW200037, the IBM-037 code page. Specify WW201047, or an equivalent, for the IBM-1047 code page. No

zvmHost Specifies the URL of the z/VM host. Yes^E

zvmLanguageXml Specifies the fully qualified path on the build engine to the languages XML file. Yes^E

zvmObjectsDisk Specifies the z/VM VDEV (virtual device address) for the disk that contains OBJECTS file. This VDEV should be linked in the directory entry for the specified zvmUser. When FTP transfers a file from z/VM, it is referenced by filename and filetype on minidisk "zvmUser.vdev". Therefore, all VDEV attributes specified here must be included in the zvmUser directory entry. Note: the minidisk need not be owned by the zvmUser, all that is required is that the zvmUser have a link to the minidisk in their directory entry. Yes^E

zvmPassword Specifies the encrypted password to use when logging onto the z/VM system. Yes^E

zvmProductBase Specifies the z/VM VDEV (virtual device address) for the product base disk. When FTP transfers a file from z/VM, it is referenced by filename and filetype on minidisk "zvmUser.vdev". Therefore, all VDEV attributes specified here must be included in the zvmUser directory entry. Yes^E

zvmProductDisk Specifies the z/VM VDEV (virtual device address) for the product disk. When FTP transfers a file from z/VM, it is referenced by filename and filetype on minidisk "zvmUser.vdev". Therefore, all VDEV attributes specified here must be included in the zvmUser directory entry. Yes^E

zvmRelease Specifies the z/VM filename for the OBJECTS file. Yes^E

zvmSymbols Specifies the fully qualified path on the build engine to the symbols file. No

zvmUpdatesFile Specifies the z/VM filename for the updates OBJECTS file for an EXTRACT_UPDATE function. No

zvmUser Specifies the user ID for authentication to the z/VM system. Yes^E

^ERequired for EXTRACT only.
^DRequired for DELIVER only.

Languages XML File

The Languages XML file describes the languages that will be extracted and delivered by . The Languages XML file has two elements: <languages> and <language>. The <languages> element is a container for any number of <language> elements. A language element describes how zVMIport will process a language file. Each language included in the import needs to be described in the Languages XML file. The following table describes the valid values for the language element attributes:

Languages XML File

Attribute Description Required

type Language type. User defined. Yes

subtype Language subtype. User defined. Yes

fileExtension Language file extension. User defined. Yes

fileDirectory Language file directory (folder). User defined. This is the name of the zFolder where the file should be placed. This folder will have a parent folder of zOSsrc. Yes

fileFolderMcs Default MCS part type for folder. Valid MCS part type. For example: ++MOD. See SMP/E documentation for more information on valid MCS (Modification Control Statement) part types. Yes

fileFolderUpd Default source update setting for folder. Valid values are true and false. Yes

fileLineFilter This option controls whether or not FTP filtering takes place for DTL compiler attributes which are to be replaced in ISPF panel files. Valid values are true and false. If true, DTL compiler attributes are replaced with printable characters during the extract process. The default is false. Set doReplace to true when using this option. Yes

fileLongRecord Specifies that files associated with the language will have records longer than 80 characters. Valid values are true and false. Yes

compilerParms

Specifies that files associated with the language will have a compiler CMPRENT parameter. Valid values are true and false.

When this attribute is set to true and the file has a reusType value of E or N, an entry will be created in the Enterprise Extensions System Definitions script created by to define a CMPRENT translator variable, team.enterprise.build.var.CMPRENT, for the file with a value of RENT.

This variable can be used with compiler translators to set RENT/NORENT parameters for the compiler for individual files. Set the default value of CMPRENT to NORENT and use the overrides created by to set the value to RENT when needed.

Yes

formattingOpt

Language formatting option. Valid values are:

Type:	Description:
ASSEMBLE	Assembler language source file
C	C language source file
CLIST	CLIST source file
COBOL	COBOL language source file
COPY	Assembler language COPY file
DTL	DTL ISPF panel source
JCL	Job control language source
MACRO	Assembler language MACRO file
MESSAGE	ISPF message file
NONE	No associated language
PANEL	ISPF panel file
PLI	PLI language source file
PLX	PLX language source file
REXX	REXX source file
SCRIPT	SCRIPT source file
SKELETON	ISPF skeleton file
XML	XML source file
XSD	XSD source file

Yes

linkEditAmode

Specifies that files associated with the language will have a link edit AMODE=31 parameter added to their packaging link edit parameter. Valid values are true and false.

When this attribute is set to true and the packageLEParm attribute is set to true, the value of the file packaging property, team.enterprise.packaging.file.linkparm, for the file will have an AMODE=31 parameter added to the parameter string. For example:

AMODE=31,NCAL,LIST,REUS=SERIAL,XREF.

Yes

packageLEParm

Specifies that files associated with the language will have a packaging link edit parameter. Valid values are true and false.

When this attribute is set to true and the file has a reusType value of E, an entry will be created in the Enterprise Extensions System Definitions script created by to define a file packaging property, team.enterprise.packaging.file.linkparm, with a value of: NCAL,LIST,REUS=REFR,XREF.

If the file has a reusType value of N, the value will be set to: NCAL,LIST,REUS=RENT,XREF.

If the file has a reusType value of U, the value will be set to: NCAL,LIST,REUS=SERIAL,XREF.

Yes

Example

Components XML File

The Components XML file describes the EWM components and projects that will be populated by . The Components XML file has five elements: <components>, <component>, <group>, <projects>, and <project>.

<components> element

The components element is a container for any number of component elements.

<component> element

A component element describes an EWM component to . The component element has one required attribute, name, which defines the name of the component and one optional attribute, prefix, which defines the prefix for project names. If the prefix attribute is omitted, the value of the name attribute will be used as the prefix for project names. Please note that when the value of the name attribute is used as the prefix for project names, all blanks are removed from the name and the name is translated to lower case.

For example, the following will result in a component named "Some component name" with a "base" project named "com.ibm.bpe.base":

<component name="Some component name" prefix="com.ibm.ims.bpe">
  <project id="BP" name="base"/>
</component>

<project> element

The project element describes an Eclipse^® project to . Every project referenced by an import needs to be described by a project element. The project element has three attributes id, name, and ignore, which define: the two-character ID of the project as coded in the OBJECTS file, the final token in the name of the project, and whether or not to ignore OBJECTS file entries assigned to the project.

The following definition creates a component named "com.ibm.ims.bpe" with one project named "com.ibm.ims.bpe.base":

<component name="com.ibm.ims.bpe">
  <project id="BP" name="base"/>
</component>

<group> element

The optional group element describes a group of eclipse projects to . The group element has one required attribute, name, which defines the name of the group and one optional attribute, prefix, which defines a prefix for project names. If the prefix attribute is omitted, the value of the name attribute will be used as a prefix for project names. Please note that when the value of the name attribute is used as the prefix for project names, all blanks are removed from the name and the name is translated to lower case.

The following definition creates a component named "com.ibm.ims.sci.base" with two projects named "com.ibm.ims.sci.base.system" and "com.ibm.ims.sci.base.services":

<component name="com.ibm.ims.sci">
  <group name="base">
    <project id="SI" name="system"/>
    <project id="CZ" name="services"/>
  </group>
</component>

The following definition illustrates the use of the prefix attribute with the same definition. It creates a component named "SCI Base" with two projects named "com.ibm.ims.sci.base.system" and "com.ibm.ims.sci.base.services":

<component name="com.ibm.ims.sci">
  <group name="SCI Base" prefix="base">
    <project id="SI" name="system"/>
    <project id="CZ" name="services"/>
  </group>
</component>

<projects> element

The projects element describes a set of Eclipse projects to . The projects element has one attribute, name, which defines the intermediate name token of the projects.

The following definition creates a component named "com.ibm.ims.sci" with two projects named "com.ibm.ims.sci.base.system" and "com.ibm.ims.sci.base.services":

<component name="com.ibm.ims.sci">
  <projects name="base">
    <project id="SI" name="system"/>
    <project id="CZ" name="services"/>
  </projects>
</component>

Example

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="com.ibm.team.enterprise.smpe.toolkit.zimport.components"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="com.ibm.team.enterprise.smpe.toolkit.zimport.components zimport.components.xsd">
  <component name="com.ibm.ims.core">
    <group name="db">
      <project id="CA" name="catalog"/>
      <project id="CB" name="controlblock"/>
      <project id="CS" name="commonservices"/>
      <project id="DL" name="locking"/>
      <project id="DM" name="commonmacros"/>
      <project id="DS" name="sharing"/>
      <project id="DT" name="ddlt0"/>
      <project id="UT" name="utilities"/>
      <project id="GS" name="gsam"/>
      <project id="HD" name="haldb"/>
      <project id="IS" name="ioservices"/>
      <project id="RR" name="rsr"/>
      <project id="XR" name="xrf"/>
    </group>
    <group name="dbrc">
      <project id="RB" name="base"/>
      <project id="RC" name="commands"/>
      <project id="RE" name="services"/>
      <project id="RG" name="groupservices"/>
      <project id="RH" name="haldbdefinition"/>
      <project id="RI" name="api"/>
      <project id="RO" name="recon"/>
      <project id="RS" name="system"/>
      <project id="RX" name="rsr"/>
    </group>
    <group name="fp">
      <project id="Z1" name="controlblockslogrecs"/>
      <project id="Z2" name="dedb"/>
      <project id="Z3" name="msdb"/>
      <project id="Z4" name="commands"/>
      <project id="Z5" name="inittermschedule"/>
      <project id="Z6" name="misc"/>
      <project id="Z7" name="traceformatterdiagnostics"/>
      <project id="Z8" name="utilitiesother"/>
      <project id="Z9" name="buffermanagement"/>
      <project id="ZA" name="dedbalter"/>
      <project id="ZB" name="checkpointrestart"/>
      <project id="ZC" name="fpsi"/>
      <project id="ZD" name="openclosecommit"/>
      <project id="ZE" name="rsr"/>
      <project id="ZF" name="vsosvso"/>
      <project id="ZG" name="emhsemhmessage"/>
    </group>
    <group name="oa">
      <project id="DB" name="base"/>
      <project id="FD" name="fdr"/>
      <project id="OD" name="odba"/>
      <project id="RT" name="restart"/>
      <project id="SQ" name="sql"/>
    </group>
    <group name="ras">
      <project id="DI" name="diagnose"/>
      <project id="VC" name="dump"/>
      <project id="TR" name="trace"/>
      <project id="OP" name="ignore.1" ignore="true"/>
      <project id="TT" name="ignore.2" ignore="true"/>
      <project id="XX" name="ignore.3" ignore="true"/>
    </group>
    <group name="sys">
      <project id="AX" name="aoi"/>
      <project id="CD" name="commands"/>
      <project id="CM" name="macros"/>
      <project id="DD" name="drd"/>
      <project id="DP" name="dispatcher"/>
      <project id="IN" name="install"/>
      <project id="IQ" name="sharedqueues"/>
      <project id="LG" name="logger"/>
      <project id="LU" name="latchusemanager"/>
      <project id="OL" name="olc"/>
      <project id="QM" name="queuemanager"/>
      <project id="RL" name="RSR"/>
      <project id="SB" name="batch"/>
      <project id="SM" name="storagemanager"/>
      <project id="SR" name="restart"/>
      <project id="SS" name="services"/>
      <project id="ST" name="statistics"/>
      <project id="SU" name="utilities"/>
      <project id="TI" name="timeservices"/>
      <project id="UX" name="userexits"/>
    </group>
    <group name="tm">
      <project id="AP" name="appc"/>
      <project id="MS" name="msc"/>
      <project id="OS" name="isc"/>
      <project id="OT" name="otma"/>
      <project id="OI" name="otmaci"/>
      <project id="TC" name="commonservices"/>
      <project id="TM" name="base"/>
      <project id="TS" name="sysgen"/>
      <project id="TU" name="utilities"/>
      <project id="VT" name="vtam"/>
    </group>
    <group name="ui">
      <project id="AS" name="asn"/>
      <project id="DF" name="dumpformatter"/>
      <project id="DR" name="rdds"/>
      <project id="IV" name="ivp"/>
      <project id="SC" name="syntaxchecker"/>
      <project id="SP" name="spoc"/>
      <project id="UB" name="base"/>
    </group>
  </component>
  <component name="com.ibm.ims.bpe">
    <project id="BP" name="base"/>
  </component>
  <component name="com.ibm.ims.cqs">
    <project id="CQ" name="base"/>
  </component>
  <component name="com.ibm.ims.om">
    <project id="OM" name="base"/>
  </component>
  <component name="com.ibm.ims.rm">
    <project id="RM" name="base"/>
  </component>
  <component name="com.ibm.ims.rp">
    <project id="RP" name="base"/>
  </component>
  <component name="com.ibm.ims.sci">
    <projects name="base">
      <project id="SI" name="system"/>
      <project id="CZ" name="services"/>
    </projects>
  </component>
  <component name="com.ibm.ims.icon">
    <project id="IC" name="base"/>
  </component>
</components>

Symbols File

The Symbols file describes symbolic replacements that are to be performed on strings in the source code files as they are processed by . Each line in the Symbols file describes one replacement value. The first token in the line is a user-defined control character, which is entered in column one and followed by a blank. User-defined control characters are not referenced by , and therefore, may be any non-blank value other than an an asterisk. The second token in the line is the search string and the third token in the line is the symbolic replacement value. Comment lines can be included in the Symbols file by coding an asterisk in the first column.

Symbolic replacements can be used to dynamically update the code as it is being built. Refer to Ant <filter> or <replacefilter> documentation for more information.

In the following example

"A" is the control character
"5635-A04" is the search string
"@prodid@" is the symbolic replacement value

Standard Symbols File

A 5635-A04 @prodid@

The Symbols file can be set up for testing symbolic replacements. To accomplish this, add a fourth token to each line with one of two values: BASE or TEST. Symbolic replacements designated as BASE will always be performed. Symbolic replacements designated as TEST will only be performed when the doSymobolsTesting attribute is set to true.

Testing Symbols File

A 5635-A04 @prodid@ BASE
A 9999-999 @prodid@ TEST

`OBJECTS` File

The OBJECTS file provides an inventory of z/VM source files to be processed by . The OBJECTS file is maintained on the z/VM host and downloaded by to determine what z/VM files to process and their location on the z/VM host. The OBJECTS file should contain one line for each file that is to be processed. Comment lines can be included in the OBJECTS file by coding an asterisk in the first column. The following table describes the layout of the OBJECTS file. All columns must have a non-blank value. The columns contain the following information:

OBJECTS File Layout

# Column Description Required

1 fileName The name of the z/VM file. Yes

2 fileType The type of the z/VM file. Yes

fileDisk

The disk where the z/VM file is located. Valid values are:

Value:	Description:
B	Specifies the z/VM VDEV for the product base disk. Refer to the zvmProductBase attribute description above for more information.
P	Specifies the z/VM VDEV for the product disk. Refer to the zvmProductDisk attribute description above for more information.
O	Specifies the z/VM VDEV for the disk that contains `OBJECTS` file. Refer to the zvmObjectsDisk attribute description above for more information.

Yes

transferType

Specifies the transfer type for the file. Valid values are:

Value:	Description:
T	Text
B	Binary

Yes

5 projectId The 2-character project ID for the file. Refer to your Components XML File for valid values. Yes

6 languageType The language type for the file. Refer to your Languages XML File for valid values. Yes

7 languageSubType The language subtype for the file. Refer to your Languages XML File for valid values. Yes

8 fmidId The FMID ID for the file. If specified, an entry will be created in the System Definitions script created by to create a file-level override for the FMID ID setting. Specify a dash (-) to use the default FMID ID for the file. Yes

9 mcsPartType The MCS part type for the file. If the file MCS part type does not match the folder MCS part type, an entry will be created in the System Definitions script created by to create a file-level override for the MCS part type setting. Refer to your Languages XML File for the folder MCS part type setting. Specify a dash (-) to use the default MCS part type for the file. Yes

reusType

The link-edit re-usability option for the module. Valid values for reusType are:

Value:	Description:
-	Not applicable
E	`REFRESHABLE`
N	`REENTRANT`
U	`REUSABLE`

This attribute controls the value of the LNKREUS translator variable. When this attribute is set to E, N, or U, an entry will be created in the System Definitions script created by to define a LNKREUS translator variable, team.enterprise.build.var.LNKREUS, for the file with a value of REFR for E, RENT for N, and SERIAL for U. This variable can be used with compiler translators to set REUS parameter for the linkage editor. Set the default value of LNKREUS to NONE and use the overrides created by to set the other values when needed.

Yes

sourceUpdate

The source update setting for the file. If the file source update setting does not match the folder source update setting, an entry will be created in the System Definitions script created by to create a file-level override for the source update setting. Refer to your Languages XML File for the folder source update setting. Valid values are:

Value:	Description:
T	File is maintained via source updates (true).
F	File is not maintained via source updates (false).

This attribute controls the value of the team.enterprise.packaging.file.sourceupdate file property. This property is used to override language settings for source updatable parts.

Yes

12 languageDefinition The name of the EWM Enterprise Extensions language to associate with the file. An entry will be created in the System Definitions script created by to explicitly associate the file with an EWM Enterprise Extensions language. Specify a dash (-) to use the default language for the file. Do not specify language names with embedded blanks. Yes

lineDelimiter

The type of line delimiter to use for the file. The default setting for line delimiter is Platform. If the file uses a line delimiter other than Platform, specify the value here and an entry will be created in the System Definitions script created by to set the line delimiter value for the file. Valid values for lineDelimiter are:

Value:	Description:
-	Use default.
None	Binary file
CR	Text file with carriage returns
LF	Text file with line feeds
CRLF	Text file with carriage returns and line feeds
Platform	Text file that adjusts line delimiter based on the current platform

Yes

codePage

The name of the code page to use for the file. If a code page is specified, an entry will be created in the System Definitions script created by to set an mvsCodePage property for the file. Valid values for codePage are:

Value:	Description:
-	Use default.
`gb2312` `Big5` `eucJP` `euc-kr` `IBM-037` `IBM-1047` `ISO-8859-1` `ISO-8859-2` `windows-1251`	Name of the code page. The listed code pages are examples. Any valid code page can be specified.

Yes

encoding

The name of the encoding to use for the file in the Eclipse environment. Valid values for encoding are:

Value:	Description:
-	Use default.
`gb2312` `Big5` `eucJP` `euc-kr` `IBM-037` `IBM-1047` `ISO-8859-1` `ISO-8859-2` `windows-1251`	Name of the encoding to use. The listed encoding values are examples. Any valid encoding can be specified.

Yes

Example

BPEAQHE  IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAQHTU IMSBLD.HMK1400S.MAC                          P T BP COPY     -    -  -      - F -            -        -
BPEAQHT0 IMSBLD.HMK1400S.ASM                          P T BP ASSEMBLE -    -  ++MOD  - F -            -        -
BPEATTCH IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWCR0 IMSBLD.HMK1400S.PLX                          P T BP PLX370   -    -  ++MOD  E F -            -        -
BPEAWDEF IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWE   IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWEAT IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWELD IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWETM IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWEXT IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWIX  IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWIXU IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWI00 IMSBLD.HMK1400S.PLX                          P T BP PLX370   -    -  ++MOD  E F -            -        -
BPEAWSRV IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEAWSV0 IMSBLD.HMK1400S.PLX                          P T BP PLX370   -    -  ++MOD  E F -            -        -
BPEAWS10 IMSBLD.HMK1400S.PLX                          P T BP PLX370   -    -  ++MOD  E F -            -        -
BPEBPCA  IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEBPCRE IMSBLD.HMK1400S.MAC                          P T BP MACRO    -    -  -      - F -            -        -
BPEBPCR0 IMSBLD.HMK1400S.PLX                          P T BP PLX370   -    -  ++MOD  E F -            -        -

Magic Properties File

Certain file extensions do not automatically pick up the desired line delimiter and encoding by default. The Magic Properties file addresses this issue by describing file properties to EWM during initial check-in. The Magic Properties file contains rules that specify:

MIME type
line delimiters
encoding

for all files matching a given pattern. The general syntax is that of a property file, with the pattern acting as the key, followed by zero or more keywords indicating the values for matching patterns. For example, to define the "asm" extension to use a MIME of "text/plain", a "Platform" line delimiter, and encoding of UTF-8, the magic.properties file entry would be:

*.asm: encoding: UTF-8; mime: text/plain; delim: platform

The placement of the magic.properties file is discussed in the article, SCM Magic File, on jazz.net. In brief, the magic.properties should be placed according to the following table:

System:	Location:
UNIX and Linux	~/.jazz-scm/
Windows	LOCALAPPDATA\jazz-scm\
Windows 7	C:\Users\userid\AppData\Local\jazz-scm\

Example

*.asm: encoding: UTF-8; mime: text/plain; delim: platform
*.asmisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.asmsmpl: encoding: UTF-8; mime: text/plain; delim: platform
*.asmsrc: encoding: UTF-8; mime: text/plain; delim: platform
*.bnd: encoding: UTF-8; mime: text/plain; delim: platform
*.bnd370: encoding: UTF-8; mime: text/plain; delim: platform
*.bnd390: encoding: UTF-8; mime: text/plain; delim: platform
*.c: encoding: UTF-8; mime: text/plain; delim: platform
*.cpl: encoding: UTF-8; mime: text/plain; delim: platform
*.cisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.csmpl: encoding: UTF-8; mime: text/plain; delim: platform
*.c370: encoding: UTF-8; mime: text/plain; delim: platform
*.c390: encoding: UTF-8; mime: text/plain; delim: platform
*.c390pl: encoding: UTF-8; mime: text/plain; delim: platform
*.c390isrc: encoding: UTF-8; mime: text/plain; delim: platform
*.c390smpl: encoding: UTF-8; mime: text/plain; delim: platform
*.clst: encoding: UTF-8; mime: text/plain; delim: platform
*.cbl: encoding: UTF-8; mime: text/plain; delim: platform
*.cblisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.cblsmpl: encoding: UTF-8; mime: text/plain; delim: platform
*.cpy: encoding: UTF-8; mime: text/plain; delim: platform
*.cpyisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.cpysmpl: encoding: UTF-8; mime: text/plain; delim: platform
*.cpysrc: encoding: UTF-8; mime: text/plain; delim: platform
*.data: encoding: UTF-8; mime: text/plain; delim: platform
*.dataisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.datasmpl: encoding: UTF-8; mime: text/plain; delim: platform
*CSLOTCHS.databin: encoding: gb2312; mime: application/octet-stream; delim: none
*CSLOTCHT.databin: encoding: Big5; mime: application/octet-stream; delim: none
*CSLOTJPN.databin: encoding: eucJP; mime: application/octet-stream; delim: none
*CSLOTKOR.databin: encoding: euc-kr; mime: application/octet-stream; delim: none
*CSLOTPOL.databin: encoding: ISO-8859-2; mime: application/octet-stream; delim: none
*CSLOTRUS.databin: encoding: windows-1251; mime: application/octet-stream; delim: none
*.databin: encoding: ISO-8859-1; mime: application/octet-stream; delim: none
*.dtl: encoding: UTF-8; mime: text/plain; delim: platform
*.dtm: encoding: UTF-8; mime: text/plain; delim: platform
*.h: encoding: UTF-8; mime: text/plain; delim: platform
*.hsrc: encoding: UTF-8; mime: text/plain; delim: platform
*.jcl: encoding: UTF-8; mime: text/plain; delim: platform
*.jclin: encoding: UTF-8; mime: text/plain; delim: platform
*.lnk: encoding: UTF-8; mime: text/plain; delim: platform
*.mac: encoding: UTF-8; mime: text/plain; delim: platform
*.macisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.macsmpl: encoding: UTF-8; mime: text/plain; delim: platform
*.macsrc: encoding: UTF-8; mime: text/plain; delim: platform
*.mcscpyrt: encoding: UTF-8; mime: text/plain; delim: platform
*.msg: encoding: UTF-8; mime: text/plain; delim: platform
*.pnl: encoding: UTF-8; mime: text/plain; delim: platform
*.pli: encoding: UTF-8; mime: text/plain; delim: platform
*.pliisrc: encoding: UTF-8; mime: text/plain; delim: platform
*.plismpl: encoding: UTF-8; mime: text/plain; delim: platform
*.plx: encoding: UTF-8; mime: text/plain; delim: platform
*.rexx: encoding: UTF-8; mime: text/plain; delim: platform
*.scr: encoding: UTF-8; mime: text/plain; delim: platform
*.skl: encoding: UTF-8; mime: text/plain; delim: platform
*.tbl: encoding: UTF-8; mime: text/plain; delim: platform
*.xml: encoding: UTF-8; mime: text/plain; delim: platform
*.xsd: encoding: UTF-8; mime: text/plain; delim: platform

Notes

Encrypted passwords can be generated by the zVMPassword task or by the zImportGetPassword Java application. To generate an encrypted password with the zVMPassword task refer to the zVMPassword Task Reference. To generate an encrypted password with the zImportGetPassword Java application, issue the following command from a Windows command prompt window:
```
java -classpath path_to_jar\com.ibm.team.enterprise.smpe.build.scmutilities.jar
  com.ibm.team.enterprise.smpe.toolkit.internal.zimport.util.zImportGetPassword pw
        
```
substituting "path_to_jar" with the actual path to the jar file, "pw" with the actual password, and substituting the jar bundle version (_1.0.0.v20161214_0308) with the one in the version of the toolkit you installed. You will need to navigate to the jar in your file system to get the actual jar name.
The password that is generated is a signed 32-character alphanumeric string. All 32-characters, or 33-characters if a leading minus sign is present, make up the password which must be specified as input to .
If is executed using an Ant build and the Jazz Source Control tab is included in the build definition, exclude all components that are to be imported by from the load process for better performance. loads all components as part of its process. Loading the components with the build results in the components being loaded twice.

Examples

Ant script:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed Materials - Property of IBM
  (c) Copyright IBM Corporation 2014, 2016. All Rights Reserved.
  
  Note to U.S. Government Users Restricted Rights:
  Use, duplication or disclosure restricted by GSA ADP Schedule
  Contract with IBM Corp.
-->
<project
  name="zVMImport"
  default="all"
  xmlns:es="antlib:com.ibm.team.enterprise.smpe.toolkit">
  <description>zVMImport</description>
 
  <!-- Set global properties -->
  <condition property="deliver">
      <equals arg1="${rtc.deliver}" arg2="true"/>
  </condition>
 
  <property name="debugOn"            value="true"/>
  <property name="timerOn"            value="true"/>
  <property name="timer"              value="true"/>
  <property name="trace"              value="true"/>
  <property name="debug"              value="false"/>
  <property name="items"              value="false"/>
 
  <property name="root"               value="${team.scm.fetchDestination}"/>
  <property name="work"               value="${team.scm.fetchDestination}/.work"/>
 
  <property name="doCharsNS"          value="false"/>
  <property name="doCharsSB"          value="false"/>
  <property name="doCreates"          value="true"/>
  <property name="doDeletes"          value="true"/>
  <property name="doNumbers"          value="true"/>
  <property name="doReplace"          value="true"/>
  <property name="doSymbols"          value="false"/>
  <property name="doSymbolsTesting"   value="false"/>
  <property name="doWorkspaceDeliver" value="true"/>
 
  <property name="requestThreadCnt"   value="100"/>
  <property name="requestThreadMax"   value="6"/>
  <property name="requestTimeoutInt"  value="120"/>
 
  <property name="rtcCheckinOnly"     value="false"/>
  <property name="rtcComponents"      value="C:/etc/cnf/zVMImport.components.xml"/>
  <property name="rtcPassword"        value="-166560c9814832497271a936782212b1"/>
  <property name="rtcProcessArea"     value="Dan's PA"/>
  <property name="rtcScmTool"         value="C:/Program Files/IBM/RTC/scmtools/eclipse/scm.exe"/>
  <property name="rtcServer"          value="https://linux235.rtp.raleigh.ibm.com:10443/ccm/"/>
  <property name="rtcStream"          value="Test.zVMImport"/>
  <property name="rtcUser"            value="DREILLY"/>
  <property name="rtcWorkspace"       value="Test.zVMImport.Workspace"/>
 
  <property name="zvmCodePage"        value="WW200037"/>
  <property name="zvmHost"            value="stlvm1.svl.ibm.com"/>
  <property name="zvmLanguageXml"     value="C:/etc/cnf/zVMImport.languages.xml"/>
  <property name="zvmObjectsDisk"     value="395"/>
  <property name="zvmPassword"        value="-166560c9814832497271a936782212b1"/>
  <property name="zvmProductBase"     value="314"/>
  <property name="zvmProductDisk"     value="315"/>
  <property name="zvmRelease"         value="14A"/>
  <property name="zvmSymbols"         value="C:/etc/cnf/zVMImport.symbols"/>
  <property name="zvmUpdatesFile"     value=""/>
  <property name="zvmUser"            value="DJREILLY"/>
 
  <!-- - - - - - - - - - - - - - - - - - - *
  *  zVMImport init                        *
  *- - - - - - - - - - - - - - - - - - - -->
  <target name="init" description="init"/>
 
  <!-- - - - - - - - - - - - - - - - - - - *
  *  zVMImport main                        *
  *- - - - - - - - - - - - - - - - - - - -->
  <target name="main" description="main">
    
    <es:zVMImport
      function="extract"
      root="${root}"
      work="${work}"
      
      doCharsNS="${doCharsNS}"
      doCharsSB="${doCharsSB}"
      doCreates="${doCreates}"
      doDeletes="${doDeletes}"
      doNumbers="${doNumbers}"
      doReplace="${doReplace}"
      doSymbols="${doSymbols}"
      doSymbolsTesting="${doSymbolsTesting}"
      
      requestThreadCnt="${requestThreadCnt}"
      requestThreadMax="${requestThreadMax}"
      requestTimeoutInt="${requestTimeoutInt}"
      
      rtcComponents="${rtcComponents}"
      rtcPassword="${rtcPassword}"
      rtcProcessArea="${rtcProcessArea}"
      rtcScmTool="${rtcScmTool}"
      rtcServer="${rtcServer}"
      rtcStream="${rtcStream}"
      rtcUser="${rtcUser}"
      rtcWorkspace="${rtcWorkspace}"
      
      zvmCodePage="${zvmCodePage}"
      zvmHost="${zvmHost}"
      zvmLanguageXml="${zvmLanguageXml}"
      zvmObjectsDisk="${zvmObjectsDisk}"
      zvmPassword="${zvmPassword}"
      zvmProductBase="${zvmProductBase}"
      zvmProductDisk="${zvmProductDisk}"
      zvmRelease="${zvmRelease}"
      zvmSymbols="${zvmSymbols}"
      zvmUpdatesFile="${zvmUpdatesFile}"
      zvmUser="${zvmUser}"
    />
    
    <antcall target="deliver"/>
  </target>
 
  <target name="deliver" description="deliver" if="deliver">
    
    <es:zVMImport
      function="deliver"
      root="${root}"
      work="${work}"
      
      doWorkspaceDeliver="${doWorkspaceDeliver}"
      
      rtcCheckinOnly="${rtcCheckinOnly}"
      rtcComponents="${rtcComponents}"
      rtcPassword="${rtcPassword}"
      rtcProcessArea="${rtcProcessArea}"
      rtcScmTool="${rtcScmTool}"
      rtcServer="${rtcServer}"
      rtcStream="${rtcStream}"
      rtcUser="${rtcUser}"
      rtcWorkspace="${rtcWorkspace}"
    />
    
  </target>
  
  <!-- - - - - - - - - - - - - - - - - - - *
  *  zVMImport term                        *
  *- - - - - - - - - - - - - - - - - - - -->
  <target name="term" description="term"/>
 
  <target depends="init,main,term" description="manualBuilds" name="all"/>
</project>

getTaskNameHdr()

EXTRACT

DELIVER

EXTRACT_UPDATE

DELIVER_UPDATE

Attributes

Languages XML File

Example

Components XML File

<components> element

<component> element

<project> element

<group> element

<projects> element

Example

Symbols File

Standard Symbols File

Testing Symbols File

OBJECTS File

Example

Magic Properties File

Example

Notes

Examples

`EXTRACT`

`DELIVER`

`EXTRACT_UPDATE`

`DELIVER_UPDATE`

`OBJECTS` File