Deleting the Temporary Catalog Aliases

When a software instance is created by the deployment action, a new master catalog may also be created. Temporary catalog aliases and data set aliases are created during the deployment to allow access to the target software instance data sets from both the driving and target systems. The "delete temporary catalog alias" action removes the temporary catalog aliases and data set aliases.

HTTP method and URI path

POST /zosmf/swmgmt/swi/<system-nickname>/<swi-name>/deltempcatalias
POST /zosmf/swmgmt/swi/<swi-uuid>/deltempcatalias
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 processed. 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 processed. 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.
  • /deltempcatalias indicates that the temporary catalog aliases and data set aliases that are created during the deployment process are to be deleted.

Standard headers

Use the following standard HTTP header with this request:

Accept-Language
Identifies the preferred language for messages that may 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. The JSON content type Content-Type: application/json is used for the JSON document, if there are any, and included as an 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.
{ 

 "jcldataset":"data-set-name",  
 "jobstatement":["jclrecord"], 
 "tgtsystem":"system-nickname", 
 "tgtjobstatement":["jclrecord"], 
 "unixdatasets":[{ 
   "dsname":"data-set-name", 
   "mountpoint":"UNIX-path" 
   }], 
 "systems":[{ 
   "name":"system-nickname", 
   "zosmfuid":"user-id", 
   "zosmfpw":"password", 
   "proxyuid":"user-id", 
   "proxypw":"password" 
   }] 
}
Where:
jcldataset

Partitioned data set to contain the generated JCL. The data set name must comply with z/OS® data set naming conventions. If a data set with the specified name does not already exist, z/OSMF will create a data set residing on the target system for the software instance.

tgtsystem
Nickname of the system that is currently started with, or will be started with, the new master catalog created during the deployment for the subject software instance. This system has or will have access to the software instance data sets after the temporary catalog aliases are deleted and may or may not be the same as the current system for the software instance.
Use the nickname that is specified for the system definition in the z/OSMF Systems task. The nickname is required.
To manage the systems that are defined to z/OSMF, you can use the z/OSMF topology services. For more details, see Topology services.
jobstatement
List of JCL cards for the JOB statement to be used in the generated JCL that will run on the current system for the software instance. This is an optional property. If specified it must be 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 - 8 characters. If the JOB statement is not provided, the default is exactly //IZUDnntt JOB (ACCOUNT),'NAME' where nntt uniquely identifies the job sequence and type.
tgtjobstatement
List of JCL cards for the JOB statement to be used in the generated JCL that will run on the target system for the software instance. This is an optional property. If specified it must be 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 the JOB statement is not provided, the default is exactly //IZUDnntt JOB (ACCOUNT),'NAME' where nntt uniquely identifies the job sequence and type.
unixdatasets
List of UNIX file system data sets in the software instance that are currently not mounted. Because they are currently not mounted, they 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 that contain 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.
systems
List of authentication credentials for remote z/OSMF servers. This is an optional property.
system
Nickname of the system for a remote z/OSMF server. This name must match either the system where the software instance resides or the target system for the operation.
zosmfuid
Userid for authenticating with the named remote z/OSMF server. This is an optional property.
zosmfpw
Password for authenticating with the named remote z/OSMF server. 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 may need to specify the remote z/OSMF user ID, password, and proxy user ID and password on the systems property.

Required authorizations

To submit requests through the software management services, the user ID that initiates the request requires the same authorizations as when you perform an analogous operation that uses the z/OSMF Software Management task. That is, to delete the temporary catalog aliases for a software instance, the user ID must have READ access to the Software Management task, and UPDATE access to the SAF resources for the software instance that is 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

Generating JCL to delete the temporary catalog aliases for 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 that contains 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"
}
statusurl
Indicates the URL that provides status for the "delete temporary catalog aliases" 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 that contains status information for the operation.
  • If the operation is complete, then an HTTP response code of 200 OK is returned, along with a JSON document that contains status information and the desired result set.
  • If the request is expired, then an HTTP response code of 404 Not found is returned. That is, when the operation is complete, the z/OSMF server holds the result set for a finite length of time. After that length of time has passed, the result set is said to expire and is no longer 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)"],
 "jobs":[{ 
   "jobname":"job-name", 
   "jobid":"job-id", 
   "retcode":"completion-code" 
   }],
"swiurl":"swi-URL"
}
status

The status of the "delete temporary catalog aliases" request. The status can be either "running" or "complete".

percentcomplete

The percentage of the processing that is complete for this delete temporary catalog aliases request, expressed as a whole number from 0 to100.

jcl

Ordered list of generated jobs for the delete temporary catalog aliases 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)".

jobs
Ordered list of batch jobs submitted to delete the temporary catalog aliases.
jobname
Job name.
jobid
Job ID.
retcode
Job completion code.
swiurl

URL that allows you to access the updated software instance. For example, a client application can use the URL to get the software instance properties or list the data sets in the software instance.

For more information about the error response document that contains a reason code and a list of one or more message strings to describe the errors that are detected during the processing of a request, see Error handling.

Example

The example request #izuprog_API_DeleteTempCatAliases__ExampleRequestRemoveTempCatAlias deletes the temporary catalog aliases for the software instance that is named zos25 on SYS123.
POST /zosmf/swmgmt/swi/SYS123/zos25/deltempcatalias HTTP/1.1
Host: sys123.yourco.com
Content-Type: application/json
Accept-Language: en
{
"jcldataset":"USERID.SMJCL.CNTL",
"jobstatement":["//JOBNAME  JOB (12345),'USER',NOTIFY=&SYSUID",
"//    MSGCLASS=H,MSGLEVEL=1,REGION=0M","//*"],
"tgtsystem":"SYSNEW"
}
A sample response is described in #izuprog_API_DeleteTempCatAliases__ExampleResponseRemoveTempCatAlias:
HTTP/1.1 202 Accepted
Date: Tues, 1 February 2022 18:53:04 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"statusurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/statusmonitor\/deltempcatalias\/4837290198343"}
The example response #izuprog_API_DeleteTempCatAliases__ExampleResponseRemoveTempCatAlias indicates the request to delete temporary catalog aliases for the software instance is accepted, and the status monitor URL is provided. A subsequent GET request to the status monitor URL is described in #izuprog_API_DeleteTempCatAliases__SampleGETrequestStatusMonitorURL:
GET /zosmf/swmgmt/statusmonitor/deltempcatalias/4837290198343 HTTP/1.1
Host: sys123.yourco.com
A sample response is described in #izuprog_API_DeleteTempCatAliases__SampleGETresponseStatusMonitorURL:
HTTP/1.1 200 OK
Date: Tues, 1 February 2022 18:53:27 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"status":"complete", "percentcomplete":"100",
"jcl":["USERID.SMJCL.CNTL(IZUD01UC)",
"USERID.SMJCL.CNTL(IZUD01DA)",
"USERID.SMJCL.CNTL(IZUD01DT)"],
"jobs":[{"jobname":"IZUD01UC","jobid":"JOB12345","retcode":"CC 0"},
{"jobname":"IZUD02DA","jobid":"JOB12347","retcode":"CC 0"},
{"jobname":"IZUD03DT","jobid":"JOB12349","retcode":"CC 0"}],
"swiurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/swi\/SYSNEW\/zos25"