STRTOFILE( ) Function

Writes the contents of a character string to a file.

STRTOFILE(cExpression, cFileName [, lAdditive | nFlag])

Parameters

• cExpression
  Specifies the character string that is written to the file. cExpression can be a literal character string, an expression that evaluates to a character string, or a character type variable, array element, or field.

• cFileName
  Specifies the name of the file to which the character string is written. Include a path with the file name if the file is in a directory other than the current default directory. If the file you specify does not exist, Visual FoxPro automatically creates it.

• lAdditive (for backward compatibility)
  Specifies whether the character string is appended to the end of the file. If lAdditive is true (.T.), the character string is appended to the end of the file.

  If lAdditive is false (.F.) (the default), the file is overwritten with the character string. You are asked if you want to overwrite an existing file if SET SAFETY is set to ON. If SET SAFETY is set to OFF, the file is overwritten without warning.

• nFlag
  Beginning with Visual FoxPro 7, you can use the nFlag parameter instead of lAdditive which enables you to also chose to write UTF-8 and Unicode Byte Order Marks. The following table describes the valid nFlag values.

  nFlag	Bit	Description
  0 (default)	0000	The file is overwritten with the character string (formerly lAdditive=.f.)
  1	0001	The string is appended to the end of the file (formerly lAdditive=.t.).
  2	0010	Write Unicode Byte Order Mark (BOM) FF FE at the beginning of file. cExpression is assumed to be UNICODE, therefore no translation is performed. The file is overwritten
  4	0100	Write UTF-8 Byte Order Mark (BOM) EF BB BF at the beginning of file. cExpression is assumed to be UTF-8, therefore no translation is performed. The file is overwritten.

Return Value

Numeric; the number of bytes written to the file.

Remarks

An nFlag value of 3 or 5 is not valid. You cannot attempt to write a new Byte Order Mark if nFlag bit 1, Additive, is set.

Unlike earlier versions of Visual FoxPro, STRTOFILE( ) opens a file in Shared rather than Exclusive mode. This is useful when multiple servers attempt to simultaneously write to the same file. Because of this change, you might not need to check for STRTOFILE( ) to return 0 (failure to open a file).

See Also

Reference

FILETOSTR( ) Function
FWRITE( ) Function
SET SAFETY Command

Other Resources

Functions
Language Reference (Visual FoxPro)