8
The SAS module in ESS (ESS[SAS]) is currently undergoing development.
9
It is functional and pretty stable. Please send any suggestions and
10
bug reports to ess-bugs@stat.math.ethz.ch.
12
ESS (originally S-mode) was initially designed for use with S and
13
S-PLUS(tm). ESS has been extended to support other languages,
14
including SAS(tm). The editing of SAS files is based on
15
the stable, old SAS mode by Cook
16
(ftp://ftp.biostat.wisc.edu/pub/cook/sas-mode/sas.tar.gz). Those
17
editing features and new advanced features are part of ESS[SAS].
18
The user interface with ESS[SAS] is similar in behavior to the
19
interface for S (unlike Cook's SAS mode) and to the windowing
20
interface that SAS itself uses.
22
We denote by _Emacs_ one of the GNU family of editors, either Emacs
23
(as developed and maintained by the Free Software Foundation) or
24
XEmacs (which is a derivative work).
26
The following is covered in this document:
27
- general Emacs features.
29
- running an interactive SAS process as an inferior process to Emacs
30
- running a batch SAS process in a shell buffer
31
- Scenarios for use (possibilities, based on actual usage)
36
Emacs: General features
37
=======================
39
We assume that you are familiar with Emacs terminology and syntax:
40
file, buffer, region, description of keys etc. If not, please read
41
the New Users guide (found in the info pages, "C-h i" (by pressing
42
control h, i) or Tutorial, "C-h t").
45
ESS[SAS]: Editing Files
46
=======================
48
ESS[SAS] is the mode for editing SAS language files. This mode handles:
50
- proper indenting, generated by both [Tab] and [Return].
51
- color and font choices based on syntax.
52
- ability to send the contents of an entire buffer, a highlighted region,
53
or a single line to an inferior SAS process, if one is currently running.
54
- ability to switch between processes which would be the target of the
55
buffer (for the above).
56
- ability to save and submit the file you are working on as a batch SAS
57
process with a single keypress and to continue editing while it is running
58
- capability of killing the batch SAS process through the shell buffer or
59
allow the SAS process to keep on running after you exit Emacs
60
- single keypress navigation of .sas, .log and .lst files (.log and .lst
61
files are automatically refreshed with each keypress)
63
ESS[SAS], the mode for editing SAS language files, is automatically
64
turned on when editing a file with a ".sas" suffix (or other, if
65
specified in ess-site). The batch processing keypress commands are
66
enabled by default to use the same function keys that the SAS Display
67
Manager uses. The interactive capabilities of ESS require you to
68
start an inferior SAS process with M-x SAS (described below).
70
At this writing (ESS release 5.2), the indenting and syntactic
71
highlighting are usually correct.
74
ESS[SAS]: Function keys for batch processing
75
============================================
77
The description of the setup for function keys for batch processing of
78
SAS files is unavoidably more complex than we wish it were. The actual
79
use of the function keys is simple. There are five distinct options:
81
1. (default) Function keys in ESS[SAS] modes do whatever they normally
82
do in other emacs modes. Many users will have defined some of the
83
keys [f2]-f[8] in their .emacs or _emacs file, or will have
84
installation-wide definitions in their site-start.el file. By
85
default, ESS does not override those definitions. This default is
86
intended to make ESS[SAS] mode behave similarly to other emacs modes.
89
Users who are primarily familiar with SAS, and who are learning emacs
90
as a way to approach SAS, will likely want to duplicate the function
91
key capabilities that SAS Institute provides with its Display Manager.
92
There are still options. SAS provides different function key
93
definitions with its PC and Unix products; ESS can use either. The
94
ESS[SAS] function key definitions can be active in all buffers
95
(global) or limited (local) only to buffers that have SAS-related file
96
extensions: .sas, .log, .lst, and "Type-1" which defaults to .txt.
97
The distinction between local and global appears subtle. If you want
98
the ESS[SAS] definitions to work when you are in *shell* or when
99
editing files other than the file extensions that SAS recognizes, you
100
will most likely want to use the global definitions.
101
If you want your function keys to understand SAS batch commands when you
102
are editing SAS files, and to behave normally when editing other files,
103
then you will choose the local definitions.
105
The option can be chosen by the person installing ESS for a site or by
108
The site manager can uncomment only one of the following lines.
109
ESS[SAS] Function keys are available in ESS[SAS] and related modes if you
110
uncomment either of the following lines in your ess-site.el:
111
;;2; (setq ess-sas-local-unix-keys t)
112
;;3; (setq ess-sas-local-pc-keys t)
113
ESS[SAS] Function keys are available in all Emacs modes if you
114
uncomment either of the following lines in your ess-site.el:
115
;;4; (setq ess-sas-global-unix-keys t)
116
;;5; (setq ess-sas-global-pc-keys t)
117
The names -unix- and -pc- have nothing to do with the operating system
118
that you are running. Rather they mimic the definitions that the SAS
119
Display Manager uses by default on those platforms.
121
The option can be selected by an individual by adding a line to the
122
.emacs (or _emacs) file, immediately following the
124
line. If your site manager has chosen an option 2,3,4,5 you don't
125
want, you must turn it off before selecting a different option. To
126
turn off an option, add the appropriate line (uncommented) to your
127
.emacs (_emacs) file.
128
;;2; (setq ess-sas-local-unix-keys nil)
129
;;3; (setq ess-sas-local-pc-keys nil)
130
;;4; (setq ess-sas-global-unix-keys nil)
131
;;5; (setq ess-sas-global-pc-keys nil)
133
Finally we get to what the function keys do.
136
F2 F2 Refresh:revert the buffer with the file if the file on disk is newer
137
than the file currently in the buffer.
138
F3 F8 Submit: save the current .sas buffer (which may be the .sas
139
file associated with the .lst or .log file you
140
are actually looking at) to a file and submit
141
the file to a background SAS job.
142
F4 F5 Program:switch buffer to .sas file.
143
F5 F6 Log: switch buffer to .log file, "refresh" and
144
goto next error message, if any.
145
F6 F7 Listing:switch buffer to .lst file and "refresh".
146
F7 F4 Type-1: switch buffer to Type-1 (defaults to .txt) file and "refresh".
147
F8 F3 Shell: switch buffer to shell.
149
Keys [f3]-[f8] mimic SAS Display Manager keys. One other key has been
150
provided for convenience. F2 performs the "refresh" operation on the
151
current buffer. "refresh" compares the buffer date stamp with the
152
file date stamp and replaces the buffer with the file if the file is
153
newer. This is the same operation that is automatically performed
154
when Log, Listing, or Type-1 are pressed. Type-1 takes you to a file
155
with a user-specified extension; .txt by default. You can over-ride
156
the default, by specifying a different extension in your .emacs file:
157
(setq ess-sas-suffix-1 '.txt')
165
The TAB key is bound by default to sas-indent-line. This function is
166
used to syntactically indent SAS code so PROC and RUN are in the left
167
margin, other statements are indented 4 spaces from the margin,
168
continuation lines are indented 4 spaces in from the beginning column
169
of that statement. This is the type of functionality that Emacs
170
provides in most programming language modes. This functionality is
171
equivalent to uncommenting the following line in ess-site.el:
172
;;; (setq ess-sas-edit-keys-toggle 0)
174
ESS provides an alternate behavior for the TAB key that makes it
175
behave as it does on non-emacs terminals, i.e. move the cursor to the
176
next tab stop. The alternate behavior also provides a backwards TAB
177
key: C-TAB. This functionality is obtained by uncommenting the
178
following line in ess-site.el:
179
;;; (setq ess-sas-edit-keys-toggle 1)
180
Under the alternate behavior, the TAB key is bound to tab-to-tab-stop
181
and the tab stops are set by default at multiples of 4.
184
iESS: Inferior ESS processes
185
============================
187
iESS (inferior ESS) is the mode for interfacing with active
188
statistical processes (programs).
190
To start up iESS[SAS] mode, use:
194
- The ability to request help from a process for variables and
195
functions, and to have the results sent into a separate buffer.
196
- completion of object names and file names.
199
ESS[SAS]: Batch processes
200
=========================
202
The default command used by the Submmit funciton key (F3 or F8) to submit
203
a batch SAS job is simply "sas". If necessary, you can over-ride this in
204
your .emacs file something like one of the following:
205
;;; (setq ess-sas-submit-command "nohup nice sas") ;; Unix
206
;;; (setq ess-sas-submit-command "c:/progra~1/sas/sas.exe") ;; Windows
207
;;; (setq ess-sas-submit-command "invoke SAS using program file") ;; Mac
208
Note that when you are specifying a path under Windows, you should
209
avoid spaces (that is use "progra~1", not "Program Files") and you
210
should use forward slashes "/". There may be occasions when you want
211
to run a particular buffer under a different version of SAS or specify
212
different options on the command line. In that case, you can
213
over-ride ess-sas-submit-command in your local buffer with file
214
variables or other means.
216
There is a built-in delay before a batch SAS job is submitted when using
217
a Unix shell under either Unix or Windows. This is necessary in many cases
218
since the shell might not be ready to receive a command. This delay is
219
currently set high enough so as not to be a problem on any system. But,
220
there may be cases when it needs to be set higher, or could be set much
221
lower to speed things up. You can over-ride the default in your .emacs
222
file by (the default of 5 seconds is shown):
223
(setq ess-sleep-for 5)
229
We present one scenario for using ESS to interact with SAS.
230
Contributions of examples of how you work with ESS are appreciated
231
(especially since it helps us determine priorities on future
232
enhancements)! (comments as to what should be happening are prefixed
235
Batch SAS (-unix-keys illustrated, pc-keys in the comments)
236
## Find the file you want to work with
238
## myfile.sas will be in ESS[SAS] mode
240
## Edit as appropriate, then save and submit the batch SAS job.
244
## The job runs in the shell buffer while you continue to edit
245
## myfile.sas. If you are running a Unix shell under Unix or
246
## Windows, the message buffer will notify you with a shell
247
## notification when the job is complete. If so, then you
248
## will also have the option of terminating the batch job
249
## before it is finished.
253
## In any case, you may want to visit the .log while the process
254
## is still running (unix only) or when it is done and check for
256
## (you will be taken to the next error message, if any).
257
## The .log will be refreshed and you will be placed in it's buffer.
261
## Now, refresh the .lst and go to it's buffer.
265
## If you wish to make changes, go to the .sas file with
268
## and make your editing changes. The go back to the submit instruction.
272
## Find the file you want to work with
274
## myfile.sas will be in ESS[SAS] mode
276
## Edit as appropriate, and then start up SAS with the cursor in
277
## the myfile.sas buffer
280
## Four buffers will appear on screen:
281
## myfile.sas in ESS[SAS] mode # your source file
282
## *SAS:1* in iESS [SAS:1] mode # ESS communication buffer
283
## *SAS:1.log* in Shell [] ESStr mode # SAS log information
284
## *SAS:1.lst* in Shell [] ESSlst mode # SAS listing information
286
## If you would prefer each of the four buffers to appear in its
287
## own individual frame, you can arrange for that. Place the
288
## cursor in the buffer displaying myfile.sas. Enter the
292
## The cursor will normally be in buffer myfile.sas.
293
## If not, put it there:
296
## Send regions, lines, or the entire file contents to SAS
297
## (regions are most useful). A highlighted region will normally
298
## begin with the keywords 'DATA' or 'PROC' and end with the
302
## Information appears in the log buffer, analysis results in the
303
## listing buffer. In case of errors, make the corrections in the
304
## myfile.sas buffer and resubmit with another C-c C-r
306
## PROC GPLOT graphs will normally be produced in a postscript
307
## file and be viewed later. Include the lines
308
/* required gsoptions for batch files */
309
/* comment out these lines for interactive use on X-terminals*/
310
filename grafout 'temp.ps';
311
goptions device=ps gsfname=grafout gsfmode=append gaccess=sasgastd;
314
## PROC PLOT graphs can be viewed in the listing buffer. You may
315
## wish to control the vertical spacing to allow the entire plot
316
## to be visible on screen, for example, by
317
proc plot; plot a*b / vpos=25;
319
## At the end of the session you may save the log and listing
320
## buffers with the usual C-x C-s commands. You will be prompted
321
## for a file name. Typically, the names myfile.log and mfile.lst
322
## will be used. You will almost certainly want to edit the saved
323
## files before including them in a report. The files are
324
## read-only by default. You can make them writable by the Emacs
327
## At the end of the session, the input file myfile.sas will
328
## typically have been revised. You can save it. It can be used
329
## later as the beginning of another iESS[SAS] session. It can
330
## also be used as a batch input file to SAS.
332
## The *SAS:1* buffer is strictly for ESS use. The user should
333
## never need to read it or write to it. Refer to the .lst and
334
## .log buffers for monitoring output!
337
Here is a typical myfile.sas:
339
title 'Analysis of Case 0502';
342
infile '/home/public/stat/Data/case0502.asc'
349
model percent=code /ss1;
354
Recommended autoexec.sas
355
========================
357
The default settings of the inferior-SAS-args in essd-sas.el
358
are "-stdio -linesize 80 -noovp -nosyntaxcheck"
359
with the interpretations:
360
-stdio required to make the redirection of stdio work
361
-linesize 80 keeps output lines from folding on standard terminals
362
-noovp prevents error messages from printing 3 times
363
-nosyntaxcheck permits recovery after syntax errors
365
In addition there are several parameters that can't be set in the
366
command line. For these, we recommend the following line appear in
367
your autoexec.sas in your home directory:
369
options noovp pagesize=60 linesize=80 formdlim=' ';
373
noovp prevents error messages from printing 3 time
374
pagesize=60 standard printed page length instead of window length
375
linesize=80 keeps output lines from folding on standard terminals
376
formdlim=' ' blank replaces "C-l" formfeeds to prevent mostly
379
The noovp and linesize=80 appear in both the inferior-SAS-args and in
380
the autoexec.sas. The redundancy means that these options are in
381
effect for SAS batch usage and SAS window manager usage as well as for
389
Not yet available. The intent is that a marked section of a log file
390
from a previous SAS run can be resubmitted to SAS. The user would
391
highlight a region from 'PROC' to 'RUN;' and then send it to the
392
inferior SAS process with the [RET] key. ESS would automatically
393
clean the region (remove line numbers) and send the entire region over
394
as a single request to SAS.
400
ESS[SAS] mode was designed to aid the user in writing and maintaining
401
input command files, such as myfile.sas, for SAS. These are files
402
containing SAS statements. In a batch environment such files would be
403
submitted to SAS by the operating system command:
405
In a SAS window environment, these files would be brought into the
406
"SAS: PROGRAM EDITOR" window and then submitted with the 'Local' 'Submit'
409
The *SAS:1.log* buffer in ESStr mode corresponds to the file
410
myfile.log in SAS batch usage and to the "SAS: LOG" window in the SAS
411
window environment. All commands submitted to SAS, informative
412
messages, warnings, and errors appear here.
414
The *SAS:1.lst* buffer in ESSlst mode corresponds to the file
415
myfile.lst in SAS batch usage and to the "SAS: OUTPUT" window in the
416
SAS window environment. All data related printed output from the
417
PROCs appear in this window.
419
The iESS [SAS:1] buffer exists solely as a communications buffer.
420
Files are edited in the myfile.sas buffer. The C-c C-r key in
421
ESS[SAS] mode is the functional equivalent of bringing a file into the
422
"SAS: PROGRAM EDITOR" window followed by the 'Local' 'Submit' menu
423
commands. The user should never use this buffer directly.
426
The ESS[SAS] mode was written with two primary goals.
428
1. Using Emacs, a window environment becomes available for dial-up
429
users who do not have access to the SAS window environment.
431
2. The authors prefer the Emacs environment for editing and managing
432
input and output files, even on computer systems which run the SAS
435
A secondary goal was also realized.
437
3. With an X-windows terminal connected by ppp at 14400 baud to a
438
Unix system running SAS, iESS[SAS] interaction with SAS was hundreds
439
of times faster than the SAS window system. The savings come because
440
the ESS windows are subunits of a text-based xterm window, rather than
441
the remotely managed graphical windows provided by SAS. (The timings
442
are SAS timings from the log files. The SAS windows times include
443
window management and communications times as well as calculation
444
times. The iESS times include only the calculations by the SAS
448
Some Frequently Seen Problems
449
=============================
451
1. If M-x SAS gives weird errors upon startup, check the following:
452
- ess-sas-sh-command (in the ESS source directory) needs to be
453
executable (solution: "chmod ugo+rx ess-sas-sh-command").
454
- sas isn't in your executable path (verify using "which sas" from
455
a shell command-line)
456
- you need a copy of SAS (we can't solve this)
458
2. M-x SAS starts up SAS in the window system (motif, for example),
459
instead of starting it up in the emacs buffers.
461
Probably the unix command "sas" on your system calls a local
462
script which in turn calls the sas executable. The fix is to
463
call the sas executable directly.
465
Change the line in ess-sas-sh command from:
466
sas </dev/tty 1>$stdout 2>$stderr $@
467
to a call to the complete path name of the sas executable on
468
your system, for example:
469
/usr/local/sas612/sas </dev/tty 1>$stdout 2>$stderr $@
471
To find the complete path name on your system, you can
472
execute the line (from the unix prompt):
473
find / -name 'sas' -exec ls -ld {} \;
474
and expect a response similar to the following
475
-rwxr-xr-x 1 sas sas 2441216 Sep 9 1997 /usr/local/sas612/sas
added
removed
doc/README.SAS
