SET TEXTMERGE Command

  • Article

Enables or disables the evaluation of fields, variables, array elements, functions, or expressions that are surrounded by text-merge delimiters, and lets you specify text-merge output.

SET TEXTMERGE [ON | OFF] [TO [FileName] MEMVAR VarName [ADDITIVE]]
   [WINDOW WindowName] [SHOW | NOSHOW]

Parameters

  • ON
    Specifies that any fields, variables, array elements, functions, or expressions surrounded by the text-merge delimiters be evaluated and output when placed after \ or \\, or between TEXT and ENDTEXT.

    The following short program example demonstrates how the contents of the variable gcTodayDate and the DATE( ) and TIME( ) functions are evaluated when SET TEXTMERGE is set to ON. The variable gcTodayDate, DATE( ), and TIME( ) are evaluated because they are enclosed by the text-merge delimiters and SET TEXTMERGE is set to ON.

    CLEAR
SET TALK OFF
STORE 'Today is: ' TO gcTodayDate
SET TEXTMERGE ON
\<<gcTodayDate>>
\\<<DATE( )>>
\The time is:
\\ <<TIME( )>>

    Here is the output from the program above when run on January 1:

    Today is: 01/01/98
The time is: 10:55:19

  • OFF
    (Default) Specifies that any fields, variables, array elements, functions, or expressions be literally output along with the text-merge delimiters surrounding them. Note the difference in output when SET TEXTMERGE is set to OFF in the previous example:

    CLEAR
SET TALK OFF
STORE 'Today is: ' TO gcTodayDate
SET TEXTMERGE OFF
\<<gcTodayDate>>
\\<<DATE( )>>
\The time is:
\\ <<TIME( )>>

    Here is the output from this program:

    <<gcTodayDate>><<DATE( )>>
The time is: <<TIME( )>>

  • TO [FileName]
    Specifies that output from \, \\, and TEXT ... ENDTEXT be directed to a text file in addition to the main Visual FoxPro window, which is the default. You can also direct the output to a text file by including FileName. If a file with that name doesn't exist, a new file is created. If a file with the same name already exists and SET SAFETY is set to ON, you are given the option of overwriting the existing file.

    The text file is opened as a low-level file, and its file handle is stored to the _TEXT system variable. You can close the file by issuing SET TEXTMERGE TO without additional arguments. If the file handle of another file was previously stored in _TEXT, that file is closed.

  • MEMVAR VarName
    Specifies a variable to contain data from TEXTMERGE output.

    Because SET TEXTMERGE is a global setting and can span several procedures or methods, it is possible for MEMVAR VarName to lose scope. The command will function even when the variable is out of scope, but will return no content. You can control scooping of MEMVAR VarName by declaring the variable PUBLIC or PRIVATE.

    This clause can also create recursive behavior, which you can control with the SET TEXTMERGE TO command, as in the following example:

    USE LABELS
STORE "" to myVar, myVar2

SET TEXT ON NOSHOW
SET TEXTMERGE TO MEMVAR myVar && TEXTMERGE begins on the next line.

\Hey Now
\<<date()>>

SCAN
   \  <<name>>
ENDSCAN

* Remove comments from SET TEXTMERGE TO line to eliminate recursive 
* error with myVar and myVar2.
* SET TEXTMERGE TO

TEXT TO myVar2
<b> Here's some HTML. </b>
This is HTML
   <<date()>>
ENDTEXT

SET TEXTMERGE OFF
USE

CLEAR
? myVar  && But has also stored the TEXTMERGE contents to variables
? myVar2

  • ADDITIVE
    Specifies that output from \, \\, and TEXT ... ENDTEXT be appended to an existing file or memory variable.

    For more information on directing text-merge output to a file, see _TEXT.

  • WINDOW WindowName
    Specifies that output from \, \\, and TEXT ... ENDTEXT be directed to a user-defined window rather than the main Visual FoxPro window, which is the default. WindowName specifies the name of the window to which you want to direct output. The window must be created with DEFINE WINDOW before output can be sent to it. The window doesn't have to be active or visible.

  • SHOW | NOSHOW
    (Default) SHOW displays text-merge output.

    NOSHOW suppresses display of text-merge output.

    By default, output generated by \, \\, and TEXT ... ENDTEXT is sent to the main Visual FoxPro window or an active user-defined window.

Remarks

The \, \\, and TEXT ... ENDTEXT commands are used to merge text with the contents of tables, variables, array elements, and the results of functions and expressions. If a field, variable, array element, function, or expression is surrounded by text-merge delimiters (by default, << and >>), it can be evaluated and merged with text. This text-merge capability lets you produce letters, programs, and templates that create programs.

SET TEXTMERGE determines how fields, variables, array elements, functions, or expressions surrounded by text-merge delimiters are evaluated. It also lets you direct text-merge output to the main Visual FoxPro window, a user-defined window, or a file.

Memo fields can be used to nest merged text. If a memo field contains field names, variables, array elements, functions, or expressions surrounded by the current text-merge delimiters, these are evaluated and output with the contents of the memo field. The memo field name must also be enclosed in text-merge delimiters.

See Also

\ | \\ | _PRETEXT | SET TEXTMERGE DELIMITERS | TEXTMERGE( ) Function | _TEXT | TEXT ... ENDTEXT