Options for Other Functions

BYSORT=

Summary

Specifies whether to use implicit automatic SPD Server sorts on BY clauses.

Syntax

BYSORT=YES | NO
Arguments
YES
performs an implicit sort for a BY clause. This is the default.
NO
does not perform an implicit sort for a BY clause.

Description

Where Base SAS software requires an explicit sort statement (PROC SORT) to sort SAS data, by default, SPD Server performs a sort whenever it encounters a BY clause. If the value of the BYSORT= option is NO, the SPD Server software performs the same as the Base SAS engine.

Example 1

Specify to turn off implicit SPD Server sorts for the session.
LIBNAME mydatalib sasspds 'conversion_area'
   server=husky.5105
   user='siteusr1'
   prompt=yes
   bysort=no ;

data mydatalib.old_autos;
   input
     year $4.
     @6 manufacturer $12.
     model $10.
     body_style $5.
     engine_liters
     @39 transmission_type $1.
     @41 exterior_color $10.
     options $10.
     mileage condition ;
   datalines ;

1971 Buick       Skylark   conv  5.8  A  yellow    00000001 143000 2
1982 Ford        Fiesta    hatch 1.2  M  silver    00000001  70000 3
1975 Lancia      Beta      2door 1.8  M  dk blue   00000010  80000 4
1966 Oldsmobile  Toronado  2door 7.0  A  black     11000010 110000 3
1969 Ford        Mustang   sptrf 7.1  M  red       00000111 125000 3
;

PROC PRINT data=mydatalib.old_autos;
   by model;
run;
In this program, the PRINT procedure will return an error message because the table MYDATALIB.OLD_AUTOS is not sorted.

Example 2

Turn off implicit SPD Server sorts with the LIBNAME option, but specify a server sort for the table MYDATALIB.OLD_AUTOS using the BYSORT table option.
PROC PRINT data=mydatalib.old_autos
 (bysort=yes);
  by model;
run; 

DISCONNECT=

Summary

The DISCONNECT= option is used to control how user proxy resources are assigned for an SPD Server user. Each SPD Server user in a SAS session requires an SPD Server user proxy process to handles client requests.

Syntax

DISCONNECT=YES | NO 
Arguments
YES
closes network connections between the SAS client and SPD Server when all SPD Server librefs are cleared.
NO
closes network connections between the SAS client and SPD Server only when the SAS session ends. This is the default setting.

Description

The DISCONNECT= option is used to control how user proxy resources are created and terminated for an SPD Server user. Each SPD Server user in a SAS session requires an SPD Server user proxy process to handles client requests.
The DISCONNECT= state of the user proxy is determined by the first LIBNAME statement a user issues in the SAS session.
When the DISCONNECT= option is set to NO, the network connections between the SAS client and the SPD Server user proxy are closed when the SAS session ends. Closing the network connection ends all SPD Server user proxy processes for that session.
When the DISCONNECT= option is set to YES, the network connections between the SAS client and the SPD Server user proxy are closed after the user's last SPD Server libref in the SAS session is cleared. Closing the network connection ends all SPD Server user proxy processes, but not necessarily the SAS session. If the user issues a subsequent SPD Server libref in that SAS session, a new SPD Server user proxy process must be started up.
The advantage of using DISCONNECT=NO is that the processor overhead that is required to create an SPD Server user proxy is only required when an SPD Server user issues his first LIBNAME of his session. The disadvantage of using DISCONNECT=NO is that the SPD Server user proxy does not terminate until the user's SAS session ends. For example, if a user does not log out at the end of the day and leaves an SPD Server session running overnight, the user proxy remains in force, occupying system resources that might be utilized by other jobs.
The advantage of using DISCONNECT=YES is that user resources are freed as soon as the user's last LIBNAME of the session is cleared. The disadvantage of using DISCONNECT=YES is if the user needs to issue a subsequent LIBNAME in that session, the LIBNAME assignment will require a new SPD Server user proxy to be launched.
The DISCONNECT=YES LIBNAME option must be used with the LIBNAME CLEAR statement to be effective.
The default setting for the DISCONNECT= option is NO.

Example 1

Use the default setting of DISCONNECT=NO to retain the user proxy process. Libref SPUD is assigned using user proxy process 8292, and then libref SPUD is cleared. Then libref CAKE is assigned, still using user proxy process 8292. The user proxy process is not terminated when libref SPUD is cleared, and no new user proxy process is required to assign libref CAKE.
LIBNAME spud sasspds 'potatoes' 
   server=husky.6100 
   user='bob' 
   passwd='bob123';

NOTE: Libref SPUD was successfully assigned as follows: 
      Engine:        SASSPDS 
      Physical Name: :8292/spds/test/potatoes/

LIBNAME spud clear;

LIBNAME cake sasspds 'carrots' 
   server=husky.6100 
   user='bob' 
   passwd='bob123';

NOTE: Libref CAKE was successfully assigned as follows: 
      Engine:        SASSPDS 
      Physical Name: :8292/spds/test/carrots/

Example 2

Use the DISCONNECT=YES setting to terminate the user proxy process when the last user LIBNAME is cleared. Libref SPUD is user Bob's last open LIBNAME. SPUD is assigned using user proxy process 8234, and then cleared. Next, libref CAKE is assigned using user proxy process 8240. When libref SPUD is cleared, user proxy process 8234 is terminated, and the resources that were allocated to proxy process 8324 are freed. When Bob submits a subsequent libref statement for CAKE, a new user proxy process 8240 is created.
LIBNAME spud sasspds 'potatoes' 
   server=husky.6100 
   user='bob' 
   passwd='bob123'
DISCONNECT=YES;

NOTE: Libref SPUD was successfully assigned as follows: 
      Engine:        SASSPDS 
      Physical Name: :8234/spds/test/potatoes/

LIBNAME spud clear;

LIBNAME cake sasspds 'carrots' 
   server=husky.6100 
   user='bob' 
   passwd='bob123'
DISCONNECT=YES;

NOTE: Libref CAKE was successfully assigned as follows: 
      Engine:        SASSPDS 
      Physical Name: :8240/spds/test/carrots/
Now Bob has libref CAKE assigned using user proxy process 8240. Suppose Bob makes another libref FRUIT without first clearing the CAKE libref. The libref FRUIT will re-use the active proxy process 8240. In this case, both the CAKE and FRUIT librefs must be cleared before the user proxy process can terminate.
LIBNAME fruit sasspds 'apples' 
   server=husky.6100 
   user='bob' 
   passwd='bob123'
DISCONNECT=YES;

NOTE: Libref FRUIT was successfully assigned as follows: 
      Engine:        SASSPDS 
      Physical Name: :8240/spds/test/apples/

ENDOBS=

Summary

Specifies the end row (observation) number in a user-defined range for processing.

Syntax

ENDOBS=n 
Arguments
n
is the number of the end row.

Description

By default SPD Server processes the entire table unless the user specifies a range of rows with the STARTOBS= and ENDOBS= options. If the STARTOBS= option is used without the ENDOBS= option, the implied value of ENDOBS= is the end of the table. When both options are used together, the value of ENDOBS= must be greater than STARTOBS=.
In contrast to the Base SAS software options FIRSTOBS= and OBS=, the STARTOBS= and ENDOBS= SPD Server options can be used for WHERE clause processing in addition to table input operations.

Example 1

Specify for SPD Server to process only row numbers (observations) 200 - 500 while the LIBNAME is active.
LIBNAME mydatalib sasspds 'conversion_area'
   server=husky.5105
   user='siteusr1'
   prompt=yes
   startobs=200
   endobs=500;

LIBGEN=

Summary

The LIBGEN=YES option is used in explicit SQL connection statements. When you set LIBGEN= yes, SPD Server is configured to generate additional domain connections that enable you to perform SQL joins across different SPD Server domains.

Syntax

LIBGEN=YES 

Description

You should specify the LIBGEN=YES option in the explicit SQL LIBNAME connection. You cannot specify the LIBGEN=YES option setting without first creating a LIBNAME connections to the domain.

Examples

The two code examples that follow both perform the same task. Both examples use explicit SQL to join two tables from different domains. The first example uses execute connection statements to facilitate joining the tables from separate domains. The second example uses the LIBGEN=YES option to perform the same join without having to issue the extra execute connection statements.

SQL without LIBGEN=YES

/* The example code without LIBGEN=YES */
/* must issue execute connection       */
/* statements to access tables that    */
/* reside in two different domains.    */

LIBNAME path1 sasspds 'path1'
  server=boxer.5140
  ip=YES
  user='anonymous' ;

LIBNAME path2 sasspds 'path2'
  server=boxer.5140
  ip=YES
  user='anonymous' ;

DATA path1.table1
  (keep=i table1)
path2.table2
  (keep=i table2) ;

table1 = 'table1' ;
table2 = 'table2' ;

do i = 1 to 10 ;
  output ;
  end ;
run ;

PROC SQL ;
CONNECT to sasspds (
  dbq='Path1'
  server=boxer.5140
  user='anonymous') ;

/* Without LIBGEN=YES, you must make  */
/* two execute connect statements.    */

execute (LIBREF path1 engopt="dbq='path1'")
  by sasspds;
execute (LIBREF path2 engopt="dbq='path2'")
  by sasspds;

execute
  (create table table4 as
   select *
   from
     path1.table1 a,
     path2.table2 b
   where a.i = b.i)
 by sasspds ;

disconnect from sasspds ;

quit ;

SQL with LIBGEN=YES

/* The example code that uses LIBGEN=YES   */
/* can join the tables from two different  */
/* domains in a more simple manner.        */

LIBNAME path1 sasspds 'path1'
  server=boxer.5140
  LIBGEN=YES
  ip=YES
  user='anonymous' ;

LIBNAME path2 sasspds 'path2'
  server=boxer.5140
  LIBGEN=YES
  ip=YES
  user='anonymous' ;

DATA path1.table1
  (keep=i table1)
path2.table2
  (keep=i table2) ;

table1 = 'table1' ;
table2 = 'table2' ;

do i = 1 to 10 ;
  output ;
  end ;
run ;

PROC SQL ;
CONNECT to sasspds (
  dbq='Path1'
  server=boxer.5140
  user='anonymous') ;

/* Syntax used with LIBGEN=YES option */

execute
 (create table table4 as
  select *
  from
   path1.table1 a,
   path2.table2 b
  where a.i = b.i)
by sasspds ;

disconnect from sasspds ;

quit ;

LOCKING=

Overview of Record-Level Locking

Record-level locking is an SPD Server feature that allows multiple users concurrent Read and Write access to SPD Server tables while maintaining the integrity of the table contents. When record-level locking is enabled, users can insert, append, delete, and update the contents of an SPD Server table while performing concurrent reads on the table. When a client enables record-level locking, the client connects to the single SPD Server record-level locking proxy process. When record-level locking is not enabled, clients connect to separate SPD Server user proxy processes for each LIBNAME connection to a domain.

Record-Level Locking Details

Record-level locking is enabled when an SPD Server client specifies the LOCKING=YES LIBNAME option to the client's LIBNAME connection statement. All subsequent operations on the given LIBNAME domain will use record-level locking. The primary use of record-level locking is to allow multiple clients or parallel operations from the same client to have both Read and Write access to the same SPD Server table resource. If record-level locking is not enabled, then any Write operation (update, append, insert, or delete) on an SPD Server table requires exclusive access to the resource, or a member lock failure error occurs. Operations that affect metadata, such as creating or deleting indexes, renaming variables, and renaming tables require exclusive access to the resource, whether record-level locking is enabled or not. These types of operations will report a member lock failure error when record-level locking is enabled, but exclusive access is not available.
Record-level locking must be enabled in SPD Server before a SAS client can use the CNTLEV=REC table option in their SAS program to access SPD Server tables. Record-level locking enforces SAS style record-level integrity across multiple clients so clients are guaranteed that an observation will not change during a multiphased Read or Write operation on the specified observation. Record-level locking will allow multiple concurrent update access to a single SPD Server table, but it will deny concurrent access to the specified observation within the table.
When an SPD Server client establishes a LIBNAME connection to a domain with record-level locking enabled, it connects using the single record-level locking proxy process. There is only one record-level locking proxy process per SPD Server. All SPD Server clients that use record-level locking connections are processed through the record-level locking proxy process. If there are a large number of record-level locking connections, there might be some contention for process resources between the clients. The record-level locking proxy process is a single point of failure for all these connections, so care should be taken when you use record-level locking to update critical data.
When you append or insert new rows into a table with defined indexes, the table updates are processed more sequentially through the record-level locking proxy process than they would be through the SPD Server user proxy processes. The performance of record-level locking will probably be less than the performance that can be obtained without record-level locking enabled for these types of operations. The standard member-level locking that is used in SPD Server user proxy processes allows for more parallel processing when doing table append or insert operations.
Record-level locking is not supported for operations on tables that use dynamic clusters.

Syntax

LOCKING=YES|NO
Default: NO
Arguments
YES
enables record sharing mode.
NO
disables record sharing mode.

Example

     LIBNAME testrl sasspds 'tmp'
           server=serverNode.port
           user='anonymous'
           locking=YES ;

STARTOBS=

Summary

Specifies the start row (observation) number in a user-defined range for processing.

Syntax

STARTOBS=n
Arguments
n
is the number of the start row.

Description

By default SPD Server processes the entire table unless the user specifies a range of rows with the options STARTOBS= and ENDOBS=. If the ENDOBS= option is used without the STARTOBS= option, the implied value of STARTOBS= is 1. When both options are used together, the value of STARTOBS= must be less than the value of ENDOBS.=
In contrast to the Base SAS software options FIRSTOBS= and OBS=, the STARTOBS= and ENDOBS= SPD Server options can be used for WHERE clause processing in addition to table input operations.

Example

Specify for SPD Server to process only row numbers (observations) 200–500 while the LIBNAME is active.
LIBNAME mydatalib sasspds 'conversion_area'
   server=husky.5105
   user='siteusr1'
   prompt=yes
   startobs=200
   endobs=500;

TEMP=

Summary

Controls the creation of a temporary LIBNAME domain for this LIBNAME assignment.

Syntax

TEMP=YES|NO 
Default: NO
Arguments
YES
creates a temporary LIBNAME domain for the LIBNAME assignment.
NO
does not create a temporary LIBNAME domain.

Description

Use this option to create temporary LIBNAME domains that exist for the duration of the LIBNAME assignment. The TEMP (temporary) domains are analogous to SAS WORK libraries.
To create a temporary LIBNAME domain, use TEMP=YES. Any data objects, tables, catalogs, or utility files that are created in the TEMP=YES temporary domain are automatically deleted when you end the SAS session. This functions similarly to a SAS WORK library. (Note: The temporary domain is created as a subdirectory of the directory specified as the library domain.)

Example 1

Create a LIBNAME domain to use for temporary storage during your SAS session.
LIBNAME mydatalib sasspds 'conversion_area'
   server=kaboom.5191
   user='siteusr1'
   prompt=yes
   temp=yes ;

TRUNCWARN=

Summary

Suppresses hard failure on NLS transcoding overflow and character mapping errors.

Syntax

TRUNCWARN=YES|NO 
Default: NO

Description

When using the TRUNCWARN=YES LIBNAME option, data integrity might be compromised because significant characters can be lost in this configuration. The default setting is NO, which causes hard Read and Write stops when transcode overflow or mapping errors are encountered. When TRUNCWARN=YES, and an overflow or character mapping error occurs, a warning is posted to the SAS log at data set close time if overflow occurs, but the data overflow is lost.

WORKPATH=

Summary

I/O contention can occur when many SPD Server users or SPD Server jobs perform heavy processing that uses the same workpath. The WORKPATH= option permits users to specify an alternate workpath that utility files (such as index builds and sorting files) can use. Specifying an alternate workpath can relieve I/O contention issues when other users are running heavy processing jobs at the same time.
A properly configured workpath directs I/O from utility operations to a separate disk. Mapping the utility file work to a separate disk using the WORKPATH= option avoids conflicts with other jobs that use a default work path that is specified in the spdsserv.parm configuration file.
Using the optional WORKPATH= specification to direct utility file operations to a separate disk increases the overall I/O throughput for the utility files and speeds up the server performance as well.

Syntax

WORKPATH=('path-specification') ;

Example

Two SPD Server power users perform heavy index creation and are creating heavy I/O contention on the default workpath that is defined in the spdsserv.parm configuration file:
workpath=('workspace1')
Both users override the default workpath by using the alternate WORKPATH= specification when issuing the LIBNAME statements in their jobs:
User 1 LIBNAME statement:
LIBNAME domain-name sasspds "domain-name"
   server=host-name.port-number
   user='user1'

workpath=('/bigdisk/spdsmgr/workpath1') ;
User 2 LIBNAME statement:
LIBNAME domain-name sasspds "domain-name"
   server=host-name.port-number
   user='user2'

workpath=('/bigdisk/spdsmgr/workpath2') ;
All SPD Server jobs by other users continue to use the default workpath specification that is declared in spdsserv.parm
The libnames.parm configuration file also accepts alternate WORKPATH= specifications for each domain.