This is ess.info, produced by makeinfo version 4.2 from ess.texi. ESS -- Emacs Speaks Statistics ****************************** START-INFO-DIR-ENTRY * ESS: (ess). Emacs Speaks Statistics (S/S+/R, SAS, BUGS, Stata, XLisp-Stat). END-INFO-DIR-ENTRY  File: ess.info, Node: S+elsewhere and ESS-elsewhere, Prev: ESS processes on Remote Computers, Up: ESS processes on Remote Computers S+elsewhere and ESS-elsewhere ============================= These commands are now deprecated. We recommend `ess-remote'. We have two versions of the elsewhere function. `S+elsewhere' is specific for the S-Plus program. The more general function `ESS-elsewhere' is not as stable. 1. Enter `M-x S+elsewhere'. You will be prompted for a starting directory. I usually give it my project directory on the local machine, say `~myname/myproject/' Or enter `M-x ESS-elsewhere'. You will be prompted for an ESS program and for a starting directory. I usually give it my project directory on the local machine, say `~myname/myproject/' 2. The `*S+3*' buffer will appear with a prompt from the local operating system (the unix prompt on a unix workstation or with cygwin bash on a PC, or the msdos prompt on a PC without bash). emacs may freeze because the cursor is at the wrong place. Unfreeze it with `C-g' then move the cursor to the end with `M->'. With `S+elsewhere' the buffer name is based on the name of the ESS program. 3. Enter `telnet myname@other.machine' (or `ssh myname@other.machine'). You will be prompted for your password on the remote machine. Use `M-x send-invisible' before typing the password itself. 4. Before starting the ESS process, type `stty -echo nl' at the unix prompt. The `-echo' turns off the echo, the `nl' turns off the newline that you see as `^M'. 5. You are now talking to the unix prompt on the other machine in the `*S+3*' buffer. cd into the directory for the current project and start the ESS process by entering `Splus' or `R' or `sas -stdio' as appropriate. If you can login remotely to your Windows 2000, then you should be able to run `Sqpe' on the Windows machine. I haven't tested this and noone has reported their tests to me. You will not be able to run the GUI through this text-only connection. 6. Once you get the S or R or SAS prompt, then you are completely connected. All the `C-c C-n' and related commands work correctly in sending commands from `myfile.s' or `myfile.r' on the PC to the `*S+3*' buffer running the S or R or SAS program on the remote machine. 7. Graphics on the remote machine works fine. If you run the X window sysyem on the remote unix machine you should be able to display them in `xfree86' on your PC. If you don't run X11, then you can write graphics to the postscript device and copy it to your PC with dired and display it with ghostscript.  File: ess.info, Node: Customizing startup, Prev: ESS processes on Remote Computers, Up: Interactive ESS Changing the startup actions ============================ If you do not wish ESS to prompt for a starting directory when starting a new process, set the variable `ess-ask-for-ess-directory' to `nil'. In this case, the value of the variable `ess-directory' is used as the starting directory. The default value for this variable is your home directory. If `ess-ask-for-ess-directory' has a non-`nil' value (as it does by default) then the value of `ess-directory' provides the default when prompting for the starting directory. Incidentally, `ess-directory' is an ideal variable to set in `ess-pre-run-hook'. If you like to keep a record of your S sessions, set the variable `ess-ask-about-transfile' to `t', and you will be asked for a filename for the transcript before the ESS process starts. - User Option: ess-ask-about-transfile If non-`nil', as for a file name in which to save the session transcript. Enter the name of a file in which to save the transcript at the prompt. If the file doesn't exist it will be created (and you should give it a file name ending in `.St'); if the file already exists the transcript will be appended to the file. (Note: if you don't set this variable but you still want to save the transcript, you can still do it later -- *note Saving transcripts::.) Once these questions are answered (if they are asked at all) the S process itself is started by calling the program name specified in the variable `inferior-ess-program'. If you need to pass any arguments to this program, they may be specified in the variable `inferior-S_PROGRAM_NAME-args' (e.g. if `inferior-ess-program' is `"S+"' then the variable to set is `inferior-S+-args'. It is not normally necessary to pass arguments to the S program; in particular do not pass the `-e' option to `Splus', since ESS provides its own command history mechanism. By default, the new process will be displayed in another window in the current frame. If you wish your S process to appear in a separate variable, customize the variable `inferior-ess-own-frame'.  File: ess.info, Node: Help for the S family, Next: Help for SAS, Prev: Interactive ESS, Up: Top Help for the S family ********************* * Menu: * ESS(S)--Editing files:: * iESS(S)--Inferior ESS processes:: * Handling and Reusing Transcripts:: * ESS-help--assistance with viewing help:: * Philosophies for using ESS(S):: * Scenarios for use (possibilities--based on actual usage):: * Customization Examples and Solutions to Problems::  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. For example, `--vanilla' will ensure R starts up without loading in any init files. To enter a command line argument, call R using a "prefix argument", by C-u M-x R and when ESS prompts for "Starting Args ? ", enter (for example): `--vanilla' Then that R process will be started up using `R --vanilla'. Menubar access to other versions of R and Sqpe If you have other versions of R or S-Plus available on the system, ESS is also able to start those versions. R on Unix systems: If you have "R-1.8.1" on your `exec-path', it can be started using `M-x R-1.8.1'. By default, ESS will find versions of R beginning "R-1" or "R-2". If your versions of R are called other names, consider renaming them with a symbolic link or change the variable `ess-r-versions'. To see which defuns have been created for starting different versions of R, type `M-x R-' and then hit [Tab]. You will then see if any defuns for particular versions of R have been created. These other versions of R can also be started from the "ESS / Start Process / Other" menu. R on Windows systems: If you have "rw1081" on your `exec-path', it can be started using `M-x rw1081'. By default, ESS will find versions of R located in directories parallel to the version of R in your `PATH'. If your versions of R are called other names, you will need to change the variable `ess-rterm-versions'. To see which defuns have been created for starting different versions of R, type `M-x rw' and then hit [Tab]. You will then see if any defuns for particular versions of R have been created. These other versions of R can also be started from the "ESS / Start Process / Other" menu. Sqpe (S-Plus running inside an emacs buffer) on Windows systems: If you have an older version of S-Plus (S-Plus 6.1 for example) on your system, ir can be started inside an emacs buffer with `M-x splus61'. By default, ESS will find versions of S-Plus located in the installation directories that Insightful uses by default. If your versions of S-Plus are anywhere else, you will need to change the variable `ess-SHOME-versions'. To see which defuns have been created for starting different versions of S-Plus, type `M-x spl' and then hit [Tab]. You will then see if any defuns for particular versions of S-Plus have been created. These other versions of S-Plus can also be started from the "ESS / Start Process / Other" menu. 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 ===================================== ESS has built-in facilities for viewing help files from S. *Note Help::.  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: (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-sp3.el and essd-s4.el files to be "S" instead of "S4" and "S+3". This will ensure 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, Next: Help for BUGS, Prev: Help for the S family, Up: Top Help for SAS ************ * Menu: * ESS(SAS)--Design philosophy:: * ESS(SAS)--Editing files:: * iESS(SAS)--Interactive SAS processes:: * ESS(SAS)--Batch SAS processes:: * ESS(SAS)--Function keys for batch processing:: * ESS(SAS)--TAB key:: * ESS(SAS)--Usage scenarios:: * iESS(SAS)--Common problems:: * ESS(SAS)--MS Windows:: ESS[SAS] was designed for use with SAS. It is descended from emacs macros developed by John Sall for editing SAS programs and SAS-mode by Tom Cook. Those editing features and new advanced features are part of ESS[SAS]. The user interface of ESS[SAS] has similarities with ESS[S] and the SAS Display Manager.  File: ess.info, Node: ESS(SAS)--Design philosophy, Next: ESS(SAS)--Editing files, Prev: Help for SAS, Up: Help for SAS ESS[SAS]-Design philosophy ========================== ESS[SAS] was designed to aid the user in writing and maintaining SAS programs, such as myfile.sas. Both interactive and batch submission of SAS programs is supported. ESS[SAS] was written with two primary goals. 1. The emacs text editor provides a powerful and flexible development environment for programming languages. These features are a boon to all programmers and, with the help of ESS[SAS], to SAS users as well. 2. Although a departure from SAS Display Manager, ESS[SAS] provides similar key definitions to give novice ESS[SAS] users a head start. Also, inconvenient SAS Display Manager features, like remote submission and syntax highlighting, are provided transparently; appealing to advanced ESS[SAS] users.  File: ess.info, Node: ESS(SAS)--Editing files, Next: iESS(SAS)--Interactive SAS processes, Prev: ESS(SAS)--Design philosophy, 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 interactive SAS process. - ability to switch between processes which would be the target of the buffer (for the above). - ability to save and submit the file you are working on as a batch SAS process with a single keypress and to continue editing while it is runs in the background. - capability of killing the batch SAS process through the shell buffer or allow the SAS process to keep on running after you exit emacs. - single keypress navigation of .sas, .log and .lst files (.log and .lst files are automatically refreshed with each keypress). ESS[SAS] is automatically turned on when editing a file with a .sas suffix (or other extension, if specified via auto-mode-alist). The function keys can be enabled to use the same function keys that the SAS Display Manager does. The interactive capabilities of ESS require you to start an inferior SAS process with M-x SAS (*Note iESS(SAS)--Interactive SAS processes::.) At this writing, the indenting and syntax highlighting are generally correct. Known issues: for multiple line * or %* comments, only the first line is highlighted; for .log files, only the first line of a NOTE:, WARNING: or ERROR: message is highlighted; unmatched single/double quotes in CARDS data lines are NOT ignored; in a DO ... TO or a DO ... TO ... BY statement, TOs are not highlighted (and neither is BY).  File: ess.info, Node: iESS(SAS)--Interactive SAS processes, Next: ESS(SAS)--Batch SAS processes, Prev: ESS(SAS)--Editing files, Up: Help for SAS iESS[SAS]-Interactive SAS processes =================================== iESS (inferior ESS) is the method for interfacing with interactive statistical processes (programs). iESS[SAS] is what is needed for interactive SAS programming. iESS[SAS] works best with the following settings for SAS command-line options (the default of inferior-SAS-args): -stdio -linesize 80 -noovp -nosyntaxcheck -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 To start up iESS[SAS] mode, use: M-x SAS The *SAS:1.log* buffer in ESStr mode corresponds to the file myfile.log in SAS batch usage and to the "SAS: LOG" window in the SAS Display Manager. All commands submitted to SAS, informative messages, warnings, and errors appear here. The *SAS:1.lst* buffer in ESSlst mode corresponds to the file myfile.lst in SAS batch usage and to the "SAS: OUTPUT" window in the SAS Display Manager. All data related printed output from the PROCs appear in this window. The iESS [SAS:1] buffer exists solely as a communications buffer. Files are edited in the myfile.sas buffer. The C-c C-r key in ESS[SAS] is the functional equivalent of bringing a file into the "SAS: PROGRAM EDITOR" window followed by the 'Local' 'Submit' menu commands. The user should never use this buffer directly. Troubleshooting: *Note iESS(SAS)--Common problems::.  File: ess.info, Node: ESS(SAS)--Batch SAS processes, Next: ESS(SAS)--Function keys for batch processing, Prev: iESS(SAS)--Interactive SAS processes, Up: Help for SAS ESS[SAS]-Batch SAS processes ============================ Submission of a SAS batch job is dependent on your environment. ess-sas-submit-method is determined by your operating system and your shell. It defaults to 'sh unless you are running Windows or Mac Classic. Under Windows, it will default to 'sh if you are using a Unix-imitating shell; otherwise 'ms-dos for an MS-DOS shell. On Mac OS X, it will default to 'sh, but under Mac Classic AppleScript is used ('apple-script). You will also set this to 'sh if the SAS batch job needs to run on a remote machine rather than your local machine. This works transparently if you are editing the remote file via ange-ftp/EFS or tramp. Note that ess-sas-shell-buffer-remote-init is a Local Variable that defaults to "ssh" which will be used to open the buffer on the remote host and it is assumed that no password is necessary, i.e. you are using the equivalent of ssh-agent/ssh-add (see the discussion about Local Variables below if you need to change the default). However, if you are editing the file locally and transferring it back and forth with Kermit, you need some additional steps. First, start Kermit locally before remotely logging in. Open a local copy of the file with the ess-kermit-prefix character prepended (the default is "#"). Execute the command ess-kermit-get which automatically brings the contents of the remote file into your local copy. If you transfer files with Kermit manually in a shell buffer, then note that the Kermit escape sequence is C-q C-\ c rather than C-\ c which it would be in an ordinary terminal application, i.e. not in an emacs buffer. Lastly, note that the remote Kermit command is specified by ess-kermit-command. The command used by the SUBMIT function key (F3 or F8) to submit a batch SAS job, whether local or remote, is ess-sas-submit-command which defaults to sas-program. sas-program is "invoke SAS using program file" for Mac Classic and "sas" otherwise. However, you may have to alter ess-sas-submit-command for a particular program, so it is defined as buffer-local. Conveniently, it can be set at the end of the program: endsas; Local variables: ess-sas-submit-command: "sas8" End: The command line is also made of ess-sas-submit-pre-command, ess-sas-submit-post-command and ess-sas-submit-command-options (the last of which is also buffer-local). Here are some examples for your .emacs file (you may also use M-x customize-variable): ;'sh default (setq ess-sas-submit-pre-command "nohup") ;'sh default (setq ess-sas-submit-post-command "-rsasuser &") ;'sh example (setq-default ess-sas-submit-command "/usr/local/sas/sas") ;'ms-dos default (setq ess-sas-submit-pre-command "start") ;'ms-dos default (setq ess-sas-submit-post-command "-rsasuser -icon") ;Windows example (setq-default ess-sas-submit-command "c:/progra~1/sas/sas.exe") ;Windows example (setq-default ess-sas-submit-command "c:\\progra~1\\sas\\sas.exe") There is a built-in delay before a batch SAS job is submitted when using a Unix-imitating shell under Windows. This is necessary in many cases since the shell might not be ready to receive a command. This delay is currently set high enough so as not to be a problem. But, there may be cases when it needs to be set higher, or could be set much lower to speed things up. You can over-ride the default in your .emacs file by: (setq ess-sleep-for 0.2)  File: ess.info, Node: ESS(SAS)--Function keys for batch processing, Next: ESS(SAS)--TAB key, Prev: ESS(SAS)--Batch SAS processes, Up: Help for SAS ESS[SAS]-Function keys for batch processing =========================================== The setup of function keys for SAS batch processing is unavoidably complex, but the usage of function keys is simple. There are five distinct options: Option 1 (default). Function keys in ESS[SAS] are not bound to elisp commands. This is in accordance with the GNU Elisp Coding Standards (GECS) which do not allow function keys to be bound so that they are available to the user. Options 2-5. Since GECS does not allow function keys to be bound by modes, these keys are often unused. So, ESS[SAS] provides users with the option of binding elisp commands to these keys. Users who are familiar with SAS will, most likely, want to duplicate the function key capabilities of the SAS Display Manager. There are four options (noted in parentheses). a. SAS Display Manager has different function key definitions for Unix (2, 4) and Windows (3, 5); ESS can use either. b. The ESS[SAS] function key definitions can be active in all buffers (global: 4, 5) or limited (local: 2, 3) only to buffers with files that are associated with ESS[SAS] as specified in your auto-mode-alist. The distinction between local and global is subtle. If you want the ESS[SAS] definitions to work when you are in the *shell* buffer or when editing files other than the file extensions that ESS[SAS] recognizes, you will most likely want to use the global definitions. If you want your function keys to understand SAS batch commands when you are editing SAS files, and to behave normally when editing other files, then you will choose the local definitions. The option can be chosen by the person installing ESS for a site or by an individual. a. For a site installation or an individual, uncomment ONLY ONE of the following lines in your ess-site.el. ESS[SAS] Function keys are available in ESS[SAS] if you uncomment either 2 or 3 and in all modes if you uncomment 4 or 5: ;;2; (setq ess-sas-local-unix-keys t) ;;3; (setq ess-sas-local-pc-keys t) ;;4; (setq ess-sas-global-unix-keys t) ;;5; (setq ess-sas-global-pc-keys t) 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. b. If your site installation has configured the keys contrary to your liking, then you must call the appropriate function. (load "ess-site") ;; local-unix-keys (ess-sas-global-pc-keys) Finally, we get to what the function keys actually do. You may recognize some of the nicknames as SAS Display Manager commands (they are in all capitals). Unix PC Nickname "inferior" Alias (if any) and Description F2 F2 refresh revert the current buffer with the file of the same name if the file is newer than the buffer F3 F8 SUBMIT C-c C-b save the current .sas file (which is either the .sas file in the current buffer or the .sas file associated with the .lst or .log file in the current buffer) and submit the file as a batch SAS job F4 F5 PROGRAM switch buffer to .sas file F5 F6 LOG C-c C-x switch buffer to .log file, `refresh' and goto next error message, if any F6 F7 OUTPUT C-c C-y switch buffer to .lst file and `refresh' F7 F4 filetype-1 switch buffer to filetype-1 (defaults to .txt) file and `refresh' F8 F3 shell switch buffer to shell F9 F9 VIEWTABLE open an interactive FSEDIT/FSBROWSE session on the SAS dataset near point F10 F10 toggle-log toggle ESS[SAS] for .log files; may be useful for certain debugging situations F11 F11 filetype-2 switch buffer to filetype-2 (defaults to .dat) file and `refresh' F12 F12 viewgraph open a GSASFILE near point for viewing either in emacs or with an external viewer C-F1 C-F1 rtf-portrait create an MS RTF portrait file from the current buffer with a file extension of .rtf C-F2 C-F2 rtf-landscape create an MS RTF landscape file from the current buffer with a file extension of .rtf C-F3 C-F8 submit-region C-c C-r write region to ess-temp.sas and submit C-F5 C-F6 append-to-log append ess-temp.log to the current .log file C-F6 C-F7 append-to-output append ess-temp.lst to the current .lst file C-F9 C-F9 INSIGHT open an interactive INSIGHT session on the SAS dataset near point C-F10 C-F10 kill-em-all kill all buffers associated with a .sas program SUBMIT, PROGRAM, LOG and OUTPUT need no further explanation since they mimic the SAS Display Manager function key definitions. However, six other keys have been provided for convenience and are described below. `shell' switches you to the *shell* buffer where you can interact with your operating system. This is especially helpful if you would like to kill a SAS batch job. You can specify a different buffer name to associate with a SAS batch job (besides *shell*) with the buffer-local variable ess-sas-shell-buffer. This allows you to have multiple buffers running SAS batch jobs on multiple local/remote computers that may rely on different methods specified by the buffer-local variable ess-sas-submit-method. F2 performs the `refresh' operation on the current buffer. `refresh' compares the buffer's last modified date/time with the file's last modified date/time and replaces the buffer with the file if the file is newer. This is the same operation that is automatically performed when LOG, OUTPUT, `filetype-1' or F11 are pressed. `filetype-1' switches you to a file with the same file name as your .sas file, but with a different extension (.txt by default) and performs `refresh'. You can over-ride the default extension; for example in your .emacs file: (setq ess-sas-suffix-1 "csv") ; for example F9 will prompt you for the name of a permanent SAS dataset near point to be opened for viewing by PROC FSEDIT. You can control the SAS batch command-line with ess-sas-data-view-submit-options. For controlling the SAS batch commands, you have the global variables ess-sas-data-view-libname and ess-sas-data-view-fsview-command as well as the buffer-local variable ess-sas-data-view-fsview-statement. If you have your SAS LIBNAMEs defined in autoexec.sas, then the defaults for these variables should be sufficient. Similarly, C-F9 will prompt you for the name of a permanent SAS dataset near point to be opened for viewing by PROC INSIGHT. You can control the SAS batch command-line with ess-sas-data-view-submit-options. For controlling the SAS batch commands, you have the global variables ess-sas-data-view-libname and ess-sas-data-view-insight-command as well as the buffer-local variable ess-sas-data-view-insight-statement. F10 toggles ESS[SAS] mode for .log files which is off by default (technically, it is SAS-log-mode, but it looks the same). The syntax highlighting can be helpful in certain debugging situations, but large .log files may take a long time to highlight. F11 is the same as `filetype-1' except it is .dat by default. F12 will prompt you for the name of a GSASFILE near the point in .log to be opened for viewing either with emacs or with an external viewer. Depending on your version of emacs and the operating system you are using, emacs may support .gif and .jpg files internally. You may need to change the following variables for your own situation. ess-sas-graph-view-suffix-regexp is a regular expression of supported file types defined via file name extensions. ess-sas-graph-view-viewer-default is the default external viewer for your platform. ess-sas-graph-view-viewer-alist is an alist of exceptions to the default; i.e. file types and their associated viewers which will be used rather than the default viewer. (setq ess-sas-graph-view-suffix-regexp (concat "[.]\\([eE]?[pP][sS]\\|" "[pP][dD][fF]\\|[gG][iI][fF]\\|[jJ][pP][eE]?[gG]\\|" "[tT][iI][fF][fF]?\\)")) ;; default (setq ess-sas-graph-view-viewer-default "kodakimg") ;; Windows default (setq ess-sas-graph-view-viewer-default "sdtimage") ;; Solaris default (setq ess-sas-graph-view-viewer-alist '(("[eE]?[pP][sS]" . "gv") ("[pP][dD][fF]" . "acroread")) ;; default C-F2 produces US landscape by default, however, it can produce A4 landscape (first line for "global" key mapping, second for "local"): (global-set-key [(control f2)] 'ess-sas-rtf-a4-landscape) (define-key sas-mode-local-map [(control f2)] 'ess-sas-rtf-a4-landscape)  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 ================ 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 nil) ESS provides an alternate behavior for the TAB key that makes it behave as it does in SAS Display Manager, i.e. move the cursor to the next tab stop. The alternate behavior also provides a backwards TAB, C-TAB, that moves the cursor to the tab stop to the left and deletes any characters between them. This functionality is obtained by uncommenting the following line in ess-site.el: (setq ess-sas-edit-keys-toggle t) Under the alternate behavior, the TAB key is bound to tab-to-tab-stop and the tab stops are set at multiples of sas-indent-width.  File: ess.info, Node: ESS(SAS)--Usage scenarios, Next: iESS(SAS)--Common problems, Prev: ESS(SAS)--TAB key, Up: Help for SAS ESS[SAS]-Usage scenarios ======================== We present a batch and an interactive scenario for using ESS with SAS. The remarks with respect to graphics apply to either with exceptions noted. Graphics Output from GPROCs can be displayed in a SAS/Graph window for SAS batch on Windows or for both SAS batch and interactive with X11 on Unix. If you need to create graphics files and view them with F12, then include the following in myfile.sas (for F12 to work the FILENAME statement must be in myfile.sas, but the GOPTIONS statement can be in your autoexec.sas): filename gsasfile 'graphics.ps'; goptions device=ps gsfname=gsasfile gsfmode=append; 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: proc plot; plot a*b / vpos=25; run; SAS Batch (ess-sas-global-unix-keys keys shown, ess-sas-global-pc-keys in parentheses). Open 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. F3 (F8) The job runs in the shell buffer while you continue to edit myfile.sas. If ess-sas-submit-method is 'sh, then the message buffer will display the shell notification when the job is complete. The 'sh setting also allows you to terminate the SAS batch job before it is finished. F8 (F3) Terminating a SAS batch in the *shell* buffer. kill %1 You may want to visit the .log (whether the job is still running or it is finished) and check for error messages. The .log will be refreshed and you will be placed in it's buffer. You will be taken to the 1st error message, if any. F5 (F6) Goto the next error message, if any. F5 (F6) Now, refresh the .lst and go to it's buffer. F6 (F7) If you wish to make changes, go to the .sas file with. F4 (F5) Make your editing changes and submit again. F3 (F8) Interactive SAS Open 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: Buffer Mode Description myfile.sas ESS[SAS] your source file *SAS:1* iESS [SAS:1] ESS communication buffer *SAS:1.log* Shell [] ESStr SAS log information *SAS:1.lst* Shell [] ESSlst SAS listing information 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 At the end of the session you may save the log and listing buffers with the usual C-x C-s commands. You will be prompted for a file name. Typically, the names myfile.log and myfile.lst will be used. You will almost certainly want to edit the saved files before including them in a report. The files are read-only by default. You can make them writable by the emacs command C-x C-q. At the end of the session, the input file myfile.sas will typically have been revised. You can save it. It can be used later as the beginning of another iESS[SAS] session. It can also be used as a batch input file to SAS. The *SAS:1* buffer is strictly for ESS use. The user should never need to read it or write to it. Refer to the .lst and .log buffers for monitoring output!  File: ess.info, Node: iESS(SAS)--Common problems, Next: ESS(SAS)--MS Windows, Prev: ESS(SAS)--Usage scenarios, Up: Help for SAS iESS[SAS]-Common problems ========================= 1. iESS[SAS] does not work on Windows. In order to run SAS inside an emacs buffer, it is necessary to start SAS with the -stdio option. SAS does not support the -stdio option on Windows. 2. If M-x SAS gives errors upon startup, check the following: - you are running Windows: see 1. - ess-sas-sh-command (in the ESS source directory) needs to be executable (solution: "chmod ugo+rx ess-sas-sh-command"). - sas isn't in your executable path (verify using "which sas" from a shell command-line) 3. M-x SAS starts SAS Display Manager. Probably, the command "sas" on your system calls a shell script. Specify the path to the real "sas" executable in the file ess-sas-sh-command, i.e.: /usr/local/sas612/sas $stdout 2>$stderr $@ To find the "sas" exectuable, you can execute the unix command: find / -name sas -print  File: ess.info, Node: ESS(SAS)--MS Windows, Prev: iESS(SAS)--Common problems, Up: Help for SAS ESS[SAS]-MS Windows =================== * iESS[SAS] does not work on Windows. *Note iESS(SAS)--Common problems::. * 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 SAS processes::. Or you can mark regions with the mouse and submit the code with `submit-region' or paste them into SAS Display Manager.  File: ess.info, Node: Help for BUGS, Next: Entering commands, Prev: Help for SAS, Up: Top Help for BUGS ************* * Menu: * ESS(BUGS)--Model files:: * ESS(BUGS)--Command files:: * ESS(BUGS)--Log files:: ESS[BUGS] was designed for use with BUGS software. It was developed by Rodney A. Sparapani and has some similarities with ESS[SAS]. ESS facilitates BUGS batch with ESS[BUGS], the mode for files with the .bug extension. ESS provides 5 features. First, BUGS syntax is described to allow for proper fontification of statements, distributions, functions, commands and comments in BUGS model files, command files and log files. Second, ESS creates templates for the command file from the model file so that a BUGS batch process can be defined by a single file. Third, ESS provides a BUGS batch script that allows ESS to set BUGS batch parameters. Fourth, key sequences are defined to create a command file and submit a BUGS batch process. Lastly, interactive submission of BUGS commands is also supported.  File: ess.info, Node: ESS(BUGS)--Model files, Next: ESS(BUGS)--Command files, Prev: Help for BUGS, Up: Help for BUGS ESS[BUGS]-Model files ===================== Model files (with the .bug extension) are edited in ESS[BUGS] mode. Two keys are bound for your use in ESS[BUGS], F2 and F12. F2 performs the same action as it does in ESS[SAS], *Note ESS(SAS)--Function keys for batch processing::. F12 performs the function ess-bugs-next-action which you will use a lot. Pressing F12 in an empty buffer for a model file will produce a template for you. ESS[BUGS] supports "replacement" variables. These variables are created as part of the template, i.e. with the first press of F12 in an empty buffer. They are named by all capitals and start with '%': %N, %DATA, %INIT, %MONITOR and %STATS. When you are finished editing your model file, pressing F12 will perform the necessary replacements and build your command file for you. The %DATA variable appears in the line 'data in "%DATA";'. On the second press of F12, %DATA will be replaced by the model file name except it will have the .dat extension. If your data file is named something else, then change %DATA in the template to the appropriate file name and no replacement will occur. The %INIT variable appears in the line 'inits in "%INIT";'. On the second press of F12, %INIT will be replaced by the model file name except it will have the .in extension. If your model will be generating it's own initial values, place a comment character, #, at the beginning of the line. Or, if your init file is named something else, then change %INIT in the template to the appropriate file name. The %N variable appears in the line 'const N = 0;#%N'. Although it is commented, it is still active. Notice that later on in the template you have the line 'for (i in 1:N)'. The BUGS constant N is the number of rows in your data file. When you press F12, the data file is read and the number of lines are counted (after %DATA is resolved, if necessary). The number of lines replace the zero in the 'const N = 0' statement. The %MONITOR variable appears on a line by itself. Although it is commented, it is still active. This line is a list of variables that you want monitored. When you press F12, the appropriate statements are created in the command file to monitor the list of variables. If the line is blank, then the list is populated with the variables from the 'var' statement. The %STATS variable is similar to the %MONITOR variable. It is a list of variables for which summary statistics will be calculated. When you press F12, the appropriate statements will be generated in your command file. Please note that the %DATA and %INIT variables are only replaced on the second press of F12, but the actions for %N, %MONITOR and %STATS are performed on each press of F12 if you re-visit the model file.  File: ess.info, Node: ESS(BUGS)--Command files, Next: ESS(BUGS)--Log files, Prev: ESS(BUGS)--Model files, Up: Help for BUGS ESS[BUGS]-Command files ======================= To avoid extension name collision, .bmd is used for BUGS command files. When you have finished editing your model file and press F12, a command file is created if one does not already exist. However, the command file was created, it recognizes two "replacement" variables: %MONITOR and %STATS. Two %MONITOR variables appears on lines by themselves. Although they are commented, they are still active. Between them appears the necessary statements to monitor the list of variables specified in the model file. The behavior of the %STATS variable is similar. When you are finished editing your command file, pressing F12 again will submit your command file as a batch job. Batch scripts are provided for both DOS and Unix in the etc sub-directory of the ESS distribution. The DOS script is called "BACKBUGS.BAT" and the Unix script is "backbugs". These scripts allow you to change the number of bins to use in the Griddy algorithm (Metropolis sampling). That is handled by the variable ess-bugs-default-bins which defaults to 32.