Named Counter Service

Version 3.0.2

Last updated: December 1, 2009

Description
Software Requirements
Installation and Configuration
Variables
Request Syntax
- INC
- DEC
- GET
- RESET
- DELETE
- LIST
- VERSION
- HELP
Error Code Reference

Named Counter Service

Description

The Named Counter service is an external STAF service that provides the ability to dynamically manage counters based on a name.

Software Requirements

This service requires:

STAF Version 3.0.0 or later
Java 1.2 or later

Installation and Configuration

Install the Named Counter service by downloading the NamedCounterV302.zip/tar file from Get STAF Services and extracting its contents to a local directory (e.g. C:\STAF\services or /usr/local/staf/services). The STAFNamedCounter.jar file is the service jar file needed when registering the Named Counter service.

The Named Counter service is written in Java and since it is an external service, it must be registered with the SERVICE configuration statement. The syntax is:

SERVICE <ServiceName> LIBRARY JSTAF EXECUTE <Service Jar File Name>

<ServiceName> is the name by which the Named Counter service will be known on this machine.

<Service Jar File Name> is the fully-qualified name of the STAFNamedCounter.jar file.

Example

SERVICE NamedCounter LIBRARY JSTAF EXECUTE c:/STAF/services/namedcounter/STAFNamedCounter.jar

Variables

The Named Counter service uses a STAF system variable named "STAF/Service/<ServiceName>/Persist" which can be set on the server running the service to define whether the named counters should be persisted to the filesystem so that they are not lost when the STAFProc is stopped and started. As an example, the following statement would be added to the STAF configuration file:

SET SYSTEM VAR STAF/Service/NamedCS/Persist=True

The default is NOT to persist the named counters, and as such, if this variable isn't set that is the behaviour which is used.

Request Syntax

The Named Counter service provides the following requests:

INC - Increments (or creates if doesn't exist) the named counter by 1
DEC - Decrements the named counter by 1
GET - Gets the value of a named counter
RESET - Resets the named counter to 0
DELETE - Deletes the named counter
LIST - Lists the named counters
VERSION - Displays the version of the Named Counter service
HELP - Displays a list of requests for the Named Counter service and how to use them.

INC

Increments (or creates if didn't previously exist) the named counter by 1 .

Syntax

INC <name>

<name> Specifies the name of the counter to increment.

Security

Minimum security level of 4 required to do an INC.

Return Codes

See table 1.

Results

The incremented value of the counter specified is returned.

DEC

Decrements the named counter by 1 .

Syntax

DEC <name>

<name> Specifies the name of the counter to decremented.

Security

Minimum security level of 4 required to do a DEC.

Return Codes

See table 1.

Results

The incremented value of the counter specified is returned.

GET

Gets the value of the named counter.

Syntax

GET <name>

<name> Specifies the name of the counter.

Security

Minimum security level of 1 required to do a GET.

Return Codes

See table 1.

Results

The value of the counter specified is returned.

RESET

Resets the named counter back to Zero.

Syntax

RESET <name>

<name> Specifies the name of the counter reset.

Security

Minimum security level of 4 required to do a RESET.

Return Codes

See table 1.

Results

The zeroed value for the named counter.

DELETE

Delete the named counter.

Syntax

DELETE <name>

<name> Specifies the name of the counter to delete.

Security

Minimum security level of 4 required to do a DELETE.

Return Codes

See table 1.

Results

The counter named will no longer exist.

LIST

List all of the named counters, along with their values.

Syntax

LIST

Security

Minimum security level of 1 required to do a LIST.

Return Codes

See table 1.

Results

A <Map> of <String> representing the counters with the name of the counters as the map keys and the counts as the map values.

Examples

Goal: List all of the counters
Syntax: LIST
Result: If the request is submitted from the command line, the result, in the default format, could look like:

ActiveClients     : 52
UnexpectedTimeouts: 4
Workload/TestType1: 4
Workload/TestType2: 1
Workload/TestType3: 7
Workload/TestType4: 2
Workload/TestType5: 9

VERSION

Get details of the commands syntax.

Syntax

VERSION

Security

Minimum security level of 1 required to do VERSION.

Return Codes

See table 1.

Results

The version of the Named Counter Service.

Examples

Goal: Get the version of the Named Counter service
Syntax: VERSION
Result: 3.0.2

HELP

Get details of the commands syntax.

Syntax

HELP

Security

Minimum security level of 0 required to do HELP.

Return Codes

See table 1.

Results

The allowable syntax to access the Named Counter Service.

NamedCounter Service Help

INC <name>
DEC <name>
GET <name>
RESET <name>
DELETE <name>
LIST
VERSION
HELP

Named Counter Error Code Reference

In addition to the common STAF return codes, the following Named Counter return codes are defined:

**Table 1. Named Counter Service Return Codes**
Error Code	Meaning	Comment
4001	Counter Does Not Exist	The specified named counter could not be found.
4002	Counter Already Zero	The named counter is currently at Zero.
4003	Counter At Max	The named counter is at its maximum possible value.