The SERVER Procedure

PROC SERVER Statement

Starts a SAS/SHARE server session.

Valid in:	server session
Category:	Data Access

Syntax

PROC SERVER <options>;

Options

ALLOC | NOALLOC

determines whether clients can define additional SAS libraries to a server after a server has started. The ALLOC option enables clients to define libraries to a server. The NOALLOC option prevents clients from defining additional libraries to the server and restricts clients to accessing libraries that are defined by a server administrator.

Default:

ALLOC

ACCTLVL=value | (value 1 < ... value n >)

specifies the level of accounting. Use this option to specify the aggregation (or detail) used in reporting server usage statistics. This option is useful for tuning an application because it enables you to examine, in more detail, how various parts of the application use the server resources. The usage statistics also enable you to charge users for the amount of server resources they consume.

The ACCTLVL= and LOG= options are closely related. The LOG= option specifies which usage statistic is written to the log; the ACCTLVL= option specifies the level of aggregation for that statistic (user, file, and resource environment). See the LOG= option for more information.

You can specify multiple values for the ACCTLVL= option by enclosing the values in parentheses and separating them with a space or a comma--for example, ACCTLVL=(USER DATA). Here are the valid values for ACCTLVL=:

DATA: causes the server to log statistics every time a SAS file is closed by a user. These statistics show the usage of server resources for each file by that user.
USER: causes the server to log statistics every time a user disconnects from the server. These statistics show the usage of server resources for that client session.
RESOURCE_ENVIRONMENT: causes the server to log statistics every time a user terminates a resource environment. Examples of resource environments include a SAS procedure, a SAS window, a DATA step, a SAS process, or other internal SAS activity. These statistics show the usage of server resources by requests that are made in the context of that resource environment by that user.
ALL: causes the server to log statistics for all accounting levels (DATA, USER, and RESOURCE_ENVIRONMENT).

Default:

USER

ADMINLIBREF=value | _NONE_

specifies the libref associated with the library of administrative data for the server. This option enables a client to handle a server's administrative data in the same way it handles any other SAS file, which enables the client to process that data programmatically. To turn off this type of access to a server's administrative data, specify ADMINLIBREF=_NONE_.

/* This program segment creates the SAS data file WORK.A,
which is a list of all the libraries that clients of the 
server are accessing. */
   libname sasadmin server=shr1;
   data a;
      set sasadmin.library;
      where users > '0';
run;

Default:

SASADMIN

AUTHENTICATE=REQUIRED | OPTIONAL

controls whether a server requires connecting users to provide a valid user ID and password when they connect to the server. You can use this option with a communications access method security option (for example, use the TCPSEC option for TCP/IP).

AUTHENTICATE=REQUIRED means that the security options of all the access methods that are used by the server must be set to _SECURE_. Also, PROC SERVER will not start unless all of the access methods guarantee that they require a valid user ID and password combination before establishing a connection between a client and the server.

AUTHENTICATE=OPTIONAL means that the communications access method security options might be set to _SECURE_. Each access method can have a different security option. This can be useful for a site that trusts the IDs of users that connect through one access method but does not trust the IDs of users that connect through another access method. In this instance, only the access method used by the non-trusted clients would have its security option set to _SECURE_. Using the parameter OPTIONAL allows trusted users to connect without requiring validation.

When an access method supplies a validated user ID (usually, by requiring a connecting client to specify a valid user ID and password combination), the server uses that validated ID to verify the user's authorization to access SAS files. When AUTHENTICATE=OPTIONAL and some access methods do not supply validated user IDs, those clients are allowed to access only those SAS files that the server is allowed to access. In this instance, you should run the server under a user ID that does not have open access to the files on its computer.

Default:

REQUIRED

Aliases:

REQ, OPT

CLIENTID = SESSION | SECURITY

specifies the source of the client user ID to use in log messages that are written to the server log. Your choice determines the search order that is used to locate the client user ID. Choose the source of the client's name to be used in the server log, as follows:

SESSION

specifies that the source of the client user ID is either the logon name or the batch account name of the client session. The server uses the following search order:

If a session name is located, the session name is used.
If a session name is not located, but a secured name is located, the secured name is used. (For details, see the SECURITY value.)
If neither a session name nor a secured name is located, the string _U_ is used as a generic identifier in the log messages.

SECURITY

specifies that the source of the user ID is the secured name that the client used to connect to the server. The server uses the following search order:

If a client's secured name is located, the secured name is used.

Note: A secured name is the user ID that is specified using the USERNAME= and PASSWORD= options in the LIBNAME statement.

Example:
```
libname test userid=tbass password=_PROMPT_;
```
For details about the LIBNAME statement, see LIBNAME Statement.
If a secured name is not located, but a session name is located, the session name is used. (For details, see the SESSION value).
If neither a session name nor a secured name is located, the string _U_ is used as a generic identifier in the log messages.

DTFORMAT=SAS-datetime-format |_NODTS_

specifies the format for the date-and-time stamp at the beginning of each message that is written to the server log. You can specify any SAS date, time, or date-and-time format; or you can specify your own date-and-time format. For details about specifying these formats, see the SAS formats in SAS Language Reference: Dictionary.

If you specify your own date-and-time format in this option, a SAS datetime value is supplied to the formatting routine. For an example of the date-and-time format in the server log, see Usage Statistics in the Server Log.

Specifying the value _NODTS_ suppresses the date-and-time stamp.

Default:

DATETIME22.3

Alias:

DTF

LRPYIELD=value

indicates, to a long-running process in the server's SAS session, how frequently the process should yield so that others can use the server. The default is 10000; this value has no units. Increase the value to have a long-running process yield more frequently; decrease the value to have it yield less frequently. LRPYIELD=0 does not yield at all. With a 0 value, the server can process other requests only after the long-running process has finished.

Here are two examples of long-running processes:

A client accesses a PROC SQL view that joins two large data sets which the server is required to sort.
A client issues a WHERE clause that requires the server to search millions of observations, sequentially, to find the first observation that satisfies the WHERE clause.

Default:

10000

LOG=value|(value 1 <... value n>)

causes the server to log specific usage statistics about client/server transactions and SQL queries that it receives through the Remote SQL Pass-Through facility. This is useful for application tuning and for charging clients for the amount of server resources they consume. The server writes one line to its log for each resource statistic that is specified.

When this option is used with the ACTIVETIME, BYTECOUNT, ELAPSEDTIME, and MESSAGE values, the LOG= option is related to the ACCTLVL= option. The LOG= option specifies which usage statistic is written to the log; the ACCTLVL= option specifies the level of aggregation for that statistic (user, file, and resource environment). See the ACCTLVL= option for more information.

The LOG=QUERY option allows you to track SQL queries that are submitted through the Remote SQL Pass-Through facility. This is useful to applications programmers for debugging and to server administrators to learn how the server is being accessed.

You can specify multiple values for the LOG= option by enclosing the values in parentheses and using a space or a comma to separate them--for example, LOG=(MESSAGE BYTECOUNT).

Note: The log values IO and CPU are no longer valid. The data that was reported by these options in SAS 6 offered limited accuracy, and the changes in resource tracking in SAS 8 reduced the potential accuracy even further. If you previously set the SAS options STIMER or FULLSTIMER because you had specified LOG=IO or LOG=CPU, you can reset or delete these SAS options in order to improve your server performance. [cautionend]

Here are the valid values for LOG=:

ACTIVETIME

causes the server to log the cumulative elapsed time of server processing for the specified event in the ACCTLVL= option. For example, if ACCTLVL=USER and LOG=ACTIVE, the server logs the cumulative elapsed time of processing for that client session when that client session ends. This value is printed using the SAS format TIME15.3. Here is an example of a log message that is recorded for this statistic:

30Apr2008:10:42:44.060 Usage statistics for user TIM(1):
                           Active time:               0:00:01.0394

Alias:

ACTIVE

BYTECOUNT

causes the server to log the cumulative number of bytes that are transferred between the client and the server for the event that is being logged. For example, if ACCTLVL=USER and LOG=BYTE, the server logs the cumulative number of bytes transferred between the client and the server for that client session when that client session ends. The value for BYTE is automatically scaled to make it easier to read and the appropriate character is appended to the data. K=Kilobytes (1,024 bytes), M=Megabytes (1,048,576 bytes) and G=Gigabytes (1,073,741,824 bytes). The values are printed using the SAS format COMMA10.0. Here is an example of a log message that is recorded for this statistic:

30Apr2008:10:52:31.040 Usage statistics for user MIKE(2):
                           Bytes transferred:             40,052 K

Alias:

BYTE

ELAPSEDTIME

causes the server to log the elapsed time of the recorded event. For example, if ACCTLVL=DATA and LOG=ELAPSED, the server logs the length of time that a file was open. If ACCTLVL=USER and LOG=ELAPSED, the server logs the length of time that the user was connected to the server. This value is printed using the SAS format TIME15.3. Here is an example of a log message that is recorded for this statistic:

30Apr2008:11:15:44.020 Usage statistics for user JOE(3):
                           Elapsed time:              0:22:57.6912

Alias:

ELAPSED

MESSAGE

causes the server to log the number of client requests that are processed by the server for the recorded event. For example, if ACCTLVL=USER and LOG=MESSAGE, the server logs the number of requests processed for the client when that client session ends. This value is printed using the SAS format COMMA15.0. Here is an example of a log message that is recorded for this statistic:

30Apr2008:13:22:04.060 Usage statistics for user STEPHEN(4):
                           Messages processed:                  15

Note: Do not confuse LOG=MESSAGE with the MSGNUMBER option. [cautionend]

Alias:

MSG

QUERY

causes the server to log each SQL query that it receives through the Remote SQL Pass-Through facility from a SAS session or other client. By default, the server logs only update and output SQL statements, not queries. If LOG= QUERY, you will see messages similar to the following in your server log:

30Apr2008:15:14:12.898 GISELLE(14) in "SQL"(13) has issued select
                       flight, date, depart from home.chicago where
                       flight='202' to SQLVIEW.

ALL

causes the server to log all the usage statistics (ACTIVETIME, BYTECOUNT, ELAPSEDTIME, and MESSAGE) for the corresponding accounting level. For example, if ACCTLVL=USER and LOG=ALL, the server logs statistics for ACTIVETIME, BYTECOUNT, ELAPSEDTIME, and MESSAGE for the client session when that client session ends.

If you specify LOG=ALL, the server will also log SQL queries that it receives through the Remote SQL Pass-Through facility. See the QUERY option for an example of the SQL messages that are logged.

Here is an example of a log message that is recorded when ALL is specified:

30Apr2008:16:02:44.060 Usage statistics for user BILL(1):
                           Messages processed:                  47
                           Bytes transferred:                104 K
                           Active time:               0:00:05.0394
                           Elapsed time:              0:22:57.6912

REM

is an acronym for REMOTE engine emulation; when the server terminates, this value causes the server to log the total number of connections and maximum concurrent number of connections from thin clients that access the SAS/SHARE server. These clients include Share JDBC, ODBC, OLE DB, and SAS SQL.

MSGNUMBER

associates a unique message number (represented in hexadecimal notation) with each type of operation for which a message is recorded in a server log.

CAUTION:: Avoid hardcoding message numbers in your applications. Use macros instead.
Message numbers can change from one software release to another.

Message numbers are useful for server log analysis applications, which can count the number of instances of an operation that occur in a specific client/server session. Collection and analysis of these statistics might help with server load balancing. SAS provides a set of server log analysis program prototypes that you can customize for your needs. Among these prototypes is a file that maps message numbers to operations. See Starting the Server Log for information about the server log analysis tools.

In the following example of a typical message written to a server log, the message number 043131 identifies a PROC SERVER start-up operation.

30Apr2008:08:28:20.911 043131 SAS server SHR1 started

Note: Do not confuse the MSGNUMBER option with the LOG=MESSAGE option. [cautionend]

Alias:

MSGN

NORMTVIEW

disables the ability of a server to interpret SAS data views.

By default, a SAS data view is interpreted in the server SAS session, and the data that is produced by the view is transmitted to a client SAS session.

Occasionally, it is preferable to transmit the view (the instructions for producing the data) to a client SAS session and to have the view interpreted and the data assembled in the server SAS session. You can use the RMTVIEW option in a LIBNAME statement to request this action on a library-by-library basis.

The NORMTVIEW option enforces transmission of the view (instead of the data) for all users of the server, regardless of whether the RMTVIEW option is specified in a LIBNAME statement.

Note: The NORMTVIEW option was developed for specific needs and is only rarely appropriate for use. To use this option for a server, contact SAS Technical Support to review the circumstances. [cautionend]

OAPW=password | "encoded-password"

specifies a password that you must supply (by using the OPERATE procedure) to connect to the server.

password

must be a valid SAS name that is 1 to 8 characters in length. The value for this option is replaced by Xs in the log. To protect this password, you should use the security software at your site to limit access to the SAS program statements that create the server.

"encoded-password"

is an encoded version of a password. Using encoded passwords promotes security and enables you to store SAS programs that do not contain clear-text passwords.

To obtain an encoded password, specify the clear-text password as input to the PROC PWENCODE statement.

Here is an example of code for obtaining an encoded password:

 proc PWENCODE in="srvmach";
run;
{sas001}c2Vydm1hY2g=

The clear-text password srvmach is specified in the PROC PWENCODE statement. The output is generated in the form {key}encoded-password . sas001 is the key, which is used to decode the encoded password to its clear-text form when the password is needed.

Note: The encoded password is case-sensitive. Use the entire generated output string, including the key. [cautionend]

Use the output from the PROC PWENCODE statement as the value for encoded-password in the appropriate statement.

PT2DBPW=password | "encoded-password"

specifies the client password for controlling pass-through access to a remote DBMS. This password allows a connection between the SAS/SHARE server and another data server (either a DMBS or another SAS/SHARE server) that contains the target database.

Pass-through access to a remote database by means of a SAS/SHARE server requires that you also run the CONNECT TO REMOTE statement in PROC SQL with the DBMS= option and the PT2DBPW= option.

password

"encoded-password"

is an encoded version of a password. Using encoded passwords promotes security and enables you to store SAS programs that do not contain clear-text passwords.

To obtain an encoded password, specify the clear-text password as input to the PROC PWENCODE statement.

Here is an example of code for obtaining an encoded password:

 proc PWENCODE in="srvmach";
run;
{sas001}c2Vydm1hY2g=

Note: The encoded password is case-sensitive. Use the entire generated output string, including the key. [cautionend]

Use the output from the PROC PWENCODE statement as the value for encoded-password in the appropriate statement.

SERVERID=server-ID | _ _port-number

specifies the name of a server.

server-ID

must be a valid SAS name that is 8 characters or less in length.

Server naming is also affected by the operating environment and the access method that you specify for communication between a server and a client session. For example, if you use the TCP/IP communications access method, server-ID must be a valid TCP/IP service as defined in the TCP/IP SERVICES file.

For complete information about how to name servers by operating environment, see Communications Access Methods for SAS/CONNECT and SAS/SHARE. For details about the SERVICES file, see SERVICES File in Communications Access Methods for SAS/CONNECT and SAS/SHARE.

_ _port-number

If you are using the TCP/IP access method, you can specify the server's port number that corresponds to the server ID in the TCP/IP SERVICES file. Precede the port number with two consecutive underscores. For details, see the topic on the SERVICES file in Communications Access Methods for SAS/CONNECT and SAS/SHARE.

Note: Do not space after the first underscore or the second underscore. [cautionend]

Example:

_ _1025

Note: Specifying a server by using a port number is not supported for ODBC clients. [cautionend]

Aliases:

SERVER, ID

THREADEDTCP | NOTHREADEDTCP

specifies whether the threaded version of the TCP access method and associated threaded infrastructure should be used when TCP/IP communication is specified. The default is NOTHREADEDTCP.

When THREADEDTCP is specified, communication activity to and from the server is processed primarily in a threaded context. Communication activity refers to the work the server does to receive a request and to reply to the request, including any necessary data representation conversion. Threading enables multiple, concurrent reception and transmission activity when the server runs on SMP hardware.

Also, a portion of the main request processing, which occurs between the time the request is received and the reply time, is performed in the threaded context for a SAS 9, 9.1, or 9.2 client or a SAS 9, 9.1, or 9.2 OLE DB provider for SAS/SHARE.

Note: New in SAS 9.2, threaded TCP is now compatible with the collection of active-time usage statistics. You specify the collection of statistics by setting either the LOG=ALL or LOG=ACTIVETIME option in the PROC SERVER statement. When THREADEDTCP is specified, active time can still be collected. [cautionend]

Aliases:	TTCP, NOTTCP
Default:	NOTHREADEDTCP
Restriction:	THREADEDTCP is an experimental option that was introduced in SAS 9.1. Do not use this option in production jobs.
Restriction:	THREADEDTCP is incompatible with network data encryption, which is specified by using the NETENCRYPT and NETENCRYPTALGORITHM system options. If network data encryption and THREADEDTCP are specified, an error message is issued and server initialization fails. For details about the encryption system options, see Data Security Technologies in SAS.

TBUFSIZE=value

specifies the suggested size of a buffer that the server uses to transmit information to a client or receive information from a client. When this option is not specified in the PROC SERVER statement, the value of the TBUFSIZE= SAS system option, if specified, is used.

The use of these transmission buffers is for transmitting observations. The server uses the value of the TBUFSIZE= option when computing the number of observations to transmit in each multi-observation transfer between the server and the client sessions. If the observation size, plus overhead, exceeds the value of the TBUFSIZE= option, only single-observation transfers are executed. Specifying an excessive value for the TBUFSIZE= option might cause your server or clients to run out of memory and to terminate abnormally.

You cannot calculate the number of observations per transfer by dividing the observation length into the value that you specify for the TBUFSIZE= option. To determine the effect of this option on your data sets, use the PROC SERVER options LOG=MESSAGE and ACCTLVL=DATA and compare the number of messages exchanged between the server and the client sessions as a function of the value of the TBUFSIZE= option and the number of observations in the data set.

Default:

32k

UAPW=password | "encoded-password"

specifies a password that a client must supply in the LIBNAME statement to establish communication with the server.

password

"encoded-password"

is an encoded version of a password. Using encoded passwords promotes security and enables you to store SAS programs that do not contain clear-text passwords.

To obtain an encoded password, specify the clear-text password as input to the PROC PWENCODE statement.

Here is an example of code for obtaining an encoded password:

 proc PWENCODE in="srvmach";
run;
{sas001}c2Vydm1hY2g=

Note: The encoded password is case-sensitive. Use the entire generated output string, including the key. [cautionend]

Use the output from the PROC PWENCODE statement as the value for encoded-password in the appropriate statement.

WORKTASKS = initial | ( <initial> <, maximum> )

specifies the initial and maximum number of work tasks for the SAS/SHARE server to execute. A work task is typically a pair of lightweight threads that service requests from SAS/SHARE clients. When the server receives a request for service and no work task is available, the server spawns a new work task to service the request, up to the maximum number specified.

More work tasks enable the SAS/SHARE server to service more asynchronous requests. However, the majority of work tasks that request service will execute synchronously. Also, the THREADEDTCP option facilitates asynchronous processing.

initial: specifies the initial number of work tasks for the SAS/SHARE server to execute. The default is 3.
maximum: specifies the maximum number of work tasks for the SAS/SHARE server to execute. The default is 16.

Interaction between PROC SERVER and other File-Locking Processes

Under the OpenVMS, UNIX, and Windows operating environments, if the FILELOCKWAITMAX= system option is not specified at SAS invocation, the FILELOCKWAITMAX= system option is set to zero for the duration of a server session that is started with PROC SERVER. This system option is used to specify the maximum time for a SAS session to wait to access a SAS file that is currently locked by another process.

Note: When using SAS/SHARE, you should not perform other processes that lock SAS files or use the FILELOCKWAITMAX= system option and the FILELOCKWAIT= option in the LIBNAME statement. [cautionend]

For details about the FILELOCKWAITMAX= system option and the FILELOCKWAIT= option in the LIBNAME statement, see the SAS Companion for UNIX Environments or the SAS Companion for the Microsoft Windows Environment, as appropriate.

PROC SERVER and the Default NOXCMD System Option

The XCMD and NOXCMD system options can be used to specify whether to enable host-system mode in order to submit an operating system command without ending the SAS session.

Using the XCMD option, an unauthorized user in a SAS/SHARE client session could access privileged data through a SAS/SHARE server session.

Starting in SAS 9.2, to prevent unauthorized access, if the XCMD system option is not specified at SAS invocation, the NOXCMD system option is set for the duration of a server session that is started with PROC SERVER.

Note: For SAS releases before SAS 9.2, XCMD is the default. Therefore, you must explicitly specify the NOXCMD system option in order to disable host-system mode. [cautionend]

For details, see the XCMD system option in the SAS Companion for OpenVMS, the SAS Companion for UNIX Environments, the SAS Companion for the Microsoft Windows Environment, or the SAS Companion for z/OS, as appropriate.

PROC SERVER: Examples

The following statements start the server SHARE1:

proc server id=share1;
run;

The following statements start the server SHARE1 and prevent clients from defining SAS libraries to the server:

proc server id=share1 noalloc;
run;

The following statements start the server SHARE1 and report all message counts to the server log:

proc server id=share1 log=msg;
run;

Top of Page