FileWrite
PowerScript function
Description
Writes data to the file associated with the specified file number.
The file number was assigned to the file with the FileOpen function.
FileWrite is maintained for backward compatibility. Use the FileWriteEx
function for new development.
Syntax
|
1 |
FileWrite ( file#, variable ) |
|
Argument |
Description |
|---|---|
|
file# |
The integer assigned to the file when the file was |
|
variable |
A string or blob whose value is the data you want to write |
Return value
Integer.
Returns the number of bytes written if it succeeds and it returns -1
if an error occurs. If any argument’s value is null, FileWrite returns
null.
Usage
FileWrite can write to files with ANSI, UTF-8, UTF-16LE, and
UTF-16BE encoding.
FileWrite writes its data at the position identified by the file
pointer. If the file was opened with the writemode argument set to
Replace!, the file pointer is initially at the beginning of the file.
After each call to FileWrite, the pointer is immediately after the last
write. If the file was opened with the writemode argument set to Append!,
the file pointer is initially at the end of the file and moves to the end
of the file after each write.
FileWrite sets the file pointer following the last character
written. If the file was opened in line mode, FileWrite writes a carriage
return (CR) and linefeed (LF) after the last character in variable and
places the file pointer after the CR and LF.
If the data is in a string and the associated file uses ANSI or
UTF-8 encoding, FileWrite converts the string to ANSI or UTF-8 encoding
before saving it to the associated file.
The behavior of the FileWrite function when the file is opened with
the EncodingANSI! parameter or with no encoding parameter is platform
dependent. On the Windows and Solaris platforms, FileWrite does not
convert multilanguage characters to UTF-8 and saves the file with ANSI
encoding. On the Linux platform, if the string contains multilanguage
characters, FileWrite converts the multi-language characters to UTF-8 and
saves the file with UTF-8 encoding.
If the file is opened in stream mode, no conversion is done. If the
file was opened in text mode, FileWrite returns -1. Use FileWriteEx to
write to files in text mode.
For Unicode files and files that you convert to Unicode, you must
make sure that the file length value is an even number. Otherwise
FileWrite cannot parse the entire file.
Length limit
FileWrite can write only 32,766 bytes at a time, which includes
the string terminator character. If the length of variable exceeds
32,765 bytes, FileWrite writes the first 32,765 bytes and returns
32,765. Use FileWriteEx to handle variables that have more than 32,765
bytes.
Examples
This script excerpt opens EMP_DATA.TXT and writes the string New
Employees at the end of the file. The variable li_FileNum stores the
number of the opened file:
|
1 2 3 4 |
integer li_FileNum li_FileNum = FileOpen("C:HREMP_DATA.TXT", & LineMode!, Write!, LockWrite!, Append!) FileWrite(li_FileNum, "New Employees") |
The following example reads a blob from the database and writes it
to a file. The SQL SELECT statement assigns the picture data to the blob
Emp_Id_Pic. Then FileOpen opens a file for writing in stream mode and
FileWrite writes the blob to the file. You could use the Len function to
test whether the blob was too big for a single FileWrite call:
|
1 2 3 4 5 6 7 8 9 |
integer li_FileNum blob emp_id_pic SELECTBLOB salary_hist INTO : emp_id_pic FROM Employee WHERE Employee.Emp_Num = 100 USING Emp_tran; li_FileNum = FileOpen( & "C:EMPLOYEEEMP_PICS.BMP", & StreamMode!, Write!, Shared!, Replace!) FileWrite(li_FileNum, emp_id_pic) |
See also