A SAS® blog for the rest of us

In a previous article, I described how to use Windows PowerShell to connect to a remote SAS Workspace, run a SAS program, and retrieve the results. In that example, the only results I retrieved were the SAS log and SAS listing (text) output, if any.

When you run a SAS program on a remote session, sometimes the expected result is more substantial than just a text-based listing. What if your program creates Output Delivery System (ODS) files such as HTML or graphics? To retrieve those results, you need to download the files from the SAS session to your local machine, where your application can access them. Consider this program, implemented in a PowerShell script, which creates an image with PROC SGPLOT:

# change these to your own SAS-session-based
# file path and file name
# Note that $destImg can't be > 7 chars
$destPath = "/projects/results"
$destImg = "hist"

# program to run
# could be read from external file
$program =  
       "ods graphics / imagename='$destImg';
        ods listing gpath='$destPath' style=plateau;
        proc sgplot data=sashelp.cars;
        histogram msrp;
        density msrp;
        run;"

# run the program
$objSAS.LanguageService.Submit($program);

Downloading a file with FileService

The SAS Workspace provides the FileService API, which allows you to transfer file-based content between your local application and the SAS session. As with most file-based operations in SAS, the FileService relies on the use of a SAS fileref, or the name that SAS uses to reference your file within a program. For a file download operation, these are the basic steps:

• Obtain a SAS reference to the file (FileService AssignFileref method.
• Tell SAS to open the remote file for reading (OpenBinaryStream method).
• Read the contents of the file into a local array of bytes (Read method, repeating in 1K increments).
• Write the contents into a local file (PowerShell objects).
• When completed, close the local and remote file handles, and unassign the SAS file reference (Close method and DeassignFileref method).

Here's a PowerShell program snippet that implements these steps. (The complete example is available on GitHub.)

# local directory for downloaded file
$localPath = "c:\temp"

# now download the image file
$fileref = ""

# assign a Fileref so we can use FileService from IOM
$objFile = $objSAS.FileService.AssignFileref(
     "img", "DISK", "$destPath/$destImg.png", 
     "", [ref] $fileref);

$StreamOpenModeForReading = 1
$objStream = $objFile.OpenBinaryStream($StreamOpenModeForReading)

# define an array of bytes
[Byte[]] $bytes = 0x0

$endOfFile = $false
$byteCount = 0
$outStream = [System.IO.StreamWriter] "$localPath\$destImg.png"
do
{
  # read bytes from source file, 1K at a time
  $objStream.Read(1024, [ref]$bytes)
  
  # write bytes to destination file
  $outStream.Write($bytes)
  # if less than requested bytes, we're at EOF
  $endOfFile = $bytes.Length -lt 1024
  
  # add to byte count for tally
  $byteCount = $byteCount + $bytes.Length
  
} while (-not $endOfFile)

# close input and output files
$objStream.Close()
$outStream.Close()

# free the SAS fileref
$objSAS.FileService.DeassignFileref($objFile.FilerefName)

Write-Output "Downloaded $localPath\$destImg.png: SIZE = $byteCount bytes"

NOTE: PROCEDURE SGPLOT used (Total process time):
      real time           13.18 seconds
      cpu time            0.12 seconds
      
NOTE: Listing image output written to /projects/result/hist.png.
NOTE: There were 428 observations read from the data set SASHELP.CARS.

Downloaded c:\temp\hist.png: SIZE = 15092 bytes

Related links

• Complete code example on GitHub (SasWorkspaceDownloadFile.ps1)
• Running Windows PowerShell scripts
• Using Windows PowerShell to connect to a SAS Workspace server
• Copying files in SAS Enterprise Guide
• Create Your Own Client Apps using SAS Integration Technologies

This post is another in my series about creating apps with SAS Integration Technologies, a topic that I'm preparing for SAS Global Forum 2013.

In this article, I'll describe how to use Windows PowerShell to connect to a remote SAS Workspace, run a SAS program, and retrieve the results. This can be a useful method to implement a batch-style SAS job that you initiate from a client machine -- a common requirement in many SAS shops. The complete code example is on GitHub as SasWorkspaceExample.ps1.

Like my previous example with the SAS Metadata Server, this example begins with using SAS Object Manager. Use SAS Object Manager to create a ServerDef object that you use to connect to a SAS Workspace. This time we'll use the Workspace server port (by default, 8591) and the ClassIdentifier value for a SAS Workspace object. Remember, I used PROC IOMOPERATE to remind me which value that is, since I've never been any good at memorizing a 32-character hexadecimal value.

$objFactory = New-Object -ComObject SASObjectManager.ObjectFactoryMulti2
$objServerDef = New-Object -ComObject SASObjectManager.ServerDef 
$objServerDef.MachineDNSName = "server.mycompany.com" # SAS Workspace node
$objServerDef.Port           = 8591  # workspace server port
$objServerDef.Protocol       = 2     # 2 = IOM protocol
# Class Identifier for SAS Workspace
$objServerDef.ClassIdentifier = "440196d4-90f0-11d0-9f41-00a024bb830c"

Connecting to a SAS Workspace

With an instance of an ObjectFactory class and the ServerDef class, you can now establish a connection to the server:

# create and connect to the SAS session 
$objSAS = $objFactory.CreateObjectByServer(
                "SASApp",      # server name
                $true, 
                $objServerDef, # used server definition for Workspace
                "sasdemo",     # user ID
                "Password1"    # password
                )

When this statement completes successfully the $objSAS variable contains a connection to the SAS Workspace. With this connection, you can run SAS programs, read SAS data, and transfer files between the SAS Workspace and your application. (I'll cover how to transfer files in a future post.)

Running a SAS program with LanguageService

The SAS Workspace provides an API called LanguageService, which allows you to run SAS programs and retrieve the text-based results, including the SAS log and the SAS listing output. Here is a simple example using the $objSAS variable from the previous example:

$program = "ods listing; proc means data=sashelp.cars; run;"

# run the program
$objSAS.LanguageService.Submit($program);

# flush the log - could redirect to external file
Write-Output "LOG:"
$log = ""
do
{
  $log = $objSAS.LanguageService.FlushLog(1000)
  Write-Output $log
} while ($log.Length -gt 0)

The FlushLog method requires that you specify the number of bytes that you want to retrieve in a single call. In the above example, we used 1000. But what if your SAS log is greater than 1000 characters? That's the reason for the do..while loop. In this example, the PowerShell statements will continue to retrieve and emit the SAS log content until the FlushLog method no longer returns any content (that is, while the length of the $log variable is greater than 0).

You can retrieve the SAS listing output in a similar way by using the FlushList method:

# flush the output - could redirect to external file
Write-Output "Output:"
$list = ""
do
{
 $list = $objSAS.LanguageService.FlushList(1000)
 Write-Output $list
} while ($list.Length -gt 0)

This picture shows the Windows PowerShell ISE (scripting environment) with the script output:

Closing the SAS Session

It's important to manage the lifetime of the SAS session in a responsible way. If you create a SAS Workspace connection and use it within your application, you should call the Close method on the SAS.Workspace object when your work is complete. This is especially true if your application is designed to stay running for a long time, even when the SAS session is not in use.

To close the SAS Workspace session, use the Close() method:

# end the SAS session
$objSAS.Close()

Related links

• Complete code example on GitHub (SasWorkspaceExample.ps1)
• Running Windows PowerShell scripts
• Using Windows PowerShell to connect to a SAS Metadata Server
• Using Windows PowerShell to download a file from a SAS Workspace session