This topic is under construction for the 24.3 (March 2024) release of LabKey Server with embedded Tomcat 10. For the previous documentation, click here.
This topic explains how to configure LabKey Server to retrieve and display data from a SAS/SHARE data repository as an
external data source. This topic assumes you have
reviewed the general guidance here and provides specific parameters and details for this database type.
Overview
Publishing SAS datasets to your LabKey Server provides secure, dynamic access to datasets residing in a SAS repository. Published SAS data sets appear on LabKey Server as directly accessible datasets. They are dynamic, meaning that LabKey treats the SAS repository as a live database; any modifications to the underlying data set in SAS are immediately viewable on LabKey. The data sets are visible only to those who are authorized to see them.
Authorized users view published data sets using the familiar, easy-to-use grid user interface used throughout LabKey. They can customize their views with filters, sorts, and column lists. They can use the data sets in custom queries and reports. They can export the data in Excel, web query, or TSV formats. They can access the data sets from JavaScript, SAS, R, Python, and Java client libraries.
Several layers keep the data secure. SAS administrators expose selected SAS libraries to SAS/SHARE. LabKey administrators then selectively expose SAS libraries as schemas available within a specific folder. The folder is protected using standard LabKey security; only users who have been granted permission to that folder can view the published data sets.
Before SAS datasets can be published to LabKey, an administrator needs to do three things:
Set Up SAS/SHARE Server
The SAS/SHARE server runs as part of the SAS installation (it does not run on the LabKey server itself). SAS/SHARE allows LabKey to retrieve SAS data sets over an internal corporate network. The SAS/SHARE server must be configured and maintained as part of the SAS installation. The LabKey installation must be able to connect to SAS/SHARE; it requires high-speed network connectivity and authentication credentials. SAS/SHARE must be configured to predefine all data set libraries that the LabKey installation needs to access.
1. Add a line to the file named "services" (For Windows, check in c:\windows\system32\drivers\etc; for Linux and OSX, check in /etc/services) for SAS/SHARE; for example:
sasshare 5010/tcp #SAS/SHARE server
2. Run SAS
3. Execute a script that specifies one or more libnames and starts the SAS/SHARE server. For example:
libname airline 'C:\Program Files\SAS\SAS 9.1\reporter\demodata\airline';
proc server authenticate=optional id=sasshare; run;SAS/SHARE Driver
The SAS/SHARE JDBC driver allows LabKey to connect to SAS/SHARE and treat SAS data sets as if they were tables in a relational database. The SAS/SHARE JDBC driver must be installed on the LabKey installation. This requires copying two .jar files into the tomcat/lib directory on LabKey.
Copy the JDBC driver jars sas.core.jar and sas.intrnet.javatools.jar to your tomcat/lib directory.
Note: We recommend using the latest version of the SAS Driver 9.2 for JDBC; this driver works against both SAS 9.1 and 9.2. At this time, the most recent 9.2 version is called 9.22-m2; the driver lists a version number of 9.2.902200.2.0.20090722190000_v920m2. Earlier versions of the 9.2 driver are not recommended because they had major problems with column data types.
For more information on configuring the SAS JDBC Driver, see
Introduction to the SAS Drivers 9.2 for JDBC
Configure the SAS/SHARE Data Source
The new external data source must have a
unique JNDI name that you will use in naming the properties you will define. In the example on this page, we use "externalSasDataSource", which will appear to users defining external schemas as "externalSas". If you have more than one external data source, give each a unique name with the DataSource suffix ("firstExternalSasDataSource", "secondExternalSasDataSource", etc.). Learn more
here.
In the <LABKEY_HOME>/config/application.properties file, add a new section with the name of the datasource and the parameters you want to define. Provide your own server/port and other appropriate values:
context.resources.jdbc.externalSasDataSource.driverClassName=com.sas.net.sharenet.ShareNetDriver
context.resources.jdbc.externalSasDataSource.url=jdbc:sharenet://localhost:5010?appname=LabKey
context.resources.jdbc.externalSasDataSource.validationQuery=SELECT 1 FROM sashelp.table
There are additional properties you can set, as shown in the
template for the main "labkeyDataSource" in the application.properties file.
Note: This procedure will run SAS/SHARE in a completely open, unsecured manner. It is intended for development purposes only. Production installations should put appropriate authentication in place.
driverClassName
Use this as the
driverClassName:
com.sas.net.sharenet.ShareNetDriver
url
The
url property for SAS/SHARE takes this form:
jdbc:sharenet://localhost:5010?appname=LabKey
validationQuery
Use "SELECT 1 FROM sashelp.table" as the validation query for SAS/SHARE:
context.resources.jdbc.@@extraJdbcDataSource@@.validationQuery=SELECT 1 FROM sashelp.table
Define a New External Schema
To define a new schema from this data source see
Set Up an External Schema.
Choose your SAS data source, pick a library, and specify a schema name to use within this folder (this name can be different from the SAS library name).
The data sets in the library are now available as queries in this folder. You can browse them via the Schema Browser, configure them in a query web part, create custom queries using them, etc.
Usage
Once defined via the Schema Administration page, a SAS library can be treated like any other database schema (with a couple important exceptions listed below). The query schema browser lists all its data sets as "built-in" tables. A query web part can be added to the folder’s home page to display links to a library’s data sets. Links to key data sets can be added to wiki pages, posted on message boards, or published via email. Clicking any of these links displays the data set in the standard LabKey grid with filtering, sorting, exporting, paging, customizing views, etc. all enabled. Queries that operate on these datasets can be written. The data sets can be retrieved using client APIs (Java, JavaScript, R, and SAS).
Limitations
The two major limitations with SAS data sets are currently:
- Like all other external data sources, SAS data sets can be joined to each other but not joined to data in the LabKey database or other data sources.
- SAS/SHARE data sources provide read-only access to SAS data sets. You cannot insert, update, or delete data in SAS data sets from LabKey.
Related Topics
