4D v14.3

TEXT TO DOCUMENT

Home

 
4D v14.3
TEXT TO DOCUMENT

TEXT TO DOCUMENT 


 

TEXT TO DOCUMENT ( fileName ; text {; charSet {; breakMode}} )  
Parameter Type   Description
fileName  String in Document name or Pathname to document
text  Text in Text to store in the document
charSet  Text, Longint in Name or Number of character set
breakMode  Longint in Processing mode for line breaks

The TEXT TO DOCUMENT command lets you write the text directly to a disk file.

In fileName, pass the name or pathname of the file to be written. If this file does not exist, it is created. When this file already exists on the disk, its prior contents are erased, except if it is already open, in which case, its contents are locked and an error is generated. In fileName, you can pass:

  • just the file name, for example "myFile.txt": in this case, the file is placed next to the structure file of the application.
  • a pathname relative to the structure file of the application, for example "\\docs\\myFile.txt" under Windows or ":docs:myFile.txt" under OS X.
  • an absolute pathname, for example "c:\\app\\docs\\myFile.txt" under Windows or "MacHD:docs:myFile.txt" under OS X..

If you want the user to be able to indicate the name or location of the document, use the Open document or Create document commands, as well as the Document system variable.

Note: By default, documents generated by this command do not have an extension. You must pass an extension in fileName. You can also use the SET DOCUMENT TYPE command.

In text, pass the text to write to the disk. It can be a literal constant ("my text"), or a 4D text field or variable. 

In charSet, you pass the character set to be used to write the document. You can pass a string containing the standard set name (for example “ISO-8859-1” or “UTF-8”) or its MIBEnum ID (longint). For more information about the list of character sets supported by 4D, refer to the description of the CONVERT FROM TEXT command. If a Byte Order Mark (BOM) exists for the character set, 4D inserts it into the document. If you do not specify a character set, by default 4D uses the "UTF_8" character set and a BOM. 

In breakMode, you can pass a longint indicating the processing to apply to end-of-line characters before saving them in the file. You can pass one of the following constants, found in the "System Documents" theme:

Constant Type Value Comment
Document unchanged Longint 0 No processing
Document with CR Longint 3 Line breaks are converted to OS X format: CR (carriage return)
Document with CRLF Longint 2 Line breaks are converted to Windows format: CRLF (carriage return + line feed)
Document with LF Longint 4 Line breaks are converted to Unix format: LF (line feed)
Document with native format Longint 1 (Default) Line breaks are converted to the native format of the operating system: CR (carriage return) under OS X, CRLF (carriage return + line feed) under Windows

By default, when you omit the breakMode parameter, line breaks are processed in native mode (1).

Note: This command does not modify the OK variable. In case of failure, an error is generated that you can intercept using a method installed by the ON ERR CALL command.

Here are some typical examples of using this command:

 TEXT TO DOCUMENT("myTest.txt";"This is a test")
 TEXT TO DOCUMENT("myTest.xml";"This is a test")

Example allowing the user to indicate the location of the file to create:

 $MyTextVar:="This is a test"
 ON ERR CALL("IO ERROR HANDLER")
 $vhDocRef :=Create document("")
  // Store document with the ".txt" extension
  // In this case, the .txt extension is always added to the name; it is not possible to change it
 If(OK=1) // If document has been created successfully
    CLOSE DOCUMENT($vhDocRef//Closes the document
    TEXT TO DOCUMENT(Document;$MyTextVar )
  // We write the document
 Else
  // Error management
 End if

 
PROPERTIES 

Product: 4D
Theme: System Documents
Number: 1237

 
HISTORY 

New
Created: 4D v14

 
SEE ALSO 

Document to text
System Documents

 
ARTICLE USAGE

4D Language Reference ( 4D v14 R3)
4D Language Reference ( 4D v14 R2)
4D Language Reference ( 4D v14.3)
4D Language Reference ( 4D v14 R4)