Understanding the Portable Software Instance descriptor file

A software instance is a collection of data sets containing installed software, and other data sets that may be associated with that installed software. The software may be SMP/E managed, in which case the collection of data sets also contains, and is described by, one or more SMP/E target and distribution zone pairs, defined by a single global zone.

A portable software instance is, exactly as the name implies, a portable form of a software instance, which can be used to simplify distribution of a software instance across a network, and can be deployed by the z/OSMF Software Management task. A portable software instance is a set of portable archive files created by the SMP/E GIMZIP service routine for each of the data sets defined to the software instance, including SMPCSI data sets with all associated SMP/E managed target and distribution libraries, and a descriptor file to describe in detail the entire originating software instance.

Portable Software Instance Descriptor File

The portable software instance descriptor file contains detailed information to describe the content of the originating software instance. It contains the information required by the z/OSMF Software Management task to perform a deployment operation on the content of the portable software instance. The portable software instance descriptor file has a file name of IZUD00DF.json, and is created by z/OSMF during the operation of an Export action on a software instance.

The content of the portable software instance descriptor file is shown in the following example:


{"izud.pswi.descriptor":
 {
  "version":"pswi-descriptor-version"
  "created":"yyyy-mm-ddThh:mm:ssZ",
  "gimpaflocation":"relative-path-for-GIMPAF.XML-file",
  "name":"software-instance-name",
  "description":"software-instance-description",
  "globalzone":"csi-data-set-name",
  "zones":[{
    "name":"zone-name",
    "type":"zone-type",
    "related":"related-zone-name",
    "csi":"csi-data-set-name"
    }]
  "datasets":[{
    "dsname":"data-set-name",
    "volumes":["volume-serial"],
    "storclas":"storage-class",
    "dstype":"data-set-type",
    "tracks":"allocated-tracks",
    "zonedddefs":[{
      "zone":"zone-name",
      "dddefs":[{"dddef":"dddef-name", "path":"unix-directory", Start of change"pathcontainedinds":"unix-directory-subset"End of change}]
      }],
    "mountpoint":"UNIX-path",
    "unixdirs":["unix-directory"],
    "isextendedformat":true | false",
    "recfm":"record-format",
    "lrecl":"logical-record-length",
    "blksize":"block-size",
    "used":"used-tracks-percent"
    "extents":"allocated-extents",
    "dscategory":["data-set-category"],
    "archid":"gimzip-archive-id",
    }]
  "smpeproducts":[{
    "prodname":"product-name",
    "prodid":"product-id", 
    "release":"vv.rr.mm",
    "vendor":"vendor-name",
    "url":"product-url",
     "srels":["srel"],
     "prodsups":[{
     "prodid":"product-id",
     "release":"vv.rr.mm"
      }],
    "features":[{
      "featname":"feature-name",
      "featid":"feature-id",
      "fmids":["fmid-name"]
      }]
    }],
  "fmids":["fmid-name"],
  "products":[{
    "prodname":"product-name",
    "prodid":"product-id", 
    "release":"product-level",
    "vendor":"vendor-name",
    "url":"product-url",
    "features":["feature-name"],
    "gadate":"yyyy-mm-ddThh:mm:ssZ",
    "eosdate":"yyyy-mm-ddThh:mm:ssZ" | "NotAnnounced",
    "prodinfoversion":"yyyy-mm-ddThh:mm:ssZ"
    }],
  "workflows":[{
    "name":"workflow-name",
    "description":"workflow-description",
    "location": {
      "smptype":"smp-type",
      "smpname":"smp-name",
      "dsname":"workflow-dsname",
      "path":"workflow-path"Start of change},
    "performonhostsystem":true | falseEnd of change
    }],
  "datasetproperties":[{
    "dddefname":"dddef-name",
    "zone":"zone-name",
    "dsname":"data-set-name",
    "volume":"volume-serial",
    "dstype":"DLIB",
    "properties":[{"key":"value"}] 
    }],
Start of change "datasetpropertylabels":[{
    "propertyname":"property-name",
    "label":"property-label"
    }],End of change
  "productproperties":[{
    "prodid":"product-id",
    "release":"product-level",
    "prodname":"product-name",
    "properties":[{"key":"value"}] 
    }]
 }
}
Where:
version
Indicates the version of the portable software instance descriptor. The version value may be:
  1. The initial version of the descriptor file.
  2. Adds support for non-SMP/E managed product information.
  3. Adds support for SMP/E Product end-of-service information.
  4. Adds support for workflows.
  5. Adds support for datasetproperties and productproperties.
  6. Start of changeAdds support for pathcontainedinds and performonhostsystemEnd of change
  7. Start of changeAdds support for datasetpropertylabelsEnd of change
created
Indicates the date and time when the portable software instance was created, in ISO 8601 format. For example, yyyy-mm-ddThh:mm:ssZ.
gimpaflocation
Indicates the relative path to the GIMPAF.XML file for this portable software instance, relative to the location of the portable software instance descriptor file.
name
Indicates the name for the originating software instance.
description
Indicates the description of the originating software instance. This is an optional property.
globalzone
Indicates the name of the CSI data set that contains the global zone. This is an optional property, specified only if the originating software instance describes SMP/E managed software.
zones
Indicates the list of SMP/E zones from the originating software instance. This is an optional property, specified only if the originating software instance describes SMP/E managed software.
name
Indicates the zone name.
type
Indicates the type for the zone, global, target or dlib.
related
Indicates the name of the zone's related zone, if any.
csi
Indicates the name for the CSI data set that contains the zone.
datasets
Indicates the list of data sets from the originating software instance.
dsname
Indicates the originating data set name.
volumes
Indicates the list of volume serials where the originating data set resided.
storclas
Indicates the name of the storage class where the originating data set resided. This is an optional property.
dstype
Indicates the type for the data set. Can be one of the following types:
  • HFS — Hierarchical file system.
  • PDS — Partitioned data set.
  • PDSE — Partitioned data set extended.
  • SEQ — Sequential data set.
  • VSAM — VSAM data set.
  • ZFS — zSeries file system.
tracks
Indicates the number of 3390-device equivalent tracks (56664 bytes/track) allocated to the data set.
zonedddefs
Indicates the list of SMP/E zones and DDDEF entries that reference the data set. This is an optional property, specified only if the originating software instance describes SMP/E managed software, and if the subject dataset is referenced in the SMP/E zones.
zone
Indicates the name of an SMP/E zone that contains one or more DDDEF entries for the data set.
dddefs
Indicates the list of DDDEF entries that identify the data set.
dddef
Indicates the name of the DDDEF entry.
path
Indicates the UNIX directory identified in the DDDEF entry. Null if the DDDEF entry identifies a data set.
Start of changepathcontainedindsEnd of change
Start of changeThe fixed portion of the UNIX path that is contained in the subject data set. This value excludes the mount point and any intermediate symbolic links that are specified in a DDDEF entry.End of change
mountpoint
Indicates the mount point for the originating UNIX file system data set. Null if the DDDEF entry identifies a data set instead of a UNIX directory. This is an optional property, specified only if the originating software instance describes SMP/E managed software, and if the subject dataset is referenced in the SMP/E zones by a DDDEF entry with a UNIX directory.
unixdirs
A list of UNIX directories that reside in the subject data set and contain one or more workflow definition files for the software instance.
isextendedformat
Indicates, true or false, if the data set is an extended format sequential data set.
recfm
Indicates the record format. The record format can be any valid combination of the following codes:
  • A — ASA printer control characters.
  • B — Blocked records.
  • F — Fixed-length records.
  • M — Machine code printer control characters.
  • S — Standard (for F) or spanned (for V); used only with sequential data sets.
  • T — Track-overflow feature.
  • U — Undefined format records.
  • V — Variable-length records.
lrecl
Indicates the logical record length.
blksize
Indicates the block size, in bytes.
used
Indicates the percentage of allocated tracks used, expressed in whole numbers, not rounded. If any track is used, the minimum percentage is 1. If the data set is a PDSE, the percentage refers to the percentage of allocated pages used.
extents
Indicates the number of extents allocated to the data set.
dscategory
List of categories for how the data set is used. Can be one or more of the following:
  • DLIB — SMP/E managed distribution library, or SMP/E control data set associated with a distribution zone.
  • GLOBAL — SMP/E control data set associated with the global zone.
  • SMP — SMP/E control data set.
  • SMPTLIB — SMPTLIB data sets associated with the global zone.
  • TARGET — SMP/E managed target library, or SMP/E control data set associated with a target zone.
  • WORKFLOW — Contains one or more workflow definition files for the workflows explicitly defined to the software instance.
  • OTHER — None of the above.
archid
Indicates the archive ID value, produced by the GIMZIP service routine and specified in the GIMPAF.XML file, to identify the portable archive file for the data set.
smpeproducts
Indicates the list of software products installed in the originating software instance that are managed by SMP/E. This is an optional property.
prodname
Indicates the name for the product.
prodid
Indicates the identifier for the product.
release
Indicates the version, release, and modification level for the product, in this format: vv.rr.mm.
vendor
Indicates the name for the product's vendor. This is an optional property.
url
Indicates the URL that links to additional information about the product. This is an optional property.
srels
Indicates the system or subsystem releases on which the subject product can be installed.
prodsups
Indicates the list of products that are superseded by the subject product. This is an optional property.
features
Indicates the list of features for the subject product.
featname
Indicates the name for the feature.
featid
Indicates the identifier for the feature.
fmids
Indicates the list of FMIDs for the subject feature. It is also the list of FMIDs in the originating software instance. This list includes all FMIDs associated with one or more products and features, and all FMIDs associated with no products or features.
products
The list of products from the originating software instance that are not managed by SMP/E
product-name
Name of the product, but can be up to 64 characters.
product-ID
Identifier for the product, but can be up to 64 characters.
product-level
Release level for the product, but can be up to 64 characters.
vendor-name
Name of the vendor that provides the product, but can be up to 64 characters.
product-URL
A URL that links to additional information about the product, but can be up to 256 characters.
feature-name
List of names of features for the product, but can be up to 64 characters
gadate
The date when the product became generally available. May be null, or a date value, in ISO 8601 format.
eosdate
The last date on which the vendor will deliver standard support services for the product.
  • null - The end of service date is unknown for the product.
  • yyyy-mm-ddThh:mm:ssZ - The known end of service date, in ISO 8601 format.
  • NotAnnounced - The end of service date has not yet been announced for the product.
prodinfoversion
The version for the most recent product information file that provided information for the subject product. The version value represents the date the file was created or updated. May be null, or a date value, in ISO 8601 format.
workflows
List of workflows for the software instance.
workflow-name
Name for the workflow.
workflow-description
Description for the workflow.
location
Location of the workflow definition file for the workflow.
smp-type
The SMP/E element type for a workflow definition file that is managed by SMP/E.
smp-name
The SMP/E element name for a workflow definition file that is managed by SMP/E.
workflow-dsname
The name of the data set that contains the workflow definition file.
workflow-path
The UNIX path for a workflow definition file that is a UNIX file.
Start of changeperformonhostsystemEnd of change
Start of changeIndicates whether the workflow steps may be performed on the host system or on another system in the same sysplex as the host system. This property is optional and the default value is true.
true
Indicates that the workflow steps may be performed on the z/OSMF host system on which the software instance resides.
false
Indicates that the workflow steps may be performed on a system in the sysplex other than the z/OSMF host system on which the software instance resides.
End of change
datasetproperties

A list of one or more properties for individual data sets. These properties are made available to a workflow as workflow variable properties when Software Management creates a workflow instance for the software instance. See Software Management workflow variables for more information.

dddefname
The name of the SMP/E DDDEF entry that describes an SMP/E managed data set.
zone
The zone name where the DDDEF entry resides. The zone is specified to identify a unique data set when there are more than one DDDEF entries with the same name in different zones, and each DDDEF entry identifies a different data set in the software instance.
dsname
The name of the subject data set. The data set name is specified to identify a non-SMP/E managed data set.
volume
The volume of the subject data set. The volume is specified to identify a non-SMP/E managed data set where the volume was specified to identify an uncatalogued data set.
dstype
The usage type of the subject data set. A value of DLIB indicates the data set is an SMP/E managed distribution library, or an SMP/E control data set associated with a distribution zone.
properties
A list of one or more properties for the subject data set, specified as key-value pairs.
Start of changedatasetpropertylabelsEnd of change
Start of change

A list of labels that each correspond to unique data set properties that a provider defines in datasetproperties. Label values are used for column headings to display provider defined data set property values on the Deployment Configuration Data Sets page. Not all provider defined data set properties must have corresponding defined labels, but only those with defined labels are eligible for display on the Deployment Configuration Data Sets page. A data set property can have only one associated label, and all labels must be unique.

End of change
Start of change
propertyname
The name, or key, of the existing provider defined property.
label
The unique label that is displayed on the Deployment Configuration Data Sets page. Label values can contain up to 20 characters.
End of change
productproperties
A list of one or more properties for individual software products. These properties are made available to a workflow as workflow variable properties when Software Management creates a workflow instance for the software instance. See Software Management workflow variables for more information.
A prodid and release must be specified to uniquely identify an SMP/E product.
Prodname, prodid, and release may be specified to uniquely identify a non-SMP/E product.
prodid
The identifier for the subject product. This is required to identify an SMP/E managed product.
release
The version, release, modification level for the subject product. This is required to identify an SMP/E managed product.
prodname
The name of the subject product. This is required to identify a non-SMP/E managed product.
properties
A list of one or more properties for the subject product, specified as key-value pairs.