help-sas.texi

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

@comment  node-name,  next,  previous,  up
@node ESS(SAS)--Design philosophy, ESS(SAS)--Editing files, ESS for SAS, ESS for SAS
@section ESS[SAS]--Design philosophy

@ESS{[SAS]} was designed to aid the user in writing and maintaining @SAS{}
programs, such as @file{@var{foo}.sas}.  Both interactive and batch
submission of @SAS{} programs is supported.

@ESS{[SAS]} was written with two primary goals.
@enumerate
@item
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 @ESS{[SAS]}, to @SAS{} users as well.
@item
Although a departure from @SAS{} Display Manager, @ESS{[SAS]} provides
similar key definitions to give novice @ESS{[SAS]} users a head start.
Also, inconvenient @SAS{} Display Manager features, like remote submission
and syntax highlighting, are provided transparently; appealing to
advanced @ESS{[SAS]} users.
@end enumerate

@comment  node-name,  next,  previous,  up
@node ESS(SAS)--Editing files, ESS(SAS)--TAB key, ESS(SAS)--Design philosophy, ESS for SAS
@section ESS[SAS]--Editing files

@ESS{[SAS]} is the mode for editing @SAS{} language files.  This mode handles:

@itemize @bullet
@item
proper indenting, generated by both @key{TAB} and @key{RET}.
@item
color and font choices based on syntax.
@item
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.
@item
capability of killing the batch @SAS{} process through the @file{*shell*} buffer or
allow the @SAS{} process to keep on running after you exit emacs.
@item
single keypress navigation of @file{.sas}, @file{.log} and @file{.lst} files
(@file{.log} and @file{.lst} files are refreshed with each keypress).
@item
ability to send the contents of an entire buffer, a highlighted region,
or a single line to an interactive @SAS{} process.
@item
ability to switch between processes which would be the target of the
buffer (for the above).
@end itemize

@ESS{[SAS]} is automatically turned on when editing a file with a @file{.sas}
suffix (or other extension, if specified via @code{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 @wkbd{M-x SAS}
(@xref{iESS(SAS)--Interactive SAS processes}.)

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

@comment  node-name,  next,  previous,  up
@node  ESS(SAS)--TAB key, ESS(SAS)--Batch SAS processes, ESS(SAS)--Editing files, ESS for SAS
@section ESS[SAS]--@key{TAB} key

Two options.  The @key{TAB} key is bound by default to
@code{sas-indent-line}.  This function is used to syntactically indent
@SAS{} code so @code{PROC} and @code{RUN} are in the left margin,
other statements are indented @code{sas-indent-width} spaces from the
margin, continuation lines are indented @code{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 activated by placing the following line in your
initialization file prior to a @code{require}/@code{load}:
@example
(setq ess-sas-edit-keys-toggle nil)
@end example

@ESS{} provides an alternate behavior for @key{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, @wkbd{C-@key{TAB}}, that moves the cursor to the stop to
the left and deletes any characters between them.  This functionality
is obtained by placing the following line in your initialization file
prior to a @code{require}/@code{load}:
@example
(setq ess-sas-edit-keys-toggle t)
@end example
Under the alternate behavior, @key{TAB} is bound to @wkbd{M-x tab-to-tab-stop}
and the stops are defined by @code{ess-sas-tab-stop-list}.

@comment  node-name,  next,  previous,  up
@node  ESS(SAS)--Batch SAS processes, ESS(SAS)--Function keys for batch processing, ESS(SAS)--TAB key, ESS for SAS
@section ESS[SAS]--Batch SAS processes

Submission of a @SAS{} batch job is dependent on your environment.
@code{ess-sas-submit-method} is determined by your operating system and
your shell.  It defaults to @code{'sh} unless you are running Windows or
Mac Classic.  Under Windows, it will default to @code{'sh} if you are using
a @UNIX{}-imitating shell; otherwise @code{'ms-dos} for an @acronym{MS-DOS}
shell.  On macOS, it will default to @code{'sh}, but under Mac Classic,
it defaults to @code{'apple-script}.  You will also set this to @code{'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
@code{ess-sas-shell-buffer-remote-init} is a Local Variable that defaults
to @code{"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
@code{ssh-agent}/@code{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
@code{ess-kermit-prefix} character prepended (the default is @code{"#"}).
Execute the command @wkbd{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 @file{*shell*} buffer, then note that the
Kermit escape sequence is @wkbd{C-q C-\ c} rather than @wkbd{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
@code{ess-kermit-command}.

The command used by the @code{SUBMIT} function key (@key{F3} or @key{F8})
to submit a batch @SAS{} job, whether local or remote, is
@code{ess-sas-submit-command} which defaults to @code{sas-program}.
@code{sas-program} is @code{"invoke SAS using program file"} for Mac
Classic and @code{"sas"} otherwise.  However, you may have to alter
@code{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:
@example
endsas;
Local variables:
ess-sas-submit-command: "sas8"
End:
@end example

The command line is also made of @code{ess-sas-submit-pre-command},
@code{ess-sas-submit-post-command} and @code{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 @wkbd{M-x customize-variable}):
@example
;'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")
@end example

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:
@example
(setq ess-sleep-for 0.2)
@end example

For example, @code{(setq ess-sas-global-unix-keys t)} keys shown,
@code{(setq ess-sas-global-pc-keys t)} in parentheses;
@ESS{[SAS]} function keys are presented in the next section.
Open the file you want to work with @wkbd{C-x C-f foo.sas}.
@file{@var{foo}.sas} will be in @ESS{[SAS]} mode.  Edit as appropriate, then save and
submit the batch @SAS{} job.
@example
@key{F3} (@key{F8})
@end example
The job runs in the @file{*shell*} buffer while you continue to edit
@file{@var{foo}.sas}.  If @code{ess-sas-submit-method} is @code{'sh}, then the
message buffer will display the shell notification when the
job is complete.  The @code{'sh} setting also allows you to
terminate the @SAS{} batch job before it is finished.
@example
@key{F8} (@key{F3})
@end example
Terminating a @SAS{} batch in the @file{*shell*} buffer.
@example
kill @var{PID}
@end example
You may want to visit the @file{.log} (whether the job is still running
or it is finished) and check for error messages.  The @file{.log} will be
refreshed and you will be placed in it's buffer.  You will be
taken to the first error message, if any.
@example
@key{F5} (@key{F6})
@end example
Goto the next error message, if any.
@example
@key{F5} (@key{F6})
@end example
Now, @samp{refresh} the @file{.lst} and go to it's buffer.
@example
@key{F6} (@key{F7})
@end example
If you wish to make changes, go to the @file{.sas} file with.
@example
@key{F4} (@key{F5})
@end example
Make your editing changes and submit again.
@example
@key{F3} (@key{F8})
@end example

@comment  node-name,  next,  previous,  up
@node  ESS(SAS)--Function keys for batch processing, iESS(SAS)--Interactive SAS processes, ESS(SAS)--Batch SAS processes, ESS for SAS
@section 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 @ESS{[SAS]} are not bound to elisp
commands.  This is in accordance with the GNU Elisp Coding Standards
(@acronym{GECS}) which do not allow function keys to be bound so that they are
available to the user.

Options 2-5.  Since @acronym{GECS} does not allow function keys to be bound by
modes, these keys are often unused.  So, @ESS{[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).

@enumerate a
@item
@SAS{} Display Manager has different function key definitions for
@UNIX{} (2, 4) and Windows (3, 5); @ESS{[SAS]} can use either.
@item
The @ESS{[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 @ESS{[SAS]} as specified in your @code{auto-mode-alist}.
@end enumerate

The distinction between local and global is subtle.  If you want the
@ESS{[SAS]} definitions to work when you are in the @file{*shell*} buffer or when
editing files other than the file extensions that @ESS{[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.

@enumerate a
@item
For a site installation or an individual, place @strong{ONLY ONE} of
the following lines in your initialization file prior to a
@code{require}/@code{load}.  @ESS{[SAS]} function keys are available
in @ESS{[SAS]} if you choose either 2 or 3 and in all modes if you
choose 4 or 5:
@example
;;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)
@end example

The names @code{-unix-} and @code{-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.

@item
If your site installation has configured the keys contrary to your
liking, then you must call the appropriate function.
@example
 (load "ess-site") ;; local-unix-keys
 (ess-sas-global-pc-keys)
@end example
@end enumerate

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).

@multitable {123456} {123456} {really-really-really-really-really-really-really-really-really-really-long}
@item
@UNIX{} @tab @PC @tab Nickname
@item
@key{F2} @tab @key{F2} @tab @samp{refresh}
@item
@tab @tab
                    revert the current buffer with the file of the same
                    name if the file is newer than the buffer
@item
@key{F3} @tab @key{F8} @tab @code{SUBMIT}
@item
@tab @tab
                    save the current @file{.sas} file (which is either the @file{.sas}
                    file in the current buffer or the @file{.sas} file associated
                    with the @file{.lst} or @file{.log} file in the current buffer)
                    and submit the file as a batch @SAS{} job
@item
@key{F4} @tab @key{F5} @tab @code{PROGRAM}
@item
@tab @tab
                    switch buffer to @file{.sas} file
@item
@key{F5} @tab @key{F6} @tab @code{LOG}
@item
@tab @tab
                    switch buffer to @file{.log} file, @samp{refresh} and goto next
                    error message, if any
@item
@key{F6} @tab @key{F7} @tab @code{OUTPUT}
@item
@tab @tab
                    switch buffer to @file{.lst} file and @samp{refresh}
@item
@key{F7} @tab @key{F4} @tab @samp{filetype-1}
@item
@tab @tab
                    switch buffer to @samp{filetype-1} (defaults to @file{.txt}) file
                    and @samp{refresh}
@item
@key{F8} @tab @key{F3} @tab @samp{shell}
@item
@tab @tab
                    switch buffer to @file{*shell*}
@item
@key{F9} @tab @key{F9} @tab @code{VIEWTABLE}
@item
@tab @tab
                    open an interactive @code{PROC FSEDIT} session on the @SAS{}
                    dataset near point
@item
@key{F10} @tab @key{F10} @tab toggle-log
@item
@tab @tab
                    toggle @ESS{[SAS]} for @file{.log} files; useful for certain
                    debugging situations
@item
@key{F11} @tab @key{F11} @tab @samp{filetype-2}
@item
@tab @tab
                    switch buffer to @samp{filetype-2} (defaults to @file{.dat}) file
                    and @samp{refresh}
@item
@key{F12} @tab @key{F12} @tab viewgraph
@item
@tab @tab
                    open a @code{GSASFILE} near point for viewing either in emacs
                    or with an external viewer
@item
@kbd{C-@key{F1}} @tab @kbd{C-@key{F1}} @tab rtf-portrait
@item
@tab @tab
                    create an @sc{MS RTF} portrait file from the current buffer
                    with a file extension of @file{.rtf}
@item
@kbd{C-@key{F2}} @tab @kbd{C-@key{F2}} @tab rtf-landscape
@item
@tab @tab
                    create an @sc{MS RTF} landscape file from the current buffer
                    with a file extension of @file{.rtf}
@item
@kbd{C-@key{F3}} @tab @kbd{C-@key{F8}} @tab submit-region
@item
@tab @tab
                    write region to @file{ess-temp.sas} and submit
@item
@kbd{C-@key{F5}} @tab @kbd{C-@key{F6}} @tab append-to-log
@item
@tab @tab
                    append @file{ess-temp.log} to the current @file{.log} file
@item
@kbd{C-@key{F6}} @tab @kbd{C-@key{F7}} @tab append-to-output
@item
@tab @tab
                    append @file{ess-temp.lst} to the current @file{.lst} file
@item
@kbd{C-@key{F9}} @tab @kbd{C-@key{F9}} @tab @code{INSIGHT}
@item
@tab @tab
                    open an interactive @code{PROC INSIGHT} session on the @SAS{}
                    dataset near point
@item
@kbd{C-@key{F10}} @tab @kbd{C-@key{F10}} @tab toggle-listing
@item
@tab @tab
                    toggle @ESS{[SAS]} for @file{.lst} files; useful for toggling
                    read-only
@end multitable

@code{SUBMIT}, @code{PROGRAM}, @code{LOG} and @code{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.

@samp{shell} switches you to the @file{*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 @file{*shell*}) with the
buffer-local variable @code{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 @code{ess-sas-submit-method}.

@key{F2} performs the @samp{refresh} operation on the current buffer.
@samp{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 @code{LOG}, @code{OUTPUT}, @samp{filetype-1} or @key{F11} are pressed.

@samp{filetype-1} switches you to a file with the same file name as your @file{.sas}
file, but with a different extension (@file{.txt} by default) and performs
@samp{refresh}.  You can over-ride the default extension; for example in your
@initfile{} file:
@example
(setq ess-sas-suffix-1 "csv") ; for example
@end example

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

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

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

@key{F11} is the same as @samp{filetype-1} except it is @file{.dat} by default.

@key{F12} will prompt you for the name of a @code{GSASFILE} near the point in @file{.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 @file{.gif} and @file{.jpg} files internally.  You may need
to change the following variables for your own situation.
@code{ess-sas-graph-view-suffix-regexp} is a regular expression of supported
file types defined via file name extensions.
@code{ess-sas-graph-view-viewer-default} is the default external viewer for
your platform.  @code{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.
@example
(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
@end example

@wkbd{C-@key{F2}} produces US landscape by default, however, it can produce A4
landscape (first line for "global" key mapping, second for "local"):
@example
(global-set-key [(control f2)] 'ess-sas-rtf-a4-landscape)
(define-key sas-mode-local-map [(control f2)] 'ess-sas-rtf-a4-landscape)
@end example


@comment  node-name,  next,  previous,  up
@node  iESS(SAS)--Interactive SAS processes, iESS(SAS)--Common problems, ESS(SAS)--Function keys for batch processing, ESS for SAS
@section iESS[SAS]--Interactive SAS processes

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

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

To start up @iESS{[SAS]} mode, use:
@example
   @wkbd{M-x SAS}
@end example

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

The @file{*SAS:1.lst*} buffer in @code{ESSlst} mode corresponds to the file
@file{@var{foo}.lst} in @SAS{} batch usage and to the @samp{SAS: OUTPUT} window in the
@SAS{} Display Manager.  All printed output appears in this window.

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

For example, open the file you want to work with.
@example
@wkbd{C-x C-f foo.sas}
@end example
@file{@var{foo}.sas} will be in @ESS{[SAS]} mode.  Edit as appropriate, and then start
up @SAS{} with the cursor in the @file{@var{foo}.sas} buffer.
@example
@wkbd{M-x SAS}
@end example
Four buffers will appear on screen:
@multitable {buffer-names} {long-mode-names} {much-much-much-much-longer-description}
@item
Buffer               @tab Mode                   @tab Description
@item
@file{@var{foo}.sas} @tab @code{@ESS{[SAS]}}        @tab your source file
@item
@file{*SAS:1*}       @tab @code{@iESS{[SAS:1]}}     @tab @iESS{} communication buffer
@item
@file{*SAS:1.log*}   @tab @code{Shell ESStr []}  @tab @SAS{} log information
@item
@file{*SAS:1.lst*}   @tab @code{Shell ESSlst []} @tab @SAS{} listing information
@end multitable
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 @file{@var{foo}.sas}.  Enter the
sequence @wkbd{C-c C-w}. The cursor will normally be in buffer
@file{@var{foo}.sas}.  If not, put it there and @wkbd{C-x b @var{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 @code{DATA} or @code{PROC} and end with
@code{RUN;}), @wkbd{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
@file{@var{foo}.sas} buffer and resubmit with another @wkbd{C-c C-r}.

At the end of the session you may save the log and listing
buffers with the usual @wkbd{C-x C-s} commands.  You will be prompted
for a file name.  Typically, the names @file{@var{foo}.log} and @file{@var{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 @wkbd{C-x C-q}.

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

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

Troubleshooting: @xref{iESS(SAS)--Common problems}.

@comment  node-name,  next,  previous,  up
@node   iESS(SAS)--Common problems, ESS(SAS)--Graphics, iESS(SAS)--Interactive SAS processes, ESS for SAS
@section iESS[SAS]--Common problems

@enumerate
@item
@iESS{[SAS]} does not work on Windows.  In order to run @SAS{} inside
an emacs buffer, it is necessary to start @SAS{} with the @code{-stdio} option.
@SAS{} does not support the @code{-stdio} option on Windows.
@item
If @wkbd{M-x SAS} gives errors upon startup, check the following:
@itemize @bullet
@item
you are running Windows:  see 1.
@item
@file{ess-sas-sh-command} (from the @ESS{} @file{etc} directory) needs to be
executable; too check, type @wkbd{M-x dired}; if not, fix it as follows,
type @kbd{M-:}, then at the minibuffer prompt @wsamp{Eval:},
type @code{(set-file-modes "ess-sas-sh-command" 493)}.
@c (solution: @code{chmod ugo+rx ess-sas-sh-command}).
@item
@code{sas} isn't in your executable path; to verify, type
@kbd{M-:} and at the minibuffer prompt @samp{Eval:}, type
@code{(executable-find "sas")}
@end itemize
@item
@wkbd{M-x SAS} starts @w{@SAS{} Display} Manager.  Probably, the command @code{sas}
on your system calls a shell script.  In that case you will need to locate
the real  @code{sas} executable and link to it.
You can execute the @UNIX{} command:
@example
find / -name sas -print
@end example
Now place a soft link to the real @code{sas} executable in your @code{~/bin}
directory, with for example
@example
cd ~/bin
ln -s /usr/local/sas9/sas sas
@end example
@end enumerate
Check your @code{PATH} environment variable to confirm that
@code{~/bin} appears before the directory in which the @code{sas}
shell script appears.

@comment Specify the path to the real
@comment @code{sas} executable in @file{ess-sas-sh-command}, i.e.:
@comment @example
@comment /usr/local/sas9/sas $@@ </dev/tty 1>$stdout 2>$stderr
@comment @end example
@comment    To find the @code{sas} executable, you can execute the @UNIX{} command:
@comment @example
@comment find / -name sas -print
@comment @end example
@comment @end enumerate

@comment  node-name,  next,  previous,  up
@node   ESS(SAS)--Graphics, ESS(SAS)--Windows, iESS(SAS)--Common problems, ESS for SAS
@section ESS[SAS]--Graphics

Output from a @SAS{/GRAPH} @code{PROC} can be displayed in a @SAS{/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 @key{F12}, then include the following (either in
@file{@var{foo}.sas} or in @file{~/autoexec.sas}):
@example
filename gsasfile 'graphics.ps';
goptions device=ps gsfname=gsasfile gsfmode=append;
@end example
@code{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:
@example
proc plot;
    plot a*b / vpos=25;
run;
@end example

@comment  node-name,  next,  previous,  up
@node   ESS(SAS)--Windows,  , ESS(SAS)--Graphics, ESS for SAS
@section ESS[SAS]--Windows

@itemize @bullet
@item
@iESS{[SAS]} does not work on Windows.  @xref{iESS(SAS)--Common problems}.

@item
@ESS{[SAS]} mode for editing @SAS{} language files works very well.
@xref{ESS(SAS)--Editing files}.

@item
There are two execution options for @SAS{} on Windows.
You can use batch.  @xref{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.

@end itemize

@comment Local Variables:
@comment TeX-master: "ess.texi"
@comment End: