You can use the z/OS data set and member utilities to work with data sets and members.
The available operations include: rename data set, rename member, copy data set, copy member,
migrate data set, recall a migrated data set, and 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 data set 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 6 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.
Custom headers
The header Content-Type: application/json; charset={charset-name} must be
specified, too.
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 can 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.
X-IBM-Target-System = <string>
This header indicates the target system name (nick name) for this request, where the system name
(nick name) is defined in the local system Systems table. The target host system must support
single-sign-on by using either an LTPA token or a valid X-IBM-Target-System-User
and X-IBM-Target-System-Password is provided for the target system. If the target
system is the local system, this header is ignored and has no effect.
X-IBM-Target-System-User
This header indicates the z/OS user ID that allows the user to access the target system. If the
X-IBM-Target-System header is not supplied, this header is ignored. Both
X-IBM-Target-System-Password and X-IBM-Target-System-User must be
provided together; otherwise, this header is ignored.
If this header is not provided in the
current request, the current request uses the authenticated user credentials to access the target
system if either of the following conditions are true:
The X-IBM-Target-System-User header was provided in a previous request
This header indicates the password that is associated with the z/OS user ID. If the
X-IBM-Target-System header is not supplied, this header is ignored. Both
X-IBM-Target-System-Password and X-IBM-Target-System-User must be
provided together; otherwise, this header is ignored.
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
request
Indicates the function name.
Yes
wait:true|false
If true, the function waits for completion of the request. If false (default) the request is
queued.
No
hrecall
request
Indicates the function name.
Yes
wait:true|false
If true, the function waits for completion of the request. If false (default) the request is
queued.
No
hdelete
request
Indicates the function name.
Yes
wait:true|false
If true, the function waits for completion of the request. If false (default) the request is
queued.
No
purge:true|false
If true, the function uses the PURGE=YES on ARCHDEL request. If false (default) the function
uses the PURGE=NO on ARCHDEL request.
No
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 can 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 file name. This value is required.
type
One of "binary | executable | text". Default is text. This is not required.
from-dataset
The data set to copy.
dsn
The source data set. This is required.
member
Used to specify a member; "*" means all members. This is not required.
volser
Can 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 is 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 data set 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.
Users of the IEBCOPY data set utility might be accustomed to freeing unused space
during a data set copy operation for a partitioned data set (PDS). This function is similar to ISPF
option 3.1 compress, in which the unused space occupied by deleted or updated members is removed
when a PDS is copied. The z/OS data set and member utilities REST API does not offer an equivalent
option for a data set copy operation.
On completion, the service returns an HTTP response, which includes a status code that indicates
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
See 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
See 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)
X-IBM-Target-System = <string>