Software Update Search

The Software Update Search service allows you to search a software instance for one or more software updates. This is helpful when you need to complete a task that requires you to determine if a software instance is installed or needs to be installed.

HTTP method and URI path

POST /zosmf/swmgmt/swi/<system-nickname>/<swi-name>/softwareupdatesearch
POST /zosmf/swmgmt/swi/<swi-uuid>/softwareupdatesearch
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 analyzed. 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 information, see Topology services.

    In addition, the software instance UUID can be used instead of <system-nickname/swi-name> to identify a software instance.

  • <swi-uuid> further qualifies the request and indicates the specific software instance to be analyzed. A software instance can be uniquely identified by using its UUID. A UUID is assigned to every software instance and can be obtained by using the REST API List the software instances defined to z/OSMF.
  • /softwareupdatesearch indicates that the SYSMOD Search service is to be performed and the results returned.

Standard headers

Use the following standard HTTP header with this request:

Accept-Language
Identifies the preferred language for messages that can 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.
Content-Type
Identifies the type of input content that is provided by the caller. The JSON content type ("Content-Type: application/json") is used for the JSON document, if any, included as input with this request.

Custom headers

None.

Request content

Your request must include a JSON object that identifies properties that are required to perform the operation, for example:
{
 "updates":["update-id"],
 "zosmfuid":"user-id", 
 "zosmfpw":"password",
 "proxyuid":"user-id",
 "proxypw":"password"
}
Where:
updates

The list of software update (SYSMOD) IDs to be searched in the subject software instance.

zosmfuid

Userid for authenticating with a remote z/OSMF instance. This is an optional property.

zosmfpw

Password for authenticating with a remote z/OSMF instance. This is an optional property.

proxyuid

Userid for authenticating with an HTTP proxy. This is an optional property.

proxypw
Password for authenticating with an HTTP proxy. This is an optional property.

The request content is required, but some properties are optional. For example, if the software instance does not reside in the same sysplex as the primary z/OSMF instance, you might be required to authenticate with the secondary z/OSMF instance that is running in the sysplex where the software instance resides. In addition, if the primary z/OSMF instance must navigate an HTTP proxy server to connect with the secondary z/OSMF instance, you might also be required to authenticate with that HTTP proxy server. Therefore, you may need to specify the remote z/OSMF userid, password, and proxy userid and password.

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 you perform an analogous operation that uses the z/OSMF Software Management task. That is, the user ID must have READ access to the Software Management task and the SAF resources for the software instance that is being processed.

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.

Usage considerations

For more information about usage considerations, see Usage considerations for the z/OSMF REST services.

Expected response

The software updates search action for a software instance is an asynchronous operation. Therefore, on completion of the initial POST request, the z/OSMF Software Management REST interface returns an HTTP response code of 202 Accepted and a JSON document that contains a URL for the status monitor for the request. The client performs GET requests to the supplied URL to monitor the status of the operation and to obtain the result set. For example:
{
 "statusurl":"url"
}
statusurl

Indicates the URL that provides status for the missing critical updates request.

On subsequent GET requests to the status monitor URL:

  • If the operation is not yet complete, an HTTP response code of 200 OK is returned, along with a JSON document that contains status information for the operation.
  • If the operation is complete, then an HTTP response code of 200 OK is returned, along with a JSON document that contains status information and the desired result set.
  • If the request expires, then an HTTP response code of 404 Not found is returned. That is, when the operation has completed, the z/OSMF server holds the result set for a finite length of time. After that time has passed, the result set is said to expire, and is no longer available for the client to obtain.
The response to GET requests on the status monitor URL includes the following JSON document:
{
 "status":"status",
 "updates":[{
   "name":"sysmod-id",
   "type":"sysmod-type",
   "fmid":"fmid",
   "zones:[{
     "zone":"zone-name",
     "status":"sysmod-status",
     "installed":"date-time"
   }]
 }]
}
status

The status of the report request. The status can be either "running" or "complete".

updates
List of software updates (SYSMODs) that were searched.
name

Software update (SYSMOD) ID that was searched.

type

Type of SYSMOD. The SYSMOD can be one of the following types: APAR, FUNCTION, PTF, or USERMOD.

fmid

FMID for the subject SYSMOD.

zones
The list of zones in the software instance.
zone
Name of a global, target, or dlib zone.
status

Status of the SYSMOD in this zone. May be one of the following values:

  • Accepted. The SYSMOD is installed in the distribution zone.
  • Applied. The SYSMOD is installed in the target zone.
  • Deleted. The SYSMOD was deleted when another SYSMOD was installed.
  • Error. The SYSMOD has only been partially installed. Errors occurred during APPLY or ACCEPT processing.
  • Not Found. The SYSMOD was not found in the corresponding zone.
  • Received. An entry for the SYSMOD exists in the global zone.
  • Superseded by <sysmod-id>. A SYSMOD that supersedes the subject SYSMOD is installed in the target or distribution zone. The ID of the superseding SYSMOD is provided.
installed

Date and time the SYSMOD was received, applied, or accepted into the global zone, target zone, or distribution zone, respectively.

For more information about error responses, see Error handling.

Example

The request that is shown in Figure 1 performs the software update search action for the software instance that is named zos24 on SYS123.
Figure 1. Sample POST request for Software Update Search
POST /zosmf/swmgmt/swi/SYS123/zos24/softwareupdatesearch HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
Accept-Language: en
{
"updates":["HBB77C0","UA12345","UJ00132","CA57408"]
}
A sample response is shown in Figure 2:
Figure 2. Sample POST response for Software Update Search
HTTP/1.1 202 Accepted
Date: Tues, 1 February 2022 18:53:04 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"statusurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/statusmonitor\/softwareupdatesearch\/4837290198343"}
The response in Figure 2 indicates that the request is accepted, and the status monitor URL is provided. A subsequent GET request to the status monitor URL is shown in Figure 3:
Figure 3. Sample GET request for Software Update Search
GET /zosmf/swmgmt/statusmonitor/softwareupdatesearch/4837290198343 HTTP/1.1
Host: sys123.yourco.com
A sample response is shown in Figure 4:
Figure 4. Sample GET response for Software Update Search
HTTP/1.1 200 OK
Date: Tues, 1 February 2022 18:53:27 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{
"status":"complete",
"updates":[
 {"name":"HBB77C0",
  "type":"FUNCTION",
  "fmid":"HBB77C0",
  "zones:[
   {"zone":"DLB24","status":"Accepted","installed":"2022-02-11T19:15:34Z"},
   {"zone":"GLOBAL","status":"Not Found","installed":null},
   {"zone":"TGT24","status":"Applied","installed":"2022-02-11T19:15:34Z"}
   ]},
 {"name":"UA12345",
  "type":null,
  "fmid":null,
  "zones:[
   {"zone":"DLB24","status":"Not Found","installed":null},
   {"zone":"GLOBAL","status":"Not Found","installed":null},
   {"zone":"TGT24","status":"Not Found","installed":null}
   ]},
 {"name":"UJ00132",
  "type":"PTF",
  "fmid":"HBB77C0",
  "zones:[
   {"zone":"DLB24","status":"Not Found","installed":null},
   {"zone":"GLOBAL","status":"Received","installed":"2022-02-11T18:34:56Z"},
   {"zone":"TGT24","status":"Applied","installed":"2022-02-11T19:15:34Z"}
   ]},
 {"name":"CA57408",
  "type":null,
  "fmid":null,
  "zones:[
   {"zone":"DLB24","status":"Not Found","installed":null},
   {"zone":"GLOBAL","status":"Not Found","installed":null},
   {"zone":"TGT24","status":"Superseded by UJ00132","installed":null}
   ]}
 ]
}