README

JDMS Overview JDMS is a lightweight interface to the SAS System that meets the needs of users who relied on the ASCII driver in the SAS System, Version 6, for minimal GUI capabilities (such as a program editor with a recall function). JDMS is also an alternative to using the X Windows interface to SAS for users who use SAS from a dial-up connection and prefer a GUI interface. JDMS creates a GUI interface to a remote SAS session. The user is provided with the basic Display Management System (DMS) windows: Program Editor, Log, and Output. The JDMS applet connects to a SAS spawner, starts a remote SAS session, and then allows the user to submit code to that SAS session. Afterwards, the results of the submitted job(s) can be viewed in the Log and Output windows of the applet. Note: JDMS is not an attempt to create a fully functional DMS replacement. JDMS will not run AF applications or support complex graphical or display objects.

System Requirements JDMS requires the following: • A SAS server running SAS System software (Version 6.12 or higher) • Licenses for SAS/CONNECT® and SAS/IntrNet® software are required when using a version of the SAS System Software prior to version 8.2. If you are using version 8.2 or above of the SAS System Software, the license requirements for SAS/CONNECT® and SAS/IntrNet® software have been removed. • The Tunnel Feature (needed only if the web server and the SAS server are not installed on the same machine) is a part of the SAS/IntrNet software. Additional requirements for the Applet Version: • A current version of either Netscape® (version 4.08 or higher) or Microsoft® Internet Explorer (version 5.01 or higher). Note: If you are using Internet Explorer, you must use the Java Plug-in. If you do not have the Java Plug-in installed on your machine, your browser will automatically take you to the URL where it can be downloaded. • A copy of the JDMS applet files, which must be installed on the web server. • Apache Web server, Microsoft Internet Information server, or Netscape Enterprise server if you are using the Applet Version of JDMS. Additional requirements for the Application Version: • A Java Development Kit (version 1.3 or higher, also known as Java 2 Platform, Standard Edition). This can be downloaded from http://java.sun.com. • A copy of the JDMS Application files. Note: The SAS server must have either the SAS spawner program or a telnet daemon available. The spawner program is provided with Base SAS and with SAS/CONNECT® software. For more information on the SAS spawner program, please see your SAS System documentation.

1

See SAS/CONNECT® Driver for Java (http://www.sas.com/rnd/web/intrnet/ and click on SAS/CONNECT® Driver for Java under "Components") for more information on deploying applets.

Installing and Starting the Applet Version Note: While we believe that this Java code will run on any platform, we have not completed our testing on all platforms. Therefore, we currently only have installation instructions for the UNIX platforms. We will be adding additional instructions as we complete our testing. You can install this software on your own or check our Web site (go to http://www.sas.com/download and then click on JDMS) for a newer release containing updated instructions. There are three main steps to installing and starting the Applet version of JDMS: 1. 2. 3.

Test the SAS spawner on the Web Server. Set up the applet files on the Web server. Start JDMS.

Warning: Do not attempt to resize the JDMS applet window when using the Netscape browser. Resizing the window will stop the applet and the Netscape browser will then attempt to restart it. This will close your connection to the SAS server and the applet will not be able to restart. Note: To exit from the JDMS interface, you should always use the exit button from the JDMS interface. If you attempt to close your web browser before you exit the SAS session, you will leave orphan SAS sessions on the SAS server. Internet Explorer has a property that can control whether existing browser windows are reused for short cut requests. The property called 'Reuse windows for launching short cuts' is set in the Internet Options -> Advanced list. If this property is checked, any current instance of the applet can be reused. For instance, clicking on the URL link in an email message can cause the user to lose the current applet connection to the SAS session. The connection cannot be reestablished. The SAS session will become an orphaned process on the remote machine. If the property is not set (no check mark), then the applet is in no danger of accidentally losing the connection.

Step 1. Test the SAS spawner on the Web Server. Before JDMS can be utilized on the Web Server, you must have the SAS spawner configured and started. The SAS spawner (sastcpd) is located in the !SASROOT/utilities/bin directory. For example, with SAS 6.12, the spawner is located at /usr/local/sas612/utilities/bin/sastcpd . 1.

Verify that you have an entry for the spawner in your /etc/services file. For this example, we added the following entry in our /etc/services file: spawner

2323/tcp

# SAS job spawner

The number shown in the entry is the port number for the spawner. 2. Log in using the root ID. 3.

Change to the directory in the SAS installation where the sastcpd script is located. For example, if you have version 6.12 of SAS installed you will change to the /sas612/bin directory: cd /usr/local/sas612/utilities/bin

4.

Test the spawner: ./sastcpd –service spawner – shell&

5.

Verify that the spawner is running by trying to telnet to the spawner port from a UNIX prompt: telnet YourMachineName 2323

2

You should see prompts for a username and password. If the login is successful, the Hello> prompt will appear. Now you are ready to proceed to the configuration of the JDMS component. 6.

Stop the current spawner process by getting the process id and terminating the job: ps –ef | grep sastcpd kill –9

7.

Start the spawner in the background: ./sastcpd -service spawner -shell - nocleartext &

Note: When testing the spawner as indicated in Step 5, you should start the spawner without the –nocleartext option. When running the spawner in order to use JDMS, you should use the –nocleartext option so that the username and password are not passed over the network as clear text.

Step 2. Set up the applet files on the Web server. The JDMS tarball contains the following files: • • • • • • • • •

index.html app.html close.html JDMS.gif netutil.jar connect.jar privapp.jar JDMS.jar README.TXT

These files must be installed on the web server. index.html opens app.html in a plain browser window, which helps to prevent the user from leaving the applet web page without exiting the SAS session. JDMS.jar is an archive of the classes needed to run the applet and application. The *.jar format is recognized by Netscape browsers and also the IE browsers (when the Java plug-in is used). The archive files are signed with a Digital ID for SAS Institute Inc. that was purchased from a Certificate Authority named Verisign, Inc. Signing archive files informs users if Java applets are requesting special privileges, such as reading/writing to the hard disk or requesting printing privileges. 1.

Create a directory accessible from your web server. To simplify our usage, we will create a JDMS directory under the Web Server's DocumentRoot location. For our server, we will use the default location of /usr/local/apache/htdocs: cd /usr/local/apache/ htdocs mkdir JDMS

2.

Copy the tar file into this location. If you are viewing index.html in a browser, you can copy the tar file by selecting the "Download the JDMS tarball" link.

3.

Extract the contents of the tarball: tar xvf JDMS.tar

4.

Ensure that all users have read and execute access to these files: chmod 755 *

3

Step 3. Start JDMS. In a browser window, open the URL http://YourMachineName/Path_to_JDMS_folder/ For our example, the URL would be http://JDMS.unx.sas.com/JDMS/ JDMS will prompt you for startup information: • Host: Enter the hostname value for the machine where the SAS server is installed. • Port: Enter the port number that you have configured for the Spawner on the SAS server machine. In our example, this number is 2323. • Remote Login Prompt: Enter the login prompt you get when you telnet to the Spawner running on the SAS server machine (Username:). • Remote Password Prompt: Enter the password prompt you get when you telnet to the Spawner running on the SAS server machine (Password:). • Remote User Prompt Char: Enter the last character of the user's prompt when connecting to the Spawner on the SAS server machine (>). • SAS Command: Specify the command that is used on your system to invoke SAS. Some of the required options that you MUST include in the startup command are: -dmr -nosyntaxcheck -noterminal -cleanup • User ID: Enter your userid. • Password: Enter your password. • Enable TelnetConnection Debug Option: Select this option to echo the connection process to the Java console. Please refer to your browser's documentation for information about the Java console. This option works only for the TelnetConnection process. This option does not work if you are using the Tunneling Feature. The LOAD and SAVE AS pushbuttons can be used to save and restore the JDMS login parameters to the client machine. Password information is not saved to the file. Note: It may take several seconds for JDMS to complete the connection. After you have successfully connected, you should see a SAS initiation message in the Log window. Note: We do not recommend using an emulator, such as Exceed to display the JDMS applet or application. The GUI may not behave or appear as it should.

4

Installing and Starting the Application Version Note: While we believe that this Java code will run on any platform, we have not completed our testing on all platforms. Therefore, we currently only have installation instructions for the UNIX platforms. We will be adding additional instructions as we complete our testing. You can install this software on your own or check our Web site (go to http://www.sas.com/download and then click on JDMS) for a newer release containing updated instructions. There are three main steps to installing and starting the Application version of JDMS: 1. 2. 3.

Set up a JDK (Java Development Kit). Set up the application files on the machine where the JDK has been installed. Start JDMS.

Step 1. Set up a JDK. Before JDMS the Application version can be utilized, you must install a JDK on your machine. For information about installing a JDK on your machine please visit http://www.javasoft.com/products/. To verify that you have the JDK properly installed, type java -version at a command prompt. You should get a message that contains the version of the JDK that you are running.

Step 2. Set up the application files on the machine where the JDK has been installed. The JDMS tarball contains the following files: • • • • • • • • •

index.html app.html close.html JDMS.gif netutil.jar connect.jar privapp.jar JDMS.jar README.TXT

The files connect.jar, netutil.jar, privapp.jar, and JDMS.jar are used to run the application version of JDMS. The connect.jar, netutil.jar, and privapp.jar files are archives of the Jconnect classes needed to connect to the SAS session. These files will need to be copied into the jre/lib/ext directory of your JDK installation.

5

Step 3. Start JDMS. The following command will run JDMS the application version: java -jar JDMS.jar JDMS will prompt you for startup information: • Host: Enter the hostname value for the machine where the SAS server is installed. • Port: Enter the port number for the telnet port on the SAS server machine. In our example, this number is 23. • Remote Login Prompt: Enter the login prompt you get when you telnet to the SAS server machine (Login:). • Remote Password Prompt: Enter the password prompt you get when you telnet to the SAS server machine (Password:). • Remote User Prompt Char: Enter the last character of the user's prompt on the SAS server machine (>). • SAS Command: Specify the command that is used on your system to invoke SAS. Some of the required options that you MUST include in the startup command are: -dmr -nosyntaxcheck -noterminal -cleanup • User ID: Enter your userid. • Password: Enter your password. • Enable TelnetConnection Debug Option: Select this option to echo the connection process to the console. The LOAD and SAVE AS pushbuttons can be used to save and restore the JDMS login parameters to the client machine. Password information is not saved to the file. Note: It may take several seconds for JDMS to complete the connection. After you have successfully connected, you should see a SAS initiation message in the Log window. Note: When using an X Emulator and the native window manager on a PC, the GUI may not behave or appear as it should. If you are using a X Emulator and are experiencing problems, try running a window manager that is native to your remote machine, such as the Motif Window Manager (mwm) on your remote machine.

Copyright  2001 SAS Institute Inc. Cary, NC, USA. All rights reserved. SAS and all other SAS Institute product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. Other brand and product names are registered trademarks or trademarks of their respective companies.  indicates USA registration.

6 January 19, 2001