Submit a Help Request (804) 828-2227 | itsc@vcu.edu

How to use SAS/Connect with Koti

Overview
Preliminary Steps
    PuTTY Setup
    Editing the tcpunix.scr SAS File
Using SAS/Connect With Koti
Sample SAS/Connect Sessions

OVERVIEW

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. 

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 (TS1M4) on Koti.

Because Koti is intended to house sensitive data, you need 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

Preliminary steps include downloading and setting up the PuTTY program and editing the tcpunix.scr SAS file.  These procedures are described below.

  • PuTTY SETUP:

    Download a copy of the PuTTYprogram. To obtain a copy, go to its home website:
    follow the download links, and download and save the file named:
    putty.exe

    for Windows.  On the website, you will see putty.exe in two lists of files; get the putty.exe that is in the first list.
    (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. 

    In the screen that appears, as shown below, in the Host Name box type:

    koti.vcu.edu
    and in the Saved Sessions box type:

    Koti

     


    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

    8888
    and 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.
     
  • EDITING THE TCPUNIX.SCR SAS FILE:

    You need to edit and make two changes to 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.

    Although you could use any Windows text editor to edit this file, it will be convenient to use the SAS Enhanced Editor, because it can display line numbers to aid you in finding the two lines that need changing, as described below.

    Launch SAS, if you have not already done so.  Make sure the Editor window is active and select File / Open Program from the menus.  In the Open dialog box, display the "Files of type" drop-down list and select "All Files".  Navigate to the folder that contains the tcpunix.scr file noted above and open that file in the Editor window.

    Important:  You will NOT be running this file in SAS, but only using the SAS Editor window to edit and then save this file.

    Since it will be helpful to display line numbers in the editor, select Tools / Options / Enhanced Editor from the menus.  In the screen that appears, select the General tab and select (put a check mark beside) Show line numbers, as shown below:

    ‌Click OK.

    In the Enhanced Editor, make the following two changes to the file (the line numbers noted below are correct for SAS 9.3 and 9.4; if you have a different SAS version on your PC, the line numbers may be slightly different):

    • Navigate to line 144 and change it from this:

      waitfor '$'
      to this:

      *waitfor '$'
      (insert an asterisk in front of the line).
    • Change line 151 from this:

      type    'logout' LF;
      to this:

      *type    'logout' LF;
      (insert an asterisk in front of the line).

    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
    The updating of this file is complete.  Now exit SAS.
     
    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.

USING SAS/CONNECT WITH KOTI

Important:  In the steps below, you will be using SAS/Connect on your PC to login to your Koti account.  Therefore, before proceeding further, you must connect your PC to the VCU VPN ("virtual private network") using 2-factor authentication.  This is required for all Koti logins.  For more information, please read the VCU VPN Via 2-Factor Authentication PDF document.

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.

In the screen that appears, enter your Koti userid and then your password, as shown in the two screens below:





You will receive a 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.1 or above) on your PC, if you have not already done so, and enter the 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';
options comamid=tcp;
%let koti=localhost 8888;
signon koti;

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:

NOTE: Remote sign on to KOTI complete.

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 Remote Sessions section below.

When finished, you should terminate your SAS/Connect session by typing and submitting the following command in the SAS editor window:

signoff;

You should then see the following line at the bottom of the SAS Log screen:

NOTE: Remote signoff from KOTI complete.

Finally, to terminate the secure tunnel to Koti, simply log out of your Koti session that you had initiated in the PuTTY window.

SAMPLE SAS/CONNECT SESSIONS

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., a/b/c) 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.

Example 1:

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.

Example 2:

In this example, a remote 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 remote 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.

Example 3: 

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.

Example 4:

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.

Example 5:

This example, as in Example 2, defines a local libref 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.

RSUBMIT;
LIBNAME myremote "MyKotiFolder/ASubFolder";
ENDRSUBMIT;

LIBNAME mylocal SLIBREF=myremote SERVER=koti;
  • The first LIBNAME statement defines a remote libref named myremote, which refers to the MyKotiFolder/ASubFolder directory located in the user's home directory on Koti.
  • Although issued outside the RSUBMIT/ENDRSUBMIT sandwich, the second LIBNAME statement uses the SLIBREF= and SERVER= options to define a local libref named mylocal, which refers to the remote MyKotiFolder/ASubFolder directory located in the user's home directory on Koti.
  • In your PC SAS session, you may now display your SAS Explorer window and double-click Libraries.  One of the librefs listed will be mylocal.  Double-clicking mylocal 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/26/2017