3.6.1 Defining a user-defined service

You must create a program for measuring the target service's performance, such as its response times, and then register the program as a user-defined command.

Organization of this subsection
(1) Creating a user-defined command
(2) Registering user-defined commands

(1) Creating a user-defined command

A user-defined command is created as a program that executes from the command line. Each user-defined command measures only one item. To measure multiple items, you must create a user-defined command for each item. Note that you must execute the user-defined commands with Administrator permissions because they are called from PFM - Agent for Service Response.

(a) Input

PFM - Agent for Service Response does not provide an interface for passing input values. For a service-specific measurement condition, you must provide the information that is necessary for measurement by an appropriate method, such as by specifying arguments in the user-defined command or reading files.

(b) Output

If a measurement result is to be the standard output of a user-defined command, the user-defined command must output the value shown below to the standard output. PFM - Agent for Service Response treats a value in the standard output as the response performance information. If the measurement result is to be the time required for the execution of the user-defined command (from start to termination), do not output anything to the user-defined command's standard output.

Table 3-9 Output of a user-defined command

ValueDescription
Response performance informationOutputs the value of a given measurement item (double-precision real number), such as total response time or throughput, expressed as a character string.
Supplement:
The measurement information obtained by a user-defined command is output to a report file. When a user-defined command's execution time is output, the value is in seconds with a precision of up to milliseconds. If the value output by a user-defined command is outside the permitted range or is in an invalid format, the system treats it as an error and stops the measurement.
(c) Return value

A user-defined command's return value indicates the measurement result. You must create your user-defined commands in such a manner that they return one of the values listed in the table below.

Table 3-10 Return values of user-defined commands

Return valueDescription
0Normal termination
The measurement terminated normally and the response performance information was acquired.
Other than 0Abnormal termination
The measurement failed and any value obtained as the response performance information is invalid.

You should store your created user-defined commands in the following user-defined command storage folder provided by PFM - Agent for Service Response:

installation-folder\agtv\probe\user

To call a command that has been stored in a folder other than the user-defined command storage folder, you must create a batch file for calling the command, and then store the batch file in the user-defined command storage folder.

Note:
A user-defined command is executed after the timeout value specified in the measurement condition is reached. This prevents startup of measurement (issuance of a measurement request) for other Internet services from being delayed if the current user-defined command's internal processing takes a long time. Therefore, create your user-defined command in such a way that its processing will be completed within the timeout value specified as a measurement condition.

(2) Registering user-defined commands

Register your created user-defined commands in the command registration file (espcommand.xml). In the command registration file, you can define a user-selected service ID which will be used to identify the target service and service-specific measurement conditions. For details about the command registration file, see 7.6 Command registration file (espcommand.xml).