Missing Critical Updates

The Missing Critical Updates service helps you determine if your software instances are missing software updates to resolve PE PTFs, HIPER fixes, or other exception SYSMODs identified by ERROR HOLDDATA, and helps you identify the SYSMODs that resolve those exceptions.

HTTP method and URI path

POST /zosmf/swmgmt/swi/<system-nickname>/<swi-name>/missingcriticalupdates

POST /zosmf/swmgmt/swi/<swi-uuid>/missingcriticalupdates

Note: Before you use this service, use SMP/E to receive the latest HOLDDATA into the global zone associated with the software instance. Otherwise, the results might be incomplete, incorrect, or outdated. For more information, see How to process HOLDDATA in z/OS SMP/E User's Guide.

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.
/missingcriticalupdates indicates that the Missing Critical Updates action 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:

{
 "zosmfuid":"user-id", 
 "zosmfpw":"password",
 "proxyuid":"user-id",
 "proxypw":"password"
}

Where:

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 only if you are required to authenticate with a secondary z/OSMF instance or an HTTP proxy server. Otherwise, omit the JSON object. 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 may also be required to authenticate with that HTTP proxy server. Therefore, you might 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 performing 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 Missing Critical Updates 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",
 "lastholdrecvdate":"date"
 "missingcriticalupdates":[{
   "name":"sysmod-id",
   "holdclass":"hold-class",
   "holdsymptom":"hold-symptom",
   "heldsysmod":"sysmod-id",
   "fmid":"fmid",
   "fmiddesc":"fmid-description",
   "resolvers":[{
     "name":"sysmod-id",
     "received":true | false
   }],
   "tgtzones:["zone-name"]
 }]
}

status

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

lastholdrecvdate

Date and time in ISO 8601 format when HOLDDATA was last received into the software instance's global zone.

missingcriticalupdates

List of critical software updates that are not yet installed in the software instance target zones.

name

SYSMOD ID for the missing update (APAR fix).

holdclass

Hold class that is specified on the CLASS operand of the ++HOLD statement.

holdsymptom

Short description of the problem fixed by the missing APAR.

heldsysmod

SYSMOD ID for the SYSMOD with the unresolved error HOLD and is fixed by the missing APAR.

fmid

FMID for the held SYSMOD.

fmiddesc

Description of the FMID.

resolvers

The list of SYSMODs that resolve the missing APAR. This list includes SYSMODs that supersede the missing APAR and resolving SYSMODs that are identified on the ++HOLD statement.

If this field is null, either no resolving SYSMODs are received in the global zone, or no resolving SYSMODs are identified for the missing APAR.

name: SYSMOD ID for the resolving SYSMOD.
received: Indicates whether the resolving SYSMOD is received in the software instance's global zone.

tgtzones

List of target zone names where the missing APAR is not installed and a resolving SYSMOD must be installed to resolve the critical problem.

For more information about error responses, see Error handling.

Example

The request that is shown in Figure 1 performs the missing critical updates report for the software instance that is named zos24 on SYS123.

Figure 1. Sample POST request for Missing Critical Updates

POST /zosmf/swmgmt/swi/SYS123/zos24/missingcriticalfixes HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
Accept-Language: en

A sample response is shown in Figure 2:

Figure 2. Sample POST response for Missing Critical Updates

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\/missingcriticalupdates\/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 Missing Critical Updates

GET /zosmf/swmgmt/statusmonitor/missingcriticalupdates/4837290198343 HTTP/1.1
Host: sys123.yourco.com

A sample response is shown in Figure 4:

Figure 4. Sample GET response for Missing Critical Updates

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",
 "lastholdrecvdate":"2022-02-11T19:15:34Z"
 "missingcriticalupdates":[
  {"name":"CA61368",
   "holdclass":"HIPER",
   "holdsymptom":"FUL",
   "heldsysmod":"HBB77C0",
   "fmid":"HBB77C0",
   "fmiddesc":"BCP Base",
   "resolvers":[{
     "name":"UJ07031",
     "received":true
   }],
   "tgtzones:["TGT24"]},
  {"name":"CA62658",
   "holdclass":"PE",
   "holdsymptom":null,
   "heldsysmod":"UJ00132",
   "fmid":"HBB77C0",
   "fmiddesc":"BCP Base",
   "resolvers":null,
   "tgtzones:["TGT24"]}
  ]
}