Job Management Partner 1/Performance Management - Agent Option for Platform Description, User's Guide and Reference

3.2.6 Settings for collecting user-specific performance data

This section provides an overview of the function that collects user-specific performance data, and explains how to set up the function.

Organization of this subsection

(1) Function overview

(2) Setting procedure

(3) Example of collecting user-specific performance data

(4) Format of the jpcuser command

(5) Format of user-created data files

(6) Debug log

(1) Function overview

The following explains functionality for collecting user-specific performance data and functionality for periodically executing user commands.

(a) Functionality for collecting user-specific performance data

This functionality uses the jpcuser command to convert custom performance data output by users to a text file, into a format that can be stored in records provided by PFM - Agent for Platform (PD_UPD, PD_UPDB, PI_UPI, and PI_UPIB). To use this functionality for collecting user-specific performance data, a command must be created to output performance data to text files ahead of time.

The following figure shows how user-specific performance data is collected.

Figure 3-9 Mechanism for collecting user-specific performance data

The following describes the processing corresponding to the numbers in the figure.

User commands are executed to create user-defined data.
The user commands collect performance data, such as process name, process ID, and number of processes, and output the collected data to a text file. The data in the text file is called user-created data.
The user commands must be created as scripts beforehand.

The jpcuser command is executed to convert the user-created data.
The jpcuser command converts the user-created data into a file in a format that can be managed by PFM - Agent for Platform. The file resulting from the conversion is called a user data file.

The contents of the user data file are saved in user-defined records every time PFM - Agent for Platform performs record collection.
PFM - Web Console must be set beforehand so that PFM - Agent for Platform collects the records from the user data file.

To collect performance data periodically, use the functionality for periodically executing user commands to set a user command, and the jpcuser command, to execute automatically.

Note

When outputting a file specified for the jpcuser command argument, or file in a batch file or script that executes the jpcuser command, specify a folder other than the installation folder.

For Windows Server 2008 environments, when directly executing the jpcuser command from a user command, execute the user command from a user with Administrators permissions.

(b) Functionality for periodically executing user commands

This functionality executes a user command from PFM - Agent for Platform at a fixed interval without using a task scheduler or other schedule functionality. The method for creating user data files from user commands is the same as described in (a) Functionality for collecting user-specific performance data.

Functionality for periodically executing user commands is executed using the same timing as record collection in PFM - Agent for Platform. After record collection processing is completed, a user data file is created by a user command, so that user data file collection processing and creation processing do not cause a race condition. Note that because functionality for periodically executing user commands is executed according to Collection Interval as set for the user record, it is executed for historical collection and alarm collection, but not for real-time collection. The following figure shows the flow of processing for functionality for periodically executing user commands.

Figure 3-10 Flow of processing for functionality for periodically executing user commands

Functionality for periodically executing user commands determines whether the previously started user command has terminated, and skips user command processing if it is executing.

Reference note

For versions of PFM - Web Console earlier than 09-00, functionality for periodically executing user commands cannot batch distribute properties to multiple PFM - Agent instances.

(c) Precautions regarding functionality for periodically executing user commands

The following gives precautions about functionality for periodically executing user commands.

Executable files

The file formats that can be executed by functionality for periodically executing user commands are as follows:

EXE format: executable file

COM format: executable (command) file

BAT format: batch file

To execute internal commands such as DEL and DIR as jobs, create a batch file, and then execute the command within the batch file.

Accounts

Use the system account to execute functionality for periodically executing user commands. Make sure that the system account can access the following files and resources:

Files specified for functionality for periodically executing user commands (user commands)

Resources referenced or updated from those files (user commands)

Environment variables

The environment variables valid for executing functionality for periodically executing user commands are the system environment variables defined when the Performance Management program service starts up. Profile information is not loaded when functionality for periodically executing user commands is executed.

Current folder

The PFM - Agent for Platform service folder (installation-folder\jp1pc\agtt\agent) is used as the current folder for executing functionality for periodically executing user commands.

Other precautions

Windows 16-bit applications cannot be executed.

When specifying a command in the Windows SysWOW64 system folder for functionality for periodically executing user commands, specify an absolute path.

Programs that display a window or dialog box cannot be executed. However, the net send command can be executed to display a dialog box, because it displays the Windows Messenger service instead of a dialog box.

Programs that use Windows messaging functionality (Dynamic Data Exchange, or DDE) cannot be executed.

Programs that require interactivity cannot be executed.

Resident programs (programs that do not terminate) cannot be executed.

Programs with extensions linked to an application cannot be executed.

Programs in network folders cannot be executed.

Do not set up programs on removable disks or other disks that cannot be set up.

Do not set Windows service startup settings to allow interaction with the desktop.

The contents of the standard output and standard error output cannot be obtained for executed programs.

When performing file output from an executed program, use an absolute path to specify the output destination file. If an absolute path is not specified, the folder for the PFM - Agent for Platform service (installation-folder\jp1pc\agtt\agent) is used as the current folder.

(2) Setting procedure

To collect user-specific performance data:

Determine the information to be stored in fields.

Create user commands.

Set the scheduler to collect user-specific performance data periodically.

Specify the settings for collecting information from the user data file.

The following subsections describe the steps in this procedure.

(a) Determining the information to be stored in fields

The fields of a user-defined record store two types of information, key information and data information. You will need to consider what to store as key information and what to store as data information.

n Key information

A user-defined record for storing user-specific performance data is a multi-instance record in which one or more rows can be stored by one collection run. To identify each record instance in one user-defined record, key information must be set. If you specify multiple user-created data files in the jpcuser command, you must set key information that uniquely identifies each record instance across all of the specified files. The following table describes the types of key information.

Table 3-13 Types of key information

Type Field name Explanation

Transaction type Trans Type Identifies the instance type.

Transaction key Trans Data Key (numeric type) Identifies each of the instances that have the same transaction type.

Trans String Key (string type)

The transaction type is used to identify the type of the performance data. For example, assume that information about a database is stored in one record and information about a Web server is stored in another record. In this case, you can use DATABASE and WEB as transaction types to indicate which type of information (information about a database or information about a Web server) is stored.

When there are multiple instances that have the same transaction type, the transaction key is used to identify each instance. If neither the Trans Data Key field nor the Trans String Key field is set or the same value is set for multiple transaction keys, the record instances cannot be identified uniquely. As a result, the first record instance is used.

n Data information

As data information, user-defined records can store three types of numeric data (double, long, and ulong types), three lengths of string data, and time data. The number of data items that can be stored differs depending on the user-defined record. For numeric data of the PI record type, either average or cumulative can be selected as the consolidation rule.

Select the user-defined record to be used based on the performance data to be collected. Note that a user-defined record that can store a larger amount of information consumes a larger amount of memory and other resources. We recommend that you select the user-defined record whose size is the minimum necessary.

The following table lists the number of fields for each type of user-defined record.

Table 3-14 Number of fields for each type of user-defined record

Record type User-defined record type Number of fields

Numeric data String data Time data

PD record type User Data Detail (PD_UPD) 2 x 3 = 6 1 + 2 + 4 = 7 1

User Data Detail - Extended (PD_UPDB) 5 x 3 = 15 5 + 5 + 5 = 15 1

PI record type User Data Interval (PI_UPI) 4 x 3 = 12 1 + 2 + 4 = 7 1

User Data Interval - Extended (PI_UPIB) 10 x 3 = 30 5 + 5 + 5 = 15 1

The following table lists the criteria for selecting the recommended user-defined record.

Table 3-15 Criteria for selecting the recommended user-defined record

Will cumulative data be stored as the performance data? Will many types of performance data be stored? Recommended user-defined record

Yes No PI_UPI

Yes Yes PI_UPIB

No No PD_UPD

No Yes PD_UPDB

(b) Creating user commands

User commands are scripts that are used to collect performance data to generate user-created data. You must code the scripts so that performance data is output in the format used for user-created data files.

For details about the format of user-created data files, see (5) Format of user-created data files.

To verify the user-created data output by the user commands, execute the jpcuser command in the following format:
installation-folder\agtt\agent\jpcuser\jpcuser PI_UPI -file user-created-data -debug 1
When the command is executed, the following debug log file is generated:
installation-folder\agtt\agent\jpcuser\debug\jpcuser_dbg_01.log
Use the debug log file to check for errors.

For details about the jpcuser command, see (4) Format of the jpcuser command.

(c) Setting a scheduler to collect user-specific performance data periodically

The following explains how to set up the functionality for periodically executing user commands, to periodically collect user-specific performance data.

To periodically collect user-specific performance data:

Set up user record collection in PFM - Web Console.
The execution interval for functionality for periodically executing user commands depends on the Collection Interval setting for each user record.

Set the properties for functionality for periodically executing user commands in PFM - Web Console.
In PFM - Web Console, set the following properties for each user record to run functionality for periodically executing user commands. The method for setting these properties is the same for PD_UPD records, PD_UPDB records, PI_UPI records, and PI_UPIB records.

Figure 3-11 Properties for functionality for periodically executing user commands

Table 3-16 Setting properties for user records

Property Value Description Default value

Execute Yes/No Specify whether to execute functionality for periodically executing user commands.

Yes: Perform execution

No: Do not perform execution

No

UserCommand Absolute path Specify the absolute path for user commands. The maximum length of the string that can be specified for an absolute path is 255 bytes. Half-width alphanumeric characters and half-width symbols can be specified, except for the following characters:
| < > Blank

#1

When the Execute property is set to Yes and the UserCommand property is blank, the KAVF11318-W message is output, and the user command is not executed.

#2

If the specified user command does not exist, or the user command does not have execution permissions, the KAVF11007-W message is output.

Reference note

The Windows Task Scheduler can be used to periodically collect user-specific performance data. Windows includes Task Scheduler, which can automatically execute a batch file or program at the specified time and interval. After creating a batch file that executes the user commands and then the jpcuser command, set Task Scheduler so that the batch file is executed periodically.

(d) Specifying the settings for collecting information from the user data file

The user data file contains data that the jpcuser command has converted from user-created data into a record format that can be managed by PFM - Agent for Platform. The data in the user data file is stored in user-defined records every time PFM - Agent for Platform collects records. Make sure that PFM - Web Console is set so that PFM - Agent for Platform will collect user-defined records.

For details about how to collect records, see the chapter on Performance Management functionality in the manual Job Management Partner 1/Performance Management Planning and Configuration Guide.

Type	Field name	Explanation
Transaction type	Trans Type	Identifies the instance type.
Transaction key	Trans Data Key (numeric type)	Identifies each of the instances that have the same transaction type.
Trans String Key (string type)

Record type	User-defined record type	Number of fields
Numeric data	String data	Time data
PD record type	User Data Detail (PD_UPD)	2 x 3 = 6	1 + 2 + 4 = 7	1
User Data Detail - Extended (PD_UPDB)	5 x 3 = 15	5 + 5 + 5 = 15	1
PI record type	User Data Interval (PI_UPI)	4 x 3 = 12	1 + 2 + 4 = 7	1
User Data Interval - Extended (PI_UPIB)	10 x 3 = 30	5 + 5 + 5 = 15	1

Will cumulative data be stored as the performance data?	Will many types of performance data be stored?	Recommended user-defined record
Yes	No	PI_UPI
Yes	Yes	PI_UPIB
No	No	PD_UPD
No	Yes	PD_UPDB

Property	Value	Description	Default value
Execute	Yes/No	Specify whether to execute functionality for periodically executing user commands. Yes: Perform execution No: Do not perform execution	No
UserCommand	Absolute path	Specify the absolute path for user commands. The maximum length of the string that can be specified for an absolute path is 255 bytes. Half-width alphanumeric characters and half-width symbols can be specified, except for the following characters: \| < >	Blank

(3) Example of collecting user-specific performance data

This subsection provides an example of collecting process information into the PI_UPI record under the conditions shown in the following table.

Table 3-17 Conditions for collecting performance data in the example

Option Explanation Corresponding field Value

tt Transaction type Trans Type PROCESS

ki Transaction key (numeric type) Trans Data Key Process ID

ks Transaction key (string type) Trans String Key Process name

u Unsigned long type User Unsigned Long 1 Number of threads

(a) Examples of user commands

The following are examples of user commands (userproc1.vbs and userproc2.vbs) that acquire process information from Windows and output user-created data.

userproc1.vbs:
' Output header.
WScript.Echo "Product Name=PFM-Agent for Platform (Windows)"
WScript.Echo "FormVer=0001"
' Output option header.
WScript.Echo "tt ki ks u"
' Get and output a list of processes. A string including a space is enclosed in Chr(34) codes.
for each Process in GetObject("winmgmts:").InstancesOf("win32_process")
  WScript.Echo "Process", Process.ProcessId, Chr(34) & Process.Name & Chr(34), Process.ThreadCount
next
userproc2.vbs:
' Output header.
WScript.Echo "Product Name=PFM-Agent for Platform (Windows)"
WScript.Echo "FormVer=0001"
' Output option header.
WScript.Echo "tt u"
' Get and output total amount of physical memory.
for each Memory in GetObject("winmgmts:").InstancesOf("Win32_LogicalMemoryConfiguration")
  WScript.Echo "TotalPhysicalMemory", Memory.TotalPhysicalMemory
next
The following examples are examples of user-created data output by the user commands above.

Example of user-created data output by userproc1.vbs:
Product Name=PFM-Agent for Platform (Windows)
FormVer=0001
tt ki ks u
Process 0 "System Idle Process" 1
Process 8 "System" 41
Process 172 "SMSS.EXE" 6
Process 200 "CSRSS.EXE" 12
Process 196 "WINLOGON.EXE" 19
Process 248 "SERVICES.EXE" 41
Example of user-created data output by userproc2.vbs:
Product Name=PFM-Agent for Platform (Windows)
FormVer=0001
tt u
TotalPhysicalMemory 1048052
Reference note

For an example of collecting information about used ports, see 1.3.2(8) Example of collecting information about used ports.

For an example of collecting performance data from multiple hosts on which PFM product is not installed, see 1.3.2(9) Example of collecting performance data from multiple hosts on which PFM products are not installed.

(b) Example of a batch file used to perform periodic collection

The following gives an example of a batch file (userperf.bat) using functionality for periodically executing user commands to perform periodic execution.
Move the REM folder
cd C:\Program Files\Hitachi\jp1pc\agtt\agent\jpcuser
REM Generate user-created data.
cscript //nologo userproc1.vbs > UPI1.txt
cscript //nologo userproc2.vbs > UPI2.txt
REM Use the jpcuser command to convert the data into a record format.
jpcuser PI_UPI -file UPI1.txt -file UPI2.txt^#
#: If -debug 2 is specified, debug log information is output to the following folder:
installation-folder\agtt\agent\jpcuser\debug\
Store the batch file (userperf.bat) and VB script in the following location:
C:\Program Files\Hitachi\jp1pc\agtt\agent\jpcuser
Reference note

This batch file can be periodically executed using the Windows Task Scheduler.

Option	Explanation	Corresponding field	Value
tt	Transaction type	Trans Type	PROCESS
ki	Transaction key (numeric type)	Trans Data Key	Process ID
ks	Transaction key (string type)	Trans String Key	Process name
u	Unsigned long type	User Unsigned Long 1	Number of threads

(4) Format of the jpcuser command

The following describes the format of the jpcuser command.
Format:
jpcuser record-name
        -file user-created-data-file-name
        [-file user-created-data-file-name]...
        [-debug [0|1|2]]
Note: Square brackets ([]) indicate optional items. A vertical bar (|) has the same meaning as OR. Accordingly, only one of the options separated by a vertical bar can be used at a time.
Description:

The jpcuser command converts user-created data (user-specific performance data output by user commands) into data in a format that PFM - Agent for Platform can use (user data file).

The command can also output debug log information that can be used for checking whether the user-created data is correct. For details about the debug log, see (6) Debug log.

If an error occurs during execution of this command, an error message is output to the following folder: installation-folder\agtt\agent\jpcuser\log\public\.

Users who can execute the command:

Members of the Administrators group

Location of the command:

installation-folder\agtt\agent\jpcuser\

Arguments:

The first argument in the command line must be record-name. The -debug option can be specified before or after -file options. The arguments that are always required on the command line are record-name and a -file option. The -debug option can be omitted.

record-name

Specify the name of the user-defined record in which performance data is to be stored. You can specify only one of the following names:

PD_UPD

PD_UPDB

PI_UPI

PI_UPIB

-file user-created-data-file-name

Specify the name of a user-created data file whose length is no more than 1023 bytes. Use multiple -file options to specify multiple user-created data files. When multiple user-created data files are specified, the command creates one user data file from the user-created data files.

Wildcard characters cannot be used in the file name specified in the -file option.

You can specify a file name by using a relative path name from the current directory, which is the directory in which the command is executed.

If a warning occurs in one or more files when multiple user-created data files are specified, the command returns a value that indicates normal termination with a warning. If an error occurs in one or more files, the command returns a value that indicates abnormal termination or the occurrence of an error.

-debug [0|1|2]

Use this option to specify whether to output only the user data file, only the output debug log information, or both. You can use this option to check whether the user-created data was correct. You can specify only one -debug option in the command.

When -debug 1 is specified, the command performs only debugging. If you want to create user-defined records, specify the -debug option with a value other than 1.

If an error message is output to the debug log, an error might exist in the user command scripts.

If this option is not specified, the command does not output debug log information.

The following table explains the values that can be specified in the -debug option.

Table 3-18 Values specified for the debug option

Value User data file output? Debug log file output?

0 Yes No

1 No Yes

2 Yes Yes

Other values Yes No

No value specified Yes No

Legend:

Yes: The file is output.

No: The file is not output.

The user data file is created with the name jpcuser_XXX in the installation-folder\agtt\agent\jpcuser\userdata folder. The XXX part represents the record type (UPD, UPDB, UPI, or UPIB).

The debug log is created with the name jpcuser_dbg_XX.log in the installation-folder\agtt\agent\jpcuser\debug folder. The XX part is a two-digit number that indicates how new the log file is. The following table explains the naming rule for debug log files.

Table 3-19 Example of debug log output

Debug log file name Explanation

jpcuser_dbg_01.log The latest debug log file

jpcuser_dbg_02.log The second latest debug log file

jpcuser_dbg_03.log The third latest debug log file

... ...

Return value:

0 Normal termination

1 to 100 Normal termination with a warning

101 to 255 Abnormal termination or the occurrence of an error

Value	User data file output?	Debug log file output?
0	Yes	No
1	No	Yes
2	Yes	Yes
Other values	Yes	No
No value specified	Yes	No

Debug log file name	Explanation
jpcuser_dbg_01.log	The latest debug log file
jpcuser_dbg_02.log	The second latest debug log file
jpcuser_dbg_03.log	The third latest debug log file
...	...

(5) Format of user-created data files

This subsection describes the format of user-created data files. For user commands collecting performance data, output text according to this format.

Information output to a user-created data file consists of a product information section and a data section. Both of these sections must be present in each user-created data file. The following figure gives an example configuration of user-created data.

Figure 3-12 Example configuration of user-created data

(a) Product information section

The product information section contains the constants that indicate the product name and the version of the user-created data file. The information set in this section is used only by internal functions and is not stored in records.

The following is an example of information set in this section.
Product Name=PFM-Agent for Platform (Windows)
FormVer=0001
Note:

In the above specification method, an error will occur if there is a space before or after the equal sign (=). Note that the specified characters are case sensitive.

(b) Data section

This section sets performance data information. This information is specified below the product information section. The data section consists of the option header and a data part.

n Option header

The first line is the option header line, which contains the specified field options. Each option must be separated using one or more space characters or tabs. The field options correspond to user record fields.

tt ks ki l ...

The following table lists field option names and corresponding record field names. Each of the columns for number of fields indicates the maximum number of options that can be specified. For example, if ss is specified multiple times for the field option in a PI_UPI record, note that the PI_UPI column (No. 10) indicates 4. Accordingly, you can specify ss a maximum of four times, such as ss ss ss ss, for the PI_UPI record.

Table 3-20 Options that can be specified in the data section and the corresponding fields

No. Option name Field name Explanation of value Number of fields (total)

PD_UPD (17) PD_UPDB (34) PI_UPI (23) PI_UPIB (49)

1 tt Trans Type Transaction type. This option is a required item.^#1
Size: 1 to 19 bytes 1 1 1 1

2 ki Trans Data Key Numeric-type transaction key.
Either ki or ks, or both, must be specified.
Type: ulong
Specifiable characters: Numeric values and a plus sign (+) 1 1 1 1

3 ks Trans String Key String-type transaction key.
Either ki or ks, or both, must be specified.^#1
Size: 1 to 19 bytes 1 1 1 1

4 f User Float Floating point number.^#2
Type: double 2 5 2 5

5 fr^#3 User Float Roll Floating point number for a cumulative value^#2
Type: double -- -- 2 5

6 l User Long Signed long data.
Type: long
Specifiable characters: Numeric values and signs (+, -) 2 5 2 5

7 lr^#3 User Long Roll Signed long data for a cumulative value.
Type: long
Specifiable characters: Numeric values and signs (+, -) -- -- 2 5

8 sl User String(64) Long string.^#1
Size: 1 to 63 bytes + NULL 1 5 1 5

9 sm User String(32) Medium string.^#1
Size: 1 to 31 bytes + NULL 2 5 2 5

10 ss User String(16) Short string.^#1
Size: 1 to 15 bytes + NULL 4 5 4 5

11 t User Time Time data (time_t type) in the following format:
YYYY/MM/DD,hh:mm:ss
The time must be the local time of the machine on which the jpcuser command is executed. 1 1 1 1

12 u User Unsigned Long Unsigned long data.
Type: ulong
Specifiable characters: Numeric values and a plus sign (+) 2 5 2 5

13 ur^#3 User Unsigned Long Roll Unsigned long data for a cumulative value.
Type: ulong
Specifiable characters: Numeric values and a plus sign (+) -- -- 2 5

Legend:

--: Not specifiable.

#1

The characters that can be specified are upper-case and lower-case alphabetic characters, numeric characters, space characters, and the following symbols:

` ~ ! @ # $ % ^ & * ( ) _ + - = { } : ; < > , . ? / | \ [ ]

#2

The characters that can be specified are numeric values and the following symbols:

- + .

#3

When history data collected by specifying the fr, lr, or ur option is displayed in consolidation mode, the cumulative value is displayed. When a numeric-value option other than these options or the ki option is specified, the average value is displayed.

Note that if multiple field options are specified for user-created data, they are allocated sequentially to the target field of the user record.

For example, if lr is specified 3 times for the field option of the PI_UPIB record, this is specified as lr lr lr. In this case, each lr is allocated to its field as follows:

First lr: User Long Roll 1

Second lr: User Long Roll 2

Third lr: User Long Roll 3

If sl lr sl lr lr is specified, it is allocated to the following fields:

First sl: User String 11

Second lr: User Long Roll 1

Third sl: User String 12

Fourth lr: User Long Roll 2

Fifth lr: User Long Roll 3

n Data

The second and subsequent lines are for data. Data lines specify the performance data, corresponding to the field operations specified in the optional header. Each column is separated by 1 or more bytes of spaces or tabs.

Make sure that the order of the data matches the field option type.

For example, if tt ks lr lr ss ss is specified for the field option, an error will occur for all lines for the following data order:
TCP jp1host "ESTABLISHD COUNT=" 5 "LISTENING COUNT=" 2
TCP jp1host "ESTABLISHD COUNT=" 3 "LISTENING COUNT=" 1
TCP jp1host "ESTABLISHD COUNT=" 3 "LISTENING COUNT=" 2
The reason this error occurs is because the field options for the third and sixth columns do not match the data types.

Third column
The string "ESTABLISHD COUNT=" is specified for the lr field option, even though a cumulative long integer value should be specified.

Sixth column
The integer values 2, 1, 2 are specified for the ss field option, even though a string of size 16 should be specified.

(c) Precautions

Create user-created data files in ASCII.

Each data line in this file must be terminated with a carriage return character and line feed character (CR+LF).

Comments cannot be specified in user-created data files.

An error will occur if any of the first three lines of a user-created data file are empty or contain a half-width space character.

Any empty lines or lines that contain a half-width space character are disregarded for the fourth and subsequent lines of a user-created data file.

When entering a string with a space character, enclose the string in double quotation marks (").

For the string type, set a single-byte string of printable alphanumeric characters. Special single-byte characters such as " cannot be set.

One field option can be specified for definition in the optional header line for each user-created data file. To define a different field option, create another user-created data file.

No.	Option name	Field name	Explanation of value	Number of fields (total)
PD_UPD (17)	PD_UPDB (34)	PI_UPI (23)	PI_UPIB (49)
1	tt	Trans Type	Transaction type. This option is a required item.^#1 Size: 1 to 19 bytes	1	1	1	1
2	ki	Trans Data Key	Numeric-type transaction key. Either ki or ks, or both, must be specified. Type: ulong Specifiable characters: Numeric values and a plus sign (+)	1	1	1	1
3	ks	Trans String Key	String-type transaction key. Either ki or ks, or both, must be specified.^#1 Size: 1 to 19 bytes	1	1	1	1
4	f	User Float	Floating point number.^#2 Type: double	2	5	2	5
5	fr^#3	User Float Roll	Floating point number for a cumulative value^#2 Type: double	--	--	2	5
6	l	User Long	Signed long data. Type: long Specifiable characters: Numeric values and signs (+, -)	2	5	2	5
7	lr^#3	User Long Roll	Signed long data for a cumulative value. Type: long Specifiable characters: Numeric values and signs (+, -)	--	--	2	5
8	sl	User String(64)	Long string.^#1 Size: 1 to 63 bytes + NULL	1	5	1	5
9	sm	User String(32)	Medium string.^#1 Size: 1 to 31 bytes + NULL	2	5	2	5
10	ss	User String(16)	Short string.^#1 Size: 1 to 15 bytes + NULL	4	5	4	5
11	t	User Time	Time data (time_t type) in the following format: YYYY/MM/DD,hh:mm:ss The time must be the local time of the machine on which the jpcuser command is executed.	1	1	1	1
12	u	User Unsigned Long	Unsigned long data. Type: ulong Specifiable characters: Numeric values and a plus sign (+)	2	5	2	5
13	ur^#3	User Unsigned Long Roll	Unsigned long data for a cumulative value. Type: ulong Specifiable characters: Numeric values and a plus sign (+)	--	--	2	5

(6) Debug log

The debug log is used to check whether the user-created data is correct. If you want to output debug log information, specify the -debug 1 or -debug 2 option in the jpcuser command.

In the debug log, a check result code, such as OK (success), NG (failure), or WG (warning), is output for each data line in the user-created data. If NG or WG is output in the debug log, the user-created data might be invalid. If NG or WG has been output, check the user commands by which the user-created data was created, and make any necessary corrections for outputting the data in the correct format. For the correct format, see (5) Format of user-created data files.

The following shows the location and name of a debug log file:
installation-folder\agtt\agent\jpcuser\debug\jpcuser_dbg_{01|02|03|04|05}.log
The following describes the debug log file format.

(a) Debug log file format

A debug log file consists of four sections:

Product information

The execution time and process ID of the jpcuser command

Header line

Check results

A check result is output for each data line in the user-created data. A comma is used to separate items.

The following table explains the items that are output to a debug log file.

Table 3-21 Items that are output to a debug log file

No. Section Item Value Explanation

1 Product information Product name Product Name=PFM-Agent for Platform (Windows) The PFM - Agent product name.

2 Format version FormVer=0001 The version of the user-created data format.

3 Execution time and process ID of the jpcuser command Execution time YYYY/MM/DD hh:mm:ss YYYY: Year
MM: Month
DD: Day
hh: Hour
mm: Minute
ss: Second

4 Process ID PID=xxxx The process ID of the jpcuser command.

5 Header line Header Example (for the PD_UPD record):
LineNumber, Result, APITime, Recordtype, Transactiontype, t, ks, ki, L1, L2, UL1, UL2, F1, F2, SS1, SS2, SS3, SS4, SM1, SM2, SL1 The debug log header.
The header names correspond to the field options and field names specified on the option header line in a user-created data file. For the correspondence, see Table 3-14.
Note that the header items differ depending on the user-defined records that are to be stored.

6 Check result User-created data file name Example:
File=D:\Program Files\HITACHI\jp1pc\agtt\agent\jpcuser\UPIB_sample01.txt The user-specified path name of a user-created data file that is read is output.

7 Error or warning message KAVFxxxxx-x If an error or other problem that the user should be made aware of occurs on a line in the user-created data, the applicable error and warning messages are output at the beginning of the line.

8 Line number Numeric value The number of a line in the user-created data.

9 Result code OK Success.
The line in the user-created data was free of problems and was converted successfully.

10 WG Warning.
The line in the user-created data contained a problem but was converted nevertheless.
When WG is output, a warning message is also output.

11 NG Failure.
The line in the user-created data contained a problem and was not converted.
When NG is output, a warning message or error message, depending on the cause of the problem, is also output. If a warning message is output, processing continues. If an error message is output, processing stops.

12 BL Null line.
The line in the user-created data is empty and is ignored.

13 Data Data The contents of the line in the user-created data.
For an empty numeric field, 0 is output.
For an empty string field, two quotation marks ("") are output.

The following table lists the items output on the header line in a debug log file and their corresponding field options and field names specified on the option header line in a user-created data file.

Table 3-22 Header line items in a debug log file and their corresponding field options and field names

No. Item on the header line in a debug log file Field option specified on the option header line in a user-created data file Field name
(PFM - View name) Explanation

1 Line Number -- -- Number of the line on which the relevant data exists

2 Result -- -- Check result of the relevant data

3 API Time -- Collect Time Time that the relevant data was converted

4 Record type -- Record Type Record type

5 Transaction type tt Trans Type Transaction type

6 t t User Time 1 Time value

7 ks ks Trans String Key String-type transaction key

8 ki ki Trans Data Key Numeric-type transaction key

9 L1 l User Long 1 Integer value of type long

10 L2 l User Long 2 Integer value of type long

11 L3 l User Long 3 Integer value of type long

12 L4 l User Long 4 Integer value of type long

13 L5 l User Long 5 Integer value of type long

14 L1R lr User Long Roll 1 Cumulative integer value of type long

15 L2R lr User Long Roll 2 Cumulative integer value of type long

16 L3R lr User Long Roll 3 Cumulative integer value of type long

17 L4R lr User Long Roll 4 Cumulative integer value of type long

18 L5R lr User Long Roll 5 Cumulative integer value of type long

19 UL1 u User Unsigned Long 1 Integer value of type unsigned long

20 UL2 u User Unsigned Long 2 Integer value of type unsigned long

21 UL3 u User Unsigned Long 3 Integer value of type unsigned long

22 UL4 u User Unsigned Long 4 Integer value of type unsigned long

23 UL5 u User Unsigned Long 5 Integer value of type unsigned long

24 UL1R ur User Unsigned Long Roll 1 Cumulative integer value of type unsigned long

25 UL2R ur User Unsigned Long Roll 2 Cumulative integer value of type unsigned long

26 UL3R ur User Unsigned Long Roll 3 Cumulative integer value of type unsigned long

27 UL4R ur User Unsigned Long Roll 4 Cumulative integer value of type unsigned long

28 UL5R ur User Unsigned Long Roll 5 Cumulative integer value of type unsigned long

29 F1 f User Float 1 Floating point number value

30 F2 f User Float 2 Floating point number value

31 F3 f User Float 3 Floating point number value

32 F4 f User Float 4 Floating point number value

33 F5 f User Float 5 Floating point number value

34 F1R fr User Float Roll 1 Cumulative floating point number value

35 F2R fr User Float Roll 2 Cumulative floating point number value

36 F3R fr User Float Roll 3 Cumulative floating point number value

37 F4R fr User Float Roll 4 Cumulative floating point number value

38 F5R fr User Float Roll 5 Cumulative floating point number value

39 SS1 ss User String 1 16-byte character string

40 SS2 ss User String 2 16-byte character string

41 SS3 ss User String 3 16-byte character string

42 SS4 ss User String 4 16-byte character string

43 SS5 ss User String 5 16-byte character string

44 SM1 sm User String 5 (for the PD_UPD or PI_UPI record)
User String 6 (for the PD_UPDB or PI_UPIB record) 32-byte character string

45 SM2 sm User String 6 (for the PD_UPD or PI_UPI record)
User String 7 for the (PD_UPDB or PI_UPIB record) 32-byte character string

46 SM3 sm User String 8 32-byte character string

47 SM4 sm User String 9 32-byte character string

48 SM5 sm User String 10 32-byte character string

49 SL1 sl User String 7 (for the PD_UPD or PI_UPI record)
User String 11 (for the PD_UPDB or PI_UPIB record) 64-byte character string

50 SL2 sl User String 12 64-byte character string

51 SL3 sl User String 13 64-byte character string

52 SL4 sl User String 14 64-byte character string

53 SL5 sl User String 15 64-byte character string

Legend:

--: Not applicable

(b) Example of information output to a debug log file

The following figure shows an example of information output to a debug log file.

Figure 3-13 Example of information output to a debug log file

The following explanations are keyed to the numbers in parentheses in the figure.

This line is the header line.

The user-specified path name of a user-created data file loaded into the command is output.

Output of the check result for the user-created data file begins with this line. The number (4) at the beginning of the line indicates the number of the line in the user-created data file. In a user-created data file, the first line contains product information, the second line contains version information, and the third line is the option header line. Therefore, checking normally begins with line 4. If the line contains no problems, OK is output for Result.

The user-specified path name of another user-created data file that is read is output.

This line warns the user of a problem on line 4 in the UPIB_sample02.txt file. Because the t value (2007/02/24,10:10:010) did not have the expected format, n/a has been output for the element corresponding to t (see (7) in the figure).

This line also warns the user of a problem on line 4 in the UPIB_sample02.txt file. Because the specified ss value (abcdefghijklmnop) exceeded the predefined maximum of 15 bytes, a warning message has been output. and a truncated value (abcdefghijklmno) has been output for the element corresponding to SS1 (see (7) in the figure).

Because the warnings indicated by (5) and (6) have been issued, the check result code WG has been output for Result for line 4.

The check result code BL indicates that the line is a null line.

This line warns the user of a problem on line 7. A warning message has been output because the specified ks value exceeded the predefined maximum of 19 bytes.

Because the value of the ks unique key on line 7 in the user-created data file was incorrect, the value could not be used. Accordingly, NG has been output for Result. If the value of Transaction type, ks, or ki, which is a unique key, is incorrect, the line is not processed.

No.	Section	Item	Value	Explanation
1	Product information	Product name	Product Name=PFM-Agent for Platform (Windows)	The PFM - Agent product name.
2	Format version	FormVer=0001	The version of the user-created data format.
3	Execution time and process ID of the jpcuser command	Execution time	YYYY/MM/DD hh:mm:ss	YYYY: Year MM: Month DD: Day hh: Hour mm: Minute ss: Second
4	Process ID	PID=xxxx	The process ID of the jpcuser command.
5	Header line	Header	Example (for the PD_UPD record): LineNumber, Result, APITime, Recordtype, Transactiontype, t, ks, ki, L1, L2, UL1, UL2, F1, F2, SS1, SS2, SS3, SS4, SM1, SM2, SL1	The debug log header. The header names correspond to the field options and field names specified on the option header line in a user-created data file. For the correspondence, see Table 3-14. Note that the header items differ depending on the user-defined records that are to be stored.
6	Check result	User-created data file name	Example: File=D:\Program Files\HITACHI\jp1pc\agtt\agent\jpcuser\UPIB_sample01.txt	The user-specified path name of a user-created data file that is read is output.
7	Error or warning message	KAVFxxxxx-x	If an error or other problem that the user should be made aware of occurs on a line in the user-created data, the applicable error and warning messages are output at the beginning of the line.
8	Line number	Numeric value	The number of a line in the user-created data.
9	Result code	OK	Success. The line in the user-created data was free of problems and was converted successfully.
10	WG	Warning. The line in the user-created data contained a problem but was converted nevertheless. When WG is output, a warning message is also output.
11	NG	Failure. The line in the user-created data contained a problem and was not converted. When NG is output, a warning message or error message, depending on the cause of the problem, is also output. If a warning message is output, processing continues. If an error message is output, processing stops.
12	BL	Null line. The line in the user-created data is empty and is ignored.
13	Data	Data	The contents of the line in the user-created data. For an empty numeric field, 0 is output. For an empty string field, two quotation marks ("") are output.

No.	Item on the header line in a debug log file	Field option specified on the option header line in a user-created data file	Field name (PFM - View name)	Explanation
1	Line Number	--	--	Number of the line on which the relevant data exists
2	Result	--	--	Check result of the relevant data
3	API Time	--	Collect Time	Time that the relevant data was converted
4	Record type	--	Record Type	Record type
5	Transaction type	tt	Trans Type	Transaction type
6	t	t	User Time 1	Time value
7	ks	ks	Trans String Key	String-type transaction key
8	ki	ki	Trans Data Key	Numeric-type transaction key
9	L1	l	User Long 1	Integer value of type long
10	L2	l	User Long 2	Integer value of type long
11	L3	l	User Long 3	Integer value of type long
12	L4	l	User Long 4	Integer value of type long
13	L5	l	User Long 5	Integer value of type long
14	L1R	lr	User Long Roll 1	Cumulative integer value of type long
15	L2R	lr	User Long Roll 2	Cumulative integer value of type long
16	L3R	lr	User Long Roll 3	Cumulative integer value of type long
17	L4R	lr	User Long Roll 4	Cumulative integer value of type long
18	L5R	lr	User Long Roll 5	Cumulative integer value of type long
19	UL1	u	User Unsigned Long 1	Integer value of type unsigned long
20	UL2	u	User Unsigned Long 2	Integer value of type unsigned long
21	UL3	u	User Unsigned Long 3	Integer value of type unsigned long
22	UL4	u	User Unsigned Long 4	Integer value of type unsigned long
23	UL5	u	User Unsigned Long 5	Integer value of type unsigned long
24	UL1R	ur	User Unsigned Long Roll 1	Cumulative integer value of type unsigned long
25	UL2R	ur	User Unsigned Long Roll 2	Cumulative integer value of type unsigned long
26	UL3R	ur	User Unsigned Long Roll 3	Cumulative integer value of type unsigned long
27	UL4R	ur	User Unsigned Long Roll 4	Cumulative integer value of type unsigned long
28	UL5R	ur	User Unsigned Long Roll 5	Cumulative integer value of type unsigned long
29	F1	f	User Float 1	Floating point number value
30	F2	f	User Float 2	Floating point number value
31	F3	f	User Float 3	Floating point number value
32	F4	f	User Float 4	Floating point number value
33	F5	f	User Float 5	Floating point number value
34	F1R	fr	User Float Roll 1	Cumulative floating point number value
35	F2R	fr	User Float Roll 2	Cumulative floating point number value
36	F3R	fr	User Float Roll 3	Cumulative floating point number value
37	F4R	fr	User Float Roll 4	Cumulative floating point number value
38	F5R	fr	User Float Roll 5	Cumulative floating point number value
39	SS1	ss	User String 1	16-byte character string
40	SS2	ss	User String 2	16-byte character string
41	SS3	ss	User String 3	16-byte character string
42	SS4	ss	User String 4	16-byte character string
43	SS5	ss	User String 5	16-byte character string
44	SM1	sm	User String 5 (for the PD_UPD or PI_UPI record) User String 6 (for the PD_UPDB or PI_UPIB record)	32-byte character string
45	SM2	sm	User String 6 (for the PD_UPD or PI_UPI record) User String 7 for the (PD_UPDB or PI_UPIB record)	32-byte character string
46	SM3	sm	User String 8	32-byte character string
47	SM4	sm	User String 9	32-byte character string
48	SM5	sm	User String 10	32-byte character string
49	SL1	sl	User String 7 (for the PD_UPD or PI_UPI record) User String 11 (for the PD_UPDB or PI_UPIB record)	64-byte character string
50	SL2	sl	User String 12	64-byte character string
51	SL3	sl	User String 13	64-byte character string
52	SL4	sl	User String 14	64-byte character string
53	SL5	sl	User String 15	64-byte character string

[Contents][Back][Next]

[Trademarks]

0	Normal termination
1 to 100	Normal termination with a warning
101 to 255	Abnormal termination or the occurrence of an error