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. If the file already exists, it can be overwritten. If the file does not exist, it can be created.

Request body

The data to write to the target UNIX file. 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:

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

Start of change A value "text;fileEncoding=<codepage>" can be used to select an alternate EBCDIC code page. The default code page is IBM-1047. End of change

Start of change A value text;crlf=true can be used to control whether each input text line is terminated with a carriage return line feed (CRLF), rather than a line feed (LF), which is the default. End of change

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/.//
opt : g|<n>, g means global
n means search and replace <n> times

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.

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. End of change

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
The service described in Authenticate with a secondary z/OSMF instance was issued in a previous request.

X-IBM-Target-System-Password

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. End of change

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 if an existing file was updated. Status code 201 indicates a success if a new file was created. 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