jpcaspsv update
- Organization of this page
Format
jpcaspsv update [-mx maximum-heap-size] [-ms initial-heap-size] input-file-name
Function
The jpcaspsv update command connects to an agent and changes the definitions related to the storage conditions of the Store database. The command acquires the new storage condition definition information from the XML-format parameter file that is specified as a command line argument.
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-name
Specifies the XML-format parameter file that is to be used to change the Store database storage condition 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-preserve-definition
Type
Description
Description
Root tag for the Store database storage condition 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 S (Agent Store or Remote Monitor Store).
Parent element
agent-store-db-preserve-definition
Child element#
product-interval (can be specified only once per service or can be omitted)
product-detail (can be specified only once per service or can be omitted)
product-log (can be specified only once per service or can be omitted)
ex-product-interval (can be specified only once per service or can be omitted)
ex-product-detail (can be specified only once per service or can be omitted)
ex-product-log (can be specified only once per service or can be omitted)
-
product-interval
Type
Description
Description
Specifies the PI record retention period.
The condition for the target Store database is either of the following:
-
Version 08-00 or earlier
-
Version 08-11 or later and Store 1.0
Specifiable value
None
Omissible
Yes (when omitted, product-interval is not updated)
Attribute
None
Parent element
service
Child element#
minute-drawer (can be specified only once per product-interval or can be omitted)
hour-drawer (can be specified only once per product-interval or can be omitted)
day-drawer (can be specified only once per product-interval or can be omitted)
week-drawer (can be specified only once per product-interval or can be omitted)
month-drawer (can be specified only once per product-interval or can be omitted)
-
-
minute-drawer
Type
Description
Description
Specifies the PI record retention period in minutes.
Specifiable value
Alphanumeric characters that are not case sensitive.
Permitted values are as follows:
-
minute: 1 minute
-
hour: 1 hour
-
day: 1 day
-
n days: n days (n: 2 to 6)
-
week: 1 week
-
month: 1 month
-
year: 1 year
Omissible
Yes (when the parameter is omitted, minute-drawer is not updated)
Attribute
None
Parent element
product-interval
Child element
None
-
-
hour-drawer
Type
Description
Description
Specifies the PI record retention period in hours.
Specifiable value
Alphanumeric characters that are not case sensitive.
Permitted values are as follows:
-
hour: 1 hour
-
day: 1 day
-
n days: n days (n: 2 to 6)
-
week: 1 week
-
month: 1 month
-
year: 1 year
Omissible
Yes (when the parameter is omitted, hour-drawer is not updated)
Attribute
None
Parent element
product-interval
Child element
None
-
-
day-drawer
Type
Description
Description
Specifies the PI record retention period in days.
Specifiable value
Alphanumeric characters that are not case sensitive.
Permitted values are as follows:
-
day: 1 day
-
n days: n days (n: 2 to 6)
-
week: 1 week
-
month: 1 month
-
year: 1 year
Omissible
Yes (when the parameter is omitted, day-drawer is not updated)
Attribute
None
Parent element
product-interval
Child element
None
-
-
week-drawer
Type
Description
Description
Specifies the PI record retention period in weeks.
Specifiable value
Alphanumeric characters that are not case sensitive.
Permitted values are as follows:
-
week: 1 week
-
month: 1 month
-
year: 1 year
Omissible
Yes (when the parameter is omitted, week-drawer is not updated)
Attribute
None
Parent element
product-interval
Child element
None
-
-
month-drawer
Type
Description
Description
Specifies the PI record retention period in months.
Specifiable value
Alphanumeric characters that are not case sensitive.
Permitted values are as follows:
-
month: 1 month
-
year: 1 year
Omissible
Yes (when the parameter is omitted, month-drawer is not updated)
Attribute
None
Parent element
product-interval
Child element
None
-
-
product-detail
Type
Description
Description
Specifies the number of PD records that can be stored.
The condition for the target Store database is either of the following:
-
Version 08-00 or earlier
-
Version 08-11 or later and Store 1.0
Specifiable value
None
Omissible
Yes (when the parameter is omitted, product-detail is not updated)
Attribute
None
Parent element
service
Child element
detail-record (can be specified only once per PD record or can be omitted)
-
-
detail-record
Type
Description
Description
Specifies the maximum number of PD records that can be stored.
Specifiable value
None
Omissible
Yes (when the parameter is omitted, detail-record is not updated)
Attribute
id
PD record ID (for the record ID, see the PFM - Agent or PFM - RM manuals. This attribute cannot be omitted.)
max-rec
0 to 2,147,483,647 (cannot be omitted)
Parent element
product-detail
Child element
None
-
product-log
Type
Description
Description
Specifies the maximum number of PL records that can be stored.
The condition for the target Store database is either of the following:
-
Version 08-00 or earlier
-
Version 08-11 or later and Store 1.0
Specifiable value
None
Omissible
Yes (when the parameter is omitted, product-log is not updated)
Attribute
None
Parent element
service
Child element
log-record (can be specified only once per PL record or can be omitted)
-
-
log-record
Type
Description
Description
Specifies the maximum number of PL records that can be stored.
Specifiable value
None
Omissible
Yes (when the parameter is omitted, log-record is not updated)
Attribute
id
PL record ID (for the record ID, see the PFM - Agent or PFM - RM manuals. This attribute cannot be omitted.)
max-rec
0 to 2,147,483,647 (cannot be omitted)
Parent element
product-log
Child element
None
-
ex-product-interval
Type
Description
Description
Specifies the PI record retention period.
The condition for the target Store database is as follows:
-
Version 08-11 or later and Store 2.0
Specifiable value
None
Omissible
Yes (when the parameter is omitted, ex-product-interval is not updated)
Attribute
None
Parent element
service
Child element
ex-interval-record (can be specified only once per PI record or can be omitted)
-
-
ex-interval-record
Type
Description
Description
Specifies the PI record retention period.
Specifiable value
None
Omissible
Yes (when the parameter is omitted, ex-interval-record is not updated)
Attribute
id
PI record ID
For details about the PI record ID, see the PFM - Agent or PFM - RM manuals.
You cannot omit id.
Parent attribute
ex-product-interval
Child attribute#
minute-drawer-days (can be specified only once per ex-interval-record or can be omitted)
hour-drawer-days (can be specified only once per ex-interval-record or can be omitted)
day-drawer-weeks (can be specified only once per ex-interval-record or can be omitted)
week-drawer-weeks (can be specified only once per ex-interval-record or can be omitted)
month-drawer-months (can be specified only once per ex-interval-record or can be omitted)
-
minute-drawer-days
Type
Description
Description
Specifies the PI record retention period in minutes.
Specify the number of days. You can specify a maximum of 366 days (one year).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, minute-drawer-days is not updated)
Attribute
period
0 to 366 (cannot be omitted)
Parent element
ex-interval-record
Child element
None
-
hour-drawer-days
Type
Description
Description
Specifies the PI record retention period in hours.
Specify the number of days. You can specify a maximum of 366 days (a year).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, hour-drawer-days is not updated)
Attribute
period
0 to 366 (cannot be omitted)
Parent element
ex-interval-record
Child element
None
-
day-drawer-weeks
Type
Description
Description
Specifies the PI record retention period in days.
Specify the number of weeks. You can specify a maximum of 522 weeks (10 years).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, day-drawer-weeks is not updated)
Attribute
period
0 to 522 (cannot be omitted)
Parent element
ex-product-interval
Child element
None
-
week-drawer-weeks
Type
Description
Description
Specifies the PI record retention period in days.
Specify the number of weeks. You can specify a maximum of 522 weeks (10 years).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, week-drawer-weeks is not updated)
Attribute
period
0 to 522 (cannot be omitted)
Parent element
ex-product-interval
Child element
None
-
month-drawer-months
Type
Description
Description
Specifies the PI record retention period in months.
Specify the number of months. You can specify a maximum of 120 months (10 years).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, month-drawer-months is not updated)
Attribute
period
0 to 120 (cannot be omitted)
Parent element
ex-product-interval
Child element
None
-
ex-product-detail
Type
Description
Description
Specifies the PD record retention period.
The condition for the target Store database is as follows:
-
Version 08-11 or later and Store 2.0
Specifiable value
None
Omissible
Yes (when the parameter is omitted, ex-product-detail is not updated)
Attribute
None
Parent element
service
Child element
ex-detail-record (can be specified only once per PD record or can be omitted)
-
-
ex-detail-record
Type
Description
Description
Specifies the PD record retention period.
Specify the number of days. You can specify a maximum of 366 days (a year).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, ex-detail-record is not updated)
Attribute
id
PD record ID (for the record ID, see the PFM - Agent or PFM - RM manuals. You cannot omit this attribute.)
period
0 to 366 (cannot be omitted)
Parent element
ex-product-detail
Child element
None
-
ex-product-log
Type
Description
Description
Specifies the PL record retention period.
The condition for the target Store database is as follows:
-
Version 08-11 or later and Store 2.0
Specifiable value
None
Omissible
Yes (when the parameter is omitted, ex-product-log is not updated)
Attribute
Yes
Parent element
service
Child element
ex-log-record (can be specified only once per PL record or can be omitted)
-
-
ex-log-record
Type
Description
Description
Specifies the PL record retention period.
Specify the number of days. You can specify a maximum of 366 days (a year).
Specifiable value
None
Omissible
Yes (when the parameter is omitted, ex-log-record is not updated)
Attribute
id
PL record ID (for the record ID, see the PFM - Agent or PFM - RM manuals. You cannot omit this parameter.)
period
0 to 366 (cannot be omitted)
Parent element
ex-product-log
Child element
None
The following are examples of the parameter file.
Parameter file example (when the Store version is 1.0)
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE pr-cli-parameters SYSTEM "aspsv_params.dtd"> <pr-cli-parameters ver="0110"> <agent-store-db-preserve-definition> <service id="TS1host1"> <product-interval> <minute-drawer>day</minute-drawer> <hour-drawer>day</hour-drawer> <day-drawer>week</day-drawer> <week-drawer>month</week-drawer> <month-drawer>year</month-drawer> <!-- year-drawer : Year --> </product-interval> <product-detail> <detail-record id="PD" max-rec="30000"/> <detail-record id="PD_THRD" max-rec="30000"/> <detail-record id="PD_ADRS" max-rec="30000"/> <detail-record id="PD_PDI" max-rec="30000"/> <detail-record id="PD_PEND" max-rec="30000"/> </product-detail> <product-log> <log-record id="PL" max-rec="30000"/> <log-record id="RM" max-rec="30000"/> </product-log> </service> </agent-store-db-preserve-definition> </pr-cli-parameters>
Parameter file example (when the Store version is 2.0)
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE pr-cli-parameters SYSTEM "aspsv_params.dtd"> <pr-cli-parameters ver="0110"> <agent-store-db-preserve-definition> <service id="TS1host1"> <ex-product-interval> <ex-interval-record id="PI"> <minute-drawer-days period="10"/> <hour-drawer-days period="10"/> <day-drawer-weeks period="10"/> <week-drawer-weeks period="10"/> <month-drawer-months period="10"/> <!-- year-drawer-years period="10" --> </ex-interval-record> <ex-interval-record id="PI_LOGD"> <minute-drawer-days period="10"/> <hour-drawer-days period="10"/> <day-drawer-weeks period="10"/> <week-drawer-weeks period="10"/> <month-drawer-months period="10"/> <!-- year-drawer-years period="10" --> </ex-interval-record> </ex-product-interval> <ex-product-detail> <ex-detail-record id="PD" period="10"/> <ex-detail-record id="PD_THRD" period="10"/> <ex-detail-record id="PD_ADRS" period="10"/> <ex-detail-record id="PD_PDI" period="10"/> <ex-detail-record id="PD_PEND" period="10"/> </ex-product-detail> <ex-product-log> <ex-log-record id="PL" period="10"/> <ex-log-record id="RM" period="10"/> </ex-product-log> </service> </agent-store-db-preserve-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 and record ID, 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 storage condition definitions are registered consecutively and the registration of any of the definitions fails, the command cancels the registration of that definition and registers the next definition, if any.
-
The specifications of retention periods (minute-drawer through month-drawer) simply use different units; these specifications have no mutual relationships.
-
When the Store version is 1.0, the ex-product-interval tag, the ex-product-detail tag, and the ex-product-log tag are ignored if they are specified. When the Store version is 2.0, the product-interval tag, the product-detail tag, and the product-log tag are ignored if they are specified.
-
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 ended 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 (aspsv_update.xml) that contains definition information about the Store database storage conditions:
jpcaspsv update aspsv_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 6. Log Information Output by Performance Management.
In this example, three service IDs are specified and one of them results in an error, as shown in the standard output below. It displays the execution results (OK or ERR) for each service ID specified in the service tag.
Example of standard output
jpcaspsv update connected to hostname at yyyy MM dd HH:MM:SS.mmm update result OK : TS1host1 update result OK : TS1host2 update result ERR : TS1host3 jpcaspsv update disconnected at yyyy MM dd HH:MM:SS.mmm