setting ess-style now works from *customized* ess-default-style
[ess.git] / doc / help-sas.texi
blob7041767a85012159d11e2ccb4abf1d74a611a04f
1 @ESS{[SAS]} was designed for use with @SAS{}.  It is descended from emacs
2 macros developed by John Sall for editing @SAS{} programs and @code{SAS-mode} by
3 Tom Cook.  Those editing features and new advanced features are part of
4 @ESS{[SAS]}.  The user interface of @ESS{[SAS]} has similarities with @ESS{[S]}
5 and the @SAS{} Display Manager.
7 @comment  node-name,  next,  previous,  up
8 @node ESS(SAS)--Design philosophy, ESS(SAS)--Editing files, ESS for SAS, ESS for SAS
9 @section ESS(SAS)--Design philosophy
11 @ESS{[SAS]} was designed to aid the user in writing and maintaining @SAS{}
12 programs, such as @file{@var{foo}.sas}.  Both interactive and batch
13 submission of @SAS{} programs is supported.
15 @ESS{[SAS]} was written with two primary goals.
16 @enumerate
17 @item
18 The emacs text editor provides a powerful and flexible development
19 environment for programming languages.  These features are a boon to all
20 programmers and, with the help of @ESS{[SAS]}, to @SAS{} users as well.
21 @item
22 Although a departure from @SAS{} Display Manager, @ESS{[SAS]} provides
23 similar key definitions to give novice @ESS{[SAS]} users a head start.
24 Also, inconvenient @SAS{} Display Manager features, like remote submission
25 and syntax highlighting, are provided transparently; appealing to
26 advanced @ESS{[SAS]} users.
27 @end enumerate
29 @comment  node-name,  next,  previous,  up
30 @node ESS(SAS)--Editing files, ESS(SAS)--TAB key, ESS(SAS)--Design philosophy, ESS for SAS
31 @section ESS(SAS)--Editing files
33 @ESS{[SAS]} is the mode for editing @SAS{} language files.  This mode handles:
35 @itemize @bullet
36 @item
37 proper indenting, generated by both @key{TAB} and @key{RET}.
38 @item
39 color and font choices based on syntax.
40 @item
41 ability to save and submit the file you are working on as a batch
42 @SAS{} process with a single keypress and to continue editing while it is runs
43 in the background.
44 @item
45 capability of killing the batch @SAS{} process through the @file{*shell*} buffer or
46 allow the @SAS{} process to keep on running after you exit emacs.
47 @item
48 single keypress navigation of @file{.sas}, @file{.log} and @file{.lst} files
49 (@file{.log} and @file{.lst} files are refreshed with each keypress).
50 @item
51 ability to send the contents of an entire buffer, a highlighted region,
52 or a single line to an interactive @SAS{} process.
53 @item
54 ability to switch between processes which would be the target of the
55 buffer (for the above).
56 @end itemize
58 @ESS{[SAS]} is automatically turned on when editing a file with a @file{.sas}
59 suffix (or other extension, if specified via @code{auto-mode-alist}).  The function
60 keys can be enabled to use the same function keys that
61 the @SAS{} Display Manager does.  The interactive capabilities of @ESS{} require you
62 to start an inferior @SAS{} process with @wkbd{M-x SAS}
63 (@xref{iESS(SAS)--Interactive SAS processes}.)
65 At this writing, the indenting and syntax highlighting are generally
66 correct.  Known issues: for multiple line @code{*} or @code{%*} comments, only the
67 first line is highlighted; for @file{.log} files, only the first line of a
68 @code{NOTE:}, @code{WARNING:} or @code{ERROR:} message is highlighted; unmatched
69 single/double quotes in @code{CARDS} data lines are @strong{NOT} ignored; in an
70 iterative @code{DO} statement, @code{TO} and @code{BY} are not highlighted.
72 @comment  node-name,  next,  previous,  up
73 @node  ESS(SAS)--TAB key, ESS(SAS)--Batch SAS processes, ESS(SAS)--Editing files, ESS for SAS
74 @section ESS(SAS)--@key{TAB} key
76 Two options.  The @key{TAB} key is bound by default to @code{sas-indent-line}.  This
77 function is used to syntactically indent @SAS{} code so @code{PROC} and @code{RUN} are in
78 the left margin, other statements are indented @code{sas-indent-width} spaces from the margin,
79 continuation lines are indented @code{sas-indent-width} spaces in from the beginning column of
80 that statement.  This is the type of functionality that emacs provides
81 in most programming language modes.  This functionality is equivalent to
82 uncommenting the following line in @file{ess-site.el}:
83 @example
84 (setq ess-sas-edit-keys-toggle nil)
85 @end example
87 @ESS{} provides an alternate behavior for @key{TAB} that makes it behave
88 as it does in @SAS{} Display Manager, i.e. move the cursor to the next stop.
89 The alternate behavior also provides a "TAB" backwards, @wkbd{C-@key{TAB}}, that
90 moves the cursor to the stop to the left and deletes any characters
91 between them.  This functionality is obtained by uncommenting the
92 following line in @file{ess-site.el}:
93 @example
94 (setq ess-sas-edit-keys-toggle t)
95 @end example
96 Under the alternate behavior, @key{TAB} is bound to @wkbd{M-x tab-to-tab-stop}
97 and the stops are defined by @code{ess-sas-tab-stop-list}.
99 @comment  node-name,  next,  previous,  up
100 @node  ESS(SAS)--Batch SAS processes, ESS(SAS)--Function keys for batch processing, ESS(SAS)--TAB key, ESS for SAS
101 @section ESS(SAS)--Batch SAS processes
103 Submission of a @SAS{} batch job is dependent on your environment.
104 @code{ess-sas-submit-method} is determined by your operating system and
105 your shell.  It defaults to @code{'sh} unless you are running Windows or
106 Mac Classic.  Under Windows, it will default to @code{'sh} if you are using
107 a @UNIX{}-imitating shell; otherwise @code{'ms-dos} for an @acronym{MS-DOS}
108 shell.  On Mac OS X, it will default to @code{'sh}, but under Mac Classic,
109 it defaults to @code{'apple-script}.  You will also set this to @code{'sh}
110 if the @SAS{} batch job needs to run on a remote machine rather than your
111 local machine.  This works transparently if you are editing the remote file
112 via ange-ftp/EFS or tramp.  Note that
113 @code{ess-sas-shell-buffer-remote-init} is a Local Variable that defaults
114 to @code{"ssh"} which will be used to open the buffer on the remote host
115 and it is assumed that no password is necessary, i.e. you are using
116 @code{ssh-agent}/@code{ssh-add} or the equivalent (see the discussion about
117 Local Variables below if you need to change the default).
119 However, if you are editing the file locally and transferring it back and
120 forth with Kermit, you need some additional steps.  First, start Kermit
121 locally before remotely logging in.  Open a local copy of the file with the
122 @code{ess-kermit-prefix} character prepended (the default is @code{"#"}).
123 Execute the command @wkbd{M-x ess-kermit-get} which automatically brings
124 the contents of the remote file into your local copy.  If you transfer
125 files with Kermit manually in a @file{*shell*} buffer, then note that the
126 Kermit escape sequence is @wkbd{C-q C-\ c} rather than @wkbd{C-\ c} which
127 it would be in an ordinary terminal application, i.e. not in an emacs
128 buffer.  Lastly, note that the remote Kermit command is specified by
129 @code{ess-kermit-command}.
131 The command used by the @code{SUBMIT} function key (@key{F3} or @key{F8})
132 to submit a batch @SAS{} job, whether local or remote, is
133 @code{ess-sas-submit-command} which defaults to @code{sas-program}.
134 @code{sas-program} is @code{"invoke SAS using program file"} for Mac
135 Classic and @code{"sas"} otherwise.  However, you may have to alter
136 @code{ess-sas-submit-command} for a particular program, so it is defined as
137 buffer-local.  Conveniently, it can be set at the end of the program:
138 @example
139 endsas;
140 Local variables:
141 ess-sas-submit-command: "sas8"
142 End:
143 @end example
145 The command line is also made of @code{ess-sas-submit-pre-command},
146 @code{ess-sas-submit-post-command} and @code{ess-sas-submit-command-options}
147 (the last of which is also buffer-local).
148 Here are some examples for your @initfile{}
149 file (you may also use @wkbd{M-x customize-variable}):
150 @example
151 ;'sh default
152 (setq ess-sas-submit-pre-command "nohup")
153 ;'sh default
154 (setq ess-sas-submit-post-command "-rsasuser &")
155 ;'sh example
156 (setq-default ess-sas-submit-command "/usr/local/sas/sas")
157 ;'ms-dos default
158 (setq ess-sas-submit-pre-command "start")
159 ;'ms-dos default
160 (setq ess-sas-submit-post-command "-rsasuser -icon")
161 ;Windows example
162 (setq-default ess-sas-submit-command "c:/progra~1/sas/sas.exe")
163 ;Windows example
164 (setq-default ess-sas-submit-command "c:\\progra~1\\sas\\sas.exe")
165 @end example
167 There is a built-in delay before a batch @SAS{} job is submitted when using
168 a @UNIX{}-imitating shell under Windows.  This is necessary in many cases
169 since the shell might not be ready to receive a command.  This delay is
170 currently set high enough so as not to be a problem.  But, there may be
171 cases when it needs to be set higher, or could be set much lower to
172 speed things up.  You can over-ride the default in your @initfile{} file by:
173 @example
174 (setq ess-sleep-for 0.2)
175 @end example
177 For example, @code{(setq ess-sas-global-unix-keys t)} keys shown,
178 @code{(setq ess-sas-global-pc-keys t)} in parentheses;
179 @ESS{[SAS]} function keys are presented in the next section.
180 Open the file you want to work with @wkbd{C-x C-f foo.sas}.
181 @file{@var{foo}.sas} will be in @ESS{[SAS]} mode.  Edit as appropriate, then save and
182 submit the batch @SAS{} job.
183 @example
184 @key{F3} (@key{F8})
185 @end example
186 The job runs in the @file{*shell*} buffer while you continue to edit
187 @file{@var{foo}.sas}.  If @code{ess-sas-submit-method} is @code{'sh}, then the
188 message buffer will display the shell notification when the
189 job is complete.  The @code{'sh} setting also allows you to
190 terminate the @SAS{} batch job before it is finished.
191 @example
192 @key{F8} (@key{F3})
193 @end example
194 Terminating a @SAS{} batch in the @file{*shell*} buffer.
195 @example
196 kill @var{PID}
197 @end example
198 You may want to visit the @file{.log} (whether the job is still running
199 or it is finished) and check for error messages.  The @file{.log} will be
200 refreshed and you will be placed in it's buffer.  You will be
201 taken to the first error message, if any.
202 @example
203 @key{F5} (@key{F6})
204 @end example
205 Goto the next error message, if any.
206 @example
207 @key{F5} (@key{F6})
208 @end example
209 Now, @samp{refresh} the @file{.lst} and go to it's buffer.
210 @example
211 @key{F6} (@key{F7})
212 @end example
213 If you wish to make changes, go to the @file{.sas} file with.
214 @example
215 @key{F4} (@key{F5})
216 @end example
217 Make your editing changes and submit again.
218 @example
219 @key{F3} (@key{F8})
220 @end example
222 @comment  node-name,  next,  previous,  up
223 @node  ESS(SAS)--Function keys for batch processing, iESS(SAS)--Interactive SAS processes, ESS(SAS)--Batch SAS processes, ESS for SAS
224 @section ESS(SAS)--Function keys for batch processing
226 The setup of function keys for @SAS{} batch processing
227 is unavoidably complex, but the usage of function keys is simple.
228 There are five distinct options:
230 Option 1 (default).  Function keys in @ESS{[SAS]} are not bound to elisp
231 commands.  This is in accordance with the GNU Elisp Coding Standards
232 (@acronym{GECS}) which do not allow function keys to be bound so that they are
233 available to the user.
235 Options 2-5.  Since @acronym{GECS} does not allow function keys to be bound by
236 modes, these keys are often unused.  So, @ESS{[SAS]} provides users with
237 the option of binding elisp commands to these keys.  Users who are
238 familiar with @SAS{} will, most likely, want to duplicate the function key
239 capabilities of the @SAS{} Display Manager.  There are four options (noted
240 in parentheses).
242 @enumerate a
243 @item
244 @SAS{} Display Manager has different function key definitions for
245 @UNIX{} (2, 4) and Windows (3, 5); @ESS{[SAS]} can use either.
246 @item
247 The @ESS{[SAS]} function key definitions can be active in all buffers
248 (global: 4, 5) or limited (local: 2, 3) only to buffers with files that
249 are associated with @ESS{[SAS]} as specified in your @code{auto-mode-alist}.
250 @end enumerate
252 The distinction between local and global is subtle.  If you want the
253 @ESS{[SAS]} definitions to work when you are in the @file{*shell*} buffer or when
254 editing files other than the file extensions that @ESS{[SAS]} recognizes,
255 you will most likely want to use the global definitions.  If you want
256 your function keys to understand @SAS{} batch commands when you are editing
257 @SAS{} files, and to behave normally when editing other files, then you
258 will choose the local definitions.  The option can be chosen by the
259 person installing @ESS{} for a site or by an individual.
261 @enumerate a
262 @item
263 For a site installation or an individual, uncomment @strong{ONLY ONE} of the
264 following lines in your @file{ess-site.el}.  @ESS{[SAS]} function keys are
265 available in @ESS{[SAS]} if you uncomment either 2 or 3 and in all modes if
266 you uncomment 4 or 5:
267 @example
268 ;;2; (setq ess-sas-local-unix-keys t)
269 ;;3; (setq ess-sas-local-pc-keys t)
270 ;;4; (setq ess-sas-global-unix-keys t)
271 ;;5; (setq ess-sas-global-pc-keys t)
272 @end example
274 The names @code{-unix-} and @code{-pc-} have nothing to do with the operating system
275 that you are running.  Rather, they mimic the definitions that the @SAS{}
276 Display Manager uses by default on those platforms.
278 @item
279 If your site installation has configured the keys contrary to your
280 liking, then you must call the appropriate function.
281 @example
282  (load "ess-site") ;; local-unix-keys
283  (ess-sas-global-pc-keys)
284 @end example
285 @end enumerate
287 Finally, we get to what the function keys actually do.  You may recognize
288 some of the nicknames as @SAS{} Display Manager commands (they are in all
289 capitals).
291 @multitable {123456} {123456} {really-really-really-really-really-really-really-really-really-really-long}
292 @item
293 @UNIX{} @tab @PC @tab Nickname
294 @item
295 @key{F2} @tab @key{F2} @tab @samp{refresh}
296 @item
297 @tab @tab
298                     revert the current buffer with the file of the same
299                     name if the file is newer than the buffer
300 @item
301 @key{F3} @tab @key{F8} @tab @code{SUBMIT}
302 @item
303 @tab @tab
304                     save the current @file{.sas} file (which is either the @file{.sas}
305                     file in the current buffer or the @file{.sas} file associated
306                     with the @file{.lst} or @file{.log} file in the current buffer)
307                     and submit the file as a batch @SAS{} job
308 @item
309 @key{F4} @tab @key{F5} @tab @code{PROGRAM}
310 @item
311 @tab @tab
312                     switch buffer to @file{.sas} file
313 @item
314 @key{F5} @tab @key{F6} @tab @code{LOG}
315 @item
316 @tab @tab
317                     switch buffer to @file{.log} file, @samp{refresh} and goto next
318                     error message, if any
319 @item
320 @key{F6} @tab @key{F7} @tab @code{OUTPUT}
321 @item
322 @tab @tab
323                     switch buffer to @file{.lst} file and @samp{refresh}
324 @item
325 @key{F7} @tab @key{F4} @tab @samp{filetype-1}
326 @item
327 @tab @tab
328                     switch buffer to @samp{filetype-1} (defaults to @file{.txt}) file
329                     and @samp{refresh}
330 @item
331 @key{F8} @tab @key{F3} @tab @samp{shell}
332 @item
333 @tab @tab
334                     switch buffer to @file{*shell*}
335 @item
336 @key{F9} @tab @key{F9} @tab @code{VIEWTABLE}
337 @item
338 @tab @tab
339                     open an interactive @code{PROC FSEDIT} session on the @SAS{}
340                     dataset near point
341 @item
342 @key{F10} @tab @key{F10} @tab toggle-log
343 @item
344 @tab @tab
345                     toggle @ESS{[SAS]} for @file{.log} files; useful for certain
346                     debugging situations
347 @item
348 @key{F11} @tab @key{F11} @tab @samp{filetype-2}
349 @item
350 @tab @tab
351                     switch buffer to @samp{filetype-2} (defaults to @file{.dat}) file
352                     and @samp{refresh}
353 @item
354 @key{F12} @tab @key{F12} @tab viewgraph
355 @item
356 @tab @tab
357                     open a @code{GSASFILE} near point for viewing either in emacs
358                     or with an external viewer
359 @item
360 @kbd{C-@key{F1}} @tab @kbd{C-@key{F1}} @tab rtf-portrait
361 @item
362 @tab @tab
363                     create an @sc{MS RTF} portrait file from the current buffer
364                     with a file extension of @file{.rtf}
365 @item
366 @kbd{C-@key{F2}} @tab @kbd{C-@key{F2}} @tab rtf-landscape
367 @item
368 @tab @tab
369                     create an @sc{MS RTF} landscape file from the current buffer
370                     with a file extension of @file{.rtf}
371 @item
372 @kbd{C-@key{F3}} @tab @kbd{C-@key{F8}} @tab submit-region
373 @item
374 @tab @tab
375                     write region to @file{ess-temp.sas} and submit
376 @item
377 @kbd{C-@key{F5}} @tab @kbd{C-@key{F6}} @tab append-to-log
378 @item
379 @tab @tab
380                     append @file{ess-temp.log} to the current @file{.log} file
381 @item
382 @kbd{C-@key{F6}} @tab @kbd{C-@key{F7}} @tab append-to-output
383 @item
384 @tab @tab
385                     append @file{ess-temp.lst} to the current @file{.lst} file
386 @item
387 @kbd{C-@key{F9}} @tab @kbd{C-@key{F9}} @tab @code{INSIGHT}
388 @item
389 @tab @tab
390                     open an interactive @code{PROC INSIGHT} session on the @SAS{}
391                     dataset near point
392 @item
393 @kbd{C-@key{F10}} @tab @kbd{C-@key{F10}} @tab toggle-listing
394 @item
395 @tab @tab
396                     toggle @ESS{[SAS]} for @file{.lst} files; useful for toggling
397                     read-only
398 @end multitable
400 @code{SUBMIT}, @code{PROGRAM}, @code{LOG} and @code{OUTPUT} need no further
401 explanation since they mimic the @SAS{} Display Manager commands and
402 related function key definitions.  However, six other keys have been
403 provided for convenience and are described below.
405 @samp{shell} switches you to the @file{*shell*} buffer where you can
406 interact with your operating system.  This is especially helpful if you
407 would like to kill a @SAS{} batch job.  You can specify a different buffer
408 name to associate with a @SAS{} batch job (besides @file{*shell*}) with the
409 buffer-local variable @code{ess-sas-shell-buffer}.  This allows you to have
410 multiple buffers running @SAS{} batch jobs on multiple local/remote
411 computers that may rely on different methods specified by the buffer-local
412 variable @code{ess-sas-submit-method}.
414 @key{F2} performs the @samp{refresh} operation on the current buffer.
415 @samp{refresh} compares the buffer's last modified date/time with the
416 file's last modified date/time and replaces the buffer with the file if the
417 file is newer.  This is the same operation that is automatically performed
418 when @code{LOG}, @code{OUTPUT}, @samp{filetype-1} or @key{F11} are pressed.
420 @samp{filetype-1} switches you to a file with the same file name as your @file{.sas}
421 file, but with a different extension (@file{.txt} by default) and performs
422 @samp{refresh}.  You can over-ride the default extension; for example in your
423 @initfile{} file:
424 @example
425 (setq ess-sas-suffix-1 "csv") ; for example
426 @end example
428 @key{F9} will prompt you for the name of a permanent @SAS{} dataset near
429 point to be opened for viewing by @code{PROC FSEDIT}.  You can control the
430 @SAS{} batch command-line with @code{ess-sas-data-view-submit-options}.
431 For controlling the @SAS{} batch commands, you have the global variables
432 @code{ess-sas-data-view-libname} and
433 @code{ess-sas-data-view-fsview-command} as well as the buffer-local
434 variable @code{ess-sas-data-view-fsview-statement}.  If you have your
435 @SAS{} @code{LIBNAME} defined in @file{~/autoexec.sas}, then the defaults
436 for these variables should be sufficient.
438 Similarly, @wkbd{C-@key{F9}} will prompt you for the name of a permanent
439 @SAS{} dataset near point to be opened for viewing by @code{PROC INSIGHT}.
440 You can control the @SAS{} batch command-line with
441 @code{ess-sas-data-view-submit-options}.  For controlling the @SAS{} batch
442 commands, you have the global variables @code{ess-sas-data-view-libname}
443 and @code{ess-sas-data-view-insight-command} as well as the buffer-local
444 variable @code{ess-sas-data-view-insight-statement}.
446 @key{F10} toggles @ESS{[SAS]} mode for @file{.log} files which is off by default
447 (technically, it is @code{SAS-log-mode}, but it looks the same).  The syntax
448 highlighting can be helpful in certain debugging situations, but large
449 @file{.log} files may take a long time to highlight.
451 @key{F11} is the same as @samp{filetype-1} except it is @file{.dat} by default.
453 @key{F12} will prompt you for the name of a @code{GSASFILE} near the point in @file{.log} to
454 be opened for viewing either with emacs or with an external viewer.
455 Depending on your version of emacs and the operating system you are
456 using, emacs may support @file{.gif} and @file{.jpg} files internally.  You may need
457 to change the following variables for your own situation.
458 @code{ess-sas-graph-view-suffix-regexp} is a regular expression of supported
459 file types defined via file name extensions.
460 @code{ess-sas-graph-view-viewer-default} is the default external viewer for
461 your platform.  @code{ess-sas-graph-view-viewer-alist} is an alist of
462 exceptions to the default; i.e. file types and their associated
463 viewers which will be used rather than the default viewer.
464 @example
465 (setq ess-sas-graph-view-suffix-regexp (concat "[.]\\([eE]?[pP][sS]\\|"
466 "[pP][dD][fF]\\|[gG][iI][fF]\\|[jJ][pP][eE]?[gG]\\|"
467 "[tT][iI][fF][fF]?\\)")) ;; default
468 (setq ess-sas-graph-view-viewer-default "kodakimg") ;; Windows default
469 (setq ess-sas-graph-view-viewer-default "sdtimage") ;; Solaris default
470 (setq ess-sas-graph-view-viewer-alist
471   '(("[eE]?[pP][sS]" . "gv") ("[pP][dD][fF]" . "gv")) ;; default w/ gv
472 @end example
474 @wkbd{C-@key{F2}} produces US landscape by default, however, it can produce A4
475 landscape (first line for "global" key mapping, second for "local"):
476 @example
477 (global-set-key [(control f2)] 'ess-sas-rtf-a4-landscape)
478 (define-key sas-mode-local-map [(control f2)] 'ess-sas-rtf-a4-landscape)
479 @end example
482 @comment  node-name,  next,  previous,  up
483 @node  iESS(SAS)--Interactive SAS processes, iESS(SAS)--Common problems, ESS(SAS)--Function keys for batch processing, ESS for SAS
484 @section iESS(SAS)--Interactive SAS processes
486 Inferior @ESS{} (@iESS{}) is the method for interfacing with interactive
487 statistical processes (programs).  @iESS{[SAS]} is what is needed for
488 interactive @SAS{} programming.  @iESS{[SAS]} works best
489 with the @SAS{} command-line option settings
490 @code{"-stdio -linesize 80 -noovp -nosyntaxcheck"}
491 (the default of @code{inferior-SAS-args}).
493 @display
494 @code{-stdio}
495             required to make the redirection of stdio work
496 @code{-linesize 80}
497             keeps output lines from folding on standard terminals
498 @code{-noovp}
499             prevents error messages from printing 3 times
500 @code{-nosyntaxcheck}
501             permits recovery after syntax errors
502 @end display
504 To start up @iESS{[SAS]} mode, use:
505 @example
506    @wkbd{M-x SAS}
507 @end example
509 The @file{*SAS:1.log*} buffer in @code{ESStr} mode corresponds to the file
510 @file{@var{foo}.log} in @SAS{} batch usage and to the @samp{SAS: LOG} window in the
511 @SAS{} Display Manager.  All commands submitted to @SAS{}, informative
512 messages, warnings, and errors appear here.
514 The @file{*SAS:1.lst*} buffer in @code{ESSlst} mode corresponds to the file
515 @file{@var{foo}.lst} in @SAS{} batch usage and to the @samp{SAS: OUTPUT} window in the
516 @SAS{} Display Manager.  All printed output appears in this window.
518 The @file{*SAS:1*} buffer exists solely as a communications buffer.
519 The user should never use this buffer directly.
520 Files are edited in the @file{@var{foo}.sas} buffer.  The @wkbd{C-c C-r} key in
521 @ESS{[SAS]} is the functional equivalent of bringing a file into the
522 @samp{SAS: PROGRAM EDITOR} window followed by @code{SUBMIT}.
524 For example, open the file you want to work with.
525 @example
526 @wkbd{C-x C-f foo.sas}
527 @end example
528 @file{@var{foo}.sas} will be in @ESS{[SAS]} mode.  Edit as appropriate, and then start
529 up @SAS{} with the cursor in the @file{@var{foo}.sas} buffer.
530 @example
531 @wkbd{M-x SAS}
532 @end example
533 Four buffers will appear on screen:
534 @multitable {buffer-names} {long-mode-names} {much-much-much-much-longer-description}
535 @item
536 Buffer               @tab Mode                   @tab Description
537 @item
538 @file{@var{foo}.sas} @tab @code{@ESS{[SAS]}}        @tab your source file
539 @item
540 @file{*SAS:1*}       @tab @code{@iESS{[SAS:1]}}     @tab @iESS{} communication buffer
541 @item
542 @file{*SAS:1.log*}   @tab @code{Shell ESStr []}  @tab @SAS{} log information
543 @item
544 @file{*SAS:1.lst*}   @tab @code{Shell ESSlst []} @tab @SAS{} listing information
545 @end multitable
546 If you would prefer each of the four buffers to appear in its
547 own individual frame, you can arrange for that.  Place the
548 cursor in the buffer displaying @file{@var{foo}.sas}.  Enter the
549 sequence @wkbd{C-c C-w}. The cursor will normally be in buffer
550 @file{@var{foo}.sas}.  If not, put it there and @wkbd{C-x b @var{foo}.sas}.
552 Send regions, lines, or the entire file contents to @SAS{}
553 (regions are most useful:  a highlighted region will normally
554 begin with the keywords @code{DATA} or @code{PROC} and end with
555 @code{RUN;}), @wkbd{C-c C-r}.
557 Information appears in the log buffer, analysis results in the
558 listing buffer.  In case of errors, make the corrections in the
559 @file{@var{foo}.sas} buffer and resubmit with another @wkbd{C-c C-r}.
561 At the end of the session you may save the log and listing
562 buffers with the usual @wkbd{C-x C-s} commands.  You will be prompted
563 for a file name.  Typically, the names @file{@var{foo}.log} and @file{@var{foo}.lst}
564 will be used.  You will almost certainly want to edit the saved
565 files before including them in a report.  The files are
566 read-only by default.  You can make them writable by the emacs
567 command @wkbd{C-x C-q}.
569 At the end of the session, the input file @file{@var{foo}.sas} will
570 typically have been revised.  You can save it.  It can be used
571 later as the beginning of another @iESS{[SAS]} session.  It can
572 also be used as a batch input file to @SAS{}.
574 The @file{*SAS:1*} buffer is strictly for @ESS{} use.  The user should
575 never need to read it or write to it.  Refer to the @file{.lst} and
576 @file{.log} buffers for monitoring output!
578 Troubleshooting: @xref{iESS(SAS)--Common problems}.
580 @comment  node-name,  next,  previous,  up
581 @node   iESS(SAS)--Common problems, ESS(SAS)--Graphics, iESS(SAS)--Interactive SAS processes, ESS for SAS
582 @section iESS(SAS)--Common problems
584 @enumerate
585 @item
586 @iESS{[SAS]} does not work on Windows.  In order to run @SAS{} inside
587 an emacs buffer, it is necessary to start @SAS{} with the @code{-stdio} option.
588 @SAS{} does not support the @code{-stdio} option on Windows.
589 @item
590 If @wkbd{M-x SAS} gives errors upon startup, check the following:
591 @itemize @bullet
592 @item
593 you are running Windows:  see 1.
594 @item
595 @file{ess-sas-sh-command} (from the @ESS{} @file{etc} directory) needs to be
596 executable; too check, type @wkbd{M-x dired}; if not, fix it as follows,
597 type @kbd{M-:}, then at the minibuffer prompt @wsamp{Eval:},
598 type @code{(set-file-modes "ess-sas-sh-command" 493)}.
599 @c (solution: @code{chmod ugo+rx ess-sas-sh-command}).
600 @item
601 @code{sas} isn't in your executable path; to verify, type
602 @kbd{M-:} and at the minibuffer prompt @samp{Eval:}, type
603 @code{(executable-find "sas")}
604 @end itemize
605 @item
606 @wkbd{M-x SAS} starts @w{@SAS{} Display} Manager.  Probably, the command @code{sas}
607 on your system calls a shell script.  In that case you will need to locate
608 the real  @code{sas} executable and link to it.
609 You can execute the @UNIX{} command:
610 @example
611 find / -name sas -print
612 @end example
613 Now place a soft link to the real @code{sas} executable in your @code{~/bin}
614 directory, with for example
615 @example
616 cd ~/bin
617 ln -s /usr/local/sas9/sas sas
618 @end example
619 @end enumerate
620 Check your @code{PATH} environment variable to confirm that
621 @code{~/bin} appears before the directory in which the @code{sas}
622 shell script appears.
624 @comment Specify the path to the real
625 @comment @code{sas} executable in @file{ess-sas-sh-command}, i.e.:
626 @comment @example
627 @comment /usr/local/sas9/sas $@@ </dev/tty 1>$stdout 2>$stderr
628 @comment @end example
629 @comment    To find the @code{sas} executable, you can execute the @UNIX{} command:
630 @comment @example
631 @comment find / -name sas -print
632 @comment @end example
633 @comment @end enumerate
635 @comment  node-name,  next,  previous,  up
636 @node   ESS(SAS)--Graphics, ESS(SAS)--Windows, iESS(SAS)--Common problems, ESS for SAS
637 @section ESS(SAS)--Graphics
639 Output from a @SAS{/GRAPH} @code{PROC} can be displayed in a @SAS{/GRAPH}
640 window for @SAS{} batch on Windows or for both @SAS{} batch and interactive
641 with XWindows on @UNIX{}.  If you need to create graphics files and view
642 them with @key{F12}, then include the following (either in
643 @file{@var{foo}.sas} or in @file{~/autoexec.sas}):
644 @example
645 filename gsasfile 'graphics.ps';
646 goptions device=ps gsfname=gsasfile gsfmode=append;
647 @end example
648 @code{PROC PLOT} graphs can be viewed in the listing buffer.  You may
649 wish to control the vertical spacing to allow the entire plot
650 to be visible on screen, for example:
651 @example
652 proc plot;
653     plot a*b / vpos=25;
654 run;
655 @end example
657 @comment  node-name,  next,  previous,  up
658 @node   ESS(SAS)--Windows,  , ESS(SAS)--Graphics, ESS for SAS
659 @section ESS(SAS)--Windows
661 @itemize @bullet
662 @item
663 @iESS{[SAS]} does not work on Windows.  @xref{iESS(SAS)--Common problems}.
665 @item
666 @ESS{[SAS]} mode for editing @SAS{} language files works very well.
667 @xref{ESS(SAS)--Editing files}.
669 @item
670 There are two execution options for @SAS{} on Windows.
671 You can use batch.  @xref{ESS(SAS)--Batch SAS processes}.
673 Or you can mark regions with the mouse and submit the code with
674 `submit-region' or paste them into @SAS{} Display Manager.
676 @end itemize
678 @comment Local Variables:
679 @comment TeX-master: "ess.texi"
680 @comment End: