SAS Component Language Dictionary

PREVIEW

Manipulates an application's preview buffer

Category:

Submit Block

Syntax
Actions for the PREVIEW Function
Details
Example
See Also

Syntax

rc=PREVIEW(action<,argument-1<,argument-2<,argument-3>>>);

rc

contains the return code for the operation:

0	The operation was successful.
-1	For actions that open the PREVIEW window, the CANCEL command was used to exit the PREVIEW window. For other actions, the requested operation was not performed successfully.

Type: Numeric

action

is an action from Actions for the PREVIEW Function.

Type: Character

argument

specifies up to three arguments for the specified action from Actions for the PREVIEW Function.

Type: Character

Actions for the PREVIEW Function

'BROWSE'

opens the PREVIEW window for browsing only. You can optionally specify a window title as argument-1.

'CLEAR'

clears the preview buffer. Any statements that were generated previously by SUBMIT statements or that were included by COPY or INCLUDE actions are lost. No optional arguments are used with this action.

'CLOSE'

closes the PREVIEW window. No optional arguments are used with this action.

'COPY'

copies a catalog entry of type SOURCE, OUTPUT, LOG, or SCL into the preview buffer. You must specify the name of the entry to be copied as argument-1. For the syntax for argument-1, see the description of the SAVE action.

Note: If you copy an SCL entry to the PREVIEW window, you should CLEAR the window before closing it. Otherwise, the SCL code that was copied will be submitted to SAS. [cautionend]

'DISPLAY|EDIT'

opens the PREVIEW window to display the contents of the preview buffer for editing. All standard text editor commands are valid in this window. Control stays with the PREVIEW window until the PREVIEW window is exited. Issue the END command to exit the window and return to the SAS/AF program. Changes that a user makes to the statements in the window are not reversed by issuing a CANCEL command. However, the SCL program can check for the return code of -1 from the PREVIEW function, indicating that a CANCEL command was issued in the PREVIEW window, and can then specify not to save the contents of the PREVIEW window.

You can optionally specify a window title as argument-1.

'FILE'

saves the current contents of the PREVIEW window to an external file. With this action, you must specify the fileref for the external file as argument-1. You must specify a fileref; physical filenames are not allowed.

You can specify APPEND for argument-2 to append the contents of the preview buffer to the contents of the external file.

'HISTORY'

saves or appends the statements submitted from SCL programs to a catalog member. You must specify the name of an entry as argument-1, in one of the following forms:

entry: saves the submitted statements in SASUSER.PROFILE.entry.SOURCE.
entry.SOURCE: saves the submitted statements in SASUSER.PROFILE.entry.SOURCE.
libref.catalog.entry: saves the submitted statements in libref.catalog.entry.SOURCE.
libref.catalog.entry.SOURCE: saves the submitted statements in libref.catalog.entry.SOURCE.

Once a history destination is set, it remains in effect for the application until a reset is performed. To clear the destination, invoke PREVIEW again by passing the HISTORY action without any subsequent argument. The application stops appending the submitted statements to the previously specified SOURCE entry.

You can also optionally specify a description of up to 40 characters for the entry as argument-2.

'INCLUDE'

copies into the PREVIEW window the contents of an external file. With this action, you must specify the fileref for the external file as argument-1. A physical filename is not allowed.

'LINES'

returns the number of the last non-blank line in the PREVIEW window.

'MODIFIED'

returns 1 if the PREVIEW window was modified and 0 if it was not modified.

'OPEN'

displays the PREVIEW window and immediately returns control to the SCL program. New SAS statements are displayed continually as they are generated.

This window is displayed until the application closes or until you use the PREVIEW function and specify the CLOSE action. Thus, specifying OPEN enables you to keep the window open throughout an application by allowing control to return to the procedure while the window is open. With OPEN, you can optionally specify a window title as argument-1.

'PRINT'

prints the contents of the PREVIEW window. This action accepts three arguments:

You can optionally use argument-1 to specify a form to use for controlling printing. Use name or name.FORM to specify a form in the current catalog. Use libref.catalog.name or libref.catalog.name.FORM to specify a form in a different catalog. If you do not specify a form, SASHELP.FSP.DEFAULT.FORM is used. For more information about forms, see SAS Language Reference: Dictionary.
You can optionally use argument-2 to specify a fileref for a print file. If this argument is blank or missing, the printout is sent to the default system printer.
You can optionally use argument-3 to specify append mode. Use A to append the output to the print file. If this argument is blank or missing, each new PRINT option replaces the contents of the print file.

'SAVE'

copies the contents of the PREVIEW window to a catalog member. With this action, you must specify the name of an entry as argument-1, in one of the following forms:

entry: saves the contents in SASUSER.PROFILE.entry.SOURCE.
entry.type: saves the contents in SASUSER.PROFILE.entry.type. Entry types can be SOURCE, LOG, OUTPUT, or SCL.
libref.catalog.entry: saves the contents in libref.catalog.entry.SOURCE.
libref.catalog.entry.type: saves the contents in libref.catalog.entry.type.

You can also optionally specify a description for the entry as argument-2. The first 256 characters of the description are saved.

You can also optionally specify APPEND as argument-3 to append the contents of the PREVIEW window to the specified catalog entry.

Details

The preview buffer is where statements that are generated by SUBMIT blocks are stored before they are submitted for execution.

Example

Manipulate the PREVIEW window. The user enters values in text entry controls TABLENAME (the name of a SAS table to be created), MIMIC (the name of an existing SAS table after which the new table is modeled), and FNAME (the fileref of a file in which submitted SAS statements will be stored). If the user does not issue a CANCEL command from the application window, then PREVIEW displays the statements in the PREVIEW window. If the user does not issue a CANCEL command from the PREVIEW window, then the statements are submitted for execution. If a user issues a CANCEL command from the application or from the PREVIEW window, the PREVIEW window is cleared of all statements. When a user presses the RUN button, the statements are submitted.

INIT:
   control label;
return;
RUN:
 submit;
    data &tablename;
       set &mimic;
    run;
  endsubmit;
 if (_status_ ne 'C') then
    do;
     if (preview('EDIT') = -1) then
        rc=preview('clear');
       else
        do;
          rc=preview('FILE',FNAME);
            submit continue;
             endsubmit;
           end;
      end;
   else
      rc=preview('clear');
return;