Ship list files
The ship list file describes the files from the build to include in the new component version to deploy. Ship list files can also use generic artifacts to describe changes that are not physical files, such as configuration changes.
You must create a ship list file before you run the IBM® z/OS® deployment tools. Typically, you write a script that works with your build engine to create a ship list file from the build output. Ship list files are XML files that contain a list of file specifiers.
Partitioned data sets
Partitioned data set (PDS) members are identified by the PDS container type and the PDSmember resource type. You can use an asterisk (*) as a wildcard for the resource name, if you want all members in a partitioned data set to be included in a package.
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="BLD.JCL" type="PDS">
<resource name="BLZCPBTK" type="PDSMember"/>
</container>
<container name="BLD.LOAD1" type="PDS">
<resource name="*" type="PDSMember"/>
</container>
<container name="BLD.LOAD2" type="PDS">
<resource name="ORDRSET" type="PDSMember"/>
<resource name="RDBKC01" type="PDSMember"/>
</container>
</manifest>
Sequential data sets
Sequential data sets are identified by the sequential container type.
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name=" BLD.DATA1" type="sequential">
</container>
</manifest>
HFS files
Hierarchical file system (HFS) files used in z/OS UNIX are identified by the directory container type and the file resource type. Both container name and resource name support the Ant file include pattern. (For more information about Ant, see https://ant.apache.org/.) Each directory container must use the rootDir attribute to identify the root directory to resolve files from. Only files in that root directory are considered.
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="wsbind" rootDir="/u/dave/cicsfiles" type="directory">
<resource name="*.wsbind" type="file"/>
</container>
<container name="wsdl" rootDir="/u/dave/cicsfiles" type="directory">
<resource name="*.wsdl" type="file"/>
</container>
</manifest>
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="." rootDir="/u/dave/cicsfiles" type="directory">
<resource name="**/*" type="file"/>
</container>
</manifest>
To deploy HFS files, use the same plug-in steps as you use to deploy data sets. HFS files and data sets can be put into the same version and deployed or rolled back together.
Deployment types
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="BLD.JCL" type="PDS" deployType="JCL">
<resource name="BLZCPBTK" type="PDSMember"/>
</container>
<container name="BLD.LOAD1" type="PDS" deployType="CICS LOAD">
<resource name="*" type="PDSMember"/>
</container>
<container name="BLD.LOAD2" type="PDS">
<resource name="ORDRSET" type="PDSMember" deployType="CICS LOAD"/>
<resource name="RDBKC01" type="PDSMember" deployType="CICS LOAD"/>
</container>
</manifest>
Custom properties
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="BLD.DBRM" type="PDS">
<property name="COLLID" value="C001"/>
<resource name="MOD01" type="PDSMember">
<property name="devowner" value="Martin"/>
</resource>
</container>
</manifest>
You can add custom properties to the manifest element. When a property is the child of the manifest element, it is created as a component version property. If the value of the property is a URL, a link is added to the version.
To learn more about using custom properties, see "Using custom properties in deployments" in the z/OS Utility Plug-in.
Deletions
You can mark PDS members, sequential data sets, or HFS files for deletion by specifying the containers inside a deleted element. Data sets or HFS files that are marked for deletion are deleted from the target environment when the deployment process runs. The deleted artifacts can be rolled back if the backup option is enabled in the deployment step. If you use the ship list file to delete data sets, you can roll back the deletions as needed.
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="BLD.LOAD1" type="PDS">
<resource name="PGM1" type="PDSMember"/>
<resource name="PGM2" type="PDSMember"/>
</container>
<deleted>
<container name="BLD.LOAD1" type="PDS">
<resource name="PGM3" type="PDSMember"/>
</container>
</deleted>
</manifest>
Generic artifacts
Use generic artifacts to describe changes to deploy that are not physical files. For example, use
generic artifacts to deploy system configuration changes or middleware configuration changes that
are not associated with standard artifacts. Generic artifacts have the GENERIC
container type.
For example, the following ship list describes two message queues to deploy to the target environment:
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="QLOCAL" type="GENERIC" deployType="">
<resource name="LCQ1">
<property name="maxdepth" value="5000"/>
</resource>
<resource name="LCQ2">
<property name="maxdepth" value="200000"/>
</resource>
</container>
</manifest>
To deploy generic artifacts, use the Generate Artifact Information step from the z/OS Utility plug-in to generate commands for deploying the artifacts. Then, use an appropriate command step to run the commands. Steps that you can use to run commands include the Submit Job step, the Shell step, and the TSO/ISPF Command step. Other plug-ins can also use the output of the Generate Artifact Information step to deploy changes.
Source information
You can add source information to PDS members and sequential data sets to build traceability from deployable artifacts to the source code version. The source information is displayed in appropriate views in the IBM UrbanCode® Deploy server.
In following example, the source information in the <inputs>
and
<input>
elements indicate BLD.LOAD(ORDRSET)
is compiled from
two source code files, a main program ORDERSET and a copybook ORDRDATA. The version of the source
code is identified by the version attribute.
<?xml version="1.0" encoding="CP037"?>
<manifest type="MANIFEST_SHIPLIST">
<container name="BLD.LOAD" type="PDS">
<resource name="ORDRSET" type="PDSMember">
<inputs url="">
<input name="ORDRSET" version="3" compileType="Main" url = ""/>
<input name="ORDRDATA" version="1" compileType="Copybook" url = ""/>
</inputs>
</resource>
</container>
</manifest>
- The ship list file must be encoded in CP037 format.
- In deletions, wildcards must not be used for directory or file names.
- If a data set member name contains invalid characters, the characters are replaced by % to match
any characters. Valid data set member name characters are
0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ@#$
.