WRITE operator

The WRITE operator creates an action that writes a file from a property to an external resource.

Syntax

WRITE [CLIENT [DIALOG]] fileExpr TO urlExpr [APPEND]

Description

The WRITE operator creates an action that writes a file from the property to an external resource located at the specified URL.

The following URL types are supported:

[file://]path_to_file
ftp://username:password[;charset]@host:port[/path_to_file][?param1=value1&param2=value2&...]
ftps://username:password[;charset]@host:port[/path_to_file][?param1=value1&param2=value2&...]
sftp://username:password[;charset]@host:port[/path_to_file]

For ftp and ftps, the supported query parameters are passivemode, binarytransfermode, datatimeout, connecttimeout.

If the part of the URL after the last period already looks like a file extension (either a standard MIME extension, or a short — fewer than 4 characters — suffix with more letters than digits), it is used as is. Otherwise the period . is treated as part of the file name, and the extension is determined automatically based on the class of the file being written:

Extension	Class
read from the passed object	FILE
none — no extension is appended	RAWFILE
json	JSONFILE
xml	XMLFILE
csv	CSVFILE
txt	TEXTFILE
xls or xlsx, depending on the file content	EXCELFILE
dbf	DBFFILE
table	TABLEFILE
html	HTMLFILE
doc or docx, depending on the file content	WORDFILE
jpg, png or bmp, depending on the file content	IMAGEFILE
pdf	PDFFILE
mp4	VIDEOFILE

When the URL ends with an extension this rule does not recognize — patch or yaml, for example — the extension of the file is appended even if it is the same one: report.patch for a FILE with the extension patch is written as report.patch.patch. A RAWFILE has no extension, so a URL that names the file is used as is: WRITE RAWFILE(f) TO url writes the content of f under exactly url (type conversion operator). If the URL ends with /, it names a directory: the file is written into it under its name — the name of a NAMEDFILE, file for the other classes — with the extension determined as above.

The Downloads folder in the user folder is considered to be the current folder on the client side.

Parameters

• CLIENT

  Keyword. If specified, the action will be executed on the client side. By default, the action is executed on the server.

• DIALOG

  Keyword. If specified, before writing the file a dialog will be shown in which the user can change the specified URL. This can be used only when writing to the disk (the URL type is file). On the desktop client the extension of the name chosen in the dialog is replaced by the extension of the file being written, so a RAWFILE is saved there without an extension. By default, the dialog is not shown.

• urlExpr

  An expression whose value equals to the URL.

• fileExpr

  An expression whose value is the file that will be written to an external resource. JSON-typed values are also accepted: in this case the value is serialized to a .json file.

• APPEND

  Keyword. If specified, the file is re-read from fileExpr and appended to the file at urlExpr. Supported only when writing to the file system (URL type file). For ftp, ftps, and sftp, using APPEND raises a runtime error. It also cannot be combined with CLIENT DIALOG. Behavior by file extension:

  • csv, txt — data is appended to the end of the file;
  • xls, xlsx — all sheets from the fileExpr file are copied into the file at the specified urlExpr;
  • docx — the contents of the fileExpr document are appended to the document at the specified urlExpr;
  • pdf — the pages of the fileExpr document are appended to the document at the specified urlExpr;
  • not supported for other extensions.

  With CLIENT, merging into an existing xls, xlsx, docx or pdf file is done only by the desktop client.

  If the file at the specified urlExpr does not yet exist, WRITE with APPEND works for any file type: a new file with the contents of fileExpr is created.

  By default, the file is rewritten.

Examples

loadAndWrite ()  {
    INPUT f = FILE DO {
        WRITE f TO 'file:///home/user/loadedfile.csv' APPEND;
        WRITE RAWFILE(f) TO '/home/user/loadedfile.patch'; // written under exactly this name, whatever the extension of f
        WRITE CLIENT f TO '/home/user/loadedfile.txt';
        WRITE CLIENT DIALOG f TO 'loadedfile';
    }
}