IFS_WRITE, IFS_WRITE_BINARY, and IFS_WRITE_UTF8 procedures

The IFS_WRITE, IFS_WRITE_BINARY, and IFS_WRITE_UTF8 procedures write data to an integrated file system stream file. The data can be written as character, binary, or UTF-8 data. Data can be either replaced or appended for an existing file, or a new file can be created.

Up to 2 gigabytes of data can be written by one call to this procedure. It can contain embedded end of line characters, or the procedure can append end of line characters to the input data.

Authorization: The caller must have:

For objects not in the QSYS.LIB file system when the stream file exists and is not being replaced:
- Execute (*X) data authority to each directory preceding the stream file being written and
- Write (*W) data authority to the stream file
For objects not in the QSYS.LIB file system when the stream file does not exist or is being replaced:
- Execute (*X) data authority to each directory preceding the stream file being written and
- Write and Execute (*WX) authority to the parent directory of the stream file
For objects in the QSYS.LIB file system when the object exists and is not being replaced:
- Execute (*X) data authority to each directory preceding the object being written and
  - For a *SAVF object, Read, Write, and Execute (*RWX) data authority to the object
  - For all other object types, Write (*W) data authority to the object
For objects in the QSYS.LIB file system when the object does not exist or is being replaced:
- Execute (*X) data authority to each directory preceding the object being written and
  - For a *SAVF object, Read and Execute and Add (*RX and *ADD) data authority to the parent directory of the object
  - For a physical file member, Add (*ADD) data authority to the parent directory of the object
  - For all other object types, *OBJMGT or *OBJALTER authority to the parent directory of the object

The schema is QSYS2.

path-name

A character or graphic string that defines the path name for the file to be written. If an absolute path name is not specified, the current working directory is used in combination with the relative path name to resolve to the object.

If path-name identifies an existing object, the object must be a stream file. Otherwise, a stream file will be created.

When a stream file is created, the default authority for the parent directory is used.

line

A character or graphic string containing the data to be written to the stream file at path-name. It can be up to 2 gigabytes long.

For IFS_WRITE, line is a character string in the job CCSID. If the stream file is not in the job CCSID, line will be converted to the stream file's CCSID as it is written.
For IFS_WRITE_BINARY, line is a binary string. The data will not be converted when writing to the stream file.
For IFS_WRITE_UTF8, line is a UTF-8 string. If the stream file is not UTF-8, line will be converted to the stream file's CCSID as it is written.

file-ccsid

An integer value that specifies the CCSID to be used when creating a new stream file. This parameter is ignored when appending to an existing file.

If this parameter is not specified, the default is 1208 for IFS_WRITE_UTF8 and 0 for IFS_WRITE and IFS_WRITE_BINARY.

When file-ccsid is 0, the job CCSID is used when creating a new stream file.

overwrite

A character or graphic string that specifies whether the write operation appends to the stream file, replaces the stream file, or fails when a stream file with the specified name already exists.

APPEND: The data in line is added to the end of the existing stream file. If the stream file does not exist, it is created. This is the default.
NONE: The write operation fails if the stream file exists.
REPLACE: The data in line replaces the existing stream file if it exists. An existing stream file is deleted and a new stream file is created. The CCSID of the stream file might change. If the stream file does not exist, it is created.

end-of-line

A character or graphic string that specifies the end of line characters to write to the stream file after line is written. When using IFS_WRITE_BINARY, end of line characters are never appended, so this parameter must have a value of NONE.

The carriage-return character is always X'0D'. Based on the CCSID of the stream file being written, the line feed character is X'25' for an EBCDIC CCSID and X'0A' for ASCII and UTF-8 CCSIDs.

CR: A carriage return is appended.
CRLF: A carriage return and line feed are appended. This is the default for IFS_WRITE and IFS_WRITE_UTF8.
LF: A line feed is appended.
LFCR: A line feed and carriage return are appended.
NONE: No end of line characters are appended. This is the default for IFS_WRITE_BINARY.

Examples

Create a stream file which contains a list of all of the libraries on the system, one per line. The file is created in job CCSID.

BEGIN
  -- Make sure output file is empty to start
  CALL QSYS2.IFS_WRITE(PATH_NAME =>'/tmp/library_names', 
                       LINE => '', 
                       OVERWRITE => 'REPLACE', 
                       END_OF_LINE => 'NONE');

  -- Add lines to the output file
  FOR SELECT OBJNAME AS LIBNAME FROM TABLE(QSYS2.OBJECT_STATISTICS('*ALLSIMPLE', 'LIB')) DO
    CALL QSYS2.IFS_WRITE(PATH_NAME => '/tmp/library_names', 
                         LINE => LIBNAME);
  END FOR;
END;

The QSYS2.IFS_READ table function can be used to read the contents of the generated stream file.

SELECT * FROM TABLE(QSYS2.IFS_READ('/tmp/library_names'));

Create a UTF-8 (CCSID 1208) stream file which contains a UTF-8 Byte Order Mark (BOM) and the string 'Hello'.

CALL QSYS2.IFS_WRITE_BINARY(PATH_NAME => '/usr/utf8file',
                            LINE => BLOB(X'EFBBBF48656C6C6F'),
                            FILE_CCSID => 1208,
                            OVERWRITE => 'REPLACE'
                            );