Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next


Controls writing of request statistics to a data set


STATISTICS CREATE=library.dataset <(data-set-options)>;

STATISTICS DATA=library.dataset <(data-set-options)> <ADDPORT> <EXITONERROR> <TEMPLATE=library.dataset <(data-set-options)>> <WRITECOUNT=n> <WRITEEVERY=n>;

Server administrators can use the default data set variables that are supplied by the Application Server, or they can modify the variables that are written to the data set, by removing default variables and adding variables of their own.


CREATE=library.dataset <(data-set-options)>
creates the specified data set with the default set of statistics variables. The use of the CREATE= option is NOT required. The Application Server (when started with the STATISTICS DATA=library.dataset statement) will create a default data set even if the CREATE= option is not specified.

This option is only used in a standalone SAS session. Do NOT use it when starting the Application Server for application processing. The CREATE= option creates an empty SAS data set containing the default statistics data set variables. The data set can then be modified using a DATA step (to add new variables or drop existing default variables). The modified data set can then be used with the STATISTICS DATA= or TEMPLATE= option. See the Customizing the Statistics Data Set for an example of how to create and modify the statistics dataset.

DATA=library.dataset <(data-set-options)>
specifies the data set to which statistics are written. These data set options are not required. If the specified data set exists, it is opened and used. If the specified data set does not exist, it is created. If TEMPLATE= is specified, all of the variable definitions from the TEMPLATE data set are copied into the new DATA data set. If TEMPLATE= is not specified, the new data set has the default variables. Data set options should include options for creating the data set and for opening the data set for update.

The library specification must be a library that is specified in one of the Application Server ALLOCATE statements. This enables the Application Server to define the library for the server and for administrative requests.

Note: On z/OS, the library containing the statistics data set cannot use the DISP=NEW option because the library might be assigned multiple times. If you wish to create a new statistics data set when running PROC APPSRV, issue the LIBNAME statement with DISP=NEW before the PROC APPSRV statement. For example,

   libname statds '...' disp=new;

   proc appsrv port=5800;
   allocate library statds '...';
   statistics data=statds.stats;

tells the Application Server to append the port number of the current server to the member name of the STATISTICS data set. This is useful when you want pool servers to write to different data sets.

causes the Application Server to exit when there is a failure writing to the statistics data set. Failures can occur due to a disk-full condition, a SAS/SHARE server shutdown or other conditions that disable access to the data set. Use this option if you must collect statistics on all server accesses (for example, for security auditing purposes).

If EXITONERROR is not set, a write failure causes the Application Server to queue STATISTICS observations and periodically attempt to write them to the data set. The Application Server will continue to process client requests. If the error condition is not corrected and the Application Server is stopped, any queued STATISTICS observations are lost.

TEMPLATE=library.dataset <(data-set-options)>
specifies a template data set. When the statistics data set is created, the variable definitions from the template data set are copied into the new statistics data set.

The specified library must be defined externally to PROC APPSRV.

specifies the number of observations to place in the queue before writing to the data set. When the data set is temporarily unavailable (for example, when a SAS/SHARE server is restarting) the queue might grow larger than WRITECOUNT. The default value for WRITECOUNT is 50 observations.

writes all observations that are in the queue every n minutes. The default value for WRITEEVERY is 5 minutes.

Default Contents of the Data Set

The following table shows the default variables:

Variable Name Variable Type Description
Obstype Character length 1 R = request, I = Internal, U = startup, D = shutdown, T = trace
Okay Character length 1 1 = request ran okay, 0 = error
Duplex Character length 1 H = half duplex, F = full duplex
Http Character length 1 1 = http request, 0= normal broker request
Program Character length 32 _PROGRAM variable
Peeraddr Character length 16 Peer address
Hostname Character length 20 Node name of the server
Username Character length 12 _USERNAME variable, if any
Entry Character length 32 _ENTRY variable, if any
Sessionid Character length 12 _SESSIONID, if any
Service Character length 12 Service name
Starttime Number Time the request started
Runtime Number Run time of the request
Port Number Server port number
Bytesin Number Number of input bytes (read from client)
Bytesout Number Number of output bytes (written to client)
Cputime Number Amount of usage time for CPU for the request. This field is only available
on z/OS systems. The STIMER option must be enabled to get valid
Cputime values. The STIMER option is the default for z/OS.

Customizing the Statistics Data Set

In some cases, you might want to modify the list of variables in the data set. The example below shows how to

First, create a default data set using the following code:

   proc appsrv port=0; 
      statistics create=work.stdstat;

This command creates the data set called STDSTAT in the WORK library, and writes the default list of variables to it. Next, use a DATA step to create a modified data set, as follows:

   libname statlib 'path-to-library';
   data statlib.stats;

      /* change program length to 40 - you must change var defns before anything else */
      length program $40; 

      /* start with the default data set */
      set work.stdstat;

      /* set up EMPNO and EMPDEPT variables */
      attrib empno   length=$8  label='Employee Number';
      attrib empdept length=$32 label='Employee Department';

      /* drop service */
      drop service;  
      /* do not select any observations (there are none) from the previous data set */

The STATLIB.STATS data set now contains the desired variables. Modify your file to save statistics to this data set, as follows:

   proc appsrv ...;
      allocate library statlib 'path-to-library'; 
      statistics data=statlib.stats;

Application Server Access to the Data Set

The Application Server opens the statistics data set for WRITE access. This means that usually each server needs to write to its own data set. However, if a data set is accessed by using SAS/SHARE software, multiple servers can write to a single data set.

The following code is an example of a PROC APPSRV command that specifies that a single server accesses a single data set:

   proc appsrv ... ;
      allocate library data '.';
      STATISTICS DATA=data.stats;

The following is an example of a PROC APPSRV command that specifies that a server write statistics to a data set on a SAS/SHARE server:

   proc appsrv ... ;
      allocate library data '.' server=host.sasapp11;
      STATISTICS DATA=data.stats;

Refer to SAS/SHARE documentation for more information about configuring, running, and accessing SAS/SHARE servers.

Application Access to the Data Set

User applications can access the data set by using the _STATDATASET and _STATDATALIBNAME macro variables. The _STATDATASET macro variable contains the library.DATASET setting of the statistics data set for this server. The _STATDATALIBNAME contains the LIBNAME, the physical name, and the options of the ALLOCATE FILE statement for the statistics data set library. This enables the application to assign a LIBNAME to the library with additional options (for example, ACCESS=READONLY).

Before you access the data set with the _STATDATASET or _STATDATALIBNAME macro variables, check the status of the _STATDATASETAVAIL macro variable. It is set to one of the following values:

Value Description
OK The statistics data set is enabled and available for use.
NOADMINPW The statistics data set is enabled, but the _ADMINPW password was not supplied for this request or was incorrect. The _STATDATASET and _STATDATALIBNAME variables are not defined in this case.
NOSTATS The statistics data set is not enabled.

The following code is an example of assigning a libname and data access authority to the statistics data set library:

   &_STATDATALIBNAME access=readonly;
   data RSTATS;
      set &_STATDATASET;
      where obstype='R';
      keep program starttime runtime;

Note: Only requests with administrator privileges (if the PROC APPSRV ADMINPW option is not specified, all requests, otherwise only requests with a valid _ADMINPW) get these macro variables set. In this way, an administrator can control access to the data set.

Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next