FSLETTER Procedure Windows

Creating and Editing Documents

Documents are entered or edited in the FSLETTER window. FSLETTER windows can be opened for editing in the following ways:

by specifying the name of a LETTER entry in the LETTER= argument of the PROC FSLETTER statement or in the FSLETTER command
by selecting an existing LETTER entry or creating a new LETTER entry in the Explorer window
by issuing an EDIT command in another FSLETTER window
by issuing an EDIT command in an FSBROWSE or FSEDIT window.

If the LETTER entry that you specify when you open the FSLETTER window is not in the current catalog, an empty FSLETTER window is opened for entering text. If the specified entry already exists, it is displayed for editing. All text in the FSLETTER window is unprotected. Using editing keys and commands, you can write new documents and edit existing documents.

The FSLETTER window uses the SAS text editor, so all the standard text editor commands are available. See the online Help for Base SAS software if you need an introduction to the features of the SAS text editor. You can customize many features of the text editor to suit your own tastes and needs. Refer to Setting Text Editor Parameters for a discussion of the features that you can control.

Choosing a Form

When you create a new document, you should choose a form to associate with it. Forms are SAS catalog entries of type FORM that contain instructions for formatting the text in your document when it is printed. In addition, the line length specified in the form determines the width of the text entry area in the FSLETTER window.

Newly created documents are assigned the default form FSLETTER.FORM. You can change the form assignment by using the FORM command in the FSLETTER window. When you change the form assignment, the procedure first looks for the new form in the current catalog (the catalog in which the current document resides). If the specified entry is not there, the procedure looks in your personal PROFILE catalog (SASUSER.PROFILE, or WORK.PROFILE if the SASUSER library is not allocated). If the specified entry is not there, the procedure looks last in the SASHELP.FSP system catalog. If the specified entry still is not found, an error message is returned, and the current form assignment is not changed.

Defining Fields

The FSLETTER procedure enables you to define fields in your documents. Fields are areas in which values can change for each copy of a document. A field appears in the text of a document as an ampersand (&) followed by a valid SAS name.

The length of each field in your document should be equal to the largest number of characters expected for that value. The field length is determined by the number of characters in the field name (including the ampersand). To extend a field, you can follow the field name with a series of underscores (_). The underscores increase the field length, but they are not part of the field name.

You can use the automatic variables &DATE and &DATE7 as fields in FSLETTER documents. These variables provide the current date when the document is printed. Because the variable names already begin with an ampersand, the field names should begin with two ampersands (&&DATE and &&DATE7). The variables provide the current date in WORDDATE. and DATE7. formats, respectively. If you use &&DATE, add underscores to extend the field to 18 characters (the maximum possible length for date values in the WORDDATE. format).

FSLETTER Document Containing Fields shows a portion of a document displayed in the FSLETTER window. This portion of the document contains six different fields; FULLNAME appears twice.

FSLETTER Document Containing Fields

[FSLETTER Document Containing Fields]

You define fields in the FSLETTER window, but you do not supply values for the fields until you print the document from the FSLETTER SEND window. See Printing Documents for details. The FSLETTER procedure can also fill the fields automatically, using values from observations in a SAS data set. See Step 1: Filling Fields for details.

Using Color and Highlighting Attributes

If your terminal or workstation supports color and highlighting, then you can change the color and highlighting of characters as you type (or overtype) them. Use the global COLOR TEXT command to change the color and highlighting attributes of the text that you enter. For example, the following command changes all the text you type after the command is issued to reverse-video magenta:

color text magenta reverse

Once you enter a COLOR TEXT command, the specified attributes are used until you change them with another COLOR command. Refer to the description of the COLOR command in the online Help for Base SAS software for additional details.

Note: Some terminals or workstations provide special keys that control text color and highlighting. If your device has such keys, you can use them to set color and highlighting attributes as you enter the text. [cautionend]

The color and highlighting attributes are stored with the document; therefore, they remain in effect the next time the document is displayed.

You can use color and highlighting in FSLETTER documents

to enhance displayed text.

You can change the default text color and highlighting attributes to change the appearance of the document in the FSLETTER and FSLETTER SEND windows. For example, you can use a different color or highlighting attribute for the fields in the document so that they stand out more clearly when the text is displayed in the FSLETTER SEND window for data entry.
to signal printing instructions.

The form that is associated with the document may interpret certain colors or highlighting (or combinations of color and highlighting) as signals to use a particular printer feature when the document is printed. For example, the form can interpret the combination of red and reverse video as a signal that text with those attributes should be underlined or italic when printed.

You can edit the FORM entry to select which attributes signal printing instructions for your documents. For details about how the color and highlighting attributes that signal printing instructions are defined in the FORM entry, see the discussion of the FORM window in the online Help for Base SAS software.

You can use the global FONT command in the FSLETTER window to check which color and highlighting attributes are defined as printing instructions for the current form.

FSLETTER Window Commands

In addition to the SAS text editor commands that are described in the online Help for Base SAS software and the global commands described in SAS/FSP Software Global Commands, you can use the following commands when editing a document in the FSLETTER window:

Managing LETTER entries

ATTR

COPY <libref.catalog-name>entry-name<.LETTER>

DES description

EDPARMS

FORM form-name

SAVE letter-name

SEND <ALL> <DATA=data-set<(data-set-options)>>

<FILE=fileref | 'actual-filename'<APPEND | REPLACE>>

Opening Additional Windows

BROWSE letter-name<.LETTER> | form-name.FORM | FSLETTER.EDPARMS

EDIT letter-name<.LETTER> | form-name.FORM | FSLETTER.EDPARMS

Closing the Window

CANCEL

END

Managing Data Sets

DATA <data-set<(data-set-options)>>

WHERE <<ALSO> expression> | <UNDO | CLEAR>

Command Descriptions

Descriptions of the FSLETTER window commands:

ATTR

opens the FSLETTER ATTR window, in which the field attributes for the current document can be viewed or modified.

Assigning an attribute to a field tells the FSLETTER procedure to take certain actions when it encounters the field in the FSLETTER SEND window. See Assigning Field Attributes for more information.

BROWSE letter-name<.LETTER> | form-name.FORM | FSLETTER.EDPARMS

opens an additional window for browsing the specified entry:

If the entry type is LETTER, or if no entry type is specified, another FSLETTER window is opened for browsing the specified document.
If the entry type is FORM, a FORM window is opened for browsing the specified form. For information on using the FORM window, see the online Help for Base SAS software.
If the entry is FSLETTER.EDPARMS, an EDPARMS window is opened for browsing the default editor parameter file. For information on using the EDPARMS window, see Setting Text Editor Parameters.

An error occurs if you specify an entry type that is not supported by the FSLETTER procedure.

The new window that is opened by the BROWSE command becomes the active window. You can use the SWAP command to move between the windows that have been opened in the current FSLETTER session. Use the END command to close the new window and return to the previous window.

CANCEL

cancels all changes that have been made to the current document since the FSLETTER window was opened (or since the last SAVE command), closes the current FSLETTER window, and returns you to the window from which the FSLETTER window was opened.

CLOSE

closes the data set that was opened with the DATA command. After the data set is closed, the FSLETTER procedure no longer uses it to fill fields during printing.

COPY <libref.catalog-name>entry-name<.LETTER>

copies the specified LETTER entry into the current document. You can use text editor line-target commands (A or B, for after or before) to copy the document at a specific position within the current text. Otherwise, the copied document is appended to the end of the current document.

If the document being copied uses a different form than the current document, the document being copied is flowed (if necessary), using the line length information in the current document's form.

DATA <data-set<(data-set-options)>>

opens the specified SAS data set for filling fields in documents.

While the data set is open, any fields in a document whose names or aliases match variable names in the specified data set are filled automatically from observations in the data set when the document is printed.

You can add a list of data set options following the data set name. The list must be enclosed in parentheses. The following data set options are valid with the DATA command:

DROP	RENAME
KEEP	WHERE

Refer to SAS Language Reference: Dictionary for descriptions of these data set options.

Use the CLOSE command to close the data set that was opened with the DATA command if you no longer want fields to be filled from the data set.

DES description

assigns a description of up to 40 characters to a document. The description does not need to be enclosed in quotes. The description is displayed with the name of the document when you select the Details view in the Explorer window.

EDIT letter-name<.LETTER> | form-name.FORM | FSLETTER.EDPARMS

opens an additional window for creating or editing the specified entry:

If the entry type is LETTER, or if no entry type is specified, an FSLETTER window is opened for editing the specified document. If the specified entry does not exist, the FSLETTER window is initially blank. The entry is not created until you enter text and save the document or close the FSLETTER window. (No entry is created when you close a blank FSLETTER window.)
If the entry type is FORM, a FORM window is opened for creating or editing the specified form. For information on using the FORM window, see the online Help for Base SAS software.
If the entry is FSLETTER.EDPARMS, an EDPARMS window is opened for creating or editing the default editor parameter file. For information on using the EDPARMS window, see Setting Text Editor Parameters.

Note: The parameter settings in the FSLETTER.EDPARMS entry do not affect the current document. The FSLETTER.EDPARMS entry determines the initial parameters for newly created documents. Use the EDPARMS command to change parameter settings for the current document.

An error occurs if you specify an entry type that the FSLETTER procedure does not support.

The new window that is opened by the EDIT command becomes the active window. You can use the SWAP command to move between the windows that have been opened in the current FSLETTER session. Use the END command to close the new window and return to the previous window.

EDPARMS

opens an EDPARMS window and displays the text editor parameter settings for the current document. Any changes that you make take effect when the EDPARMS window is closed. The parameter settings are stored in the LETTER entry and remain in effect the next time you edit this document.

See Setting Text Editor Parameters for more information on using the EDPARMS window.

Note: Changes made in the EDPARMS window that is opened by the EDPARMS command do not affect the default parameter settings in the FSLETTER.EDPARMS entry for the catalog. [cautionend]

END

saves the currently displayed document, closes the FSLETTER window, and returns you to the window from which the FSLETTER window was opened.

FORM form-name

changes the FORM entry that is assigned to a document. The form name is recorded in the LETTER entry.

When you specify a new form name, the FSLETTER procedure looks first for a FORM entry that has the specified name in the current catalog (the catalog that was opened when the procedure was initiated). If the form is not there, the procedure looks for it in your personal PROFILE catalog (SASUSER.PROFILE, or WORK.PROFILE if the SASUSER library is not allocated). If the form is not there, the procedure looks for it in the SASHELP.FSP system catalog. If the form still is not found, the procedure returns an error message, and the current form assignment is not changed.

If the new form specifies a different line width than the current form uses, a dialog box appears asking whether you want the document to be flowed to the new line width. Respond with a Y to flow the text or with an N to wrap the text. If you choose N, lines of text are split if the new line length is smaller, or blanks are added to pad the lines if the new line length is larger.

SAVE <letter-name>

stores the current version of the document in the catalog, leaving the document displayed for further editing. If you do not specify a name for the entry, the text is saved under its original name in the catalog. Specify a different name to store the current document under another name in the catalog.

It is wise to issue SAVE commands occasionally while entering text to avoid losing work due to interruptions in computing services. Any document that has been modified is automatically saved when you use the END or SEND commands.

SEND <ALL> <DATA=data-set<(data-set-options)>> <FILE=fileref | 'actual-filename' <APPEND | REPLACE>>

closes the FSLETTER window and prints the current LETTER entry. By default, the SEND command opens the FSLETTER SEND window, in which you can fill in fields and make final editing changes before the document is printed.

If a SAS data set is currently open, any fields in the document whose names or aliases match variable names in the open data set are filled automatically with values from the data set. If the data set was opened with a DATA command, the field values come from the first observation in the data set. If the data set is open because the FSLETTER window was opened by an EDIT command in an FSBROWSE or FSEDIT session, then the field values come from the observation that was displayed in the FSBROWSE or FSEDIT window when the EDIT command was issued.

If you include the ALL argument with the SEND command, a copy of the document is produced for every observation in the open data set (or for every observation that satisfies the WHERE condition, if a WHERE command has been issued). When you use the ALL option, the FSLETTER SEND window is not opened.

Note: The ALL argument is valid only when a data set is currently open. [cautionend]

You can also use the DATA= option in the SEND command to produce a copy of the document for each observation in a specified data set. The DATA= option is useful in the following circumstances:

when you want to produce copies of an individual document without using the DATA command to open a data set for the FSLETTER session.
when you want to produce copies of an individual document for a data set other than the data set that is currently open. (The DATA= option has no effect on any other data set that may currently be open.)

Because the DATA= option produces a copy of the document for each observation in the data set, it is not necessary to use the ALL option with the DATA= option. When you use the DATA= option, the FSLETTER SEND window is not opened.

You can add a list of data set options following the data set name in the DATA= argument. The list must be enclosed in parentheses. The following data set options are valid with the DATA= option:

DROP	RENAME
KEEP	WHERE

Refer to SAS Language Reference: Dictionary for descriptions of these data set options.

Unless you issue a PRTFILE command or use the PRINTFILE= option in the PROC FSLETTER (or PROC FSBROWSE or PROC FSEDIT) statement that initiates the session, output is sent to the destination that is specified in the form associated with the document. To route output to an external file instead, use the FILE= option in the SEND command. The FILE= option is useful in the following situations:

when you want to send an individual document to an external file while leaving the printer as the default output destination
when you want to send an individual document to an external file other than the currently designated print file.

To identify the external file, you can use either a fileref or its actual filename. If you use a fileref, you must have previously assigned the fileref to the external file with a FILENAME statement. If you use an actual filename, enclose it in quotes.

By default, each new document that is sent to the file replaces any text that was previously in the file. (If you use the ALL or DATA= options to produce copies of a document for observations in a SAS data set, all copies are sent to the same file.) To append the output from the current SEND command to the existing text instead of overwriting the text, add the APPEND option to the SEND command. The REPLACE option specifies the default behavior.

WHERE <<ALSO> expression> | <UNDO | CLEAR>

imposes one or more sets of conditions that observations in the data set must meet in order to fill fields in printed documents. Expression is any valid WHERE expression that includes one or more of the variables in the input data set. (Refer to the description of the WHERE statement in SAS Language Reference: Dictionary for details about the operators and operands that are valid in WHERE expressions.) No documents are created for observations that do not satisfy the specified conditions.

Note: The WHERE command is valid only when a data set is open for the FSLETTER session. [cautionend]

The complete set of conditions imposed by the WHERE command is called a temporary WHERE clause. The conditions can be modified or canceled during the FSLETTER session.

The WHERE command has the following forms:

WHERE expression: applies the conditions specified in expression as the new temporary WHERE clause, replacing any clause that was previously in effect.
WHERE ALSO expression: adds the conditions specified in expression to the existing temporary WHERE clause.
WHERE UNDO: removes the most recently added set of conditions from the temporary WHERE clause.
WHERE WHERE CLEAR: cancels the current temporary WHERE clause.

Top of Page