You can use this operation to retrieve the properties of a software instance. The
properties include, but are not limited to, the global zone and target zones associated with the
software instance and a list of the products, features, FMIDs, and non-SMP/E managed data sets that are included in the software instance.
HTTP method and URI path
GET /zosmf/swmgmt/swi/<system-nickname>/<swi-name>
where:
zosmf/swmgmt identifies the software management services.
swi informs the service that the request is for the software instance object.
<system-nickname>/<swi-name> further
qualifies the request and indicates the specific software instance to be retrieved. A software
instance is uniquely identified by its name (swi-name) and the nickname
(system-nickname) of the z/OSMF host system
that has access to the volumes and data sets where the software instance resides.
To obtain
information about the specified system, you can use the z/OSMF topology services. For more details, see Topology services.
Standard headers
Use the following standard HTTP header with this request:
Accept-Language
Identifies the preferred language for messages that may be returned to the caller. Acceptable
values are "Accept-Language: en" (English) and "Accept-Language: ja" (Japanese). Any other language
value is ignored and English is used instead. In addition, if the header is not specified, then
English is used.
To submit requests through the software management services, the user ID
initiating the request requires the same authorizations as when performing an analogous operation
using the z/OSMFSoftware Management task. That is, to retrieve the properties
of a software instance, the user ID initiating the request must have READ access to both the z/OSMFSoftware Management task and the software instance. For
information about access controls for the Software Management
task, see Creating access controls for the Software Management task in IBM z/OS Management Facility Configuration Guide.
Expected response
On completion, the service returns an HTTP response, which includes a status code indicating
whether your request completed. Status code 200 indicates success. A status code of
4nn or 5nn indicates that an error has occurred. For more details, see Error handling.
If the request is successful, the response also includes the following JSON object:
Nickname of the z/OSMF host
system that has access to the volumes and data sets where the software
instance resides. To obtain information about the specified system,
you can use the z/OSMF topology
services. For more details, see Topology services.
swi-description
Description of the software instance.
global-zone
CSI data set that contains the global zone used to manage the software. If the software instance has no global zone, then this property will be
null.
target-zones
Comma-separated list of the target zones included in the software instance. If the software instance has no global zone, then this property will be
null.
categories
Comma-separated list of the categories to which the software instance
is assigned.
last-retrieved
Date and time the product, feature, and FMID information was last
retrieved for the software instance. This attribute is blank if this
information has not been retrieved.
last-modified
Date and time in ISO 8601 format that the software instance was
last modified.
modified-user-ID
User ID of the user who last modified the software instance.
date-created
Date and time in ISO 8601 format that the software instance was
created.
created-user-ID
User ID of the user who created the software instance.
date-locked
Date and time in ISO 8601 format that the software instance was
locked. This attribute is null if the software instance is not currently
locked.
locked-user-ID
User ID of the user who locked the software instance. This attribute
is null if the software instance is not currently locked.
datasets
Array that contains each non-SMP/E managed data set that is included in the software
instance.
data-set-name
Name of the non-SMP/E managed data set.
volume-serial
Volume on which the non-SMP/E managed data set resides.
products
Array that contains each product that is included in the software instance.
product-name
Name of the product. If any FMIDs are not related to a product and feature, those FMIDs are
listed under a product named No Product.
product-ID
Identifier of the product.
product-level
Version, release, and modification level of the product. The value has the format
VV.RR.MM, where VV is the two-digit version, RR is the two-digit release, and
MM is the two-digit modification level.
vendor-name
Name of the vendor that provides the product.
general-availability
Date this level of the product is available to all users.
end-of-service
Last date on which the vendor will deliver standard support services for this level of the
product. This date is the general end of service date. It does not account for lifecycle
extensions.
product-URL
URL that links to additional information about the product. This information can include, for
example, product life cycle dates, product highlights, planning information, and technical
descriptions.
file-version
Version of the most recent product information file that was retrieved that contains the
corresponding product. The version represents the date that file was created or last updated.
features
Array that contains each feature that is included in the product.
feature-name
Name of the feature. If any FMIDs are not related to a product and feature, those FMIDs are
listed under a feature named No Feature.
fmids
Array that contains each FMID that is included in the feature.
fmid-name
Name of the FMID.
fmid-description
Description of the FMID.
fmid-target-zones
Name of the target zones where the FMID is installed.
nonsmpeproducts
List of products for the 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.
general-availability-date
Date this level of the product is available to all users.
end-of-service-date
Last date on which the vendor will deliver standard support services for this level of the
product. This date is the general end of service date. It does not account for lifecycle extensions.
Can be any of the following:
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 is not yet announced for the product.
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.
performonhostsystem
Indicates whether the workflow steps may be performed on the host system or on another system in
the same sysplex as the host system.
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.
datasetproperties
A list of one or more properties for individual data sets.
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.
dsname
The name of the subject data set.
volume
The volume of the subject 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. The
keys are strings, and values are a valid JSON data type such as string, number, Boolean, array,
object or null.
datasetpropertylabels
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.
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.
productproperties
A list of one or more properties for individual software products.
prodid
The identifier for the subject product.
release
The version, release, modification level for the subject product.
prodname
The name of the subject product.
properties
A list of one or more properties for the subject product, specified as key-value pairs. The keys
are strings, and the values are a valid JSON data type such as string, number, Boolean, array,
object or null. See Provider Defined Properties
for more information.
Example
In the following example, the GET method is used to retrieve the
properties of software instance DB2V9 on system PEV174.Figure 1. Sample request to retrieve the properties of a
software instance
GET /zosmf/swmgmt/swi/PEV174/DB2V9 HTTP/1.1
Host: zosmf1.yourco.com
A sample response is shown in Figure 2.Figure 2. Sample response from a request to
retrieve the properties of a software instance
},
"performonhostsystem":true | false
}],
"datasetproperties":[{
"dddefname":"dddef-name",
"zone":"zone-name",
"dsname":"data-set-name",
"volume":"volume-serial",
"dstype":"DLIB",
"properties":[{"key":"value"}]
}],
"datasetpropertylabels":[{
"propertyname":"property-name",
"label":"property-label"
}],
"productproperties":[{
"prodid"":"product-id",
"release":"product-level",
"prodname":"product-name",
"properties":[{"key":"value"}]
}]
}