This is ess.info, produced by makeinfo version 4.0 from ess.texi. START-INFO-DIR-ENTRY * ESS: (ess). Emacs Speaks Statistics (S/S+/R, SAS, BUGS, Stata, XLisp-Stat). END-INFO-DIR-ENTRY ESS -- Emacs Speaks Statistics ****************************** Currently maintained by A.J. (Tony) Rossini, Richard M. Heiberger, Kurt Hornik, Martin Maechler, and Rodney A. Sparapani. This file documents `ESS', a GNU Emacs package for running `S(plus)', `R', `XLisp-Stat', `SAS' and potentially any other interactive `statistical' languages in an `inferior' buffer, editing source code in these languages and interacting with the running program. This documentation relates to Version 5.1.21 of `ESS'. Original Info Author: David M. Smith (), Department of Mathematics and Statistics, Lancaster University, UK. Current Info Author: A.J. Rossini (), Department of Biostatistics, University of Washington, Seattle, WA 98185, USA  File: ess.info, Node: ESS(S)--Editing files, Next: iESS(S)--Inferior ESS processes, Up: Help for the S family ESS[S]-Editing files ==================== ESS[S] is the mode for editing S language files. This mode handles: - 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, an S function, or a single line to an inferior S process, if one is currently running. - ability to switch between processes which would be the target of the buffer (for the above). - The ability to request help from an S process for variables and functions, and to have the results sent into a separate buffer. - completion of object names and file names. ESS[S] mode should be automatically turned on when loading a file with the suffices found in ess-site (*.R, *.S, *.s, etc). However, one will have to start up an inferior process to take advantage of the interactive features.  File: ess.info, Node: iESS(S)--Inferior ESS processes, Next: Handling and Reusing Transcripts, Prev: ESS(S)--Editing files, Up: Help for the S family iESS[S]-Inferior ESS processes ============================== iESS (inferior ESS) is the mode for interfacing with active statistical processes (programs). This mode handles: - proper indenting, generated by both [Tab] and [Return]. - color and font highlighting based on syntax. - ability to resubmit the contents of a multi-line command to the executing process with a single keystroke [RET]. - The ability to request help from the current process for variables and functions, and to have the results sent into a separate buffer. - completion of object names and file names. - interactive history mechanism - transcript recording and editing To start up iESS mode, use: M-x S+3 M-x S4 M-x R (for S-PLUS 3.x, S4, and R, respectively. This assumes that you have access to each). Usually the site will have defined one of these programs (by default S+3) to the simpler name: M-x S Note that R has some extremely useful command line arguments, -v and -n. To enter these, call R using a "prefix argument", by C-u M-x R and when ESS prompts for "Starting Args ? ", enter (for example): -v 10000 -n 5000 Then that R process will be started up using "R -v 10000 -n 5000". New for ESS 5.1.2 (and later): "S-elsewhere" command The idea of "M-x S-elsewhere" is that we open a telnet (or rlogin) to another machine, call the buffer "*S-elsewhere*", and then run S on the other machine in that buffer. We do that by defining "sh" as the inferior-S-elsewhere-program-name. Emacs sets it up in a "*S-elsewhere*" iESS buffer. The user does a telnet or login from that buffer to the other machine and then starts S on the other machine. The usual C-c C-n commands from myfile.s on the local machine get sent through the buffer "*S-elsewhere*" to be executed by S on the other machine.  File: ess.info, Node: Handling and Reusing Transcripts, Next: ESS-help--assistance with viewing help, Prev: iESS(S)--Inferior ESS processes, Up: Help for the S family Handling and Reusing Transcripts ================================ - edit transcript - color and font highlighting based on syntax. - resubmit multi-line commands to an active process buffer - The ability to request help from an S process for variables and functions, and to have the results sent into a separate buffer. - ability to switch between processes which would be the target of the buffer (for the above).  File: ess.info, Node: ESS-help--assistance with viewing help, Next: Philosophies for using ESS(S), Prev: Handling and Reusing Transcripts, Up: Help for the S family ESS-help-assistance with viewing help ===================================== * move between help sections * send examples to S for evaluation  File: ess.info, Node: Philosophies for using ESS(S), Next: Scenarios for use (possibilities--based on actual usage), Prev: ESS-help--assistance with viewing help, Up: Help for the S family Philosophies for using ESS[S] ============================= The first is preferred, and configured for. The second one can be retrieved again, by changing emacs variables. 1: (preferred by the current group of developers): The source code is real. The objects are realizations of the source code. Source for EVERY user modified object is placed in a particular directory or directories, for later editing and retrieval. 2: (older version): S objects are real. Source code is a temporary realization of the objects. Dumped buffers should not be saved. _We_strongly_discourage_this_approach_. However, if you insist, add the following lines to your .emacs file (GNU emacs uses the filename `~/.emacs' and Xemacs uses the filename `~/.xemacs/init.el' for the initialization file): (setq ess-keep-dump-files 'nil) (setq ess-delete-dump-files t) (setq ess-mode-silently-save nil) The second saves a small amount of disk space. The first allows for better portability as well as external version control for code.  File: ess.info, Node: Scenarios for use (possibilities--based on actual usage), Next: Customization Examples and Solutions to Problems, Prev: Philosophies for using ESS(S), Up: Help for the S family Scenarios for use (possibilities-based on actual usage) ======================================================= We present some basic suggestions for using ESS to interact with S. These are just a subset of approaches, many better approaches are possible. Contributions of examples of how you work with ESS are appreciated (especially since it helps us determine priorities on future enhancements)! (comments as to what should be happening are prefixed by "##"). 1: ## Data Analysis Example (source code is real) ## Load the file you want to work with C-x C-f myfile.s ## Edit as appropriate, and then start up S-PLUS 3.x M-x S+3 ## A new buffer *S+3:1* will appear. Splus will have been started ## in this buffer. The buffer is in iESS [S+3:1] mode. ## Split the screen and go back to the file editing buffer. C-x 2 C-x b myfile.s ## Send regions, lines, or the entire file contents to S-PLUS. For regions, ## highlight a region with keystrokes or mouse and then send with: C-c C-r ## Re-edit myfile.s as necessary to correct any difficulties. Add ## new commands here. Send them to S by region with C-c C-r, or ## one line at a time with C-c C-n. ## Save the revised myfile.s with C-x C-s. ## Save the entire *S+3:1* interaction buffer with C-c C-s. You ## will be prompted for a file name. The recommended name is ## myfile.St. With the *.St suffix, the file will come up in ESS ## Transcript mode the next time it is accessed from Emacs. 2: ## Program revision example (source code is real) ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) M-x S+3 ## Load the file you want to work with C-x C-f myfile.s ## edit program, functions, and code in myfile.s, and send revised ## functions to S when ready with C-c C-f ## or highlighted regions with C-c C-r ## or individual lines with C-c C-n ## or load the entire buffer with C-c C-l ## save the revised myfile.s when you have finished C-c C-s 3: ## Program revision example (S object is real) ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) M-x S+3 ## Dump an existing S object my.function into a buffer to work with C-c C-d my.function ## a new buffer named yourloginname.my.function.S will be created with ## an editable copy of the object. The buffer is associated with the ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not ## exist after you log off. ## enter program, functions, and code into work buffer, and send ## entire contents to S-PLUS when ready C-c C-b ## Go to *S+3:1* buffer, which is the process buffer, and examine ## the results. C-c C-y ## The sequence C-c C-y is a shortcut for: C-x b *S+3:1* ## Return to the work buffer (may/may not be prefixed) C-x C-b yourloginname.my.function.S ## Fix the function that didn't work, and resubmit by placing the ## cursor somewhere in the function and C-c C-f ## Or you could've selected a region (using the mouse, or keyboard ## via setting point/mark) and C-c C-r ## Or you could step through, line by line, using C-c C-n ## Or just send a single line (without moving to the next) using C-c C-j ## To fix that error in syntax for the "rchisq" command, get help ## by C-c C-v rchisq 4: Data Analysis (S object is real) ## Start up S-PLUS 3.x, in a process buffer (this will be *S+3:1*) M-x S+3 ## Work in the process buffer. When you find an object that needs ## to be changed (this could be a data frame, or a variable, or a ## function), dump it to a buffer: C-c C-d my.cool.function ## Edit the function as appropriate, and dump back in to the ## process buffer C-c C-b ## Return to the S-PLUS process buffer C-c C-y ## Continue working. ## When you need help, use C-c C-v rchisq ## instead of entering: help("rchisq")  File: ess.info, Node: Customization Examples and Solutions to Problems, Prev: Scenarios for use (possibilities--based on actual usage), Up: Help for the S family Customization Examples and Solutions to Problems ================================================ 1. Suppose that you are primarily an SPLUS 3.4 user, occasionally using S version 4, and sick and tired of the buffer-name *S+3* we've stuck you with. Simply edit the "ess-dialect" alist entry in the essd-s+3.el and essd-s4.el files to be "S" instead of "S4" and "S+3". This will insure that all the inferior process buffer names are "*S*". 2. Suppose that you WANT to have the first buffer name indexed by ":1", in the same manner as your S-PLUS processes 2,3,4, and 5 (for you heavy simulation people). Then uncomment the line in ess-site (or add after your (require 'ess-site) or (load "ess-site") command in your .emacs file, the line: (setq ess-plain-first-buffername nil) ) 3. Fontlocking sometimes fails to behave nicely upon errors. When Splus dumps, a mis-matched " (double-quote) can result in the wrong font-lock face being used for the remainder of the buffer. Solution: add a " at the end of the "Dumped..." statement, to revert the font-lock face back to normal.  File: ess.info, Node: Help for SAS, Prev: Help for the S family, Up: Help for Statistical Packages Help for SAS ************ * Menu: * ESS(SAS)--Design philosophy:: * ESS(SAS)--Recommended autoexec:: * ESS(SAS)--Editing files:: * iESS(SAS)--Inferior ESS processes:: * ESS(SAS)--Batch processes:: * ESS(SAS)--Function keys for batch processing:: * ESS(SAS)--TAB key:: * ESS(SAS)--Usage scenarios:: * ESS(SAS)--Common problems:: * ESS(SAS)--MS Windows:: ESS[SAS] (originally SAS-mode) was designed for use with SAS. SAS-mode was developed by Cook . Those editing features and new advanced features are part of ESS[SAS]. The user interface of ESS[SAS] has similarities with ESS[S], the ESS interface for S, and to the SAS Display Manager. By _emacs_ we mean either GNU Emacs from the Free Software Foundation or XEmacs from the XEmacs Project.  File: ess.info, Node: ESS(SAS)--Design philosophy, Next: ESS(SAS)--Recommended autoexec, Prev: Help for SAS, Up: Help for SAS ESS[SAS]-Design philosophy ========================== ESS[SAS] mode was designed to aid the user in writing and maintaining input command files, such as myfile.sas, for SAS. These are files containing SAS statements. In a batch environment such files would be submitted to SAS by the operating system command: sas myfile.sas In a SAS window environment, these files would be brought into the "SAS: PROGRAM EDITOR" window and then submitted with the 'Local' 'Submit' menu commands. 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 window environment. 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 window environment. 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] mode 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. The ESS[SAS] mode was written with two primary goals. 1. Using the emacs environment is desirable for users accessing a remote computer via a network or dial-up who can not use the native SAS window environment. 2. Using the emacs environment is desirable for local users as well due to the inherent efficiency of using the same superior interface all of the time.  File: ess.info, Node: ESS(SAS)--Recommended autoexec, Next: ESS(SAS)--Editing files, Prev: ESS(SAS)--Design philosophy, Up: Help for SAS ESS[SAS]-Recommended autoexec.sas ================================= The default settings of the inferior-SAS-args in essd-sas.el are -stdio -linesize 80 -noovp -nosyntaxcheck with the interpretations: -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 In addition there are several parameters that can't be set in the command line. For these, we recommend the following line appear in your autoexec.sas in your home directory: options noovp pagesize=60 linesize=80 formdlim=' '; Interpretations noovp prevents error messages from printing 3 time pagesize=60 standard printed page length instead of window length linesize=80 keeps output lines from folding on standard terminals formdlim=' ' blank replaces "C-l" formfeeds to prevent mostly empty pages The noovp and linesize=80 appear in both the inferior-SAS-args and in the autoexec.sas. The redundancy means that these options are in effect for both SAS interactive and batch jobs.  File: ess.info, Node: ESS(SAS)--Editing files, Next: iESS(SAS)--Inferior ESS processes, Prev: ESS(SAS)--Recommended autoexec, Up: Help for SAS ESS[SAS]-Editing files ====================== ESS[SAS] is the mode for editing SAS language files. This mode handles: - 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 inferior 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). ESS[SAS], the mode for editing SAS language files, is automatically turned on when editing a file with a ".sas" suffix (or other, if specified in ess-site). The batch processing keypress commands are enabled by default to use the same function keys that the SAS Display Manager uses. The interactive capabilities of ESS require you to start an inferior SAS process with M-x SAS (*Note iESS(SAS)--Inferior ESS processes::.) At this writing (5.1.21), the indenting and syntactic highlighting are usually correct.  File: ess.info, Node: iESS(SAS)--Inferior ESS processes, Next: ESS(SAS)--Batch processes, Prev: ESS(SAS)--Editing files, Up: Help for SAS iESS[SAS]-Inferior ESS processes ================================ iESS (inferior ESS) is the mode for interfacing with active statistical processes (programs). To start up iESS[SAS] mode, use: M-x SAS We plan to add - The ability to request help from a process for variables and functions, and to have the results sent into a separate buffer. - completion of object names and file names. MS Windows: *Note ESS(SAS)--MS Windows::.  File: ess.info, Node: ESS(SAS)--Batch processes, Next: ESS(SAS)--Function keys for batch processing, Prev: iESS(SAS)--Inferior ESS processes, Up: Help for SAS ESS[SAS]-Batch 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 bash for your shell rather than MS-DOS ('ms-dos). 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. However, if you are editing the file locally and transferring it back and forth with Kermit, you need some additional steps. First of all, start Kermit locally before remotely logging in. Execute the command ess-kermit-get. A local copy of the file will be created with the ess-kermit-prefix character prepended (the default is ":"). Also, note that the remote Kermit command is defined 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, you can set it in Local Variables: at the end of your program). 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 custom-ize): (setq ess-sas-submit-pre-command "nohup") ;'sh default (setq ess-sas-submit-post-command "-rsasuser &") ;'sh default (setq ess-sas-submit-command "/usr/local/sas/sas") ;'sh example (setq ess-sas-submit-pre-command "start") ;'ms-dos default (setq ess-sas-submit-post-command "-rsasuser -icon") ;'ms-dos default (setq ess-sas-submit-command "c:/progra~1/sas/sas.exe") ;Windows example (setq ess-sas-submit-command "c:\\progra~1\\sas\\sas.exe");Windows example There is a built-in delay before a batch SAS job is submitted when using a Unix shell under either Unix or 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 on any system. 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 (the default of 5 seconds is shown): (setq ess-sleep-for 5)  File: ess.info, Node: ESS(SAS)--Function keys for batch processing, Next: ESS(SAS)--TAB key, Prev: ESS(SAS)--Batch processes, Up: Help for SAS ESS[SAS]-Function keys for batch processing =========================================== The description of the setup for function keys for batch processing of SAS files is unavoidably more complex than we wish it were. The actual use of the function keys is simple. There are five distinct options: 1. (default) Function keys in ESS[SAS] modes do whatever they normally do in other emacs modes. Many users will have defined some of the keys [f2]-[f12] in their .emacs or _emacs file, or will have installation-wide definitions in their site-start.el file. By default, ESS does not override those definitions. This default is intended to make ESS[SAS] mode behave similarly to other emacs modes. 2,3,4,5. Users who are primarily familiar with SAS, and who are learning emacs as a way to approach SAS, will likely want to duplicate the function key capabilities that SAS Institute provides with its Display Manager. There are still options. 1. SAS provides different function key definitions with its PC and Unix products; ESS can use either. 2. The ESS[SAS] function key definitions can be active in all buffers (global) or limited (local) only to buffers that have SAS-related file extensions: .sas, .log, .lst, filetype-1 (which defaults to .txt), and filetype-2 which defaults to .dat. The distinction between local and global appears subtle. If you want the ESS[SAS] definitions to work when you are in *shell* or when editing files other than the file extensions that SAS recognizes, you will most likely want to use the global definitions. If you want your function keys to understand SAS batch commands when you are editing SAS files, and to behave normally when editing other files, then you will choose the local definitions. The option can be chosen by the person installing ESS for a site or by an individual. 1. The site manager can uncomment only one of the following lines. ESS[SAS] Function keys are available in ESS[SAS] and related modes if you uncomment either of the following lines in your ess-site.el: ;;2; (setq ess-sas-local-unix-keys t) ;;3; (setq ess-sas-local-pc-keys t) ESS[SAS] Function keys are available in all emacs modes if you uncomment either of the following lines in your ess-site.el: ;;4; (setq ess-sas-global-unix-keys t) ;;5; (setq ess-sas-global-pc-keys t) The names -unix- and -pc- have nothing to do with the operating system that you are running. Rather they mimic the definitions that the SAS Display Manager uses by default on those platforms. 2. The option can be selected by an individual by adding a line to the .emacs (or _emacs) file, immediately following the (load "ess-site") line. If your site manager has chosen an option 2,3,4,5 you don't want, you must turn it off before selecting a different option. To turn off an option, add the appropriate line (uncommented) to your .emacs (_emacs) file. ;;2; (setq ess-sas-local-unix-keys nil) ;;3; (setq ess-sas-local-pc-keys nil) ;;4; (setq ess-sas-global-unix-keys nil) ;;5; (setq ess-sas-global-pc-keys nil) Finally, we get to what the function keys actually do. You may recognize some of the Short Names as SAS Display Manager commands (they are in all capitals). Unix PC Short Name Long 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 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. C-F3 C-F8 SUBMIT-REGION Write region to temporary file, and submit to SAS. F4 F5 PROGRAM switch buffer to .sas file. F5 F6 LOG switch buffer to .log file, `refresh' and goto next error message, if any. C-F5 C-F6 APPEND-TO-LOG Append ess-temp.log to the current .log file. F6 F7 OUTPUT switch buffer to .lst file and `refresh'. C-F6 C-F7 APPEND-TO-OUTPUT Append ess-temp.lst to the current .lst file. 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 Besides the keys that mimic SAS Display Manager commands, six other keys have been provided for convenience. `shell' switches you to the *shell* buffer where you can type operating system commands. This is especially helpful if you would like to kill a SAS batch job. F2 performs the `refresh' operation on the current buffer. `refresh' compares the buffer date/time stamp with the file date/time stamp 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 `filetype-2' are pressed. `filetype-1' switches you to a file with the same file root as your .sas file, but with a different extension; .txt by default. You can over-ride the default, by specifying a different extension in your .emacs file. For example, for `filetype-1': (setq ess-sas-suffix-1 "txt") `filetype-2' is similar, except it is .dat by default. 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 will take a long time to render. F12 will open a GSASFILE near point 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 two variables for your own situation: (setq ess-sas-graph-suffix-regexp "[.]\\(e?ps\\|gif\\|jpe?g\\|tiff?\\)") (setq ess-sas-image-viewer "kodakimg") ;; external viewer  File: ess.info, Node: ESS(SAS)--TAB key, Next: ESS(SAS)--Usage scenarios, Prev: ESS(SAS)--Function keys for batch processing, Up: Help for SAS ESS[SAS]-TAB key ================ Again, 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: ;;; (setq ess-sas-edit-keys-toggle 0) ESS provides an alternate behavior for the TAB key that makes it behave as it does on non-emacs terminals, i.e. move the cursor to the next tab stop. The alternate behavior also provides a backwards TAB key: C-TAB. This functionality is obtained by uncommenting the following line in ess-site.el: ;;; (setq ess-sas-edit-keys-toggle 1) Under the alternate behavior, the TAB key is bound to tab-to-tab-stop and the tab stops are set by default at multiples of 4.  File: ess.info, Node: ESS(SAS)--Usage scenarios, Next: ESS(SAS)--Common problems, Prev: ESS(SAS)--TAB key, Up: Help for SAS ESS[SAS]-Usage scenarios ======================== We present one scenario for using ESS to interact with SAS. Contributions of examples of how you work with ESS are appreciated (especially since it helps us determine priorities on future enhancements)! (comments as to what should be happening are prefixed by "##"). Batch SAS (-unix-keys illustrated, pc-keys in the comments) ## Find the file you want to work with C-x C-f myfile.sas ## myfile.sas will be in ESS[SAS] mode ## Edit as appropriate, then save and submit the batch SAS job. ## -pc- F8 F3 ## The job runs in the shell buffer while you continue to edit ## myfile.sas. If you are running a Unix shell under Unix or ## Windows, the message buffer will notify you with a shell ## notification when the job is complete. If so, then you ## will also have the option of terminating the batch job ## before it is finished. ## -pc- F3 F8 ## In any case, you may want to visit the .log while the process ## is still running (unix only) or when it is done and check for ## error messages ## (you will be taken to the next error message, if any). ## The .log will be refreshed and you will be placed in it's buffer. ## -pc- F6 F5 ## Now, refresh the .lst and go to it's buffer. ## -pc- F7 F6 ## If you wish to make changes, go to the .sas file with ## -pc- F5 F4 ## make your editing changes and then submit again. Interactive SAS ## Find the file you want to work with C-x C-f myfile.sas ## myfile.sas will be in ESS[SAS] mode ## Edit as appropriate, and then start up SAS with the cursor in ## the myfile.sas buffer M-x SAS ## Four buffers will appear on screen: ## myfile.sas in ESS[SAS] mode # your source file ## *SAS:1* in iESS [SAS:1] mode # ESS communication buffer ## *SAS:1.log* in Shell [] ESStr mode # SAS log information ## *SAS:1.lst* in Shell [] ESSlst mode # SAS listing information ## If you would prefer each of the four buffers to appear in its ## own individual frame, you can arrange for that. Place the ## cursor in the buffer displaying myfile.sas. Enter the ## sequence: C-c C-w ## The cursor will normally be in buffer myfile.sas. ## If not, put it there: C-x b myfile.sas ## Send regions, lines, or the entire file contents to SAS ## (regions are most useful). A highlighted region will normally ## begin with the keywords 'DATA' or 'PROC' and end with the ## keyword 'RUN;' C-c C-r ## Information appears in the log buffer, analysis results in the ## listing buffer. In case of errors, make the corrections in the ## myfile.sas buffer and resubmit with another C-c C-r ## PROC GPLOT graphs will normally be produced in a postscript ## file and be viewed later. Include the lines /* required gsoptions for batch files */ /* comment out these lines for interactive use on X-terminals*/ filename grafout 'temp.ps'; goptions device=ps gsfname=grafout gsfmode=append gaccess=sasgastd; ## in myfile.sas. ## 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, by proc plot; plot a*b / vpos=25; ## 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 mfile.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! Here is a typical myfile.sas: title 'Analysis of Case 0502'; data case0502; infile '/home/public/stat/Data/case0502.asc' firstobs=2; input percent code; run; proc glm; class code; model percent=code /ss1; run;  File: ess.info, Node: ESS(SAS)--Common problems, Next: ESS(SAS)--MS Windows, Prev: ESS(SAS)--Usage scenarios, Up: Help for SAS ESS[SAS]-Common problems ======================== 1. MS Windows users. - M-x SAS does not work on MS 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 weird errors upon startup, check the following: - you are running Windows: SAS does not support stdio on Windows - 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) - you need a copy of SAS (we can't solve this) 3. M-x SAS starts up SAS in the window system (motif, for example), instead of starting it up in the emacs buffers. Probably the unix command "sas" on your system calls a local script which in turn calls the sas executable. The fix is to call the sas executable directly. Change the line in ess-sas-sh command from: sas $stdout 2>$stderr $ to a call to the complete path name of the sas executable on your system, for example: /usr/local/sas612/sas $stdout 2>$stderr $ To find the complete path name on your system, you can execute the line (from the unix prompt): find / -name 'sas' -exec ls -ld {} \; and expect a response similar to the following -rwxr-xr-x 1 sas sas 2441216 Sep 9 1997 /usr/local/sas612/sas  File: ess.info, Node: ESS(SAS)--MS Windows, Prev: ESS(SAS)--Common problems, Up: Help for SAS ESS[SAS]-MS Windows =================== * `M-x SAS' does not work on MS 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. * ESS[SAS] mode for editing SAS language files works very well. *Note ESS(SAS)--Editing files::. * There are two execution options for SAS on Windows. You can use batch *Note ESS(SAS)--Batch processes::. You do not get interactive graphics this way. Or you can pick up marked regions with the mouse and drop them into the SAS editor and then submit them for processing. This gives you complete access to the SAS windowing system, including interactive graphics.  File: ess.info, Node: Installation, Next: Customization, Prev: Help for Statistical Packages, Up: Top Installing ESS on your system ***************************** The following section details those steps necessary to get ESS running on your system. * Menu: * Unix installation:: Installing ESS on your Unix system * Microsoft Windows installation:: Installing ESS on your MS Windows system * System dependent:: Other variables you may need to change We now discuss installation, which might happen under Unix or Microsoft Windows. First, we discuss Unix installation. *Note Unix installation::. For Microsoft Windows Installation please skip to the *Note Microsoft Windows installation::.  File: ess.info, Node: Unix installation, Next: Microsoft Windows installation, Up: Installation Unix installation ================= 1. cd to a directory where you keep emacs lisp files, or create a new directory to hold the distribution. This directory will be referred to below as "the ESS distribution directory". It will contain, at the end, the tar file `ess-5.1.21.tar.gz', and a directory for the ESS source, which will be termed "the ESS-5.1.21 source directory". Note that the .elc files may be installed elsewhere (as specified in the Makefile) if desired. 2. Retrieve the gzipped tar file or zipped file from 3. Copy `ess-5.1.21.tar.gz' to the location where you want the ESS-5.1.21 directory, and cd there. Extract the files from the distribution, which will unpack into a subdirectory, ess-5.1.21. gunzip ess-5.1.21.tar.gz tar vxf ess-5.1.21.tar (or: `gunzip < ess-5.1.21.tar.gz | tar vxf -' ). (or using GNU tar: `tar zvxf ess-5.1.21.tar.gz'). The `tar' command will extract files into the current directory. Do not create ess-5.1.21 yourself, or you will get an extra level of depth to your directory structure. Note if you have a very ancient version of GNU emacs (_and_ really can not upgrade to Emacs 20 or higher!) you can unpack the `lisp/19.29.tar.gz' file, read the ensuing `lisp/19.29/README' and you may succeed... 4. Edit the file `lisp/ess-site.el' as explained in the comments section of that file. Installations that are using ESS only for S-Plus 6.x will probably not need to make any changes. Installations that also have one or more of (S+5 S4 S+4 S+3 R SAS XLispStat Stata) may need to uncomment corresponding lines in `ess-site.el'. 5. READ THIS ITEM THOROUGHLY BEFORE STARTING: In the ess-5.1.21 directory, edit the file `Makeconf' (only if you want to place the executables in other locations; see LISPDIR and INFODIR) and then type: make If this works, then you might try: make install Note that the latter does the former as well, so if you are feeling lucky, you might want to skip it. This will install the info files (and the lisp files, if they are to go in another directory). Don't forget to edit the file `dir' in the info directory specified by `INFODIR' in `doc/Makefile'. See the sample `dir' file for an example of the line to add. If you are using XEmacs, you might do: make EMACS=xemacs and then make EMACS=xemacs install instead of editing the Makefile. _Note_ that you might need to use GNU make for everything to work properly An alternative, if you are running XEmacs and have access to the XEmacs system directories, would be to place the directory in the site-lisp directory, and simply type `make' (and copy the documentation as appropriate). For Emacs, you would still have to move the files into the top level site-lisp directory. 6. Add the line (load "/PATH/ess-site") to your .emacs file (or default.el or site-init.el, for a site-wide installation). Replace `/PATH' above with the value of ess-lisp-directory as defined in ess-site.el. (GNU emacs uses the filename `~/.emacs' and Xemacs uses the filename `~/.xemacs/init.el' for the initialization file.) Alternatively, if ess-site.el is in your current Lisp path, you can do: (require 'ess-site) to configure Emacs for ESS. 7. (OPTIONAL) If you are running S-PLUS or R, you might consider installing the database files. From within (X)Emacs, `C-x d' to the directory containing ESS. Now: M-x S+6 get running. once you have reached the SPLUS prompt, do: M-x ess-create-object-name-db (this will create the file `ess-s+6-namedb.el'; if it isn't in the ESS directory, move it there). Then, completions will be autoloaded and will not be regenerated for every session. For R, do the same, using M-x R and then `M-x ess-create-object-name-db' creating `ess-r-namedb.el'; if it isn't in the ESS directory, move it there). 8. For more information on using ESS in your daily work, see the files README.S, README.SAS, and README.XLispStat. For the impatient, the quick version of usage follows: 9. To edit statistical programs, load the files with the requiste extensions (".sas" for SAS, ".S" for S-PLUS, ".R" for R, and ".lsp" for XLispStat). 10. To run statistical processes under (X)Emacs: Run S-PLUS 6.x with: M-x S+6 (or M-x S using backwards compatibility). You will then be asked for a pathname ("S starting data directory?"), from which to start the process. If you wish to run R, you can start it with: M-x R XLispStat can be run with M-x XLS An interactive SAS can be run in an `iESS[SAS]' buffer with: M-x SAS This works when SAS is running on a Unix machine, either the local machine or over a network connection. M-x SAS does not work when SAS is running on a Windows machine. 11. That's it!  File: ess.info, Node: Microsoft Windows installation, Prev: Unix installation, Up: Installation Microsoft Windows installation ============================== For Microsoft Windows installation, please follow the next steps: (see separate instructions above for UNIX *Note Unix installation::. 1. cd to a directory where you keep emacs lisp files, or create a new directory (for example, `c:\emacs\') to hold the distribution. This directory will be referred to below as "the ESS distribution directory". It will contain, at the end, either the tar file `ess-5.1.21.tar.gz' or the zip file `ess-5.1.21.zip', and a directory for the ESS source, which will be termed "the ESS-5.1.21 source directory". 2. Retrieve the compressed tar file `ess-5.1.21.tar.gz' or the zipped file `ess-5.1.21.zip' from one of the FTP or WWW archive sites via FTP (or HTTP). Be aware that http browsers on Windows frequently change the "." and "-" characters in filenames to other punctuation. Please change the names back to their original form. 3. Copy `ess-5.1.21.tar.gz' to the location where you want the ess-5.1.21 directory, for example to `c:\emacs\ess-5.1.21.tar.gz', and cd there. For example, cd c:\emacs Extract the files from the distribution, which will unpack into a subdirectory, `ess-5.1.21'. gunzip ess-5.1.21.tar.gz tar vxf ess-5.1.21.tar (or: `gunzip < ess-5.1.21.tar.gz | tar vxf -' ). (or: from the zip file: `unzip ess-5.1.21.zip') The `tar' command will extract files into the current directory. Do not create `ess-5.1.21' yourself, or you will get an extra level of depth to your directory structure. 4. Windows users will usually be able to use the `lisp/ess-site.el' as distributed. Only rarely will changes be needed. 5. Windows users will need to make sure that the directories for the software they will be using is in the PATH environment variable. On Windows 9x, add lines similar to the following to your `c:\autoexec.bat' file: path=%PATH%;c:\progra~1\spls2000\cmd On Windows NT/2000, add the directories to the PATH using the MyComputer menu. Note that the directory containing the program is added to the PATH, not the program itself. One such line is needed for each software program. Be sure to use the abbreviation `progra~1' and not the long version with embedded blanks. Use backslashes "\". 6. Add the line (load "/PATH/ess-site") to your .emacs (or _emacs) file (or default.el or site-init.el, for a site-wide installation). Replace `/PATH' above with the value of ess-lisp-directory as defined in `ess-site.el'. Use forwardslashes `/'. (GNU emacs uses the filename `~/.emacs' and Xemacs uses the filename `~/.xemacs/init.el' for the initialization file.) 7. (OPTIONAL) If you are running Sqpe or R, you might consider installing the database files. From within (X)Emacs, `C-x d' to the directory containing ESS. Now: M-x Sqpe+6 (get running. once you have reached the SPLUS prompt, do:) M-x ess-create-object-name-db (this will create the file `ess-s+6-namedb.el'; if it isn't in the ESS directory, move it there). Then, completions will be autoloaded and will not be regenerated for every session. For R, do the same, using M-x R and then `M-x ess-create-object-name-db' creating `ess-r-namedb.el'; if it isn't in the ESS directory, move it there). 8. For more information on using ESS in your daily work, see the files doc/README.SPLUS4WIN, doc/README.S, doc/README.SAS, and doc/README.XLispStat. For the impatient, the quick version of usage follows: 9. To edit statistical programs, load the files with the requisite extensions (".sas" for SAS, ".S" or "s" or "q" or "Q" for S-PLUS, ".r" or ".R" for R, and ".lsp" for XLispStat). 10. To run statistical processes under (X)Emacs: Run S-PLUS 6.x or 2000 with: M-x S+6 (or `M-x S'). You will then be asked for a pathname ("S starting data directory?"), from which to start the process. The prompt will propose your current directory as the default. Similarly for S-PLUS 6.x. Send lines or regions from the emacs buffer containing your S program (for example, `myfile.s') to the S-Plus Commands Window with the `C-c C-n' or `C-c C-r' keys. Run S-PLUS 6.x or 2000 inside an emacs buffer M-x Sqpe+6 You will then be asked for a pathname ("S starting data directory?"), from which to start the process. The prompt will propose your current directory as the default. Similarly for S-PLUS 6.x. Send lines or regions from the emacs buffer containing your S program (for example, `myfile.s') to the *S+6* buffer with the `C-c C-n' or `C-c C-r' keys. You do not have access to interactive graphics in this mode. You get Unix-like behavior, in particular the entire transcript is available for emacs-style search commands. If you wish to run R, you can start it with: M-x R XLispStat can not currently be run with M-x XLS Hopefully, this will change. However, you can still edit with Emacs, and cut and paste the results into the XLispStat *Listener* Window under Microsoft Windows. SAS for Windows uses the batch access with function keys that is described in `doc/README.SAS'. The user can also edit SAS files in an `ESS[SAS]' buffer and than manually copy and paste them into an Editor window in the SAS Display Manager. For Windows, inferior SAS in an `iESS[SAS]' buffer does not work on the local machine. It does work over a network connection to SAS running on a remote Unix computer. Reason: we use ddeclient to interface with programs and SAS doesn't provide the corresponding ddeserver capability. 11. That's it!