+---------------------------------+
|             FWRITE              |
+---------------------------------+
FWRITE(<expN1>, <expC> [, <expN2>])

-----------------------------------
Writes character string to file or communication port.
Return value - Numeric
-----------------------------------

The FWRITE() function allows you to write to the file or communication
port whose handle is <expN1>.

The entire character string <expC> is written to the file or port unless
the optional <expN2> argument is included.  <expN2> specifies the number
of characters to write to the file or port.  If <expN2> is greater than
the number of characters in <expC>, all of <expC> is written to the file
or port.  If <expN2> is less than the number of characters in <expC>,
only <expN2> characters are written to the file or port.

FWRITE() returns the number of bytes written to the file or port.  If
unsuccessful, FWRITE() returns 0.

Clauses
-------

<expN1>
        File handle of file or port.

<expC>
        String to be written to file or port.

<expN2>
        Number of characters to write to file or port.

+---------------------------------+
|         Program Example         |
+---------------------------------+
The example below creates and opens temporary file for data entry.  If
file is created successfully, program creates input window where you can
enter first name, last name and position.  This information is then
written to temporary file. Note that unlike FWRITE(),  FPUTS() places
carriage return at end of string.  FoxPro editor then displays resulting
file.  If file cannot be successfully created using low-level file
functions, FoxPro editor creates and then displays empty file.

SET TALK OFF
CLEAR
tmpfile = SYS(3) && Create a temporary file name
handle = FCREATE(tmpfile) && Open the temporary file

IF handle < 0
        DEFINE WINDOW alert FROM 7,17 TO 12,60 DOUBLE COLOR SCHEME 7

        DO CASE && Unable to open the temporary file.
                CASE FERROR() = 4
                        reason = 'Too many files open (out of handles)'
                CASE FERROR() = 5
                        reason = 'Access denied'
                CASE FERROR() = 8
                        reason = 'Out of memory'
                CASE FERROR() = 29
                        reason = 'Disk full'
                CASE FERROR() = 31
                        reason = 'General Failure'
        ENDCASE

                ACTIVATE WINDOW alert
        @ 1,7 SAY 'Unable to open file'
        @ 2,7 SAY 'Reason: ' + reason
        @ 3,7 SAY 'Press a key to exit'
        =INKEY(0)
        DEACTIVATE WINDOW alert
        CANCEL
ELSE
        STORE SPACE(15) TO fname, lname, pos
        DEFINE WINDOW wingets FROM 10,20 TO 18,60 ;
                CLOSE FLOAT SHADOW SYSTEM ;
                COLOR SCHEME 8 TITLE ' Name Entry '
        ACTIVATE WINDOW wingets
        @ 1,5 SAY 'First Name:' GET fname
        @ 3,5 SAY 'Last Name :' GET lname
        @ 5,5 SAY 'Position  :' GET pos
        READ
        =FWRITE(handle,'First name: ')
        =FPUTS(handle,fname)
        =FWRITE(handle,'Last name: ')
        =FPUTS(handle,lname)
        =FWRITE(handle,'Position: ')
        =FPUTS(handle,pos)
        =FCLOSE(handle)  && Close the file
        DEACTIVATE WINDOW wingets
        WAIT 'Press a key to view the file' WINDOW
ENDIF

IF !WEXIST('wingets')
        DEFINE WINDOW wingets FROM 10,20 TO 18,60 ;
                CLOSE FLOAT SHADOW SYSTEM ;
                COLOR SCHEME 8 TITLE ' Name Entry '
ENDIF

MODIFY FILE (tmpfile) WINDOW wingets  && View the file just created
DELETE FILE (tmpfile)
CLEAR WINDOW

-----------------------------------

See Also:  FCHSIZE(), FCLOSE(), FCOUNT(), FCREATE(), FEOF(), FERROR(),
FFLUSH(), FGETS(), FOPEN(), FPUTS(), FREAD(), FSEEK(), FSIZE(),

-----------------------------------