The SERVER Procedure

PROC SERVER Statement

Starts a SAS/SHARE server session.

Syntax

PROC SERVER <options>;

Summary of Optional Arguments

specifies the level of accounting.
specifies the libref associated with the library of administrative data for the server.
determines whether clients can define additional SAS libraries to a server after a server has started.
controls whether a server requires connecting users to provide a valid user ID and password when they connect to the server.
specifies the source of the client user ID to use in log messages that are written to the server log.
specifies the format for the date-and-time stamp at the beginning of each message that is written to the server log.
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.
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.
associates a unique message number (represented in hexadecimal notation) with each type of operation for which a message is recorded in a server log.
disables the ability of a server to interpret SAS data views.
specifies a password that you must supply (by using the OPERATE procedure) to connect to the server.
specifies the client password for controlling pass-through access to a remote DBMS.
specifies the name of a server.
specifies the suggested size of a buffer that the server uses to transmit potentially large pieces of information to a client or receive such information from a client.
specifies whether the threaded version of the TCP access method and associated threaded infrastructure should be used when TCP/IP communication is specified.
specifies a password that a client must supply in the LIBNAME statement to establish communication with the server.
specifies the initial and maximum number of work tasks for the SAS/SHARE server to execute.

Optional Arguments

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=:
ALL
causes the server to log statistics for all accounting levels (DATA, USER, and RESOURCE_ENVIRONMENT).
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.
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.
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.
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
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
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.
Aliases:REQ

OPT

Default:REQUIRED
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. For 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 SAS Formats and Informats: Reference.
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.
Alias:DTF
Default:DATETIME22.3
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.
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
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
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.
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.
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.
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
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.
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.
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. For details, see the PWENCODE Procedure in the Base SAS Procedures Guide.
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.
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 DBMS 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
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. For details, see the PWENCODE Procedure in the Base SAS Procedures Guide.
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.
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 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 TCP/IP 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 TCP/IP SERVICES File in Communications Access Methods for SAS/CONNECT and SAS/SHARE.
Note: Do not space after the first underscore or the second underscore. Example:
_ _1025
Note: Specifying a server by using a port number is not supported for ODBC clients.
Aliases: ID

SERVER

TBUFSIZE=value
specifies the suggested size of a buffer that the server uses to transmit potentially large pieces of information to a client or receive such 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.
One of the uses 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.
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:128k
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 SAS 9.0 and later clients.
Threaded TCP is 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.
Aliases:TTCP

NOTTCP

Default:NOTHREADEDTCP
UAPW=password | “encoded-password”
specifies a password that a client must supply in the LIBNAME statement to establish communication with 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. For details, see the PWENCODE Procedure in the Base SAS Procedures Guide.
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.
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 with some of the work done in parallel.. However, the majority of work will happen synchronously as work tasks time-slice against a single processor. A larger number of work tasks does facilitate fair processor sharing when the number of concurrent requests is high.
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.

Details

Interaction between PROC SERVER and Other File-Locking Processes

Under the 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.
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 Windows, 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.
For SAS 9.2 and later releases, 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.
For details, see the XCMD system option in the SAS Companion for UNIX Environments, the SAS Companion for Windows, or the SAS Companion for z/OS, as appropriate.

Examples

Example 1

The following statements start the server SHARE1:
proc server id=share1;
run;

Example 2

The following statements start the server SHARE1 and prevent clients from defining SAS libraries to the server:
proc server id=share1 noalloc;
run;

Example 3

The following statements start the server SHARE1 and report all message counts to the server log:
proc server id=share1 log=msg;
run;