filedump

Copy the contents of the source object to the specified file.

filedump {/text {/nobom} {/append} | /image | /raw | /web } Source,FileName {, UnicodeFormat | CharacterSet}

Example: filedump/append "NAME","MYFILE"

Qualifiers

Qualifiers
Qualifier	Description
/text	Translates the raw data from Source to the system character set or the UnicodeFormat. This is the default behavior.
/nobom	Omits the Unicode Byte-Order-Mark (BOM) when writing Unicode (if UnicodeFormat is specified or $SYS_CHARSET is set to `UTF8`).
/append	Appends the contents of Source to the specified FileName. If FileName does not exist, it is created. The /append switch cannot be used in conjunction with /image and /raw.
/image	Writes the raw data from Source, assuming that this data is an image. An initial hash character (#) is removed from the data before writing. (The hash character is an indicator to show that image data follows.) No further conversion is performed on the data in Source.
/raw	Writes the raw data from Source; an initial hash character (#) is not removed. No further conversion is performed on the data in Source, which is encoded as UTF-8.
/web	In components running in the Web Application Server, copies files that were downloaded via the browser. The files are in raw format.

Parameters

Parameters
Parameter	Data Type	Description
Source	String	Source object containing the contents to be copied.
FileName	String	Destination path and file name of the output file, which can include a ZIP archive. The total length of the path and file name cannot exceed 255 bytes, and the name must not end with a directory separator.
UnicodeFormat	String	Unicode encoding format of the input file. It can be a string, or a field (or indirect reference to a field), a variable, or a function that evaluates to a string. Valid values are: `UTF-8UTF-16UTF-16BEUTF-16LEUTF-32UTF-32BEUTF-32LE`. If not specified, the system character set is used.
CharSet	String	CharacterSet—character set; overrides the character set specified by $SYS_CHARSET. If the data is save to an XML file, the character set is mapped to an IANA-approved name that matches the character set. For example, if `CP1252` or `LATIN1` is specified, `ISO-8859-1` is used for character set encoding. For more information, see XML Encoding to Character Set Mappings.

Return Values

Values returned in $status
Value	Meaning
>=`0`	The number of bytes from Source written to FileName.
`-1`	An I/O error occurred while writing FileName.
`-4`	Cannot open FileName.
`-13`	An error occurred while trying to perform the OS command. Set `/pri=64` to display the exact error in the message frame.
`-16`	Network error: unknown.
`-17`	Network error: pipe broken.
`-18`	Network error: failed to start new server.
`-19`	Network error: fatal.

Values commonly returned by $procerror following filedump and lfiledump
Value	Error constant	Meaning
`-4`	`<UIOSERR_OPEN_FAILURE>`	The table or file could not be opened. The entity is not painted or the corresponding table or file does not exist in the database.
`-12`	`<UIOSERR_FILE_READ_WRITE>`	An error occurred while trying to read or write to the file.
`-13`	`<UIOSERR_OS_COMMAND>`	An error occurred while trying to perform the OS command. Set `/pri=64` to display the exact error in the message frame.
`-16` through `-30`	`<UNETERR_*>`	Errors during network I/O.

Use

Allowed in all component types.

Description

The filedump statement copies the contents of Source to FileName. Assignments are considered when locating FileName.

The file FileName is created if it does not already exist. If FileName is an existing file, its contents will be overwritten, unless you specify the /append option.

The statement fails if FileName is in use (locked), has an invalid syntax, or the user does not have authorization to write files.

If the output file or location does not contain enough space to write the entire contents of the Source, the data is truncated and -12<UIOSERR_FILE_READ_WRITE> is returned in $procerror.

Specifying the File Name

Each specification can be a string, a field (or indirect reference to a field), a variable, or a function that evaluates to a string.
The total length of any path (or file name or directory name) must not exceed 255 bytes.
Valid generic directory separators are the backward slash (\), the forward slash (/) , and the period (.) in combination with square brackets ([a.b]). These are translated to the platform-specific separators.
No wildcards are allowed in any path, except for $ldirlist and $dirlist, which allows the Uniface wildcards ? (GOLD ?) and * (GOLD *) in the directory name, for example ab?, or in its suffix, for example abc\*.txt.

For more information, see ProcScript for File System Management.

Writing Unicode

Used without the /image or /raw switch, the data is converted and stored to the UTF8 character set, or with the UnicodeFormat (if specified).

If a Unicode format is specified, either by the UnicodeFormat parameter or the $SYS_CHARSET assignment, a Unicode Byte-Order-Mark (BOM) is written. This is a special character to recognize the encoding.

However, the BOM can cause problems with some standards and applications. For example, the Unicode type for JSON data must be deduced from the first characters of the JSON text itself, rather than the BOM. In such cases, you can prevent the BOM from being written by using the /nobom qualifier.

Note: You can change the application behavior so that the BOM is never written, even if /nobom is omitted. To do so, use the $NO_BOM_UTF8 assignment setting.

If the first line of data contains an XML declaration, the encoding attribute is added (if not already present) to specify the character set to use in the XML string. The value of the XML encoding attribute is derived from the UnicodeFormat or CharacterSet specified in the statement, or otherwise from the $SYS_CHARSET.

For example:

If $SYS_CHARSET=CP1252 and no CharacterSet is specified, <?xml version="1.0"> is copied as:
```
<?xml version="1.0" encoding="ISO-8859-1"?>
```
If $SYS_CHARSET=SJIS and no CharacterSet is specified, <?xml version="1.0"> is copied as:
```
<?xml version="1.0" encoding="Shift_JIS"?>
```
If $SYS_CHARSET=CP1252 and CharacterSet is specified as "CP1252", <?xml version="1.0"> is copied as:
```
<?xml version="1.0" encoding="ISO-8859-1"?>
```
Even though CharacterSet has been explicitly set, CP1252 is not an accepted name for an XML encoding, so it has been converted to an equivalent ISO encoding.

There are some differences between the character sets and the encoding formats, especially between Windows code page 1252 and ISO-8859-1. For this reason, It is best practice to specify the encoding yourself, either by including the encoding attribute in the data, or by specifying the CharacterSet attribute.

To ensure that a Windows code page encoding is used, you must use the format windows-nnnn, wherennnn is the code page number.

Writing XML

If the first line contains XML information, for example <?xml version="1.0"?>, the encoding attribute is added (if not already present) to specify the character set in use to the XML string. For example:

<?xml version="1.0" encoding="ISO-8859-1"?>

Note: The XML encoding is derived from the UnicodeFormat or CharSet specified in the statement or otherwise from the $SYS_CHARSET. There are some differences between the character sets and the encoding formats, especially with Windows code page 1252 and ISO-8859-1. It is best practice to specify the encoding yourself.

XML Encoding to Character Set Mappings

In the following table, if $SYS_CHARSET or CharSet is set to a value in the Character Set column, filedump will use the corresponding XML encoding.

XML Encoding to Character Set Mappings
XML Encoding	Character Set	Description
`UTF-8`	`UTF8`	Unicode
`ISO-8859-1`	`CP1252` `LATIN1`	Western Europe
`ISO-8859-2`	`CP1250` `LATIN2`	Czech; Eastern Europe
`ISO-8859-5`	`CP1251` `LATIN5`	Russian; Cyrillic
`ISO-8859-6`	`CP1256` `LATIN6`	Arabic
`ISO-8859-7`	`CP1253` `LATIN7`	Greek
`ISO-8859-8`	`CP1255` `LATIN8`	Hebrew
`ISO-8859-9`	`CP1254`	Turkish; ISO-8859-9
`ISO-8859-15`	`LATIN9`	Western Europe, including Euro sign
`EUC-JP`	`EUC` `EUC_JP`	Japanese; Kanji; Hankaku
`ISO-2022-JP`	`JIS`	Japanese; Kanji; Hankaku
`GB2312`	`GB` `GB2312`	Chinese Simplified
`EUC-CN`	`EUC_CN`
`Big5`	`Big5`	Traditional Chinese
`EUC-TW`	`EUC_TW`	Traditional Chinese
`KSC_5601`	`KSC` `KSC5601`	Korean; Hangul; Hanja
`EUC-KR`	`EUC_KR`	Korean; Hangul; Hanja
`windows-1250`		Czech; Eastern Europe
`windows-1251`		Russian; Cyrillic
`windows-1252`		English and Western Europe (default)
`windows-1253`		Greek
`windows-1255`		Hebrew
`windows-1256`		Arabic

Appending Data to a File 1

After the following code has been executed, the file MYFILE contains the string "Crew, JimNAME"

NAME = "Crew, Jim"
filedump NAME, "MYFILE"
filedump/append "NAME","MYFILE"

Appending Data to a File 2

To cause data to appear on separate lines in the output file, use filedump (with append) "%%^", as follows:

filedump NAME, "MYFILE"
filedump/append "%%^", "MYFILE"
filedump/append "NAME", "MYFILE"

The result of this code is:

Crew, Jim
NAME

Saving a Downloaded File

The following example dumps a file that was downloaded via a web browser:

filedump/web UPLOADNAME.ENTITY.MODEL,"downloads/file1"

Saving Data to Unix File

In the following example, a Unix file is the destination for the data written by the filedump statement:

; trigger: Detail

filedump TEXTFIELD,"/home/jimc/textfiles/TEXT.EXT"
message "%%$status%%% bytes of TEXTFIELD copied to TEXT.EXT file."

History
Version	Change
9.1.01	Added ZIP file support Added optional parameter UnicodeFormat
9.6.04	Added /nobom switch