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 |
<span>FileWrite</span> ( <span>file#</span>, <span>variable</span> ) |
|
Argument |
Description |
|---|---|
|
file# |
The integer assigned to the file when |
|
variable |
A string or blob whose value is the data |
Return Values
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 |
integer li_FileNum |
|
1 |
li_FileNum = FileOpen("C:HREMP_DATA.TXT", & |
|
1 |
   LineMode!, Write!, LockWrite!, Append!) |
|
1 |
<span>FileWrite</span>(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 |
integer li_FileNum<br>blob emp_id_pic<br>SELECTBLOB salary_hist INTO <span>:</span> emp_id_pic<br>   FROM Employee WHERE Employee.Emp_Num = 100<br>   USING Emp_tran;<br>li_FileNum = FileOpen( &<br>   "C:EMPLOYEEEMP_PICS.BMP", &<br>   StreamMode!, Write!, Shared!, Replace!)<br><span>FileWrite</span>(li_FileNum, emp_id_pic) |