Hitachi

JP1 Version 12 JP1/Performance Management Reference


jpcrpt

Organization of this page

Format

jpcrpt   -o output-file-name
         [ -mx maximum-heap-size]
         [ -ms initial-heap-size]
         [ -y ]
         [ -rc refresh-count]
         [ -ri refresh-interval]
         [ -dateformat date-format-pattern-name]
         [ -dateseparator date-format-separator-name]
         [ -exportseparator
         date-format-separator-name-during-report-output]
         [-agent service-ID [,service-ID]...]
         input-file-name

Function

The jpcrpt command outputs a report to a file in CSV format or HTML format. The command acquires the output definition from the XML-format parameter file specified as a command line argument. In the parameter file, you can specify the report output format, the report to be output, and the items equivalent to the items on the Show Options page in the View Report window or a combination report window. When reports are output in HTML format, the html-output tag needs to be set in the input file.

Note that the types of reports you can output by using the jpcrpt command differ depending on the version of PFM - Web Console. The following table lists which version of PFM - Web Console can output which types of reports.

Table 3‒37: Types of reports that can be output for each version of PFM - Web Console

Item to be output

08-00

08-11 or later

Report

CSV format

Yes

Yes

HTML format

No

Yes

Registered report

CSV format

No

Yes

HTML format

No

Yes

Combination report

HTML format

No

Yes

Legend: Yes: Can be output. No: Cannot be output.

You can specify one report in one parameter file. When the report to be output is a realtime report and you want to output it in CSV format, data is added at the end of the output file for the number of updates specified in the rc option at the update interval specified in the ri option. When you want to output a report in HTML format, an HTML file is output with the latest data available at the time that the command is executed. After the HTML file is output, data is not updated. When you specify output of a report in HTML format, the rc option and the ri option are ignored if specified.

If you specify multiple agents for a single-agent report, an error occurs.

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 name of the file to which the report is to be output. If you do not specify an output file name, an error occurs. Do not specify the following characters in the output file name:

# % < > & \

For output-file-name, you can specify the full file path name, a relative file path name, or a file name. For path names other than the full file path name, the current directory is the base. If the specified directory does not exist, an error occurs. If the same file is specified more than once, the system follows the specification of the -y option.

The report output format (CSV or HTML) is specified in the parameter file (XML file) specified as a command line argument. If CSV is specified, a single CSV file will be generated without a file name extension. If HTML is specified, a PNG-format graph image file might be generated in addition to an HTML file. For files generated when HTML is specified, file name extensions are added. When you specify HTML format, be careful that the name of the generated HTML file differs from the output file name that you specify as an argument. The following table describes the differences in the names of generated files between CSV and HTML.

Output format

Specified file name

Output file name

CSV

Output

output

output.csv

output.csv

HTML

output

output.htm

output.png

output.htm

output.htm.htm

output.htm.png

When you output a report in HTML format, if you specify a path containing the following characters for the output file path, the KAVJK0210-E message is displayed and command execution is canceled:

# % < > & \ "

-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

-y

Specifies that no confirmation message is to be displayed if the output file specified in the -o option already exists.

When the -y option is specified, the command overwrites the existing file without displaying the overwrite configuration message. When this option is omitted, the command displays an overwrite confirmation message. When y or Y is entered as the response to the deletion confirmation message, the command overwrites the existing file. When any other value is entered, the command cancels the processing.

-rc refresh-count

This option is applied to realtime reports. Specify the number of times that the reports are to be updated. You can specify a number from 1 to 2,147,483,647. If you omit this option, 1 is assumed. If you specify a number outside the range, an error occurs. If you specify this option for historical reports or HTML output, the option is ignored.

-ri refresh-interval

This option is applied to realtime reports. Specify the update interval for the reports. You can specify a number in the range from the minimum update interval specified when the report is specified to 3,600 seconds. If you omit this option, the initial update interval specified when the report is defined is assumed. If you specify a number outside the range, an error occurs. When the report display mode for realtime reports is set to the re-schedule mode, if you specify this option for historical reports or HTML output, the option is ignored.

-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-value>, <start-time>, <end-time>, and <baseline-start-time> tags in the input file. The specified date format pattern is also used to determine the date format 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 date separators specified in the <expression-value>, <start-time>, <end-time>, and <baseline-start-time> tags in the input file. The following date format separator names can be specified:

  • space

  • slash

  • hyphen

  • period

-exportseparator date-format-separator-name-during-report-output

Specifies the separator string used for the date format separator name in the output file. The following date format separator names can be specified:

  • space

  • slash

  • hyphen

  • period

-agent service-ID

Specifies the report output target agent, using the service ID of the Agent Collector service, remote agent, or group agent. An error will occur if the service ID of the Remote Monitor Collector service is specified. When the report definition report type is Historical (multiple agents), and multiple service IDs are specified, they can be separated with commas. In this case, processing is performed in the order starting from the service ID on the left. If duplicate service IDs are specified, the first one takes effect.

If this option is specified, any <agent> tag specified in the parameter file is ignored.

An error will occur if a non-existent service ID or service ID different from the report definition and product is specified. An error will occur if the report definition report type is not Historical (multiple agents), and multiple service IDs are specified. Note that this is ignored if specified for registration reports or combination reports.

input-file-name

Specifies the name of the input file that contains the definitions for displaying the report. The input file must be an XML-format parameter file created according to the Parameter file format described below. The input file name can be the absolute path or relative path. If the specified input file name is not the absolute path, the command assumes the current directory.

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/

Parameter file example (for outputting reports other than registered reports and combination reports)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-report>
    <agent>TA1htmprsvr</agent>
    <agent>TA1admin</agent>
    <report-definition name="CPU Trend" parent-folder="/Windows/Operating System/Monthly Trend">
      <launch-options>
        <indication-settings maximum-number-of-records="1440">
          <report-interval>HOUR</report-interval>
          <start-time>2007 08 10 12:00</start-time>
          <end-time>2007 08 11 12:00</end-time>
        </indication-settings>
      </launch-options>
      <html-output>
        <show-graph>
          <graph-options zoom-scale = "100">
            <show-3d/>
            <show-grid/>
            <vertical-axis minvalue="0" maxvalue="100"/>
          </graph-options>
        </show-graph>
        <show-table/>
      </html-output>
    </report-definition>
  </launch-report>
</pr-cli-parameters>

Parameter file example (for outputting registered reports)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-registration-report>
    <registration-report-definition report-name="CPU Usage@TA1host01"
      bookmark-name="CPU Usage"
      bookmark-parent-folder="/">
      <launch-options>
        <indication-settings maximum-number-of-records="1440">
          <date-range>WITHIN_THE_PAST_24_HOURS</date-range>
          <report-interval>HOUR</report-interval>
        </indication-settings>
      </launch-options>
      <html-output>
        <show-graph>
          <graph-options zoom-scale = "100">
            <show-grid/>
            <vertical-axis minvalue="0" maxvalue="100"/>
          </graph-options>
        </show-graph>
      <show-table/>
      </html-output>
    </registration-report-definition>
  </launch-registration-report>
</pr-cli-parameters>

Parameter file example (for outputting combination reports)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-combination-bookmark>
    <combination-definition bookmark-name="CPU Usage with Baseline" bookmark-parent-folder="/">
      <combination-options><combination-indication-settings>
        <date-range>WITHIN_THE_PAST_24_HOURS</date-range>
        <report-interval>HOUR</report-interval>
      </combination-indication-settings>
     </combination-options>
     <combination-graph-options zoom-scale="100" />
   </combination-definition>
  </launch-combination-bookmark>
</pr-cli-parameters>

Examples of date formats in tags that specify dates

Example 1

If you specify pattern-yyyyMMdd for the argument -dateformat and space for the argument -dateseparator, and specify MINUTE for report-interval, the tags that specify dates and times are specified in the format YYYY Δ MM Δ DD Δ hh:mm.

Example 2

If you specify pattern-yyyyMMdd for the argument -dateformat and slash for the argument -dateseparator, and specify MINUTE for report-interval, the tags that specify dates and times are specified in the format YYYY/MM/DD Δ hh:mm.

Example 3

If you specify pattern-yyyyMMdd for the argument -dateformat and hyphen for the argument -dateseparator, and specify MINUTE for report-interval, the tags that specify dates and times are specified in the format YYYY-MM-DD Δ hh:mm.

Example 4

If you specify pattern-yyyyMMdd for the argument -dateformat and period for the argument -dateseparator, and specify MINUTE for report-interval, the tags that specify dates and times are specified in the format YYYY.MM.DD Δ hh:mm.

Example 5

If you do not specify the -dateformat argument, the tags that specify dates and times are specified in the same format that is set for the locale in the OS.

  • Japanese: YYYY Δ MM Δ DD Δ hh:mm

  • English (USA): MM Δ DD Δ YYYY Δ hh:mm

  • Other than above: DD Δ MM Δ YYYY Δ hh:mm

Legend:

Δ: Single-byte space

YYYY: Year

MM: Month

DD: Day

hh: Hour

mm: Minute

  • launch-report

    Type

    Description

    Description

    Specifies the combination of report definitions and agents for output of a report.

    Specifiable value

    None

    Omissible

    Yes (launch-report, launch-registration-report, or launch-combination-bookmark must be specified)

    Attribute

    None

    Parent element

    pr-cli-parameters

    Child element

    agent (the element can be specified more than once)

    report-definition

  • agent

    Type

    Description

    Description

    Specifies a target agent for report output.

    Specifiable value

    Specifies the agent's Agent Collector service, or the service ID of a remote agent or a group agent. Note, however, that specifying one of the following service IDs results in an error:

    • Service ID of the Remote Monitor Collector service

    • Nonexistent service ID

    • Service ID that is assigned to multiple products

    • Service ID of an agent that the user who executes the command is not authorized to view

    If duplicate service IDs are specified, the service ID specified first takes effect. An error will occur when the report type specified for report-definition is not multi-agent, and multiple service IDs are specified.

    When this command is executed with the -agent option specified for PFM - Web Console 09-00 or later, the value specified for this tag is ignored. Likewise, if this tag is omitted, the -agent option needs to be specified during command execution.

    Omissible

    No

    Attribute

    None

    Parent element

    launch-report

    Child element

    None

  • report-definition

    Type

    Description

    Description

    Specifies a single report definition for report output.

    An error results in the following cases:

    • The product of the specified agent differs from the product of the specified report definition.

    • The data model version of the specified agent is not the same as or is newer than the data model version of the report definition.

    Specifiable value

    None

    Omissible

    No

    Attribute

    name

    Specify the name of a report definition to be output to a file, 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.

    Specifying a nonexistent report name results in an error. If this attribute is omitted, an error results.

    parent-folder

    Specify the directory path of the parent directory that contains the report definition specified in the name attribute. The directory path begins with /, followed by directory names arranged sequentially and separated by / starting from the highest-level directory. To specify the root directory, specify only /. If the directory name contains \ or /, specify it as \\ or \/, respectively. Specifying a nonexistent directory results in an error. If this attribute is omitted, an error results. An error also results if the specified directory path name ends in \ or /.

    Parent element

    launch-report

    Child element

    launch-options (can be specified only once per report-definition or can be omitted)

    html-output (can be specified only once per report-definition or can be omitted)

  • launch-options

    Type

    Description

    Description

    Specifies report acquisition conditions.

    Specifiable value

    None

    Omissible

    Yes (when the parameter is omitted, the parameter is not set)

    Attribute

    None

    Parent element

    report-definition, registration-report-definition

    Child element

    indication-settings (can be specified only once per launch-options or can be omitted)

    realtime-indication-settings (can be specified only once per launch-options or can be omitted)

    expression-values (can be specified only once per launch-options or can be omitted)

  • indication-settings

    Type

    Description

    Description

    Specifies the following values:

    • Report acquisition interval

    • Report interval

    • Start date and time

    • End date and time

    • Peak time

    • Maximum number of records

    An error results if this parameter is specified when the report type is Realtime (Single Agent) in the record definition.

    Specifiable value

    None

    Omissible

    Yes (including the child elements, the values in the report definitions are used)

    Attribute

    maximum-number-of-records

    Specify the maximum number of records to be acquired for the report, with an integer in the range 1 to 2,147,483,647. The permitted maximum is the value specified in maxFetchCount in the <command> tag in config.xml. If the specified value is greater than the maximum, the command uses the value of maxFetchCount. If the value of maxFetchCount in the <command> tag in config.xml is smaller than the value specified in the report definition, the command use the value of maxFetchCount.

    If this attribute is omitted, value in the report definition is used.

    Parent element

    launch-options

    Child element

    date-range (can be specified only once per indication-settings or can be omitted)

    start-time (can be specified only once per indication-settings or can be omitted)

    end-time (can be specified only once per indication-settings or can be omitted)

    report-interval (can be specified only once per indication-settings or can be omitted)

    peak-time (can be specified only once per indication-settings or can be omitted)

    exclude-terminal-data (can be specified only once per indication-settings or can be omitted)

  • date-range

    Type

    Description

    Description

    Specifies the report acquisition period.

    Specifiable value

    Specify one of the following values (which are not case sensitive):

    • For the past hour: WITHIN_THE_PAST_HOUR

    • For the past day (24 hours): WITHIN_THE_PAST_24_HOURS

    • For the past 7 days: WITHIN_THE_PAST_7_DAYS

    • For the past month: WITHIN_THE_PAST_MONTH

    • For the past year: WITHIN_THE_PAST_YEAR

    • For specifying the value when the report is displayed: SPECIFY_WHEN_DISPLAYED

    Omissible

    Yes (value in the report definition is used)

    Attribute

    None

    Parent element

    indication-settings, combination-indication-settings

    Child element

    None

  • report-interval

    Type

    Description

    Description

    Specifies the report interval.

    Specifiable value

    Specify one of the following values (which are not case sensitive):

    • For minutely: MINUTE

    • For hourly: HOUR

    • For daily (every 24 hours): DAY

    • For weekly: WEEK

    • For monthly: MONTH

    • For yearly: YEAR

    If you specify this parameter when you output a report or a registered report, and the records in the report definition are not PI records, an error occurs. If you specify this parameter for a combination report, no error occurs and only the PI records of the records to be output reference this value. When peak time is set in the report definition, peak time is invalidated for any value you specify other than HOUR.

    Omissible

    Yes (value in the report definition is used)

    Attribute

    None

    Parent element

    indication-settings, combination-indication-settings

    Child element

    None

  • start-time

    Type

    Description

    Description

    Specifies the start date and time.

    There are two ways to specify this: directly as an absolute time, and relatively using the child element <relative-time> tag.

    Specifiable value

    Specify the value in the format specified in report-interval. For reports for which report-interval cannot be specified, specify the start date and time in the format that is applied when MINUTE is specified for report-interval.

    An error occurs in the following cases:

    • The specified value is invalid.

    • The format is invalid.

    • The specified value is greater than end-time.

    • The specified year is before 1970 or after 2036.

    Omissible

    Depends on the combination of the date-range and end-time values. For details, see Notes.

    Attribute

    None

    Parent element

    indication-settings, combination-indication-settings

    Child element

    relative-time (this can only be specified once per start-time, and can be omitted.)

  • end-time

    Type

    Description

    Description

    Specifies the end date and time.

    There are two ways to specify this: directly as an absolute time, and relatively using the child element <relative-time> tag.

    Specifiable value

    Specify the value in the format specified in report-interval. For reports for which report-interval cannot be specified, specify the end date and time in the format that is applied when MINUTE is specified for report-interval.

    An error occurs in the following cases:

    • The specified value is invalid.

    • The format is invalid.

    • The specified value is smaller than start-time.

    • The specified year falls before 1970 or after 2036.

    Omissible

    Depends on the combination of the date-range and start-time values. For details, see Notes.

    Attribute

    None

    Parent element

    indication-settings, combination-indication-settings

    Child element

    relative-time (this can only be specified once per end-time, and can be omitted.)

  • peak-time

    Type

    Description

    Description

    Specifies the peak time.

    Specifiable value

    Specify the field ID of the field whose peak time value is to be used. If you specify NONE, the field ID specified in the report definition is ignored.

    If this parameter is specified when the report definition satisfies any of the following conditions, an error results:

    • The specified record is not a PI record.

    • A multi-instance record is specified.

    • report-interval is not set to HOUR.

    Omissible

    Yes (value in the report definition is used)

    Attribute

    None

    Parent element

    indication-settings

    Child element

    None

  • exclude-terminal-data

    Type

    Description

    Description

    Specifies whether to exclude the report start and end times in the report to be output.

    Specifiable value

    One of the values listed below can be specified. Uppercase and lowercase characters are not distinguished.

    • STARTTIME: The start time is not included in the report.

    • ENDTIME: The end time is not included in the report.

    • BOTHTIME: Both the start and end times are excluded from the report.

    • NONE: Both the start and end times are included in the report.

    Omissible

    Yes (If this element is omitted, the value of excludeTerminalData under the <command> tag in the config.xml initialization file is used. For details about the config.xml file, see Initialization file (config.xml).)

    Attribute

    None

    Parent element

    indication-settings, combination-indication-settings

    Child element

    None

  • realtime-indication-settings

    Type

    Description

    Description

    Specifies display by ranking for a realtime report.

    This parameter can be specified when the report type is Realtime (Single Agent) in the record definition. For any other report type, specifying this parameter results in an error.

    Specifiable value

    None

    Omissible

    Yes (the value in the report definition is used, including for child elements)

    Attribute

    indicate-delta-value

    Specify TRUE to collect delta values; otherwise, specify FALSE. If this attribute is omitted, the value in the report definition is used.

    Parent element

    launch-options

    Child element

    display-by-ranking (can be specified only once per realtime-indication-settings or can be omitted)

  • display-by-ranking

    Type

    Description

    Description

    Specifies the target field for ranking, the number of items to be obtained, and whether the order is descending or ascending.

    If this parameter is specified for a report definition for single-instance records, an error results.

    Specifiable value

    None

    Omissible

    Values in the report definition

    Attribute

    field

    Specify the field ID to be used as the basis for ranking.

    If ranking is not applicable, specify NONE (which is not case sensitive). If this attribute is omitted, an error results.

    display-number

    Specify the number of items to be obtained for ranking with an integer from 1 to 100. If the specified value is outside this range, an error results. If the field attribute is NONE, specifying display-number results in an error.

    If the field attribute is specified and the display-number attribute is omitted in this parameter, and the field attribute is specified in the report definition, the value in the report definition takes effect; if the field attribute is omitted in the report definition, 10 is assumed.

    in-descending-order

    The field used as the basis for display by ranking can be sorted in ascending or descending order and then as many items as specified in the display-number attribute can be displayed from the beginning.

    Specify TRUE to sort the field in ascending order and FALSE to sort in descending order.

    If the field attribute is NONE, specifying in-descending-order results in an error.

    If the field attribute is specified and the in-descending-order attribute is omitted in this parameter, and the field attribute is specified in the report definition, the value in the report definition takes effect; if the field attribute is omitted in the report definition, NONE is assumed. If the field attribute is omitted, FALSE is assumed.

    Parent element

    realtime-indication-settings

    Child element

    None

  • expression-values

    Type

    Description

    Description

    Specifies one or more conditional expressions.

    If this parameter is specified for a report that does not contain the conditional expression set in Specify when displayed, an error results.

    Specifiable value

    None

    Omissible

    Yes (when the parameter is omitted, the parameter is not set)

    Attribute

    None

    Parent element

    launch-options

    Child element

    expression-value (this element can be specified more than once)

  • expression-value

    Type

    Description

    Description

    Specifies a conditional expression value.

    Specifiable value

    Specify a value for the expression on the line specified by the pos attribute.

    You can specify an integer, a decimal value, or a character string of up to 2,048 bytes.

    Omissible

    Yes (if expression-values is specified, the parameter cannot be omitted)

    Attribute

    pos

    Specify the order in which the simple expression for which Specify when displayed has been set in the conditional expression appears as an integer beginning at 0. The order of appearance matches the display order in the conditional expression displayed in the Report Display Settings window. The value of pos for the conditional expression displayed first in the Report Display Settings window is 0, and the value of pos for the conditional expression displayed third in the Report Display Settings window is 2.

    The permitted value range is from 0 to the number of simple expressions for which Specify when displayed has been set -1.

    If pos is omitted in the first expression-value tag, the value of this attribute is 0. If it is omitted in any other expression-value tag, the value of this attribute is the value of the previous pos + 1.

    The same value can be specified more than once in pos. In this case, the last value specified takes effect.

    If the specified value is outside the permitted range, an error results.

    Parent element

    expression-values

    Child element

    relative-time (this can only be specified once per expression-value, and can be omitted.)

  • html-output

    Type

    Description

    Description

    Outputs reports in HTML format. For details on the display format of output reports, see Output files.

    When outputting reports in HTML format, one of the following display formats is available by specifying it as a child element:

    • Graph display

    • Table display

    If a child element is omitted, only the report definition name of the header part is displayed.

    Specifiable value

    None

    Omissible

    If this tag is omitted, reports are output in CSV format.

    Attribute

    None

    Parent element

    report-definition, registration-report-definition

    Child element #

    show-graph (can be specified only once per html-output or can be omitted)

    show-table (can be specified only once per html-output or can be omitted)

    #: If you specify child elements, specify them in the order listed above.

  • show-graph

    Type

    Description

    Description

    Displays graphs in the report to be output. To display graphs, set graph display in the report definition and specify this tag. No error occurs if the report definition is invalid or the tag is invalid. However, no graph is displayed in the report. Use the child element to specify the graph options in the report. If you do not specify a child element, graphs are displayed with the default settings.

    Specifiable value

    None

    Omissible

    If this tag is omitted, no graph is displayed in the report.

    Attribute

    None

    Parent element

    html-output

    Child element

    graph-options (can be specified only once per show-graph or can be omitted)

  • graph-options

    Type

    Description

    Description

    Changes the settings of the graph options. Depending on the specified child element, you can change the settings of the following items:

    • Display in 3D

    • Display of grids

    • Manual setting of the maximum and minimum values of the vertical axis

    Specifiable value

    None

    Omissible

    If this tag is omitted, 3D display is disabled, grids are not displayed, and the maximum and minimum values of the vertical axis are automatically set.

    Attribute

    zoom-scale

    Specify the magnification of graphs. You can select 100, 200, 400, 600, or 800. If you omit this attribute, 100 is assumed. If you specify an invalid value, an error occurs.

    Parent element

    show-graph

    Child element #

    show-3d (can be specified only once per graph-options or can be omitted)

    show-grid (can be specified only once per graph-options or can be omitted)

    vertical-axis (can be specified only once per graph-options or can be omitted)

    #: If you specify child elements, specify them in the order listed above.

  • show-3d

    Type

    Description

    Description

    Displays graphs in 3D. However, an error results if the graph type is line or area graph. Stacked area graphs are displayed in 2D.

    Specifiable value

    None

    Omissible

    If this tag is omitted, graphs are displayed in 2D.

    Attribute

    None

    Parent element

    graph-options

    Child element

    None

  • show-grid

    Type

    Description

    Description

    Displays grids in graphs. However, an error results if the graph type is pie graph.

    Specifiable value

    None

    Omissible

    If this tag is omitted, grids are not displayed.

    Attribute

    None

    Parent element

    graph-options

    Child element

    None

  • vertical-axis

    Type

    Description

    Description

    Specifies the range of the vertical axis in a graph displayed in a report. However, an error results if the graph type is pie graph.

    Specifiable value

    None

    Omissible

    If this tag is omitted, the range of the vertical axis is automatically set based on the data in the graph.

    Attribute

    minvalue

    Use a real number to specify the minimum value for the vertical axis. You can specify a value from -1.797E308 to 1.797E308. If you omit this attribute or minvalue is greater than maxvalue, an error occurs.

    maxvalue

    Use a real number to specify the maximum value for the vertical axis. You can specify a value from -1.797E308 to 1.797E308. If you omit this attribute or minvalue is greater than maxvalue, an error occurs.

    Parent element

    graph-options

    Child element

    None

  • show-table

    Type

    Description

    Description

    Displays tables in the report to be output. To display tables, set table display in the report definition and specify this tag. No error occurs if the report definition is invalid or this tag is invalid. However, no table is displayed in the report.

    Specifiable value

    None

    Omissible

    If this tag is omitted, no table is displayed in the report.

    Attribute

    None

    Parent element

    html-output

    Child element

    None

  • launch-registration-report

    Type

    Description

    Description

    Specifies a registered report under a bookmark (including combination bookmarks) in the bookmarks tree.

    Specifiable value

    None

    Omissible

    Yes (launch-report, launch-registration-report, or launch-combination-bookmark must be specified)

    Attribute

    None

    Parent element

    pr-cli-parameters

    Child element

    registration-report-definition

  • registration-report-definition

    Type

    Description

    Description

    Specifies one registered report to be output.

    Specifiable value

    None

    Omissible

    Yes (cannot be omitted when launch-registration-report is specified)

    Attribute

    bookmark-name

    Specify the name of the bookmark (including a combination bookmark) storing the registered report to be output to a file. If the bookmark name contains \ or /, specify it as \\ or \/, respectively. If you specify a nonexistent bookmark, or if you omit this attribute, an error occurs.

    report-name

    Specify the name of the registered report to be output to a file. To include \ or / in the report name, specify it as \\or \/, respectively. If you specify a registered report that does not exist in the bookmark specified in the bookmark-name attribute or if you omit this attribute, an error occurs.

    Note: If multiple registered reports that have the same name are defined under the same bookmark, the command outputs the first registered report encountered in the output definition that the command acquires from the parameter file.

    bookmark-parent-folder

    Use a directory path to specify the parent directory of the bookmark specified in the bookmark-name attribute. The directory path must begin with / and the directory names must be delimited by using /. If you want to specify the root directory, specify / only. If the directory name contains \ or /, specify it as \\ or \/, respectively. If you specify a nonexistent directory or if you omit this attribute, an error occurs. An error also occurs if you write \ or / at the end of the directory path name.

    Parent element

    launch-registration-report

    Child element #

    launch-options (can be specified only once per registration-report-definition or can be omitted)

    html-output (this can only be specified once per registration-report-definition, and can be omitted.)

    #: If you specify child elements, specify them in the order listed above.

  • launch-combination-bookmark

    Type

    Description

    Description

    Specifies a combination bookmark in the bookmarks tree.

    Specifiable value

    None

    Omissible

    Yes (launch-report, launch-registration-report, or launch-combination-bookmark must be specified)

    Attribute

    None

    Parent element

    pr-cli-parameters

    Child element

    combination-definition

  • combination-definition

    Type

    Description

    Description

    Specifies one combination bookmark that is to be output as a report.

    Specifiable value

    None

    Omissible

    Yes (cannot be omitted when launch-combination-bookmark is specified)

    Attribute

    bookmark-name

    Specify the name of the combination bookmark whose registered report is to be output to a file. When the bookmark name contains \ or /, specify it as \\ or \/, respectively. If you specify an nonexistent bookmark or a bookmark that is not a combination bookmark or if you omit this attribute, an error occurs.

    bookmark-parent-folder

    Use a directory path to specify the parent directory of the bookmark specified in the bookmark-name attribute. The directory path must begin with / and the directory names must be delimited by using /. If you want to specify the root directory, specify / only. If the directory name contains \ or /, specify it as \\ or \/, respectively. If you specify a nonexistent directory or if you omit this attribute, an error occurs. An error also occurs if you write \ or / at the end of the directory path name.

    Parent element

    launch-combination-bookmark

    Child element #

    combination-options (can be specified only once per combination-definition or can be omitted)

    combination-graph-options (can be specified only once per combination-definition or can be omitted)

    #: If you specify child elements, specify them in the order listed above.

  • combination-graph-options

    Type

    Description

    Description

    Specifies one of the combination bookmarks to be included in the report.

    Specifiable value

    None

    Omissible

    Yes (The graph zoom scale is set to 100 (%).)

    Attribute

    zoom-scale

    Specifies the graph zoom scale. 100, 200, 400, 600, or 800 can be specified as the value. The default is 100. Specifying an invalid value results in an error.

    Parent element

    combination-definition

    Child element

    None

  • combination-options

    Type

    Description

    Description

    Specifies options for the output of a combination report. Note that the baseline display setting is specified by the child element.

    Specifiable value

    None

    Omissible

    If this tag is omitted, display options for the combination report are not set.

    Attribute

    None

    Parent element

    combination-definition

    Child element #

    combination-indication-settings (can be specified only once per combination-options or can be omitted)

    baseline-indication-settings (can be specified only once per combination-options or can be omitted)

    #: If you specify child elements, specify them in the order listed above.

  • combination-indication-settings

    Type

    Description

    Description

    Specifies the report acquisition period, report interval, start time, and end time for a combination report.

    Specifiable value

    None

    Omissible

    If this tag is omitted, the values in the report definition are applied including the values that are specified using the child elements.

    Attribute

    None

    Parent element

    combination-options

    Child element

    date-range (can be specified only once per combination-indication-settings or can be omitted)

    start-time (can be specified only once per combination-indication-settings or can be omitted)

    end-time (can be specified only once per combination-indication-settings or can be omitted)

    report-interval (can be specified only once per combination-indication-settings or can be omitted)

    exclude-terminal-data (can be specified only once per combination-indication-settings or can be omitted)

  • baseline-indication-settings

    Type

    Description

    Description

    Specifies the display start position for the baseline in a combination report. Note that the baseline display start position is specified by the child element.

    Specifiable value

    None

    Omissible

    If this tag is omitted, the default setting (start date and time of the report) is used as the start position for the baseline.

    Attribute

    None

    Parent element

    combination-options

    Child element

    baseline-start-time

  • baseline-start-time

    Type

    Description

    Description

    Specifies the display start position for the baseline in a combination report.

    There are two ways to specify this: directly as an absolute time, and relatively using the child element <relative-time> tag.

    Specifiable value

    Use the format specified in report-interval to specify the position. For reports for which report-interval cannot be specified, specify the display start position in the format to be applied when MINUTE is specified for report-interval.

    An error occurs in the following cases:

    • The specified value is invalid.

    • The format is invalid.

    • The specified value is greater than end-time.

    • The specified year is before 1970 or after 2036.

    Omissible

    Yes (cannot be omitted when baseline-start-time is specified)

    Attribute

    None

    Parent element

    baseline-indication-settings

    Child element

    relative-time (this can only be specified once per baseline-start-time, and can be omitted.)

  • relative-time

    Type

    Description

    Description

    Specifies a base time or relative time from the base time.

    The base time is the local time for the PFM - Web Console host, and is specified by the origin attribute, by selecting the command execution time, or command execution hour, day, week, month, or year from the start time. Since the optional year, month, week, day, hour, and minute attributes can be specified in combination, a relative time from the base time can be specified.

    An error will occur if the year of the last calculated time is earlier than 1970 or later than 2036.

    Specifiable value

    None

    Omissible

    If this is omitted, the absolute time needs to be specified according to the parent element format.

    Attribute

    origin

    Specifies the base time, command execution time, or hour, day, week, month, or year for the start time.

    • NOW or now

      The time the command is executed

    • THIS-HOUR or this-hour

      The first minute of the hour the command is executed

    • THIS-DAY or this-day

      The first hour and minute of the time the command is executed

    • THIS-WEEK or this-week

      The first hour and minute of the first day of the week the command is executed

    • THIS-MONTH or this-month

      The first minute, hour, and day of the month the command is executed

    • THIS-YEAR or this-year

      The first minute, hour, day, and month of the year the command is executed

    An error will occur if a value other than the above is specified, or the value is omitted.

    The default start day differs depending on the locale of the environment on which the command is executed. The default start day is Sunday in Japan and the US. The start day can be changed optionally using the firstDayOfWeek parameter in config.xml.

    year

    Specifies a relative number of years from the base time. This is 0 by default. In attributes indicating a relative value, this is evaluated first. An error will occur if the year of the last calculated time is earlier than 1970 or later than 2036.

    month

    Specifies a relative number of months from the base time. This can be from -12 to 12. This is 0 by default. This is evaluated after the year attribute.

    week

    Specifies a relative number of weeks from the base time. This can be from -53 to 53. This is 0 by default. This is evaluated after the month attribute.

    day

    Specifies a relative number of days from the base time. This can be from -366 to 366. This is 0 by default. This is evaluated after the week attribute.

    hour

    Specifies a relative number of hours from the base time. This can be from -24 to 24. This is 0 by default. This is evaluated after the day attribute.

    minute

    Specifies a relative number of minutes from the base time. This can be from -60 to 60. This is 0 by default. This is evaluated after the hour attribute.

    Parent element

    start-time, end-time, expression-value, baseline-start-time

    Child element

    None

Notes

Return values

0

The command terminated normally.

1

Command line format is invalid.

2

The user does not have execution permission for the command.

4

The range specified in -rc or -ri option is invalid.

5

A parameter cannot be analyzed because it does not conform to a DTD file.

6

An invalid DTD file was specified.

10

A value specified in the input file is invalid.

11

PFM - Manager authentication processing failed.

21

An output file cannot be accessed.

70

Processing to acquire a report has timed out.

80

The user rejected overwriting.

100

Initialization failed due to invalid Performance Management environment.

200

A memory shortage occurred.

202

An input file cannot be accessed.

220

Access to PFM - Manager failed.

222

Connection to PFM - Manager failed.

223

A communication error occurred.

224

Connection to PFM - Manager or PFM - RM failed.

229

An error occurred at PFM - Manager for the connection destination.

255

An unexpected error occurred.

Usage example

This example outputs to the output.csv file the parameter file param.xml that contains report output definitions:

jpcrpt -o output.csv -y param.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.

An example is shown below of the standard output format. It displays the execution results of the report output specified in the arguments.

Example of standard output (when the processing is successful)

jpcrpt connected to hostname at dd MM yyyy HH:MM:SS.mmm
result  OK  : report-definition-directory-path/report-definition-name@agent-ID
jpcrpt disconnected at dd MM yyyy HH:MM:SS.mmm

Output files

An output file consists of the data header section and other sections. Output of the data header can be enabled and disabled by using outputCsvHeader under the <command><export> tag in the initialization file (config.xml).

Outputting the contents of a report in CSV format

A report in CSV format consists of the data header section and the data section.

The following table describes the information that is displayed in the data header of the file that is output by this command:

Table 3‒41: Information displayed in data header

Data header information

Information that is output

Report:

Absolute path of the report name

Agents:

Agent name. Regardless of the product name display functionality settings, this is always output in a format with the product name display functionality disabled.

Date Format:

Date format and separator

Command:

Option information in the order specified.

null line

None

Column heading

Field's column heading.

This is the schema name of the field. However, if Display name has been set for the field during definition, that Display name is displayed.

For details, see the chapter describing how to create reports to analyze data in the JP1/Performance Management User's Guide.

An example is shown below of a file output by this command. If the resulting count is 0 or the agent is stopped, the data section is not displayed, in which case only the data header section is displayed. However, if the output of the data header is disabled by using outputCsvHeader under the <command><export> tag in the initialization file (config.xml), nothing is output.

Example of output file when the contents of a report are output in CSV format

Report: /Windows/Troubleshooting/RecentPast/System Overview
Agents: TA1htmprsvr
Date Format: pattern-yyyyMMdd,slash
Command:jpcrpt -input C:\ProgramFiles\Hitachi\jp1pcwebCon\
        param.xml,-o C:\ProgramFiles\Hitachi\jp1pcwebCon\
        output.csv,-y
 
Agent Host,Agent Instance,Date and Time,CPU %,User CPU %,
Privileged CPU %,Processor Queue Length,Context Switches/sec,
               % Total Interrupt Time,System Calls/sec
htmprsvr,htmprsvr,2006/07/03 09:00:00,10.910626,8.917643,
                1.9929985,4,825.3214,0.040342055,3351.263
htmprsvr,htmprsvr,2006/07/03 10:00:00,10.646775,9.116808,
                1.5356027,5,778.178,0.009959743,3238.7776
htmprsvr,htmprsvr,2006/07/03 11:00:00,11.603203,9.505386,
                2.0978165,3,809.5369,0.036344547,3257.031
htmprsvr,htmprsvr,2006/07/03 12:00:00,2.2210534,0.8610586,
                1.3599948,2,744.3879,0.0121342335,3597.5398
htmprsvr,htmprsvr,2006/07/03 13:00:00,2.2657635,1.1398388,
                1.1259354,3,675.37067,0.024730453,2883.5593
htmprsvr,htmprsvr,2006/07/03 14:00:00,10.394524,8.527414,
                1.8726714,4,817.1143,0.009072154,3453.1233

Outputting the contents of a report in HTML format

A report in HTML format consists of a report header, graphs, and tables.

For details about each part output and the output conditions, see the chapter describing how to create reports to analyze data in the JP1/Performance Management User's Guide.

If there are no items or if the agent is inactive, only the report header is output. However, if the output of the data header is disabled by using outputCsvHeader under the <command><export> tag in the initialization file (config.xml), nothing is output.

HTML documents are output in UTF-8. The character encoding and linefeed settings in the Export format in config.xml are not applied.

Note that the agent name output in the report header section is always output in a format with the product name display functionality disabled, regardless of the product name display functionality settings.

Example of report execution by relative time specification

By using relative time specifications and creating reports regularly, the efficiency of acquisition periods can be increased. The following shows an example parameter file using relative time specification. Note that relative time specifications can only be used for PFM - Web Console 09-00 or later.

Example 1

The following performs report execution every 24 hours (00:00 to 24:00). Note that the jpcrpt command is executed the next day from 00:00 to 24:00.

  • Agent: TA1host1

  • Report definition: /Folder1/ReportA

  • Acquisition period: One day starting from the day before the jpcrpt command is executed

  • Sample parameter file name: jpcrpt-parameters-for-scheduled-operation1.xml

Edit the bold characters in the sample parameter file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-report>
    <agent>TA1host1</agent>
    <report-definition name="ReportA" parent-folder="/Folder1">
      <launch-options>
        <indication-settings>
          <report-interval>HOUR</report-interval>
           <start-time>
             <relative-time origin="THIS-DAY" day="-1"/>
           </start-time>
           <end-time>
             <relative-time origin="THIS-DAY"/>
           </end-time>
        </indication-settings>
      </launch-options>
    </report-definition>
  </launch-report>
</pr-cli-parameters>

In the above example, THIS-DAY is specified for the origin attribute of both the <start-time> tag and <end-time> tag, and 0:00 of the day of jpcrpt command execution is used as the base time. -1 is specified for the day attribute of the <start-time> tag, and goes back one day from then. This means that the 0:00 of the previous day is specified as the acquisition period start time, and 0:00 of this day is specified as the acquisition period end time. When a PI record is to be output, the interval for which reports are output is specified using the <report-interval> tag.

Example 2

The following performs report execution everyday from 8:30 to the next day at 5:00. Note that the jpcrpt command is executed from 5:00 to 8:30 the next day.

  • Agent: TA1host1

  • Report definition: /Folder1/ReportA

  • Acquisition period: From 8:30 the day before the jpcrpt command is executed until the current day at 5:00

  • Sample parameter file name: jpcrpt-parameters-for-scheduled-operation2.xml

Edit the bold characters in the sample parameter file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-report>
    <agent>TA1host1</agent>
    <report-definition name="ReportA" parent-folder="/Folder1">
      <launch-options>
        <indication-settings>
          <report-interval>MINUTE</report-interval>
           <start-time>
             <relative-time origin="THIS-DAY" day="-1" hour="8" minute="30"/>
           </start-time>
           <end-time>
             <relative-time origin="THIS-DAY" hour="5"/>
           </end-time>
        </indication-settings>
      </launch-options>
    </report-definition>
  </launch-report>
</pr-cli-parameters>

As shown in example 1, settings can be set in detail by using hours and minutes. When the <start-time> is set to 8:30 on the previous day, and the day attribute is not specified, but the hour attribute is set to -15 and the minute attribute is set to -30, the results are the same. However, as shown in this example, setting the day attribute 1 day back and then setting the hour attribute and minute attribute from there helps create an easy-to-read definition. When a PI record is to be output, the interval for which reports are output is specified using the <report-interval> tag.

Example 3

The following performs report execution every week from Monday to Friday (the last day). Note that the jpcrpt command is batch executed on the following Saturday.

  • Agent: TA1host1

  • Report definition: /Folder1/ReportA

  • Acquisition period: From Monday to Friday (including 24:00 on Friday (0:00 on Saturday)), the day of the week that the jpcrpt command is executed

  • Sample parameter file name: jpcrpt-parameters-for-scheduled-operation3.xml

Edit the bold characters in the sample parameter file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-report>
    <agent>TA1host1</agent>
    <report-definition name="ReportA" parent-folder="/Folder1">
      <launch-options>
        <indication-settings>
          <report-interval>DAY</report-interval>
           <start-time>
             <relative-time origin="THIS-WEEK" day="1"/>
           </start-time>
           <end-time>
             <relative-time origin="THIS-WEEK" day="6"/>
           </end-time>
        </indication-settings>
      </launch-options>
    </report-definition>
  </launch-report>
</pr-cli-parameters>

When the origin attribute is set to THIS-WEEK, the base time is the start day for the week, at 0:00. In Japan, the start day of the week is set to Sunday by default. In the above example, therefore, the day attribute under <start-time> is set to +1 so that 0:00 on Monday is set as the start time. Similarly, the day attribute under <end-time> is set to +6 so that 0:00 on Saturday (24:00 on Friday) is set as the end time. This will get the same results as setting the day attribute to +5 and the hour attribute to +24 for the <end-time>.

Note that if execution of the jpcrpt command shifts to Sunday, since the base time will shift into the next week, the week attribute might need to be set to -1.

When a PI record is to be output, the interval for which reports are output is specified using the <report-interval> tag.

Example 4

The following performs monthly report execution every month starting on the 25th at 22:00. However, because the time needed for monthly processing might vary, the end time might cross over to the 26th. As such, execute the jpcrpt command immediately after monthly processing completes.

  • Agent: TA1host1

  • Report definition: /Folder1/ReportA

  • Acquisition period: From 22:00 on the 25th of the month the jpcrpt command is executed, until just before the command is executed

  • Sample parameter file name: jpcrpt-parameters-for-scheduled-operation4.xml

Edit the bold characters in the sample parameter file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-report>
    <agent>TA1host1</agent>
    <report-definition name="ReportA" parent-folder="/Folder1">
      <launch-options>
        <indication-settings>
          <report-interval>MINUTE</report-interval>
           <start-time>
             <relative-time origin="THIS-MONTH" day="24" hour="22"/>
           </start-time>
           <end-time>
             <relative-time origin="NOW"/>
           </end-time>
        </indication-settings>
      </launch-options>
    </report-definition>
  </launch-report>
</pr-cli-parameters>

The following shows an example specification for monthly report execution. The end time is NOW, the command execution time. To keep the start time from shifting, the base time is set to THIS-MONTH instead of THIS-DAY. One thing to keep in mind about specifying THIS-MONTH and the day attribute together is that since THIS-MONTH indicates the first day of the current month, when the 25th day of the current month is specified relatively, the day attribute needs to be set to +24. For the same reason, please pay attention to the month attribute and day attribute values when specified with THIS-YEAR. When a PI record is to be output, the interval for which reports are output is specified using the <report-interval> tag.

Example 5

The following performs quarterly (3-month) report execution. The jpcrpt command is executed the next month after each quarter, in April, July, October, and January.

  • Agent: TA1host1

  • Report definition: /Folder1/ReportA

  • Acquisition period: From 3 months before the jpcrpt command is executed until the month before (including 24:00 on the last day of the previous month (0:00 on day 1 of the current month))

  • Sample parameter file name: jpcrpt-parameters-for-scheduled-operation5.xml

Edit the bold characters in the sample parameter file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
  <launch-report>
    <agent>TA1host1</agent>
    <report-definition name="ReportA" parent-folder="/Folder1">
      <launch-options>
        <indication-settings>
          <report-interval>MONTH</report-interval>
          <start-time>
            <relative-time origin="THIS-MONTH" month="-3"/>
          </start-time>
          <end-time>
            <relative-time origin="THIS-MONTH"/>
          </end-time>
        </indication-settings>
      </launch-options>
    </report-definition>
  </launch-report>
</pr-cli-parameters>

The following is an example specification for quarterly reports. Since the acquisition period is three months, the month attribute of the <start-time> tag is set to -3. When a PI record is to be output, the interval for which reports are output is specified using the <report-interval> tag.

Example 6

The following performs report execution every day for a 24-hour (from 0:00 to 23:59) report. Note that the jpcrpt command is executed at any point in time from 0:00 to 24:00 on the next day.

  • Agent: TA1host1

  • Report definition: /Folder1/ReportA

  • Acquisition period: The day before execution of the jpcrpt command

  • Sample parameter file name: jpcrpt-parameters-for-scheduled-operation6.xml

Edit the bold characters in the sample parameter file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rpt_params.dtd">
<pr-cli-parameters ver="0220">
 <launch-report>
  <agent>TA1host1</agent>
  <report-definition name="ReportA" parent-folder="/Folder1">
   <launch-options>
    <indication-settings>
     <start-time>
      <relative-time origin="THIS-DAY" day="-1"/>
     </start-time>
     <end-time>
      <relative-time origin="THIS-DAY"/>
     </end-time>
     <exclude-terminal-data>ENDTIME</exclude-terminal-data>
    </indication-settings>
   </launch-options>
  </report-definition>
 </launch-report>
</pr-cli-parameters>

In the above example, the origin attributes under the <start-time> and <end-time> tags are set to THIS-DAY so that the base time is set to 0:00 on the day that the jpcrpt command is executed. To set the start day to the day before the day on which the command is executed, -1 is set for the day attribute under the <start-time> tag. To prevent the command from outputting the data at 0:00 on the current day (24:00 on the previous day), ENDTIME is specified in the <exclude-terminal-data> tag. As a result, the acquisition start time is set to 0:00 on the previous day, and the acquisition end time is set to 0:00 on the current day (23:59:59 on the previous day).