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.
FileWrite ( file#, variable )
Argument |
Description |
|---|---|
file# |
The integer assigned to the file when the file was opened |
variable |
A string or blob whose value is the data you want to write to the file |
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.
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.
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:
integer li_FileNum
li_FileNum = FileOpen("C:\HR\EMP_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:
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:\EMPLOYEE\EMP_PICS.BMP", & StreamMode!, Write!, Shared!, Replace!) FileWrite(li_FileNum, emp_id_pic)
