Notes on commands that are executed in PFM - Web Console

Prerequisites for command execution

The following prerequisites apply to command execution:

• Creating a parameter file to be specified in a command

  To execute a command that requires a parameter file as an argument, you must have created the parameter file in advance.

  For details about how to specify a parameter file, see Command input method. For details about the parameters that are specified in a parameter file, see the description of the parameter file format in the explanations of the applicable commands.

• Checking the <logging> and <vsa> tags that are set in the config.xml^# file

  Make sure that the <logging> and <vsa> tags are set in the config.xml^# file. These tags are required. To set the tags, see the sample config.xml^# file.

• Checking the operating status of PFM - Manager

  PFM - Manager must be running when a command executes.

• Checking the operating status of PFM - Agent or PFM - RM

  To execute a command related to the Store database or a command that outputs report results, the appropriate PFM - Agent or PFM - RM must be running.

• Command execution permissions

  To execute commands, the OS user must have the Administrators permissions.

• Creating an authentication key file

  Before you can execute commands, you must create an authentication key file for PFM - Manager. You use the jpcmkkey command to create the authentication key file.

#

For an example of a config.xml file, see Initialization file (config.xml).

To Page Top

Command input method

This subsection explains how to describe a parameter file that is specified in a command.

How to describe a parameter file

The following explains how to describe a parameter file that is specified in a command argument:

• Create the parameter file in XML format.

• After specifying the XML version and encoding, enclose the parameters in <pr-cli-parameters> tags.

  For details about the parameters to be specified, see the parameter format for each applicable command.

• To use an XML-format control character (such as <) as part of a value, the syntax rules stipulated in the XML specifications must be observed.

  For example, < and > must be coded as &lt; and &gt;, respectively.

• In the case of a value that is specified by selecting from a specified token that is stipulated in the command parameter file specifications, such as a field ID, record ID, date-range, or report-interval, you may use all upper-case letters or all lower-case letters unless otherwise restricted explicitly. For details about the definitions of values that are specified in parameters, see the description of the parameter file format or DTD file for each applicable command.

• A parameter that accepts TRUE also accepts true, and a parameter that accepts FALSE also accepts false.

• An element or attribute whose value is blank is treated as being omitted. Leading and trailing spaces in an element or attribute value are ignored.

• An error results if a non-printable character is specified as an element or attribute.

• The DOCTYPE declaration is fixed in a parameter file. Make sure that the DOCTYPE declaration in the parameter file contains the name of the DTD file that defines the parameter descriptions. The following is an example of a DOCTYPE declaration:

  <!DOCTYPE pr-cli-parameters SYSTEM "DTD-file-name">

The following table lists the DTD files supported by the commands:

• You can specify the root directory by specifying / in the parent-folder attribute. To specify a directory under the root directory, specify a forward slash immediately before the directory name, such as /Directory1. Similarly, to specify a directory under Directory1, specify a directory path that uses / to connect each directory name, such as /Directory1/Directory2.... Specifying User Reports or System Reports in the / root directory results in an error.

• If a specified value is outside the range denoted in Parameter file format, a parameter file error results.

The following table describes pr-cli-parameters:

An example of the coding for a parameter file is shown below. Specify the report definition in the portion that is between the sections shown in bold type.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pr-cli-parameters SYSTEM "rdef_params.dtd">
<pr-cli-parameters ver="0110">
<report-definitions>
<report-definition> ....report-definition....</report-definition>
<report-definition> ....report-definition....</report-definition>
</report-definitions>
</pr-cli-parameters >

To Page Top

Command output method

Detailed information about a command's processing is output to the standard output, standard error output, and trace log file. The following table describes the output destinations for this detailed information:

To Page Top

Example of standard output

The command name, host name/IP address of PFM - Manager for the connection destination, PFM - Manager connection time, and PFM - Manager disconnection time are added as title and end rows common to all commands.

The example shown below shows the standard output when three reports are defined with the jpcrdef create command, two reports definitions are created, and one report definition result in an error.

jpcrdef create connected to hostname at yyyy MM dd HH:MM:SS.mmm
create result OK  : report-definition-directory-path-1/report-definition-name-1
create result OK  : report-definition-directory-path-2/report-definition-name-2
create result ERR : report-definition-directory-path-3/report-definition-name-3
cause-of-error
jpcrdef create disconnected at yyyy MM dd HH:MM:SS.mmm

jpcrdef   -h

Usage: jpcrdef <subcmd> [ <option>... ] {<parameter file>|<parameter option>... }
    <subcmd> Mandatory. Specify one of subcommands listed below:
        create          Creates report definition(s)
        delete          Deletes report definition(s)
        output          Outputs report definition(s)
    <option> Specify optionals after each extension listed below.
        -o <outputfile> Output file is required only if <subcmd>
                        is 'output'
        -mx             Specify maximum heap size from 1 to
                        2048 MB
                        Example: -mx 128. Default for both is 128MB.
        -ms             Specify minimum heap size from 1 to
                        2048 MB
                        Example: -ms 32. Default for both is 32MB.
        -y              Only used 'delete' <subcmd>. Assume a
                        yes response to
                        all questions asked by jpcrdef.
        -dateformat <pattern>
                        Specifiable when <subcmd> is 'create' or
                        'output'.
                        The specified <pattern> entry determines
                        the date format
                        for I/O in the <expression> tag.
                        Specifiable <pattern> entries are
                        'pattern-ddMMyyyy', 'pattern-MMddyyyy',
                        or 'pattern-yyyyMMdd'.
        -dateseparator <pattern>
                        Specifiable when <subcmd> is 'create' or
                        'output'.
                        The specified <pattern> entry determines
                        the date separator
                        for I/O in the <expression> tag.
                        Specifiable <pattern> entries are
                        'space', 'slash', 'hyphen', or 'period'.
    <parameter file>
                        If <subcmd> is "create", "delete", or
                        "output", specify a parameter file name.
                        This is required when <subcmd> is
                        "create", or "delete".
    <parameter option>
                        This can be specified when <subcmd> is
                        "output".
        -parent <parent directory>
                        Specify the directory path of the report
                        definition you want to output.
                        This is required when <parameter option>
                        is specified.
        -name <report name>
                        Specify the report definition name you
                        want to output.
                        If this is omitted, all report
                        definitions in the report definition
                        directory specified for the
                        parent-folder attribute, including
                        those in lower-level directories, are
                        output to a single file.

To Page Top

Concurrent command execution

The following commands (that is, commands other than the jpcrpt command) cannot be executed at the same time as another instance of the same command or as other commands:

• jpcrdef create

• jpcrdef delete

• jpcrdef output

• jpcasrec update

• jpcasrec output

• jpcaspsv update

• jpcaspsv output

• jpcmkkey

• jpcprocdef create

• jpcprocdef delete

• jpcprocdef list

• jpcprocdef output

To Page Top

Performance Management user permissions required for command execution

To use the GUI to change report definitions and collection items, you must first log into PFM - Manager (authenticated). This authentication is also required to execute commands. This authentication is also required to execute commands. Authentication determines whether the user has permissions to execute commands in the Performance Management system.

For command authentication, you must have created an authentication key file in advance and the key file is read during command execution; you do not enter a user name or password during command execution. You use the jpcmkkey command to create the key file. One key file is created for each host. Command execution from the host is permitted on the basis of the user names/passwords set in the key file. One key file is used by all commands executed from the host.

The following table shows the Performance Management user permissions required for command execution:

#

Execution permissions for Performance Management that are required for a Performance Management user or JP1 user.

To Page Top