7.4.6 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.
- Organization of this subsection
(1) 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 (UNIX) 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.
(2) 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.
(a) Option header
The first line is the option header line, which contains the specified field options. Each option must be separated by using one or more space characters or tabs. The field options correspond to user record fields.
tt ks ki l ...
The following table lists 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.
No. |
Option name |
Field name |
Value explanation |
Number of fields (total) |
||||
---|---|---|---|---|---|---|---|---|
PD_UPD (17) |
PD_UPDB (34) |
PI_UPI (23) |
PI_UPIB (49) |
PI_XUI1 to PI_XUI5 ( 67) |
||||
1 |
tt |
Trans Type |
Transaction type. This option is a required item.#1 Size: 1 to 19 bytes |
1 |
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 |
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 |
1 |
4 |
f |
User Float |
Floating point number.#2 Type: double |
2 |
5 |
2 |
5 |
30 |
5 |
fr#3 |
User Float Roll |
Floating point number for a cumulative value#2 Type: double |
-- |
-- |
2 |
5 |
30 |
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) |
64-byte character string#1 Size: 1 to 63 bytes + NULL |
1 |
5 |
1 |
5 |
2 |
9 |
sm |
User String(32) |
32-byte character string#1 Size: 1 to 31 bytes + NULL |
2 |
5 |
2 |
5 |
-- |
10 |
ss |
User String(16) |
16-byte character string#1 Size: 1 to 15 bytes + NULL |
4 |
5 |
4 |
5 |
-- |
11 |
sv |
User String(128) |
128-byte character string#1 Size: 1 to 127 bytes + NULL |
-- |
-- |
-- |
-- |
1 |
12 |
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 |
1 |
13 |
u |
User Unsigned Long |
Unsigned long data. Type: ulong Specifiable characters: Numeric values and a plus sign (+) |
2 |
5 |
2 |
5 |
-- |
14 |
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 uppercase and lowercase 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
(b) Data
The second and subsequent lines are for data. Data lines specify the performance data, corresponding to the field options 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.
(3) Notes
-
Create user-created data files in ASCII.
-
Each data line in this file must be terminated with a line feed character (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 space character.
-
Any empty lines or lines that contain a 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.
-
Create user-created data files while making sure their contents are not prepended with a BOM#. If the contents of a user-created data file are prepended with a BOM, running the jpcuser command results in an error.
- #
-
Abbreviation of "Byte Order Mark", an identifier added to the first line of the file to indicate the type of Unicode encoding (UTF-16 Little Endian, UTF-16 Big Endian, UTF-8, and so on). A 2-byte identifier is added for UTF-16, and a 3-byte identifier is added for UTF-8.