Write data to a z/OS data set or member

You can use this operation to write data to an existing sequential data set, or a member of a partitioned data set (PDS or PDSE). To write to an uncataloged data set, include a volume serial on the request.

HTTP method and URI path

PUT /zosmf/restfiles/ds/[-(<volser>)/]<dataset-name>[(<member-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 six characters. You cannot use wildcard characters for this parameter. Indirect volume serials are not supported.
<dataset-name> identifies the data set to which to write. 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 name of the PDS or PDSE member to which to write. Include this parameter for a PDS or PDSE member write request.
If the member does not exist, it is created. If the data set name identifies a base name of a Generation Data Group (GDG), then member may refer to relative data sets, for example: (0), (+1), (-1)

Based on the object to which you want to write, you can specify one of the following parameter combinations:

/<data-set-name>: To write to a sequential data set.
/<data-set-name>(<member-name>): To write to a member of a PDS or PDSE.
/-(<volser>)/<data-set-name>: To write to an uncataloged sequential data set.
/-(<volser>)/<data-set-name>(<member-name>): To write to a member of an uncataloged PDS or PDSE.

Request body

The data to write to the target data set. The data is interpreted according to the content-type as one of binary, text, record or 'diff -e' format according a combination of the "Content-Type" and the value of the X-IBM-Data-Type custom header, if present.

Standard headers

You can include the following standard HTTP header with this request:

If-Match: This header is optional; use it to specify the ETag to be used for correlating this request with a previous request on the same resource. If the resource has not changed since the ETag token was generated, the data is written to the target data set or member. Otherwise, if the resource has been modified, the request is failed with status code HTTP 412.
If you omit this header, the data is always written, regardless of whether the resource is changed.

Custom headers

You can use the following custom HTTP header with this request:

X-IBM-Data-Type

This header is optional; use it to indicate whether data conversion is to be performed on the request body. Start of change

text: When set to text, data conversion is performed. The data transfer process converts each record from the charset specified on the "Content-Type" header of the request. If no charset is specified, the default is ISO8859-1. Each line of data, delimited by a Line Feed in the request charset, is converted to EBCDIC and written as a record to the data set or member. (The line feed character is removed from the data, and the data is padded with the space character to the end of the record if it is a fixed record size data set. For variable record size data sets, the record is written without padding.) If the record size of the data set is smaller than any line of text, an HTTP 400 is returned with a JSON error document indicating that not all data was written.
Note: When set to 'text' and "Content-Type" is "application/x-ibm-diff-e", the input consists of commands in the same format as produced by the z/OS UNIX 'diff -e' command. These commands are used to add, replace and delete lines in the target data set. The following commands are supported:

a

c

d

s/.//
Each command may be optionally preceded by a line or line range, as allowed by the z/OS UNIX 'ed' command. If an error is detected while processing a command,status code 500 is returned with an exception.
binary: When set to binary, no data conversion is performed. The data is written to the data set without respect to record boundaries. All records will be written at their maximum record length and for fixed length record data sets, the last record will be padded with nulls if required.
record: When set to record, no data conversion is performed. Each logical record is preceded by the 4-byte big endian record length of the record that follows. This length does not include the prefix length. For example: a zero-length record would be 4 bytes of zeros with nothing following.

If you omit this header, the default is text; the request body is converted.

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.

X-IBM-Obtain-ENQ

This header is optional; set it to one of the following values to request that a system ENQ be obtained and held after the completion of this request. If not specified, then no ENQs will be held after the completion of this request.

EXCL: a SYSDSN/Exclusive ENQ will be held on the data set
SHRW: a SYSDSN/SHR ENQ will be held on the data set, and a SPFEDIT/EXCL ENQ will be held on the data set, including the member name if this is a request for a PDS member.

A successful response will include an X-IBM-Session-Ref response header that can be added as a request header to subsequent requests to specify affinity to the TSO address space holding this ENQ.

X-IBM-Session-Ref

This header is optional; include it with the value returned from a previous X-IBM-Session-Ref response header to indicate that your request should be executed in the TSO address space that was previously reserved with a X-IBM-Obtain-ENQ request header. This address space will not be used for other requests and if not used at least once every 10 minutes it will be terminated.

The following URL request may be used to "ping" the reserved address space to keep it alive:

GET https://zosmf1.yourco.com/zosmf/restfiles/ping HTTP/1.1

X-IBM-Session-Ref: xxxxxx

The X-IBM-Obtain-ENQ and X-IBM-Session-Ref headers are mutually exclusive.

X-IBM-Release-ENQ

This header is optional; it may be specified with a value ''true'' to request that the ENQ held by the associated TSO address space be released.

This header must be specified along with a valid X-IBM-Session-Ref header.

Required authorizations

See Required authorizations.

Request content

Your request must supply the data set content. For an example, see Example request.

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 204 indicates success. Start of change Status code 201 indicates success if a new PDS member was created. Status code 412 indicates that the document does not match the supplied ETag token on the If-Match header as described above. End of change 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 request

Suppose that you want to update the contents of the SMFPRM00 member of SYS1.PARMLIB using a PUT request. Figure 1 shows an example of the request header that you might use.

Figure 1. Example: Request header for a write request to the SMFPRM00 member of sys1.parmlib

PUT /zosmf/restfiles/ds/SYS1.PARMLIB(SMFPRM00)
If-Match: B5C6454F783590AA8EC15BD88E29EA63
Content-Type: text/plain; charset=UTF-8

In Figure 1, notice that the optional header If-Match is included. This header is specified with an ETag that was obtained from a previous read request on the parmlib member. Using an ETag in this manner allows for conditional processing; the new member contents are written only when the member has not been modified on the host system since the ETag was generated. If the member was modified, for example, by another user or process, this request is failed with HTTP status code 412.

A sample request body is shown in Figure 2. The body contains the new contents of the member.

Figure 2. Example: Request body for a write request to the SMFPRM00 member of sys1.parmlib

    /******************************************************/
    /* THIS PARMLIB MEMBER CONTAINS CONFIGURATION FOR SMF */
    /******************************************************/
     ACTIVE                       /*ACTIVE SMF RECORDING*/              00010000 
     DSNAME(SYS1.&SMFDSN1,SYS1.&SMFDSN2,    /*SMF ON 3390        */     00020000 
      SYS1.&SMFDSN3)                    /*FT: SYSAQ3, TS: SYSAQ4 */     00030000 
     NOPROMPT                     /*PROMPT THE OPERATOR FOR OPTIONS*/   00040000 
     REC(PERM)                    /*TYPE 17 PERM RECORDS ONLY*/         00050000 
     MAXDORM(3000)               /* WRITE AN IDLE BUFFER AFTER 30 MIN*/ 00060000 
     MEMLIMIT(256M)              /* 256M FOR 64 BIT APPS             */ 00061005 
     STATUS(003000)              /* WRITE SMF STATS AFTER HALF HOUR*/   00070000 
     JWT(0700)                   /* INVOKE EXIT IEFUTL AFTER  7HR 00M*/ 00080002 
     SID(&SYSNAME),              /* SYSTEM ID FOR 3084 - SINGLE IMAGE*/ 00090000 
     LISTDSN                     /* LIST DATA SET STATUS AT IPL*/       00100000 
     INTVAL(30)                  /* INTVAL OPTION SP430 */              00110000 
     SYNCVAL(00)                 /* SYNCVAL OPTION SP430  */            00120000 
     SYS(NOTYPE(19,40,92),                                              00130001 
      EXITS(IEFU83,IEFU84,IEFACTRT,IEFUJV,IEFUJI,                       00140000 
           IEFUSI,IEFUTL,IEFU29),INTERVAL(010000),DETAIL)               00150000 
                                                                        00160000 
     /* WRITE ALL RECORDS AS THE SYSTEM DEFAULT, TAKE ALL KNOWN         00170000 
        EXITS, NOTE: JES EXITS CONTROLED BY JES , THERE IS NO           00180000 
        DEFAULT INTERVAL RECORDS WRITTEN AND ONLY SUMMARY T32           00190000 
        RECORDS AS A DEFAULT FOR TSO */                                 00200000 
                                                                        00210000 
     SUBSYS(STC,NOTYPE(19,40,92),                                       00220001 
      EXITS(IEFU29,IEFU83,IEFU84,IEFUTL),                               00230000 
      INTERVAL(SMF,SYNC),DETAIL)           /*SP430*/                    00240000 
                                                                        00250000 
     /* WRITE ALL RECORDS AS BY  SYSTEM DEFAULT, TAKE ONLY THREE        00260000 
        EXITS, NOTE: IEFU29 EXECUTES IN THE MASTER ASID WHICH IS A      00270000 
        STC ADDRESS SPACE SO IEFU29 MUST BE ON FOR STC. USE ALL OTHER   00280000 
        SYS PARAMETERS AS A DEFAULT  */                                 00290000

Example response

For a successful request, the HTTP response contains the following:

Status code indicating that the request completed (status code 204)
ETag that you can use on subsequent requests to test for changes to the resource

204 No Content
Etag:  DE2BE8B8485EB8F1E28D3716DFFE0680
Content-Type:  application/json; charset=UTF-8
Content-Language:  en-US
Date:  Fri, 07 Nov 2014 02:31:39 GMT

Example request

The PUT method is used to write the contents of a sequential data set.

PUT /zosmf/restfiles/ds/JIAHJ.REST.SRVMP HTTP/1.1
If-Match: B5C6454F783590AA8EC15BD88E29EA42
Content-Type: text/plain; charset=UTF-8

Example response

A sample response is shown in Contents of a sequential data set.

Figure 3. Example: Contents of a sequential data set

Response:

204 No Content
X-Powered-By:  Servlet/3.0
Content-Type:  application/json; charset=UTF-8
Content-Length:  0
Etag: 39E89731CE27214AE2FE0BBD9200DC26
Content-Language:  en-US
Date:  Wed, 25 Nov 2015 03:10:12 GMT