fileload

Copy the contents of a file into a field or variable.

fileload {/text | /raw | /image | /web } FilePath, Target {, UnicodeFormat | CharSet}

Example: fileload "/textfiles/text.txt", TEXTFIELD

Qualifiers

Qualifiers
Qualifier	Description
/text	Translates the raw data from FilePath to the system character set or the UnicodeFormat. This is the default behavior.
/image	Reads the raw data from FilePath, assuming that this data is an image. An initial hash character (#) is added to the data before copying the data to Target. (The hash character is an indicator to show that image data follows.) No further conversion is performed on the data.
/raw	Reads the raw data from FilePath, except that the data in FilePath is assumed not to be an image; an initial hash character (#) is not added. No further conversion is performed on the data.
/web	When used in components running in the Web Application Server, it loads files that were uploaded via the browser. The files are in raw format.

Parameters

Parameters
Parameter	Data Type	Description
FilePath	String	Name and path of the file contents to be copied; maximum 255 bytes. The file can be located in a zip archive.
Target	String	Name of a field, a variable, or a parameter to receive the data.
UnicodeFormat	String	Unicode encoding format of the input file. Valid values are: `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, `UTF-32`, `UTF-32BE` and `UTF-32LE`. If not specified, the system character set is used.
CharSet	String	Character set; overrides the value of the system character set ($SYS_CHARSET). For a list of supported character sets, see $SYS_CHARSET.

Return Values

Values returned in $status
Value	Meaning
>=`0`	The number of bytes in Target.
`-1`	An I/O error occurred while reading FileName.
`-4`	Cannot open FileName.
`-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 fileload and lfileload
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.
`-16` through `-30`	`<UNETERR_*>`	Errors during network I/O.
`-1101`	`<UPROCERR_FIELD>`	An incorrect field name was provided; either the field name is not valid syntactically or the field is not available in the component.
`-1113`	`<UPROCERR_PARAMETER>`	Parameter name not valid or not defined.
`-1114`	`<UPROCERR_LOCAL_VARIABLE>`	Local variable name not valid or not defined.
`-1115`	`<UPROCERR_COMPONENT_VARIABLE>`	Component variable name not valid or not found.
`-1116`	`<UPROCERR_GENERAL_VARIABLE>`	General variable not valid.
`-1117`	`<UPROCERR_GLOBAL_VARIABLE>`	Global variable name not valid or not found.

Use

Allowed in all component types.

Description

The fileload statement copies the contents of FileName to Target. Unlike lfileload, it uses the locations specified in the assignment file to locate files.

Used without the /image or /raw switch, fileload converts the data to be stored from the character set specified by the assignment setting $SYS_CHARSET or with the UnicodeFormat, if specified.

To strip the end-of-line character from an otherwise empty input file, so the resulting data is truly empty, use the assignment setting $FILELOAD_SINGLE_LINE.

Unicode Byte-Order-Mark (BOM)

fileload checks for a Unicode Byte-Order-Mark (BOM), a special character to recognize the encoding. If no BOM is available, the indicated character set is used:

Character Set Used if Unicode BOM Not Available
Character Set Specified by UnicodeFormat	Character Set Used
UnicodeFormat is not specified	Character set specified by the $SYS_CHARSET assignment setting
`UTF-8`	`UTF-8`
`UTF-16` or `UTF-32`	Big-Endian character set; either `UTF-16BE` or `UTF-32BE`, according to Unicode specification

If the UnicodeFormat is specified as UTF-16BE, UTF-16LE, UTF-32BE or UTF-32LE, fileload does not check the Unicode BOM because the character set is explicitly provided.

Loading XML Files

If the first line of the source file contains an XML declaration, the encoding attribute and value are removed and the XML data is converted to UTF-8. For example, an XML file has the following:

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

The fileload statement converts the XML data from ISO-8859-1 to UTF-8, and in the target the XML declaration becomes:

<?xml version="1.0" ?>

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 Syntax of File and Directory Names.

Operation Failure

The operation fails if FilePath:

Does not exist
Does not permit user-reading due to insufficient authorization level
Has invalid syntax

Uploading Files to a Static Server Page

When you create a server page to select files to be uploaded, you use the following ProcScript syntax for fileload:

fileload/web FileName, Target

In addition, you must also modify the server page to include the attribute enctype within the FORM tag, as follows:

<FORM method="POST" action="" onSubmit="return uSubmit(this)" enctype="multipart/form-data">

The addition of enctype="multipart/form-data" instructs the browser to send not only the file name, but also the contents of the selected file.

Loading an Image File

The following example loads a bitmap for a national flag based on the current value of $language :

fileload/image "flags\%%$language%%%.bmp",FLAGFIELD

Download a File

The following example downloads a file from a web page and stores it to a file system:

fileload/web "UPLOADNAME.ENTITY.MODEL",$1
filedump/raw $1,"downloads/file1"

Loading a Unix File

trigger detail
fileload "/home/central_park/textfiles/text.txt", TEXTFIELD
message "%%$status%%% bytes of text loaded into TEXTFIELD field."
end ; trigger end

History
Version	Change
9.1.01	Added ZIP file support Added optional parameter UnicodeFormat