LIBNAME Statement Syntax

associates a SAS libref with tables on a SAS LASR Analytic Server.

Valid in: Anywhere
Category: Data Access

Syntax

LIBNAME libref SASIOLA <LASR= "server-description-file">
<HOST= "grid-host"> <PORT= number>
<TAG= server-tag> <FORMATEXPORT= DATA | NONE | ALL>
<NODEFAULTFORMAT= YES | NO>
<STARTSERVER <=(non-distributed-server-options)>>
<SIGNER= "authorization-web-service-uri">
<FORCESIGNER=YES | NO>
<VERBOSE= YES | NO>;

Required Arguments

libref

is a valid SAS name that serves as a shortcut name to associate with the tables on the SAS LASR Analytic Server. The name must conform to the rules for SAS names. A libref cannot exceed eight characters.

SASIOLA

is the engine name for the SAS LASR Analytic Server engine.

Optional Arguments

FORCESIGNER= YES | NO

specifies whether to rely on the SAS LASR Authorization service or to create a signature file for data that is loaded into the server.

If you specify YES, then the server does not create a signature file for a table when the data is loaded into the server. This forces the server to rely on the SAS LASR Authorization service for data access decisions. This option enables sites that run the server as a service account and manage access controls in SAS metadata.
Default NO

FORMATEXPORT= DATA | NONE | ALL

specifies how the engine interacts with user-defined formats when tables are added to the server instance. The default value is FORMATEXPORT=DATA. This option can be overridden in a data set option. This option has no effect for input data sets (data sets that are transferred from the server instance to the SAS client).

DATA

specifies that the definition of all user-defined formats associated with variables written to the server instance are transferred to the server. You can then use those formats when you access the table (from a client such as SAS Visual Analytics). The user-defined formats are transferred to the server only once. The formats are not transferred as XML streams on subsequent requests to the server.

NONE

specifies that user-defined formats are not transferred to the server.

ALL

specifies that all formats in the format catalog search path are converted and transferred to the server with the table. This option is useful if the catalog search path contains user-defined formats that are not associated with variables in the table, but you might want to use later. Considerable resources can be required to generate the XML representation of the formats for deployments that have large catalogs or a deep search path.

HOST="grid-host"

specifies the grid host that has a running server instance. Enclose the host name in quotation marks. If you do not specify the HOST= option, it is determined from the GRIDHOST= environment variable.

Alias SERVER=
Interaction If the LASR= option is specified, then the host name specified in the HOST= option is ignored.

LASR="server-description-file"

specifies the server to use. Provide the fully qualified path to the server description file.

Interaction If you specify the server description file to use, then you do not need to specify the HOST= or PORT= options.

NODEFAULTFORMAT= YES | NO

specifies whether a default format that is applied to a variable is reported by the engine.

If you do not specify a format for a variable when you add a table to the server, the engine adds a default format. The server applies BEST. for numeric variables and $. for character variables.
The engine displays this "forced" format in procedures that list variable attributes, such as the CONTENTS and DATASETS procedures. If you specify NODEFAULTFORMAT=YES, then the display of the "forced" format is suppressed.
Note: This setting does not control whether formats are applied to a variable.

PORT=number

specifies the port number to use for connecting to the running server instance. If you use the PORT= option when you start a non-distributed server instance, then use this option to specify the network port number for the server.

Interaction The LASR procedure stores the port number of the last server instance that is started in the LASRPORT macro variable. You can specify PORT=&LASRPORT to use the macro variable.

SIGNER="authorization-web-service-uri"

specifies the URI for the SAS LASR Authorization web service. The web service is provided by the SAS Visual Analytics software. For more information, see SAS Visual Analytics: Administration Guide.

Example SIGNER="https://server.example.com/SASLASRAuthorization"

STARTSERVER= YES | NO

STARTSERVER <=(non-distributed-server-options)>

specifies to start a non-distributed server instance. Options are specified as name and value pairs. Separate each option with a space. The following options are available:

AFFINITY= YES | NO

requests that the concurrently executing threads of the server are associated with specific CPUs. When thread affinity is set to YES, a thread does not bounce between CPUs.

Default NO

CLF= YES | NO

specifies to use the common log format for log files. This format is a standardized text file format that is frequently analyzed by web analysis software. Specifying this option implies the LOGGING option.

KEEPLOG= YES | NO

specifies to keep the log files when the server exits instead of deleting them. By default, the log files are removed when the server exits. Specifying this option implies the LOGGING option.

LOGGING= YES | NO

specifies to enabling logging of server actions. The log file is stored with the signature files in the directory that is specified in the PATH= option. The log file is named in the pattern LASR.timestamp.0.saslasr.log.

MAXLOGSIZE=n

specifies the maximum log file size, in megabytes, for a log file. When the log file reaches the specified size, the log file is rolled over and renamed with a sequentially assigned index number (for example, .log.1). The default value is 100 megabytes. Specifying this option implies the LOGGING option.

Tip
Do not include an MB or M suffix when you specify the size.

MAXLOGROLL=n

specifies the maximum number of log files to create. When the maximum has been reached, the server begins to overwrite existing log files. The oldest log file is overwritten first. The default value is 10. Specifying this option implies the LOGGING option.

MERGELIMIT=n

specifies the limit for merging large result sets into smaller groups. The MERGEBINS= option specifies the size of the group. If MERGEBINS= is not specified, then n is the bin limit.

MERGEBINS=b

specifies the number of bins that numeric variables are binned into when MERGELIMIT=n is reached.

NOHOSTCHECK = YES | NO

specifies that the server does not check that the host name specified in the HOST= option is the local host. This option can be useful with unusual network configurations.

Interaction When the SIGNER= option is also specified, the host name that is specified in the HOST= option is sent to the SAS LASR Authorization Service.

NTHREADS=n

specifies the number of threads to use for the server. By default, n equals the number of CPU cores on the machine.

PATH="signature-file-path"

specifies the directory to use for storing the server and table signature files. The specified directory must already exist.

If you do not specify a value for PATH=, the signature files are stored in the default utility file directory of the SAS session.

PERM=mode

specifies the permission setting for accessing the server instance. The mode value is specified as an integer value such as 755. The mode corresponds to the mode values that are used for UNIX file access permissions.

For Windows servers, the UNIX mode setting is not applicable. Access is controlled according to permissions that you set manually on the signature files directory.
Alias PERMISSION=
Range 600 to 777
Alias START=

TAG=server-tag

specifies the tag to use for identifying the tables in the server instance. The value for server-tag cannot exceed 128 characters in length.

VERBOSE= YES | NO

specifies whether the engine accepts and reports extra messages from TKGrid. Specifying VERBOSE=YES can help diagnose problems with passwordless SSH setups, grid install locations, and so on.

The following message in the SAS log shows an example of a problem with passwordless SSH configuration.
ERROR: Failed to load the SAS LASR Analytic Server access extension 
       in the distributed computing environment.

Server refused our key from:
/home/sasdemo/.ssh/id_rsa
Timeout waiting for Grid connection.

Examples

Example 1: Submitting a LIBNAME Statement Using the Defaults

Program

The following example shows the code for starting a server with the LASR procedure and then connecting to the same server with a LIBNAME statement:
option set=GRIDHOST="grid001.example.com"; 1
option set GRIDINSTALLLOC="/opt/TKGrid";

proc lasr
    create port=10010
    path="/tmp" noclass;

    performance nodes=all;
run;

libname salessvr sasiola; 2
NOTE: No tag was specified in the LIBNAME statement. The default tag (WORK) is 
      used to name and identify tables in the LASR Analytic Server. You can 
      specify a tag as a data set option.
NOTE: Libref SALESSVR was successfully assigned as follows:
      Engine:        SASIOLA
      Physical Name: SAS LASR Analytic Server engine on host 
      'grid001.example.com', port 10010

Program Description

  1. The grid host is specified in the GRIDHOST environment variable.
  2. The default LIBNAME statement does not include the LASR=, HOST=, or PORT= options. The LIBNAME statement uses host name from the GRIDHOST environment variable and the LASRPORT macro variable and connect to server instance.

Example 2: Submitting a LIBNAME Statement Using the LASR= Option

The following example shows a LIBNAME statement that uses the LASR= option to specify the server instance to use:
proc lasr
    create="/tmp/hrsvr" 1
    path="/opt/VADP/var/hr"
    noclass;

    performance host="grid001.example.com" install="/opt/TKGrid" nodes=all; 2
run;

libname hrsvr sasiola lasr="/tmp/hrsvr"; 3

Program Description

  1. A server instance is started with the CREATE= option. The server description file is /tmp/hrsvr.
  2. The HOST= option is specified in the PERFORMANCE statement rather than specifying the GRIDHOST environment variable.
  3. The LASR= option specifies the server description file that was created when the server instance started.

Example 3: Submitting a LIBNAME Statement Using the HOST= and PORT= Options

The following example shows the code for starting a server with the LASR procedure and then submitting a LIBNAME statement to use the same server by specifying the HOST= and PORT= options.
proc lasr
    create port=10010
    path="/tmp"
    noclass;

    performance host="grid001.example.com" install="/opt/TKGrid" nodes=all;
run;
NOTE: The LASR procedure is executing in the distributed computing environment
      with 7 worker nodes.
NOTE: The server started on 'grid001.example.com' port 10010. 1
NOTE: The LASR Analytic Server port '12637' has been assigned to the macro 
      variable "LASRPORT".
libname hrdata sasiola host="grid001.example.com" port=10010 tag='hr'; 2
NOTE: Libref hrdata was successfully assigned as follows:
      Engine:        SASIOLA
      Physical Name: SAS LASR Analytic Server engine on host 
      'grid001.example.com', port 10010

Program Description

  1. When a server instance is started, the SAS log indicates the port number for the server instance.
  2. The PORT= option in the LIBNAME statement references the port number. The value for the PORT= option can also be specified as PORT=&LASRPORT to use the port number for the most recently started server instance.

Example 4: Accessing Tables Loaded with a DATA Step

The following example shows how to use the engine without a server tag in a DATA step.
libname sales sasiola port=10010;

data sales.prdsale;
    set sashelp.prdsale;
run;

proc datasets lib=sales;
quit;

* a server tag is not needed to access the data ;
proc print data=sales.prdsale(obs=5);
run;
When no server tag is specified, a default server tag that is named WORK is used.
DATASETS Procedure Output Showing the WORK Server Tag
DATASETS procedure output showing the WORK server tag.

Example 5: Accessing Tables Loaded with the LASR Procedure

When tables are loaded to memory on a server instance with the LASR procedure, the libref that is used with the procedure is set as the server tag. The following example shows how to add a table to a server instance and then access the table with a LIBNAME statement that includes a server tag.
proc lasr port=10010 add data=sashelp.prdsale noclass;
run;

libname lasr2 sasiola tag=sashelp;

proc datasets lib=lasr2;
run;

* a server tag is not needed to access the data              ;
* because a server tag is specified in the LIBNAME statement ;
proc print data=lasr2.prdsale(obs=5);
run;
By default, the libref is used as the server tag. The following display shows sashelp used as the server tag.
DATASETS Procedure Output Showing the SASHELP Server Tag
DATASETS procedure output showing the SASHELP server tag.

Example 6: Accessing Tables That Are Loaded from HDFS

When tables are loaded into memory on the server instance with the LASR procedure and the SASHDAT engine, the server tag is related to the HDFS directory name. The server tag is the same as the HDFS path to the SASHDAT file, but is delimited with periods (.) instead of slashes (/).
The following example shows how to add a table to a server instance from HDFS and then access the table with a LIBNAME statement that includes a server tag.
libname sales sashdat path="/dept/sales";

proc lasr port=10010 add data=sales.sales2012 noclass;
run;

libname lasr3 sasiola tag="dept.sales";

proc datasets lib=lasr3;
run;

* access the data with the "dept.sales" server tag;
proc print data=lasr3.sales2012(obs=5);
run;
DATASETS Procedure Output Showing the DEPT.SALES Server Tag
DATASETS procedure output showing the DEPT.SALES server tag.

Example 7: Loading a Table and Partitioning

Partitioning a table as it is loaded to memory can be a powerful feature for reducing processing times. For more information, see Data Partitioning and Ordering.
libname lasrlib sasiola host="grid001.example.com" port=10010 tag="sales";

data lasrlib.prdsale(partition=(country region) orderby=(descending year)); 1
    set sashelp.prdsale;
run;

Program Description

The Prdsale table is distributed to the machines in the cluster according to the PARTITION= data set option. The rows are distributed according to the unique combinations of the formatted values for the variables Country and Region. In addition, the ORDERBY= option is used to sort the rows in each partition by Year, in descending order.

Example 8: Creating an Empty Table

Creating an empty table can be useful to seed the column information for a table that you later append to. The following statements create an empty table with two numeric and two character variables:
libname lasrlib sasiola host="grid001.example.com" port=10010 tag="sales";

data lasrlib.empty;
   length c1 $15;
   length c2 $12;
   x=1;
   y=1;
   c1="";
   c2="";
   delete;
run;

Program Description

The Empty table is added to the server.