jpcrdef output
- Organization of this page
Format
jpcrdef output -o output-file-name [-mx maximum-heap-size] [-ms initial-heap-size] [-dateformat date-format-pattern-name] [-dateseparator date-format-separator-name] [input-file-name | -parent report-definition-directory [-name report-definition-name]}
Function
The jpcrdef output command connects to PFM - Manager and outputs a report definition specified by the input-file-name option or the -parent option to a file in XML format. When a directory is specified for the input-file-name option or the -parent option, all the report definitions in the directory, including the report definitions in subdirectories, are output to one file. In addition, when the input-file-name option is specified, you can specify multiple paths or directories for output-file-name of the -o option. You can use the output file as the input to the jpcrdef create command.
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 or general 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
-o output-file-name
Specifies the output target file. When this option is omitted, an error results. 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. If the specified file already exists, the command overwrites the existing file. If the specified directory does not exist, an error results.
-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
-dateformat date-format-pattern-name
Specifies the name of the date format pattern that is used to identify the format of dates specified in the <expression> tag in the output file. The following date format pattern names can be specified:
-
pattern-ddMMyyyy
-
pattern-MMddyyyy
-
pattern-yyyyMMdd
-dateseparator date-format-separator-name
Specifies the character string that is used to identify the format of separators specified in the <expression> tag in the output file. The following date format separator names can be specified:
-
space
-
slash
-
hyphen
-
period
input-file-name
Specifies the XML-format parameter file that specifies the report definitions that are to be output. 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.
The input-file-name and -parent options are mutually exclusive.
-parent report-definition-directory
Specifies the directory where the output target report definition is found according to the following rules:
-
Specify a directory path in double-byte or single-byte characters from 1 to 64 characters (not in bytes) starting from the root directory, separated by /.
-
Enclose a value containing any space characters with double quotations (").
-
Use \\ or \/ when the directory name contains \ or /, in single-byte character, respectively.
-
Double-bytes and single-byte characters can be mixed for use.
-
An error occurs if a single-byte space character is added before and/or after a / that separates the directory path.
-
An error occurs if this option is specified together with the input-file-name option.
-name report-definition-name
Specifies the definition name of the output target report according to the following rules:
-
Specify a report definition name in double-byte or single-byte characters from 1 to 64 characters (not in bytes).
-
Enclose a value containing any space characters with double quotations (").
-
Use \\ or \/ when the report definition name contains \ or /, in single-byte character, respectively.
-
Double-bytes and single-byte characters can be mixed for use.
-
Delete any single-byte space characters added before or after the report definition name.
-
An error occurs if this option is specified together with the input-file-name option.
-
This option must be specified together with the -parent option.
-
When the -name option is omitted, the command outputs all the report definitions in the report definition directory specified by the -parent option to one file, including subdirectories.
Parameter file format
XML tag specifications
The examples in this subsection show how to write the parameter file. Parameter file samples are stored in the following directories. Use the samples as templates for writing parameter files.
- In Windows:
-
installation-directory\sample\conf\
- In UNIX:
-
/opt/jp1pcwebcon/sample/conf/
-
report-definitions
Type
Description
Description
Root tag for report definition information
Specifiable value
None
Omissible
No
Attribute
None
Parent element
pr-cli-parameters
Child element
report-definition
-
report-definition
Type
Description
Description
Specifies a single report definition.
Specifiable value
None
Omissible
No
Attribute
name
Specify a report definition name with 1 to 64 double-byte and/or single-byte characters (rather than 1 to 64 bytes). If the report definition name contains \ or /, specify it as \\ or \/, respectively. If the name attribute is omitted, the command outputs to a single file the report definition directory specified in parent-folder and all its subdirectories. If spaces are specified before and/or after the report definition name, the name is registered without the leading and/or trailing spaces.
parent-folder
Specify the name of the directory that contains the report definition specified in the name attribute. The name that you specify is a slash (/) separated path from the root directory. The path can have 1 to 64 double-byte and/or single-byte characters (rather than 1 to 64 bytes). If the parent-folder attribute is specified and the name attribute is omitted, the command outputs to a single file all report definitions contained in the report definition directory and its subdirectories. For a path, specify the directories sequentially separated by / starting from the highest-level directory. If the directory name contains \ or /, specify it as \\ or \/, respectively. An error results if spaces are specified before and/or after the directory name. This attribute cannot be omitted.
For example, to output the report definition named PD define located under the User Reports root directory, specify as follows:
<report-definition name="PD define" parent-folder="/"/>
The following example outputs to a file, all report definitions located in the Dir1 and Dir2 directories under the User Reports root directory:
<report-definition parent-folder="/Dir1/Dir2"/>
id
Outputs the identifier of the report definition (or directory for directory output). In the input file, this attribute is ignored if specified.
read-only
Outputs true for system definition and false for other than system definition. In the input file, this attribute is ignored if specified.
Parent element
report-definitions
Child element
product
Ignored, if specified.
report-type
record
indication-settings
view-type
drilldown
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 "rdef_output_params.dtd"> <pr-cli-parameters ver="0100"> <report-definitions> <report-definition name="Workload Status (Multi-Agent)" parent-folder="/"/> <report-definition name="CPU Usage Top 10 Processes" parent-folder="/" read-only="FALSE"/> <report-definition parent-folder="/Windows/Operating System"/> </report-definitions> </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.
-
If the output target is a report definition directory and an exception occurs while one of the report definitions in a subdirectory is being output, the command skips that report definition and processes the next report definition.
-
If multiple report definitions or report definition directories are specified as output targets and an exception occurs while one of the report definitions is being output, the command cancels that processing and outputs the next definition.
-
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 |
Creation of at least one report definition failed. |
11 |
Authentication processing for logging into PFM - Manager failed. |
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 1
The following shows an example of executing the command that outputs the parameter file containing the report definition (rdef_input.xml) specified by the input-file-name option to a file in XML format (rdef_output.xml):
jpcrdef output -o rdef_output.xml rdef_input.xml
Usage example 2
The following shows an example of executing the command that outputs the report definition specified by the -parent and -name options to a file in XML format (rdef_output.xml):
jpcrdef output -o rdef_output.xml -parent "/Windows/Operating System" -name "CPU Usage Top 10 Processes"
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.
An example is shown below of the standard output format when ten report definitions and five report definition directories were specified and three report definitions resulted in an error.
Example of standard output
jpcrdef output connected to vserv01 at 2006 03 20 15:00:55.282 output result OK : report-definition-directory-path-1/report-definition-name-11 output result OK : report-definition-directory-path-2/report-definition-name-21 output result ERR : report-definition-directory-path-3 Skipped : report-definition-directory-path-3/report-definition-name-31 cause-of-error OK : report-definition-directory-path-3/report-definition-name-32 Skipped : report-definition-directory-path-3/report-definition-name-33 cause-of-error OK : report-definition-directory-path-3/report-definition-name-34 OK : report-definition-directory-path-3/report-definition-name-35 output result ERR : report-definition-directory-path-4/report-definition-name-41 cause-of-error output result OK : report-definition-directory-path-5 OK : report-definition-directory-path-5/report-definition-name-51 OK : report-definition-directory-path-5/report-definition-name-52 jpcrdef output disconnected at 2006 03 20 15:01:06.2
Output file format
The specified attributes and the attributes set as the default settings are output to the file. The output command outputs a node ID as the id attribute of the report-definition tag. The create and delete commands ignore the id attribute specification.
You can use the output parameter file as the input file when you create report definitions. The output DTD file that defines the parameter descriptions is the same as the DTD file specified during creation. For examples of a parameter file that is output and a DTD file that defines parameter descriptions, see Example of parameter file (for historical report), and Example of parameter file (for realtime report) in the description of the jpcrdef create command.