z/OS Data set and member utilities

You can use the Data set and member utilities to operate on data sets or members. Operations include: rename data set, rename member, copy data set and copy member, migrate data set, recall a migrated data set, delete a backup version of a data set.

HTTP method and URI path

Figure 1. 'rename' request

PUT /zosmf/restfiles/ds/<to-data-set-name>
PUT /zosmf/restfiles/ds/<to-data-set-name>(<member-name>)

Figure 2. 'copy' request

PUT /zosmf/restfiles/ds/<to-data-set-name>
PUT /zosmf/restfiles/ds/<to-data-set-name>(<member-name>)
PUT /zosmf/restfiles/ds/-(<to-volser>)/<to-data-set-name>
PUT /zosmf/restfiles/ds/-(<to-volser>)/<to-data-set-name>(<member-name>)

Figure 3. ''hmigrate' , 'hrecall', or 'hdelete' request

PUT /zosmf/restfiles/ds/<to-data-set-name>

where:

/zosmf/restfiles specifies the z/OS® data set and file REST interface
/ds indicates a Dataset request
-(<volser>) represents a volume serial. For an uncataloged data set, include this parameter to identify the volume to be searched for data sets or members that match the specified <data-set-name> or <member-name>. The length of the volume serial cannot exceed six characters. You cannot use wildcard characters for this parameter. Indirect volume serials are not supported.
<to-data-set-name> identifies the target data set name. This parameter is required and must consist of a fully qualified data set name. The length of the data set name that you specify on the request cannot exceed 44 characters.
<member-name> identifies the target PDS or PDSE member name.

Headers

X-IBM-BPXK-AUTOCVT

This header is optional; use it to indicate how file auto conversion is handled when using the copy operation to copy text mode data sets to POSIX files, if you omit this header, the system default is taken.

'on' or 'all': The target file is a candidate for automatic conversion if its TXTFLAG is tagged TEXT and the source data set is type TEXT.
'off': The target file is not a candidate for automatic conversion

X-IBM-Migrated-Recall

This header is optional; use it to specify how a migrated data set is handled. By default, a migrated data set is recalled synchronously. The following values may be specified too:

wait: This is the default value. If the data set is migrated, wait for it to be recalled before processing the request.
nowait: If the data set is migrated, request it to be recalled, but do not wait.
error: If the data set is migrated, do not attempt to recall the data set.

The header, Content-Type: application/json; charset={charset-name}, must be specified as well.

Request body

A JSON request document (content-type=application/json, character-encoding=UTF-8) must be supplied in one of the following forms:

Table 1. Request
Function	Property	Description	Required
hmigrate	wait:true\|false	If true then the function waits for completion of the request. If false the request is queued.
hrecall	wait:true\|false	If true then the function waits for completion of the request. If false the request is queued.
hdelete	wait:true\|false	If true then the function waits for completion of the request. If false the request is queued.
hdelete	purge:true\|false	If true then the function uses the PURGE=YES on ARCHDEL request. If false the function uses the PURGE=NO on ARCHDEL request.
rename	request	Indicates the function name.	Yes
	from-dataset	The data set to rename.	Yes
		dsn The source data set name. This is required	Yes
		member If renaming a member this is the old member name. This is not required.	No
	enq	enq for the "to" data set is only allowed for renaming members. Values may be SHRW or EXCLU. SHRW is the default or PDS members, EXCLU otherwise.	No
copy	request	Indicates the function copy.	Yes
	from-file	The file to copy.	You must choose either from-file or from-dataset.
		filename The absolute source filename. This is required.
		type One of "binary \| executable \| text". Default is text. This is not required.
	from-dataset	The dataset to copy.
		dsn The source data set. This is required.
		member Used to specify a member; "*" means all members. This is not required.
		volser May be specified if dsn is not cataloged. This is not required.
		alias:true\|false if true, aliases are copied along with main member;if false(default), alias relationships are not maintained. This is not required.
	enq	Only applicable when from-dataset specified. With from-file, an error is reported (see note below).This is the enqueue type for the "to" data set. Allowed values are: SHR, SHRW, EXCLU;SHRW is the default for PDS, EXCLU for sequential. The source data set is always enqueued via SHR. Note: When from-file is specified, the target dsn is opened with DISP=OLD (EXCLU) with one exception: if the target is a PDS and the from-file/type is text, the target PDS is enqueued SHRW. This is not required.	No
	replace:true\|false	Applicable with from-dataset. When from-file specified,ignored unless from-file/type=text. if true, members in the target dataset are replaced. if false(default), like named members are not copied and an error is returned.	No

Note: The "to" data set must be a PDS if from-dataset/member is '*' or a <member-name> is specified on the URL. When from-dataset/member is a single member name and the member name is NOT specified on the URL, the 'to' data set is expected to be sequential.

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 OK indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

For errors, the HTTP response includes error information as a JSON error report document. See Error report document.

Example

Refer to Figure 4 for an example of renaming a data set.

Figure 4. Example: Rename MY.OLD.DSN to MY.NEW.DSN

Request:
PUT https://zosmf1.yourco.com/zosmf/restfiles/ds/MY.NEW.DSN HTTP/1.1
Content-Type: application/json; charset=UTF-8

{"request":"rename", "from-dataset":{"dsn":"MY.OLD.DSN"}}

Example

Refer to Figure 5 for an example of copying a PDS member.

Figure 5. Example: copy member MYMEM1 from MY.OLD.DSN to MY.NEW.DSN(MYMEM2)

Request:
PUT https://zosmf1.yourco.com/zosmf/restfiles/ds/MY.NEW.DSN(MYMEM2) HTTP/1.1
Content-Type: application/json; charset=UTF-8

{"request":"copy", "from-dataset":{"dsn":"MY.OLD.DSN", "member":"MYMEM1"}, "replace":true }