You can use this operation to modify the properties of a software instance that is
defined in z/OSMF, including changing the global
zone, target zones, or non-SMP/E managed data sets associated with the software instance. The modify
operation updates only the definition of the software instance in z/OSMF. The physical data sets that compose the software
instance are not affected.
HTTP method and URI path
PUT /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 modified. 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:
Content-Type
Identifies the type of input content provided by the caller. The JSON content type
("Content-Type: application/json") is used for the JSON document included as input 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, English
is used.
Custom headers
None.
Request content
Your request must include a JSON object that describes all the properties of the software
instance to be modified, for example:Figure 1. Modifying a software instance: request content
Name of the software instance. The name can contain up to 30 non-blank characters, including
alphanumeric characters (A-Z, a-z, and 0-9), mathematical symbols (< > - = | \), punctuation
marks (? ! : ' " /), and special characters ($ _ # @ ^). The name is required and must be unique on
the system.
system-nickname
Nickname of the system that has access to the volumes and data sets where the software instance
resides. Use the nickname that is specified for the system definition in the z/OSMFSystems task. The nickname is required.
To manage
the systems defined to z/OSMF, you can use the z/OSMF topology services. For more details, see Topology services.
swi-description
Description of the software instance. The description is optional and can contain a maximum of
256 characters.
global-zone
CSI data set that contains the global zone used to manage the software. The data set name is
required, must comply with z/OS® data set naming conventions,
and must end with .CSI.
target-zones
Comma-separated list of the target zones to be included in the software instance. At least one
target zone is required. Each target zone name must be 1-7 characters long; the valid characters are
uppercase alphabetic characters (A-Z), numeric characters (0-9), and special characters (@ # $). The
first character must be an alphabetic character.
categories
Comma-separated list of the categories to which the software instance is assigned. Each category
name can contain up to 30 non-blank characters, including alphanumeric characters (A-Z, a-z, and
0-9), mathematical symbols (< > - = | \), punctuation marks (? ! : ' " /), and special
characters ($ _ # @ ^). Assigning the software instance to a category is optional.
datasets
Array that contains each non-SMP/E managed data set to be added to the
software instance. Adding non-SMP/E managed data sets to the software instance is optional.
data-set-name
Name of the non-SMP/E managed data set. You cannot specify data set
members or a subset of a data set. A data set name is required if you are adding non-SMP/E managed
data sets to the software instance. The data set name must comply with z/OS data set naming conventions
volume-serial
Volume on which the non-SMP/E managed data set resides. The volume serial is required if the
data set is not cataloged, and the volume must be accessible by the system where the software
instance resides. The volume serial must be 6 characters long; the valid characters are uppercase
alphabetic characters (A-Z) and numeric characters (0-9).
products
List of products for the software instance that are not managed by SMP/E. This list is
optional.
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 1023
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. May be null,or a date value, in ISO
8601 format, yyyy-mm-ddThh:mm:ssZ.
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. This list is optional.
workflow-name
Name for the workflow. The name may contain up to 100 characters, but must not include the
characters for ampersand ('&'), forward slash ('/'), backward slash ('\'), logical or ('|'),
greater than ('>'), or less than ('<'). Embedded blanks are allowed.
workflow-description
Description for the workflow. The description is optional, and can contain a maximum of 256
characters.
location
Location of the workflow definition file for the workflow. A workflow definition file location
is required.
smp-type
The SMP/E element type for a workflow definition file that is managed by SMP/E. The SMP/E
element type is optional and may be up to 12 uppercase alphanumeric characters. The first character
cannot be numeric.
smp-name
The SMP/E element name for a workflow definition file that is managed by SMP/E. The SMP/E
element name is optional and may be up to 8 uppercase alphanumeric, $, #, or @ characters.
workflow-dsname
The sequential data set name, or partitioned data set name and member for a workflow definition
file that is in a data set. The data set name is optional, but if specified must comply with z/OS data set naming conventions. For example,
IBMUSR.SM.WRKFLOWS(WRKFLOW1).
workflow-path
The UNIX path for a workflow definition file that is a
UNIX file. The UNIX
path is optional, but if specified it must have valid UNIX
file name syntax:
Must be an absolute pathname (must start with slash).
Must not end with a slash.
Can be up to 1023 characters long.
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. 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.
Tip: Ensure that the
description property contains information that helps the user select an appropriate alternative
system for the performance of the workflow steps. For example, if the workflow steps are for
installation verification procedures (IVPs), the user would select the system on which the newly
activated software runs.
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.
To define properties for SMP/E managed data sets, specify the DDDEF entry name that identifies
the desired data set or data sets. Specify the zone name only when necessary to identify a unique
data set. For example, if there are more than one DDDEF entries with the same name pointing to
different data sets, then both a DDDEF entry name and zone name are required to define properties
for only one of those data sets. If an SMP/E zone name is not specified then the properties apply to
all data sets identified by all DDDEF entries with the same name in all zones that reside in the
software instance.
To define properties for a non-SMP/E managed data set, specify the data set name and the volume
for the data set as they are used when defining the data set to the software instance. That is, if
only a data set name is specified to define the data set to the software instance, then specify only
the data set name when defining properties for the data set. If a data set name and volume are
specified to define the data set to the software instance, then specify both the data set name and
volume to define properties for the data set.
dddefname
The name of the SMP/E DDDEF entry that describes one or more SMP/E managed data sets. It may be
up to 8 uppercase alphanumeric, $, #, or @ characters.
zone
The zone name where the DDDEF entry resides. It may be up to 7 uppercase alphanumeric, $, #, or
@ characters.
dsname
The name of the subject data set. This is used to identify a non-SMP/E managed data set. It may
be up to 44 characters and must comply with z/OS data set
naming conventions.
volume
The volume of the subject data set. This is used to identify a non-SMP/E managed data set where
the volume had been specified to identify an uncatalogued data set. It may be up to 6 uppercase
alphanumeric, $, #, or @ characters.
dstype
The usage type of the identified data set. The value may be DLIB or the default value of null. A
value of DLIB indicates the identified data set is an SMP/E managed distribution library, or an
SMP/E control data set associated with a distribution zone. The dstype value of DLIB must be
specified for properties that identify distribution library or related control data sets so Software
Management can safely ignore this property specification when a software instance does not contain
SMP/E managed distribution libraries or related control data sets.
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. Keys may not start with izud- to ensure no collisions with
Software Management provided variables and properties.
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. 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.
The product identifier may be up to 64 characters.
release
The version, release, modification level for the subject product. This is required to identify
an SMP/E managed product. The release level may be null, or up to 64 characters.
prodname
The name of the subject product. This is required to identify a non-SMP/E managed product. The
product name may be null, or up to 64 characters.
properties
A list of one or more properties for the subject product, 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. Keys may not start with izud- to ensure no collisions with Software
Management provided variables and properties.
Usage considerations
The SMP/E global zone and target zones define the installed products, features, and FMIDs for a
software instance. If you modify these properties for a software instance, perform a PUT method to
load the products, features, and FMIDs for the updated software instance. Doing so refreshes the
product, feature, and FMID information known to z/OSMF for the subject software instance. For instructions, see Load the products, features, and FMIDs for a software instance.
To submit a modify software instance request through the software management services, the user
ID initiating the request requires the same authorizations as when performing a modify operation
using the z/OSMFSoftware Management task. That is, the user ID must have READ
access to the Software Management task. The user ID must also
have either CONTROL or UPDATE access to the SAF resources corresponding to the software instance to
be modified, as follows:
The name, system, and categories properties are used to create the SAF resource names for the
software instance; therefore, to modify any of these properties, the user ID must have CONTROL
access to the existing SAF resource names and to the new SAF resource names.
If a global zone or categories will be implicitly added to z/OSMF through the modify operation, the user ID must
have CONTROL access to the SAF resources corresponding to the specified global zone and
categories.
To modify any other property, the user ID must have UPDATE access.
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.
Example
In the following example, the PUT method is used to modify the description property for software
instance Hooli on system PEV174.Figure 2. Sample request to modify 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"}]
}]
}