How to use SAS/Connect with Koti
SAS/Connect allows you to establish a "connection" between SAS running on your PC and SAS running on Koti. Once connected, you can issue commands to SAS on your PC to interact with SAS on Koti. These commands (a SAS/Connect "session") provide you the ability to manage, access, and process data in a distributed and parallel environment. For example, from SAS on your PC, you can issue a command to SAS on Koti to process a data file stored on Koti, and then send the results back to SAS on your PC for you to display locally.
This web page describes how to set up such a connection between SAS on your PC and on Koti, and it provides a few examples of SAS/Connect sessions.
To establish a SAS/Connect to Koti session, you can use SAS 9.3 or above on your PC. You will be connecting to SAS 9.4 (TS1M6) on Koti.
Because Koti is approved for and may house sensitive data, you are required to use a secure connection for your SAS/Connect to Koti sessions. To obtain a secure connection, you must use a method known as SSH tunneling. With SSH tunneling, first you use an SSH program to create a secure "tunnel" (connection) from your PC to Koti. Then you instruct SAS/Connect to send and receive all its information for Koti through that tunnel. The information passed through the tunnel (in both directions) is encrypted before transmission and then unencrypted upon receipt. The SSH program that we recommend using is a free program named PuTTY.
The instructions below include some one-time preliminary steps that need to be performed, followed by instructions for establishing and terminating a SAS/Connect to Koti session.
Please see the SAS/Connect documentation for complete information.
Preliminary steps include downloading and setting up the PuTTY program and editing the tcpunix.scr SAS file. These procedures are described below.
Download a copy of the PuTTY program. To obtain a copy, go to its home website:
follow the download links, and download and save the file named:putty.exe
(Note that you DO NOT install PuTTY on your PC, you just download it onto your PC. Also, do NOT try to run the file directly from the website, but download and save it on your PC.)
Double-click the putty.exe file that you downloaded. This launches the PuTTY program.
In the screen that appears, as shown below, in the Host Name box type:
koti.vcu.eduand in the Saved Sessions box type:
On the left side of this screen, click the '+' plus sign beside SSH to expand that entry, and then select (click) Tunnels, as shown below:
In that same screen, shown above, in the Source port box type
8888and in the Destination box type
koti.vcu.edu:51234(do NOT include any blank spaces). It is assumed here that port 8888 is unused on your PC (if you don't know what that means, then it probably is unused). Port 51234 has been setup on Koti for use with SAS/Connect.
In the above screen, click the Add button.
That screen should now appear as shown below:
On the left side of the screen, scroll up to the top of the list and select Session, then click the Save button. The screen should appear as shown below:
You have now completed the PuTTY setup. In the above screen, click the Cancel button to exit the PuTTY program.
You need to edit and change two lines in the following SAS text file:!SASROOT\connect\saslink\tcpunix.scr
where !SASROOT represents the folder where SAS is installed on your PC. If you don't know this folder's location on your PC, a quick way to find out is to launch SAS and submit the following SAS command:
libname a '!sasroot';
and then look in the SAS log for the location of this folder.
Open the above tcpunix.scr file in the Windows Notepad text editor program and perform the following steps:
- Navigate to line 144 by displaying the Notepad Edit menu, selecting Go To, and entering 144.
- Scroll up or down slightly, as needed, until you see the following set of lines:
waitfor '$' , '>' /*-- another common prompt character --*/ , '%' /*-- another common prompt character --*/ , '}' /*-- another common prompt character --*/ , 30 seconds ; type 'logout' LF; log 'NOTE: SAS/CONNECT conversation terminated.'; stop;
- Insert an asterisk in front of the two lines shown in bold text below:
* waitfor '$' , '>' /*-- another common prompt character --*/ , '%' /*-- another common prompt character --*/ , '}' /*-- another common prompt character --*/ , 30 seconds ; * type 'logout' LF; log 'NOTE: SAS/CONNECT conversation terminated.'; stop;
To preserve the original file, save this modified file, using the File / Save As menu, under a different name (such as tcpunix-KOTI.scr) and/or in a different folder. In the instructions we give later in this document, for simplicity we will assume that you have named and saved this file as follows:c:\vcu\tcpunix-KOTI.scr
Warning: If you instead use Microsoft Word or other word processor program to edit this file, be sure to save it as a "text" file.
This completes the editing of the tcpunix.scr file.
Double-click the putty.exe file that you downloaded in the preliminary steps above.
In the screen that appears, select Koti in the large white box, then click the Load button. The screen should look as follows:
In the above screen, click the Open button.
If you see the following screen, click Yes.
In the screen that appears, enter your Koti userid and then your password, as shown in the two screens below:
You will then receive a Koti command prompt (not shown here).
Although you could enter commands here to perform on Koti, you do not have to do anything further in this Koti session. By simply logging in, you have established the secure tunnel by which SAS/Connect can communicate to Koti (as explained below). But you MUST REMAIN LOGGED IN with PuTTY while you use SAS/Connect, so that the tunnel continues to exist.
To verify that the tunnel has been established, RIGHT-click on the blue title bar in the above window, then select Event Log. Scroll to the bottom of the resulting screen, and you should see something similar to the following:
One of the last lines states, "Local port 8888 forwarding to koti.vcu.edu:51234". If you do NOT see such a line, the tunnel has NOT been established, and your attempt to create a SAS/Connect session with Koti, as described below, will fail.
Close the above Event Log window (but remain logged into Koti via PuTTY).
Now launch SAS 9.3 or above on your PC (use "regular" SAS --- not SAS Studio, SAS OnDemand, or SAS University Edition). Enter the four SAS commands shown below. The first command contains the name and location of the modified tcpunix.scr file that you edited and saved in the preliminary steps above (we are using 'c:\vcu\tcpunix-KOTI.scr' in this example).
filename rlink 'c:\vcu\tcpunix-KOTI.scr';
%let koti=localhost 8888;
Submit (run) these commands within SAS. This will initiate a SAS/Connect session with Koti. You will be prompted to enter your Koti userid and password (not shown here).
After you correctly enter your userid and password, the SAS/Connect session will be established, and you should see the following line at the bottom of your SAS Log screen:
You may now issue any appropriate commands, as desired, for your SAS/Connect session. For complete details, please see SAS/Connect documentation. We give a few examples of such commands in the Sample SAS/Connect Sessions section below.
When finished, you should terminate your SAS/Connect session by typing and submitting the following command in the SAS editor window:
You should then see the following line at the bottom of the SAS Log screen:
Finally, to terminate the secure tunnel to Koti, simply log out of your Koti session that you had initiated in the PuTTY window.
Below are several examples of commands that might be issued during a SAS/Connect session. In each example, it is assumed that you have previously initiated a SAS/Connect session from your Windows PC to Koti, as described above, and received a "Remote sign on to KOTI complete" message.
In the discussion below, the term local refers to events or files on your PC, and the term remote refers to events or files on Koti.
All of the commands below are typed and submitted in the SAS program editor window on your PC. Statements that are intended to be executed remotely by SAS on Koti are "sandwiched" between RSUBMIT and ENDRSUBMIT statements. You should select (highlight) and execute the entire RSUBMIT sandwich (all of the SAS statements from RSUBMIT to the ENDRSUBMIT, inclusive). Do NOT, for example, execute those statements one at a time.
Some of the pathnames below (e.g., x/y/z) refer to files or directories on Koti, and some refer to those on your PC. Because Koti will only accept forward slashes ("/") in pathnames, and Windows will accept either forward ("/") or backward ("\") slashes, for simplicity we have only used forward slashes in all cases.
In this example, a PROC PRINT is run remotely on Koti to produce a print listing of a SAS dataset that is stored on Koti.
RSUBMIT; LIBNAME abc "MyKotiFolder/ASubFolder"; PROC PRINT DATA=abc.MyKotiSASDataset; RUN; ENDRSUBMIT;
- The LIBNAME statement defines a remote libref named abc, which refers to the MyKotiFolder/ASubFolder directory located in the user's home directory on Koti.
- The PROC PRINT procedure is executed remotely on Koti (i.e., it is executed by SAS running on Koti). It produces a print listing of the MyKotiSASDataset SAS dataset, which is located in the above directory on Koti. The print listing is displayed on your PC.
In this example, a local libref (abc) is defined to refer to a folder stored on Koti. A PROC PRINT is then run locally on the user's PC to produce a print listing of a SAS dataset in that folder.
LIBNAME abc "MyKotiFolder/ASubFolder" SERVER=koti;
PROC PRINT DATA=abc.MyKotiSASDataset; RUN;
- The LIBNAME statement defines a local libref named abc, which refers to the MyKotiFolder/ASubFolder directory located in the user's home directory on Koti. The SERVER=koti option instructs SAS to look on Koti for this directory.
- The PROC PRINT is executed locally by SAS running on the user's PC (because it is not sandwiched between RSUBMIT and ENDRSUBMIT commands). It produces a print listing of the remote SAS dataset, located in the above directory on Koti. To accomplish this, SAS/Connect transfers the data from the remote dataset to SAS running on the local PC.
This example demonstrates how to use the Output Delivery System to produce local RTF output (on the PC) from a PROC PRINT that is executed remotely on Koti.
ODS RTF BODY="C:/MyLocalFolder/MyFile.rtf"; RSUBMIT; LIBNAME abc "MyKotiFolder/ASubFolder"; PROC PRINT DATA=abc.MyKotiSASDataset; RUN; ENDRSUBMIT; ODS RTF CLOSE;
- The first ODS statement opens the ODS RTF destination and defines the local file (on the PC) that will receive the RTF output.
- The statements issued within the RSUBMIT/ENDRSUBMIT sandwich are run remotely on Koti and produce a print listing of the remote MyKotiSASDataset SAS dataset, which is located on Koti.
- The second ODS statement closes the RTF destination.
This example demonstrates how to upload (copy) SAS files from a folder on the local PC to a folder on Koti. The SAS files on the PC are in the Windows SAS file format. The uploaded SAS files that are stored on Koti are automatically converted ("migrated") to Koti's SAS file format (Linux X64).
LIBNAME local 'C:/MyPCFolder/ASubFolder'; RSUBMIT; LIBNAME remote "MyKotiFolder/SomeSubFolder"; PROC UPLOAD INLIB=local OUTLIB=remote MEMTYPE=(DATA CATALOG); RUN; ENDRSUBMIT;
- The first LIBNAME statement defines a libref, arbitrarily named local, which refers to the C:/MyPCFolder/ASubFolder directory located on the user's PC.
- The statements issued within the RSUBMIT/ENDRSUBMIT sandwich are run remotely on Koti:
- The second LIBNAME statement defines a libref, arbitrarily named remote, which refers to the MyKotiFolder/SomeSubFolder directory located in the user's home directory on Koti.
- The PROC UPLOAD statement copies all SAS dataset and catalog files from the directory referenced by the libref named local to the directory referenced by the libref named remote.
In this example, as in Example 2, a local libref, named abc, is defined that represents a remote folder on Koti. Afterward, you can use your SAS Explorer window in your PC SAS session to open and view the SAS datasets that are stored in that remote folder on Koti.
LIBNAME abc "MyKotiFolder/ASubFolder" SERVER=koti;
- This LIBNAME statement defines a local libref, named abc, which refers to the MyKotiFolder/ASubFolder directory located in the user's home directory on Koti. The SERVER=koti option instructs SAS to look on Koti for this directory.
- In your PC SAS session, you may now display your SAS Explorer window (click the Explorer tab in the lower left corner) and double-click Libraries. One of the librefs listed will be abc. Double-clicking abc will display all the SAS datasets in the remote directory. You may now, for example, double-click one of those datasets to view its contents.
This article was updated: 06/7/2019