Missing FIXCAT Updates

The Missing FIXCAT Updates service helps you identify missing updates for fix categories that might be applicable to the software instance, and it identifies the SYSMODS that can resolve the missing updates.

HTTP method and URI path

POST /zosmf/swmgmt/swi/<system-nickname>/<swi-name>/missingfixcatupdates
POST /zosmf/swmgmt/swi/<swi-uuid>/missingfixcatupdates
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.
  • /missingfixcatupdates indicates that the Missing FIXCAT 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 requests 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 Missing FIXCAT 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"
 "missingfixcatupdates":[{
   "name":"sysmod-id",
   "fixcats":["fix-category"],
   "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.

missingfixcatupdates
List of software updates that are associated with one or more fix categories, which are not yet installed in the software instance target zones.
name

SYSMOD ID for the missing APAR.

fixcats

List of fix categories associated with the missing APAR.

fmid

FMID for the missing APAR.

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 inthe or no resolving SYSMODs are identified for missing APAR.
name
SYSMOD ID for the resolvin the global zone,g 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 FIXCAT updates for the software instance that is named zos24 on SYS123.
Figure 1. Sample POST request for Missing FIXCAT Updates
POST /zosmf/swmgmt/swi/SYS123/zos24/missingfixcatupdates 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 Mission FIXCAT 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\/missingfixcatupdates\/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 FIXCAT Updates
GET /zosmf/swmgmt/statusmonitor/missingfixcatupdates/4837290198343 HTTP/1.1
Host: sys123.yourco.com
A sample response is shown in Figure 4 :
Figure 4. Sample GET response for Missing FIXCAT 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"
 "missingfixcatupdates":[
  {"name":"CA61368",
   "fixcats":["IBM.ProductInstall-RequiredService"],
   "fmid":"HBB77C0",
   "fmiddesc":"BCP Base",
   "resolvers":[{
     "name":"UJ07031",
     "received":true
   }],
   "tgtzones:["TGT24"]},
  {"name":"CA62202",
   "fixcats":["IBM.ProductInstall-RequiredService"],
   "fmid":"HBB77C0",
   "fmiddesc":"BCP Base",
   "resolvers":[{
     "name":"UJ07520",
     "received":true
   }],
   "tgtzones:["TGT24"]}
  ]
}