List the data sets included in a software instance
You can use this operation to obtain a list of the data sets that compose a software
instance.
HTTP method and URI path
POST /zosmf/swmgmt/swi/<system-nickname>/<swi-name>/datasets
POST /zosmf/swmgmt/swi/<swi-uuid>/datasets
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 retrieved. 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.
In
addition, the software instance UUID can be used instead of
<system-nickname/swi-name> to identify the software instance.
<swi-uuid> further qualifies the request and indicates the
specific software instance to be retrieved. 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 List the software instances defined to z/OSMF REST API.
datasets indicate that the data sets included in the software instance are to be
obtained.
When you issue this request, z/OSMF analyzes the
global, target, and distribution zones included in the software instance to identify the SMP/E
managed data sets and the SMP/E managed UNIX data sets that
contain the installed software that is described in those zones. z/OSMF returns a JSON
object that lists the properties of each data set it identified, along with the properties of each
non-SMP/E managed data set included in the software instance.
Standard headers
Use the following standard HTTP header with this request:
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.
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.
Custom headers
None.
Request content
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. To do so, include the following
JSON object in your request:
Figure 1. Request content to authenticate with a
secondary z/OSMF
instance and an HTTP proxy server
User ID for authenticating with the secondary z/OSMF instance.
zosmf-password
Password for authenticating with the secondary z/OSMF instance.
proxy-user-ID
User ID for authenticating with the HTTP proxy server.
proxy-password
Password for authenticating with the HTTP proxy server.
Include the JSON object in the request only if you are required to authenticate with a secondary
z/OSMF instance or
an HTTP proxy server. Otherwise, omit the JSON object.
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 by using the z/OSMFSoftware Management task. That
is, the user ID must have READ access to both the Software Management task and the
SAF resources that are required to process the request. 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.
Expected response
On completion, the service returns an HTTP response, which includes a status code that indicates
whether your request was accepted. If the request was accepted, the service returns status code
202 Accepted and a JSON object that contains a URL
({"statusurl":"url"}). To monitor the status of the list data sets request and to
retrieve the results, perform GET requests to the supplied URL. Only the user ID that initiates the
list data sets request is authorized to check the status and retrieve the results. One of the
following responses is returned from the get status request:
If the list data sets request is still in progress, an HTTP response code of 200
OK is returned, along with the following JSON object: {"status":"status",
"percentcomplete":"percent-complete"}.
If the list data sets request is complete, an HTTP response code of 200 OK is
returned, along with the following JSON object:
Status of the list data sets request. The status is either running or
complete.
percent-complete
Percentage of the processing that is complete for the list data sets request, expressed as a
whole number from 0 to 100.
swidatasets
Lists all the data sets included in the software instance. A software instance can contain:
smpemanageddatasets. Array of the SMP/E managed data sets included in the software
instance.
smpemanagedunixdatasets. Array of the SMP/E managed UNIX file system data sets included in the software instance.
nonsmpemanageddatasets. Array of the non-SMP/E managed data sets included in the software
instance.
data-set-name
Name of the data set.
UNIX-directory
Array of the UNIX directories contained in the data set.
If z/OSMF could not
identify the UNIX file system data set for any UNIX directories, the data set name for those directories is set
to No Data Set Found. Typically, this occurs when the UNIX file system data set is not mounted.
volume-serial
Array of the volume serials for the volumes on which the data set resides. If the data set is
migrated, a value of MIGRAT is returned.
data-set-type
Type of data set. The data set can be one of the following types:
HFS. Hierarchical file system.
PDS. Partitioned data set.
PDSE. Partitioned data set extended.
Sequential. Sequential data set.
VSAM. VSAM data set.
ZFS. zSeries file system.
record-format
Record format specified when the data set was allocated. The record format can be any valid
combination of the following codes:
A. ASA printer control characters.
B. Blocked records.
F. Fixed-length records.
M. Machine code printer control characters.
S. Standard (for F) or spanned (for V); used only with sequential data sets.
T. Track-overflow feature.
U. Undefined format records.
V. Variable-length records.
logical-record-length
Logical record length, in bytes, specified when the data set was allocated.
block-size
Block size, in bytes, specified when the data set was allocated.
allocated-tracks
Number of tracks allocated to the data set.
used-tracks-percent
Percentage of allocated tracks used, expressed in whole numbers, not rounded. If any track is
used, the minimum percentage is 1. If the data set is a PDSE, the percentage refers to the
percentage of allocated pages used.
allocated-extents
Number of extents that are allocated to the data set.
dscategory
List of categories for how the data set is used. Can be one or more of the following:
TARGET - SMP/E managed target library, or SMP/E control data set associated with a target
zone.
DLIB - SMP/E managed distribution library, or SMP/E control data set associated with a
distribution zone.
GLOBAL - SMP/E control data set associated with the global zone.
SMP/E - SMP/E control data set.
WORKFLOW - Contains one or more workflow definition files for the workflows that are explicitly
defined to the software instance.
zones
Array of the SMP/E zones that contain a DDDEF entry for the data set. For an SMPCSI data set, it
is an array of the SMP/E zones that are contained in the data set.
zonedeffs
Array of SMP/E zones and DDDEF entries for the data set.
zone-name
Name of an SMP/E zone that contains one or more DDDEF entries for the data set.
dddef-name
Array of DDDEF entry names that identify the data set.
message-text
Array of messages returned for the data set.
If the list data sets request is complete but the results are no longer available, an HTTP
response code of 404 Not found is returned. z/OSMF makes the results
available for a client application for a finite period of time. When that time elapses, the results
are no longer available; in which case, the client must reissue the request.
If the list data sets request cannot be processed, a status code of 4nn or 5nn is
returned, indicating that an error has occurred. For more details, see Error handling.
Example
In the following example, the POST method is used to retrieve a list of the data sets included in
software instance DB2V9 on system SYS123. Figure 2. Sample request to list the data sets included in a software
instance
POST /zosmf/swmgmt/swi/SYS123/DB2V9/datasets HTTP/1.1
Host: sys123.yourco.com
Figure 3 provides a sample response, which indicates
that the list data sets request has been accepted and is supplying the URL to use for monitoring the
status of that request. Figure 3. Sample response for a list data sets request
HTTP/1.1 202 Accepted
Date: Tues, 21 November 2014 18:53:04 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"statusurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/statusmonitor\/dslist
\/4837290198343"}
To check the status of the list data sets request, submit the following request:
Figure 4. Sample request to obtain the
status of a list data sets request
GET /zosmf/swmgmt/statusmonitor/dslist/4837290198343 HTTP/1.1
Host: sys123.yourco.com
Figure 5 provides a sample response for when the list
data sets request is in progress. Figure 5. Sample get status response when the list data sets request is in progress
HTTP/1.1 200 OK
Date: Tues, 21 November 2014 18:53:19 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"status":"running", "percentcomplete":"65"}
Figure 6 provides a sample response for when the list
data sets request is complete.
Figure 6. Sample get status response
when the list data sets request is complete