Query an SMP/E CSI

HTTP method and URI path

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

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

POST /zosmf/swmgmt/csi/csiquery/<csi-data-set-name>

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. Use the JSON content type ("Content-Type: application/json") if a JSON document is included as input with this request.

Custom headers

None.

Request content

The request must include a JSON document that identifies properties that are required to perform the operation.

{
"zones":["zone-name"],
"entries":["entry-type"],
"subentries":["subentry-type"],
"filter":"filter-sring",
"zosmfuid":"user-id",
"zosmfpw":"password",
"proxyuid":"user-id",
"proxypw":"password"
}

Required authorizations

To submit requests 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 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

See Usage considerations for the z/OSMF REST services.

Expected response

Querying an SMP/E CSI data set 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 containing 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"
} 

{
 "status":"status",
 "entries":[{
  "entryname":"entry-name",
  "entrytype":"entry-type",
  "zonename":"zone-name",
  "subentries":[{
    "sub-entry-type":["sub-entry-value"],
    "VER":"ver-statement-sequence"
   }]
 }]
}

status

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

entries

List of CSI entries from the requested zones which satisfy the requested entry types and filter conditions.

entryname

The name for the entry.

entrytype

The type for the entry.

zonename

The name of the zone where the entry resides.

subentries

The list of subentries returned for the entry. The list may be null if no subentries are returned for a particular entry.

sub-entry-type

The type for the subentry. Refer to Valid subentry types in z/OS SMP/E Reference for the list of possible subentry types and descriptions of the subentry values.

sub-entry-value

The list of values for the subentry.

VER

The ++VER statement sequence number is returned for each SYSMOD entry subentry type that originates on a SYSMOD's ++VER statement. A SYSMOD may contain multiple ++VER statements, therefore, the sequence number identifies on which ++VER statement the subentry originated. In other words, a ++VER sequence number will be returned for each of the following subentry types: DELETE, FMID, NPRE, PRE, REQ, SREL, SUPING, and VERSION.

See Error handling for the error response document containing a reason code and a list of one or more message strings to describe the errors that are detected during processing of a request.

Example

The following request performs an SMP/E CSI query for the software instance that is named zos24 on SYS123, to get the list of PTF SYSMODs and their FMIDs and SOURCEIDs in the ZOS24T zone.

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

{"zones":["ZOS24T"],"entries":["SYSMOD"],"subentries":["FMID",
"SOURCEID"],"filter":"SMODTYPE=’PTF’"} 

A sample response is as follows:

HTTP/1.1 202 Accepted
Date: Tues, 12 September 2023 18:53:04 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"statusurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/statusmonitor\/csiq
uery\/4837290198343"}

The above response indicates the request has been accepted, and the status monitor URL is provided. A subsequent GET request to the status monitor URL is as follows:

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

A sample response is as follows:

HTTP/1.1 200 OK
Date: Tues, 12 September 2023 18:53:27 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{
 "status":"complete",
 "entries":[
  {"entryname":"UO12345",
   "entrytype":"SYSMOD",
   "zone":"ZOS24T",
   "subentries":[
    {"FMID":["HUD1234"],"VER":"001"},
    {"SOURCEID":["RSU2304","PUT2301","IBM.ProductInstall-RequiredService"]}
    ]
   },
   {"entryname":"UO45678",
    "entrytype":"SYSMOD",
    "zone":"ZOS24T",
    "subentries":[
     {"FMID":["HUD1234"],"VER":"001"},
     {"SOURCEID":["RSU2308","PUT2305"]}
     ]
   },
   {"entryname":"UR90123",
    "entrytype":"SYSMOD",
    "zone":"ZOS24T",
    "subentries":[
     {"FMID":["JUD5678"],"VER":"001"}
     ]
   }
}