jpcasrec update
- Organization of this page
Format
jpcasrec update [-mx maximum-heap-size] [-ms initial-heap-size] input-file
Function
The jpcasrec update command connects to an agent and changes the definition related to the recording method of the Store database. The command acquires the new recording method definition information from the XML-format parameter file that is specified as a command line argument. You can specify multiple Store database definition information items in a single parameter file to make changes in batch mode.
Hosts that can execute the command
PFM - Web Console
Execution permission
- In Windows:
-
User with Administrators permissions
- In UNIX:
-
User with root user permissions
To execute this command, a key file for authentication needs to be created in advance for a user account with administrator user permissions# for Performance Management. For details, see the jpcmkkey command.
- #
-
Execution permissions for Performance Management that are required for a Performance Management user or JP1 user.
Installation directory
- In Windows:
-
installation-folder\tools\
- In UNIX:
-
/opt/jp1pcwebcon/tools/
Arguments
-mx maximum-heap-size
Specifies the maximum heap size for java.exe (in megabytes). The default is 128 MB. The maximum size that can actually be acquired depends on the system. If the specified value does not satisfy the following conditions, an invalid command line format results:
-
Integer in the range 1 to 2,048
-
Value specified in -mx >= value specified in -ms
-ms initial-heap-size
Specifies the initial heap size for java.exe (in megabytes). The default is 32 MB. If the specified value does not satisfy the following conditions, an invalid command line format results:
-
Integer in the range 1 to 2,048
-
Value specified in -mx >= value specified in -ms
input-file
Specifies the XML-format parameter file that is to be used to change the Store database recording method definition information. This parameter file must be created according to the Parameter file format described below. You can specify the absolute file path name, relative file path name, or file name. When the name is not the absolute file path, the command assumes the current directory.
Parameter file format
XML tag specifications
-
agent-store-db-record-definition
Type
Description
Description
Root tag for the Store database recording method change definition information
Specifiable value
None
Omissible
No
Attribute
None
Parent element
pr-cli-parameters
Child element
service (can be specified more than once)
-
service
Type
Description
Description
Specifies the service that identifies the agent.
Specifiable value
None
Omissible
No
Attribute
id
Service ID (4 to 258 characters)
The first character specifies the product ID of the agent. For details about the product ID, see the PFM - Agent or PFM - RM manuals.
The second character specifies A (Agent Collector or Remote Monitor Collector).
Parent element
agent-store-db-record-definition
Child element
record (cannot be omitted and can be specified more than once)
-
record
Type
Description
Description
Specifies the record ID to be changed.
Specifiable value
None
Omissible
No
Attribute
id
Record ID (1 to 8 characters). This is a record ID described in the PFM - Agent or PFM - RM manuals.
Parent element
service
Child element#
log (can be specified only once per record or can be omitted)
collection-interval (can be specified only once per record or can be omitted)
collection-offset (can be specified only once per record or can be omitted)
logif (can be specified only once per record or can be omitted)
-
log
Type
Description
Description
Specifies whether or not the information is to be recorded in the Store database.
Specifiable value
Alphabetic characters
-
Yes: Record in the Store database
-
No: Do not record in the Store database
This value is not case sensitive.
Omissible
Yes (when the parameter is omitted, log is not updated.)
Attribute
None
Parent element
record
Child element
None
-
-
collection-interval
Type
Description
Description
Specifies the performance data collection interval (in seconds).
Specifiable value
Numeric value
0 to 2,147,483,647 (when 0 is specified, performance data is not collected)
Omissible
Yes (when the parameter is omitted, collection-interval is not updated)
Attribute
None
Parent element
record
Child element
None
-
collection-offset
Type
Description
Description
Specifies the delay in seconds for starting collection of performance data.
Specifiable value
Numeric value
0 to 32,767 (when 0 is specified, collection of performance data is started at the same time)
Omissible
Yes (when the parameter is omitted, collection-offset is not updated)
Attribute
None
Parent element
record
Child element
None
-
realtime-report-data-collection-mode
Type
Description
Description
Specifies the operation mode when the collection of historical data will be prioritized over the processing to display realtime reports#.
Specifiable value
Alphabetic characters
-
Reschedule: The re-schedule mode
-
Temporary Log: Temporary log mode
This value is not case sensitive.
Omissible
Yes (when the parameter is omitted, realtime-report-data-collection-mode is not updated)
Attribute
None
Parent element
Record
Child element
None
-
-
logif
Type
Description
Description
Specifies the checking condition for recording performance data in the Store database.
Specifiable value
None
Omissible
Yes (when the parameter is omitted, logif is not updated)
Attribute
delete
"yes" (When this attribute is specified, the command ignores the specified child elements and deletes the registered expression. If this attribute is omitted, the command registers the checking condition according to the specified child elements.)
Parent element
record
Child element
expression (can be specified more than once and can be omitted)
and (can be specified more than once if there is more than one expression, or can be omitted)
or (can be specified more than once if there is more than one expression, or can be omitted)
-
expression
Type
Description
Description
Specifies the checking condition for storing performance data in the Store database.
Specifiable value
Specifies the conditional expression in field condition"value" format. You cannot use a space as a delimiter for field, condition, and value.
-
You cannot specify a field on the right side.
-
If you want to specify multiple expression attributes, enclose only two of them at a time between <and> tags or <or> tags, which represent logical operators, and specify the attributes as a binomial. Nesting of binomials is allowed. You cannot specify a polynomial.
-
If you want to use an equality sign or an inequality sign other than in a condition, insert \ before the sign. If you want to use \, specify \ twice (\\).
field
Specify a field in the record. For field, specify the PFM - Manager name. For details about the PFM - Manager name, see the description of records in the applicable PFM - Agent or PFM - RM manuals.
condition
Specify one of the following as the condition value:
-
=: Field value is equal to "value".
-
<: Field value is less than "value".
-
<=: Field value is equal to or less than "value".
-
>: Field value is greater than "value".
-
>=: Field value is equal to or greater than "value".
-
<>: Field value is any value other than "value".
In XML, specify < for < and > for >.
Character string fields are compared in ascending order of ASCII codes.
"value"
Specify the value according to the field format described in the PFM - Agent or PFM - RM manuals. The permitted values are as follows:
-
Characters (specify as is)
-
Integer (specify a value in the range permitted for Integer)
-
Decimal value (specify a value in the range permitted for Double; more than 4 decimal places must be rounded to 4 decimal places according to IEEE 754: Standard for Floating-Point Arithmetic#)
-
Date (specify time in the format "HH:mm:ss")
The value cannot contain any control character or any of the symbols ( ) [ ] < > = ". If a control character or any of these symbols is specified, an error results.
Omissible
No
Attribute
None
Parent element
logif
and
or
Child element
None
-
-
and
Type
Description
Description
Specifies the AND operation of the logical expression specified in expression.
Specifiable value
None
Omissible
Yes
Attribute
None
Parent element
logif
and
or
Child element
expression (can be specified more than once or can be omitted)
and (can be specified more than once if there is more than one expression, or can be omitted)
or (can be specified more than once if there is more than one expression, or can be omitted)
-
or
Type
Description
Description
Specifies the OR operation of the logical expression specified in expression.
Specifiable value
None
Omissible
Yes
Attribute
None
Parent element
logif
and
or
Child element
expression (can be specified more than once or can be omitted)
and (can be specified more than once if there is more than one expression, or can be omitted)
or (can be specified more than once if there is more than one expression, or can be omitted)
An example of a parameter file is shown below.
Example of parameter file
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE pr-cli-parameters SYSTEM "asrec_params.dtd"> <pr-cli-parameters ver="0110"> <agent-store-db-record-definition> <service id="TA1host1"> <record id="PD_CIND"> <log>Yes</log> <collection-interval>60</collection-interval> <collection-offset>0</collection-offset> <realtime-report-data-collection-mode>Temporary Log</realtime-report-data-collection-mode> <logif> <and> <and> <expression>RECORD_TIME="10:26:50"</expression> <expression>UNIQUE_KEYS>="40"</expression> </and> <or> <expression>INSTANCE="abc"</expression> <expression>INSTANCE="xyz"</expression> </or> </and> </logif> </record> <record id="PD_CINF"> <log>Yes</log> <collection-interval>300</collection-interval> <collection-offset>10</collection-offset> <logif delete="yes"/> </record> <record id="PD_DEV"> <log>No</log> </record> </service> </agent-store-db-record-definition> </pr-cli-parameters>
Notes
-
The command requires authentication for PFM - Manager during execution. If a key file for authentication has not been created prior to command execution, use the jpcmkkey command to create the key file for authentication. For the specification value for each tag, see the notes on Settings for performance data collection in the PFM - Agent or PFM - RM manuals.
-
For details about the service ID, record ID, field names for each record ID, and permitted value ranges, see the PFM - Agent or PFM - RM manuals.
-
The parameters that can be changed depend on the service ID and record ID. For details, see the PFM - Agent or PFM - RM manuals.
-
Depending on the specified service ID or record ID, Sync Collection With applies to the record. In this case, neither Collection interval nor Collection offset can be specified. For details, see the PFM - Agent or PFM - RM manuals.
-
If the specified service ID is not for an agent product, an error results.
-
If the same service ID is specified more than once, an error results.
-
If the same record ID is specified more than once, an error results.
-
If multiple Store database recording method definitions are registered consecutively by service ID and the registration of any of the definitions fails, the command cancels the registration of that definition and registers the next definition by service ID, if any.
-
Only two elements can be specified under <and> and <or> tags in the <logif> tag.
The following shows an example:
<and> <expression>expression-1</expression> <or> <expression>expression-2</expression> <or> <expression>expression-3</expression> <or> <expression>expression-4</expression> <expression>expression-5</expression> </or> </or> </or> </and>
The following shows examples of expressions specified in the <expression> tag:
<expression>SEGMENTS_RETRANSMITTED_PER_SEC>"100"</expression> <expression>RECORD_TIME>"11:22:33"</expression>
-
Normally, you do not need to set the -mx or -ms option. If the KAVJK0401-E message, which reports insufficient memory, is output during command execution, re-execute the command with the -mx option to increase the maximum heap size. At this time, make sure that you specify 64 or a greater value for the -mx option.
Return values
0 |
The command terminated normally. |
1 |
The command line format is invalid. |
2 |
The user does not have execution permission for the command. |
3 |
Creation of the output file failed. |
5 |
The parameters cannot be analyzed because they do not match the DTD file. |
10 |
Updating of at least one Store database definition failed. |
11 |
Authentication processing for login to PFM - Manager failed. Alternatively, the user specified at authentication does not have execution permission. |
100 |
The environment is invalid. |
200 |
A memory error occurred. |
202 |
A file access error occurred. |
222 |
A communication processing error occurred. |
255 |
An unexpected error occurred. |
Usage example
This example specifies a parameter file (asrec_update.xml) that contains definition information about the Store database recording method:
jpcasrec update asrec_update.xml
Output example
This example outputs the details of the command's processing to the standard output, standard error output, and trace log file. For details about the log specifications, see Chapter 4. Log Information Output by Performance Management.
If three service IDs are specified and one of them results in an error, the standard output shown below is obtained. It displays the execution results (OK or ERR) for each service ID specified in the service tag.
Example of standard output
jpcasrec update connected to hostname at yyyy MM dd HH:MM:SS.mmm update result OK : TA1host1 update result OK : TA1host2 update result ERR : TA1host3 jpcasrec update disconnected at yyyy MM dd HH:MM:SS.mmm