APPSRV Procedure

STATISTICS Statement

Controls writing of request statistics to a data set

Syntax

Required 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) creates a default data set even if the CREATE= option is not specified.
This option is used only in a stand-alone 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 Customizing the Statistics Data Set for an example of how to create and modify the statistics data set.
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.
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 want 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;

Optional Arguments

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 continues 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 used instead of the default variables for the 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.

Details

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.

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 = start up, 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 available only
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.