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 create a secure "SSH tunnel" (connection) between your PC to Koti. Then you establish a SAS/Connect "session" between SAS on your PC and SAS on Koti so that all information that is exchanged between them will be sent through that tunnel. The information that is passed through the tunnel (in both directions) is encrypted before transmission and then unencrypted upon receipt.
The instructions below describe a one-time preliminary step that must be performed (editing the 'tcuunix.scr' SAS file), followed by instructions for setting up an SSH tunnel and then establishing a SAS/Connect session between your PC and Koti. Finally, a few practical examples are given of using SAS/Connect commands.
For complete information, please see the SAS/Connect documentation.
Before you can use SAS/Connect, you must edit and change two lines in the following tcpunix.scr SAS text file on your PC:
Here !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 (to launch Notepad, you can hold down the Windows key on your keyboard and type Notepad and then press Enter):
- 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, use the File / Save As menu to save this modified file under a different name (such as tcpunix-KOTI.scr) and/or in a different folder. When we refer to this file in our instructions below, for simplicity we will assume that you have named and saved it 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 is a one-time procedure.
In order to use SAS/Connect, you must first establish a secure "SSH tunnel" (connection) between your PC and Koti. Then you must issue a few special SAS commands on your PC to establish a SAS/Connect session with Koti.
To establish the secure SSH tunnel, proceed as follows (this procedure requires Windows 10):
Open a Command window on your PC. To do this, you can hold down the Windows key on your keyboard and press the letter r, then type cmd and then press Enter.
In the ensuing Command window, type or copy/paste the following command, and then press Enter:
ssh -L 8888:192.168.66.65:51234 firstname.lastname@example.org
being sure to replace jdoe with your Koti account name. Note that 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. The '192.168.66.65' is Koti's address.
If you now see the following:
The authenticity of host 'koti.vcu.edu (192.168.66.65)' can't be established. RSA key fingerprint is SHA256:hD/gsNnrWue/zzw0lSaSdHrKpAJQUQe/plsPICLb/SM. Are you sure you want to continue connecting (yes/no)?
type yes and press Enter.
When prompted, enter your Koti account password and press Enter.
You will then receive a Koti command prompt (not shown here).
Although you could now enter Unix commands here to perform on Koti, you do not need to do anything further in this Koti session. By simply logging in using the above command, you have established the secure SSH tunnel through which SAS/Connect can communicate to Koti (as explained below). But you MUST REMAIN LOGGED IN while you use SAS/Connect, so that the tunnel continues to exist.
Now launch SAS 9.3 or 9.4 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 in your SAS program editor window., modifying the first command appropriately, so that it contains the name and location of the tcpunix.scr file that you edited and saved in the previous section above (we are using 'c:\vcu\tcpunix-KOTI.scr' in this example).
filename rlink 'c:\vcu\tcpunix-KOTI.scr'; options comamid=tcp; %let koti=localhost 8888; signon koti;
Submit (run) these commands within SAS. These commands will initiate a SAS/Connect session 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 session 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, and you are ready to use SAS/Connect.
You may now issue any appropriate commands, as desired, while this connection is maintained. We give a few examples of such commands in the Examples of Using SAS/Connect section, just below. For complete details, please see SAS/Connect documentation.
When finished, you should terminate your SAS/Connect session by typing and submitting the following command in your SAS editor window:
You should then see the following line at the bottom of the SAS Log screen:
Finally, to terminate the SSH secure tunnel to Koti, simply log out of your Koti session that you had initiated in the Windows Command 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. Commands that are intended to be executed remotely by SAS on Koti are "sandwiched" between RSUBMIT and ENDRSUBMIT commands. You should select (highlight) and submit the entire RSUBMIT sandwich (that is, all of the SAS commands from RSUBMIT to ENDRSUBMIT, inclusive). Do NOT, for example, highlight and submit those commands 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 submit 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 in the previous section.
In this example, a PROC FREQ is run remotely on Koti to produce a frequency table for a SAS dataset that is stored on Koti.
RSUBMIT; LIBNAME abc "MyKotiFolder/ASubFolder"; PROC FREQ DATA=abc.MyKotiSASDataset;
TABLES educlevel region; RUN; ENDRSUBMIT;
- The LIBNAME command defines a remote libref named abc, which refers to the MyKotiFolder/ASubFolder directory located in your home directory on Koti.
- The PROC FREQ procedure is executed remotely on Koti (i.e., it is executed by SAS running on Koti). It produces a frequency table for the MyKotiSASDataset SAS dataset, which is located in the above directory on Koti.
- The information contained in that PROC FREQ table is sent from Koti to your PC, and the table is displayed on your PC.
In this example, a local libref (abc) is defined to refer to a folder stored on Koti. A PROC FREQ is then run locally on your PC to produce a frequency table for a SAS dataset in that folder.
LIBNAME abc "MyKotiFolder/ASubFolder" SERVER=koti;
PROC FREQ DATA=abc.MyKotiSASDataset; TABLES educlevel region;
- The LIBNAME command defines a local libref named abc, which refers to the MyKotiFolder/ASubFolder directory located in your home directory on Koti. The SERVER=koti option instructs SAS to look on Koti for this directory.
- The PROC FREQ produces a frequency table for the remote SAS dataset, located in the above directory on Koti. The PROC FREQ is executed locally by SAS running on your PC (because it is not sandwiched between RSUBMIT and ENDRSUBMIT commands). To accomplish this, SAS/Connect must transfer a copy of the data from the remote dataset on Koti to the SAS running on your local PC
- The resulting PROC FREQ table is displayed on your PC.
Example 1 and Example 2 both produce a PROC FREQ of the remote dataset. But there are differences:
- The table displayed by Example 2 is "prettier" because, being produced locally, it has table borders and background colors, etc., whereas the table displayed by Example 1 only contains the raw table data (the frequency counts, etc.).
- In Example 2, SAS/Connect must transfer a copy of the remote dataset to your local PC. If the file is large, that transfer could take a long time. In such situations, you would probably want to instead use the method shown in Example 1, because it creates the PROC FREQ table on Koti and then only transfers the table data (the frequency counts, etc.) to your 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 command opens the ODS RTF destination and defines the local file (on the PC) that will receive the RTF output from the PROC PRINT.
- The commands 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 command 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 command defines a libref, arbitrarily named local, which refers to the C:/MyPCFolder/ASubFolder directory located on your PC.
- The commands issued within the RSUBMIT/ENDRSUBMIT sandwich are run remotely on Koti:
- The second LIBNAME command defines a libref, arbitrarily named remote, which refers to the MyKotiFolder/SomeSubFolder directory located in your home directory on Koti.
- The PROC UPLOAD command 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 LIBNAME command, you can use the SAS Explorer window in your local PC SAS session to view, and even edit, the SAS datasets that are stored in that remote folder on Koti.
LIBNAME abc "MyKotiFolder/ASubFolder" SERVER=koti;
- This LIBNAME command defines a local libref, named abc, which refers to the MyKotiFolder/ASubFolder directory located in your home directory on Koti. The SERVER=koti option instructs SAS to look on Koti for this directory.
After executing this command, 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 screen) 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 (to enable editing, you must first click the Edit button in the toolbar). Or, you can right-click a dataset and choose Properties to display the dataset's properties (number of observations, variable names and attributes, etc.).
This article was updated: 10/1/2020