Initial Commit

[packages] / xemacs-packages / ess / texi / 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 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 myfile.sas.  Both interactive and batch submission
of SAS programs is supported.   

ESS[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 ESS[SAS], to SAS users as well.

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

@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:

@display
- proper indenting, generated by both [Tab] and [Return].
- color and font choices based on syntax.
- 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).
- 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 automatically refreshed with each keypress).
@end display

ESS[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
(@xref{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 a DO ... TO
or a DO ... TO ... BY statement, TOs are not highlighted (and neither is
BY).

@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]--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 4 spaces from the margin,
continuation lines are indented 4 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:
@example
(setq ess-sas-edit-keys-toggle nil)
@end example

ESS provides an alternate behavior for the TAB key that makes it behave
as it does in SAS Display Manager, i.e. move the cursor to the next tab
stop.  The alternate behavior also provides a backwards TAB, C-TAB, that
moves the cursor to the tab stop to the left and deletes any characters
between them.  This functionality is obtained by uncommenting the
following line in ess-site.el:
@example
(setq ess-sas-edit-keys-toggle t)
@end example
Under the alternate behavior, the TAB key is bound to tab-to-tab-stop
and the tab stops are set at multiples of sas-indent-width.

@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.
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 AppleScript is used
('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 the equivalent of ssh-agent/ssh-add (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 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:
@example
endsas;
Local variables:
ess-sas-submit-command: "sas8"
End:
@end example

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 .emacs file (you may also use 
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 .emacs
file by:
@example
(setq ess-sleep-for 0.2)
@end example

For example, open the file you want to work with 
(ess-sas-global-unix-keys keys shown, ess-sas-global-pc-keys in 
parentheses; ESS[SAS] function keys are presented in the next section).
@example
C-x C-f myfile.sas
@end example
myfile.sas will be in ESS[SAS] mode.  Edit as appropriate, then save and 
submit the batch SAS job.
@example
F3 (F8)
@end example
The job runs in the shell buffer while you continue to edit 
myfile.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.
@example
F8 (F3)
@end example
Terminating a SAS batch in the *shell* buffer.
@example
kill %1
@end example
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 1st error message, if any.  
@example
F5 (F6)
@end example
Goto the next error message, if any.
@example
F5 (F6)
@end example
Now, refresh the .lst and go to it's buffer.
@example
F6 (F7)
@end example
If you wish to make changes, go to the .sas file with.
@example
F4 (F5)
@end example
Make your editing changes and submit again.
@example
F3 (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
(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, 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 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 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 *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, uncomment ONLY ONE of the
following lines in your ess-site.el.  ESS[SAS] Function keys are
available in ESS[SAS] if you uncomment either 2 or 3 and in all modes if
you uncomment 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 -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.

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

@display
Unix PC  Nickname   "inferior" Alias (if any) and Description  

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     C-c C-b
                    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        C-c C-x
                    switch buffer to .log file, `refresh' and goto next 
                    error message, if any

F6   F7  OUTPUT     C-c C-y
                    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 FSEDIT/FSBROWSE session on the SAS 
                    dataset near point

F10  F10  toggle-log    
                    toggle ESS[SAS] for .log files; may be 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 C-c C-r 
                    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 INSIGHT session on the SAS 
                    dataset near point

C-F10 C-F10 kill-em-all
                    kill all buffers associated with a .sas program
@end display

SUBMIT, PROGRAM, LOG and OUTPUT need no further explanation since
they mimic the SAS Display Manager 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
.emacs file:
@example
(setq ess-sas-suffix-1 "csv") ; for example
@end 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 LIBNAMEs 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 ESS[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.
@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]" . "acroread")) ;; default
@end example

C-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

iESS (inferior ESS) 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 following settings for SAS command-line options 
(the default of inferior-SAS-args):

@example
-stdio -linesize 80 -noovp -nosyntaxcheck
@end example

@display
-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
@end display

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

The *SAS:1.log* buffer in ESStr mode corresponds to the file
myfile.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
myfile.lst in SAS batch usage and to the "SAS: OUTPUT" window in the
SAS Display Manager.  All data related printed output from the
PROCs appear in this window.

The iESS [SAS:1] buffer exists solely as a communications buffer.
Files are edited in the myfile.sas buffer.  The C-c C-r key in
ESS[SAS] is the functional equivalent of bringing a file into the
"SAS: PROGRAM EDITOR" window followed by the 'Local' 'Submit' menu
commands.  The user should never use this buffer directly.

For example, open the file you want to work with.
@example
C-x C-f myfile.sas
@end example
myfile.sas will be in ESS[SAS] mode.  Edit as appropriate, and then start 
up SAS with the cursor in the myfile.sas buffer.
@example
M-x SAS
@end example
Four buffers will appear on screen:
@example
Buffer          Mode            Description
myfile.sas      ESS[SAS]        your source file
*SAS:1*         iESS [SAS:1]    ESS communication buffer
*SAS:1.log*     Shell [] ESStr  SAS log information
*SAS:1.lst*     Shell [] ESSlst SAS listing information
@end example
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 myfile.sas.  Enter the
sequence:
@example
C-c C-w
@end example
The cursor will normally be in buffer myfile.sas.
If not, put it there:
@example
C-x b myfile.sas
@end example
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 the
keyword 'RUN;'
@example
C-c C-r
@end example
Information appears in the log buffer, analysis results in the
listing buffer.  In case of errors, make the corrections in the
myfile.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 myfile.log and myfile.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 myfile.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 *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!

@c DANGER Will Robinson!
@c We plan to add
@c @display
@c - The ability to request help from a process for variables and
@c   functions, and to have the results sent into a separate buffer.
@c - completion of object names and file names.
@c @end display

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

@display
1. iESS[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 (in the ESS source directory) needs to be
     executable (solution: "chmod ugo+rx ess-sas-sh-command").
   - sas isn't in your executable path (verify using "which sas" from
     a shell command-line)

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 the file ess-sas-sh-command, i.e.:
@example
/usr/local/sas612/sas </dev/tty 1>$stdout 2>$stderr $@@
@end example
   To find the "sas" exectuable, you can execute the unix command:
@example
find / -name sas -print
@end example
@end display

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

Output from GPROCs can be displayed in a SAS/Graph window for SAS batch
on Windows or for both SAS batch and interactive with X11 on Unix.  If
you need to create graphics files and view them with F12, then include
the following (either in myfile.sas or in your autoexec.sas):
@example
filename gsasfile 'graphics.ps'; 
goptions device=ps gsfname=gsasfile gsfmode=append; 
@end example
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)--MS Windows, , ESS(SAS)--Graphics, ESS for SAS
@section ESS[SAS]--MS 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