Modify the properties of a software instance

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. Adding a software instance: request content

{
  "name":"swi-name",
  "system":"system-nickname", 
  "description":"swi-description",
  "globalzone":"global-zone", 
  "targetzones":["target-zones"], 
  "categories":"["categories"],
  "datasets":[
  {
    "dsname":"data-set-name",
    "volume":"volume-serial"
  }]
  
}

where:

swi-name: 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/OSMF Systems 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. If specified, 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. A list of 0 or more zone names, 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).

When modifying a software instance, the software management REST interface validates the information that is supplied in the JSON object before completing the request. All input values must be valid and syntactically correct. If any errors are discovered, the modify request fails and appropriate messages are returned.

Start of change The name and system, properties are required for every software instance. If either of these are not specified or are specified as null, then the request finishes with HTTP response code 400 (Badrequest) and reason code 4 (The required property {name|system} is missing. Add the missing property and retry the request.). End of change

Start of change If the globalzone property is specified, then the targetzones property is required. Therefore, if globalzone is specified and targetzones is not, then the request finishes with HTTP response code400 (Bad request) and reason code 4 (The required property {targetzones} is missing. Add the missing property and retry the request.). End of change

Start of change If the globalzone property is not specified, then the datasets property is required. That is, the software instance must contain either SMP/E managed software, or at least one non-SMP/Emanaged data set. Therefore, if both globalzone and datasets are not specified or are specified as null, then the request finishes with HTTP response code 400 (Bad request) and reason code 42 (Both of the properties {globalzone} and {datasets} are missing, but one is required. Add one or both of the missing properties and retry the request.). End of change

Start of change The targetzone property can only be specified if the globalzone property is also specified. Therefore, if targetzone is specified but globalzone is not, then the request finishes with HTTP response code 400 (Bad request) and reason code 43 (The {targetzone} property requires the{globalzone} property, but the {globalzone} property is missing. Either add the {globalzone}property or remove the {targetzone} property and retry the request.) End of change

If the input values are valid, the software instance that is defined in this request overwrites the existing software instance definition. In a modify request, you must supply all the existing properties for the software instance, and modify only those properties you want to update. To delete a property, specify all the existing properties for the software instance in the JSON object and either exclude the property to be deleted or set its value to null.

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.

For other usage considerations, see Usage considerations for the z/OSMF REST services.

Required authorizations

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/OSMF Software 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.
are implicitly added to z/OSMF through the modify operation, the user ID must have CONTROL access to the SAF resources corresponding to the specified categories.
To modify any other property, the user ID must have UPDATE access.

For information about access controls for the Software Management task, see 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.

Example

In the following example, the PUT method is used to modify the description property for software instance DB2V9 on system PEV174.

Figure 2. Sample request to modify a software instance

PUT /zosmf/swmgmt/swi/PEV174/DB2V9 HTTP/1.1
Host: pev174.yourco.com

Content-Type: application/json
Accept-Language: en
{
  "name":"DB2V9", 
  "system":"PEV174", 
  "description":"DB2 new description",
  "globalzone":"DB2.GLOBAL.CSI", 
  "targetzones":["DB2TGT"], 
  "datasets":[
  {"dsname":"USER.DB2V9.PROCLIB","volume": "LV1234"},
  {"dsname":"USER.DB2V9.SAMPLES","volume":"LV1234"}]
}

Figure 3 provides a sample response, indicating that the update was successful.

Figure 3. Sample response for a modify software instance request

HTTP/1.1 200 OK
Date: Tues, 22 July 2014 18:53:27 +00006GMT