Notes on commands that are executed in PFM - Web Console
This section describes the prerequisites, input format, and output format of the following commands that are executed in PFM - Web Console:
-
jpcrdef create
-
jpcrdef delete
-
jpcrdef output
-
jpcasrec update
-
jpcasrec output
-
jpcaspsv update
-
jpcaspsv output
-
jpcrpt
-
jpcmkkey
-
jpcprocdef create
-
jpcprocdef delete
-
jpcprocdef list
-
jpcprocdef output
- Organization of this page
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 E. Initialization File (config.xml).
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 < and >, 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:
Type |
Description |
|
---|---|---|
Description |
Root tag for PFM - Web Console command input |
|
Specifiable value |
None |
|
Omissible |
No |
|
Attribute |
ver |
DTD file version. If the value is outside the supported range, a parameter file error results. If the specification is omitted, an error results. For details about the supported range, see each DTD file. |
Parent element |
None |
|
Child element |
report-definitions |
Root tag for report definition |
agent-store-db-record-definition |
Root tag for Store database recording method change definition information |
|
agent-store-db-preserve-definition |
Root tag for the Store database storage condition change definition information |
|
launch-report |
Root tag for the report output definition information |
|
launch-registration-report |
Root tag for the registered report output definition information |
|
launch-combination-bookmark |
Root tag for the combination bookmark output definition information |
|
application-definition |
Root tag for the application definition information |
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.
Coding example of parameter file
<?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 >
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:
Item |
Output destination |
---|---|
Execution results |
Standard output |
Messages |
Standard error output |
Trace log |
command-name_processing-type_log#.log ( where # is the log file number [from 1 to the number of generated log files]) is output under the log output directory specified in the initialization file. For example, the log name is jpcrdef_create_log1.log for the report creation command. For the jpcrpt command, command-name_process-ID_log#.log (where # is the log file number [from 1 to the number of generated log files]) is output under the log output directory specified in the initialization file. When the process ID is 100, the log name is jpcrpt_100_log1.log. Each time the command is executed, the total size of the log files is calculated. When the upper limit is exceeded, the file with the oldest update date is deleted. Note, however, that only those files updated previous to the number of days specified for logFileRetention in the initialization file after the command is started are deleted. The upper limit for size is determined by multiplying logFileSize by logFileNumber in config.xml. For the jpcmkkey command, jpcmkkey_log#.log (where # is the log file number [from 1 to the number of generated log files]) is output under the log output directory specified in the initialization file. |
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.
Example of execution results output
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
- Legend:
-
- yyyy MM dd
-
Year, month, and day.
The display format changes according to the locale. For details, see the chapter on installation and setup in the Job Management Partner 1/Performance Management Planning and Configuration Guide.
- HH:MM:SS.mmm
-
Hour, minute, second, and millisecond.
- report-definition-directory-path-1 through report-definition-directory-path-3
-
Names of the directories containing the report definitions set in the parent-folder attribute of the report-definition parameter.
- report-definition-name-1 through report-definition-name-3
-
Names of the report definitions set in the name attribute of the report-definition parameter.
For details about the log specifications, see 3. Log Information Output by Performance Management.
Help reference option
Specifying the -h option in a command displays a Help for the command. For example, to view the Help for the jpcrdef command, enter the following:
jpcrdef -h
The following shows the Help that is provided for the jpcrdef command:
Usage: jpcrdef <subcmd> [ <option>... ] <parameter file> <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 1024 MB Example: -mx 64. Default for both is 64MB. -ms Specify minimum heap size from 1 to 1024 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> Mandatory. Specify parameter file
If a command's first argument is the -h option, the system ignores the remainder of the specification and displays the command's Help. A command's Help is also displayed when the command line includes an invalid specification.
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
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:
Command |
Required Performance Management user permissions# |
---|---|
jpcrdef create |
General user permission or administrator user permission |
jpcrdef delete |
General user permission or administrator user permission |
jpcrdef output |
General user permission or administrator user permission |
jpcasrec update |
Administrator user permission |
jpcasrec output |
Administrator user permission |
jpcaspsv update |
Administrator user permission |
jpcaspsv output |
Administrator user permission |
jpcrpt |
General user permission or administrator user permission |
jpcmkkey |
None |
jpcprocdef create |
Administrator user permission |
jpcprocdef delete |
Administrator user permission |
jpcprocdef list |
Administrator user permission |
jpcprocdef output |
Administrator user permission |
- #
-
Execution permissions for Performance Management that are required for a Performance Management user or JP1 user.