Export a defined software instance

A portable software instance is a set of portable files that represent the content of a z/OSMF software instance. An Export action on a software instance is used to create a portable software instance. You can use the POST method to perform an Export action on a software instance that is defined to z/OSMF, which generates a portable software instance descriptor file and JCL that when executed creates the archive files for a portable software instance, and store those files in a UNIX directory on the system where the software instance being exported resides.

HTTP method and URI path

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

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 exported. 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.
/export indicates JCL to perform an export action for the software instance is to be generated.

Standard headers

Use the following standard HTTP headers 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, then 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

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

{
 “packagedir”:“UNIX-directory”,
 “jcldataset”:“data-set-name”,
 “includedlibs”:“yes | no”,
 “jobstatement”:[“jclrecord”],
 “unixdatasets”:[{
   “dsname”:“data-set-name”,
   “mountpoint”:“UNIX-path”
   }],
 “zosmfuid”:“user-id”, 
 “zosmfpw”:“password”,
 “proxyuid”:“user-id”,
 “proxypw”:“password”
}

where:

packagedir

UNIX directory to contain the files for the portable software instance.

Must be a UNIX directory with valid UNIX directory name syntax:

Must be an absolute pathname (must start with slash).
Must end with a slash.
Can be up to 1023 characters long.

jcldataset

Partitioned data set to contain the portable software instance descriptor file and the generated JCL.

The data set name must comply with z/OS data set naming conventions.

includedlibs

If the software instance contains SMP/E managed software, this property indicates whether the distribution libraries and DLIB zones are to be included in the portable software instance.

This is an optional property. Can be null, “yes” or “no”, but the default value is “yes”.

jobstatement

List of JCL cards for the JOB statement to be used in the generated JCL for the export operation.

This is an optional property. Can be null, or a list of JCL cards, each up to 72 characters long. Columns 1 and 2of each record must be “//” or “/*” and the job name must be 1 to 8 characters. If no JOB statement is provided, the default is exactly://IZUD01EX JOB (ACCOUNT),'NAME'.

unixdatasets

List of UNIX file system data sets in the software instance that are currently not mounted, and therefore, cannot be identified by z/OSMF by referencing the UNIX directories that are defined in the SMP/E target zone DDDEF entries.

This is an optional property, required only if the software instance describes SMP/E managed software, and if any of the UNIX file system data sets containing that software are currently not mounted.

dsname

Name of a UNIX file system data set.

The data set name must comply with z/OS data set naming conventions.

mountpoint

Mount point for the UNIX file system data set, if the data set were mounted.

Must have valid UNIX file name syntax:

Must be an absolute pathname (must start with slash).
Must not end with a slash, unless a slash is the only character. That is, “/” (root) is valid, but “/mountpoint/” is not.
Can be up to 1023 characters long.

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, but some properties are optional. 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 might also be required to authenticate with that HTTP proxy server. Therefore, you can 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 performing an analogous operation that uses the z/OSMF Software Management task. That is, to export a software instance, the user ID must have READ access to the Software Management task and READ access to the SAF resources for the software instance being exported. For information about access controls for the Software Management task, see IBM z/OS Management Facility Configuration Guide.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Expected response

Generating JCL to export 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 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”
}

where:

statusurl: Indicates the URL that provides status for the software instance export 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 containing status information for the operation.
If the operation has completed, then an HTTP response code of 200 OK is returned, along with a JSON document containing status information and the desired result set.
If the request has expired, 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 will no longer be available for the client to obtain.

The response to GET requests on the status monitor URL includes the following JSON document:

{
 “status”:“status”,
 “percentcomplete”:“percent”,
 “jcl”:[“data-set-name(member-name)”]
}

status: The status of the export request. The status can be either “running” or “complete”.
percentcomplete: The percentage of the processing that is complete for this export software instance request, expressed as a whole number from 0 to100.
jcl: Ordered list of generated jobs for the export action. Each job is a unique member in the JCL data set. The values are fully qualified data set and member names of the form “data-set-name(member-name)”.

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

Example

The following request generates an Export job for the software instance that is named DB2V9 on SYS123.

Figure 1. Sample request

POST /zosmf/swmgmt/swi/SYS123/DB2V9/export HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
Accept-Language: en
{
“packagedir”:“/u/userid/exportDir/”,
“jcldataset”:“USERID.SMJCL.CNTL”,
“includedlibs”:“yes”,
“jobstatement”:[“//EXPORT   JOB (123456),’USER’,NOTIFY=&SYSUID,”,
“// MSGCLAS=H”,“//*”]
}

A sample response is as follows:

Figure 2. Sample response

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\/export\/4837290198343”}

The above response indicates the request to generate an Export job for the software instance 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/export/4837290198343 HTTP/1.1
Host: sys123.yourco.com

A sample response is as follows:

Figure 3. Sample response

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”}

The above response indicates the operation to generate an Export job for the software instance is still running and 65% complete. A final request to the status monitor URL is as follows:

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

A sample response is as follows:

Figure 4. Sample response

HTTP/1.1 200 OK
Date: Tues, 21 November 2014 18:53:27 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{“status”:“complete”, “percentcomplete”:“100”,
“jcl”:[“USERID.SMJCL.CNTL(IZUD01EX)”]
}

Usage notes

The POST method to generate JCL that exports a software instance requires the subject software instance to be already defined to z/OSMF. If the software instance is not already defined, you can use the POST method to Add a new software instance to z/OSMF, followed by the PUT method to Load the products, features, and FMIDs for the new software instance if that software instance contains SMP/E managed software. Then, you can use the POST method to Export the software instance. For example:

Add the software instance:

POST /zosmf/swmgmt/swi HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
Accept-Language: en
{
"name":"DB2V9", 
"system":"sys123", 
"description":"DB2",
"globalzone":"DB2.GLOBAL.CSI", 
"targetzones":["DB2TGT"],
}

Load the products, features, and FMIDs for the software instance:

PUT /zosmf/swmgmt/swi/sys123/DB2/products HTTP/1.1
Host: sys123.yourco.com

Create JCL to export the software instance:

POST /zosmf/swmgmt/swi/sys123/DB2/export HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
Accept-Language: en
{
“packagedir”:“/u/userid/exportDir/”,
“jcldataset”:“USERID.SMJCL.CNTL”,
“includedlibs”:“yes”,
,
“jobstatement”:[“//EXPORT JOB (123456),'USER',NOTIFY=&SYSUID,”,
“// MSGCLAS=H”,“//*”]
}

The response from the POST method to create JCL to export the software instance specifies the members in the JCL data set that contain the generated jobs to perform the export action. You can use the z/OS jobs REST interface to submit and obtain the status of the export job. For example:

Submit the export job:

PUT /zosmf/restjobs/jobs HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
{
“file”:“//'USERID.SMJCL.CNTL(IZUD01EX)'”
}

The response to this PUT method provides the job ID and the job name for the submitted job.

Obtain status for the export job:

GET /zosmf/restjobs/jobs/IZUD01EX/job-id HTTP/1.1
Host: sys123.yourco.com

Sample REXX exec

A sample REXX exec that is named IZUDXEXP is provided in the SYS1.SAMPLIB data set to illustrate a program that uses Software management services to do the following:

Add a software instance.
Load the SMP/E Products, Features, and FMIDs for the software instance.
Generate JCL to export the software instance.
Run the generated JCL to create a portable software instance.

The sample REXX exec uses the HTTP REXX client of the z/OS Web Enablement Toolkit to perform HTTP operations to the z/OSMF server.