Retrieve the properties of a portable software instance

You can use this operation to retrieve the properties of a portable software instance.

HTTP method and URI path

GET /zosmf/swmgmt/pswi/<system-nickname>/<pswi-name>

where:

zosmf/swmgmt: Identifies the software management services.
pswi: Informs the service that the request is for a portable software instance object.
<system-nickname>: Nickname of the z/OSMF host system that has access to the volumes and data sets where the portable software instance is located. In combination with <pswi-name>, it further qualifies the request and indicates the specific portable software instance to retrieve.
To obtain information about the specified system, you can use the z/OSMF topology services. For more information, see Topology services.
<pswi-name>: Name of the portable software instance. In combination with <system-nickname>, it further qualifies the request and indicates the specific portable software instance to retrieve.

Standard headers

Use the following standard HTTP header with this request:

Accept-Language

Identifies the preferred language for any messages that are returned to the caller. The following values are acceptable:

Accept-Language: en (English)
Accept-Language: ja (Japanese)

If any other language value is specified or if the header is omitted, then English is used.

Custom headers

None.

Request content

None.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

Certain authorizations are required to submit a request through the software management services to read a portable software instance. The user ID that initiates the request requires the same authorizations as the ones needed to perform a read operation with the z/OSMF Software Management task. The user ID needs READ access to both the Software Management task and the SAF resources that correspond to the portable software instance to retrieve. For more 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 with a status code that indicates whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error occurred. For more information about errors, see Error handling.

If the request is successful, the response also includes the following JSON object:

{
   "name":"pswi-name",
   "system":"system-nickname", 
   "description":"pswi-description",
   "directory":"UNIX-directory",
   "categories":["categories"],
   "serverxml": ["remote-server-xml"],
   "clientxml": ["client-options-xml"],
   "jcldataset": "jcl-data-set-name",
   "lastmodified":"last-modified", 
   "modifiedby":"modified-user-ID",
   "created":"date-created",
   "createdby":"created-user-ID",
   "locked":"date-locked",
   "lockedby":"locked-user-ID", 
   "signatureverificationkeyring":"keyring",
   "packagesignercertdetails":{
      "subjectname":"subject-name",
      "serialnumber":"serial-number",
      "fingerprint":"finger-print",
      "issuer":"issuer-subject-name"
},

   "products": [{
      "prodname": "product-name",
      "productid": "product-ID",
      "release": "release-level",
      "vendor": "vendor-name",
      "generalavailability": "general-availability-date",
      "endofservice": "end-of-service",
      "url": "product-URL",
      "productinfofileversion": "file-version",
      "features": [
         "feature-name"
      ]
   }],
   "nonsmpeproducts": [{
      "prodname": "product-name",
      "productid": "product-id",
      "release": "release-level",
      "vendor": "vendor-name",
      "generalavailability": "general-availability-date",
      "endofservice": "end-of-service-date",
      "url": "product-url",
      "productinfofileversion": "file-version",
      "features": [
         "feature-name"
      ]
   }]
}

where:

pswi-name

Name of the portable software instance.

system-nickname

Nickname of the z/OSMF host system that has access to the volumes and data sets where the portable software instance is located.

To obtain information about the specified system, you can use the z/OSMF topology services. For more information, see Topology services.

pswi-description

Description of the portable software instance.

UNIX-directory

UNIX directory that contains the portable software instance files.

categories

Comma-separated list of the categories to which the portable software instance is assigned.

remote-server-xml

Information from when the Add Portable Software Instance from Download Server action was used to define the portable software instance. This information identifies the download server and the location of the portable software instance files on that server.

The GIMGTPKG program uses this XML to download the portable software instance files. For more information, see Content of SERVER data set in z/OS SMP/E Commands.

client-options-xml

Information about the local z/OS server used to download the files from a download server by the Add Portable Software Instance from Download Server action. The value is either the XML used by the GIMGTPKG program to download the portable software instance files, or it is the name of a data set or UNIX file that contains the XML. For more information, see Content of CLIENT data set in z/OS SMP/E Commands. End of change

jcl-data-set-name

Information from when the Add Portable Software Instance from Download Server action was used to define the portable software instance. This value lists the name of the data set that contains the generated JCL that was used to download the portable software instance files from a remote download server.

last-modified

Date and time, in ISO 8601 format, that the portable software instance was last modified.

modified-user-ID

User ID of the user who last modified the portable software instance.

date-created

Date and time, in ISO 8601 format, that the portable software instance was created.

created-user-ID

User ID of the user who created the portable software instance.

date-locked

Date and time, in ISO 8601 format, that the portable software instance was locked. This attribute is null if the portable software instance is not currently locked.

locked-user-ID

User ID of the user who locked the portable software instance. This attribute is null if the portable software instance is not currently locked.

signatureverificationkeyring

Identifies the location of the certificate that is used to validate the digital signature of the portable software instance. This is the name for a security manager keyring or "javatruststore". The value "javatruststore" indicates that the certificates in the default Java truststore were used to validate the digital signature. A Java truststore is a Java keystore file that contains the collection of the trusted Certificate Authority (CA) certificates. The default Java truststore is located relative to the Java home directory.

packagesignerdetails

Container for information that pertains to the certificate that is used to sign the portable software instance.

subjectname: The subject name of the certificate that is used to sign the portable software instance.
serialnumber: The serial number of the certificate that is used to sign the portable software instance.
fingerprint: The digital fingerprint of the certificate that is used to sign the portable software instance.
issuer: The subject name of the root certificate that issued the certificate that is used to sign the portable software instance.

products

Array that contains each product that is included in the portable software instance.

product-name: Name of the product. If any FMIDs are not related to a product and feature, those FMIDs are listed under a product that is named No Product.
product-ID: Identifier of the product.
release-level: Version, release, and modification level of the product. The value has the format VV.RR.MM, where VV is the two-digit version, RR is the two-digit release, and MM is the two-digit modification level.
vendor-name: Name of the vendor that provides the product.
general-availability-date: Date on which this level of the product is available to all users.
end-of-service: Last date on which the vendor delivers standard support services for this level of the product. This date is the general end of service date. It does not account for lifecycle extensions.
product-URL: URL that links to additional information about the product. This information can include, for example, product lifecycle dates, product highlights, planning information, and technical descriptions.
file-version: Version of the most recently retrieved product information file that contains the corresponding product. The version represents the date on which the file was created or last updated.
features: Array that contains each feature that is included in the product.
feature-name: Name of the feature. If any FMIDs are not related to a product and feature, those FMIDs are listed under a feature that is named No Feature.

nonsmpeproducts

List of products for the portable software instance that are not managed by SMP/E.

product-name

Name of the product. The value can contain up to 64 characters.

product-ID

Identifier for the product. The value can contain up to 64 characters.

release-level

Release level for the product. The value can contain up to 64 characters.

vendor-name

Name of the vendor that provides the product. The value can contain up to 64 characters.

product-URL

A URL that links to additional information about the product. The value can contain up to 256 characters.

feature-name

List of names of features for the product. The value can contain up to 64 characters.

general-availability-date

Date on which this level of the product is available to all users.

end-of-service-date

Last date on which the vendor delivers standard support services for this level of the product. This date is the general end of service date. It does not account for lifecycle extensions. The following values are acceptable:

NotAnnounced: The end of service date is not yet announced for the product.
null: The end of service date is unknown for the product.
yyyy-mm-ddThh:mm:ssZ: The known end of service date, in ISO 8601 format.

Example

In the following example, the GET method is used to retrieve the properties of portable software instance Hooli on system PEV174.

Figure 1. Sample request to retrieve the properties of a portable software instance

GET /zosmf/swmgmt/pswi/PEV174/Hooli HTTP/1.1
Host: pev174.yourco.com

A sample response is shown in Figure 2.

Figure 2. Sample response from a request to retrieve the properties of a portable software instance

HTTP/1.1 200 OK
Date: Tues, 05 June 2020 18:53:27 +00004GMT
Content-Type: application/json
Content-Language: en
Connection: close

{
"name":"DB2V9", "system":"PEV174", "description":null, "directory":
"/u/fred/DB2V9", "categories":null," "lastmodified":"2014-08-20T19:23:25+00:00", 
"modifiedby":"FRED", "created":"2014-08-20T19:23:25+00:00","createdby":"BARNEY", 
"locked":null, "lockedby":null, "products":[{"prodname":"DB2 for z/OS", 
"productid":"5635-DB2", "release":"09.01.00","vendor":"IBM", 
"generalavailability":"20006-06-09T19:23:25+00:00","endofservice":"2014-06-
27T19:23:25+00:00", "url":null,"productinfofileversion":"2014-01-01", 
"features":["feature":"DB2 Base"]}], "nonsmpeproducts": [{"prodname": 
"Acme Software","productid": "5990-ACME","release": "100","vendor": 
"Acme Software Products","generalavailability": "2020-01-01T00:00:00Z",
"endofservice": "2021-06-01T00:00:00Z","url": "http:\/\/acmesoftware.com",
"features": ["Runtime"]}],
}