Write data to a z/OS UNIX file

You can use this operation to write data to an existing z/OS® UNIX System Services file.

HTTP method and URI path

PUT /zosmf/restfiles/fs/<filepath-name>

where:

/zosmf/restfiles specifies the z/OS data set and file REST interface
/fs indicates a UNIX file request
<filepath-name> identifies the UNIX file to which to write. This parameter is required and must consist of a fully qualified path and file name.

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 UNIX file. If the file has not changed since the ETag was generated, the request is processed. Otherwise, if the file 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 file is changed.

Custom headers

You can include 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 data to be written, as follows: Start of change

text: When set to text, data conversion is performed. The data transfer process converts each byte from the charset specified on the "Content-Type" header of the request. If no charset is specified, the default is ISO8859-1. Line Feed characters are left intact. This is the default value
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 conversion is performed.

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

Query parameters

None.

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 204 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 request

In the following example, the PUT method is used to replace the UNIX file /etc/inetd.conf.

PUT /zosmf/restfiles/fs/etc/inetd.conf HTTP/1.1
If-Match: F4A5A479E78AFD4CFF7DF13937AB82AE
Content-Type: text/plain; charset=UTF-8

A sample request body is shown in Figure 1.

Figure 1. Example: Request body for a PUT request to the UNIX file /etc/inetd.conf


###                                                                           
# Internet server configuration database                                      
#                                                                             
# (C) COPYRIGHT International Business Machines Corp. 1985, 2001              
# All Rights Reserved                                                         
# Licensed Materials - Property of IBM                                        
#                                                                             
# US Government Users Restricted Rights - Use, duplication or                 
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.           
#                                                                             
# /etc/inetd.conf                                                             
#                                                                             
#          Internet server configuration database                             
#                                                                             
#  $01=PYQ0049,  HOT7705, 010130, PDJP: Correct paths and remove              
#        unsupported services (FIN APAR OW45915                               
#                                                                             
# Services can be added and deleted by deleting or inserting a                
# comment character (ie. #) at the beginning of a line                        
#                                                                             
#======================================================================       
# service | socket | protocol | wait/ | user | server  | server program       
# name    | type   |          | nowait|      | program |   arguments          
#======================================================================       
#                                                                             
# Following line uncommented by USSSETUP job: 2013/04/24 15:04:00             
otelnet   stream tcp nowait IBMUSER  /usr/sbin/otelnetd otelnetd -l           
# Following line uncommented by USSSETUP job: 2013/04/24 15:04:00             
shell     stream tcp nowait IBMUSER  /usr/sbin/orshd orshd -LV                
# Following line updated by USSSETUP job: 2013/04/24 15:04:00                 
login     stream tcp nowait IBMUSER  /usr/sbin/rlogind rlogind -m             
# Following line added by USSSETUP job: 2013/04/24 15:04:00                   
ssh       stream tcp nowait IBMUSER  /usr/sbin/sshd sshd -i                   
#exec     stream tcp nowait OMVSKERN /usr/sbin/orexecd orexecd -LV            
# All users should use this configuration file

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 UNIX file

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