Sends lines of text specified by TextLines to the current output device or memory variable. Visual FoxPro sends lines of text to the current output device until it encounters an ENDTEXT statement or until the program ends.

The current output device can include the main Visual FoxPro window, a user-defined window, a printer, a text file, or a low-level file.

TEXT [TO VarName [ADDITIVE] [TEXTMERGE] [NOSHOW] [FLAGS nValue] [PRETEXT eExpression]]
      TextLines
ENDTEXT

Parameters

TextLines

Specifies text to send to the current output device. TextLines can consist of text, memory variables, array elements, expressions, functions, or any combination of these.

Note
Visual FoxPro evaluates expressions, functions, memory variables, and array elements specified with TextLines only if you set SET TEXTMERGE to ON and enclose them with the delimiters specified by SET TEXTMERGE DELIMITERS. If SET TEXTMERGE is OFF, Visual FoxPro outputs expressions, functions, memory variables, and array elements as string literals along with their delimiters.

For example, Visual FoxPro evaluates and outputs the current date when you specify the DATE( ) function as TextLines only if SET TEXTMERGE is ON, and TextLines contains the function and the appropriate delimiters, such as <<DATE( )>>. If SET TEXTMERGE is OFF, Visual FoxPro outputs <<DATE( )>> as a string literal.

If you place comments within TEXT...ENDTEXT or after the single backslash character (\) or double backslash characters (\\), Visual FoxPro outputs the comments.

TO VarName

Specifies the memory variable name to use for passing the contents of the TEXT...ENDTEXT. This variable can already exist.

If the variable has not yet been declared, Visual FoxPro automatically creates it as a private variable. The TO clause operates regardless of how SET TEXTMERGE is set. If SET TEXTMERGE is set to a file, and the TO statement is included, Visual FoxPro outputs both the file and variable.

ADDITIVE

Determines whether the contents of the TO variable are overwritten or added to existing contents.

Note
If the contents of TO  VarName is not a string, Visual FoxPro always overwrites the contents in VarName.

TEXTMERGE

Enables evaluation of contents surrounded by delimiters without setting SET TEXTMERGE to ON.

NOSHOW

Disables display of the text merge to the screen.

FLAGS nValue

Specifies a numerical value that determines if output is suppressed to an output file, or if blank lines preceding any text are included in the output.

Value (additive)	Description
1	Suppresses output to the file specified with the _TEXT System Variable.
2	When the NOSHOW clause is included, preserves blank lines preceding text that appears within TEXT...ENDTEXT. Setting nValue to 2 will separate current TEXT...ENDTEXT output from previous TEXT...ENDTEXT output with a line feed. Note Combining an nValue setting of 2 and PRETEXT of 4 will separate current TEXT…ENDTEXT output from previous TEXT…ENDTEXT output with a line feed while removing empty lines in the TEXT...ENDTEXT output.

PRETEXT eExpression

Specifies a character string to insert before each line of the text merge contents between TEXT...ENDTEXT or a numeric expression.

The following table describes behaviors of the PRETEXT clause depending on the expression specified by eExpression.

eExpression	PRETEXT behavior
Character expression	Insert the expression before each line of the text merge contents appearing between the TEXT...ENDTEXT statement. When using PRETEXT with TEXT...ENDTEXT, eExpression is limited to a maximum length of 255 characters. eExpression overrides the contents of the _PRETEXT system variable. When eExpression contains an expression that needs to be evaluated, for example, a user-defined function (UDF), Visual FoxPro evaluates it only once when the TEXT command first appears.
Numeric expression	Specify additive flag values to determine behavior for the text merge contents appearing between the TEXT...ENDTEXT statement. For example, a value of 7 specifies that Visual FoxPro eliminate all white space including spaces, tabs, and carriage returns. A value falling outside of the range of 0-15 produces an error. Note Specifying a value of zero does not eliminate white space. When eExpression is a numeric expression, you can use the _PRETEXT system variable to insert additional text after Visual FoxPro eliminates white space.

The following table lists numeric additive flags that you can use in eExpression to specify additional behavior.

Value (Additive)	Description
1	Eliminate spaces before each line.
2	Eliminate tabs before each line.
4	Eliminate carriage returns, for example, blank lines, before each line.
8	Eliminate line feeds.

Note
Unlike the _PRETEXT system variable, the PRETEXT clause does not have global scope and applies only to the TEXT...ENDTEXT statement in which it appears.

Characters removed using the PRETEXT clause apply only to text within the TEXT...ENDTEXT statement and not to evaluated text merged from cExpression. In the following example, the spaces in the memory variable, myvar, are not removed when merged with the text in TEXT...ENDTEXT:

myvar = "   AAA"
TEXT TO x NOSHOW ADDITIVE TEXTMERGE PRETEXT 7
Start Line
<<myvar>>
      BBB
   CCC
ENDTEXT

 Remarks

By default, TEXT ... ENDTEXT sends output to the main Visual FoxPro window or the active window. To suppress output to the main Visual FoxPro window or the active window, issue SET CONSOLE OFF. To send output to a printer or a text file, use SET PRINTER. To send output from TEXT ... ENDTEXT to a low-level file that you created or opened using FCREATE( ) or FOPEN( ), store the file handle returned by FCREATE( ) or FOPEN( ) to the _TEXT system variable, which you can use to direct output to the corresponding low-level file.

Note
The text merge process usually includes any white space that might appear before each line in a TEXT...ENDTEXT statement. However, the inclusion of white space might cause the text merge to fail, for example, when XML is used in a Web browser. You must remove such white space to avoid incorrectly formatted XML.

Nesting TEXT...ENDTEXT statements is not recommended, especially if using the PRETEXT clause because the nested statements can affect the format of the outer statements.

 Example

Example 1

The following example demonstrates creating a low-level file called myNamesFile.txt and storing its file handle in the _TEXT system variable. The program exits if the myNamesFile.txt file cannot be created.

Visual FoxPro opens the customer table and outputs the names of the first ten contacts to myNamesFile.txt. Visual FoxPro outputs the text and results of the functions to the text file. The example uses MODIFY FILE to open myNamesFile.txt.

CLEAR
CLOSE DATABASES
SET TALK OFF
SET TEXTMERGE ON     
STORE FCREATE('myNamesFile.txt') TO _TEXT     
IF _TEXT = -1  
   WAIT WINDOW 'Cannot create an output file. Press a key to exit.'
   CANCEL
ENDIF

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  

TEXT
         CONTACT NAMES
   <<DATE( )>>    <<TIME( )>>
ENDTEXT
WAIT WINDOW 'Press a key to generate the first ten names.'
SCAN NEXT 10
   TEXT
      <<contact>>
   ENDTEXT
ENDSCAN
CLOSE ALL  
MODIFY FILE myNamesFile.txt
ERASE myNamesFile.txt

Example 2

The following example shows a custom procedure that uses TEXT...ENDTEXT to store an XML DataSet to a variable. In the example, all spaces, tabs, and carriage returns are eliminated.

PROCEDURE myProcedure
   DO CASE
   CASE nValue = 1
      TEXT TO myVar NOSHOW TEXT PRETEXT 7
         <?xml version="1.0" encoding="utf-8"?>
         <DataSet xmlns="http://tempuri.org">
         <<ALLTRIM(STRCONV(leRetVal.item(0).xml,9))>>
         </DataSet>
      ENDTEXT
   OTHERWISE
   ENDCASE
ENDPROC

 See Also

Reference

FOPEN( ) Function
_PRETEXT System Variable
SET TEXTMERGE Command
SET TEXTMERGE DELIMITERS Command
_TEXT System Variable

Other Resources

Commands (Visual FoxPro)
Language Reference (Visual FoxPro)