Export a defined software instance

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

POST /zosmf/swmgmt/swi/<swi-uuid>/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.

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

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.

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",
 "datasetmergeallowed":"yes | no",
 "signingcertificate":"certificate-label",
 "keyring":"keyring-name" | "userid/keyring-name",
 "jobstatement":["jclrecord"],
 "unixdatasets":[{
   "dsname":"data-set-name",
   "mountpoint":"UNIX-path"
   }],
 "workdsnprefix":"data-set-name-prefix",
 "workvolume":"volume-serial",
 "workstorclas":"storage-class",
 "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".

datasetmergeallowed

Indicates whether the merging of the data sets is allowed when you deploy the portable software instance. This is an optional property. Can be "null", "yes" or "no". The default value is "no".

signingcertificate

The label to identify the certificate that is used to sign the portable software instance. This certificate is bound to the private key that is used to sign the GIMZIP package. It contains the matching public key that is used to verify the signature later. This is an optional property, but if specified, the portable software instance is digitally signed.

Certificate labels are from 1 to 32 characters in length and may include only characters X'40' through X'FE', excluding the reserved XML characters, less than (<), greater than (>), double quotation mark ("), and ampersand (&).

If you specify signingcertificate, then you must also specify keyring.

keyring

The security manager key ring that contains the specified signing certificate. The keyring must also contain all certificates in the certification path from the signing certificate to the issuing root CA certificate.

Key ring names are from 1 to 237 characters in length and may include only characters X'40' through X'FE', excluding the forward slash (/) and the reserved XML characters, less than (<), greater than (>), double quotation mark ("), and ampersand (&).

If the key ring is associated with a user ID other than the one that is used to execute the program GIMZIP, then the key ring name must be prefixed with the associated user ID. User IDs are from 1 to 8 alphanumeric characters in length, and can consist entirely of numbers and need not begin with any particular character. The user ID is separated from the key ring value by a forward slash (ie. userid/keyring).

If you specify keyring, then you must also specify signingcertificate.

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 2 of 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.

workdsnprefix

Data set name prefix for the work data sets that are created, used, and then deleted in the generated Export JCL.

z/OSMF uses a work zFS data set to contain temporary UNIX directory space. The prefix can contain up to 26 characters, including periods, and must comply with z/OS data set naming conventions. This value is optional.

Notes:

• If one or more of the workdsnprefix, workvolume, or workstorclas values are specified, then the generated JCL creates, mounts, uses, unmounts, and deletes a work zFS data set. If none of those three values are specified, then the generated JCL does not create and use a work zFS data set and instead uses /tmp as the temporary UNIX directory space.
• If you specify workdsnprefix but do not provide values for either workvolume or workstorclas, then the volume and storclas are not specified in the generated JCL on the IDCAMS DEFINE CLUSTER command to create the zFS data set.
• If workdsnprefix is not specified but either workvolume or workstorclas is provided, then a default data set name prefix of z/OSMF-ID.WRKDSN is used, where z/OSMF-ID is the logged-in user ID that is used to authenticate to the z/OSMF server.

workvolume

Volume for the work data sets that are created, used, and then deleted in the generated Export JCL.

The volume serial value must contain 1-6 characters. Valid characters are uppercase alphabetic characters (A-Z), numeric characters (0-9), and national characters ($, #, @). This value is optional.

Notes:

• See workdsnprefix for notes that also apply here.
• The workvolume and workstorclas properties are mutually exclusive.

workstorclas

Storage class for the work data sets that are created, used, and then deleted in the generated Export JCL.

The storage class value can contain up to eight characters. Valid characters are alphabetic characters (A-Z, a-z), numeric characters (0-9), and national characters ($, #, @). This value is optional.

Notes:

• See workdsnprefix for notes that also apply here.
• The workvolume and workstorclas properties are mutually exclusive.

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.

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)".

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

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:

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:

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:

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)"]
}

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","//*"]
}

Submit the export job:

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

Obtain status for the export job:

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

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.