jpctool db dump
- Organization of this page
Format
jpctool db dump -id service-ID [-host host-name] [-lhost logical-host-name] -stime start-date-and-time -etime end-date-and-time -f export-file-name -dbid database-ID -rec record-type [-localtime] [-proxy {y|n}] [-direct] [-alone]
Function
The jpctool db dump command exports data stored in the Master Store, Agent Store, or Remote Monitor Store service database to a text file. You execute an export for each database individually.
The default execution of this command creates the export file in the following dump directory:
-
When data stored in the Master Store service database is exported:
-
Windows: installation-folder\mgr\store\dump\
-
UNIX: /opt/jp1pc/mgr/store/dump/
-
-
When data stored in the Agent Store and Remote Monitor Store service database is exported:
-
Windows: installation-folder\xxxx#1\store[\instance-name]#2\dump\
-
UNIX: /opt/jp1pc/xxxx#1/store[/instance-name]#2/dump/
-
- #1
-
xxxx denotes the service key of a PFM - Agent or PFM - RM. For details about the service key, see the naming rules described in the appendix of the JP1/Performance Management Planning and Configuration Guide.
- #2
-
A directory with instance names is for a PFM - Agent or PFM - RM that monitors an application program that can start a set of multiple services at the same host.
The export file is created using the file name specified in the export-file-name option.
Hosts that can execute the command
-
PFM - Manager
-
PFM - Agent
-
PFM - RM
Execution permission
- In Windows:
-
None
- In UNIX:
-
None
Installation directory
- In Windows:
installation-folder\tools\
- In UNIX:
/opt/jp1pc/tools/
Arguments
-id service-ID
Specifies the service ID (whose second character is S) of the Master Store, Agent Store, or Remote Monitor Store service. For service-ID, specify a string of 1 to 258 bytes.
You can use a wildcard character to specify multiple service IDs. In this case, processing of the remaining services continues even if an error occurs on one service. If errors occur on multiple services, the command returns a value for the last error that occurred.
-host host-name
Specifies the name of the host where the Master Store, Agent Store, or Remote Monitor Store service is running. You use this argument to export data from a specific host. For host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters. An export data file is created on the host specified in this option. If you omit this option, the local host is assumed.
You can use a wildcard character to specify multiple host name.
-lhost logical-host-name
Specifies a logical host name if this command is to be executed by a host in a logical host environment, not in the physical host environment. For logical-host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters. If you omit this specification, the physical host is assumed. Wildcard characters cannot be used.
-stime start-date-and-time
Specifies the start date and time of the data that is to be exported, in the format YYYY/MM/DD hh:mm:
-
YYYY
Year, in the range 1970 to 2035.
-
MM
Month, in the range 01 to 12.
-
DD
Date, in the range 01 to 31.
-
hh
Hour, in the range 00 to 23.
-
mm
Minute, in the range 00 to 59.
The permitted range for date and time is from 1970/01/01 00:00 to 2035/12/31 23:59 GMT. If the -localtime option is omitted, the specified value is assumed to be GMT, in which case the permitted value range is from 1970/01/01 00:00 to 2035/12/31 23:59. If the -localtime option is specified, the specified local date and time must be within the equivalent GMT value range. For example, if the local time is Japan Standard time (GMT + 9), the permitted value range is from 1970/01/01 09:00 to 2036/01/01 08:59.
Make sure that the specified start time precedes the specified end time.
-etime end-date-and-time
Specifies the end date and time of the data that is to be exported, in the format YYYY/MM/DD hh:mm:
-
YYYY
Year, in the range 1970 to 2035.
-
MM
Month, in the range 01 to 12.
-
DD
Date, in the range 01 to 31.
-
hh
Hour, in the range 00 to 23.
-
mm
Minute, in the range 00 to 59.
The permitted range for date and time is from 1970/01/01 00:00 to 2035/12/31 23:59 GMT. If the -localtime option is omitted, the specified value is assumed to be GMT, in which case the permitted value range is from 1970/01/01 00:00 to 2035/12/31 23:59. If the -localtime option is specified, the specified local date and time must be within the equivalent GMT value range. For example, if the local time is Japan Standard time (GMT + 9), the permitted value range is from 1970/01/01 09:00 to 2036/01/01 08:59.
Make sure that the specified end time is subsequent to the specified start time.
-f export-file-name
Specifies the name of the export file. For export-file-name, specify a string of 1 to 31 bytes, consisting of alphanumeric characters and symbols (not including the directory name). However, the following symbols and the space cannot be specified:
/ \ : ; , * ? ' " < > |
If you specify any of the following symbols, you must enclose it in double quotation marks (") in order to avoid it from being analyzed by the shell or the command prompt:
& ^ ( ) `
If a file with the specified name already exists, it will be overwritten.
-dbid database-ID
Specifies the ID of the database from which the data is to be exported. The following are the specifiable database IDs:
-
PI: PI record-type Agent Store and Remote Monitor Store service database
-
PD: PD record-type Agent Store and Remote Monitor Store service database
-
PL: PL record-type Agent Store and Remote Monitor Store service database
-
PA: Master Store service database
-rec record-type
Specifies the record type of the data to be exported. For record-type, specify a string of 1 to 8 bytes, consisting of alphanumeric characters with no space characters. You can use a wildcard character to specify multiple record types.
For example, to export data from the Processor Overview (PI_PCSR) record of PFM - Agent for Platform (Windows), specify PCSR. For details about the record types, see the chapter in the PFM - Agent or PFM - RM manuals that describes records (list of records).
If the specified record type does not exist, the command creates an export file with a file size of 0 and then terminates itself normally.
-localtime
Specifies that the export start and end date and time are to be set to the time zone of the host that executes the command.
When this option is omitted, the command sets the export start and end date and time in GMT.
-proxy {y|n}
Specifies whether or not communication is to be through PFM - Manager in the case where a remote host is specified in the -host option in an environment in which direct communication with PFM - Agent or PFM - RM on the remote host cannot be performed.
When y is specified, the command checks the status of the target Store service through PFM - Manager. You use this option when direct communication with the Store service is not available, such as because of a firewall environment.
When n is specified, the command checks the status of the target Store service without going through PFM - Manager.
-direct
Specifies that export processing be executed on the database for the Master Store, Agent Store, or Remote Monitor Store service. If this option is specified, the Name Server and Master Manager services must be running. Additionally, the host where the command is executed must be able to communicate directly with the target Store service.
This option cannot be specified together with the -proxy or -alone option.
-alone
Specifies that export processing on the Master Store, Agent Store, or Remote Monitor Store service database is to be executed at the local host. The command cannot execute export processing on the Master Store, Agent Store, or Remote Monitor Store service database located at a remote host. When this option is specified, the command can execute export processing even if PFM - Manager is not running.
This option cannot be specified together with the -proxy, -direct, or -host option.
Information that is output to an export file
The following information is output to the export file:
-
Product information
-
Field names
-
Data
The following table describes the PA database fields that are output to the export file:
Field name |
Description |
---|---|
PA_NODE_NAME |
Sets the service ID of the agent that issued the event. |
PA_HOST_NAME |
Sets the host name of the agent that issued the event. |
PA_CURR_STATE |
Sets the event status:
|
PA_ALARM_NAME |
Sets an alarm name (n/a if it is not an alarm event). |
PA_ALARM_TABLE_NAME |
Sets an alarm table name (n/a if it is not an alarm event). |
PA_MESSAGE_TEXT |
Sets a message text for the event. |
For details about other fields, see the chapter in the PFM - Agent or PFM - RM manuals that describes records (list of records). Fields that are not described in the PFM - Agent or PFM - RM manuals are used for internal processing.
Disk space required to execute this command
This command creates a temporary file during execution. For the amount of disk space that is required to execute this command, see the appendix in the JP1/Performance Management Planning and Configuration Guide.
Notes
-
Arguments must be specified in the order that they appear in the description. Otherwise, they will not be recognized correctly.
-
This command cannot be executed in the following cases:
-
The Name Server service, Master Manager service, or the specified Master Store, Agent Store, or Remote Monitor Store service is stopped.
-
The data in the database of the specified Master Store, Agent Store, or Remote Monitor Store service is currently being backed up.
-
The data in the database of the specified Master Store, Agent Store, or Remote Monitor Store service is currently being exported.
-
-
If you execute multiple instances of the jpctool db backup or jpctool db dump command on separate hosts concurrently, make sure that you specify the -direct or -alone option. If these options are omitted, these commands cannot be executed concurrently. To execute backup or export processing more than once, make sure that the current command's processing is completed before executing the next command.
If you execute the jpctool db dump command without specifying the -direct or -alone option, do so on a single host, rather than on multiple hosts.
-
The jpctool db or jpctool service command permits use of wildcard characters in the service-ID and -host options. You can execute backup or export processing concurrently on multiple agents by using wildcard characters in the service-ID or -host option.
- Example: Execute the jpctool db backup command on multiple hosts
-
Of the data stored in the Instance (PD_PDI) record at the lhost02 host of PFM - Agent for Oracle (Windows) in a logical environment, this command specifies -alone and -direct to export to the pcsr.out file data covering the period from 2006-07-25 at 02:00 (GMT) to 2006-07-26 at 02:59 (GMT):
jpctool db dump -id "TS*" -host "*" -stime 2006/07/01 00:00 -etime 2006/07/31 00:00 -f PI.out -dbid PI -rec PCSR
-
After the command has been executed, if it is re-executed for the same Master Store, Agent Store, or Remote Monitor Store service with the same export file specified, the previous output results will be overwritten.
-
If the volume of data to be exported is large, export processing may take some time.
-
When you execute this command, if the temporary file that is created exceeds 2 GB, the data in the file cannot be exported. If the size of the temporary file exceeds 2 GB, export the data at different times or divide the records before exporting.
-
If the KAVE05234-E message is output, there was too much data to process and a timeout occurred. If this message is displayed often, take one of the following actions:
-
Narrow the time interval specified by start-date-and-time and end-date-and-time in the jpctool db dump command to reduce the amount of data to be exported.
-
Specify a specific record type, rather than a wildcard character, in the option of the jpctool db dump command.
-
-
If the jpctool db dump command is executed at multiple hosts and the KAVE05234-E message is output, specify the -direct or -alone option when you execute this command.
-
Historical reports might not be able to be displayed in PFM - Web Console for Agent Store and Remote Monitor Store services being exported. Request display of the historical report again after export processing is completed.
-
In the case of executing the jpctool db dump command with PA specified in the database-ID option, some of the characters in the export file will be garbled in the display. However, these are codes that are being used in internal processing, and there is no problem in actual operation.
-
Data items that are output to an export file, such as field names, are delimited by the stroke (|). Consequently, if the data to be output contains a field name or alarm name that contains the stroke character, it cannot be differentiated from the delimiter. Therefore, you should not use the stroke character in a field name or alarm name if you are going to use the jpctool db dump command to export data.
-
If command execution is interrupted by pressing the Ctrl + C keys or by a signal, a predefined return value is not returned. Therefore, you should ignore the return value when the command was interrupted by the Ctrl + C keys or by a signal.
-
GMT applies to an export file even when the -localtime option is specified in the jpctool db dump command.
-
Before you execute this command on a PFM - Agent or PFM - RM host, check whether the option for restricting remote operation from Agent hosts is enabled on the PFM - Manager host. If that option is enabled, you can export only data on the local host. If you specify a remote host by using the -host option, the command fails.
-
The contents of the export file are not sorted by any key. If the export file is used with a user program, the contents of the file might need to be sorted by date or other key. In such cases, sort the contents as required.
-
If you want to execute this command between hosts that use different types of Internet protocol, you must execute the command from PFM - Manager, by specifying the -proxy y option. If you do not specify this option, the command cannot export data.
-
You cannot execute this command with the -direct option between hosts that use different types of Internet protocol.
Return values
0 |
The command terminated normally. |
1 |
An argument specification is invalid. |
3 |
One or more of the specified services is not active. |
7 |
The specified service ID does not match Agent Store, Remote Monitor Store, or Master Store service. |
100 |
The Performance Management environment is invalid. |
101 |
Name Server service, Master Manager service, Master Store service, or the operation target service is not active. |
102 |
The specified logical host name has not been set up. |
104 |
The specified Master Store, Agent Store, or Remote Monitor Store service is engaged in backup or export processing. |
200 |
A memory shortage occurred. |
210 |
A disk space shortage occurred. |
211 |
Export file or directory cannot be accessed. |
220 |
A host name specified in the service configuration information file is invalid. |
222 |
A communication error occurred. |
223 |
A communication processing timeout error occurred. |
255 |
An unexpected error occurred. |
Usage example 1
Of the data stored in the Processor Overview (PI_PCSR) record at the host02 host of PFM - Agent for Oracle (Windows), this command exports to the pcsr.out file data covering the period from 2006-07-25 at 02:00 (GMT) to 2006-07-26 at 02:59 (GMT):
jpctool db dump -id TS* -host host02 -stime 2006/07/25 02:00 -etime 2006/07/26 14:59 -f pcsr.out -dbid PI -rec PCSR
Usage example 2
Of the data stored in the Instance (PD_PDI) record at the lhost02 host of PFM - Agent for Oracle (Windows) in a logical environment, this command specifies -alone and -direct to export to the pcsr.out file data covering the period from 2006-07-25 at 02:00 (GMT) to 2006-07-26 at 02:59 (GMT):
jpctool db dump -id OS* -lhost lhost02 -stime 2006/07/25 02:00 -etime 2006/07/26 14:59 -f pcsr.out -dbid PD -rec PDI -alone jpctool db dump -id OS* -lhost lhost02 -stime 2006/07/25 02:00 -etime 2006/07/26 14:59 -f pcsr.out -dbid PD -rec PDI -direct
Output example
Product information, field names, and data are output to an export file as shown below.
The stroke (|) is used as the delimiter between field names and between data items.
The following shows an output example: