STATISTICS Statement

Controls writing of request statistics to a data set

Syntax

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.

Arguments

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;
   run;

ADDPORT

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.

EXITONERROR

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.

WRITECOUNT=n

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.

WRITEEVERY=n

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

eliminate the default SERVICE variable
make the PROGRAM variable larger in size
and add two new variables, EMPNO and EMPDEPT (input values used by applications that run in this service).

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

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

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 */
      stop;
   run;

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

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

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;
      ...
      run;

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;
      ...
      run;

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;
      run;

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.