[SAS] was designed for use with SAS.  It is descended from emacs macros developed by John Sall for editing SAS programs and SAS-mode by Tom Cook.  Those editing features and new advanced features are part of [SAS].  The user interface of [SAS] has similarities with [S] and the SAS Display Manager.

ESS(SAS)--Design philosophy
===========================

[SAS] was designed to aid the user in writing and maintaining SAS programs, such as FOO.sas.  Both interactive and batch submission of SAS programs is supported.

[SAS] was written with two primary goals.

 1. The emacs text editor provides a powerful and flexible development environment for programming languages.  These features are a boon to all programmers and, with the help of [SAS], to SAS users as well.

 2. Although a departure from SAS Display Manager, [SAS] provides similar key definitions to give novice [SAS] users a head start. Also, inconvenient SAS Display Manager features, like remote submission and syntax highlighting, are provided transparently; appealing to advanced [SAS] users.

ESS(SAS)--Editing files
=======================

[SAS] is the mode for editing SAS language files.  This mode handles:

  * proper indenting, generated by both TAB and RET.

  * color and font choices based on syntax.

  * ability to save and submit the file you are working on as a batch SAS process with a single keypress and to continue editing while it is runs in the background.

  * capability of killing the batch SAS process through the *shell* buffer or allow the SAS process to keep on running after you exit emacs.

  * single keypress navigation of .sas, .log and .lst files (.log and .lst files are refreshed with each keypress).

  * ability to send the contents of an entire buffer, a highlighted region, or a single line to an interactive SAS process.

  * ability to switch between processes which would be the target of the buffer (for the above).

[SAS] is automatically turned on when editing a file with a .sas suffix (or other extension, if specified via auto-mode-alist).  The function keys can be enabled to use the same function keys that the SAS Display Manager does.  The interactive capabilities of ESS require you to start an inferior SAS process with M-x SAS (see iESS(SAS)--Interactive SAS processes.)

At this writing, the indenting and syntax highlighting are generally correct.  Known issues: for multiple line * or %* comments, only the first line is highlighted; for .log files, only the first line of a NOTE:, WARNING: or ERROR: message is highlighted; unmatched single/double quotes in CARDS data lines are NOT ignored; in an iterative DO statement, TO and BY are not highlighted.

ESS(SAS)--TAB key
=================

Two options.  The TAB key is bound by default to sas-indent-line.  This function is used to syntactically indent SAS code so PROC and RUN are in the left margin, other statements are indented sas-indent-width spaces from the margin, continuation lines are indented sas-indent-width spaces in from the beginning column of that statement.  This is the type of functionality that emacs provides in most programming language modes.  This functionality is equivalent to uncommenting the following line in ess-site.el:

     (setq ess-sas-edit-keys-toggle nil)

ESS provides an alternate behavior for TAB that makes it behave as it does in SAS Display Manager, i.e. move the cursor to the next stop. The alternate behavior also provides a "TAB" backwards, C-TAB, that moves the cursor to the stop to the left and deletes any characters between them.  This functionality is obtained by uncommenting the following line in ess-site.el:

     (setq ess-sas-edit-keys-toggle t)

Under the alternate behavior, TAB is bound to M-x tab-to-tab-stop and the stops are defined by ess-sas-tab-stop-list.

ESS(SAS)--Batch SAS processes
=============================

Submission of a SAS batch job is dependent on your environment. ess-sas-submit-method is determined by your operating system and your shell.  It defaults to 'sh unless you are running Windows or Mac Classic.  Under Windows, it will default to 'sh if you are using a UNIX-imitating shell; otherwise 'ms-dos for an MS-DOS shell.  On Mac OS X, it will default to 'sh, but under Mac Classic, it defaults to 'apple-script.  You will also set this to 'sh if the SAS batch job needs to run on a remote machine rather than your local machine.  This works transparently if you are editing the remote file via ange-ftp/EFS or tramp.  Note that ess-sas-shell-buffer-remote-init is a Local Variable that defaults to "ssh" which will be used to open the buffer on the remote host and it is assumed that no password is necessary, i.e. you are using ssh-agent/ssh-add or the equivalent (see the discussion about Local Variables below if you need to change the default).

However, if you are editing the file locally and transferring it back and forth with Kermit, you need some additional steps.  First, start Kermit locally before remotely logging in.  Open a local copy of the file with the ess-kermit-prefix character prepended (the default is "#"). Execute the command M-x ess-kermit-get which automatically brings the contents of the remote file into your local copy.  If you transfer files with Kermit manually in a *shell* buffer, then note that the Kermit escape sequence is C-q C-\ c rather than C-\ c which it would be in an ordinary terminal application, i.e. not in an emacs buffer.  Lastly, note that the remote Kermit command is specified by ess-kermit-command.

The command used by the SUBMIT function key (F3 or F8) to submit a batch SAS job, whether local or remote, is ess-sas-submit-command which defaults to sas-program. sas-program is "invoke SAS using program file" for Mac Classic and "sas" otherwise.  However, you may have to alter ess-sas-submit-command for a particular program, so it is defined as buffer-local.  Conveniently, it can be set at the end of the program:

     endsas;
     Local variables:
     ess-sas-submit-command: "sas8"
     End:

The command line is also made of ess-sas-submit-pre-command, ess-sas-submit-post-command and ess-sas-submit-command-options (the last of which is also buffer-local). Here are some examples for your initfile file (you may also use M-x customize-variable):

     ;'sh default
     (setq ess-sas-submit-pre-command "nohup")
     ;'sh default
     (setq ess-sas-submit-post-command "-rsasuser &")
     ;'sh example
     (setq-default ess-sas-submit-command "/usr/local/sas/sas")
     ;'ms-dos default
     (setq ess-sas-submit-pre-command "start")
     ;'ms-dos default
     (setq ess-sas-submit-post-command "-rsasuser -icon")
     ;Windows example
     (setq-default ess-sas-submit-command "c:/progra~1/sas/sas.exe")
     ;Windows example
     (setq-default ess-sas-submit-command "c:\\progra~1\\sas\\sas.exe")

There is a built-in delay before a batch SAS job is submitted when using a UNIX-imitating shell under Windows.  This is necessary in many cases since the shell might not be ready to receive a command.  This delay is currently set high enough so as not to be a problem.  But, there may be cases when it needs to be set higher, or could be set much lower to speed things up.  You can over-ride the default in your initfile file by:

     (setq ess-sleep-for 0.2)

For example, (setq ess-sas-global-unix-keys t) keys shown, (setq ess-sas-global-pc-keys t) in parentheses; [SAS] function keys are presented in the next section. Open the file you want to work with C-x C-f foo.sas. FOO.sas will be in [SAS] mode.  Edit as appropriate, then save and submit the batch SAS job.

     F3 (F8)

The job runs in the *shell* buffer while you continue to edit FOO.sas.  If ess-sas-submit-method is 'sh, then the message buffer will display the shell notification when the job is complete.  The 'sh setting also allows you to terminate the SAS batch job before it is finished.

     F8 (F3)

Terminating a SAS batch in the *shell* buffer.

     kill PID

You may want to visit the .log (whether the job is still running or it is finished) and check for error messages.  The .log will be refreshed and you will be placed in it's buffer.  You will be taken to the first error message, if any.

     F5 (F6)

Goto the next error message, if any.

     F5 (F6)

Now, refresh the .lst and go to it's buffer.

     F6 (F7)

If you wish to make changes, go to the .sas file with.

     F4 (F5)

Make your editing changes and submit again.

     F3 (F8)

ESS(SAS)--Function keys for batch processing
============================================

The setup of function keys for SAS batch processing is unavoidably complex, but the usage of function keys is simple. There are five distinct options:

Option 1 (default).  Function keys in [SAS] are not bound to elisp commands.  This is in accordance with the GNU Elisp Coding Standards (GECS) which do not allow function keys to be bound so that they are available to the user.

Options 2-5.  Since GECS does not allow function keys to be bound by modes, these keys are often unused.  So, [SAS] provides users with the option of binding elisp commands to these keys.  Users who are familiar with SAS will, most likely, want to duplicate the function key capabilities of the SAS Display Manager.  There are four options (noted in parentheses).

 a. SAS Display Manager has different function key definitions for UNIX (2, 4) and Windows (3, 5); [SAS] can use either.

 b. The [SAS] function key definitions can be active in all buffers (global: 4, 5) or limited (local: 2, 3) only to buffers with files that are associated with [SAS] as specified in your auto-mode-alist.

The distinction between local and global is subtle.  If you want the [SAS] definitions to work when you are in the *shell* buffer or when editing files other than the file extensions that [SAS] recognizes, you will most likely want to use the global definitions.  If you want your function keys to understand SAS batch commands when you are editing SAS files, and to behave normally when editing other files, then you will choose the local definitions.  The option can be chosen by the person installing ESS for a site or by an individual.

 a. For a site installation or an individual, uncomment ONLY ONE of the following lines in your ess-site.el.  [SAS] function keys are available in [SAS] if you uncomment either 2 or 3 and in all modes if you uncomment 4 or 5:

          ;;2; (setq ess-sas-local-unix-keys t)
          ;;3; (setq ess-sas-local-pc-keys t)
          ;;4; (setq ess-sas-global-unix-keys t)
          ;;5; (setq ess-sas-global-pc-keys t)

     The names -unix- and -pc- have nothing to do with the operating system that you are running.  Rather, they mimic the definitions that the SAS Display Manager uses by default on those platforms.

 b. If your site installation has configured the keys contrary to your liking, then you must call the appropriate function.

           (load "ess-site") ;; local-unix-keys
           (ess-sas-global-pc-keys)

Finally, we get to what the function keys actually do.  You may recognize some of the nicknames as SAS Display Manager commands (they are in all capitals).

UNIX Nickname

F2   F2   refresh

revert the current buffer with the file of the same
name if the file is newer than the buffer

F3   F8   SUBMIT

save the current .sas file (which is either the .sas
file in the current buffer or the .sas file associated
with the .lst or .log file in the current buffer)
and submit the file as a batch SAS job

F4   F5   PROGRAM

switch buffer to .sas file

F5   F6   LOG

switch buffer to .log file, refresh and goto next
error message, if any

F6   F7   OUTPUT

switch buffer to .lst file and refresh

F7   F4   filetype-1

switch buffer to filetype-1 (defaults to .txt) file
and refresh

F8   F3   shell

switch buffer to *shell*

F9   F9   VIEWTABLE

open an interactive PROC FSEDIT session on the SAS
dataset near point

F10   F10   toggle-log

toggle [SAS] for .log files; useful for certain
debugging situations

F11   F11   filetype-2

switch buffer to filetype-2 (defaults to .dat) file
and refresh

F12   F12   viewgraph

open a GSASFILE near point for viewing either in emacs
or with an external viewer

C-F1   C-F1   rtf-portrait

create an MS RTF portrait file from the current buffer
with a file extension of .rtf

C-F2   C-F2   rtf-landscape

create an MS RTF landscape file from the current buffer
with a file extension of .rtf

C-F3   C-F8   submit-region

write region to ess-temp.sas and submit

C-F5   C-F6   append-to-log

append ess-temp.log to the current .log file

C-F6   C-F7   append-to-output

append ess-temp.lst to the current .lst file

C-F9   C-F9   INSIGHT

open an interactive PROC INSIGHT session on the SAS
dataset near point

C-F10   C-F10   toggle-listing

toggle [SAS] for .lst files; useful for toggling
read-only

SUBMIT, PROGRAM, LOG and OUTPUT need no further explanation since they mimic the SAS Display Manager commands and related function key definitions.  However, six other keys have been provided for convenience and are described below.

shell switches you to the *shell* buffer where you can interact with your operating system.  This is especially helpful if you would like to kill a SAS batch job.  You can specify a different buffer name to associate with a SAS batch job (besides *shell*) with the buffer-local variable ess-sas-shell-buffer.  This allows you to have multiple buffers running SAS batch jobs on multiple local/remote computers that may rely on different methods specified by the buffer-local variable ess-sas-submit-method.

F2 performs the refresh operation on the current buffer. refresh compares the buffer's last modified date/time with the file's last modified date/time and replaces the buffer with the file if the file is newer.  This is the same operation that is automatically performed when LOG, OUTPUT, filetype-1 or F11 are pressed.

filetype-1 switches you to a file with the same file name as your .sas file, but with a different extension (.txt by default) and performs refresh.  You can over-ride the default extension; for example in your initfile file:

     (setq ess-sas-suffix-1 "csv") ; for example

F9 will prompt you for the name of a permanent SAS dataset near point to be opened for viewing by PROC FSEDIT.  You can control the SAS batch command-line with ess-sas-data-view-submit-options. For controlling the SAS batch commands, you have the global variables ess-sas-data-view-libname and ess-sas-data-view-fsview-command as well as the buffer-local variable ess-sas-data-view-fsview-statement.  If you have your SAS LIBNAME defined in ~/autoexec.sas, then the defaults for these variables should be sufficient.

Similarly, C-F9 will prompt you for the name of a permanent SAS dataset near point to be opened for viewing by PROC INSIGHT. You can control the SAS batch command-line with ess-sas-data-view-submit-options.  For controlling the SAS batch commands, you have the global variables ess-sas-data-view-libname and ess-sas-data-view-insight-command as well as the buffer-local variable ess-sas-data-view-insight-statement.

F10 toggles [SAS] mode for .log files which is off by default (technically, it is SAS-log-mode, but it looks the same).  The syntax highlighting can be helpful in certain debugging situations, but large .log files may take a long time to highlight.

F11 is the same as filetype-1 except it is .dat by default.

F12 will prompt you for the name of a GSASFILE near the point in .log to be opened for viewing either with emacs or with an external viewer. Depending on your version of emacs and the operating system you are using, emacs may support .gif and .jpg files internally.  You may need to change the following variables for your own situation. ess-sas-graph-view-suffix-regexp is a regular expression of supported file types defined via file name extensions. ess-sas-graph-view-viewer-default is the default external viewer for your platform.  ess-sas-graph-view-viewer-alist is an alist of exceptions to the default; i.e. file types and their associated viewers which will be used rather than the default viewer.

     (setq ess-sas-graph-view-suffix-regexp (concat "[.]\\([eE]?[pP][sS]\\|"
     "[pP][dD][fF]\\|[gG][iI][fF]\\|[jJ][pP][eE]?[gG]\\|"
     "[tT][iI][fF][fF]?\\)")) ;; default
     (setq ess-sas-graph-view-viewer-default "kodakimg") ;; Windows default
     (setq ess-sas-graph-view-viewer-default "sdtimage") ;; Solaris default
     (setq ess-sas-graph-view-viewer-alist
       '(("[eE]?[pP][sS]" . "gv") ("[pP][dD][fF]" . "gv")) ;; default w/ gv

C-F2 produces US landscape by default, however, it can produce A4 landscape (first line for "global" key mapping, second for "local"):

     (global-set-key [(control f2)] 'ess-sas-rtf-a4-landscape)
     (define-key sas-mode-local-map [(control f2)] 'ess-sas-rtf-a4-landscape)

iESS(SAS)--Interactive SAS processes
====================================

Inferior ESS (iESS) is the method for interfacing with interactive statistical processes (programs).  [SAS] is what is needed for interactive SAS programming.  [SAS] works best with the SAS command-line option settings "-stdio -linesize 80 -noovp -nosyntaxcheck" (the default of inferior-SAS-args).

     -stdio
                 required to make the redirection of stdio work
     -linesize 80
                 keeps output lines from folding on standard terminals
     -noovp
                 prevents error messages from printing 3 times
     -nosyntaxcheck
                 permits recovery after syntax errors

To start up [SAS] mode, use:

        M-x SAS

The *SAS:1.log* buffer in ESStr mode corresponds to the file FOO.log in SAS batch usage and to the SAS: LOG window in the SAS Display Manager.  All commands submitted to SAS, informative messages, warnings, and errors appear here.

The *SAS:1.lst* buffer in ESSlst mode corresponds to the file FOO.lst in SAS batch usage and to the SAS: OUTPUT window in the SAS Display Manager.  All printed output appears in this window.

The *SAS:1* buffer exists solely as a communications buffer. The user should never use this buffer directly. Files are edited in the FOO.sas buffer.  The C-c C-r key in [SAS] is the functional equivalent of bringing a file into the SAS: PROGRAM EDITOR window followed by SUBMIT.

For example, open the file you want to work with.

     C-x C-f foo.sas

FOO.sas will be in [SAS] mode.  Edit as appropriate, and then start up SAS with the cursor in the FOO.sas buffer.

     M-x SAS

Four buffers will appear on screen:

Buffer                 Mode                     Description

FOO.sas   [SAS]          your source file

*SAS:1*         [SAS:1]       iESS communication buffer

*SAS:1.log*     Shell ESStr []    SAS log information

*SAS:1.lst*     Shell ESSlst []   SAS listing information

If you would prefer each of the four buffers to appear in its own individual frame, you can arrange for that.  Place the cursor in the buffer displaying FOO.sas.  Enter the sequence C-c C-w. The cursor will normally be in buffer FOO.sas.  If not, put it there and C-x b FOO.sas.

Send regions, lines, or the entire file contents to SAS (regions are most useful:  a highlighted region will normally begin with the keywords DATA or PROC and end with RUN;), C-c C-r.

Information appears in the log buffer, analysis results in the listing buffer.  In case of errors, make the corrections in the FOO.sas buffer and resubmit with another C-c C-r.

At the end of the session you may save the log and listing buffers with the usual C-x C-s commands.  You will be prompted for a file name.  Typically, the names FOO.log and FOO.lst will be used.  You will almost certainly want to edit the saved files before including them in a report.  The files are read-only by default.  You can make them writable by the emacs command C-x C-q.

At the end of the session, the input file FOO.sas will typically have been revised.  You can save it.  It can be used later as the beginning of another [SAS] session.  It can also be used as a batch input file to SAS.

The *SAS:1* buffer is strictly for ESS use.  The user should never need to read it or write to it.  Refer to the .lst and .log buffers for monitoring output!

Troubleshooting: see iESS(SAS)--Common problems.

iESS(SAS)--Common problems
==========================

 1. [SAS] does not work on Windows.  In order to run SAS inside an emacs buffer, it is necessary to start SAS with the -stdio option. SAS does not support the -stdio option on Windows.

 2. If M-x SAS gives errors upon startup, check the following:

       * you are running Windows:  see 1.

       * ess-sas-sh-command (from the ESS etc directory) needs to be executable; too check, type M-x dired; if not, fix it as follows, type M-:, then at the minibuffer prompt Eval:, type (set-file-modes "ess-sas-sh-command" 493).

       * sas isn't in your executable path; to verify, type M-: and at the minibuffer prompt Eval:, type (executable-find "sas")

 3. M-x SAS starts SAS Display Manager.  Probably, the command sas on your system calls a shell script.  Specify the path to the real sas executable in ess-sas-sh-command, i.e.:

          /usr/local/sas612/sas $@ </dev/tty 1>$stdout 2>$stderr

     To find the sas exectuable, you can execute the UNIX command:

          find / -name sas -print

ESS(SAS)--Graphics
==================

Output from a /GRAPH PROC can be displayed in a /GRAPH window for SAS batch on Windows or for both SAS batch and interactive with XWindows on UNIX.  If you need to create graphics files and view them with F12, then include the following (either in FOO.sas or in ~/autoexec.sas):

     filename gsasfile 'graphics.ps';
     goptions device=ps gsfname=gsasfile gsfmode=append;

PROC PLOT graphs can be viewed in the listing buffer.  You may wish to control the vertical spacing to allow the entire plot to be visible on screen, for example:

     proc plot;
         plot a*b / vpos=25;
     run;

ESS(SAS)--Windows
=================

  * [SAS] does not work on Windows.  See iESS(SAS)--Common problems.

  * [SAS] mode for editing SAS language files works very well. See ESS(SAS)--Editing files.

  * There are two execution options for SAS on Windows. You can use batch.  See ESS(SAS)--Batch SAS processes.

     Or you can mark regions with the mouse and submit the code with `submit-region' or paste them into SAS Display Manager.