FileWriteEx 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.
Syntax
|
1 |
<span>FileWriteEx</span> ( <span>file#</span>, <span>blob</span> {, <span>length</span> }) |
|
1 |
<span>FileWriteEx</span> ( <span>file#</span>, <span>string</span> ) |
|
Argument |
Description |
|---|---|
|
file# |
The integer assigned to the file when |
|
blob or string |
A blob or string whose value is the data |
|
length |
In text or stream mode, the number of |
Return Values
Long. Returns the number of bytes written
if it succeeds and -1 if an error occurs. FileWriteEx returns
-1 if you attempt to write to a string in stream mode or to a blob
in line mode. If any argument’s value is null, FileWriteEx returns null.
FileWriteEx returns long
Unlike the FileWrite function that it replaces,
the FileWriteEx function returns a long value.
Usage
FileWriteEx can write to files with ANSI,
UTF-8, UTF-16LE, and UTF-16BE encoding.
FileWriteEx 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 FileWriteEx,
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.
FileWriteEx sets the file pointer following
the last character written. If the file was opened in line mode, FileWriteEx 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 file was opened in stream or text mode, FileWriteEx writes
the full contents of the string or blob or the next length bytes,
whichever is shorter. The optional length parameter
applies only to blob data. If the length parameter
is provided when the datatype of the second parameter is string,
the code will not compile.
If the data is in a string and the associated file uses ANSI
or UTF-8 encoding, FileWriteEx converts the string
to ANSI or UTF-8 encoding before saving it to the associated file.
If the file is opened in stream mode, no conversion is done. For
Unicode files and files that you convert to Unicode, you must make
sure that the file length value is an even number. Otherwise FileWriteEx cannot
parse the entire file.
If the file does not have a byte-order mark (BOM) it is created
automatically.
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 |
TextMode!, Write!, LockWrite!, Append!) |
|
1 |
<span>FileWriteEx</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 FileWriteEx 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("C:EMPLOYEEEMP_PICS.BMP", &<br>   StreamMode!, Write!, Shared!, Replace!)<br><span>FileWriteEx</span>(li_FileNum, emp_id_pic) |