Admin

S-PLUS 7 Installation and Administration Guide for Windows and UNIX
June 2005 Insightful Corporation Seattle, Washington
Proprietary Notice
Insightful Corporation owns both this software program and its documentation. Both the program and documentation are copyrighted with all rights reserved by Insightful Corporation. The correct bibliographical reference for this document is as follows: S-PLUS 7 Installation and Administration Guide for Windows and UNIX, Insightful Corporation, Seattle, WA. Printed in the United States.
Copyright Notice Copyright 1988-2005, Insightful Corporation. All rights reserved.

Insightful Corporation 1700 Westlake Avenue N, Suite 500 Seattle, Washington 98109 USA
Trademarks
Insightful, Insightful Corporation, the Insightful logo, S-PLUS, Insightful Miner, S+FinMetrics, S+SeqTrial, S+SpatialStats, S+ArrayAnalyzer, S+EnvironmentalStats, S+Wavelets, S-PLUS Graphlets and Graphlet are either trademarks or registered trademarks of Insightful Corporation in the United States and/or other countries. Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Microsoft, Windows, MS-DOS and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Sun, Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States or other countries. UNIX is a registered trademark of The Open Group in the United States or other countries. All product names mentioned herein may be trademarks or registered trademarks of their respective companies.
ii
Acknowledgments
ACKNOWLEDGMENTS
S-PLUS would not exist without the pioneering research of the Bell Labs S team at AT&T (now Lucent Technologies): John Chambers, Richard A. Becker (now at AT&T Laboratories), Allan R. Wilks (now at AT&T Laboratories), Duncan Temple Lang, and their colleagues in the statistics research departments at Lucent: William S. Cleveland, Trevor Hastie (now at Stanford University), Linda Clark, Anne Freeny, Eric Grosse, David James, Jos Pinheiro, Daryl Pregibon, and Ming Shyu. Insightful Corporation thanks the following individuals for their contributions to this and earlier releases of S-PLUS: Douglas M. Bates, Leo Breiman, Dan Carr, Steve Dubnoff, Don Edwards, Jerome Friedman, Kevin Goodman, Perry Haaland, David Hardesty, Frank Harrell, Richard Heiberger, Mia Hubert, Richard Jones, Jennifer Lasecki, W.Q. Meeker, Adrian Raftery, Brian Ripley, Peter Rousseeuw, J.D. Spurrier, Anja Struyf, Terry Therneau, Rob Tibshirani, Katrien Van Driessen, William Venables, and Judy Zeh.
iii
iv
CONTENTS
Chapter 1
Introduction
1
2 3 6 7
Overview Supported Platforms and System Requirements Serial Numbers, License Authorization Codes, and License Keys Technical Support PART I: S-PLUS FOR WINDOWS/UNIX/LINUX
Chapter 2
Installing S-PLUS 7 for Windows
9
10
Installation Steps
Chapter 3
Installing S-PLUS 7 for UNIX/Linux
13
14 23
Basic Installation Linux-Specific Information
Chapter 4 License Management

License Types Generating a License Key Modifying the License Manager for Concurrent User (CU) and Windows Terminal Services Users (CS, SESS, PSESS) Setting the License Key Environment Variable
25
26 28
49 53
Installing the License Manager on a Separate Machine 55
Contents PART II: S-PLUS ENTERPRISE SERVER FOR WINDOWS
Chapter 5 S-PLUS Enterprise Server for Windows Architecture

Introduction S-PLUS Enterprise Server Overview
59
60 61
Chapter 6 Determining Your Optimal S-PLUS Enterprise Server for Windows Configuration
Overview Question 1: Can I Use Previously Calculated Results? Question 2: If I Cannot Use Previously Calculated Results, Is an Individual Run of My Analysis Fast Enough? Question 3: Based on My Expected Hit Rate and Analysis Time, How Many Simultaneous Analyses Does My Configuration Need to Handle?
67
68 70
72
75
Question 4: Once I Know the Number of Simultaneous Analyses Needed, Should Those Analyses Be Shared Over Multiple Servers? 77
Chapter 7 Installing S-PLUS Enterprise Server and Client for Windows 79

Introduction Server Installation Client Installation 80 81 91
Chapter 8 Administering S-PLUS Enterprise Server for Windows

Overview Administering S-PLUS Enterprise Server Through the Web Tools Other Methods of Controlling S-PLUS Enterprise Server
95
97 98 114
vi
Contents S-PLUS Enterprise Server Maintenance 117
Chapter 9
Advanced Topics
121
122 131 135 136 137 143
Configuration of Microsofts Internet Information Server (IIS) Web Server Security Allowing Upload of Large Data Files Network Load Balancing A Detailed View of How S-PLUS Enterprise Server Works Using COM+ to Distribute S-PLUS Enterprise Server Applications
Chapter 10 Troubleshooting Guide

Introduction Connection/Installation Problems License Management Problems Problems Creating or Running Analytics Problems with Remote COM Clients NTFS Issues
145
146 147 150 151 156 158
vii
Contents PART III: S-PLUS ENTERPRISE SERVER FOR UNIX
Chapter 11 S-PLUS Enterprise Server for UNIX Installation

Introduction Basic Installation Procedure Troubleshooting Installation and Licensing Problems
165
166 168 172
Chapter 12 S-PLUS Enterprise Server for UNIX Client Installation

Introduction Creating Working Directories Installing the Client Software Troubleshooting Starting a Client Health and Status
175
176 177 178 181 184 188
Chapter 13 Setting System Defaults

Introduction Specifying a Destination Directory and Name for the Splus Script Configuring S-PLUS Server to Produce Graphics on Your Printer Configuring S-PLUS Server to Print Help Files Setting License Manager Options Installing the S-PLUS Man Page
189
190 192 194 197 198 200
Chapter 14
Server Administration
201
202 203 207 213
Introduction Starting the S-PLUS Session Factory Managing the S-PLUS Session Factory S-PLUS Enterprise Server and RMI Services
viii
Contents Security Issues 215
Chapter 15 Managing Your S-PLUS Enterprise Server for UNIX Licenses

Introduction Starting and Stopping the License Server Valid License Commands and Arguments
217
218 219 220
Chapter 16 Setting Motif Defaults

Introduction X11 Fonts Color Schemes for the motif Graphics Device
223
224 226 228
Chapter 17 Enhancing S-PLUS Enterprise Server for UNIX

Introduction Adding Help Files for New Functions Customizing Start-Up
231
232 235 237
Organizing Local Functions with the library Function 233
Chapter 18
Configuring Help Services
239
240 241 243 245 248
Introduction Making Help Files Visible on the Web Server Using the S-PLUS Help Viewer Customizing the Stand-Alone Help Services Host Adding Custom Help Sets
Index
249
ix
Contents
INTRODUCTION
1
2 3 3 3 4 5 6 7
Overview Supported Platforms and System Requirements S-PLUS for Windows S-PLUS Enterprise Server for Windows S-PLUS for UNIX/Linux S-PLUS Enterprise Server for UNIX/Linux Serial Numbers, License Authorization Codes, and License Keys Technical Support
Chapter 1 Introduction
OVERVIEW
This manual contains information on installation, administration, and licensing for all editions of S-PLUS 7 and S-PLUS 7 Enterprise Server for Windows, UNIX, and Linux. All licensing scenarios (e.g., singleuser, concurrent user, production server, etc.) are discussed in this manual. S-PLUS and S-PLUS Enterprise Server feature a new built-in license management using FLEXnet, discussed in Chapter 4, License Management. This manual is written mainly for an audience of Windows, UNIX, and Linux systems administrators. Because the FLEXnet license management system is used for all editions of S-PLUS, there is helpful information for generating license keys for desktop users as well as administrators. In the typical scenario, a Windows or UNIX systems administrator uses this guide to install S-PLUS on a network so that a number of users can simultaneously access S-PLUS.
Supported Platforms and System Requirements
SUPPORTED PLATFORMS AND SYSTEM REQUIREMENTS

S-PLUS for Windows
S-PLUS 7 for Windows is supported on the following platforms: Windows 2000 Windows XP Home Windows XP Professional Edition Windows 2003 Server
To install S-PLUS, the minimum recommended system configuration is a Pentium III processor with 512MB of RAM and 450MB disk space. There are no 64-bit versions available on Windows with this release.
S-PLUS Enterprise Server for Windows
S-PLUS 7 Enterprise Server for Windows is supported on the following platforms: Windows 2000 Server Windows 2000 Advanced Server Windows Server 2003 Standard Edition Windows Server 2003 Enterprise Edition. 1 GB of RAM. One or more 1 Ghz processors. 500 MB free disk space (50 MB for program files) 450 MB for S-PLUS program files. Approximately 1GB space reserved for the system swap file. Microsoft Internet Information Services (IIS) Web server. Windows 2000 Service Pack 2 (SP2) and Security Rollup Pack 1 (SRP1) or any Service Pack greater than SP2. SP2 with Security Pack 1 (Windows 2000 Server and Windows 2000 Advanced Server only).
In addition, you must have the following:
For Windows 2000 , it is required that you have at least the following:
Note You must have Administrative privileges to install S-PLUS Enterprise Server.
For information on client installation and requirements, consult readme.txt, located in your SHOME (base installation) directory.
S-PLUS for UNIX/Linux
S-PLUS 7 for UNIX/Linux is supported on the following platforms and operating systems. The minimum recommended disk space for installing and running S-PLUS is also included:
Table 1.1: Supported 32-bit platforms for UNIX/Linux systems. Platform Sun SPARC Intel/AMD x86 IBM HP Operating System Solaris 2.8, 2.9 on SPARC processors Red Hat Enterprise Linux WS 3.0 AIX 5.1 or 5.2 on POWER processors HP-UX 11.0 on PA-RISC processors Disk Space 340 MB 340 MB 340 MB 340 MB
Note that HP Alpha running Tru64, or UNIX 4.0F or 5.1A, is no longer supported. It is also true that previous versions of the listed operating systems may function with S-PLUS, but they are not supported. There are no 64-bit versions available on UNIX/Linux with this release. You will need a minimum of 60 MB RAM to run S-PLUS from the command line, and the Java GUI requires an additional 100 MB to run. Note that these values are minima; if you work with moderatesized data sets, these numbers may be insufficient for your needs.
Supported Platforms and System Requirements
S-PLUS Enterprise Server for UNIX/Linux
In addition to the recommended disk space for installing and running S-PLUS Enterprise Server listed in Table 1.1, you must also consider the RAM necessary for simultaneous users to run S-PLUS Enterprise Server as well. This information is shown in Table 1.2. Review the minimum system configuration information below. In determining required RAM, sum the Base RAM and the per-user RAM multiplied by the number of simultaneous users. For example, a single-user Linux system should have at least 64 + 60*1 = 124MB of Base RAM. The Base RAM and per-user RAM listings can also be used to calculate minimum swap space requirements: in general, the minimum swap space required is twice the sum of the Base RAM and the per-user RAM multiplied by the number of simultaneous users. For example, on a Solaris system with 3 simultaneous S-PLUS Enterprise Server users, the minimum swap space is 2*(64+(60*3)) = 488MB. Note that these values are minima; if you work with moderately sized data sets, these numbers may be insufficient for your needs:
Table 1.2: Base RAM and per-user RAM required for S-PLUS Enterprise Server for UNIX/Linux. Platform Sun SPARC Intel x86 Operating System Solaris 2.8, 2.9 Red Hat Enterprise Linux WS 3.0 Disk Space 225 MB 225 MB Base RAM 64 MB 64 MB Per-User RAM 40 MB 32 MB
For information on client installation and requirements, consult INSTALL_SERVER.TXT, located in your SHOME (base installation) directory.
Note HP and AIX are not supported for S-PLUS Enterprise Server.
SERIAL NUMBERS, LICENSE AUTHORIZATION CODES, AND LICENSE KEYS

Your S-PLUS CD comes with a serial number printed on the jewel case. This serial number is linked to your license authorization code (LAC), which you should have received via e-mail. The license authorization code is used to generate your unique license keys which are required to running S-PLUS. Your S-PLUS license authorization code identifies your account with Insightful Corporation, and is automatically generated by the license management system. Each license authorization code is unique to a specific order; for example, one license authorization code could cover five single-user, single-machine S-PLUS 7 Enterprise Developer installations. To complete the installation process described in this manual, you need to know the serial number for the product you wish to install (in addition to the license authorization code): Your S-PLUS serial number is located on the case for your S-PLUS for Windows CD. Serial numbers for the S-PLUS modules are either located on the CD or in correspondence you received from Insightful Corporation. If you received a CD containing both S-PLUS and its modules, check the letters in that package for the module-specific serial number.
Note that module serial numbers are unique, and are separate from S-PLUS serial numbers. The license manager encrypts the key and uses it to monitor the available seats on your network. Go to the FLEXnet license manager site at http://www.macrovision.com/products/flexnet/index.shtml for more info. For additional details that are not discussed in this manual, you may find it helpful to consult the FLEXnet Licensing End User Guide. This is located at SHOME/adm/lic/cmd/LicensingEndUserGuide.pdf
Technical Support
TECHNICAL SUPPORT
Global Headquarters 1700 Westlake Avenue North, Suite 500 Seattle, WA 98109 USA Tel: 206.283.8802 800.569.0123 Fax: 206.283.6310 e-mail: support@insightful.com Insightful AG Kgenstrasse 17 4153 Reinach Switzerland Tel: +41 61 717 9340 Fax: +41 61 717 9341 e-mail: shelp@insightful.com Insightful UK 5th Floor, Network House Basing View Basingstoke, Hampshire RG21 4HG Tel: +44 (0) 1256 339800 Fax: +44 (0) 1256 339839 e-mail: shelp@insightful.com Insightful France 7, rue Auber 31000 Toulouse France Tel: +33 0 5 62 27 70 60 Fax: +33 0 5 62 27 70 61 e-mail: shelp@insightful.com
INSTALLING WINDOWS
S-PLUS
7 FOR
2
10
Installation Steps
Chapter 2 Installing S-PLUS 7 for Windows
INSTALLATION STEPS
1. Insert the S-PLUS 7 for Windows CD into the CD-ROM drive on your machine. If your machine has CD-ROM AutoPlay enabled, the installation program starts automatically. Otherwise, open Microsoft Windows Explorer and run the setup.exe program from the CD-ROM drive. The Master Setup screen appears, as shown below.
Figure 2.1: The S-PLUS 7 installation splash screen.
2. In the Master Setup, click the Install/Configure S-PLUS on your system. button. You will be prompted for your S-PLUS serial number, which is located on the jewel case. Accept all defaults in the screens that appear, except the installation directory and available options you want when starting S-PLUS. This installs the S-PLUS program files in the following default folder:
C:\Program Files\Insightful\splus70
10
Installation Steps 3. After the S-PLUS installation has completed, return to the Master Setup. If you have purchased licenses for S-PLUS modules, click the Install S-PLUS Modules button. Again, you will need a serial number for the module to complete the installation. Select a module from the menu that appears and accept all defaults in the screens that follow. This includes S+ARCVIEW, S+ARRAYANALYZER, S+ENVIRONMENTALSTATS, S+FINMETRICS, S+NUOPT, S+SEQTRIAL, S+SPATIALSTATS, or the S+WAVELETS module. By default, the module is stored in the corresponding SHOME/module/[module name] folder. For example, S+ARRAYANALYZER is installed by default at:
C:\Program Files\Insightful\splus70\module\ArrayAnalyzer
4. Installing S-PLUS also copies files related to the FLEXnet license manager in the following default folder:
C:\Program Files\Insightful\splus70\adm\lic\cmd
This should successfully complete your S-PLUS installation. To run S-PLUS, you will need a license key, which is discussed in the Chapter 4, License Management.
Note To complete the S-PLUS installation, you need the serial numbers and license authorization code for S-PLUS and any modules you have purchased in order to generate a license key. See Chapter 4, License Management for more information on license management.
11
Chapter 2 Installing S-PLUS 7 for Windows
12
INSTALLING UNIX/LINUX
S-PLUS
7 FOR
3
14 14 15 17 19 20 20 23 23 23
Basic Installation Step 1: Unpacking and Copying the Files from the Distribution CD Step 2: Obtaining and Installing a License Key Step 3: Running the CONFIGURE Script Step 4: Running the INSTALL Script Step 5: Running the License Manager Step 6: Running S-PLUS Linux-Specific Information Installation Issues Starting the License Manager Daemon at Boot Time
13
Chapter 3 Installing S-PLUS 7 for UNIX/Linux
BASIC INSTALLATION
The S-PLUS 7 for UNIX/Linux installation, configuration, and verification process consists of six steps: 1. Unpacking and copying the files from the distribution CD to an appropriate place on your system. 2. Obtaining and installing a license key. 3. Running the CONFIGURE script (to select various configuration options). 4. Running the INSTALL script. 5. Running the license manager. 6. Running S-PLUS. Beginning with S-PLUS 7, the FLEXnet license manager is used for all license management. All installations require a new license key, and all steps must be completed whether this is an upgrade or a new installation. The following section provides detailed information for each step.
Step 1: Unpacking and Copying the Files from the Distribution CD
If you have a previous edition of S-PLUS already installed on your system, do not install the new edition in the same directory tree. The existing installation should be left intact until after the new installation is up and running, and until you are satisfied that it is no longer required for any reason. To unpack and copy the files: 1. Create a new directory for the S-PLUS tree, and cd to that directory. Be sure the directory you create is on a file system with adequate disk space. This directory can be in your home directory if you are going to be the only user, or in a globally visible location if the installation is to be shared by multiple users. In the latter case, we recommend you create a special user account called splus, and use that account's home directory as the installation directory. If you create such an account, log in as splus to perform most of the installation; you will want to be superuser (or root) to actually install the S-PLUS script.
14
Basic Installation 2. Set permissions so everyone on your system can use S-PLUS:
umask 022
3. As either a regular user (yourself or splus) or as root, unpack the tar file from the CD-ROM into the new directory using tar as follows:
cat /[mount_point]/SPLUS.TZ | uncompress | tar xvf -
where [mount_point] is the absolute path to the CD-ROM drive. Depending on your platform, files on the CD may be listed in UPPERCASE, lowercase, or UPPERCASE;1. After mounting the CD-ROM drive, use the ls command to see the format shown on your system. Use the same format in the cat command as shown on your system. If you are installing as superuser (or root), the files may be restored with the user and group identifiers that existed when the files were tarred. On some platforms (including Solaris), the -o flag to tar assigns these identifiers to the user extracting the files. If your system has the zcat command, you can use it to shorten your extraction command (zcat combines the cat and uncompress commands):
zcat /[mount_point]/SPLUS.TZ | tar xvf -
Step 2: Obtaining and Installing a License Key
Follow these steps to obtain and install a license key. A license key is required in order to run S-PLUS: 1. Run ./HOSTINFO to display your hostid. Copy this hostid. 2. Point your browser to http://keys.insightful.com. 3. Click the first link, I have a License Authorization Code. 4. Enter the license authorization code (provided in the e-mail you received from keys@insightful.com. If you did not receive this e-mail, contact Tech Support.) Click Login. 5. In the Generate or View Licenses page, click Generate Licenses. 6. Check the box next to each product you want to license (including any modules that were ordered).
15
Chapter 3 Installing S-PLUS 7 for UNIX/Linux 7. If the license manager will be installed on the same machine that S-PLUS is installed, enter the information for each field in the Generate Licenses page, as shown in Table 3.1
Table 3.1: Required information for license key installation in the Generate Licenses page. Field Server hostid type Enter
Ethernet
Comment If your hostid (provided by the ./HOSTINFO script) is eight (8) characters long, select Long. If it is 12 characters, select Ethernet. In most cases, this can be left blank, and the appropriate type will be used automatically.
Server hostid
hostid of license manager machine

Ethernet
Node-Locked Type Node-Locked hostid
hostid of S-PLUS machine
This may be identical to the server hostid, if the license manager and S-PLUS are running on the same machine.
All other fields (Server 2, Server 3, etc.) should be left blank. 8. Click the Generate button. 9. Verify that each hostid was entered correctly, and click the Confirm button. 10. Click the Save to File button, and save the file to adm/lic/ keys in your new S-PLUS installation. Any file name is acceptable, but it must end in .lic. Authorizing Users for S-PLUS (client/server licensing only) Create a new text file in adm/lic/keys named IFUL.opt and in a text editor, add the following two lines, exactly as shown (except for user1 and user2; see below):
16
Basic Installation
GROUP INCLUDE INCLUDE INCLUDE splususers 00 00B 00W user1 GROUP GROUP GROUP user2 splususers splususers splususers
where user1 and user2 are the names of authorized users, 00 is the license code for S-PLUS, 00B is the license code for the Big Data library, and 00W is the license code for the S-PLUS Workbench. Do not list more user names than the number of users authorized in your S-PLUS license key. To determine the number of licensed users, open your license key file in a text editor, and look for lines beginning with INCREMENT; the number of licensed users is the number immediately preceding VENDOR_STRING. Add additional INCLUDE lines for any licensed modules; e.g.,
INCLUDE <feature> GROUP splususers
where <feature> is the feature number of the associated module. This can be found by viewing your license key file in a text editor (as in the step above). The feature code is the number immediately following INCREMENT. Save the file. For additional details on the IFUL.opt options file, see the FLEXnet Licensing End User Guide in adm/lic/cmd.
Step 3: Running the CONFIGURE Script
The purpose of running the CONFIGURE script is to select various options for creating the script for starting S-PLUS. We recommend that you ask your system administrator to create a new user called splus, and to run CONFIGURE as splus. The Unix group of that user should include those users who are likely to want to run S-PLUS. Within the new S-PLUS home directory, run the CONFIGURE script: ./CONFIGURE The license agreement is displayed for your review. When you have finished reading this agreement, press q (quit), wait a moment for the text to appear, and when it is displayed, you have an option to accept (1) or to not accept (2) the agreement.
17
Chapter 3 Installing S-PLUS 7 for UNIX/Linux The CONFIGURE script displays the following: Configuration Options: 1: 2: 3: 4: 5: 6: 0: About This Menu Graphics Hard Copy Printing Help File Printing Destinations and Name of Splus Script License Management Installation of S-PLUS man page Exit this Menu
The selections you make during this step depend on whether you have an existing version of S-PLUS installed or whether this will be a new installation. If you have an existing S-PLUS installation: This section applies if you have a previous edition of S-PLUS already installed on your system, and you would like to run S-PLUS 7 alongside your currently installed version. If you are upgrading from a previous edition of S-PLUS, please skip to the section on new installations below. Part of the configuration and installation process is to create a startup script for S-PLUS. The startup script for the new version of S-PLUS should be given a name that is separate and distinct from the name of the startup script for any existing installations of S-PLUS. For example, if you have S-PLUS 6.x or earlier installed with a startup script named Splus and you are currently installing S-PLUS 7, you have several choices, including the following: 1. Rename the existing script as Splus6.x and name the new script Splus 2. Leave the name of the existing script as Splus and name the new script Splus7.0. Startup script names and the locations for those startup scripts are selected when you run the CONFIGURE script. We recommend that you ask your system administrator to create a new user called splus, and to run CONFIGURE as splus. The UNIX group of that user should include those users who are likely to want to run S-PLUS.
18
Basic Installation When you run CONFIGURE, you will see the following menu: Configuration Options: 1: 2: 3: 4: 5: 6: 0: About This Menu Graphics Hard Copy Printing Help File Printing Destinations and Name of Splus Script License Management Installation of S-PLUS man page Exit this Menu
For most upgrades, option 4, Destinations and Name of Splus Script, is the only option that you will need to deal with. In most cases, you should leave the default destination (/usr/local/bin) alone, and select a new name for the script as discussed above. After that, select option 0 to exit the script. If this is a new S-PLUS installation For most new installations, it is sufficient to accept all of the defaults. In that case, select each of the options to confirm the information, and select Exit this Menu. It is still necessary to run CONFIGURE, even if you accept all of the defaults. The default is to name the startup script Splus, and to install it in /usr/local/bin. If you wish to give the startup script a different name or to install it in a different location, please select option 4, Destinations and Name of Splus Script.
Step 4: Running the INSTALL Script
After running CONFIGURE, the next step is to run INSTALL, which copies the information you entered in the CONFIGURE step to the appropriate directory. You should run INSTALL as root (particularly if you accept the default location for the startup script of /usr/local/bin): ./INSTALL from within your installation directory.
19
Chapter 3 Installing S-PLUS 7 for UNIX/Linux
Step 5: Running the License Manager
Start the license server daemon using the command

Splus LICENSE server start
If you use a different name for your S-PLUS script, use it instead of Splus. You can check the status of the license server at any time by entering
Splus LICENSE server status
Step 6: Running S-PLUS
Before starting S-PLUS, you must do the following: Set your DISPLAY environment variable to your local machine. Check if your DISPLAY variable is set already by looking at the output from
echo $DISPLAY
to be sure. To set your display from a C-like shell (csh, tcsh, etc.), use the setenv command:
setenv DISPLAY <display_name>
where <display_name> is the name of your local machine. From the Bourne- and Korn-like shells (including sh, ksh, bash, etc.), use the following commands:
DISPLAY=<display_name>;export DISPLAY
To use the Java related features of S-PLUS, you must be able to connect to your local X window server. Thus, you must have the environmental variable DISPLAY set, and the X window server on your local machine must allow the S-PLUS server to create windows on your machine; see the UNIX programs xauth or xhost. Typically, if you can run xclock on your machine, then S-PLUS should also be able to access the X server. Create an S-PLUS chapter to hold your work. Creating an S-PLUS chapter is necessary for storing the data objects and external files you create in S-PLUS. The following commands create an S-PLUS chapter named mysplus for you to work in (be sure you don't have a mysplus directory in your home directory before typing these commands):
20
Basic Installation
% % % % cd mkdir mysplus cd mysplus Splus CHAPTER
Note that if you do not create a chapter, S-PLUS automatically creates one for you named MySwork the first time you start S-PLUS. You are now ready to start S-PLUS. S-PLUS may be launched in a variety of modes, and the following lists each mode and the corresponding UNIX command-line expression for launching it. In all of the commands below, Splus refers to the script you use to launch S-PLUS 7 on your system. To run S-PLUS from the command line without Java:
Splus
To run S-PLUS from the command line supporting Java calls, Java graphics, and the Java help interface:
Splus -j
To run S-PLUS from the command line with the graphical user interface:
Splus -g
or Splus -g &
The second command (using the ampersand &) puts the GUI process into the background, freeing your xterm for other uses. To attach the S-PLUS Big Data Library before running S-PLUS:
Splus -bigdata
To run the S-PLUS Workbench:

Splus -w | -workbench
(Note that both the Big Data library and the Workbench are available in the Enterprise Developer edition only). The -e flag may be added to either of the first two modes to enable command-line editing. The Commands window in the graphical user interface always allows basic editing.
21
Chapter 3 Installing S-PLUS 7 for UNIX/Linux S-PLUS 7 includes two additional flags, -jit and -helpoff: The -jit flag works with the -g, -j, and -userapp flags and allows you to turn on the Java just-in-time compiler. This makes the graphical user interface and help system run faster but introduces instabilities that often lead to crashes. In particular, the just-in-time compiler often crashes while repainting graphical user interface elements such as the JavaHelp window and the Data window. The -helpoff flag is useful only with the -g flag. It turns off the automatic invisible startup of the help system. The invisible startup improves initial responsiveness of the help system but adds a significant memory footprint to the current session. If you wish to optimize your available memory, this flag may prove useful.
22
Linux-Specific Information
LINUX-SPECIFIC INFORMATION
Installation Issues
For the license manager to work, your Linux system must be running network system services. If it is not, you should receive the following error when starting S-PLUS:
Terminating S Session: License Server localhost.localdomain [S-PLUS] Network error: unable to send message to license server.
To see if network services are running on your system, type the following at your shell prompt:
ping localhost
If you cannot ping localhost, networking is not turned on. Run the following command as root at the superuser prompt:
chkconfig network on
After turning on the network system services, reboot your system and start S-PLUS. If your system is sometimes connected to a network, but not always, you need to be able to ping your machine using either its stand-alone name or its network name. For example, if your machine name is cleo and it can exist in the domain insightful.com, you need to be able to ping both cleo and cleo.insightful.com. You can ensure this by changing your host table, /etc/hosts, so that it contains only the following:
# loopback 127.0.0.1 localhost loghost cleo cleo.insightful.com
Starting the License Manager Daemon at Boot Time
You can modify your system's boot sequence so that the license manager daemon starts automatically whenever you boot or reboot your system. The basic procedure is described in the section Starting the License Server Manager on UNIX Platforms in the FLEXnet Licensing End User Guide located at SHOME/adm/lic/cmd/LicensingEndUserGuide.pdf
23
Chapter 3 Installing S-PLUS 7 for UNIX/Linux Adobe Acrobat reader is required to view this file.
Note To complete the S-PLUS installation, you need the serial numbers and license authorization code for S-PLUS and any modules you have purchased in order to generate a license key. See the section Serial Numbers, License Authorization Codes, and License Keys on page 6.
24
LICENSE MANAGEMENT
4
26 26 27 28 28 44 46 47 49 53 53 54 55 55 56
License Types S-PLUS Licensing S-PLUS Enterprise Server Licensing Generating a License Key Single-User (SU) Licensing (Windows) Concurrent User (CU) Licensing (Windows) Client/Server (CS) and Concurrent Session (SESS) Licensing (Windows/UNIX) Production Server (PS) and Production Concurrent Session (PSESS) Licensing (Windows/UNIX) Modifying the License Manager for Concurrent User (CU) and Windows Terminal Services Users (CS, SESS, PSESS) Setting the License Key Environment Variable Windows UNIX Installing the License Manager on a Separate Machine Windows UNIX
25
LICENSE TYPES
Licensing S-PLUS and S-PLUS Enterprise Server is quite similar, as both use FLEXnet license management. The differences lie in the types of licenses available for the given installation, which provides you with flexibility to license S-PLUS or S-PLUS Enterprise Server in a variety of ways. We list the licensing types by platform in the following section.
S-PLUS Licensing
Windows Single User (SU) This type of licensing applies to installations where the software is installed and computations take place at the desktop machine where the user is physically sitting. Multiple sessions on the desktop machine are allowed. Concurrent User (CU) This is a licensing scenario where one central license manager holds license keys, and any machine can check a key out. Remote access is not permitted.
Windows and UNIX Client/Server (CS) A single, powerful server machine supports specified S-PLUS users via remote access. Computations take place on the remote server machine. Multiple sessions are allowed per named user, and each named user must be included in the IFUL.opt file (see the section Creating the IFUL.opt File for Named Users for more information). Each session is node-locked. Concurrent Session (SESS) The total number of simultaneous S-PLUS sessions (initiated by any authorized user) is capped by the number of purchased concurrent session licenses. Should a user attempt to start S-PLUS when the number of active sessions is already at the limit, S-PLUS wont start. A user may run multiple simultaneous sessions, but each counts towards the limit. This type of licensing allows you to run a session on one machine or to span multiple machines. These sessions are not node-locked. No IFUL.opt file is required for SESS licensing scenario.
26
License Types
S-PLUS Enterprise Server Licensing
Windows and UNIX S-PLUS Enterprise Server supports two different licensing types: Production Server (PS) Licensing PS licensing allows an unlimited number of S-PLUS sessions on a single server-class machine. The license is based on the total number of central processing units (CPUs) on the server. Because an unlimited number of sessions are allowed on the machine, a license manager is not necessary; however, you still must obtain and install a license file to run S-PLUS. PS licensing for S-PLUS Enterprise Server is similar to CS licensing for S-PLUS. For details on CS licensing, go to the section Client/Server (CS) and Concurrent Session (SESS) Licensing (Windows/UNIX) on page 46. Production Concurrent Session (PSESS) Licensing PSESS licenses allow a predetermined number of concurrent sessions to be started on a single server-class machine or a number of machines. The number of CPUs in the server is not regulated. You must configure a license manager to serve licenses for this license type. PSESS licensing is similar to SESS licensing, and no file containing named users is required. The sessions are not nodelocked. See the section Client/Server (CS) and Concurrent Session (SESS) Licensing (Windows/UNIX) on page 46) for more information.
Notes on PS and PSESS Licensing A node-locked host ID is required to obtain a license key for PS licensing. A server host ID is required to obtain a license key for PSESS licensing. Licensing S-PLUS Enterprise Server to use only a subset of the total CPUs (sub-capacity licensing) is not permitted. You must license a total number of concurrent sessions instead, which requires a PSESS license.
Instructions for generating and installing a license key for all S-PLUS and S-PLUS Enterprise Server licensing scenarios follows.
27
GENERATING A LICENSE KEY

You need a license authorization code (LAC) in order to generate the license keys the FLEXnet license manager requires to run S-PLUS. There are two different ways to obtain the license keys: 1. Run the license key wizard on your machine. 2. Access the Web-based Insightful License Fulfillment Center. Concurrent user (CU) licensing for Windows and client/server (CS)/ concurrent session (SESS) licensing for Windows/UNIX licensing scenarios are discussed in the sections thereafter.
Single-User (SU) Licensing (Windows)
The easiest method for most single user (SU) licensed users to generate and install the license key is running the license key wizard, (the next section). You can also obtain a license key through the Insightful License Fulfillment Center, discussed thereafter.
Running the After installation, the first time you attempt to run S-PLUS without a Insightful License license key automatically invokes the Insightful License Fulfillment wizard, as shown in Figure 4.1. Click Next. Key Wizard
Figure 4.1: The Insightful License Fulfillment - Welcome dialog. The dialog is automatically displayed if you attempt to run S-PLUS without a license key.
28
Generating a License Key Input your LAC (which should have been e-mailed to you) and click Next.
Figure 4.2: The Insightful License Fulfillment - Confirm dialog.
Figure 4.3 shows FLEXnet is ready to fulfill your license. Click Finish
Figure 4.3: Insightful License Fulfillment - Ready to fulfill dialog. FLEXnet is ready to fulfill your license when the license authorization code has been confirmed. 29
Chapter 4 License Management The license key has been generated and copied to SHOME/adm/ lic/keys by default, where SHOME is your base installation directory. You can also access the wizard by navigating to Start S-PLUS 7.0 Wizard for License Manager. You can now run S-PLUS. Programs
Accessing the Insightful License Fulfillment Center
This is a Web site hosted by Insightful that allows you to perform a number of tasks related to license management, including generating, re-hosting, and viewing license keys, and editing registration information. You can access this site by pointing your browser to http://keys.insightful.com This prompts you for an authentication method, as shown in Figure 4.4.
Figure 4.4: The Insightful License Fulfillment Center allows you to generate a license key through three separate authentication methods.
30
Generating a License Key The Insightful License Fulfillment Center can process your request to manage your license keys, depending on the information you have. Click one of the following three authentication links: 1. I have a License Authorization Code (beginning with SE, UK, FR, CH, TR, or FX) If you have been issued a license authorization code (e-mailed to you), click this link to generate a license key. Once this key is generated, two options are available for activating the license key: Saving the license key to a file on your machine. When you attempt to run S-PLUS, the license manager looks for this license key, and if correct, S-PLUS starts normally. Having the license key e-mailed to you. You can save it as a file on your machine, as in the first option.
2. I have a Web Registration Code If you have been provided a Web Registration code, you can register via the Insightful License Fulfillment Center using this link. You will be prompted for your special Web Registration Code, which typically begins with WT (but not necessarily). After completing this step, the process becomes identical to 1. and 3. 3. I have a User Name and Password If you used 2. to register, a user name and password were issued to you. If you want to manage your license keys thereafter, you can bypass typing your user information in 2. by clicking this link and entering your user name and password. Note that entering your user name/password brings up all orders linked to your user name, and not just specific orders. This option should be used primarily for checking and updating licenses later. All three links provide the same options for generating, re-hosting, viewing license keys, and editing registration information, as shown in Figure 4.6. We discuss each of these options in more detail below. If you have a License Authorization Code If you have been issued a license authorization code, this link allows you to generate, rehost, and view license key information. For example, you may need to re-host license keys if they are lost after a
31
Chapter 4 License Management hard drive crash, or your registration information may have changed. You can easily perform these and other license management tasks through this link. The first step is to enter your license authorization code and click Login, as shown in Figure 4.5.
Figure 4.5: Enter your license authorization code when prompted.
32
Generating a License Key In the next step (shown in Figure 4.6), you have a number of licensing options. As mentioned, each of these options are available regardless of which authentication method you use (license authorization code, Web Registration code, or user name and password). Note the Authorization Code field is only necessary if you were issued a Web Registration code, which is different from the License Authorization Code (LAC).
Figure 4.6: Once you have successfully entered your license authorization code, Web registration code, or user name and password, you can now generate, re-host, or view a license key.
Generate Licenses Click this button if you meet any of the following criteria: You have never generated a license key for your Insightful product. You want to run a UNIX/Linux version of S-PLUS.
You will not be able to regenerate licenses for products that have already had a license key generated and stored by the Insightful License Fulfillment Center.
33
Chapter 4 License Management Re-host Licenses Click this button if you want to regenerate your license key with new hostid information; for example, you may have replaced your existing desktop computer, and you want S-PLUS to be installed on this new computer. This replaces a previously generated license key, and is only available after contacting Technical Support to request a replacement key. View Licenses Click this button if you want to view your licensed products. You can also filter the information to view specific products, or to obtain replacement license keys for products you already have licensed. Redeem Enter the authorization code and click this button only if you were issued a Web Registration code. There is no need to enter anything in this field for any other type of registration.
Lets look at what each button does in more detail.
34
Generating a License Key Generate Licenses Once you have authenticated your entry, you can perform a number of operations, including generating a license key for your S-PLUS product. Press the button. Figure 4.7 shows the dialog for a typical license key fulfillment. Note this example shows only one S-PLUS product in the order; you could have a number of products in a single order as well as multiple orders.
Figure 4.7: Information on your given product, order number, and host ID is displayed.
Select the checkbox next to the desired product and click Filter Products if you have more than one product. Select Ethernet (for most users) in Node-locked Hostid Type, and enter your host ID in Node-locked Hostid. Click Generate. Note the License Type, Node-locked Hostid Type, and Nodelocked Hostid (lower left in Figure 4.7) will appear differently for S-PLUS Enterprise Server (UNIX and Windows) versions.
35
Chapter 4 License Management If you dont know your hostid, there are two ways to find out: 1. Start Programs S-PLUS 7.0 and select Wizard for License Manager. The hostid for your machine is displayed at the bottom of the screen. 2. Go to SHOME/adm/lic/cmd and double-click lmtools.exe. Click the System Settings tab and the Ethernet Address field contains your hostid. Figure 4.8 shows the confirmation screen to verify this is the product for which you want to generate a license key. Note that your order number and serial number are included for verification. If the information is correct, click Confirm.
Figure 4.8: Confirming your selection for generating license keys.
36
Generating a License Key The next screen (Figure 4.9) provides you with the license key information. Select one of the following two buttons: Save to File Clicking this button prompts you to save the license key file to any local directory on your machine (see Cautions on the following page). The FLEXnet license manager will locate this license key file independent of the key location and confirm its authenticity each time you run S-PLUS. E-mail Enter your e-mail address, and the license key will be e-mailed to you as an attachment. Save the license key file to any directory on your local machine, as in the first option. When you start S-PLUS, the license manager will find the license key, and you can now run S-PLUS. If you move the license key from its default location, this requires setting an environment variable; see the section Cautions on page 38.
Figure 4.9: You can have the license key saved to a file on your local directory or emailed to you as an attachment.
37

Cautions If you rename the license key file in either option, the FLEXnet license manager may not recognize the license key if it does not end with .lic. In general, we recommend that you do not rename this file. It is also strongly recommended that you save your license key in your SHOME/adm/lic/keys directory. You can save your license key anywhere on your machine, but S-PLUS searches this directory first. In addition, if you put the license key elsewhere, you must set an environment variable. For more information, see the section Setting the License Key Environment Variable.
38
Generating a License Key Re-host Licenses In the event you have changed machines, you can rehost the license key. Note that this process is very similar to the section Generate Licenses in the previous step. Press the button, and the dialog in Figure 4.10 is displayed. Select the appropriate product and click the Filter Products button to view specific license information.
Figure 4.10: Select the product that you want to rehost. This is similar to the process in the section Generate Licenses.
When you input the correct information and press Generate, a dialog similar to Figure 4.8 is displayed, which echoes your product information. If the information is correct, click Confirm, and the license key information can be either saved to a file or e-mailed to you, as shown in Figure 4.9.
39
Chapter 4 License Management View Licenses If you simply want to view the license information you have for one specific order or a number of orders, click the The dialog is shown in Figure 4.11. button.
Figure 4.11: License information for one product or a number of products can be displayed as desired. Select the appropriate checkbox and click the Filter Products button to filter the products by order.
40
Generating a License Key Redeem If you have a Web Registration code and want to generate a license key, enter the Web Registration code and click the shown in Figure 4.12. button, as
Figure 4.12: Redeeming a Web Registration code. When you enter this key and click the Redeem button, the associated serial number for the product is displayed (Figure 4.13). This is used to generate a license key.
41
Chapter 4 License Management The next dialog (Figure 4.13) shows the products that you want to register, similar to that in Figure 4.7. Note the serial number of the product (lower right) is displayed, indicating the Insightful License Fulfillment site has successfully matched the product to your Web Registration code. Once you have filtered the products, click the Generate button, and the next dialog provides options for saving the license key, as in the previous step.
Figure 4.13: A license key is generated when the Web Registration code is entered and the product is matched to the serial number (far right).
42
Generating a License Key If You Have a Web Registration Code If you have been issued a Web registration code, click the I have a Web Registration Code and the dialog in Figure 4.14 is displayed. Once you enter your information and click Submit, a dialog (similar to Figure 4.9) is displayed that provides options for license key delivery.
Figure 4.14: Enter all required fields and click Submit to register your account.
If You Have a User Name/Password If you have previously accessed the Insightful License Fulfillment site using the I have a Web Registration Code link, you created a user name and password. If you want to access the Insightful License
43
Chapter 4 License Management Fulfillment Center, you can bypass the second link and click I have a User Name and Password to manage your licenses. You should see a dialog displayed as shown in Figure 4.15.
Figure 4.15: If you have a user name and password from the second link, you can use the I have a User Name and Password link.
Concurrent User (CU) Licensing (Windows)
Concurrent user licensing is a licensing scenario where one central license manager holds license keys and any machine can check a key out. The required server hostid is entered on the Server Hostid field. Note that you can enter a Server 2 Hostid and Server 3 Hostid to provide support as redundant license servers. Normally, these should be left blank. Consult the FLEXnet Licensing End User Guide for more information.
44
Generating a License Key Go to http://keys.insightful.com, and click I have a License Authorization Code. Click Login, enter the license authorization code, as shown in Figure 4.16.
Figure 4.16: Concurrent user (CU) licensing: When the number of requests exceeds the number of issued keys, the request is denied. The remaining steps are similar to single-user (SU) licensing.
45
Client/Server (CS) and Concurrent Session (SESS) Licensing (Windows/ UNIX)
Client/server licensing is a licensing scenario where a single, powerful server machine supports specified S-PLUS users via remote access. Computations take place on the remote server machine. Multiple sessions are allowed per user. Client/server licensing requires a list of named users in a IFUL.opt file so the license manager can keep track of these named users. Note that a concurrent session (SESS) license does not require an IFUL.opt file, and sessions can be run on the server and/or local machines. These sessions are not node-locked.
Figure 4.17: Client/server (CS) licensing: A single, powerful server machine supports named S-PLUS users (stored in IFUL.opt) via remote access. Concurrent session (SESS) licensing is similar but does not require an IFUL.opt file.
Creating the IFUL.opt File for Named Users

46
Some server licenses are licensed for a specific number of users whose login names must be pre-allocated to the FLEXnet license manager. This is the case with client/server (CS) licensing, and the named user
Generating a License Key information is stored in a file accessed by the license manager called IFUL.opt. As mentioned, this file is not necessary for concurrent session (SESS) licensing. It is not necessary to enter these user names when generating your license key; however, they must be configured prior to starting the license manager on your system and using S-PLUS. To allocate named users: 1. Create a new text file named IFUL.opt in the same directory where your license keys reside, which is SHOME/adm/lic/keys by default. 2. In the file, enter the following lines:
GROUP splususers user1 user2 INCLUDE 00 GROUP splususers INCLUDE 00B GROUP splususers INCLUDE 00W GROUP splususers
where user1 and user2 are the names of authorized users (separated by spaces), 00 is the license code for S-PLUS, 00B is the license code for the Big Data library, and 00W is the license code for the S-PLUS Workbench. Only named users (up to the number of licenses purchased) can run S-PLUS. Consult the FLEXnet Licensing End User Guide located at SHOME/adm/lic/cmd/LicensingEndUserGuide.pdf if you have any questions.
Production Server (PS) and Production Concurrent Session (PSESS) Licensing (Windows/ UNIX)
Production server (PS) is a licensing scenario where a single, powerful server machine supports an unlimited number of S-PLUS Enterprise Server users via remote access. Computations take place on the remote server machine. Multiple sessions are allowed per user. Production concurrent session (PSESS) is a licensing scenario where only a fixed number of S-PLUS Enterprise Server users are allowed via remote access.
47
Chapter 4 License Management Note that a production concurrent session (PSESS) license does not require an IFUL.opt file, and sessions can be run on the server and/ or local machines. These sessions are not node-locked.
Figure 4.18: Production server (PS) licensing is used when a single, powerful server machine supports an unlimited number of users via remote access. Production concurrent session (PSESS) licensing is used for a fixed number of users via remote access.
48
Modifying the License Manager for Concurrent User (CU) and Windows Terminal Services Users
MODIFYING THE LICENSE MANAGER FOR CONCURRENT USER (CU) AND WINDOWS TERMINAL SERVICES USERS (CS, SESS, PSESS)
Special instructions are required to install and modify the license manager for concurrent user (CU) licensing and server licensing for Windows Terminal Services users (CS and SESS). This section shows how to change the settings for the FLEXnet license manager for any of these licensing scenarios. Once youve generated a license key, do the following: 1. Go to SHOME/adm/lic/cmd and double-click lmtools.exe. This invokes the LMTOOLS dialog, shown in Figure 4.19.
Figure 4.19: The LMTOOLS dialog. This is used to modify the license manager settings, primarily for concurrent user (CU) licensing and Terminal Services users (CS and SESS).
2. Click the Service/License File tab (displayed by default) and select Configuration Using Services. The field below the option should be blank, indicating that are no current FLEXnet services installed on this machine.
49
Chapter 4 License Management 3. Click the System Settings tab, and in the Hostid Settings group, verify that Ethernet Address is the hostid you used when obtaining your S-PLUS license key from the Insightful License Fulfillment Center (http://keys.insightful.com). This is shown in Figure 4.20.
Figure 4.20: The System Settings page. Verify that Ethernet Address file is the hostid used when you obtained your S-PLUS license key.
50
Modifying the License Manager for Concurrent User (CU) and Windows Terminal Services Users 4. Click the Config Services tab, and enter (or browse to) each of the following fields, and enter the information in Table 4.1
Table 4.1: Enter the following in the Config Services page. Field Service Name Enter
IFUL
Note: This can be any name you select to identify this service on your system. Path to the lmgrd.exe file
C:\Program Files\Insightful\splus70\adm\lic\cmd\ lmgrd.exe C:\Program Files\Insightful\splus70\adm\lic\keys C:\Program Files\Insightful\splus70\adm\lic\logs\ iful.log
Path to the license file
Path to the debug log file
The page should look like Figure 4.21 when complete.
Figure 4.21: The Config Services page. Enter the path for each of the required fields.
51
Chapter 4 License Management Click Save Services when you are done. Note that if S-PLUS is installed in a different directory, you must change the paths you entered above accordingly. 5. Go to the Start/Stop/Reread tab. You should see the service name you specified in Step 4. in this list (Figure 4.22). Make sure it is highlighted and click the Start Server button.
Figure 4.22: The Start/Stop/Reread page. This displays the available services, and you can start, stop, re-read the license file, force a server shutdown, and change advanced settings.
6. The license server should now be running. Close the LMTOOLS dialog.
52
Setting the License Key Environment Variable
SETTING THE LICENSE KEY ENVIRONMENT VARIABLE

S-PLUS needs to know the location of the license manager server for Windows and Unix in order to obtain a license to start up. You can set an environment variable to do this:
IFUL_LICENSE_FILE=@server
where server is the name of the machine where the license manager is running. Note that this environment variable is necessary for Concurrent Session (SESS) licensing on Windows (but not UNIX), since the total number of simultaneous S-PLUS sessions is limited by the number of purchased concurrent session licenses. Setting the license key environment variable is discussed in the following section. You can save the license key to any location on your machine, but if you dont use the default location (SHOME/adm/lic/keys), you have to set the license key variable IFUL_LICENSE_FILE as a system environmental variable.
Windows
When starting S-PLUS for the first time, the Insightful License Fulfillment Wizard appears. When this appears, click Cancel. You should then see the FLEXlm License Finder. Choose Specify the License Server System and click Next. In the box that appears, enter the name or IP address of the machine where the license server is running. Click Next and then Finish to use S-PLUS. The name of the license server is stored in the registry so you don't have to enter it again the next time you start S-PLUS. To set a system environmental variable, go to Start Settings Control Panel, and select System. Select the Advanced tab, click Environmental Variables, and in the User variables field, set the IFUL_LICENSE_FILE and its associated path, as shown in Figure 4.23.
53
Figure 4.23: Setting the system environmental variable.
Setting the environment variable this way is typical for concurrent user (CU) licensing or if the license manager is installed on a different machine. S-PLUS should start normally. If not, check the path and make sure the license key is there. If this doesnt work, contact Insightful Technical Support.
UNIX
The IFUL_LICENSE_FILE=@server environment variable should be added to your .cshrc file when you run the CONFIGURE script. If it has not been added, add it:
setenv IFUL_LICENSE_FILE @server
If you are running on a bash or sh shell, enter the equivalent command:

export IFUL_LICENSE_FILE=@server
When you run S-PLUS, a file called .flexlmrc is added to your home directory. License key information for IFUL_LICENSE_FILE, such as the name(s) of license servers on the network, is stored in this file.
54
Installing the License Manager on a Separate Machine
INSTALLING THE LICENSE MANAGER ON A SEPARATE MACHINE

In some cases, you may want to install the license manager on a different machine than the one where S-PLUS is installed. This is typically done on networks, where a machine is dedicated to license management.
Windows
1. On the machine where you want to install the license manager only, run FLEXnetInstall.exe from the top level of the S-PLUS 7 CD. 2. Request a license key by navigating to http://keys.insightful.com and entering your LAC code. To obtain your hostid, run lmhostid.exe from a Command Prompt (Start Run, and enter cmd). lmhostid is located in the folder where you installed the FLEXnet license manager, which is SHOME/adm/lic/cmd, where SHOME is your installation directory (C:\Program Files\Insightful\splus70 by default). 3. Configure the license manager as shown in the section Modifying the License Manager for Concurrent User (CU) and Windows Terminal Services Users (CS, SESS, PSESS) on page 49. 4. For client/server (CS) licenses, create the text file IFUL.opt. This file pre-allocates authorized users for running S-PLUS; see the section Creating the IFUL.opt File for Named Users on page 46. 5. Install S-PLUS on your client machine(s). Instructions are in Chapter 2, Installing S-PLUS 7 for Windows. 6. Set the environment variable IFUL_LICENSE_FILE as described in the previous section. This completes the installation, and you should now be able to run S-PLUS on one machine and the FLEXnet license manager on another.
55
UNIX
The FLEXNET.TZ file contains the stand-alone FLEXnet license manager. The steps to unpack this tar file and install it on your network follows. 1. Make a directory for unpacking the distribution and cd to it:
mkdir flextest cd flextest
2. As either a regular user (yourself or splus) or as root, unpack the tar file from the CD-ROM into the new directory using tar as follows:
cat /[mount_point]/FLEXNET.TZ | uncompress | tar xvf -
where [mount_point] is the absolute path to the CD-ROM drive. If your system has the zcat command, you can use it to shorten your extraction command (zcat combines the cat and uncompress commands):
zcat /[mount_point]/FLEXNET.TZ | tar xvf -
3. Find your hostid by running the Splus LICENSE script:

Splus LICENSE hostinfo
and copy this hostid. 4. Go to http://keys.insightful.com and click the I have a License Authorization Code link. 5. Enter your license authorization code (LAC) and click Login. 6. Click the Generate Licenses button. 7. Enter your hostid in Node-locked Hostid. Click Generate. 8. Save the license key to a visible location on your network. For example, /homes/username/license_123.lic. 9. Navigate to your FLEXHOME/adm/lic/cmd directory, where FLEXHOME is the location of the FLEX license manager (in this example, the flextest directory). Run the lmgrd utility to install the license manager:
./lmgrd -c /homes/username/license_123.lic
56
Installing the License Manager on a Separate Machine Now you should be able to start, stop, and check the status of the license manager. For example, to get the name of the license host server, run the following:
Example output:
lmstat - Copyright (c) 1989-2004 by Macrovision Corporation. All rights reserved. Flexible License Manager status on Thu 1/1/2005 11:11 License server status: 27000@denny License file(s) on denny: /homes/username/ license_123.lic:
Run this utility to see all available license management options, including features, saving a log file, and viewing the current licensed users on the system:
Splus LICENSE help
Note If you are having difficulty obtaining licenses after installing your license manager, try setting an environmental variable:
setenv IFUL_LICENSE_FILE @denny
Refer to section Setting the License Key Environment Variable on page 53.
57
58
S-PLUS
ENTERPRISE SERVER FOR WINDOWS ARCHITECTURE

Introduction S-PLUS Enterprise Server Overview Elements Included in the Server Installation Elements Included in the Client Installation
5
60 61 61 63
59
INTRODUCTION
As described in Getting Started with S-PLUS Enterprise Server, S-PLUS Enterprise Server is a distributed decision support system based on S-PLUS that enables decision makers to run shared analytical models, view custom reports, and generate graphics from a familiar environment, such as a Web browser or Microsoft Excel. To accomplish this, S-PLUS Enterprise Server provides a very flexible and powerful infrastructure for deploying S-PLUS analytics to a wide variety of client environments. This chapter gives you an overview of this architecture and the elements that make up S-PLUS Enterprise Server.

60
S-PLUS Enterprise Server Overview
S-PLUS ENTERPRISE SERVER OVERVIEW

Elements Included in the Server Installation
S-PLUS Enterprise Server : The central server process, aos.exe, which responds to requests for analysis, gathers and distributes data, and controls S-PLUS in the background. This process can be run as an NT Service or as a desktop application. S-PLUS Enterprise Server Analytic Service can be started from a Web browser by going to http://hostname/statserver (where hostname is the name of the machine where S-PLUS Enterprise Server is installed) and clicking Administer S-PLUS Enterprise Server in the Web tools menu. It can also be started from the Services Manager in the Control Panel or from the S-PLUS Enterprise Server Service Monitor. The application version of S-PLUS Enterprise Server can be started from the S-PLUS Enterprise Server program folder, with the S-PLUS Enterprise Server (As Application) shortcut.
1
S-PLUS: The analytic engine that actually performs the analyses. Analytic database: An internal Adaptive Server Anywhere database bundled with S-PLUS Enterprise Server that is used to store the analytics and requests, as well as the results of each request. The database process is run as an NT Service, the S-PLUS Enterprise Server Database Service. This service is initialy configured to start automatically. S-PLUS Enterprise Server server components: The COM interface through which all clients communicate with S-PLUS Enterprise Server.
S-PLUS Enterprise Server is sometimes used to refer to the entire architecture, and sometimes used to refer solely to the central server application that is responsible for managing the multiple S-PLUS processes and queuing and servicing client requests. The meaning should be clear from the context. 61
1.
Chapter 5 S-PLUS Enterprise Server for Windows Architecture Web Server/ISAPI DLLs: This can be either Microsofts Internet Information Server (IIS) (typically used for development and deployment) or S-PLUS Enterprise Servers internal Web server (used only for debugging configuration issues). The Web server fulfills two roles: Allows execution of server-side scripts (.scr extension). These scripts compose the S-PLUS Enterprise Server Web tools. Responds to direct HTTP requests from remote COM clients.
Both of these tasks are accomplished through ISAPI (Internet Server Application Programmers Interface) DLLs (Dynamically Linked Libraries), which are loaded by the Web server process for specialized processing of HTTP requests. S-PLUS Enterprise Server Web Tools: A set of server-side scripts, written in VBScript and HTML, which enable users to create and run analytics via a Web browser, as well as perform many administrative tasks. These tools are located in the left pane, under S-PLUS Enterprise Server Development, when the URL is invoked. These tools can be accessed after installation at http://servername/statserver where servername is the name of the host machine. Sample clients: Examples of S-PLUS Enterprise Server clients are included in the installation, with examples using Excel, Visual Basic, S-PLUS Publishing Client, ActiveX control, Windows Scripting Host, and Active Server Pages. S-PLUS Enterprise Server Service Monitor: A small application that can be used to start, stop, and monitor the S-PLUS Enterprise Server Analytic Service from the desktop. It can be started from the S-PLUS Enterprise Server folder. S-PLUS Enterprise Server Monitor Service: A service that monitors the S-PLUS Enterprise Server Analytic Service. If a problem occurs, the monitor service will restart the analytic service. The monitor service can be controlled with the Services Manager in the Control Panel.
62
S-PLUS Enterprise Server Overview
Elements Included in the Client Installation
S-PLUS Enterprise Server Client Components: These components form a COM/HTTP bridge that translates COM calls from an application such as Excel into HTTP requests to S-PLUS Enterprise Server. This enables remote communication via the Web from a client machine, without using a Web browser. Sample clients: Same as the server installation.
Figure 5.1 shows how these elements fit together. On the server, S-PLUS Enterprise Server (running as an NT Service) manages one or more S-PLUS processes. When a client makes a request for a particular analytic, S-PLUS Enterprise Server retrieves the analytic from its internal database and sends the analytic, as well as any user input and data from a database or uploaded data files, to S-PLUS. S-PLUS performs the analysis and outputs graphics, text, data, and/or parameter output. This output is received by S-PLUS Enterprise Server and returned to the client. S-PLUS Enterprise Server supports clients through its Web server in a variety of ways. Each client solution is designed to fulfill a different need, representing a variety of possible client deployment scenarios. S-PLUS Enterprise Server is designed to provide application developers maximum flexibility in deploying S-PLUS analytic solutions.
63

C O M - e n a b le d C lie n t ( E x c e l, V is u a l B a s ic , S -P L U S , e tc .) A c t iv e X C o n t a in e r C lie n t ( I n t e r n e t E x p lo r e r , M S W o rd , e tc .)
W e b B ro w se r
A c t iv e X C o n tro l HTTP S -P L U S S e rv e r C lie n t C o m p o n e n ts
HTTP
C lie n t S e rv e r
W e b S e rv e r I S A P I S c r ip t D L L S -P L U S S e rv e r W e b T o o ls ( s e r v e r - s id e s c r ip t s ) IS A P I A P I D LL (fo r C O M /H T T P re q u e s ts )
S -P L U S S e rv e r C o m p o n e n ts fo r S e rv e r
A n a ly t ic D a ta b a se D a ta F ile s
S -P L U S S e rv e r C o rp o ra te D a ta b a se
S -P LU S
S -P L U S
S -P L U S
Figure 5.1: The S-PLUS Enterprise Server architecture. The client, either a Web browser or a remote COM or ActiveX client, talks to the Web server, which invokes an ISAPI DLL to handle the request. These DLLs, in turn, communicate with S-PLUS Enterprise Server through its server components. When S-PLUS Enterprise Server receives a request for an analytic, it retrieves the analytic from its internal database, gathers the inputs and data, and uses S-PLUS to perform the analysis. The results (text, graphics, parameters, and data) are returned to the client. 64
S-PLUS Enterprise Server Overview S-PLUS Enterprise Server provides server components, a server-side scripting interface, and client components. Each of these client architectures can be used with the S-PLUS Enterprise Server: 1. Local COM clients, using server components: These are clients, such as Excel and Visual Basic, which directly manipulate the server components to communicate with S-PLUS Enterprise Server and to submit requests. 2. Server-side scripts accessible via a Web browser: These scripts manipulate the server components via a Web browser. When the Web browser requests a script on the server, the script is interpreted, the commands it contains (which manipulate the server components) are executed, and an HTML page is sent back to the browser. This really is a subset of #1, but it is distinguished because the results are remotely accessible. This can be done through either S-PLUS Enterprise Servers built-in script pages or Microsofts Active Server Pages. Both are ISAPI (Internet Server Application Programmers Interface) DLLs (Dynamically Linked Libraries). ISAPI DLLs are loaded directly by the Web server, and enable customization of the Web servers handling of certain HTTP requests. 3. Remote COM Clients, using client components: In this architecture, a way of remotely manipulating the server components is provided. Insightful provides a S-PLUS Enterprise Server Client installation, which installs what is essentially a redirection layer. The client components expose an object model similar to the server components. However, rather than communicating locally with S-PLUS Enterprise Server, the client components generate HTTP requests that are sent to the Web server. The Web server calls the server components, runs the requested method or property, and then returns the information (as an HTTP response) back to the client components. In this way, COM clients such as Excel or Visual Basic are Web-enabled. Alternatively, DCOM could be used to access the COM objects directly from a remote application. In this case, a method of retrieving the output files would have to be provided.
65
Chapter 5 S-PLUS Enterprise Server for Windows Architecture S-PLUS Enterprise Server provides several examples of clients to serve as tools for quick deployment and as examples for building custom tools. For more information on these clients, see the S-PLUS Enterprise Server Users Guide.
66
DETERMINING YOUR OPTIMAL

S-PLUS
ENTERPRISE SERVER FOR WINDOWS CONFIGURATION

Overview
6
68 70 72 75
Question 1: Can I Use Previously Calculated Results? Question 2: If I Cannot Use Previously Calculated Results, Is an Individual Run of My Analysis Fast Enough? Question 3: Based on My Expected Hit Rate and Analysis Time, How Many Simultaneous Analyses Does My Configuration Need to Handle?
Question 4: Once I Know the Number of Simultaneous Analyses Needed, Should Those Analyses Be Shared Over Multiple Servers? 77
67
OVERVIEW
This chapter discusses the S-PLUS Enterprise Server system requirements, and how to determine the optimal configuration for your deployment scenario. For an overview of requirements for server and client installations, see Chapter 7, Installing S-PLUS Enterprise Server and Client for Windows. S-PLUS Enterprise Server and S-PLUS are an extremely flexible and powerful combination for deploying statistical analyses and graphics to a community of users. Because S-PLUS Enterprise Server and S-PLUS are so flexible, and because every deployment situation is different, it is impossible to provide precise guidelines for what hardware configuration to use. However, this section gives some general guidelines to consider in determining your configuration. From a deployment perspective, the goal is to minimize the response time to an individual user while minimizing costs for hardware, software, and administration. The response time is determined by the actual time it takes to perform your analysis in S-PLUS Enterprise Server, plus any delay introduced by load on the server, where one user is waiting for their analysis to be started while another users analysis finishes. The time to perform the analysis is the sum of the time it takes to obtain the data (which may be negligible or nonnegligible), the time to perform the analysis in S-PLUS, and the overhead introduced by deploying this analysis over the Web through S-PLUS Enterprise Server. These factors can be affected by modifying the following: If possible, accessing previously calculated results instead of calculating the results in real-time. The amount of memory to be installed, and the disk space to be allotted to swap space. The number of processors, their speed, and whether those processors are all on a single machine or spread over multiple servers. The number of simultaneous S-PLUS processes used.
68
Overview The coding of the analysis. In some cases, it might be possible to optimize the S-PLUS code to significantly increase the speed of the analysis. Improving data retrieval time by various methods, including optimizing SQL statements, preprocessing data, getting a faster connection to your database, and so on.
The following sections answer some basic questions regarding S-PLUS Enterprise Server functionality.
69
QUESTION 1: CAN I USE PREVIOUSLY CALCULATED RESULTS?

In some deployment situations, it may be optimal to precalculate the results of your analyses. Using a feature of S-PLUS Enterprise Server that allows you to easily access the results of a previous analysis (including matching input parameters and SQL statements), you can run a batch of analyses before your users access your site. When your users request an analysis, the results are immediately available. For example, assume you have a database containing data updated every 24 hours, and that you want to deploy a set of five analyses. In this example, each analysis has five input parameters, each of which has two unique values (true or false). Also, each analysis uses one of five different SQL statements to retrieve data. That is 5 x 5 x 2 x 5 = 250 unique analyses that might be run on your site. In this case, you can create a batch file to run these analyses, perhaps in Windows Scripting Host or in a S-PLUS Enterprise Server Web script. You can run this batch once a day after the data updates. Whether you can use previously calculated results depends on several factors: How often the data is updated. If the data is updated continuously or your data is coming from data files uploaded by your users, then batch processing is not realistic. The number of possible combinations of analyses. The larger the number, the larger the initial cost in creating the batch architecture, and the longer it takes to recalculate the entire set each time the data is updated. How long it takes to perform the analysis. The longer it takes to perform an analysis, the greater the benefit to the user in precalculating the results.
If it is possible to rely solely on precalculated results, then you require a minimal system configuration, subject to one condition: The time to recalculate your results must be small compared to how often you need to recalculate results. In the above example, if it took five seconds for each analysis on a minimal system, then the total time is five seconds multiplied by 250, or about 21 minutes, which is much
70
Question 1: Can I Use Previously Calculated Results? less than the 24-hour data update time. However, if it took ten minutes for each analysis, then the time is ten multiplied by 250 minutes, or about 42 hours, which is unsuitable for a 24-hour data update time. In that case, you would must improve the speed of your analysis, as discussed in the following section.
71
QUESTION 2: IF I CANNOT USE PREVIOUSLY CALCULATED RESULTS, IS AN INDIVIDUAL RUN OF MY ANALYSIS FAST ENOUGH?
The response time to the user is ultimately determined by how long it takes to run an individual analysis. No matter how many servers you spread your Web site over, the response time to an individual user is never shorter than the time it takes to run an individual analysis. To minimize the response time, you need to minimize the following factors: Time to perform the analysis in S-PLUS. Time to retrieve and prepare the data. Overhead associated with deploying over the Web through S-PLUS Enterprise Server.
To estimate the first factor, simply run your code in a desktop copy of S-PLUS. Running your analysis through S-PLUS Enterprise Server is never any faster than running it on a desktop copy of S-PLUS, because S-PLUS Enterprise Server uses the same S-PLUS engine. Time to execute code in S-PLUS can be improved by following good S-PLUS coding practices, such as using apply instead of for, and avoiding the use of if/then statements. Insightful can provide consulting services to help optimize your S-PLUS code. When using large data sets in S-PLUS calculations, memory and swap space are critical, since S-PLUS can make multiple copies of data while performing analysis, all of which are held in memory. For certain complex models, this could mean ten copies of the data in memory. For example, if S-PLUS performs a complex statistical analysis on a ten MB data set, then the memory requirement would be 100MB, just for the data. For two S-PLUS sessions, running on a dual-processor server, each performing the same analysis:
10 MB data X 10 copies X 2 sessions (data manipulation) + 40 MB X 2 sessions (S-PLUS)
+
10 MB (S-PLUS Enterprise Server)
72
Question 2: If I Cannot Use Previously Calculated Results, Is an Individual Run of My Analysis Fast
10 MB (Web Server)
+
40 MB (2003 Server)
+
10 MB (analytic database) 350 MB
If this were attempted on a system with 256 MB of RAM, the operating system would start swapping memory to disk, greatly reducing performance. Note these numbers are for this example only, and the installation requirements specify a minimum of 1GB of RAM. To estimate your data retrieval time, try duplicating the task in S-PLUS. If you are using data files as input, try importing an example data file. If you are using input from a database, try connecting to your database in the same way S-PLUS Enterprise Server would (that is, locally or over a network, as appropriate) and importing the data. S-PLUS Enterprise Servers data import generally is not any faster than S-PLUS import. Data retrieval time can be improved by: Preprocessing the data, to minimize the amount of data actually retrieved for an analysis. Use the database to subset and process data where possible, rather than bringing over all the data and using S-PLUS to process it. Following good database practices, such as indexing tables, and being aware of the processing implied in complex SQL statements. For data file input, make sure your users are uploading only the columns required for a given analysis. Using the BasedOn feature of S-PLUS Enterprise Server to allow analytics to access the results of previous analytics where possible, to avoid unnecessary duplication of data retrieval and processing.
Note that Insightful can provide consulting on data optimization issues. The overhead introduced by deploying over the Web through S-PLUS Enterprise Server can be minimal or significant, especially if large data sets and/or graphics are involved. This overhead is difficult to estimate, but in general it is small compared to the first two factors.
73
Chapter 6 Determining Your Optimal S-PLUS Enterprise Server for Windows Configuration There is the additional overhead introduced by insufficient system resources caused by multiple users on the same system. Ensuring sufficient system resources is answered in the next question. All of these factors can be improved by making sure you have sufficient RAM to avoid swapping to disk and a fast processor. Realistically, you have a limitation on the speed of the processor you can obtain. Based on that CPU speed and assuming sufficient RAM to avoid swapping to disk, you can determine the minimum time required to perform an analysis, after optimizing S-PLUS code and data preparation. This is the minimum response to your user. If this time is acceptable, proceed to the next question. If not, then you need to do further optimization, or reconsider using precalculated results.
74
Question 3: Based on My Expected Hit Rate and Analysis Time, How Many Simultaneous Analyses
QUESTION 3: BASED ON MY EXPECTED HIT RATE AND ANALYSIS TIME, HOW MANY SIMULTANEOUS ANALYSES DOES MY CONFIGURATION NEED TO HANDLE?
The first step in determining how many simultaneous analyses, S, your configuration needs to handle is to estimate the hit rate, H, on your S-PLUS Enterprise Server. This is the average number of requests or an analysis at a given time. This is not the total number of users on your site. At any given moment, most of your users are spending their time choosing data to run an analysis on, viewing supplementary information, navigating around the site, or viewing results of an analysis they have run. You must estimate the average number of users who run an analysis in S-PLUS through S-PLUS Enterprise Server over a given period of time. Once you estimate H, the expected hit rate, and D, the duration of an analysis determined in the previous step, you can estimate S, the number of simultaneous analyses you need to handle:
S = H x D
For example, lets say that in the previous step, you calculated that your analysis time is 20 seconds, and that you estimate a hit rate of two hits/minute. In that case,
S = H x D, or 2 hits/minute X 1/3 minute = .67
In this case, one S-PLUS process would be sufficient on average to handle demand. On the other hand, if your analysis time is 30 seconds, and your hit rate is 10 hits /minutes, then
S = H x D, or 10 hits/minute X 1/2 minute = 5
In this case, you would need at least five S-PLUS processes to handle demand. Realistically, requests for analyses do not occur evenly spaced over an interval of time. They cluster at certain times of day. For that reason, you may want to estimate H as a peak rate, rather than an average rate, to ensure good performance even during heavy periods. After you have determined the number of simultaneous S-PLUS processes you need, this effectively sets the number of processors you need serving your S-PLUS Enterprise Server application. Because S-PLUS uses the CPU intensively when it is performing an analysis,
75
Chapter 6 Determining Your Optimal S-PLUS Enterprise Server for Windows Configuration we recommend one S-PLUS process per processor under most conditions. There is little to gain by running more S-PLUS sessions than you have processors, because this just results in multiple processes sharing a single CPU, and forcing it to swap between jobs. It is generally more efficient to have one S-PLUS process per processor, and allow S-PLUS Enterprise Server to queue requests and wait for a process to be freed, if more requests are received than there are available processes. There are two exceptions to this rule: If there is insufficient RAM for the total number of S-PLUS processes, it is generally better to decrease the number of S-PLUS processes running on a server. For example, if you were running a complex statistical model on a 100 MB data set, you could easily use a GB of RAM. Unless you have 2 GB of RAM on your dual processor machine, it would be better to only run one S-PLUS process. If a given S-PLUS thread spends a long time being idle, then you can increase the ratio of S-PLUS processes to processors. For example, if each analysis needs to wait for 60 seconds for a remote database to process a SQL statement and return data, then the associated S-PLUS process is idle. In that case, you can increase the number of S-PLUS processes.
76
Question 4: Once I Know the Number of Simultaneous Analyses Needed, Should Those Analyses Be
QUESTION 4: ONCE I KNOW THE NUMBER OF SIMULTANEOUS ANALYSES NEEDED, SHOULD THOSE ANALYSES BE SHARED OVER MULTIPLE SERVERS?
After you have determined the number of simultaneous analyses, the next question is to determine how the processors running those analyses should be arranged: all on one machine, or spread over multiple machines? If S is two or less, the answer is easy: a dual-processor machine is sufficient. Even if S = 1, Insightful recommends using a dualprocessor machine for best performance, since other processes, such as the Web server, the internal database, and S-PLUS Enterprise Server itself, consume CPU time. If S is greater than four, then the answer is probably multiple servers, each a dual or quad processor. In choosing between a pair of dual-processor machines and a single quad-processor, there are several factors to consider. Availability of sufficient RAM for each analysis. Relative cost of the hardware. Relative cost of licensing S-PLUS Enterprise Server in the different configurations. Administration costs.
Administration costs are difficult to estimate, but costs increase with multiple servers. Each server requires installation of the relevant software and requires duplication of the analytic. S-PLUS Enterprise Servers Web tools do provide an easy method to copy analytics from one S-PLUS Enterprise Server to another. In addition, some method is required for load-balancing/clustering the servers. This may be trivial, such as giving half your users one URL and half another. Or, it may use software such as Microsoft Windows Load Balancing Service, which integrates multiple Web servers into a single, virtual Web site (this is described in Chapter 9, Advanced Topics. One advantage of multiple servers is generally lower hardware costs, which can be applied incrementally. For example, two dual-processor servers can cost less than a quad processor, and you dont have to buy
77
Chapter 6 Determining Your Optimal S-PLUS Enterprise Server for Windows Configuration both dual-processors at the same time. Another advantage is better reliability, since a failure on a single machine would not bring the entire site down. The process of determining your optimal S-PLUS Enterprise Server configuration is summarized in the flow chart on Figure 6.1.
R e q u ir e s R e a l T im e a n a ly s is ? No M in im a l S y s te m R e q u ir e m e n t s
Yes D e t e r m in e a n a ly s is t im e , D
A n a ly s is T im e , D , a c c e p t a b le ?
No
O p t im iz e S - P L U S c o d e a n d d a t a r e t r ie v a l t o d e c r e a s e D
Yes
E s tim a te H it r a t e , H I n it ia liz e S = 1
Is S = H x D ?
No
In cre m e n t S
Yes E ith e r 1 q u a d or 2 dual p ro ce sso r se rve rs
One dual p ro ce sso r se rve r
S= 1 or 2 N um ber of CPUs = S
S >= 3
Figure 6.1: Determining your optimal S-PLUS Enterprise Server configuration. In the chart, H = actual analysis hit rate in hits/minute, D = duration of an individual analysis, S = number of S-PLUS processes used. First, determine whether you can use previously calculated results. If not, determine your analysis time. If the time is too long, decrease it by optimizing S-PLUS code and data retrieval if possible. Once the analysis time is acceptable, determine the number of S-PLUS processes from the analysis time and the hit rate. This figure determines the number of processors you need. 78
INSTALLING ENTERPRISE SERVER AND CLIENT FOR WINDOWS

Introduction
S-PLUS
7
80 81 82 84 84 84 85 87 88 90 91
Server Installation Prepare the Server Install S-PLUS Install S-PLUS Enterprise Server Software for the Server Complete the Installation Test the Installation Migrating from an Existing Copy of S-PLUS Enterprise Server S-PLUS Enterprise Server Directory Structure S-PLUS Enterprise Server ODBC Data Sources Client Installation
79
Chapter 7 Installing S-PLUS Enterprise Server and Client for Windows
INTRODUCTION
This chapter provides an overview of installing S-PLUS Enterprise Server. For a more detailed discussion of system requirements for your particular setup, see Chapter 6, Determining Your Optimal S-PLUS Enterprise Server for Windows Configuration.
80
Server Installation
SERVER INSTALLATION
Before you start the installation, make sure you have the following: S-PLUS Enterprise Server CD-ROM, which contains the S-PLUS installation and the S-PLUS Enterprise Server installation. The S-PLUS serial number, which is on the CD case for the S-PLUS Enterprise Server CD-ROM. The TCP/IP networking protocol, which is used for your organizations intranet and Internet services, so that you can use a Web browser. Administrative privileges on the server.
Installing S-PLUS Enterprise Server requires four major steps: 1. Prepare the server. 2. Install the S-PLUS Enterprise Server software. 3. Complete the installation. 4. Test the installation. These steps are explained in more detail in the following sections.
81
Prepare the Server
To prepare the server: 1. Make sure your system meets the requirements listed in Table 7.1. If you are using Graphlets , check the recommendations in Table 7.2.
Table 7.1: Installation requirements. Required Windows 2000 Server

Recommended
Windows 2000 Advanced Server
Windows Server 2003 Standard Edition Windows Server 2003 Enterprise Edition SP2 with Security Pack 1 (Windows 2000 Server and Windows 2000 Advanced Server only) 1GB of RAM One or more processors, minimum 1Ghz 500 MB free disk space (50 MB for S-PLUS Enterprise Server program files, 450 MB for S-PLUS program files) Approximately 1GB space reserved for the system swap file SP4 (note that SP3 and higher includes Security Pack 1 and higher) 2GB of RAM Two or more processors An additional 100 MB disk space for temporary files created during processing Approximately 2X the amount of reserved RAM for the system swap file
82
Server Installation
Table 7.1: Installation requirements. (Continued) Required Microsoft IIS Web server
Recommended IIS 5.0 for Windows 2000 Server and Windows 2000 Advanced Server IIS 6.0 for Windows Server 2003 Standard Edition and Windows Server 2003 Enterprise Edition
Internet Explorer 5.01 or higher Table 7.2: Optional recommendations. Optional Graphlets
Internet Explorer 6.0 or higher
Recommendation Windows 2000 Server includes the Microsoft Java Virtual Machine (MJVM), and Graphlets display correctly. Windows Server 2003 does not support MJVM, and requires JRE ( J2SE v 1.4.2_04) for Graphlets to display. You can download the JRE from Sun's Web site (www.java.sun.com)
E-mail results
Make sure that SMTP (Simple Mail Transfer Protocol) is installed and running.
2. Make sure you are logged on to your server as an account with Administrator privileges. 3. Install IIS (if necessary).
83
Chapter 7 Installing S-PLUS Enterprise Server and Client for Windows 4. Remove older editions of S-PLUS Server. See the section Migrating from an Existing Copy of S-PLUS Enterprise Server on page 87 for more information. 5. Close all other applications. During installation, S-PLUS Enterprise Server automatically stops and restarts IIS (if it is running) in order to configure it. 6. Insert the CD. The main setup screen should appear, with buttons to install S-PLUS Enterprise Server (server and client versions) and S-PLUS.
Install S-PLUS
Note
Install S-PLUS. Refer to Chapter 2, Installing S-PLUS 7 for Windows.
After installing S-PLUS and before you install S-PLUS Enterprise Server for Windows, you must first launch S-PLUS to authorize the product copy.
Install S-PLUS Enterprise Server Software for the Server

Note
To install the S-PLUS Enterprise Server software for the server: 1. From the main setup screen, click the S-PLUS Enterprise Server installation button for the server.
You need to install Web components only if you are building Web applications, not for remote access or batch work.
Complete the Installation
To complete the installation: 1. Reboot if prompted. If not prompted to reboot, you may start the S-PLUS Enterprise Server Analytic Service directly from the closing dialog of the installation. 2. After installation is complete, close the main setup window.
84
Server Installation 3. Install Adobe Acrobat Reader if you do not have it installed.
Note You must install Adobe Acrobat Reader to display the PDF documentation for S-PLUS and S-PLUS Enterprise Server for Windows.
Test the Installation
To test the installation: 1. Open a Web browser and enter the following URL: http://hostname/statserver where hostname is the name of the server where S-PLUS Enterprise Server is installed. The S-PLUS Enterprise Server Web tools page should appear, as shown in Figure 7.1.
Figure 7.1: The Web tools page is displayed when you enter the URL of the S-PLUS Enterprise Server host.
85
Chapter 7 Installing S-PLUS Enterprise Server and Client for Windows 2. If the Web page reports that the S-PLUS Enterprise Server Analytic Service is stopped, click Administer S-PLUS Enterprise Server in the left frame. Then, in the page loads in the main frame, click Start S-PLUS Enterprise Server Analytic Service. 3. Click Examples in the left frame and then Display up-tothe-minute S-PLUS graphics in a web page. 4. After a few seconds, you see graphics and an HTML table output by the request.
Figure 7.2: Confirmation that S-PLUS Enterprise Server has been successfully installed by clicking Display up-to-the-minute S-PLUS graphics in a web page.
You have confirmed that S-PLUS Enterprise Server has been successfully installed, so proceed to Chapter 2, A Guided Tour of S-PLUS Enterprise Server in Getting Started with S-PLUS Enterprise
86
Server Installation Server for Windows. If you encountered any problems during installation, refer to Chapter 10, Troubleshooting Guide or contact Tech Support.
Important Note for Windows Server 2003 Standard Edition and Enterprise Edition Users If a Windows Server 2003 does not have Internet Explorer Enhanced Security Configuration (IEESC) enabled, then no steps to modify security settings are necessary. If the Windows Server 2003 does have IEESC enabled, then you might need to follow these steps to view the S-PLUS Enterprise Server Web pages: 1. 2. 3. 4. 5. In Internet Explorer, select Tools Click the Security tab. Select Trusted sites. Click Custom Level. Scroll to User Authentication/Logon and select Automatic logon with current username and password. Internet Options.
Follow steps 1-3 above, then click on Sites to add http://hostname/statserver to the Trusted sites zone, where hostname is the name of the server where S-PLUS Enterprise Server is installed.
Migrating from an Existing Copy of S-PLUS Enterprise Server
To migrate your old analytics and files from your existing copy of S-PLUS Enterprise Server to the new version, you must create a back up of the following files and directories: sshome\ServerFiles\aos6.db or aos.db (where sshome is the location of your server files): This is the internal Adaptive Server Anywhere database that stores the analytics. sshome\wwwroot\aocwiz: Any analytics you create via the Web wizards are stored in their own subdirectories here. Make back-ups of any custom Web pages, such as custom copies of front-end scripts, or insertATROdyn scripts.
87
Chapter 7 Installing S-PLUS Enterprise Server and Client for Windows If you changed sshome\SplusWin\sshome6, such as modifying .First or changing some of S-PLUS Enterprise Server's internal S-PLUS functions, you should make a backup copy of these functions. These functions need to be recreated after installation.
It is not possible to install S-PLUS Enterprise Server on a machine with a previous edition. You must uninstall. Once the new installation is complete, move the files and directories from the above backup to the corresponding locations in the new installation directories. In the event you need to revert to the old version, it is recommended you uninstall the new version, reinstall the old version, and restore the files and directories above to their corresponding locations.
.
Important Note When Upgrading to S-PLUS Enterprise Server 7 from an Older Version When installing this version for the first time, you are not prompted whether to overwrite an aos6.db or aos.db file, because this version uses aos6.db, while older versions use aos.db; however, this means your analytics are not visible immediately after installation. You need to copy your analytics from the old database file (aos.db) to the new database file (aos6.db). Insightful has provided a wizard to do this easily. It can be found in the Web tools menu under Administer S-PLUS Enterprise Server by clicking Migrate analytics from older version of S-PLUS Enterprise Server database in the main frame. Due to security changes in this release, you might need to enter an NT username and password to access the administration tools, if you are prompted to do so.
S-PLUS Enterprise Server Directory Structure
S-PLUS Enterprise Server installs a set of directories that it uses for various purposes. This section gives a brief overview of this directory structure: S-PLUS directories Location: Dependent on S-PLUS installation. Contents: S-PLUS executable, and database directories that contain the various functions that are provided with S-PLUS. Default: C:\Program Files\Insightful\splus70. Location: Dependent on S-PLUS Enterprise Server installation.
S-PLUS Enterprise Server directories
88
Server Installation Default: C:\Program Files\Insightful\splus70server. Clients: Contains various sample clients used to access S-PLUS Enterprise Server. Subdirectories include Excel, SPlus, VBClient, and Wsh (for Windows Scripting Host). Cmd: Contains S-PLUS Enterprise Server executable (Aos.exe) and required dynamically linked libraries (DLLs). Database: Contains supporting information for the Adaptive Server Anywhere internal database. LogFiles: Contains the log files that detail the S-PLUS Enterprise Server status, in file Aosmmdd.log, where mm is the month and dd is the date. ServerFiles: Contains internal database used to store analytics, in file Aos6.db. SPlusWin: Contains the sshome6 directory that has a set of S-PLUS functions used by S-PLUS Enterprise Server to execute analytics. tmp: Holds temporary working directories used by S-PLUS when running an analytic. wwwroot: Contains various files used by Web clients. webdbclient: Contains scripts used for analytic development, administration, and deployment. aocwiz: Holds directories for new analytics created by script pages. aoclientwiz: Holds user interface pages, which can be deployed to allow other users to run analytics. webaocs: Contains sample analytics provided with the S-PLUS Enterprise Server.
89
S-PLUS Enterprise Server ODBC Data Sources
When you install S-PLUS Enterprise Server, six data sources that refer to the runtime version of Adaptive Server Anywhere (the internal database) are installed. These data sources include the following: Analysis Server: Used by S-PLUS Enterprise Server for processing analytics, writing results, and accessing analytic information. This is the data source name (DSN) used by S-PLUS Enterprise Server. Analysis Client: Used by S-PLUS Enterprise Server for server components to add analytics and retrieve results. Analysis Author: Used by S-PLUS Enterprise Server for the server components to publish analytics to S-PLUS Enterprise Server. Analysis Previous: Used by the S-PLUS Enterprise Server Migration Wizard to copy analytics from an older version of the internal database. Analysis Backup: Used by the S-PLUS Enterprise Server tools to create a backup copy of the analytics. MSS Samples: Used to store data for demonstration analytics.
The S-PLUS Enterprise Server for server components are used by client applications to communicate with the internal database, and so using these DSNs directly is usually not necessary.
90
Client Installation
CLIENT INSTALLATION
If you plan to use only Web browsers as clients to the S-PLUS Enterprise Server, then no special installation is required on client machines. Merely launch your Web browser and point to the following URL: http://hostname/statserver where hostname is the name of the S-PLUS Enterprise Server machine. However, if you intend to use any of the other client examples, such as the S-PLUS Publishing Client or the Excel Client, you need to run the client installation on the client machine. This installs the S-PLUS Enterprise Server client components, which enables remote HTTPbased communication with the S-PLUS Enterprise Server from COM clients. The S-PLUS Enterprise Server Client installation is available from the Master Setup window on the S-PLUS Enterprise Server CD. Click the S-PLUS 7.0 Server Client Only button to start the installation.
Figure 7.3: Installing the S-PLUS Enterprise Server client.
91
Note All of the S-PLUS Enterprise Server client tools are included as part of the S-PLUS Enterprise Server installation. It is not necessary to run the client installation on the server after installing S-PLUS Enterprise Server.
During installation, you are prompted to specify the following information: Host Name: The name of the server on which S-PLUS Enterprise Server is installed. Port: The port number on which S-PLUS Enterprise Server is installed. This is 80 by default. URL: The virtual mapping that the Web server uses to route requests from the S-PLUS Enterprise Server COM client to the ISAPI DLL that handles the requests. The default is /ssbin/ webapi.dll. We strongly recommend that you do not change this value.
Figure 7.4: S-PLUS Enterprise Server client setup.
92
Client Installation These entries determine the form of the default profile stored in your statsvr.inf file. The S-PLUS Enterprise Server COM clients look for the statsvr.inf file in your Windows\system, Windows\system32, or WINNT\system32 directory. This file contains the profile information that specifies which S-PLUS Enterprise Server to use. S-PLUS Enterprise Server installed on same machine: LocalTransport is the default transport profile name. S-PLUS Enterprise Server Client only installed: Client1 is the default transport profile name.
For example, this statsvr.inf file has two profiles: LocalTransport, which uses ODBC to connect to a S-PLUS Enterprise Server on the same machine, and InetTransport, which connects to a remote S-PLUS Enterprise Server at statserver.insightful.com via the Web. The default transport value is specified to be InetTransport.
[Profiles] NumProfiles=2 Profile1=InetTransport Profile2=LocalTransport Default=InetTransport [InetTransport] Description=Inet Sample Profile Transport=Inet Host=statserver.insightful.com Port=80 BaseURL=/ssbin/webapi.dll [LocalTransport] Transport=ODBC Description=ODBC-bsed Profile AdminDSN=Analysis Server AdminLogin=spserver2 AdminPassword=spserver2 AuthorDSN=Analysis Author AuthorLogin=spauthor2 AuthorPassword=spauthor2 UserDSN=Analysis Client UserLogin=spclient2 UserPassword=spclient2
For more information on client configuration and the statsvr.inf file, see Chapter 9, Advanced Topics.
93
94
ADMINISTERING S-PLUS ENTERPRISE SERVER FOR WINDOWS

Overview
8
97 98 98 99 99 100 101 102 103 103 104 105 106 108 108 110 110 111 112 114 114 115
Administering S-PLUS Enterprise Server Through the Web Tools Main Administration Page Basic Administration of S-PLUS Enterprise Server Analytic Service Analytic Information Section Request Information Section General Information Section S-PLUS Enterprise Server Configuration Page Service Configuration Database Settings Log File Settings Server Options Housekeeping Settings Internal Web Server Configuration Web Page Settings S-PLUS Enterprise Server Storage Options AOSUtil Logging Periodic Analytic Checking Database Settings Page Other Methods of Controlling S-PLUS Enterprise Server Controlling S-PLUS Enterprise Server Through the Services Manager Controlling S-PLUS Enterprise Server Through the S-PLUS Enterprise Server Analytic Service Monitor
95
Chapter 8 Administering S-PLUS Enterprise Server for Windows Controlling S-PLUS Enterprise Server Through the S-PLUS Enterprise Server Monitor S-PLUS Enterprise Server Maintenance Backing Up or Restoring S-PLUS Enterprise Server
116 117 118
96
Overview
OVERVIEW
You can run S-PLUS Enterprise Server as a Windows started and stopped from:

Service,
The Windows Control Panel, using the Services Manager. The S-PLUS Enterprise Server program folder, using the S-PLUS Enterprise Server Service Monitor. The Administer S-PLUS Enterprise Server link, using the S-PLUS Enterprise Server Web tools.
You can also run S-PLUS Enterprise Server as a desktop application, started from S-PLUS Enterprise Server (as application) shortcut in the S-PLUS Enterprise Server program folder. This usage is not recommended, because not all functionality is available. S-PLUS Enterprise Server cannot be run as an application and a service at the same time, and it fails to start if this is attempted. The most common tasks in administering S-PLUS Enterprise Server include: Monitoring S-PLUS Enterprise Servers processing of requests by viewing the processing log that S-PLUS Enterprise Server produces. Enabling the connection of S-PLUS Enterprise Server to an external database, to allow data retrieval for an analytic. Cleaning up S-PLUS Enterprise Server by deleting previous requests.
All of these functions, and many more, can be performed remotely through a Web browser. To configure S-PLUS Enterprise Server, open a Web browser to: http://hostname/statserver where hostname is the name of the server on which S-PLUS Enterprise Server is installed. Click Administer S-PLUS Enterprise Server. You may be prompted to provide a Windows user name and password.
97
ADMINISTERING S-PLUS ENTERPRISE SERVER THROUGH THE WEB TOOLS

Main Administration Page
Using the Administration page, you can view the analytics and requests that are currently stored in the S-PLUS Enterprise Server, delete old analytics and requests, and view log and error files. You can stop and start the Analytic Service, and you can configure various S-PLUS Enterprise Server settings. The Administration page is divided into the sections shown in Figure 8.1.
Figure 8.1: Central Web page for administering S-PLUS Enterprise Server.
98
Administering S-PLUS Enterprise Server Through the Web Tools
Basic Administration of S-PLUS Enterprise Server Analytic Service
Displays current state of service (Start Pending, Running, Stop Pending, or Stopped): Use to Stop or Start the service. S-PLUS Enterprise Server Configuration: Use to set S-PLUS Enterprise Server parameters (described in more detail on the following pages). View Current Log: Displays the current S-PLUS Enterprise Server log file.
Analytic Information Section
Displays the number of published analytics with the following links: Delete individual analytics: Removes analytics from S-PLUS Enterprise Server. Use to choose whether to delete just the copy of the analytic in S-PLUS Enterprise Servers internal database, or to delete the copies on the file system as well. Copy analytics to another S-PLUS Enterprise Server: Copies analytics from this S-PLUS Enterprise Server to another, which is useful for moving from a development platform to deployment. Migrate analytics from older version of S-PLUS Enterprise Server database: Users of older versions of S-PLUS Enterprise Server (StatServer 6.2 and earlier) can migrate their analytics to S-PLUS Enterprise Server. Backup or Restore analytics: Copies analytics to a backup database file, splus70server\ServerFiles\aos6backup.db. This option is useful for archiving and restoring older versions of analytics, and for copying a large set of analytics from one S-PLUS Enterprise Server to another. View Analytic Tables: Displays the following list of links used to view these analytic tables in S-PLUS Enterprise Servers internal database: Delete individual analytics: Removes analytics individually. Copy analytics to another S-PLUS Enterprise Server: Copies analytics for processing on another server. View Analytic Table: Displays the entire list of analytics on the S-PLUS Enterprise Server.
99
Chapter 8 Administering S-PLUS Enterprise Server for Windows View Analytic Client Table: Displays the supplementary information specified in the Modify Author Interface Section. View Analytic SQL Table: Displays analytic-specified (server-specified) SQL statements associated with an analytic. View Analytic Libraries Table: Displays the library name associated with each analytic.
Republish Sample analytics: Republishes the example analytics provided with S-PLUS Enterprise Server.
Request Information Section
There are two links in the Request Information section: Delete Requests: Deletes the collection of previous requests and their results. This should be done frequently, unless you need to access the results of previous requests. View Request Tables: Displays the following request tables in S-PLUS Enterprise Servers internal database: Delete Requests: Same as above. Browse the results from previous requests: Displays the analytics that have been run recently, their status, and the results they returned. View Request Table: Displays the list of previous requests stored in the S-PLUS Enterprise Server, and any input parameters. View Request SQL Table: Displays the list of clientspecified (request-specified) SQL statements for database input/output associated with the requests stored in the S-PLUS Enterprise Server. View Request Input Data Files Table: Displays the list of input data file information associated with the requests stored in the S-PLUS Enterprise Server. View Request Results Table: Displays the list of results generated by previous requests stored in S-PLUS Enterprise Server, including the status (which indicates if a request completed successfully) and any output parameters.
100
Administering S-PLUS Enterprise Server Through the Web Tools View Request Output Data Files Table: Displays the list of output data file information associated with the requests stored in the S-PLUS Enterprise Server. View Request Output Graphic Table: Displays the list of graphics generated by requests stored in S-PLUS Enterprise Server. View Request Output Text Table: Displays the list of text output generated by requests stored in S-PLUS Enterprise Server.
General Information Section
Find information or diagnostics and viewing error, log, and Readme files: Modify S+ startup actions: The sshome6\S.init file sets the actions S-PLUS Enterprise Server performs on startup. Use this link to define the startup actions for S-PLUS from the Web tools (rather than having to modify the .First function). View S-PLUS output on startup: Displays the output each time you start an S-PLUS session. Get S-PLUS Diagnostics: Runs an analytic on the server to check the status of S-PLUS, and provide information such as the version, the search path, and the current .First function. View S-PLUS Enterprise Server tmp directories: Displays the content of the tmp directory. View S-PLUS Error files: Displays all errors generated by the S-PLUS processes since the S-PLUS Enterprise Server time was restarted. While errors are normally returned when an analytic fails, this list is a useful archive of previous error messages. This link displays the error messages stored in splus70server\tmp\n\all.err, where n is an integer for each running S-PLUS process. View S-PLUS Enterprise Server Log files: Displays the S-PLUS Enterprise Server log files, which are usually stored in splus70server\LogFiles\aos####.log, where #### is the date (mmdd) of the log file. View NTFS Permissions Log File: Displays the permissions set for the log file.
101
Chapter 8 Administering S-PLUS Enterprise Server for Windows View AOSUtil Log File: Displays the AOSUtil log file. View Readme files: Displays various S-PLUS Enterprise Server readme.txt files.
For more information, go to the Administer S-PLUS Enterprise Server link in Web tools.
S-PLUS Enterprise Server Configuration Page
Clicking S-PLUS Enterprise Server Configuration in the main Administration page displays the page shown below.
Figure 8.2: S-PLUS Enterprise Server Configuration page.
You can configure many S-PLUS Enterprise Server settings in this page. The settings are grouped according to their function.
102
Service Configuration
Service StartUp determines whether the S-PLUS Enterprise Server Analytic Service can be started manually only (Manual), whether it is started automatically when the server reboots (Automatic), or whether it cannot be started at all (Disabled). If you want to use S-PLUS Enterprise Server as a desktop application, then you should set the service to Disabled. Using this option, clients, which normally do not submit requests if the S-PLUS Enterprise Server Analytic Service is not running, can submit requests normally. Using this option, you can make the S-PLUS Enterprise Server Analytic Service dependent on another service by providing the internal name (not the display name) of another Windows Service. Find the internal name of a service in the registry.
Note Both the analytic and database service are configured to automatically start upon system startup. Previously, you had to manually start the analytic service. Unlike previous versions, by default setup now configures both services to automatically restart one minute after any serious failure in the service. To change this configuration, in Windows, click Start, and then click Administrative Tools Services. Right-click the Analytic or Database service, and then select Properties. In the Properties dialog box, click the Recovery tab, and then change the service recovery options.
Database Settings
You can view and change these settings only on this page. Click Modify to browse to the Modify Database settings page, where you can add new databases to S-PLUS Enterprise Servers database connections, change passwords, and test the database to ensure its accessibility.
103
Log File Settings
S-PLUS Enterprise Server generates a new log file daily in splus70server\LogFiles. The current log file path is displayed. The administrator can control the amount of information written to the log using the option Detail Level. The settings are explained below.
Table 8.1: Log File Settings. Setting No messages Events and Errors Description No information written to log file. Events and errors, such as queuing and processing requests, are written to the log. In addition to the above, generated warnings are written to log. This is the recommended setting. Detailed information is provided, which may be helpful in resolving problems. Maximum information is provided.
Events, Warnings, and Errors
Debug
Verbose Debug
104
Server Options
This section displays key paths used by S-PLUS Enterprise Server.
Figure 8.3: Server Options in the S-PLUS Enterprise Server Configuration page.
Server Files: Displays the location of S-PLUS Enterprise Server files. S-PLUS Path: Displays the location of S-PLUS executable. S-PLUS Working Directory: Displays the location of the working directory that S-PLUS uses. Reuse S-PLUS processes: Indicates whether S-PLUS Enterprise Server uses its S-PLUS processes repeatedly (True) or restart S-PLUS each time an analysis is run (False). This setting can be configured only when running S-PLUS Enterprise Server as an application. S-PLUS Restart Interval: Controls how often the S-PLUS processes are restarted by S-PLUS Enterprise Server to clean up any memory growth. Default is 5 hours. Request Timeout Interval: Sets the time limit for a request. Any analysis that exceeds this limit is terminated. Default is 10 minutes.
105
Chapter 8 Administering S-PLUS Enterprise Server for Windows Maximum Request Age: Sets a time limit if surplus requests are queued when more requests come in than S-PLUS processes are available. When a process becomes available, the request is retrieved from the queue, and processed. If a request has been sitting in the queue for longer than this time limit, it is deleted and not processed. Default is 10 minutes. Load library big data: Determines whether the S-PLUS bigdata library is loaded by the S-PLUS processes. Default is Disabled. Select Enabled if the bigdata capabilities are needed by the S-PLUS processes. For more information about the bigdata library, see the S-PLUS Enterprise Developer Users Guide. Daily Log: Displays the path to the daily log file. To select another log file, click Browse, and then click Update. Delete unprocessed requests on start up: Controls whether S-PLUS Enterprise Server deletes or processes any old queued requests that it finds during startup. Preserve tmp dirs on restart: Determines whether S-PLUS Enterprise Server tmp directories are preserved when restarting S-PLUS Enterprise Server. By default, they are deleted. If you run many analytics that access the S-PLUS objects created by previous requests, you may wish to preserve these tmp directories. Internal Web Server: Determines whether the development Web server included in S-PLUS Enterprise Server is started. Note that the internal Web server should be used only for debugging configuration issues. Number of S-PLUS Processes: Indicates the number of S-PLUS sessions running concurrently. This should generally be equal to the number of CPUs your server has, subject to the exceptions discussed in Chapter 6.
Housekeeping Settings
This section determines how often S-PLUS Enterprise Server performs various clean-up tasks. Analytics can create either reusable or disposable output. This option is set when the analytic is created or edited by checking the box for Keep the results of this analytic for use by future requests. Each request has two sets of output that are cleaned up by housekeeping. The first is Results, representing the
106
Administering S-PLUS Enterprise Server Through the Web Tools graphic, text, and data file output produced by the analysis and stored in the internal database. This output is available as previously-calculated results. The second is Objects, representing S-PLUS objects created by an analysis and saved to disk. These objects are stored on the file system and can be obtained by subsequent requests by using the BasedOn feature. For more information about previously-calculated results and the BasedOn option, see Chapter 8, S-Plus Programming for Analytic Developers, the section Making the Results of an Analytic Available to a Subsequent Analytic on page 158. Using this section, you can tune individual Housekeeping functions.
Figure 8.4: Housekeeping settings.
Housekeeping: Serves as a global setting to turn housekeeping completely off or on. If set to on, Purge after determines the interval for the system to perform housekeeping duties. For example, using Purge after, you can direct the system to check each object every 2 minutes and determine (based on the individual time settings) whether that object is old enough to clean up. Purge Reusable Result: Purges the results of a reusable request from the internal database if selected, at the interval specified by Purge after.
107
Chapter 8 Administering S-PLUS Enterprise Server for Windows Purge Reusable Object: Purges the S-PLUS objects and temporary files of a reusable request from the file system if selected, at the interval specified by Purge after. Purge Disposable Result: Purges the results of a disposable request from the internal database, at the interval specified by Purge after. Purge Disposable Object: Purges the S-PLUS objects and temporary files of a disposable request from the file system, at the interval specified by Purge after.
Internal Web Server Configuration
This section displays the internal Web Server parameters (if it is enabled in the Server Options section). Use to set the port number of the internal Web server.
Figure 8.5: Internal Web server parameters.
Web Page Settings
This section displays Web tools parameters, including system paths. If these paths are not correct, it indicates a problem with installation.
108
Figure 8.6: Web page settings.
Display BasedOn: Determines whether the Web pages used to run analytics provide the option to base a request on a previous analysis. Web Time Out in seconds: Determines how long S-PLUS Enterprise Server waits for the analytic to complete before returning results to the client.
109
S-PLUS Enterprise Server Storage Options
This section controls how S-PLUS Enterprise Server processes input and output. To manage results better, you can compress and store the input/output data in the database; to improve performance you can store just the path.
Figure 8.7: Storage options.
Store Input Data files in database: Determines whether the entire input data file is stored in the database, or only the path of the tmp directory. This path can reflect a temporary local location if the file is uploaded from a client. Store Output Data files in database: Determines whether the entire output data file is stored in the database, or only the path in the tmp directories. Store Output Graphic files in database: Determines whether the entire output graphic is stored in the database, or only the path in the tmp directories. Store Output Text files in database: Determines whether the entire output text file is stored in the database, or only the path in the tmp directories.
AOSUtil Logging
This section determines whether the database transactions executed by the COM objects against the internal database are logged or not, and the detail level of the logging. Only enable this for debugging severe problems, as its use impacts performance. Information is
110
Administering S-PLUS Enterprise Server Through the Web Tools logged to splus70server\LogFiles\aosUtil.log, which can be viewed from the Administer S-PLUS Enterprise Server link on the Web tools menu.
Figure 8.8: AOSUtil Logging.
Periodic Analytic Checking
This section displays various parameters used by the S-PLUS Enterprise Server Monitor Service. The monitor is controlled in the Service Manager in the Control Panel.
Figure 8.9: Periodic Analytic Checking.
Test Analytic Interval (seconds): Controls how often the test analytic is run.
111
Chapter 8 Administering S-PLUS Enterprise Server for Windows Test Analytic Wait (seconds): Controls the time period allowed before testing for successful completion of the test analytic. Test Analytic Max Failures: Controls how many failures are allowed before restarting S-PLUS Enterprise Server. Test Analytic Script File: Shows the location and name of the test script file. To change the script, click Browse, and then click Update.
Database Settings Page
This page can be accessed by clicking Administer S-PLUS Enterprise Server, then S-PLUS Enterprise Server Configuration from the main frame, and then Modify in the Database Settings section. This allows you to add or delete database connections to S-PLUS Enterprise Server, set a database as the defaults for analysis, and test the connection to a database before S-PLUS Enterprise Server is connected to it. Before an analysis can retrieve data from a database, S-PLUS Enterprise Server must be configured to connect to a database when it starts up. To configure this, click the New Database row in the Database name column, which displays all the ODBC data sources available on the server. Choose your database, enter the username and password to use, and then click Test (to the right of the New Database row) to test the connection to the database, or click Update to simply add the database to S-PLUS Enterprise Servers list of connections. To make a database the default, click the radio button next to the database in the Default column, and click Update. This means that if a data source is not specified when a SQL statement is provided for an analytic, this database is used. To remove a database, click the radio button in the Remove column and click Update.
112
Administering S-PLUS Enterprise Server Through the Web Tools The Modify Database settings page is shown below.
Figure 8.10: Modify Database settings page.
113
OTHER METHODS OF CONTROLLING S-PLUS ENTERPRISE SERVER

Controlling S-PLUS Enterprise Server Through the Services Manager
To open the Services Manager, in Windows, click Start Control Panel, and then double-click Administrative Tools. In the Administrative Tools window, double-click Services. Using the Services Manger, you can stop, start, pause, and continue the S-PLUS Enterprise Server service. When the service is paused, the database connections are closed, and the S-PLUS processes are stopped. You can also use the Services Manager to set the service start up mode (Automatic, Manual, or Disabled). See the section Administering S-PLUS Enterprise Server Through the Web Tools on page 98 for an explanation of the startup mode. The Windows Services Manager is shown in Figure 8.11.
Figure 8.11: Services Manager.
114
Other Methods of Controlling S-PLUS Enterprise Server Use the Services Manager to automatically restart a service when it fails. For S-PLUS Enterprise Server, right-click S-PLUS Enterprise Server Analytic Service, and then click Properties. Click the Recovery tab, and then select the appropriate action for each instance. For example, you can set the options to configure the server to restart the service after the first failure, reboot the machine after the second failure, and run a script on subsequent failures that sends an e-mail message to the system administrator.
Note
If you force a reboot, make sure the S-PLUS Enterprise Server Analytic Service is configured to automatically start on reboot. You can set this option in the Services Manager.
Controlling S-PLUS Enterprise Server Through the S-PLUS Enterprise Server Analytic Service Monitor
The S-PLUS Enterprise Server Service Monitor, which is available from the S-PLUS Enterprise Server program folder, is a very simple application that provides an easy way to stop, start, and monitor the S-PLUS Enterprise Server Analytic Service from the desktop. It checks and displays the status of the S-PLUS Enterprise Server service once a second. The status display can be updated immediately by clicking the Query button. The monitor is shown in Figure 8.12.
Figure 8.12: S-PLUS Enterprise Server Analytic Service Monitor.
115
Controlling S-PLUS Enterprise Server Through the S-PLUS Enterprise Server Monitor
The S-PLUS Enterprise Server Monitor (StatServerMonitor.exe, located in the cmd directory) is similar to the other services, and is installed to automatically start on system startup. The purpose of this service is to monitor and test running analytics periodically against the S-PLUS Enterprise Server Analytic Service. By default, the test analytic located in the script file ServerFiles\TestAnalyticFile.ssc is run every 10 minutes (600 seconds). If the run fails for any reason, this monitor service stops and then restarts the S-PLUS Enterprise Server Analytic Service automatically. The user can change the analytic that is run by editing ServerFiles\TestAnalyticFile.ssc. By default, the test analytic in this script is print(1:10). The user can also change the interval at which the test analytic is run as well as the script path name to run by using the new fields at the bottom of the Administration configuration page in S-PLUS Enterprise Server. To turn off this periodic monitoring, set the interval to 0 seconds. A complete log of actions that this monitoring service makes is stored in a log file at LogFiles\StatServerMonitor.log. You can check the status of the S-PLUS Enterprise Server Monitor by looking for the process S-PLUS Enterprise Server Monitor in the Services Manager.
116
S-PLUS Enterprise Server Maintenance
S-PLUS ENTERPRISE SERVER MAINTENANCE

S-PLUS Enterprise Server automatically performs numerous tasks to maintain a clean and efficient server environment. These tasks include: Housekeeping: S-PLUS Enterprise Server housekeeping automatically deletes temporary S-PLUS working directories created under splus70server\tmp, as well as periodically purging completed requests from S-PLUS Enterprise Server memory. The tmp directories are also purged if S-PLUS Enterprise Server is stopped and restarted. Automatic restart of S-PLUS: S-PLUS Enterprise Server restarts the S-PLUS sessions it manages periodically to clean up any unnecessary accumulation of system resources. The default interval is five hours. The restart is reported in the S-PLUS Enterprise Server log window as:
Restarting S-PLUS session at date time.
Automatic clean up of temporary Web files: Temporary text files generated in splus70server\wwwroot\temp are cleaned up automatically.
You must manually delete old requests periodically. Previous requests and their results are stored in the S-PLUS Enterprise Server internal database. Periodically delete these requests to maintain performance. These requests are not deleted automatically, which allows users retrieve the results of previously calculated analyses. If you want to automatically delete requests, you can use the at command and a provided Windows Scripting Host (WSH) script. Typing the following command in a Command Window deletes old requests automatically every night at midnight:
at 00:01 /every:M,T,W,Th,F,S,Su c:\Insightful\ splus70server\clients\wsh\deleteRequestsA.vbs
Note Modify the above path to reflect your installation location. The Schedule service must be running to enable the at command. See Chapter 19, Using Windows Scripting Host Scripts, for more information on the at command and Windows Scripting Host.
117
Chapter 8 Administering S-PLUS Enterprise Server for Windows You can delete requests manually via the Web pages. Click Administer S-PLUS Enterprise Server, and then click Delete Requests. Confirm deleting the request when prompted. Delete requests only while the S-PLUS Enterprise Server is not processing requests.
Backing Up or Restoring S-PLUS Enterprise Server
When you configure an automatic backup of a S-PLUS Enterprise Server system, consider the following issues: 1. The most important file to back up is splus70server\ServerFiles\aos6.db. This is the internal database that contains all the created analytics. The S-PLUS Enterprise Server is normally using this file, so an automated backup may see it as in use and be unable to copy it. Working around this requires either manually backing up the file, or making sure the S-PLUS Enterprise Server is not running during the automated back up. The S-PLUS Enterprise Server Web tools provide a wizard to enable easy backup of the internal database. Click Administer S-PLUS Enterprise Server, and then click Backup or Restore analytics. Use this wizard to copy selected analytics from the internal database (aos6.db) to a backup file (aos6backup.db). This is useful for multiple reasons: Creating a backup copy of your analytics for archiving. Repairing an existing installation. Copying the file aos6backup.db over the file aos6.db (when the S-PLUS Enterprise Server Database service is not running), thereby restoring your database file to an earlier state. This technique is useful for restoring your analytics to an earlier version, or for replacing a database file that has grown to an unreasonable size. (This can occure if you run many requests between deleting all your requests, especially if Housekeeping is turned off or set to a long delay time.) Using as an alternative to Copy Analytics to Remote S-PLUS Enterprise Server, by copying your aos6.db file to a different S-PLUS Enterprise Server. This technique
118
S-PLUS Enterprise Server Maintenance can be useful if you have many analytics to copy, or if you do not have Web access between your development and deployment platforms. 2. Backing up text copies of analytics that are created via the Web tools and stored in splus70server\wwwroot\aocwiz\analytic_name. (Any backup should include these files.) 3. Backing up any HTML front end output created by the Create User Interface tool and stored under splus70server\wwwroot\aoclientwiz. (Any backup should include these files.). For more information on backing up files, see section Migrating from an Existing Copy of S-PLUS Enterprise Server in Chapter 7, Installing S-PLUS Enterprise Server and Client for Windows.
119
120
ADVANCED TOPICS
9
122 122 126 131 132 132 133 134 135 136 137 137 139 142 143
Configuration of Microsofts Internet Information Server (IIS) Manual Configuration of IIS 5.0 with Windows 2000 Server and Advanced Server Manual Configuration of IIS 6.0 with Windows Server 2003 Standard and Enterprise Editions Web Server Security Using Secure Sockets Layer (SSL) for Remote COM Clients Using NT Challenge\ Response Security with a Web Browser Using NT Challenge\ Response or Basic Authentication with COM Clients Using NTFS Security with S-PLUS Enterprise Server Allowing Upload of Large Data Files Network Load Balancing A Detailed View of How S-PLUS Enterprise Server Works Client Submits a Request Request Processed by S-PLUS Enterprise Server Client Retrieves Result Using COM+ to Distribute S-PLUS Enterprise Server Applications
121
Chapter 9 Advanced Topics
CONFIGURATION OF MICROSOFTS INTERNET INFORMATION SERVER (IIS)

The Microsoft IIS is configured automatically during installation. If you encounter configuration errors, you might need to configure IIS manually. These instructions are provided for manually configuring an IIS installation.
Manual Configuration of IIS 5.0 with Windows 2000 Server and Advanced Server
You need administrator privileges on the local machine to configure IIS. You also need a Web browser that can display frames, such as Internet Explorer 5.01 (or later). Follow this procedure: 1. In the Web tools menu (under S-PLUS Enterprise Server Development, in the left pane), go to Administer S-PLUS Enterprise Server and select S-PLUS Enterprise Server Configuration. Ensure the Internal Web Server is set to disabled. Click Update. Run the ConfigIIS.vbs script, found in the <sshome>\cmd directory, where <sshome> is your S-PLUS Enterprise Serverinstallation directory. Test the Web pages, as in Step 8 below. If the test is successful, you have succeeded. If not, continue with Step 2, and perform the configuration manually. In Windows, click Start, and then click Control Panel. From the Control Panel, double-click Administrative Tools, and then double-click Internet Information Services. The Internet Information Services manager window appears with two panes. The left pane displays a hierarchy of web sites and locations, and the right pane displays files for each location (if available). Expand the left pane tree. In the left pane, right-click Default Web Site, and then select New Virtual Directory to open the Virtual Directory wizard. Click Next to skip the welcome page of the wizard.
2. Add the S-PLUS Enterprise Server Web pages to the IIS:
122
Configuration of Microsofts Internet Information Server (IIS) In the Virtual Directory Alias page, for Alias, type StatServer. This alias is used as the base path when requesting the S-PLUS Enterprise Server administration pages. (For example, http://hostname/StatServer/ Default.htm.) Click Next. In the Web Site Content Directory page, specify the wwwroot directory of the S-PLUS Enterprise Server installation in the Directory edit field. (This is <sshome>\WWWRoot, where <sshome> is the directory where you installed S-PLUS Enterprise Server.) Click Next. In the Access Permissions page, select the following permissions: Read Run Scripts (such as ASP) Execute (such as ISAPI applications or CGI) Click Next, and then click Finish to close the wizard and create the new virtual directory. In the left pane of the Internet Information Services window, expand the StatServer node, and then rightclick the StatServer\webdbclient\newadmin directory. In the context menu, select Properties. In the newadmin Properties dialog box, click the Directory Security tab, and then click Edit next to the label Anonymous Access and Authentication Control. In the Authentication Methods dialog box, clear the Anonymous Access box and select the Basic authentication box and the Integrated Windows authentication box. Click OK to accept these changes. If you want to permit custom client applications (non-Web browser clients) to access to S-PLUS Enterprise Server through the Internet, you can use the same procedure outlined above to associate an additional virtual path (called ssbin) with the <sshome>\cmd directory. S-PLUS
123
Chapter 9 Advanced Topics Enterprise Server setup creates the default virtual directory ssbin automatically. We recommend that you create this virtual directory. Following the procedure above for creating virtual directories in the Internet Services Manager, configure a virtual directory sstmp pointing to <sshome>\tmp. In the left pane of the Internet Services Manager, rightclick the Default Web Site node, and then select Stop from the context menu. The node now displays (Stopped) beside the name. From the Windows Start menu, click Run, and then in the Run dialog box, type regedit to start the system registry. Browse to the following registry entry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Services\W3SVC\Parameters.
3. Stop the WWW Service:
4. Edit the Registry:
In the Edit menu, click New String Value to create a new string value in the Script Map key. Give it the name .scr. Double-click the .scr entry, and then for value, specify <sshome>\cmd\webscript.dll, where <sshome> is the path to the directory where you installed S-PLUS Enterprise Server. Click OK to accept the change and close the registry editor. In the Internet Information Services manager, in the left pane, right-click Default Web Site. Click Start from the context menu. The node no longer displays (Stopped) next to the name. In the Internet Information Services manager, in the left pane, right-click Default Web Site. Click Properties.
5. Restart the WWW Service:
6. Set the Script Mapping:
124
Configuration of Microsofts Internet Information Server (IIS) In the Default Web Site Properties dialog box, click the Home Directory tab. Click Configuration to open the Application Configuration dialog box. In the Mappings tab, click Add. In the Add/Edit Application Extension Mapping dialog box, click Browse. In the Open dialog box, for Files of Type, select .dll. Browse to <sshome>\cmd and select webscript.dll. Click Open to select this file as the Executable. For Extension, type .scr.

Note
If multiple entries for .scr exist, delete all except for one correct entry. Problems can arise with multiple entries, especially if the entries point to different locations. This situation can occur if the S-PLUS Enterprise Server has been installed to one location, uninstalled, and then installed to a different directory location.
7.
Click OK in each dialog box to accept the changes. Use the S-PLUS Enterprise Server Services Monitor to start the server. Test the Web pages with a browser to access the virtual path you specified above (e.g., http://hostname/ statserver). If the server is properly configured, an S-PLUS Enterprise Server page is returned and displayed.
Restart the S-PLUS Enterprise Server:
8. Test the Web pages:
125
Manual Configuration of IIS 6.0 with Windows Server 2003 Standard and Enterprise Editions
ou need administrator privileges on the local machine to configure IIS. You also need a Web browser that can display frames, such as Internet Explorer 5.01 (or later). Follow this procedure: 1. In the Web tools menu (under S-PLUS Enterprise Server Development, in the left pane), go to Administer S-PLUS Enterprise Server and select S-PLUS Enterprise Server Configuration. Ensure the Internal Web Server is set to disabled. Click Update. Run the ConfigIIS.vbs script, found in the <sshome>\cmd directory, where <sshome> is your S-PLUS Enterprise Server installation directory. Test the Web pages, as in Step 10 below. If the test is successful, you have succeeded. If not, continue with Step 2, and perform the configuration manually. In Windows, click Start, and then click Control Panel. From the Control Panel, double-click Administrative Tools, and then double-click Internet Information Services. The Internet Information Services manager window appears with two panes. The left pane displays a hierarchy of web sites and locations, and the right pane displays files for each location (if available). Expand the left pane tree. In the left pane, right-click Default Web Site, and then select New Virtual Directory to open the Virtual Directory wizard. Click Next to skip the welcome page of the wizard. In the Virtual Directory Alias page, for Alias, type StatServer. This alias is used as the base path when requesting the S-PLUS Enterprise Server administration pages. (For example, http://hostname/StatServer/ Default.htm.) Click Next. In the Web Site Content Directory page, specify the wwwroot directory of the S-PLUS Enterprise Server installation in the Directory edit field. (This is
2. Add the S-PLUS Enterprise Server Web pages to the IIS:
126
Configuration of Microsofts Internet Information Server (IIS) <sshome>\WWWRoot, where <sshome> is the directory where you installed S-PLUS Enterprise Server.) Click Next. In the Access Permissions page, select the following permissions: Read Run Scripts (such as ASP) Execute (such as ISAPI applications or CGI) Click Next, and then click Finish to close the wizard and create the new virtual directory. In the left pane of the Internet Information Services window, expand the StatServer node, and then rightclick the StatServer\webdbclient\newadmin directory. In the context menu, select Properties. In the Properties dialog box, click the Directory Security tab, and then click Edit (next to the label Authentication and access control). In the Authentication Methods dialog box, clear the Anonymous Access check box and select the Basic authentication check box and the Integrated Windows authentication check box. Click OK to accept these changes. If you want to permit custom client applications (non-Web browser clients) to access to S-PLUS Enterprise Server through the Internet, you can use the same procedure outlined above to associate an additional virtual path (called ssbin) with the <sshome>\cmd directory. S-PLUS Enterprise Server setup creates the default virtual directory ssbin automatically. We recommend that you create this virtual directory. Following the procedure above for creating virtual directories in the Internet Services Manager, configure a virtual directory sstmp pointing to <sshome>\tmp.
3. Stop the WWW Service:
127
Chapter 9 Advanced Topics In the left pane of the Internet Services Manager, rightclick the Default Web Site node, and then select Stop from the context menu. The node now displays (Stopped) beside the name. From the Windows Start menu, click Run, and then in the Run dialog box, type regedit to start the system registry. Browse to the following registry entry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Services\W3SVC\Parameters.
4. Edit the Registry:
In the Edit menu, click New String Value to create a new string value in the Script Map key. Give it the name .scr. Double-click the .scr entry, and then for value, specify <sshome>\cmd\webscript.dll, where <sshome> is the path to the directory where you installed S-PLUS Enterprise Server. Click OK to accept the change and close the registry editor. In the Internet Information Services manager, in the left pane, right-click Default Web Site. Click Start from the context menu. The node no longer displays (Stopped) next to the name. In the Internet Information Services manager, in the left pane, right-click Default Web Site. Click Properties. In the Default Web Site Properties dialog box, click the Home Directory tab. Click Configuration to open the Application Configuration dialog box. In the Mappings tab, click Add. In the Add/Edit Application Extension Mapping dialog box, click Browse. In the Open dialog box, for Files of Type, select .dll.
5. Restart the WWW Service:
6. Set the Script Mapping:
128
Configuration of Microsofts Internet Information Server (IIS)

Note If multiple entries for .scr exist, delete all except for one correct entry. Problems can arise with multiple entries, especially if the entries point to different locations. This can occur if the S-PLUS Enterprise Server has been installed to one location, uninstalled, and then installed to a different directory location.
Browse to <sshome>\cmd and select webscript.dll. Click Open to select this file as the Executable. For Extension, type .scr.
7.
Click OK in each dialog box to accept the changes. In the Internet Information Services manager, in the left pane, click the Web Service Extension folder node. The right pane updates with a list of Web service extensions and other options. Ensure that the service Active Server Pages is set to Allowed. If it is not, in the right pane, select Active Server Pages and click Allow. In the right pane, click Add a new Web service. In the New Web Service Extension dialog box, type StatServer Script Files for the extension name. Click Add to add the following required files: <S-PLUS Enterprise Server root>\cmd\webapi.dll <S-PLUS Enterprise Server root>\cmd\webscript.dll
Enable Web Service Extensions:
Check Set extension status to Allowed. Click OK to accept the changes. Open Internet Explorer. On the menu, click Tools Internet Options. In the Internet Options dialog box, click the Security tab. Click Trusted sites, and then click Custom Level.
129
8. Set the security level for the browser:
Chapter 9 Advanced Topics Scroll down the Settings box to the User Authentication/Logon section and select Automatic logon with current username & password. Click OK to accept the change. In the Internet Options dialog box, click Sites. In the Trusted sites dialog box, type http://hostname/ StatServer in the trusted zone box (where hostname is the name of the server where you installed S-PLUS Enterprise Server), and click Add. Click OK, and then in the Internet Options dialog box, click OK to accept the changes. Use the S-PLUS Enterprise Server Services Monitor to start the server. Test the Web pages with a browser to access the virtual path you specified above (for example, http://hostname/ StatServer). If the server is properly configured, an S-PLUS Enterprise Server page is returned and displayed.
9. Restart the S-PLUS Enterprise Server:
10. Test the Web pages:
130
Web Server Security
WEB SERVER SECURITY

When used with Microsoft's IIS, S-PLUS Enterprise Server offers the following levels of security: 1. None. 2. Server-based security: restrict access to certain IP addresses or Internet Domain names. 3. Basic authentication or NT challenge/response (password protection). 4. Completely encrypted communications via Secure Sockets Layer (SSL). Any of these security schemes can protect both the remote COM clients and the S-PLUS Enterprise Server server-side scripts (for browser client access). See the IIS Internet Service Manager and product documentation for more information on Internet security. For purposes of directory-based security, you can set separate levels of security for each of these directories: splus70server: Contains server-side scripts. webdbclient and aocwiz: Analytic developers need access to these directories. aoclientwiz: Users who run analytics through customized HTML interfaces created by analytic developers need access to this directory. ssbin: Users accessing the S-PLUS Enterprise Server through remote COM clients, such as Excel and the S-PLUS Publishing Client, need access to this directory.
splus70server\webdbclient\newadmin is configured during installation with Basic and Challenge/Response security. These settings are required for the scripts in this directory to administer S-PLUS Enterprise Server.
131
Using Secure Sockets Layer (SSL) for Remote COM Clients
S-PLUS Enterprise Server supports Web communication using the Secure Sockets Layer (SSL), a technology for encrypting conversations between clients and servers on the Internet. Remote COM Client applications developed for the S-PLUS Enterprise Server have the option of connecting over a secure channel, encrypting all communications with the S-PLUS Enterprise Server. To enable this feature on the client, simply add a Secure=1 entry to your statsvr.inf files Inet transport definition. The default SSL port is 443 (as opposed to 80 for HTTP), so if you specify the Port= entry, make sure it reflects the SSL port. A sample StatSvr.inf follows:
[Client1] Transport=Inet Description=Client Profile Host=statserver.insightful.com Port=443 BaseURL=/ssbin/webapi.dll [Profiles] Default=Client1 Profile1=Client1 NumProfiles=1
You must enable SSL for the ssbin directory of the target server (for example, brimstone in the example above). This option is configured in the Internet Service Manager.
Using NT Challenge\ Response Security with a Web Browser
The advantages of NT challenge\response security are: 1. User passwords are sent in encrypted format over the Web, rather than as clear text. 2. Users are authenticated automatically (without a password prompt) as long as they are a valid user on the NT Server that is hosting the Web server. Only Internet Explorer supports this form of Web security; Netscape does not. Furthermore, due to an apparent problem in older versions of Internet Explorer, using NT Challenge\Response security breaks parts of the S-PLUS Enterprise Server Web tools. Specifically, those Web scripts that use multi-part forms (which are required to upload a
132
Web Server Security file as part of a form) fail. These include the script that publishes an analytic, and the scripts used to run analytics that upload a file to use as data input. For users to access these parts of the Web tools while NT Challenge\Response security is set, you must upgrade to Internet Explorer 5.01 or later. To check your version of IE, click Help About Internet Explorer. Version 5.01 is listed as version 5.00.2919.6307 or later. The version of IE that ships with Windows 2000 is 5.00.2920.00.
If you do not want to upgrade your users to Internet Explorer version 5.01 or later, but you do want to use NT Challenge\Response Web security, you can modify the scripts used to publish analytics. By removing the file upload capability from those scripts, you can allow users to publish analytics; however, your users cannot run analytics that upload files as input data. 1. To make this change, in a text editor (such as Notepad), open the file splus70server\wwwroot\webdbclient\pubwiz\getinfo2.scr. 2. Change this line:
<form action="showinfo.scr" enctype="multipart/ form-data" method=post>
to
<form action=showinfo.scr method=post>
3. Delete this line.

<input type=file name=FileUp>
4. Save the file. You should now be able to publish an analytic.
Using NT Challenge\ Response or Basic Authentication with COM Clients
To use either form of password-protected security with the COM clients, you must specify a username and password as part of your connection profile in your statsvr.inf file. These are used by the COM\HTTP layer to connect to the secured Web server. An example statsvr.inf file is shown below. In this example, the username is myname, and the password is mypassword. mydomain is the domain in which myname is a valid user.
[SphinxServer] Description=Password Profile
133

Transport=Inet Host=sphinx Port=80 BaseURL=/ssbn/webapi.dll UserName="mydomain\myname" Password="mypassword"
Using NTFS Security with S-PLUS Enterprise Server
Using the Windows NT File System (NTFS), you can set user-based security on individual directories and files. This option can be useful for securing a Web server; however, you must configure the server properly to allow your application necessary access to required directories and files. Note that NTFS security can be set automatically during installation, whereas you had to set permissions manually in previous releases. For detailed information on required permissions and troubleshooting NTFS-related problems, see NTFS Issues on page 158 in Chapter 10, Troubleshooting Guide. When you are applying changes, you might need to stop and restart the S-PLUS Enterprise Server and IIS services and close and reopen your browser to ensure that the changes have been committed.
134
Allowing Upload of Large Data Files
ALLOWING UPLOAD OF LARGE DATA FILES

By default, IIS limits the size of uploaded files to 48 KB. To upload larger files to be used as input data files to a S-PLUS Enterprise Server analytic, you must create a registry key that specifies a larger upload size. To do this: 1. In the Services dialog box, stop the WWW Service, and then stop the FTP and IIS Admin services. 2. In Windows, click Start Run, and then in the Run dialog box, type regedit to open the registry editor. 3. In the registry editor, browse to
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services \W3SVC\Parameters
4. Right-click Parameters, and choose New Value.
DWORD
5. Type UploadReadAhead as the name of new parameter. 6. Double-click UploadReadAhead to display the Edit DWORD value. Choose Decimal as the base, and then provide the new size limit as a number of bytes. For example, to allow uploads up to approximately 100 KB in size, in the Value box, type 102400. 7. Click OK to accept the changes. 8. In the Services dialog box, restart the WWW Service (and any other related services). Next, run a script that modifies the Metabase entries that IIS uses. The information specified in the Metabase supersedes the information in the registry. A sample script, setUploadSize.vbs, is included in splus70server\Clients\wsh. To run this script: 1. Make sure you have Windows Scripting Host installed. 2. Using a text editor (such as Notepad), open the script and change the default value (200000 bytes) to the desired limit. Save and close the script. 3. Double-click the script file to run it. Two message boxes appear: the first displays the old value (49152 is the default), and the second displays the new value.
135
NETWORK LOAD BALANCING

Network Load Balancing (NLB) is a Microsoft product that provides load balancing and clustering for Web-based applications. NLB dynamically distributes IP traffic across multiple systems in a cluster. If a system in the cluster fails, that system is automatically removed, and subsequent IP traffic is distributed over the remaining systems until the failed system is replaced. Also, you can add systems to the cluster as the need arises. The key benefits of this design are high availability and scalability. NLB is included in Windows 2000 Advanced Server and all editions of Windows Server 2003. For more information on NLB, the following sources may be helpful. Windows 2000 Advanced Server: http://www.microsoft.com/windows2000/techinfo/ howitworks/cluster/nlb.asp Windows Server 2003: http://www.microsoft.com/windowsserver2003/techinfo/ overview/clustering.mspx If you are interested in using NLB with S-PLUS Enterprise Server, contact Technical Support.

136
A Detailed View of How S-PLUS Enterprise Server Works
A DETAILED VIEW OF HOW S-PLUS ENTERPRISE SERVER WORKS

This section gives a detailed, step-by-step breakdown of how a request for analysis is submitted from a client and processed by S-PLUS Enterprise Server. Though understanding S-PLUS Enterprise Server functionality is not required for normal operation of S-PLUS Enterprise Server, specific information is provided here for two reasons: 1. Some users prefer to have a detailed understanding of the architecture of S-PLUS Enterprise Server, both for their own edification and to understand how to integrate S-PLUS Enterprise Server into a larger set of applications. 2. When errors occur and are difficult to track down, a thorough understanding of the S-PLUS Enterprise Server process is invaluable in helping determine exactly where the error occurred and how to remedy it.
Client Submits a Request

Web Browser Client
This section deals separately with requests submitted from a Web browser and from remote and local COM clients. The user opens a Web browser and requests the S-PLUS Enterprise Server URL. The user navigates through a series of Web pages, specifies the analytic to run (along with any supporting information), and then submits a request to run an analysis. On the server, the Web server receives a request for a script file (.scr extension). The Web server has been configured to load a special DLL, webscript.dll, to handle the request, using the ISAPI interface. (ISAPI is a feature of Web servers that developers use to extend the Web servers capabilities by specifying new DLLs that should be loaded to handle certain types of browser requests.) When webscript.dll is loaded, it interprets the VBScript contained in the script file. This script, in turn, initializes and manipulates the S-PLUS Enterprise Server server-side COM objects. These COM objects interact with the S-PLUS Enterprise Server internal database to retrieve information, such as the available analytics and their properties, and to insert a new request for analysis. The VBScript files
137
Chapter 9 Advanced Topics use the information returned from the COM objects to build an HTML file dynamically. The HTML file is returned to the browser, which displays the file.
S rp ci t Fl ie
WbBo s r e r we
CM O
SP U S r e - L S ev r Dt b s aa a e
HT TP Rq et e us
WbS r e e ev r
I AI S P: wb c i tdl e s rp. l
Figure 9.1: Submitting a request from a Web browser.
The Web browser presents the user with a list of available analytics to run, along with any supporting information. The user submits a request for an analytic to run. The request is inserted into the S-PLUS Enterprise Server internal database, where S-PLUS Enterprise Server detects it.
Remote COM Client
In this example, we use the sample Visual Basic client for simplicity, but the basic ideas apply to all remote COM clients. To submit a request from the Visual Basic client, the user starts the application oleclient.exe. When the application is opened, the VBClient initializes the S-PLUS Enterprise Server client-side COM objects. It generates a series of HTTP requests that open a connection to a remote S-PLUS Enterprise Server and retrieve the desired information. On the server, the Web server receives an HTTP request, which is handled by a separate ISAPI DLL (webapi.dll). This DLL interacts with the S-PLUS Enterprise Server database to retrieve the requested information and return it to the client. When the user requests an
138
A Detailed View of How S-PLUS Enterprise Server Works analysis to be run, the request is inserted into the S-PLUS Enterprise Server internal database, where it is detected by S-PLUS Enterprise Server.
C n lie t A p a io p lic t n
I AI S P: wb p ll e a i.d
SP U S r e - L S ev r Dt b s aa a e
C nCM lie t O I t ra e ne f c
WbS r e e ev r
Figure 9.2: Submitting a request from a remote COM client.
Local COM Client Submitting a request from a local COM client is similar to the remote
case. The local COM client initializes and manipulates the server-side COM interface, which interacts directly with the internal S-PLUS Enterprise Server database to retrieve information and submit requests for analysis.
Request Processed by S-PLUS Enterprise Server
After a request for analysis is inserted into the S-PLUS Enterprise Server internal database, the S-PLUS Enterprise Server application detects the request, retrieves the analytic and input data, and sends this off to S-PLUS for analysis. In more detail, the S-PLUS Enterprise Server: Detects the request and queues it. The log window displays a message containing the request ID number, the analytic name, and the time.
Queuing Request 195, Analytic SQLcho6, at 09/10/99 07:22:24:468000
Waits until an S-PLUS process is available to service the request, then it displays a message indicating the location of the analytics temporary directory:
C:\Program Files\Insightful\splus62server\tmp\2\20 will be used for Analytic 195
139
Chapter 9 Advanced Topics The first number (2) indicates the parent directory, because the server creates a separate parent directory for each running S-PLUS process. The second number (20) indicates the individual working directory used for this particular request. The server creates a separate working directory for each request. Creates a subdirectory containing the S-PLUS binary objects that are associated with the analytic. This directory contains the entry point function, as well as any other functions created as part of the analytic. The server generates the name of this directory by adding a l to the analytic name. For example, the library associated with the analytic coplot is named lcoplot. Retrieves data from databases or data files and converts them to S-PLUS objects, which are stored in /.Data/_SqlIn/. (This step depends on the analytic and the request.) Creates a file, sp#.in, and uses it as the input to S-PLUS. The input sets the attributes of the analytic object class and calls the entry point function, which is stored in one of the library subdirectories. It also tells S-PLUS to use the newly-created .Data directory as its working directory and adds the other libraries to S-PLUSs search path. Passes the entry point function to S-PLUS. The entry point functions key components do the following work: Provide the following inputs:
args: objs:
A vector of input arguments.
A vector of names of input objects (which are data frames created from database retrieval or data file conversion, and stored in /.Data/_SqlIn/). An integer that tells S-PLUS that it should add to its search path the temporary data directory created by a previous analytic.
BasedOn:
Convert arguments and objects: Converts S-PLUS Enterprise Servers names for arguments and objects, such as args[1], to names used in the S-PLUS code, such as
var1.
140
A Detailed View of How S-PLUS Enterprise Server Works Initialize graphics: using the function OpenGraphicsDevice, initializes environment for capturing output. Process: That is, the S-PLUS code that does the analytics work. Capture and clean up: Using the function CloseGraphicsDevice, captures output and cleans up environment. Assign objects: If the entry point code passes back output objects, then you must use the the assign function and specify the argument frame=1 (RAM), so the objects are visible when function returns. If you want any objects to be available for future analytics using the BasedOn functionality, then you must use the assign function and specify the argument where=1 to assign them to disk.
Return output: A list of output parameters (as vector), and output object names, which are sent to database insertion or data file conversion. The output objects are stored in .Data/_SqlOut.
Writes all text output to sp#.out. (Normally, S-PLUS writes the text output to standard out.) Appends errors to the file /tmp/#n/all.err, which contains all the errors generated by the S-PLUS process #n. Only the latest error is written to /tmp/#n/local.err; any errors that the S-PLUS GUI generates are written to gui.err. Outputs graphics in the specified format. Writes any output parameters to the file result.dat. Retrieves output graphics, text, parameters, and data. Output data may be converted into data files or stored in a database. All outputs are stored in the internal S-PLUS Enterprise Server database. Depending on your configuration, either the result itself, or the path of the file containing the results, is stored in the internal database.
141
Chapter 9 Advanced Topics Updates a flag on the initial request to alert the waiting clients that the results of the analysis are ready to be retrieved, and displays a message in the log window:
Finished Analytic 195 at 09/10/98 07:22:35:750000
Client Retrieves Result
After a result is ready, the clients retrieve the results in the same way as other information is retrieved, as explained above.
142
Using COM+ to Distribute S-PLUS Enterprise Server Applications
USING COM+ TO DISTRIBUTE S-PLUS ENTERPRISE SERVER APPLICATIONS

The standard S-PLUS Enterprise Server architecture expects that the Web server and S-PLUS Enterprise Server exist on the same computer. When you scale up the S-PLUS Enterprise Server architecture, we recommend that you replicate the entire system on each computer in a cluster. However, some users might want to use COM+ to split the S-PLUS Enterprise Server architecture, enabling IIS and ASP (Active Server Pages) to be on one computer and COM/S-PLUS Enterprise Server/S-PLUS to be on another comptuer. For more information on the use of COM+, consult Technical Support.
143
144
TROUBLESHOOTING GUIDE
10
146 147 150 151 156 158 160 162
Introduction Connection/Installation Problems License Management Problems Problems Creating or Running Analytics Problems with Remote COM Clients NTFS Issues NTFS Permissions Required for IIS Diagnosing NTFS Issues
145
INTRODUCTION
If you run into problems starting the S-PLUS Enterprise Server or running an analytic, start by performing the following tasks: 1. Stop the S-PLUS Enterprise Server service by going to Programs S-PLUS Enterprise Server S-PLUS Enterprise Server Service Monitor and clicking Stop. 2. Start the S-PLUS Enterprise Server application by going to Programs S-PLUS Enterprise Server S-PLUS Enterprise Server (As Application). When the program comes up, the service automatically starts, so stop the service by clicking the black square (Stop) in the toolbar. In the main menu, click Server Properties. Click the Log tab, and then, in the Level of Detail box, change the Logging level to Verbose Debug. Using this setting, you can see as much information as possible, which can help you identify where the analytic breaks down.
146
Connection/Installation Problems
CONNECTION/INSTALLATION PROBLEMS
Table 10.1: Connection/installation problems. Symptom Error message in browser:
HTTP error: Specified module could not be found.
Possible Cause Error in installation, or failure to stop the WWW service before installing S-PLUS Enterprise Server. Because of this, the WWW service cannot find the S-PLUS Enterprise Server ISAPI dll.
Action Check connection via browser after each one: 1. Stop and restart WWW service (and all other related service, i.e., FTP, IIS Admin Service). 2. Reboot server. 3. Run the configIIS.vbs script found in splus70server\cmd, from the shortcut in the S-PLUS Enterprise Server program folder. 4. If this does not solve the problem, manually configure IIS as described in Chapter 9, Advanced Topics. In particular, make sure that there is only one correct entry mapping .scr to the location of webscript.dll in the App Mappings dialog. This is described in the Set the Script Mapping section of the instructions.
Error message in browser:

StatServer Error The StatServer web interface could not be initialized. The application may not be properly installed.
Error in installation, leading to incorrect or missing registry entries. Most likely, this means that the Web tools are unable to initialize the S-PLUS Enterprise Server COM objects. This may happen when installing S-PLUS Enterprise Server to a different location on the same machine.
Uninstall and reinstall S-PLUS Enterprise Server.
147

Table 10.1: Connection/installation problems. (Continued) Symptom Error message in browser:
StatServer Error The StatServer web interface could not be initialized. Check your database connection settings.
Possible Cause S-PLUS Enterprise Server Web tools failed to connect to database. May indicate problem with installation, with S-PLUS Enterprise Servers internal database.
Action This error occurs if you attempt to run a previous version (StatServer 2000 R1) on Windows 2000. If this occurs under other conditions, try stopping and restarting the Web and S-PLUS Enterprise Server services.
Problem connecting to remote database: On S-PLUS Enterprise Server startup: In S-PLUS Enterprise Server log, you have the following error message:
Cannot connect to database named XYZ.
Database is not accessible via this DSN, either because of improper configuration, database is not running, or because the network connection to the database cant be made.
Test DSN by connecting from another application, such as MSQuery (msqry32.exe) or in S-PLUS, go to File Import Data From Database. If DSN cannot make connection, try connecting using native database methods, if available (e.g., SQL+ for Oracle, WISQL for Sybase). This helps pinpoint the problem.
where XYZ is the name of a DSN. Additional error messages may be returned from ODBC driver which may indicate the problem User cannot log on or connect to the server Username/password may not be set or valid. Check if username/password are set. In the Web tools menu, look at Administer S-PLUS Enterprise Server and click SPLUS Enterprise Server Configuration and then Modify Database settings. Test this username/password using a different application, as above.
148
Connection/Installation Problems
Table 10.1: Connection/installation problems. (Continued) Symptom Web browser cannot connect to server. Possible Cause WWW service may not be running, or may be using incorrect URL. IIS 5 and 6 Metabase not properly updated on reinstallation. .scr mapping may have multiple definitions. Action Check on the server that the WWW service is running. Also check the URL that you are using. Clean up the IIS 5 or 6 installation using the configIIS.vbs script in splus70server\cmd. This can be run from a shortcut in the S-PLUS Enterprise Server program folder.
On a machine where S-PLUS Enterprise Server was previously installed to one location, S-PLUS Enterprise Server is installed to a new location, and the Web pages still point to the old location.
149
LICENSE MANAGEMENT PROBLEMS

Table 10.2: License Management Problems Symptom S-PLUS License Manager Error Possible Causes Hyperthreading can alter the number of CPUs detected on a machine. With a 2-CPU computer, you are licensed to run this product on 2 CPUs. Hyperthreading creates 4 logical CPUs on a 2-CPU machine. Therefore, if you have hyperthreading enabled on your machine, the number of CPUs reported by the operating system might be greater than the number of physical CPUs in your machine. If S-PLUS detects more CPUs than you actually are using, you might see this error. Action Contact Insightful to resolve licensing issues with a hyperthreaded machine. For more information about problems with hyperthreading, see the section Problems Creating or Running Analytics on page 151.
150
Problems Creating or Running Analytics
PROBLEMS CREATING OR RUNNING ANALYTICS

Table 10.3: Problems creating or running analytics. Symptom Web browser appears to connect successfully. Submit a request for an analysis to be run. No result returned, or request returns with
Status 8: Request result is missing.
Possible Cause S-PLUS Enterprise Server may not be running.
Action Check on the server that the S-PLUS Enterprise Server service is running. Check whether request for analytic was queued.
On S-PLUS Enterprise Server start up, S-PLUS Enterprise Server reports that it failed to start S-PLUS.
S-PLUS may not be installed properly.
Test by attempting to start desktop session of S-PLUS. If you cannot, you may need to reinstall S-PLUS. Check requirements in Chapter 7, Installing S-PLUS Enterprise Server and Client for Windows to confirm correct version of S-PLUS. Verify in Task Manager that no extra splus.exe or aos.exe processes are running. Reboot server if unable to kill phantom processes.
Wrong version of S-PLUS installed.
Error in previous S-PLUS session may have prevented normal shut down.
151

Table 10.3: Problems creating or running analytics. (Continued) Symptom When publishing an analytic, a CInt error is generated, or the Web browser reports an abnormally terminated connection, and the analytic fails to publish. Possible Cause NT Challenge\Response security is set while using an older version of Internet Explorer. Action Options 1. Turn off Challenge\Response security. 2. Upgrade your browser to IE 5.01 or later. 3. Modify the scripts used to publish the analytic, as shown in the section on Web security in the Advanced Topics chapter. If you are publishing a large analytic, containing hundreds or thousands of lines of S-PLUS code, it may be too large for the default buffer that IIS allocates for use by ISAPI DLLs. Run the setUploadSize.vbs script to increase the size of the buffer, as described in the Chapter 9, Advanced Topics chapter, in the section Allowing Upload of Large Data Files on page 135. Options 1. Turn off Challenge\Response security. 2. Upgrade your browser to IE 5.01 or later. 3. Use a file on the server for data input.
When running an analytic using data file upload, a CInt error is generated, or the Web browser reports an abnormally terminated connection, and the analytic fails to run.
NT Challenge\Response security is set while using an older version of Internet Explorer.
152

Table 10.3: Problems creating or running analytics. (Continued) Symptom Possible Cause If the data file is larger than 48K, it may be too large for the default buffer that IIS allocates for use by ISAPI DLLs. Action Run the setUploadSize.vbs script to increase the size of the buffer, as described in the Chapter 9, Advanced Topics, in the section Allowing Upload of Large Data Files on page 135. General notes: Change the Level of Detail entry box in the Log tab to Verbose debug. This lets you see as much information as possible, and can help identify where the analytic breaks down. Problem with S-PLUS Enterprise Server executable or with the S-PLUS Enterprise Server Database. Application directory is created under Inetpub\wwwroot, rather than splus70server\wwwroot) Check if S-PLUS Enterprise Server is running and connected to the required databases.
While running analytic, results are not returned. A status number is generated.
Many possible causes.
Analytic fails with status 2.
webRoot
variable needs modifying.
Copy the insertATROdyn.scr file and modify it by setting the webRoot variable in the ASP page; e.g.,
webRoot = "C:\InetPub\wwwroot\sste st"
153

Table 10.3: Problems creating or running analytics. (Continued) Symptom Analytic fails with status 3. Possible Cause Error returned from Action This is the most common type of error, and usually indicates some error in the S-PLUS code. The error messages returned from S-PLUS should be displayed in the browser window, and should indicate the problem If not, look for the local.err, all.err, and gui.err files in splus70server\tmp\n, where n is the parent of the temporary directory used for this request. This information can be found in the S-PLUS Enterprise Server log window, in a message that looks like:
C:\Program Files\ Insightful\splus70server \tmp\n\m will be used for Request ##.
S-PLUS.
Analytics can't use mapped drives or UNC paths to access files.
Service runs as LocalSystem account user.
Navigate to Admin Tools Services, and change the login from a local system account to one with privileges on the network. The client requested an analytic that doesnt exist or is invalid. Check the name of the analytic, and make sure you are connected to the correct S-PLUS Enterprise Server.
Missing or Invalid Analytic.
154

Table 10.3: Problems creating or running analytics. (Continued) Symptom Analytic fails with status 5. Possible Cause Part(s) of the Analytic or Request are invalid. Action This error is rarely seen, and usually indicates some transient error. Try running the analytic again, or try running it from a different type of client. Check input SQL statement and data source name. If possible, test this connection information from another tool, such as MSQuery. Check output SQL statement and data source name. If possible, test this connection information from another tool, such as MSQuery. Insightful recommends that you disable hyperthreading according to your hardware manufacturer's instructions. However, if you wish to keep hyperthreading enabled, please contact Insightful support to resolve the licensing issues (See the section License Management Problems on page 150.)
Error processing SQL Select statement.
Error processing SQL Insert statement.
Hyperthreaded machine running slower than expected.
Hyperthreading is a technology developed by Intel to increase server performance. When you use CPU-intensive applications, such as S-PLUS, you will actually notice that performance is degraded when you enable hyperthreading.
155
PROBLEMS WITH REMOTE COM CLIENTS

Table 10.4: Problems with remote COM clients. Symptom Visual Basic client returns this error on startup:
Run-time Error 429: COM Automation server cant create object.
Possible Cause The S-PLUS Enterprise Server COM objects cannot be created. They may not be registered properly.
Action Check if
splus70server\cmd\aosapi .dll and aosfile.dll
exist. If so, open a DOS window, go to this directory, and enter these commands:
regsvr32 aosapi.dll regsvr32 aosfile.dll
If these files do not exists, reinstall S-PLUS Enterprise Server or S-PLUS Enterprise Server client.
S-PLUS client gives this error

message when attempting to connect to S-PLUS Enterprise Server:
Failed to get a IDispatch pointer for StatServer.Server. This might be caused by specifying an invalid object name to create in create.ole.object ("StatServer.Server")
The S-PLUS Enterprise Server COM objects cannot be created. They may not be registered properly.
Check if splus70server\cmd\aosap i.dll and aosfile.dll exist. If so, open a DOS window, go to this directory, and enter these commands:
regsvr32 aosapi.dll regsvr32 aosfile.dll
If these files do not exist, reinstall S-PLUS Enterprise Server or S-PLUS Enterprise Server client. Invalid structure in statsvr.inf file causing SSProfile.dll to crash when attempting to read it. This may be due to using an old (pre-StatServer 2000) statsvr.inf file. Update your statsvr.inf file to the proper structure, as shown in Chapter 9, Advanced Topics.
COM Client crashes when attempting to build a list of servers to connect to.
156
Problems with Remote COM Clients

Table 10.4: Problems with remote COM clients. (Continued) Symptom Get error message: Failure to connect in OpenMSS. Possible Cause The profile in statsvr.inf may not be defined properly. The server may not be accessible over the network. Password-based Web security may be blocking the COM clients from connecting. Action Check the statsvr.inf file.
Try connecting to the server with a Web browser.
Define a username and password as part of the connection profile in the statsvr.inf file, as described in the section on Web security in Chapter 9, Advanced Topics.
157
NTFS ISSUES
The most frequent cause of failure when configuring S-PLUS Enterprise Server on a new machine is incorrect NTFS permissions. The required permissions are documented below and in Chapter 9, Advanced Topics, in the section Using NTFS Security with S-PLUS Enterprise Server on page 134. To aid customers in configuring and diagnosing problems caused by NTFS permissions, several changes have been incorporated into S-PLUS Enterprise Server. These include the following: The S-PLUS Enterprise Server installation now checks for the correct NTFS permissions. If incorrect permissions are detected, the user is given the option of updating the permissions automatically. If the user elects not to update the permissions automatically at install, or if the automatic update is not successful, then the problems are recorded in splus70server\LogFiles\chkrghts.log. This log file contains details of the incorrect permissions, e.g.,
Path 'C:\Inetpub\Wwwroot' does not have required privileges 'read, execute'. Path 'D:\Program Files\Insightful\splus70server\wwwroot' does not have required privileges 'read, execute'. Path 'D:\Program Files\Insightful\splus70server\cmd' does not have required privileges 'read, execute'. Path 'D:\Program Files\Insightful\splus70server\tmp' does not have required privileges 'read, execute'.
If the utility creates no log file, then it encountered no problems.

Note Automatically setting/checking permissions on Windows 2000 requires Windows 2000 Service Pack 2 (SP2) and Service Rollup Pack 1 (SRP1), due to a bug in earlier versions of Windows 2000. The installation checks if these are installed, and warns the user if not. These updates can be downloaded and installed from Microsoft using the Windows Update feature.
158
NTFS Issues This file can also be viewed using the View NTFS Permissions Log File link in the Administer S-PLUS Enterprise Server page. A chkrghts.exe utility has been provided to check (or set) NTFS permissions after installation. To use the utility to check permissions, simply open a Command window, cd to the splus70server\cmd directory, and type chkrghts.exe [ssinstall path] [log path name] where: The optional parameter [ssinstall path] is the location of your S-PLUS Enterprise Server installation. The optional parameter [log path name] is the actual name of the file where the log file is updated.
By default, [ssinstall path] is determined by the location of aos.exe, and [log path name] is [ssinstall path]\logfiles\chkrghts.log. If chkrghts.exe finds no errors, then it creates no log file. To use the utility to set permissions, type chkrghts.exe [ssinstall path] [log path name] /correct If chkrghts.exe finds no errors, then it creates no log file, and the permissions were successfully updated. S-PLUS Enterprise Server Web tools displays other error messages to help you diagnose NTFS errors.
159
NTFS Permissions Required for IIS

User IUSR_MACHINE IWAM_MACHINE (IIS)
For Microsoft's Internet Information Server (IIS) and S-PLUS Enterprise Server to work properly, NTFS permissions need to be correctly configured. IIS is the Web server that comes with Windows, and is required for S-PLUS Enterprise Server. Table 10.5 shows the NTFS permissions that must be set to run IIS properly.
Table 10.5: NTFS permissions for IIS and S-PLUS Enterprise Server. Directory Program Files\Common Files Inetpub\wwwroot Winnt Winnt\System32 Winnt\System32\Inetsrv IUSR_MACHINE IWAM_MACHINE (S-PLUS Enterprise Server) splus70server\wwwroot splus70server\cmd splus70server\tmp splus70server\Database\sqlany9 splus70server\wwwroot\temp splus70server\ServerFiles splus70server\wwwroot\aoclient wiz splus70server\wwwroot\aocwiz splus70server\wwwroot\webaocs Read, Execute, Write, and Modify Read, Execute, and Write Read and Execute Permissions Read and Execute
Note that the SYSTEM account and the ADMINISTRATORS group must specify Full Control access to the hard drive. For more information on NTFS permissions required for IIS, see Microsoft Knowledge Base Article Q271071, available at: http://support.microsoft.com/default.aspx?scid=kb;ENUS;q271071
160
NTFS Issues If you plan to use anonymous access with your S-PLUS Enterprise Server web application, you need to provide the permissions detailed above. If you plan to use a nonstandard account for Anonymous access, or some form of Authenticated User access, you must ensure that those users have appropriate permissions. If you change the account that the S-PLUS Enterprise Server Analytic Service uses (which is the SYSTEM account by default), then you need to ensure that account has sufficient permissions.
161
Diagnosing NTFS Issues
The following table details the symptoms and causes for NTFSrelated problems.
Table 10.6: NTFS symptoms and possible causes. Symptom If you navigate to http:// localhost/statserver and get this error page:
You are not authorized to view this page HTTP 401.3 - Access denied by ACL on resource
Possible Cause IUSR/IWAM need read and execute permissions on splus70server\wwwroot to view the S-PLUS Enterprise Server Web tools.
If you navigate to http:// localhost/statserver and get this error page:

S-Plus Server Error The S-Plus Server web interface could not be initialized because the S-Plus Server Automation object could not connect to the database! Check your NTFS Permissions and database connection settings.
IUSR/IWAM need read and execute permissions on splus70server\Database\ SqlAny9 to access the internal S-PLUS Enterprise Server database.
When you are running an analytic and get the error message:
aosfile Line:334 Error:0
Exception in FileSystem. CreateTextFile. This may be due to incorrect NTFS permissions or insufficient disk space.
IUSR/IWAM need write permission on splus70server\wwwroot\ temp to create temporary output files.
162
NTFS Issues
Table 10.6: NTFS symptoms and possible causes. (Continued) Symptom When you are running an analytic, get an empty graphic or a broken graphic link with this error:
Error: Failed to copy graphic output into temporary file. This may be due to incorrect NTFS permissions or insufficient disk space.
Possible Cause IUSR/IWAM need read and execute permissions to splus70server\tmp.
When you are using Create Analytic Interface wizard and it fails with this error:
***Script Error*** aosfile Line:49 Error:0
IUSR/IWAM need write permission to splus70server\wwwroot\ aoclientwiz to create the requested Web page.
Exception in FileSystem.CreateTextFilePerman ent. This may be due to incorrect NTFS permissions or insufficient disk space.
When you are publishing an analytic, and it fails with these errors:
Failed to create directory <some path> ***Script Error*** aosfile Line:79 Error:0
IUSR/IWAM need write permission to splus70server\wwwroot\ aocwiz to publish analytics.
Exception in FileSystem.CreateTextFilePerman ent. This may be due to incorrect NTFS permissions or insufficient disk space.
163
164
S-PLUS ENTERPRISE SERVER
FOR UNIX INSTALLATION

Introduction Basic Installation Procedure
11
166 168 172 172 172 173
Troubleshooting Installation and Licensing Problems Errors in Reading the CD-ROM Errors from INSTALL Permission Errors
165
INTRODUCTION
For most configurations, installing S-PLUS Enterprise Server is a simple process, particularly for new installations. This chapter describes the overall process. If you encounter difficulties in following the procedures documented here, go to section Troubleshooting Installation and Licensing Problems (page 172). This section points out the most common problems with both new and updated installations, and gives cross-references to detailed explanations in later chapters that can solve the problems. Installing S-PLUS Enterprise Server should take less than 30 minutes, although in most cases you should allow two separate sessions to complete the installation. S-PLUS Enterprise Server (and most add-on modules) runs under a license manager that requires you to have a license key generated from information about your UNIX host. For information regarding installation on your specific platform, please consult the Installation Notes (INSTALL_SERVER.TXT). In your first installation session, do the following: Create a directory to hold the S-PLUS Enterprise Server files. Set appropriate permissions for the directory. Read the S-PLUS Enterprise Server files from the distribution CD-ROM. Run the HOSTINFO script to obtain your host ID.
Your License Authorization Code (LAC) should have been delivered to you with your CD. With your host ID and LAC, you can fulfill your license on http://keys.insightful.com to generate your license key (which can be e-mailed to you). When you install your license key, you can proceed to the second installation session where you can do the following: Modify various system configuration options. Install the S-PLUS Enterprise Server script and test the installation. Perform client installations. Install and configure help files.
166
Introduction The instructions in this manual discuss both new installations (if you do not have S-PLUS Enterprise Server installed on your system) and update installations (if you have a previous version of S-PLUS Enterprise Server already installed). In both cases, we strongly recommend that you create a new directory (SHOME) for your S-PLUS Enterprise Server version. If you wish to install S-PLUS Enterprise Server on a system where S-PLUS already resides, be sure to read the section Running S-PLUS Enterprise Server with S-PLUS in INSTALL_SERVER.TXT before performing the installation. Before attempting to install S-PLUS Enterprise Server, you should decide which user account will own the program files. On many systems, it makes sense to create an splus account to own the S-PLUS Enterprise Server files. With such an account, you can be sure that the S-PLUS Enterprise Server system administrator can make future configuration changes to S-PLUS Enterprise Server without having root or superuser privileges. If your system has such an account, you should perform the installation from that account. However, the final stage of installation requires that several files be copied, typically to directories normally owned by root. To copy these files, you need to use the UNIX command su to obtain root permissions. We have attempted to make the installation of S-PLUS Enterprise Server as easy as possible; the instructions in this manual walk you through all the necessary steps. Please follow the instructions carefully. If you have completed the installation instructions but cannot successfully run S-PLUS Enterprise Server, please call your distributor or Technical Support at Insightful Corporation. See the section Technical Support for contact information.
167
BASIC INSTALLATION PROCEDURE

To install S-PLUS Enterprise Server, use the procedure outlined below. You can omit any step labeled OPTIONAL STEP, provided you have appropriate file permissions to accept the system defaults. For more details on the steps listed here, see the following chapters: 1. Create a new directory for the S-PLUS Enterprise Server distribution tree. The top-level directory is called the S-PLUS SHOME . The SHOME must be on a file system with the appropriate amount of disk space; refer to the document INSTALL_SERVER.TXT to determine the amount of disk space required for your platform. Use the UNIX command df to determine the disk space available on your system. Once you have created a new SHOME directory, change to it using the UNIX command cd. 2. Set the UNIX file permissions so that all users can access S-PLUS Enterprise Server:
umask 022
3. Unpack the tar file from the CD-ROM within the new directory, using tar as follows:
cat source/SPLUS.TZ | uncompress | tar xvf -
where source is the path to the CD-ROM drive. Be sure you extract the correct file. On some platforms, including UNIX, the -o flag to tar assigns the identifiers to the user extracting the files. For example, the following reads the Solaris 2.x binaries from a CD-ROM drive:
cat /cdrom/SPLUS.TZ | uncompress | tar xvf -
Depending on your platform, files on the CD may be listed in uppercase or lowercase, or in uppercase letters followed by ;1 (i.e., SPLUS.TZ;1). After mounting the CD-ROM drive, use the UNIX command ls to see the format shown on your system.
168
Basic Installation Procedure If your system has the zcat command, you can use it to shorten your extraction command. The zcat command combines both cat and uncompress:
zcat source/SPLUS.TZ | tar xvf -
4. S-PLUS Enterprise Server uses the FLEXnet license manager, so you need a new license key for all of the following scenarios: You are a new user of S-PLUS Enterprise Server. You are installing S-PLUS Enterprise Server on a new host.
Run the HOSTINFO script in the top level of your S-PLUS Enterprise Server home directory to obtain your server code:
./HOSTINFO
The last line of output contains your server code and should be similar to
Code for server octopus is:80cf91e3
A license authorization code (LAC) should have been sent to you with your CD. With the server code and the LAC, you can now fulfill your license by navigating to http:// keys.insightful.com. A license key will be sent to you that you can install, and you will now be able to run S-PLUS Enterprise Server. You can also contact Technical Support to fulfill your license.
Notes on S-PLUS Enterprise Server Licenses S-PLUS Enterprise Server is licensed separately from S-PLUS, but both use the FLEXnet license manager to control access. S-PLUS can be licensed in a number of ways, including a fixed number of floating licenses (called Session licensing), each of which can be run anywhere on a network, and intended for individual, licensed users. In contrast, S-PLUS Enterprise Server can be licensed for an unlimited number of sessions which are node-locked (Production Server licensing) or by concurrent session (Production Server Session licensing). Refer to the section
S-PLUS Enterprise Server Licensing in Chapter 4, License Management for licensing information. . After you receive your license key, follow the next few steps:
169
Chapter 11 S-PLUS Enterprise Server for UNIX Installation 5. In the top level of your S-PLUS Enterprise Server home directory, run the CONFIGURE script:
./CONFIGURE
Set the various options using the menu selections. The most important option is Destinations and Name of Splus Script, which defines the directory where the shell script used to start S-PLUS Enterprise Server is installed. In most cases, this should be /usr/local/bin. With this CONFIGURE option, you can also change the name of the S-PLUS Enterprise Server script, which is Splus by default. For more details on CONFIGURE, see Step 5: Running CONFIGURE (page 43) and Chapter 13, Setting System Defaults. 6. In the top level of your home directory, run the INSTALL script:
./INSTALL
When you run INSTALL, the installation program prompts you to reply to various license issues. If you have never installed S-PLUS Enterprise Server before, if this is a new host, you will need to enter the license key obtained in Step 4 above. For more information on the INSTALL script, see Step 6: Running INSTALL (page 44). 7. OPTIONAL STEP. Modify your boot sequence so that the license manager starts automatically when the computer reboots. This step is optional, but is highly recommended. If you or your system administrator do not perform this step, S-PLUS Enterprise Server users may need to log in to the server each time they use the software. Some typical scenarios are described in Step 7: Modifying the Boot Sequence (page 48).
8. Test the S-PLUS Enterprise Server installation by typing Splus locally on the server. If S-PLUS starts, this confirms that the installation has completed correctly and the license manager is available. Once you have confirmed the installation has been done correctly, type q() at the S-PLUS command line to exit the application. For more details, see Step 8: Testing Your Installation (page 51).
170
Basic Installation Procedure

.
9. OPTIONAL STEP. Copy the CLIENTS subdirectory of the CDROM to a distribution directory on your system. For example, you might copy it to a clean subdirectory of the servers SHOME. If the directory you choose is visible to UNIX, Linux, and Windows systems on your network, you will be able to perform client installations without physically carrying the CD-ROM to each client machine. 10. Start the S-PLUS session factory. The session factory must be started before any S-PLUS Java clients are launched, as it creates and manages S-PLUS sessions requested by the clients. To start the factory with all defaults in effect, type the following at your UNIX prompt:
Splus SERVER factory
For more information, see Chapter 14, Server Administration. 11. Install S-PLUS Enterprise Server clients on UNIX, Linux, and Windows systems with the instructions given in Chapter 12, S-PLUS Enterprise Server for UNIX Client Installation. This allows your S-PLUS users to access S-PLUS remotely from their desktops. 12. Configure help files with the instructions given in Chapter 18, Configuring Help Services. To give remote clients access to help files from an S-PLUS Enterprise Server installation, a Web server distributes the help files using HTTP. In the simplest case, the Web server runs on the same machine where the server software is installed. Once the Web server is running, simply install the help files within the directory tree that the Web server is using.
171
TROUBLESHOOTING INSTALLATION AND LICENSING PROBLEMS

Some installation problems are obvious at the point at which they occur in the installation procedure; others may not manifest themselves until users try to work with S-PLUS Enterprise Server. For example, if you try to read the S-PLUS Enterprise Server CD-ROM into a file system with inadequate free disk space, you receive an immediate error. See the file INSTALL_SERVER.TXT in the top level of your installation to determine the amount of disk space required for your platform. If you forget to set file permissions, you wont see any errors during installation but the first user who tries to use S-PLUS Enterprise Server may see an error. This section describes the most likely problems that may arise, how to recognize them, and how to correct them.
Errors in Reading the CD-ROM
The following errors are commonly encountered while reading the CD-ROM. There is insufficient disk space in selected file system. If you try to read the CD-ROM into a file system with less than the recommended amount of free disk space, you may encounter the following message from the tar command:
tar: ./cmd/Sqpe: HELP - extract write error: No space left on device
Use the UNIX command df to find a file system with adequate disk space. Alternatively, free the required disk space in the file system you originally specified. The CD-ROM drive is not mounted. Before you can read a CD-ROM drive, the drive must be mounted. Mounting the CD-ROM is usually a task for the system administrator, using the UNIX command mount.
Errors from INSTALL
If S-PLUS Enterprise Server encounters problems running the INSTALL script, it generates error messages. Some of the problems you may encounter with INSTALL are listed below.
172
Troubleshooting Installation and Licensing Problems On most systems, you must have root permissions to install the Splus shell script that starts S-PLUS Enterprise Server. Use the following UNIX command to obtain root permissions:
su
Enter the root password if prompted. If you cannot get root permissions, you can complete the installation by using CONFIGURE to specify destination directories for which you have write permission. See the section Specifying a Destination Directory and Name for the Splus Script (page 192). On some computers, the /usr file system is mounted read-only. If you are unable to create files in this file system with root permissions, consult a system administrator. Your system administrator can either export the file system with read and write permissions to the desired client, or suggest an alternative directory for S-PLUS Enterprise Server and the Splus script. If you read S-PLUS Enterprise Server files into the SHOME for an old version of S-PLUS Enterprise Server, you may receive errors if you did not remove the old files. You should delete files in the old SHOME before attempting to install the new version of S-PLUS Enterprise Server. However, we recommend that you create a completely new SHOME and install the new version of S-PLUS Enterprise Server in that directory.
Permission Errors
If a user encounters the following error:

/usr/local/bin/Splus: /a/herb/files/Splus/cmd/NEW: permission denied
the most likely culprit is that permissions for the S-PLUS Enterprise Server files were not set correctly. It is very important to use the command umask 022 in the SHOME directory to correctly set permissions for the program files before reading the CD-ROM.
173
174
S-PLUS ENTERPRISE SERVER FOR UNIX CLIENT INSTALLATION

Introduction Creating Working Directories Installing the Client Software Solaris and Linux Clients Windows Clients Troubleshooting Telnet Issues Out-of-Memory Errors Help System Failures Starting a Client Login Profiles Advanced Login Options Health and Status
12
176 177 178 178 180 181 181 182 183 184 184 186 188
175
INTRODUCTION
Several steps must be performed before a user can successfully request a Java client from S-PLUS Enterprise Server: 1. An account on the server must be created specifically for each user. 2. A working directory on the server must be created for each user. 3. The client software must be installed on the users system. 4. A session profile should be created to allow the user to access a particular server. Each user of S-PLUS Enterprise Server must have a personal account on the server host, which may be a regular account or an NISconfigured account. All users should have user names, passwords, home directories, and adequate permissions for accessing the file systems pertaining to their work on the server. The details of creating such accounts is not covered in this document. In this chapter, we discuss the second and third steps and give simple instructions for completing client installations. You can find more information on creating session profiles in the section Starting a Client (page 246).
176
Creating Working Directories
CREATING WORKING DIRECTORIES

Before running S-PLUS Enterprise Server for the first time, you should create a working directory on the server specifically for each user. This directory contains any files the user wants to import into or export from S-PLUS, as well as a .Data directory to hold S-PLUS data objects, metadata objects, and help files. S-PLUS working directories are called chapters and are created with the S-PLUS CHAPTER utility. The first time a user runs S-PLUS Enterprise Server, a default chapter called MySwork is created on the server which can function as a working directory. However, we recommend that you create at least one chapter on the server that is separate from MySwork to hold the day-to-day work for each user. When multiple projects are involved, we recommend that you create a separate chapter for each project. To create a working directory named myproj, type the following sequence of commands at the UNIX shell prompt:
mkdir myproj cd myproj Splus CHAPTER
The CHAPTER utility creates a .Data subdirectory, which contains four other directories at start-up: __Meta, __Shelp, __Hhelp, and ___nonfile. The .Data directory contains normal S-PLUS data sets and functions, the __Meta directory contains S-PLUS metadata such as method definitions, and the two __*help directories contain SGML and HTML versions of any help files created for the functions in .Data. The ___nonfile directory records a true file name and the mapped object name in the file in the event the file name has illegal characters, such as forward slashes (e.g., either/or). This directory maps the S-PLUS object to the file __1 . All of these databases are initially empty, except for some possible marker files.
177
INSTALLING THE CLIENT SOFTWARE

Solaris and Linux Clients
The installation procedure for Solaris and Linux clients is very similar to the server installation outlined in Chapter 11, S-PLUS Enterprise Server for UNIX Installation. However, client installations do not require access to a license manager, since the S-PLUS sessions are licensed on the server (not the clients). To install S-PLUS on a Solaris or Linux client, use the procedure outlined below. You can omit any step labeled OPTIONAL STEP , provided you have appropriate file permissions to accept the system defaults. 1. Create a new directory for the S-PLUS Enterprise Server client. The top-level directory is called the client SHOME . The SHOME must be on a file system with the appropriate amount of disk space; refer to the document INSTALL_SERVER.TXT to determine the amount of disk space required for your platform. Use the UNIX command df to determine the disk space available on your system. Once you have created a new SHOME directory, change to it using the UNIX command cd. 2. Set the UNIX file permissions so that all users can access S-PLUS:
umask 022
3. Unpack the tar file from the CD-ROM within the new directory, using tar as follows:
cat source/CLIENTS/clientpf/SPLUS_CLIENT.TZ | uncompress | tar xvf
where source is the path to the CD-ROM drive, and clientpf is the platform of the client machine. Be sure you extract the correct file. On some platforms, including UNIX, the -o flag to tar assigns the identifiers to the user extracting the files.
178
Installing the Client Software For example, the following reads the Solaris 2.x client binaries from a CD-ROM drive:
cat /cdrom/CLIENTS/SOLARIS/SPLUS_CLIENT.TZ | uncompress | tar xvf
Depending on your platform, files on the CD may be listed in uppercase or lowercase, or in uppercase letters followed by ;1 (i.e., SPLUS_CLIENT.TZ;1). After mounting the CDROM drive, use the UNIX command ls to see the format shown on your system. If your system has the zcat command, you can use it to shorten your extraction command. The zcat command combines both cat and uncompress:
zcat source/CLIENTS/clientpf/SPLUS_CLIENT.TZ | tar xvf
Note If you copied the client installation files to a distribution directory on your network, as described in Step 9: Copying the Client Binaries (page 52), substitute the appropriate path in the cat commands above. For example, suppose the client binaries are located in a ClientInstall subdirectory under your servers SHOME. The following unpacks the correct files:
cat `Splus SHOME`/ClientInstall/clientpf/SPLUS_CLIENT.TZ|uncompress|tar xvf
4. In the top level of your S-PLUS home directory, run the CONFIGURE script:
./CONFIGURE
Set the option Destinations and Name of Splus Client Script, which defines the directory where the shell script used to start an S-PLUS Enterprise Server client is installed. The default path is
/usr/local/bin
but note you must have permissions to write to this directory, since you are installing the client (with these customizations) to this directory. With this CONFIGURE option, you can also change the name of the S-PLUS Enterprise Server client script, which is SplusClient by default.
179
Chapter 12 S-PLUS Enterprise Server for UNIX Client Installation 5. In the top level of your S-PLUS home directory, run the INSTALL script:
./INSTALL
You can run INSTALL as a regular user (yourself or splus) if you have write permission to the destination directory of the SplusClient script. If you need to install the script in a directory that only root can write to, you must run INSTALL while logged in as root. You may need to use the UNIX command rehash to make the SplusClient command visible. 6. To start an S-PLUS Enterprise Server session on a client, type:
SplusClient
Before a user can start a client session of S-PLUS, a session profile must be created. For more details, see the section Starting a Client (page 246).
Windows Clients
To install an S-PLUS Enterprise Server client on a Windows machine, double-click the file setup.exe in the following subdirectory of the S-PLUS Enterprise Server CD-ROM:
CLIENTS/WINDOWS
The installation wizard appears and guides you through the steps required to install the client on your workstation. If you copied the client installation files to a distribution directory on your network, as described in Step 9: Copying the Client Binaries (page 52), substitute the appropriate path above. For example, suppose the client binaries are located in a ClientInstall subdirectory under your servers SHOME. Find this directory in the Network Neighborhood, open the WINDOWS folder under it, and then double-click the setup.exe file. Once the client is installed, choose Start Programs S-PLUS 7.0 Enterprise Server Windows Client Client Login to start S-PLUS. Before a user can start a client session of S-PLUS, however, a session profile must be created. For more details, see the section Starting a Client (page 246).
180
Troubleshooting
TROUBLESHOOTING
When a login failure occurs, the returned error message should be sufficient to diagnose the cause of the failure. However, users may need administrative assistance in fixing the error condition. In this section, we describe three of the most common causes of login failures: telnet issues, memory limits, and license problems. In addition, we discuss a common cause of failure for the S-PLUS Enterprise Server help system.
Note When running an S-PLUS client on Windows, error messages that are sent to the standard output (the screen) are not visible. To see these messages, start the S-PLUS client using a DOS batch script instead of the Windows shortcut. The script login.bat is provided for this purpose in the SPLUS Server program folder. Starting the client using the DOS script allows you to see all error messages, which may help diagnose login problems.
Telnet Issues
S-PLUS Enterprise Server employs telnet sessions to connect clients with S-PLUS sessions on the server. Something like a chat script is used during this process, where the telnet client expects a particular response from the server before sending a new command via telnet. By default, a space character is accepted as a valid server response. If a client experiences difficulties when logging in to the server, a telnet prompt string may be specified in the Advanced Session Profile Options dialog; see the section Advanced Login Options (page 248) for details. The prompt string provides an exact string to await as a server response. It should match the prompt string a user receives during an active telnet session on a given host. For example, user richardc on host mountain might have a prompt such as:
[richardc@mountain richardc]$
The remainder of this section describes the default telnet session, and should help administrators understand the log file record of connection traffic. The default chat script starts by sending a login name and password. This is followed by two dummy RETURN commands, which ensure that the login has succeeded. Next, a whoami command is sent to
181
Chapter 12 S-PLUS Enterprise Server for UNIX Client Installation make certain that valid responses are being sent. If whoami succeeds, the command to start the session is given and the telnet session is exited. Depending on the network load and the responsiveness of the host, this process takes around ten seconds. One invisible telnet transaction occurs that you should be aware of. When using telnet over Java sockets, Java sets TERM to network. The Linux installations we have tested do not accept this terminal type by default, and reply with the challenge
unknown terminal "network"
The Linux installations then prompt for a new terminal type specification. Rather than require all users to adjust their /etc/ termcap entries, the prompt is automatically answered with ansi when the challenge is detected. This transaction is not written to the log file and does not occur on UNIX servers. The telnet chat script has proven successful on all UNIX and Linux hosts that we have tested. Still, the permutations of operating system peculiarities and shell-initialization sequences are vast, and this script may fail if an unexpected challenge is received from the telnet server. If such a situation arises, the first troubleshooting strategy is to try and eliminate the challenge. For unusual circumstances that cannot be worked around, we anticipate the need to customize the chat script. We have not yet implemented this feature in S-PLUS Enterprise Server. Instead, we await customer feedback about problems that actually turn up, so that we might implement a fully effective solution.
Out-ofMemory Errors
Opening or closing a large number of graph sheets in the S-PLUS Java GUI sometimes causes out-of-memory errors. This is caused by the client JVM running out of heap memory space. The workaround is to boost the maximum heap using the Java -Xmx option. On Windows clients, add the -Xmx option to the shortcut properties for S-PLUS. For example, adding
-Xmx128m
increases the available heap memory to 128 MB.
182
Troubleshooting On UNIX and Linux clients, set the JAVA_OPTIONS environment variable in the shell before starting the client. For csh and tcsh, use the command
setenv JAVA_OPTIONS -Xmx128m
For sh, bash, and ksh, use the command

export JAVA_OPTIONS=-Xmx128m
Help System Failures
The help system for S-PLUS Enterprise Server utilizes a Web server. This may be on the machine where S-PLUS Enterprise Server is installed, on some other machine on your local network, or anywhere on the Internet. If an attempt to invoke the S-PLUS help system via the help function or the Help menu does not work, you have several choices: 1. Configure a Web server on your network, as described in Chapter 18, Configuring Help Services. An improperly configured Web server is the most common cause of help system failures in S-PLUS Enterprise Server. 2. Edit the Advanced Session Profile Options dialog so that the Help System URL reads www.insightful.com See the section Advanced Login Options (page 248) for details. We will maintain a Web server at this address that supports the S-PLUS Enterprise Server help system. 3. Run the S-PLUS Enterprise Server help viewer application locally on your client machine, using the Web server at www.insightful.com. For UNIX and Linux clients, type
SplusClient HELPSTART -url www.insightful.com
For Windows clients, select Start Programs S-PLUS 7.0 Server Windows Clients S-PLUS Help at www.insightful.com.
This option allows you to browse the help files, but invoking help from the S-PLUS command line does not work. See the section Using the S-PLUS Help Viewer (page 243) for more information.
183
STARTING A CLIENT
The method you use to start a client for S-PLUS Enterprise Server depends on the platform you are using. On UNIX and Linux, you start a client with the following command:
SplusClient [-helpoff]
The optional -helpoff flag prevents the help system from initializing at start-up, which decreases the initial memory requirements by half. To start a client on Windows, choose Start Programs S-PLUS 7.0 Enterprise Server Windows Client Client Login. To start the S-PLUS client without the help system, modify the session profile as explained in the section Advanced Login Options (page 186). On all platforms, the client should display the Client Login dialog, as shown in Figure 12.1.
Figure 12.1: The Client Login dialog.
Login Profiles
To establish the correct permissions for a requested session, you must supply a login and password for the server. Since the same login may be used for several different tasks, a specific combination of session options is assembled into a login profile that should be unique to a particular task. The first time you run a client for S-PLUS Enterprise Server, you will need to create a new login profile. To do this, click the Edit button on the login dialog; you can also click Edit to modify existing profiles. The Edit Session Profile dialog appears, as shown in Figure 12.2.
184
Starting a Client
Figure 12.2: The Edit Session Profile dialog.
The required fields for a minimal profile are as follows. Profile Name: Each profile must have a unique name. User Name: This is used when logging in to the specified server. Server Host: This is the machine on which S-PLUS Enterprise Server is installed. This field accepts valid IP addresses in situations where naming services are inadequate.
Optional fields are available for specifying a particular working directory and an X-server DISPLAY string. The DISPLAY string specifies the client display, which is used to launch X windows for S-PLUS functions such as motif, brush, and spin; it is identical to the UNIX environment variable DISPLAY. For more information on these options, click on the Help button in the dialog. For example, Figure 12.3 shows the settings required to create a profile named sprime that uses lbajuk as the user name, sprime as the server, and the directory myproj in lbajuks home directory as the working directory. The example also explicitly specifies the Xserver display.
185
Figure 12.3: Example of modifying a profile using fields in the Edit Session Profile dialog.
The Work Directory for a profile contains a subdirectory named .Data that stores any S-PLUS objects created during the session. The default working directory is called MySwork and is located in the users home directory. If MySwork doesnt exist, it is created automatically. To use a different directory as the working directory, you must first initialize it as a valid S-PLUS chapter by using the CHAPTER utility. See the section Creating Working Directories (page 177) for details. Once you define a login profile, select it from the Session Profile drop-down list box in the login dialog. Enter a valid password, then press the ENTER key or click the Login button. If the login fails for any reason, a message box appears that describes the error condition. Most errors allow you to adjust your login options and retry the login.
Advanced Login Options
Advanced login options are available by clicking the Advanced button on the Edit Session Profile dialog box. The dialog in Figure 12.4 appears.
186
Starting a Client
Figure 12.4: The Advanced Session Profile Options dialog.
To start the S-PLUS client without a help viewer, check the Help viewer off at startup box. If help files are served by a host other than the one you are logging into, you should enter a Help System URL designating the other host. If S-PLUS Enterprise Server is running RMI on a port other than 1099, the port number must be specified in the Advanced Session Profile Options dialog. Additionally, a telnet prompt string may be supplied in case there are difficulties connecting to the server; refer to the section Telnet Issues (page 181) for a full explanation. The Telnet Script option is not implemented in this version of S-PLUS Enterprise Server. Additional information on all of these optional settings can be found by clicking on the Help button.
187
HEALTH AND STATUS

Once a client has acquired a remote S-PLUS session from the server, the two machines communicate directly with one another via RMI and have no further interaction with the S-PLUS session factory. If either the local or the remote process crashes, it could cause the remaining process to hang, requiring extra effort to shut it down. To avert this condition, each side of the connection checks the other via an RMI call every five minutes. If the RMI call fails, the calling process assumes its partner has failed and self-terminates. This presupposes a nearly continuous network connection. If the network link between the two computers is broken for even a few seconds, there is a likelihood that one or the other will give up and quit. Hence, you should terminate any S-PLUS clients before modifying your network connections.
188
SETTING SYSTEM DEFAULTS
13
190 192 194 195 195 195 196 197 198 199 199 200
Introduction Specifying a Destination Directory and Name for the Splus Script Configuring S-PLUS Server to Produce Graphics on Your Printer Set Print Orientation Set Print Method Set Print Command Set HP LaserJet Print Resolution Configuring S-PLUS Server to Print Help Files Setting License Manager Options Set Log File Options Set the Remote Server Auto-Start Command Installing the S-PLUS Man Page
189
INTRODUCTION
When installing S-PLUS Server, you may need to specify where the INSTALL script places program files. You may want to set defaults for printing help files or for how S-PLUS Server produces graphics on your printer. All these tasks, and more, are performed using the optional CONFIGURE script. Running CONFIGURE is an optional part of the S-PLUS Server installation procedure. The installation comes with built-in defaults for all items described in this chapter. The defaults are usually sufficient for most configurations, but if you determine that some of the defaults are not appropriate for your installation, you can run CONFIGURE and set them appropriately. If you do not run CONFIGURE during the initial installation process, you can nevertheless proceed and complete the installation as root. If you decide in the future that you would like to modify particular settings, you can run the CONFIGURE script at that time; however, you will need root privileges to do this. The CONFIGURE script allows you to perform the following actions: Set defaults for printing hard-copy graphics and help files. Specify destinations and names for the S-PLUS Server script, the log file, and the resources file. Set some defaults for the S-PLUS Server license manager. Install the UNIX manual page for S-PLUS.
To run CONFIGURE, you must be in the top-level directory of your S-PLUS Server installation. You can return to this directory at any time by issuing the following command:
cd `Splus SHOME`
Note the back-ticks surrounding the location Splus SHOME. To start CONFIGURE, issue the following command:
./CONFIGURE
190
Introduction The main Configuration Options menu appears on your screen:

Configuration Options: 1: 2: 3: 4: 5: 6: 0: About This Menu Graphics Hard Copy Printing Help File Printing Destinations and Name of Splus Script License Management Installation of S-PLUS man page Exit this Menu
You must enter a number between 0 and 6 Enter the number of your choice:
All of the CONFIGURE menus have the same form: a numbered list of options and a prompt at which to enter the desired option. To choose an option, type its corresponding number at the prompt. Use option 0 to leave any CONFIGURE menu. From the top-level menu, this returns you to the UNIX shell. From lower-level menus, it returns you to the menu one level higher up. The choices you make with CONFIGURE are not actually installed until you run the INSTALL script. Therefore, you can simply run CONFIGURE again if you want to change your choices before installing them.
191
SPECIFYING A DESTINATION DIRECTORY AND NAME FOR THE SPLUS SCRIPT

By default, the location of the script Splus that starts S-PLUS Server is /usr/local/bin. If you wish to specify a different location for the script, select Destinations and Name of Splus Script from the Configuration Options menu. This option produces the submenu that appears below. The option labeled Location for Splus shell script allows you to change the destination directory for the script; the default value is shown to the right of the label.
You must enter a number between 0 and 6 Enter the number of your choice: 4 Destination and Name for Splus Script: 1: 2: 3: 0: Location for Splus shell script Name of Splus shell script About This Menu Return to Previous Menu "/usr/local/bin" "Splus"
To change the location of the Splus script, press 1 and enter the desired path. For example, /local/bin. After you enter the new path, it appears as the default location in the menu, to the right of the Location for Splus shell script label. The change does not take effect until you run the INSTALL script.
192
Specifying a Destination Directory and Name for the Splus Script As weve mentioned, the default name of the script that starts S-PLUS Server is Splus. If you wish to specify a different name for the script, select the option Name of Splus shell script. Press 2 and enter the new name; the change will be implemented after you run INSTALL.
Note If you try to install the Splus script in a directory that already has a script with the same name, you see the following message:
/usr/local/bin/Splus already exists. You can enter a new location for the script, enter a new name for the script (e.g. nSplus), or overwrite the current script. Overwrite current Splus script [y/n]?
If you select y, the current Splus script is overwritten. If you select n, you are returned to the Destinations and Name of Splus Script menu, where you can select options to change either the location or the name for the Splus script.
193
CONFIGURING S-PLUS SERVER TO PRODUCE GRAPHICS ON YOUR PRINTER

If you want to specify system-wide defaults for printing graphics in S-PLUS Server, select Graphics Hard Copy Printing from the Configuration Options menu. The Setting Print Defaults menu appears:
You must enter a number between 0 and 6 Enter the number of your choice: 2 Setting Print Defaults Menu: 1: 2: 3: 4: 5: 6: 0: Set Print Orientation Set Print Method Set PostScript Print Command Set HP LaserJet Print Command Set HP LaserJet Resolution About This Menu Return to Previous Menu Current Value: "landscape" "postscript" "lp" "lp -dhp" "100"
In this section, we discuss each of the options shown in the menu. After you complete the changes and run the INSTALL script, the changes are saved as your default settings. When you call a graphics device and print a graphic, the new settings should be used as your defaults.
194
Configuring S-PLUS Server to Produce Graphics on Your Printer
Note on Printing The printing options available in the Configuration Options menu control printing only on the server. If a user prints from the S-PLUS Java GUI on their client, the printing behavior is determined by the clients printing configuration.
Set Print Orientation
To set the print orientation of your hardcopy output: 1. From the Setting Print Defaults menu, press 1 and hit the RETURN key. The Select the default orientation of Hardcopy Plots menu appears on the screen. 2. To choose the portrait orientation, where the x-axis prints on the short side of the paper, press 2 and hit RETURN. To choose the landscape orientation, where the x-axis prints on the long side of the paper, press 1 and hit RETURN. The landscape orientation is the default.
Set Print Method
To set the type of output for your hardcopy documents: 1. From the Setting Print Defaults Menu, press 2 and hit RETURN. The Set Print Method menu appears on the screen. 2. If you have an HP LaserJet or other PCL printer, choose laserjet by pressing 2 and then RETURN. To choose the postscript printing method, press 1 and hit RETURN. The postscript method is the default.
Set Print Command
If you use the PostScript method to print your hardcopy output, choose Set PostScript Print Command by pressing 3 from the Setting Print Defaults menu. The program prompts you for a UNIX command that will be used to send PostScript files to your printer. The following is a typical PostScript print command for UNIX and Linux workstations:
lp
If you use the LaserJet method to print your hardcopy output, choose Set HP LaserJet Print Command by pressing 4 from the Setting Print Defaults Menu. The program prompts you for a UNIX
195
Chapter 13 Setting System Defaults command that will be used to send LaserJet files to your printer. The following is a typical LaserJet print command for UNIX and Linux workstations:
lp -dhp
Set HP LaserJet Print Resolution
If you have an HP LaserJet or other PCL printer and need to set the default resolution, follow the steps below. The resolution units are in dots per inch (DPI). 1. From the Setting Print Defaults menu, press 5 and then hit the RETURN key. The Select a value for HP LaserJet Resolution menu appears on the screen. 2. To choose 75 DPI, press 1 and hit RETURN. 3. To choose 100 DPI, press 2 and hit RETURN. This option is the default. 4. To choose 150 DPI, press 3 and hit RETURN. 5. To choose 300 DPI, press 4 and hit RETURN. Smaller values produce plots with poorer resolution than the higher values, but they print more quickly.
196
Configuring S-PLUS Server to Print Help Files
CONFIGURING S-PLUS SERVER TO PRINT HELP FILES

To specify a print command for printing S-PLUS help files, select Help File Printing from the Configuration Options menu. The program prompts you for the UNIX command to use for printing help files:
You must enter a number between 0 and 6 Enter the number of your choice: 3 Enter the UNIX command which sends a file to your PostScript printer:
197
SETTING LICENSE MANAGER OPTIONS

If you want to specify options for the license managers log file or resources file, or if you need to set a command to start the license server daemon on a remote system, choose the License Management option from the Configuration Options menu. With this selection, you can also set options to install UNIX manual pages that document file formats and commands used by the license manager. From the Configuration Options menu, press 5 and hit the RETURN key. The License Manager menu appears on your screen, as shown below. In the sections below, we discuss each of the options in this menu.
You must enter a number between 0 and 6 Enter the number of your choice: 5 License Manager Menu: 1: 2: 3: 4: Current Value:
Set Server Logfile Name "adm/lic/logs/splus.log" Set Server Logfile Max Size "250k" Set Server "resources" File "adm/lic/splus.res" Remote server auto-start cmd:
rsh %s env SHOME=$SHOME Splus LICENSE server start 5: Installation of command(section 1) man pages 6: Installation of file format(section 5) man pages 7: About This Menu 0: Return to Previous Menu
198
Setting License Manager Options
Set Log File Options
You can set an option for the license server log file. Set the maximum size of the log file as follows: To choose the Set Server Logfile Max Size option, press 2 and hit RETURN. A prompt to enter the maximum size for the log file appears on the screen. Enter the maximum size of the log file in kilobytes (e.g., 250k) or megabytes (e.g., 2m) and press RETURN. The default value is 250k.
Set the Remote Server Auto-Start Command
The auto-start command for remote servers starts the license manager on a remote system. To set this command, do the following: 1. To choose the Remote server auto-start cmd option, press 4 and hit RETURN. A prompt to enter the command to start a remote license server appears on the screen. 2. Enter the command to start the license server on a remote machine and press RETURN. For example, enter
rsh %s env SHOME=$SHOME Splus LICENSE server start
Here, the %s argument is the remote server name where the license server will be started. For example, to start the license manager on a machine named spud, type
rsh spud env SHOME=$SHOME Splus LICENSE server start
199
INSTALLING THE S-PLUS MAN PAGE

To specify a location for the S-PLUS man page, select Installation of S-PLUS man page from the Configuration Options menu. The program prompts you for the path to the directory in which to install the man page, as shown below. After this is installed, you can run man splus to see a UNIX manual page for S-PLUS.
You must enter a number between 0 and 6 Enter the number of your choice: 6 Where should the S-PLUS UNIX manual pages be installed?
200
SERVER ADMINISTRATION
14
202 203 203 205 207 208 209 210 211 212 213 213 214 215
Introduction Starting the S-PLUS Session Factory From the Graphical User Interface From the UNIX/Linux Command Prompt Managing the S-PLUS Session Factory Terminating Sessions Session Limits Server Log Files RMI Port Numbers Stale References S-PLUS Enterprise Server and RMI Services Terminating the Java RMI Server Providing Multiple RMI Services Security Issues
201
Chapter 14 Server Administration
INTRODUCTION
This chapter describes many of the tools you need to administer S-PLUS Enterprise Server. In the sections that follow, we discuss the S-PLUS session factory and parameters you can set to customize your system. In addition, we discuss common concerns that arise in a client-server configuration, such as security issues. To effectively manage S-PLUS Enterprise Server, it is important to understand its architecture. Figure 14.1 shows the most typical deployment of S-PLUS Enterprise Server. One or more S-PLUS Java clients connect to S-PLUS sessions on one or more servers. Each server has a session server that responds to requests from a client to start a new S-PLUS session. Once the session has been started, the S-PLUS client connects directly to the S-PLUS session on the server. The clients and servers communicate via Java Remote Method Invocation (RMI). When the help viewer is started on a client, either independently or from within the S-PLUS client, it connects to a Web server via HTTP to retrieve the requested help files. The Web server may be on the same machine as the S-PLUS session server, or it may be on a different machine.
S-PLUS Java GUI
S-PLUS Java Help Viewer
S-PLUS Java GUI
S-PLUS Java GUI
Clients
RMI HTTP RMI HTTP RMI HTTP
S-PLUS Session Server
S-PLUS Session Server
Web Server
S-PLUS Session S-PLUS Session S-PLUS Session
S-PLUS Session S-PLUS Session S-PLUS Session
S-PLUS Help Files
Servers
Figure 14.1: Typical deployment of S-PLUS Entrprise Server. Clients request S-PLUS sessions on one or more servers using Java RMI. Each server can run multiple S-PLUS sessions. Help files are made available through a Web server.
202
Starting the S-PLUS Session Factory
STARTING THE S-PLUS SESSION FACTORY

The S-PLUS session factory must be started before any S-PLUS Java clients can be launched. The session factory creates and manages the S-PLUS sessions that are requested by clients. Several options are available in starting up the S-PLUS session factory, which you can use to limit the number of sessions, specify a non-default log file, rotate a log file, and specify a port number over which to provide RMI services. In this section, we show how to start the session factory from both the administration GUI and from the UNIX/Linux prompt. See the section Managing the S-PLUS Session Factory (page 207) for descriptions of each of the options and details on setting them.
From the Graphical User Interface
The administration GUI for the S-PLUS session factory can be launched with the following UNIX command:
Splus SERVER -servertools [portnumber]
where the optional portnumber argument specifies a non-default RMI port. Alternatively, portnumber may be omitted at launch time and changed once the GUI appears. The above command launches the S-PLUS Server Tools dialog, as shown in Figure 14.2. In the administration GUI, there are text entry fields that allow the administrator to specify the RMI port, the maximum number of sessions, and an alternate log file path name. There is also a check box named Rotate Log Daily that indicates whether the log file should be rotated; if this option is checked, a new log file is created each day. See the section Server Log Files (page 210) for details.
203
Figure 14.2: S-PLUS Enterprise Server S-PLUS Server Tools dialog.
Clicking the View button in the Server Tools dialog allows you to view the session factory log file, as shown in Figure 14.3. Once the options in the Server Tools dialog have been set to your satisfaction, the S-PLUS session factory can be started by clicking the Start button. See the section Managing the S-PLUS Session Factory (page 207) for details on the options in the administration GUI.
204
Starting the S-PLUS Session Factory
Figure 14.3: Session factory log file, accessed from the Server Tools dialog.
From the UNIX/Linux Command Prompt
The session factory can be started from a UNIX or Linux prompt with the following command:
Splus SERVER -factory [-limit session_count] [-logfile filepath] [-rotate] [portnumber]
The optional entries session_count, filepath, and portnumber are described in Table 14.1, along with their default values. The -factory argument must appear first in the command and portnumber must appear last. The remaining arguments may appear in any order. For example, to start the session factory with all defaults in effect, type the following command:
Splus SERVER -factory
Note When Splus SERVER -factory executes, it checks if a factory is already running. The execution ends and a message reporting the conditions is displayed to the terminal. When Splus SERVER -factory actually starts a new factory process, it attempts to use an existing RMI server. If it does not find one, it launches one.
205

Table 14.1: Optional entries for the S-PLUS session factory. Flag
-limit session_count
Description Limits session creation to the specified number. Specifies the absolute path to the log file. Specifies that the log file should be archived and renewed each day. Specifies the port number over which to provide RMI services.
Default 100
-logfile filepath
$SHOME/adm/logs/factory_[portnumber].log
-rotate
no rotation
portnumber
1099
206
Managing the S-PLUS Session Factory
MANAGING THE S-PLUS SESSION FACTORY

A list of active S-PLUS Enterprise Server sessions can be viewed from the administration GUI, as shown in Figure 14.2 (page 204). To ensure that the list is current, click the Refresh button in the S-PLUS Server Tools dialog. For each session, the administrative tools display the fields listed in Table 14.2.
Table 14.2: Tools that are displayed for each session in the administration GUI. Field Session ID User ID Session Host Description Uniquely identifies each session. Login name of the user. The server on which the session is running. In S-PLUS Enterprise Server, all sessions administered by the tools must run on the same server. Thus, this field is not currently used but is reserved for future versions of S-PLUS Enterprise Server. The port used for RMI communication. The location of the X-server display. While the S-PLUS Java GUI does not require an X-server for displays, certain functions invoked from the S-PLUS command line do. Examples include the S-PLUS functions motif, brush, and spin. The location of the help files. The current working directory used by the session
Port Number Display
Help Host Work Dir
207
Chapter 14 Server Administration S-PLUS client sessions can also be administered from the UNIX or Linux prompt, using the commands listed in Table 14.3.
Table 14.3: Session administration commands. Command
Splus SERVER -list [portnumber]
Description Produces a list of active sessions for the specified port. There is minor latency (usually less than 15 seconds) in adding and removing sessions from this list. Terminates the specified sessions on the specified port. Terminates the factory task but leaves the RMI services active. Terminates the RMI services (if possible).
Splus SERVER -killsession [-p portnumber] sessionid
Splus SERVER -factoryoff [portnumber]
Splus SERVER -rmioff [portnumber]
Terminating Sessions
To terminate a particular session from the Server Tools dialog, click the session in the session list to select it, and then click the Kill button. To terminate the session factory, click the Stop button; this causes all existing sessions to be terminated. At this time, there is no provision for shutting down the RMI services from the GUI. To terminate a particular session from the UNIX or Linux prompt, use the -killsession flag to the Splus SERVER command. The general syntax for doing this is listed in Table 14.3. The -killsession flag requires an identification number for the session you wish to terminate. You can obtain this as follows:
Splus SERVER -list 1299
This returns a list of entries similar to the following one:

SplusSession_1299_4 lenk orange:1299 knife:0.0 orange /homes/lenk/junk
208
Managing the S-PLUS Session Factory The -list flag displays the same fields for each user as the Server Tools dialog; see Table 14.2 above for descriptions of the fields. Thus, the session shown here is for the user lenk, the server is the machine orange, the port number is 1299, the display host is knife, the Web server for the help files is orange, and the working directory is /homes/lenk/junk. To terminate this session, issue the following command:
Splus SERVER -killsession -p 1299 SplusSession_1299_4
Note that the session identification number appears after the port number in the command. To stop session factory, supply the -factoryoff flag:
Splus SERVER -factoryoff
To terminate RMI services, use the -rmioff flag:

Splus SERVER -rmioff
The -rmioff option works only if the session factory and the RMI server run in the same JVM; see the section Terminating the Java RMI Server (page 213) for more details.
Session Limits
By default, the maximum number of sessions allowed by the S-PLUS session factory is 100. However, there is no built-in limit to the number of sessions that can be started. The number of sessions that a server can support depends on hardware issues, such as available memory and the number of CPUs. Depending on your host resources, you may wish to restrict the number of sessions that are created to ensure that other critical tasks do not fail due to resource exhaustion. In our testing, available memory has been the primary limiting factor in creating idle sessions. Exceeding available memory (that is, using virtual memory) by about 100 MB results in serious performance degradation due to disk thrashing on the host machine. CPU availability is the primary limit in supporting active sessions. Initial testing has shown that S-PLUS Enterprise Server is most stable and robust when the number of sessions is limited to approximately four per CPU. On some Linux servers, there is a hard limit of approximately 13 sessions because of the 512 process limit compiled
209
Chapter 14 Server Administration into the Linux kernel. The number of active sessions is also affected by available memory and usage. In some cases, the Linux OS filedescriptor limit can be exceeded as well. Limiting sessions from the GUI You can change the maximum number of S-PLUS client sessions by typing the desired number in the Max Sessions text box of the S-PLUS Server Tools dialog. The Max Sessions option be changed either before or after the session factory has been started. If it is changed while the session factory is running to a value less than the number of existing sessions, no sessions are terminated. However, no new sessions are created until the number of sessions drops below the new limit. Limiting sessions from the UNIX/Linux prompt To start the session factory so that it serves a limited number of S-PLUS client sessions, include the -limit flag in the call to Splus SERVER. For example, the following command limits the number of client sessions to thirteen:
Splus SERVER -factory -limit 13
Server Log Files
The S-PLUS session factory log file records the start-up and shut-down events for all requested sessions. In addition, it records the telnet transactions that occur during the creation of a session. This can be a valuable tool to help determine why a user may have difficulty creating a remote session. By default, the log file is located in the S-PLUS Enterprise Server installation tree, in a file named $SHOME/adm/logs/factory_[portnumber].log. You may wish to move it to a directory that stores log files exclusively, such as /var/log. If the session factory is very active, it may be desirable to restart the log file each day. You can do this by rotating the log file, which ensures that a new log file is started on a daily basis. Older logs can then be discarded without affecting the current log. By default, log files are not rotated. Although no automated discarding or truncating utility for log files has been implemented in this release of S-PLUS Enterprise Server, you can configure a cron job for this purpose.
210
Managing the S-PLUS Session Factory Managing log files from the GUI To designate a particular file as a log file for S-PLUS Enterprise Server, type its full path in the Log File Name text box of the Server Tools dialog. To restart the log file each day, check the Rotate Log Daily box. To view the log file in a separate window, click on the View button. Managing log files from the UNIX/Linux prompt To designate a particular log file when starting the S-PLUS session factory from a UNIX or Linux prompt, supply the -logfile flag. For example, the following starts the session factory with a log file of /tmp/splus.log:
Splus SERVER -factory -logfile /tmp/splus.log
The next command writes to the same log file, but rotates it on a daily basis:
Splus SERVER -factory -logfile /tmp/splus.log -rotate
RMI Port Numbers
Java RMI services default to port 1099. If S-PLUS is the only RMI service that is configured on a server, the default port should be adequate. However, RMI services may be required for many applications other than S-PLUS, and you might wish to isolate S-PLUS on its own RMI server by specifying a non-default port number. Similarly, if S-PLUS Enterprise Server needs to run on the same machine as a different release of S-PLUS Enterprise Server, this is accomplished easily by having two different RMI ports active. Defining a port number from the GUI To designate a particular port for S-PLUS Enterprise Server, type the desired number in the Port Number text box of the Server Tools dialog. Defining a port number from the UNIX/Linux prompt To designate a particular port when starting the S-PLUS session factory from a UNIX or Linux prompt, simply type the port number at the end of the Splus SERVER command. For example, to use port 1070, type:
Splus SERVER -factory 1070
211
Stale References
The S-PLUS session factory keeps a list of active sessions. Under normal conditions, a session removes itself from the list when it exits. If the session fails abnormally, however, a stale reference to it can exist on the list of sessions. To clean up these stale references, the factory process executes an RMI call to all registered sessions at five minute intervals; we refer to this call as the clean-up thread . If a session fails to respond to the RMI call, it is removed from the active list. If a stale reference to a session remains on the factory list for longer than five minutes, the factory clean-up thread may be hung or the process may be in some unresponsive state. In this case, you should first look for and kill any orphan processes from the session. If the stale reference persists after another five minutes, you should stop and restart the S-PLUS session factory. This kills all active sessions in addition to eliminating stale references; thus, users should be warned to exit their sessions prior to the restart. Note that a stale reference does not interfere with any sessions that are still active.
212
S-PLUS Enterprise Server and RMI Services
S-PLUS ENTERPRISE SERVER AND RMI SERVICES

Terminating the Java RMI Server
Two servers are actually in operation when you access S-PLUS Enterprise Server: 1. The S-PLUS session factory, and 2. The Java RMI server. The Java API for the RMI server appears to lack any means of terminating the RMI server. The server self-terminates once all objects registered with it have de-registered, with an approximate five minute latency. Testing has shown that it is possible to register new RMI objects with the server during this latency period. The registration succeeds but the RMI server still terminates once the five minutes has elapsed. Because of this behavior, it is possible to stop the session factory and immediately start it again, only to have the RMI server terminate a few minutes later. To avoid this condition, S-PLUS Enterprise Server starts a keep-alive thread whenever it initiates RMI services. This allows you to start and stop the S-PLUS session factory as needed. Note that if RMI services are already initiated when S-PLUS Enterprise Server launches, the keep-alive thread does not start. In stopping and starting the session factory, the factory and the RMI server run in different JVMs; this makes it impossible to terminate the RMI services from S-PLUS. The only recourse in this scenario is to manually kill the Java process running the RMI server with the UNIX command kill -9. You can avoid this problem entirely by always starting the RMI server at the same time as the factory with the command Splus SERVER -factory. Likewise, you should always end the factory at the same time as the RMI server using Splus SERVER -rmioff. However, this may not always be practicable. If you must start RMI services independently of S-PLUS Enterprise Server, you may need to devise a custom solution for your system.
213
Providing Multiple RMI Services
In some circumstances, a single host may be used to provide many RMI services. In this event, you might configure a Java application to start all RMI services at once when the host is booted. The following information should help to integrate the start-up of the S-PLUS session factory into such a system. 1. The CLASSPATH environmental variable must be adjusted to include the Splus.jar file, which is normally located in $SHOME/java/Splus.jar. 2. The Java System property splus.shome must be set to a string indicating the S-PLUS Enterprise Server installation directory (SHOME). For example, the command below sets splus.shome to /home/splus/installation:
System.setProperty("splus.shome", "/home/splus/installation");
3. The default log file parameters can be reset with Java System properties. For example:
System.setProperty("splus.factory.rotate", "true"); System.setProperty("splus.factory.log", "/tmp/splusalog.txt");
4. An instance of the Java class SplusSessionFactoryFloor must be created:

SplusSessionFactoryFloor factory = new SplusSessionFactoryFloor(portNumber, localRMI, limit)
In the call to SplusSessionFactoryFloor, the arguments are:

int portNumber,
the port number of the RMI server.
boolean localRMI, which is true if the session factory and the RMI server run in same JVM. int limit,
the maximum number of S-PLUS Enterprise Server sessions to support.
5. This SplusSessionFactoryFloor object must be bound to the RMI server under the name SplusSessionServer.
214
Security Issues
SECURITY ISSUES
This implementation of S-PLUS Enterprise Server focuses on introducing useful client-server functionality to the S-PLUS product line on UNIX and Linux platforms. Reasonable consideration was given to security issues, but S-PLUS Enterprise Server is not intended to be a bullet-proof implementation. Within a trusted network, the current level of security should be adequate. As a rule of thumb, if you can use telnet safely within your network, then you can also use S-PLUS Enterprise Server safely. The S-PLUS session factory was designed so that it does not need to be run with root privileges. In addition, client logins as root are prohibited. Password entries are hidden from view, both at login time and in the log files. S-PLUS sessions are granted to users only if they provide valid logins and passwords; the privileges of the resulting sessions are governed by those available to the individual users. Session logs recorded in the server log file provide clues that illegal attempts were made to acquire sessions. Even with these security considerations, there are at least three weaknesses in this design that might caution against deploying this product in a network that is not trusted, such as the Internet. 1. RMI traffic is not encrypted. Because of this, any data transfer between clients and the server could be captured and read. Such data includes the clear-text transmission of login and password information for accessing the server, as well as the actual data that is being analyzed. Beyond this, it is possible that the RMI connection could be spoofed and a running session could be hijacked, effectively giving an intruder a shell connection to the server. 2. In creating sessions, the server must telnet to itself. Again, login and password information is transmitted in clear-text, so that it could be collected by anyone monitoring the telnet port. While spoofing and hijacking the telnet session is also conceivable, the short lifetime of the connection (~10s) makes this quite unlikely.
215
Chapter 14 Server Administration 3. Within the program itself, the login and password information is stored as a Java property in string form, which could be retrieved from a core file or other memory dump of the program. In a future release of S-PLUS Enterprise Server, these weaknesses will be removed by encrypting the RMI traffic, employing ssh in place of telnet, and encrypting the login and password information within the program. Until that time, we hope the information in this section assists you in evaluating the suitability of this product for deployment in a given environment.
216
MANAGING YOUR S-PLUS ENTERPRISE SERVER FOR UNIX LICENSES

Introduction
15
218 219 220 220 220 221 221
Starting and Stopping the License Server Valid License Commands and Arguments Obtain the Server Code Update Your License Key The Log File and Resources File System Administration
217
INTRODUCTION
The FLEXnet license manager is a software package that controls access to S-PLUS Enterprise Server. The S-PLUS Enterprise Server utility LICENSE gives you control over the license manager. The defaults specified for the license manager should be all you need to effectively run S-PLUS Enterprise Server; using the LICENSE utility is entirely optional. Primary licensing tasks are handled during the S-PLUS Enterprise Server installation procedure. The LICENSE utility allows you to perform routine management tasks, such as viewing summaries of licensed users or seeing how often S-PLUS Enterprise Server is accessed. For example, the following command displays a report of license activity:
Splus LICENSE users
In this call, users is an argument requesting a report of user activity.
218
Starting and Stopping the License Server
STARTING AND STOPPING THE LICENSE SERVER

Once you run the INSTALL script and install your license keys, you are ready to start the license server on the current host. The server start command to the LICENSE utility starts the license manager on the current system:
Splus LICENSE server start
This enables the license manager and allows you to use S-PLUS Enterprise Server. Note that this command is unnecessary if you followed Step 7: Modifying the Boot Sequence (page 48) as part of the installation process. Use the server stop command to the LICENSE utility to stop the license manager on the current system:
Splus LICENSE server stop
This command requires system administrator privileges. You can restart the license server using the server start command. To see the current status of each license server on the network, use the server status command as follows:
This command returns the name of each license server and its current status.
219
VALID LICENSE COMMANDS AND ARGUMENTS

The S-PLUS Enterprise Server license manager includes commands that install license keys, identify hosts, view license activity, list the status of all licenses on all outstanding servers, and much more. The sections below summarize valid license commands and the available command options.
Obtain the Server Code
You need the host id for your machine to request a license key from Insightful Corporation or your S-PLUS Enterprise Server distributor. You can obtain this code in two different ways: the HOSTINFO script and the hostinfo command to the LICENSE utility. When performing a full installation, use the HOSTINFO script in the top-level of your S-PLUS Enterprise Server home directory. When you simply need to upgrade your license on a current installation of S-PLUS Enterprise Server, use the hostinfo command. When you furnish a server code to Insightful Corporation or your distributor, a license key is generated for the system that runs the license manager. The hostinfo command can be run from any directory:
Splus LICENSE hostinfo
Go to the Insightful Fulfillment Center at http://keys.insightful.com to fulfill your license key. Your license authorization code (LAC) should have been e-mailed to you, which you will need in order to generate a license key.
Update Your License Key
Use the install command in the LICENSE utility to update your license key. This need arises whenever you do any of the following: Upgrade from a demo license to a normal license. Change the server on which S-PLUS Enterprise Server is installed.
220
Valid License Commands and Arguments You use install as follows:

Splus LICENSE install
Be sure to install your license key on the same machine where you acquired your server code.
The Log File and Resources File System Administration
If you need to know the name of the license server log file, use the logfile command as follows:
Splus LICENSE logfile
You can use the admin command to the LICENSE utility to perform some administrative tasks for the license manager. However, Insightful Corporation does not recommend this, as the important features used to manage the licensing software are documented in the preceding sections. The admin command mainly allows administrative control of license manager-embedded applications. To perform an administrative task, use a command similar to the following:
Splus LICENSE admin [command arguments]
By specifying command arguments, you can access the many options in the administration utility. For example, type the following to list the current users and outstanding licenses for all features on the network:
Splus LICENSE admin -l
Note that this command returns the same information as

Splus LICENSE users
221
222
SETTING MOTIF DEFAULTS
16
224 226 228
Introduction X11 Fonts Color Schemes for the motif Graphics Device
223
INTRODUCTION
When S-PLUS is run under the X Window System version 11, or X11, your graphics appear in a window that uses the Motif user interface. You can modify the behavior of the window by setting or modifying X11 resources. The S-PLUS motif graphics device gets its default values from the system defaults wherever possible; thus, familiarizing yourself with your systems defaults is helpful for setting S-PLUS defaults. This chapter shows you how to set defaults for all S-PLUS users at your site. Users who wish to set personal defaults should read the chapter Customizing Your S-Plus Session in the S-PLUS for UNIX Users Guide.
Note
S-PLUS Enterprise Server does not use a remote X-server display for S-PLUS clients. Instead, a separate Java application runs locally on the client and calls the server remotely to open an S-PLUS session. This provides enhanced performance for the user interface, because only essential commands and results are sent over the network. When using a remote X-server to display the user interface, however, the image of the entire interface is repeatedly sent over the network.
Certain S-PLUS functions, such as motif, require an X-server to open a display on the client. For information on configuring this display, see the section Login Profiles (page 246).
To set system defaults for each X11 client, the Motif interface uses the application defaults file SPlusMotif stored in the directory $SHOME/splus/lib/X11/app-defaults. You can modify this file to set defaults for each of the S-PLUS functions that depend on them. In the sections that follow, we describe how to do this for fonts and color schemes. To set appropriate defaults, you need to start S-PLUS under X11. To do this, start X11 on the X11 server and then bring up a window on the machine you use to run S-PLUS. If your machine is different from the X11 server, log in remotely to the machine on which you run S-PLUS and then enter
echo $DISPLAY
224
Introduction This determines how your DISPLAY environment variable is set. The system should respond with one of the following:
unix:0 localhost:0.0 :0.0 server_machine:0
where server_machine is the name of your X11 server. If the client machine that runs S-PLUS is different from the X11 server, the DISPLAY variable must be set to server_machine:0:
setenv DISPLAY server_machine:0
Next, use the xhost command from a window displayed on the X11 server to ensure that you have permission to create windows on your screen with X11 programs:
xhost client_machine
Here, client_machine is the machine you use to run S-PLUS. The system should respond with a message similar to:
client_machine added to access control list
225
X11 FONTS
Because there are many implementations of X11, it is difficult to pick a set of fonts that are available on every system. To check which fonts you have on your system, first start X11. If your system has the xlsfonts command, you can obtain a list of available fonts with the following command:
xlsfonts | more
Look for times-medium fonts, because S-PLUS attempts to use these by default. If you wish to change the default fonts for the S-PLUS X11-based graphics devices, select a family of fonts from the xlsfonts list and edit the appropriate sections of the SPlusMotif file on the machine that runs S-PLUS. You may need to use the UNIX command su to get permission to edit SPlusMotif. Look for the portion of the file that contains the font specifications:
sgraphMotif*fonts :\ *-times-medium-r-*-*-8-* \ *-times-medium-r-*-*-10-* \ *-times-medium-r-*-*-12-* \ *-times-medium-r-*-*-14-* \ *-times-medium-r-*-*-18-* \ *-times-medium-r-*-*-24-* \
In this section, substitute the family of fonts you want to use. For example, you might replace the lines above with the following if you want to use the vg family of fonts:
sgraphMotif*fonts : vg-13 vg-20 vg-25 vg-31 vg-40
If the names of the fonts you choose are too long to fit on one line, you can put them on multiple lines by placing a backslash (\) at the end of each line (with the exception of the last line). Be sure there are no spaces after the backslashes.
226
X11 Fonts
Note If you receive an error message similar to

Cant find font: *-times-medium-r-*-18-*
when you start an X11-based graphics device and you dont have the xlsfonts command on your system, you might want to use:
sgraphMotif*fonts : micro iso1.8 serif10 iso1.13 iso.16 iso.20
This sets the fonts to a family that is available on most systems.
227
COLOR SCHEMES FOR THE MOTIF GRAPHICS DEVICE

Colors for the S-PLUS motif graphics device are specified by color schemes. The default color schemes are listed, along with their definitions, in the file SPlusMotif. The motif graphics device supports an unlimited number of online color schemes, so that you can readily change colors without shutting down your motif window. It is even possible to define new color schemes from the graphics window, using the Color Schemes menu. In this section, we briefly describe both of these methods.
Note Use of the motif graphics device is not recommended with S-PLUS Enterprise Server. Instead, the java.graph graphics device is preferable because it displays within the S-PLUS client; the motif device requires a separate X-Windows display.
The section of the SPlusMotif file that contains color schemes looks similar to the following:
sgraphMotif*defaultColorScheme : 2 sgraphMotif*colorSchemes : \
name : "Black on White"; \ background: white; \ lines: black; \ text: black; \ polygons: black h5 white; \ images: white h16 black \n\ . . .
Each line that begins with name : in this section of the file indicates a new color scheme. A color scheme includes five additional lines that specify colors for the background, lines, text, polygons, and images in S-PLUS graphics. The color schemes are numbered according to the order in which they are listed in SPlusMotif. In our example, Black on White is color scheme 1, the next color scheme listed is color scheme 2, and so on.
228
Color Schemes for the motif Graphics Device To specify a default color scheme to use whenever the motif graphics device is started, do the following: 1. Change to the S-PLUS X11 application defaults directory:
cd `Splus SHOME`/splus/lib/X11/app-defaults
Note the back ticks surrounding the location Splus SHOME in this command. 2. Open the file SPlusMotif in a text editor. You may need root permissions to edit this file. 3. Search for the string defaultColorScheme and replace the number following the colon with the number corresponding to the color scheme you want. If there are any monochrome monitors connected to your network, set the defaultColorScheme resource to 1, for the black and white color scheme. If an individual user sets colors from the Color Schemes dialog in the motif window, the new color scheme overrides all other application defaults, including the color settings in the SPlusMotif files. For more details, see the chapter Working With Graphics Devices in the S-PLUS for UNIX Users Guide .
229
230
ENHANCING S-PLUS ENTERPRISE SERVER FOR UNIX

Introduction Adding Help Files for New Functions Customizing Start-Up
17
232 235 237
Organizing Local Functions with the library Function 233
231
Chapter 17 Enhancing S-PLUS Enterprise Server for UNIX
INTRODUCTION
The customizations described in this chapter will be effective system-wide, on all S-PLUS client sessions for S-PLUS Enterprise Server. If you want to enhance a personal S-PLUS environment instead, read the chapter Customizing Your S-Plus Session in the S-PLUS for UNIX Users Guide. As your users write functions that everyone in your organization might want to use, you should create a way for them to easily access these functions. With the instructions in this chapter, you can: Use the S-PLUS function library to add groups of commands to the S-PLUS sessions for all users at your site. Add help files for the new functions and link them to the S-PLUS help system. Use the S.init file so that certain S-PLUS commands are run every time someone starts a new client session.
Warning It is possible to place user functions in S-PLUS system directories such as main, splus, stat, and data, so that all users at your site have access to them. However, we strongly recommend against modifying any system directories, since the changes are not preserved when you update S-PLUS. Instead, create and modify the file S.init as described in this chapter. When S-PLUS users at your site distribute their own functions, they should create and maintain separate S-PLUS libraries. If you choose to make changes to system directories, be sure to keep a careful log of how you modify S-PLUS. With the log, you can restore your changes when you receive the next update of the software.
232
Organizing Local Functions with the library Function
ORGANIZING LOCAL FUNCTIONS WITH THE LIBRARY FUNCTION

The S-PLUS command library attaches a directory that contains S-PLUS functions and data sets. It offers a clean and modular way of organizing groups of S-PLUS functions so that everyone on your system can use them. The following instructions describe how to create a new S-PLUS library.
Note All library directories must be visible from the server (not necessarily the client). That is, the libraries must be visible from the machine on which S-PLUS Enterprise Server is installed
1. Create a directory to hold your functions and data sets by typing the following at the server hosts UNIX prompt:
mkdir local cd local
Here, local is the name you want your library to have. You can create this directory almost anywhere on your system. In earlier versions of S-PLUS, user-contributed libraries were allowed only in the directory $SHOME/library; at many sites, libraries are still located there exclusively. However, libraries under SHOME must be carefully protected or moved every time S-PLUS is upgraded. Creating them outside SHOME in a permanent location will save you time and potential loss of data in the future. As we state above, the only stipulation is that a library must be visible from the server. 2. Initialize the directory as a valid S-PLUS chapter by typing the following at the server:
Splus CHAPTER
233
Chapter 17 Enhancing S-PLUS Enterprise Server for UNIX 3. Start a client session of S-PLUS:
Splus SERVER -client
If the platform of your client machine is Windows, select Start Programs S-PLUS Server Windows Client Client Login to launch a new session. 4. Call library from the S-PLUS prompt to attach the directory to your search path:
> library("local", first=T, lib.loc="libloc")
Here, libloc is a path to the directory that contains the local library you created above. The lib.loc argument is not required if your library is located in $SHOME/library. Otherwise, lib.loc must be visible from the server. 5. Copy the S-PLUS functions you want into your library with a command similar to the following:
> assign("my.function", my.function, where=2)
where my.function is the name of a function. Any S-PLUS data set or function that you copy into your library will be available to all users who type
> library("local", lib.loc="libloc")
at the S-PLUS prompt in their sessions.

Hint The lib.loc argument to the S-PLUS function library can be either a character string, as in our example above, or a character vector containing several directory paths. You can assign the character vector to frame 0 with the name lib.loc; the library function searches any directories named there as well as the default $SHOME/library directory. In this case, you do not need to supply the lib.loc argument explicitly.
234
Adding Help Files for New Functions
ADDING HELP FILES FOR NEW FUNCTIONS

When an S-PLUS function is available system-wide, a help file should always accompany it. Without a help file, use of the function is likely be limited to those in close contact with the author of the function. The S-PLUS function prompt generates a help file outline for any existing function you specify. The outline includes the correct syntax for the function, as well as its current definition and headings under which you can supply the following information: What the function does. A brief description of the function. A description of each argument, with the option of specifying both required and optional arguments. A description of the value returned by the function. Side effects from the function, which are any effects besides the return of a value. Any references to the literature. Cross-references to other help files. Keywords that are used by the S-PLUS help system to assemble its Contents menus.
The steps below describe the process needed to create help files for your functions. 1. Start a client session of S-PLUS:
Splus SERVER -client
If the platform of your client machine is Windows, select Start Programs S-PLUS Server Windows Client Client Login to launch a new session.
235
Chapter 17 Enhancing S-PLUS Enterprise Server for UNIX 2. Type prompt(function_name) at the S-PLUS command line, where function_name is the name of the function for which you are creating the help file. The function must already exist or S-PLUS returns an error message. If prompt is successful, you should see a message similar to:
created file named function_name.sgml in the current directory; edit the file according to the directions in the file.
3. Edit the help file in your preferred text editor. For example, if you use the vi editor on UNIX or Linux, type the command:
> !/usr/openwin/bin/xterm -e vi funk.sgml
Be sure to include keywords, if appropriate. Predefined keywords are listed in the help file for prompt. 4. Quit S-PLUS:
> q()
5. Use the S-PLUS utility HINSTALL on the server to install the help file:
Splus HINSTALL datadir function_name.sgml
Here, datadir is the path to the .Data directory in the library that contains your function. The HINSTALL utility automatically translates the SGML code to HTML so that the S-PLUS help system can properly display it. 6. Run the S-PLUS utility BUILD_JHELP on the server to create the appropriate JavaHelp files for those files installed by HINSTALL:
Splus BUILD_JHELP name
where name is the name of the main help set file. This creates a directory named __Jhelp in the current chapters .Data directory. See Chapter 18, Configuring Help Services, for information on adding custom help files to the help services available for S-PLUS Enterprise Server clients.
236
Customizing Start-Up
CUSTOMIZING START-UP
The S-PLUS function .First allows individual users to customize their sessions each time they start S-PLUS. The system-wide version of .First is the file $SHOME/local/S.init, which is executed whenever anyone starts a client session of S-PLUS from a particular host. You can use this file to attach directories, set options, or print messages. For example, an S.init file might be defined as follows:
cat("Hello, Welcome to S-PLUS Server\n") cat("Attaching the splusfun directory\n") attach("/usr/local/splusfun", where = 2)
The following functions and files are run in order (if they exist) when S-PLUS launches. For additional details, see the chapter Customizing Your S-Plus Session in the S-PLUS for UNIX Users Guide and the common help file for .First and S.init. S-PLUS first runs the file $SHOME/S.init, which contains the standard S-PLUS Enterprise Server initialization instructions. Do not edit this file. Local administrators can create and edit the file $SHOME/local/S.init to specify particular actions that should be performed at the start of all S-PLUS client sessions. This is evaluated prior to .First, so an individual may override the actions in $SHOME/S.init and $SHOME/local/S.init. The .First.local function, which a system administrator can create in the system database $SHOME/library/splus, provides another mechanism for this, although it is not recommended. S-PLUS looks for the file $SHOME/S.chapters, which is a text file containing paths to library sections or S-PLUS chapters. These chapters are attached to all the search paths for all client sessions.
237
Chapter 17 Enhancing S-PLUS Enterprise Server for UNIX Next, S-PLUS looks for local copies of S.init and S.chapters in a users project directory. These files are analogous to the global files $SHOME/S.init and $SHOME/S.chapters, but are evaluated only for a single project. Finally, a users .First function is called when the client session of S-PLUS is started. The S_FIRST environment variable, if it is set, replaces the .First function, if any.
238
CONFIGURING HELP SERVICES

Introduction
18
240 241 241 241 243 245 245 246 248
Making Help Files Visible on the Web Server Independent Help Trees Symbolic Links Using the S-PLUS Help Viewer Customizing the Stand-Alone Help Services Host Specifying a Host Specifying a Help Services Directory Adding Custom Help Sets
239
Chapter 18 Configuring Help Services
INTRODUCTION
To give remote clients access to help files from an S-PLUS Enterprise Server installation, help files are distributed via a Web server. The host machine for the Web server may be different from the machine where S-PLUS Enterprise Server is installed, but this is not necessary. The setup and maintenance of the Web server is not covered in this manual. In the simplest case, the Web server runs on the same machine where the server software is installed. If the Web server is a Linux machine, an X server (or simulation) must be available, but if the Web server is on a Windows machine, no X server is necessary. Once the Web server is running, simply install the help files within the directory tree the Web server is using, and then your users can access to them. For example, consider an Apache Web server on a default Red Hat Enterprise Linux WS 3.0 installation. The root directory of this Web server is /var/www/html/, so the help files must be visible beneath this root directory. By default, S-PLUS clients expect the help files to be in a shome subdirectory under the Web servers root directory: http://servername/shome On our example Red Hat Enterprise Linux WS 3.0 installation, this is located in: /var/www/html/shome In this chapter, we describe various options for configuring the S-PLUS Enterprise Server help services.
240
Making Help Files Visible on the Web Server
MAKING HELP FILES VISIBLE ON THE WEB SERVER

Independent Help Trees
An alternative to the symbolic link method discussed above is to make actual copies of the help files under the Web servers root directory. This approach uses approximately 20 to 50 MB of disk space, depending on your installation. The S-PLUS Enterprise Server utility MKHELPTAR produces a tar file that contains all S-PLUS help files. The syntax of the utility is:
Splus MKHELPTAR [filename]
This produces the file filename in the current working directory; if you do not specify a file name, the utility creates SplusHelp.tar by default. To complete the deployment of the help files, create an shome directory on the Web server and extract all of the help files. The following commands accomplish this when typed from the Web servers root directory.
mkdir shome cd shome tar -xvf ../SplusHelp.tar rm ../SplusHelp.tar
These commands assume that the SplusHelp.tar file is located in the root directory of the Web server.
Note If modules are installed for S-PLUS Enterprise Server, or if custom libraries containing help files are added to the $SHOME/library or $SHOME/local directories, the procedure outlined above must be repeated. This ensures that all new help files are added to the collection of help files that are visible on the Web server.
Symbolic Links
The simplest way to make S-PLUS help files visible on your Web server is to create a symbolic link between the S-PLUS Enterprise Server home directory and shome on the Web server. The advantage of this approach is that no extra disk space is required to establish help services.
241
Chapter 18 Configuring Help Services Several problems exist with the symbolic link method that you should be aware of, though: Not all Web servers allow links under the servers root directory, as this may present security problems. The S-PLUS Enterprise Server installation must be on the same machine as the Web server, or a file-system export must be done from the S-PLUS host to the Web server host. This method makes all S-PLUS Enterprise Server installation files visible to HTTP browsers. If expanding on Windows (with Cygwin, for example) note that there are a few symbolic links in the help file structure which do not work on Windows. These don't affect the general working of the help files which are placed in the same location (wwwroot/shome).
However, if you are on a trusted network and have access to a machine that can run both the Web server and S-PLUS Enterprise Server, the symbolic link method may be the preferred way of making the help files available.
242
Using the S-PLUS Help Viewer
USING THE S-PLUS HELP VIEWER

Depending on the platform of your client machine, there are three basic ways to launch the S-PLUS Enterprise Server help viewer: To start the viewer from a UNIX or Linux client, type the command:
SplusClient HELPSTART -url webserver
where webserver is the name of the host that serves the S-PLUS help files. To start the help viewer from a Windows client, select Start Programs S-PLUS 7.0 Enterprise Server Windows Client S-PLUS Help Viewer. To start the help viewer on the server, use the command:
Splus HELPSTART -url webserver
When the viewer runs on the server itself, the -url flag may be omitted from this command, in which case help files are obtained directly from the S-PLUS Enterprise Server installation directory. Note that if the Web server is correctly installed, help can also be accessed from the Help menu on the GUI client. All three methods assume that the S-PLUS help files are located in an SHOME subdirectory under the root directory on the Web server. See the section Customizing the Stand-Alone Help Services Host (page 245) for details on specifying a different subdirectory. That section also shows how to specify a particular Web server in your login profile. You can use the -url flag to the HELPSTART utility, on both the server and a client, to specify a specific URL where the help files reside:
Splus HELPSTART -url http://newurl.com SplusClient HELPSTART -url http://newurl.com
Additional help sets can also be specified as part of the command:

Splus HELPSTART -url http://newurl.com help1 help2 SplusClient HELPSTART -url http://newurl.com help1 help2
243
Chapter 18 Configuring Help Services Note that the help sets must be specified with paths relative to the SHOME subdirectory of the Web server. For example, the following command loads a menu.hs help set that is located in the directory library/menu/.Data/__Jhelp on the Web server sprime:
Splus HELPSTART -url sprime library/menu/.Data/ __Jhelp/menu.hs
If you open the help viewer on the server without specifying the -url flag, the help set specified must be an absolute path. For example:
Splus HELPSTART /opt/pub/Splus/library/menu/.Data/ __Jhelp/menu.hs
Hint One way to examine which help sets are available is to change to the SHOME directory on the server and use the following find command:
cd $SHOME find . -name "*.hs" -print
244
Customizing the Stand-Alone Help Services Host
CUSTOMIZING THE STAND-ALONE HELP SERVICES HOST

Specifying a Host
If the host for serving S-PLUS help files is different from the S-PLUS Enterprise Server host, all clients must be configured to access it. In this scenario, the login profiles of the S-PLUS clients should be modified as follows: 1. Click the Edit button in the Client Login dialog box. 2. The Edit Session Profile dialog appears. Click on the Advanced button. 3. In the Help System URL field, type the new host name. Assuming a default installation on the Web server hostname, any of the URLs below should work. http://hostname/shome http://hostname hostname/shome hostname
4. Click OK. 5. Click Save.
Figure 18.1: When the S-PLUS help file server host is different from the S-PLUS Enterprise Server host, use the Advanced Session Profile Options dialog to set the customizations.
245
Chapter 18 Configuring Help Services For more details on login profiles, see the section Starting a Client (page 246). For help-viewer invocations from the UNIX or Linux prompt, you can use the -url flag to the HELPSTART utility to specify a Web server. For example, the following two commands launch S-PLUS Enterprise Server help services on the server and client, respectively. Both commands specify a new host named hostname for the Web server on which the S-PLUS help files reside.
Splus HELPSTART -url hostname SplusClient HELPSTART -url hostname
For custom Java applications that do not employ the Client Login dialog, you can set the Java System property splus.help.host to acquire an S-PLUS session using a particular Web server. For example:
System.setProperty("splus.help.host", "hostname");
Note that regular S-PLUS sessions (those invoked with the commands Splus, Splus -g, Splus -j, and Splus -e) will use the help files from the S-PLUS Enterprise Server installation. Thus, they do not require access to the Web server.
Specifying a Help Services Directory
As weve previously mentioned, the default location for help files is the shome subdirectory under the Web servers root directory. This may be insufficient for some installations. For example, one Web server may be used to provide help files for different work groups, each of which may have custom help files they do not wish to intermingle. Furthermore, if help files change with a future release of S-PLUS, circumstances may require that old help directories be published alongside of new help directories. If a different directory is required for the help files, the process of configuring help services is essentially the same as the one discussed in the section Making Help Files Visible on the Web Server (page 241). Simply replace shome in the commands of that section with the subdirectory name desired. Then, following steps analogous to those in the section above, configure all clients to use the custom URL that includes the new directory specification. For example, if you deploy help files in the subdirectory new_shome instead of shome, set the clients Help System URL to one of the following values:
246
Customizing the Stand-Alone Help Services Host http://hostname/new_shome hostname/new_shome The same syntax applies to help-viewer invocations from the UNIX or Linux prompt, and to custom Java applications. You can also set the Web server path and user working directory in the Target field of an S-PLUS command line:
C:\Inetpub\wwwroot\shome>"C:\Program Files\Insightful\ splus70server\client\java\jre\bin\javaw.exe" -Dsplus.client.mode=true -Dsplus.shome=C:\PROGRA~1\INSIGH~1\SPLUS7\client\ -Dsplus.help.host=ukrh9jjames com.insightful.splus.SplusHelpViewer
247
Chapter 18 Configuring Help Services
ADDING CUSTOM HELP SETS

If you develop and publish custom help files for your own S-PLUS functions, you may want to access them from the Web server. The easiest way to accomplish this is to create symbolic links from your help sets to the S-PLUS Enterprise Server installation tree; the library/local subdirectory is the recommended location. Once the symbolic links have been established, you can re-run the utility Splus MKHELPTAR if you need a stand-alone help tree. See the section Making Help Files Visible on the Web Server (page 241) for details.
248
INDEX
Symbols
.First function 237
A
Advanced Session Profile Options dialog 181, 183 Help System URL field 187 Help viewer off at startup box 187 RMI Port field 187 Telnet Prompt field 187 analytic 90 architecture 3 assign function 234
B
boot sequence modifiying 170 BUILD_JHELP utility 236
C
cat command 168, 178 cd command 168, 178, 190, 229, 233 CD-ROM errors in reading 172 chapters 177 default name 177 CHAPTER utility 177, 186, 233 CLASSPATH environment variable 214
client/server (CS) licensing 46, 55 client installation 171 accounts on the server for 176 communicating with the server 188 memory errors 182 SHOME directory 178 Solaris and Linux clients 178 starting a client session 184 steps required for 176 telnet issues 181 troubleshooting 181 Windows clients 180 working directories 177 Client Login dialog 184 Edit button 184, 245 Session Profile list 186 color schemes default 228, 229 Concurrent Session (SESS) 46, 53 Concurrent session (SESS) 46 concurrent session (SESS) 46, 47 Concurrent User (CU) 44 Configuration Options menu 191 Destinations and Name of Splus Script option 192, 193 exiting 191 Exit this Menu option 191 Graphics Hard Copy Printing option 194 Help File Printing 197 Installation of S-PLUS man page option 200 249
Index
License Management option 198 Location for Splus shell script option 192 Name of Splus shell script option 193 Setting Print Defaults option 194 CONFIGURE script 170, 179 Configuration Options menu 191 Destinations and Name of Splus Script option 192 Exit this Menu option 191 running after INSTALL 190 setting system defaults 190 specifying destination directories 173, 190, 192 specifying file names 190, 192 licensing 169 testing the installation 170 Enterprise Server script (Splus) 166 changing the destination of 170 changing the name of 170 environment variable CLASSPATH 214 environment variables DISPLAY 185, 224 JAVA_OPTIONS 183 S_FIRST 238 SHOME, see SHOME directory TERM 182 export command 183
F
file permissions 168, 172, 178 file systems read-only 173 FLEXnet Licensing End User Guide 6 fonts default 226 error messages 227
D
df command 168, 172, 178 dialogs Advanced Session Profile Options 181, 183, 187 Client Login 184 Edit Session Profile 184 Server Tools 203 disk space 168, 172, 178 DISPLAY environment variable 185, 224
H
help file installation 171, 241 troubleshooting 183 help files adding new ones for libraries 235 adding new ones to the help system 248 copying to Web server 241 creating JavaHelp files 236 installing new ones 236 launching the help viewer 243 producing a tar file of 241 prompt function 235 HELPSTART utility 183, 246 help system adding new help files 248
E
Edit Session Profile dialog 184 Advanced button 186 Help System URL field 245, 246 Profile Name field 185 Server Host field 185 User Name field 185 Work Directory field 185 X Server Display field 185 Enterprise Server
250
Index
launching the help viewer 243 printing 197 specifying a directory 246 specifying a host 245 starting a client session without 184 starting on Solaris/Linux clients 183 starting on Windows clients 183 help viewer 243 starting from client 243 starting from server 243 HINSTALL utility 236 home directory for Enterprise Server see SHOME directory HOSTINFO script 166, 169, 220 multiple services by a single host 214
L
laserjet printing 195 libraries 233 adding help files 235 specifying a non-default location 234 library function 233 lib.loc argument 234 license key 166 installing 220 obtaining the server code 220 requesting a new one 169 updating an old key 220 license manager 166, 220 auto-start command 199 defining options for 198 displaying a report of activity 218 installing manual pages for 198 log file for 198, 199 reports of activity 220 resources file for 198 running S-PLUS and Enterprise Server simultaneously 169 setting defaults for 190 starting 219 starting on a remote system 199 status of licenses 220 stopping 219 viewing the host 220 viewing the status 219 license number 6 License type client/server (CS) licensing 26 Concurrent Session (SESS) 26 concurrent session (SESS) 28 Concurrent User (CU) 26 Production Concurrent Session (PSESS) 27 Production Server (PS) 27 Single User (SU) 26 251
I
IFUL.opt 26, 46, 47, 48, 55 installation clients 171, 176 communicating with a client 188 help files 171 over an old SHOME 173 testing 170 troubleshooting 172 INSTALL script 170, 180, 191 errors from 172 installing options from CONFIGURE 192, 194
J
java.graph graphics device 228 JAVA_OPTIONS environment variable 183 Java options -Xmx 182 Java Remote Method Invocation (RMI) 188, 202 issues with the session factory 213
Index
Single-User (SU) 28 License types 26, 27 LICENSE utility see Splus LICENSE commands licensing floating 169 node-locked 169 troubleshooting 172 Linux clients installation procedure for 178 launching the help viewer 243 starting a client session 184 log file 198, 199 defining the maximum size for 199 for the session factory 204, 210 rotating 211 viewing the name of 221 login.bat script 181 login profiles see session profiles lp command 195 ls command 168, 179 SPlusMotif 224, 228, 229 mount command 172 MySwork directory 177, 186
P
permissions 173, 225, 226 file 168, 172, 178 read 173 root 167, 173, 190, 229 superuser 167 system administrator 219 write 173, 180 port number defining a new one 211 for Java RMI services 211 PostScript printing 195 print commands HP LaserJet 195 lp 195 printing from a client session 195 from the server 195 graphics 190, 194 help files 190, 197 laserjet 195 PostScript 195 setting the orientation 195 setting the print command 195 setting the print method 195 setting the resolution 196 Production Concurrent Session (PSESS) 47 Production Server (PS) 47 Production server (PS) 48 prompt function 235
M
man command 200 manual page for S-PLUS 190, 200 memory increasing on Solaris/Linux clients 182 increasing on Windows clients 182 mkdir command 233 MKHELPTAR utility 241, 248 more command 226 motif graphics device 224 as used in S-PLUS Server 228 color schemes for 228 Color Schemes menu 228, 229 defaults for 224 setting colors for 228 SPlusMotif 224, 228, 229 Motif user interface 224 252
R
read permissions 173 rehash command 180 resources file 198 root 167, 180, 190 root permissions 167, 173, 190, 229 rsh command 199
Index
S
S.chapters file 237 S.init file 232, 237 S_FIRST environment variable 238 security issues 215 server code obtaining from Splus LICENSE 220 Server Tools dialog 203 Display field 207 Help Host field 207 Kill button 208 Log File Name text box 211 Max Sessions text box 210 Port Number field 207, 211 Refresh button 207 Rotate Log Daily check box 211 Session Host field 207 Session ID field 207 session list 207 Start button 204 starting the session factory 204 User ID field 207 View button 204, 211 viewing the factory log file 204 Work Dir field 207 session factory 171, 202, 203 defining a log file name 211 identifying each session 207 issues with Java RMI 213 log file 210 maximum number of sessions 209, 210 port number 211 rotating the log file 211 Server Tools dialog 203 session list 208 starting 204 starting from the GUI 203 starting from the UNIX prompt 205 terminating 208 terminating RMI services 208 terminating sessions 208
viewing the help system host 207 viewing the host 207 viewing the log file 204 viewing the name of each user 207 viewing the port number 207 viewing the working directory 207 viewing the X-server display 207 session profiles 180 advanced options 186 Advanced Session Profile Options dialog 181, 183 Client Login dialog 184 Edit Session Profile dialog 184 setenv command 183 setup.exe file 180 SHOME directory 167 and libraries 233 disk requirements for 168, 178 installing over an old SHOME 173 on clients 178 Solaris clients installation procedure for 178 launching the help viewer 243 starting a client session 184 Splus.jar file 214 splus account 180 to own Enterprise Server files 167 SplusCient commands HELPSTART 246 SplusClient commands -helpoff 184 HELPSTART 243 SplusClient script see S-PLUS Server client script Splus Enterprise Server script (Splus) permissions for installing 173 Splus LICENSE commands 218 admin 221 253
Index
hostinfo 220 install 220 logfile 221 server start 199, 219 server status 219 server stop 219 users 221 S-PLUS manual page 190, 200 SPlusMotif 224, 228, 229 editing color schemes 228 editing fonts 226 Splus script S-PLUS Server administration GUI 203 and X-server displays 224 architecture 202 clean-up thread 212 keep-alive thread 213 Linux servers 182 security issues 215 starting a client session of 180 S-PLUS Server client script (SplusClient) 180, 183, 184 changing the destination of 179 changing the name of 179 Splus SERVER commands defining a port number 206, 211 -factory 171, 205, 213 -factoryoff 208, 209 -killsession 208 -limit option 206, 210 -list 208 -logfile option 206, 211 -rmioff 208, 209, 213 -rotate option 206, 211 -servertools 203 S-PLUS Server script (Splus) 190 changing the destination of 192 changing the name of 192 default location 192 installing over an old Splus script 193 Splus Server script (Splus) 173 su command 167, 173, 226 superuser permissions 167 254 supported platforms 3 symbolic links 241 system administrator permissions 219 system defaults 190 system requirements 6
T
tar command 168, 172, 178 tar file for installation 168 format of names 168, 179 telnet 181 description of S-PLUS Server telnet session 181 invisible transaction 182 TERM environment variable 182 top-level directory for Enterprise Server see SHOME directory troubleshooting client installation 181 errors from the INSTALL script 172 errors in reading the CD-ROM 172 help system failures 183 installation 172 licensing 172 memory errors 182 telnet issues 181
U
umask command 168, 173, 178 uncompress command 168, 178 UNIX commands cat 168, 178 cd 168, 178, 190, 229, 233 df 168, 172, 178 export 183 lp 195 ls 168, 179 man 200
Index
mkdir 233 more 226 mount 172 rehash 180 rsh 199 setenv 183 su 167, 173, 226 tar 168, 172, 178 umask 168, 173, 178 uncompress 168, 178 whoami 181 xhost 225 xlsfonts 226, 227 zcat 169, 179 installation procedure for 180 launching the help viewer 243 login.bat script 181 making error messages visible 181 setup.exe file 180 starting a client session 184 working directories 177 default name 177, 186 MySwork 186 write permissions 173, 180
X
X11 Window System 224 as used in S-PLUS Server 224 color schemes 228 defaults for 224 fonts 226 resources 224 SPlusMotif 224, 228, 229 xhost command 225 xlsfonts command 226, 227
W
Web server 240 copying help files to 241 default location of help files 240 for help files 171, 202 root directory of 240 specifying a directory 246 specifying a host 245 symbolic links to help files 241 troubleshooting 183 whoami command 181 Windows clients
Z
zcat command 169, 179
255
Index
256

Admin

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Admin

Загружено:

Авторское право:

Доступные форматы

S-PLUS 7 Installation and Administration Guide for Windows and UNIX

June 2005 Insightful Corporation Seattle, Washington

Copyright Notice Copyright 1988-2005, Insightful Corporation. All rights reserved.

Installing S-PLUS 7 for Windows

Installing S-PLUS 7 for UNIX/Linux

Basic Installation Linux-Specific Information

Chapter 4 License Management

Installing the License Manager on a Separate Machine 55

Contents PART II: S-PLUS ENTERPRISE SERVER FOR WINDOWS

Chapter 5 S-PLUS Enterprise Server for Windows Architecture

Chapter 7 Installing S-PLUS Enterprise Server and Client for Windows 79

Chapter 8 Administering S-PLUS Enterprise Server for Windows

Contents S-PLUS Enterprise Server Maintenance 117

Chapter 10 Troubleshooting Guide

Contents PART III: S-PLUS ENTERPRISE SERVER FOR UNIX

Chapter 11 S-PLUS Enterprise Server for UNIX Installation

Chapter 12 S-PLUS Enterprise Server for UNIX Client Installation

Chapter 13 Setting System Defaults

Contents Security Issues 215

Chapter 15 Managing Your S-PLUS Enterprise Server for UNIX Licenses

Chapter 16 Setting Motif Defaults

Chapter 17 Enhancing S-PLUS Enterprise Server for UNIX

Organizing Local Functions with the library Function 233

Configuring Help Services

Supported Platforms and System Requirements

SUPPORTED PLATFORMS AND SYSTEM REQUIREMENTS

S-PLUS Enterprise Server for Windows

In addition, you must have the following:

S-PLUS for UNIX/Linux

Supported Platforms and System Requirements

S-PLUS Enterprise Server for UNIX/Linux

SERIAL NUMBERS, LICENSE AUTHORIZATION CODES, AND LICENSE KEYS

Chapter 2 Installing S-PLUS 7 for Windows

Figure 2.1: The S-PLUS 7 installation splash screen.

Chapter 2 Installing S-PLUS 7 for Windows

Chapter 3 Installing S-PLUS 7 for UNIX/Linux

Step 1: Unpacking and Copying the Files from the Distribution CD

Step 2: Obtaining and Installing a License Key

hostid of license manager machine

Node-Locked Type Node-Locked hostid

hostid of S-PLUS machine

Step 3: Running the CONFIGURE Script

Step 4: Running the INSTALL Script

Chapter 3 Installing S-PLUS 7 for UNIX/Linux

Step 5: Running the License Manager

Start the license server daemon using the command

Step 6: Running S-PLUS

To run the S-PLUS Workbench:

Starting the License Manager Daemon at Boot Time

Chapter 4 License Management

S-PLUS Enterprise Server Licensing

Chapter 4 License Management

GENERATING A LICENSE KEY

Single-User (SU) Licensing (Windows)

Figure 4.2: The Insightful License Fulfillment - Confirm dialog.

Accessing the Insightful License Fulfillment Center

Figure 4.5: Enter your license authorization code when prompted.

Lets look at what each button does in more detail.

Figure 4.8: Confirming your selection for generating license keys.

Chapter 4 License Management

Concurrent User (CU) Licensing (Windows)

Chapter 4 License Management

Client/Server (CS) and Concurrent Session (SESS) Licensing (Windows/ UNIX)