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 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 commands 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 Koti, and it provides a few examples of actual SAS/Connect commands you can use.
To establish such a connection, you can use SAS 9.3 or 9.4 on your PC. You must use the "traditional" SAS programming environment --- not SAS Studio, SAS OnDemand, SAS University Edition, or SAS Enterprise Guide. 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 between your PC and Koti. To obtain a secure connection, you must use a method known as SSH tunneling, as will be explained below. 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 between your PC and 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 must be performed to set up SSH tunneling, followed by instructions for establishing and terminating a connection between your PC and Koti. Then a few examples of using SAS/Connect commands.
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 two procedures are described below.
First, download a copy of the PuTTY program. To obtain a copy, go to its home website:
Follow the download links to the download page. In the "Alternative binary files" section of that page, download and save the "binary" file named:putty.exe
(Note that you DO NOT install the putty.exe file 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 set up 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.
This section describes how to establish a secure connection between SAS running on your PC and SAS running on Koti. It is assumed that you have performed the one-time preliminary steps, as described just above.
Double-click the putty.exe file that you downloaded in the initial 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 connection 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 (you must use "regular" SAS --- not SAS Studio, SAS OnDemand, SAS University Edition, or SAS Enterprise Guide). 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 command will initiate a SAS/Connect connection with Koti. You will be prompted to enter your Koti user id and password (not shown here).
After you correctly enter your user id and password, the SAS/Connect connection with Koti will be established, and you should see the following line at the bottom of your SAS log window:
A secure connection between your PC and Koti has now been established. You may now issue any appropriate commands, as desired, while this connection is maintained. For complete details, please see SAS/Connect documentation. We give a few examples of such commands in the Examples of SAS/Connect Commands section, just below.
When finished, you should terminate this connection 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 some examples of commands that could be issued with SAS/Connect to perform various tasks. In these discussions, 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 (that is, all of the SAS statements from RSUBMIT to the ENDRSUBMIT, inclusive). Do NOT, for example, highlight and execute those statements one at a time.
Some of the pathnames (e.g., x/y/z) used below 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 situations.
Remember that before you can issue these commands, you must initiate a connection between SAS/Connect on your Windows PC and Koti and receive the "Remote sign on to KOTI complete" message, as described above.
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 at 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 a copy of 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 from the PROC PRINT.
- 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.
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.
- Note that, because the local SAS files were created by SAS on the PC, they were created in the Windows SAS file format. But the uploaded SAS files that are stored on Koti are automatically converted ("migrated") to Koti's SAS file format (Linux X64).
In this example, as in Example 2, a local libref, named abc, is defined that represents a remote folder on Koti. After executing this statement, you can use the SAS Explorer window in your local PC SAS session to open, view, and even edit 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 at Koti for this directory.
- After executing this statement, in your local PC SAS session, you may now display your SAS Explorer window (click the Explorer tab in the lower-left corner of your SAS window) and double-click Libraries. One of the librefs listed will be abc. Double-clicking abc will display all the SAS datasets that are stored in the remote directory on Koti. You can now, for example, double-click one of those datasets to view or edit its contents. Or, you can right-click a dataset and choose Properties to view its properties (number of observations, variable names, and attributes, etc.).
This article was updated: 04/27/2020