jpcconf agttree import
- Organization of this page
Format
jpcconf agttree import [-nocheck] [-noquery] [-lhost logical-host-name] -f Agents-tree-definition-file-name
Function
The jpcconf agttree import command imports Agents tree definition information from the specified file, and creates or updates the Agents tree with the imported information. The imported Agents tree definition information is applied at the following times:
-
When the Agents tree of PFM - Web Console is refreshed
-
When the user logs in to PFM - Web Console again
Hosts that can execute the command
PFM - Manager
Execution permission
- In Windows:
-
User with Administrators permissions
- In UNIX:
-
User with root user permissions
Installation directory
- In Windows:
-
installation-folder\tools\
- In UNIX:
-
/opt/jp1pc/tools/
Arguments
-nocheck
Specify this option to skip checking whether the agents specified in the Agents tree definition file are recognized by Performance Management. If this option is omitted and an unrecognized agent is detected, the command processing stops.
After agents have been installed and set up, Performance Management recognizes them when they connect to PFM - Manager. Recognized agents are displayed under the Products node in the Agents tree.
Before agents are recognized by Performance Management, their data model version is assumed to be 3.0. The actual data model version will be applied after these agents are recognized.
Performance Management might have not yet recognized all of agents specified in the Agents tree definition file when, for example, the system is being built. In such a case, specify this option.
-noquery
If this option is specified, the command does not output any query messages that interrupt command execution, making it unnecessary for the user to respond. Specify this option if you want the command to run in non-interactive mode.
Note that if the user specified in the Agents tree definition file has already created his or her Agents tree, the tree will be overwritten.
If the Agents tree of the specified user already exists, a KAVE06073-I message is output and the Agents tree is updated.
-lhost logical-host-name
Specifies the logical host name of the host on which this command is executed. For logical-host-name, specify a string of 1 to 32 bytes, consisting of single-byte alphanumeric characters. If this option is omitted, the command will be executed on the physical host.
-f Agents-tree-definition-file-name
Specifies the name of the Agents tree definition file to be imported. The file must be an XML file. The format of this file is described in Format of Agents tree definition files below. You can specify an absolute file path, a relative file path from the current directory, or the name of a file in the current directory.
Format of Agents tree definition files
An example of the Agents tree definition file is shown below. Note that you can generate the template file for the Agents tree definition file by executing the jpcconf agttree export command with the -template option. The template file is useful when you create your Agents tree definition file.
Example of an Agents tree definition file:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE tree SYSTEM "agttree_param.dtd"> <tree owner="pfm-user"> <folder name="Test Company"> <folder name="Business Department"> <agent name="7A1instBD[tHOST01@host111]"/> </folder> <folder name="Development Department"> <agent name="7A1instDD[tHOST02@host111]"/> <agent name="7A1instDD[tHOST03@host111]"/> </folder> <agent name="TA1host111"/> </folder> <agent name="TA1host999"/> </tree>
With the above example file, the following Agents tree is created:
Descriptive conventions
The following provides the descriptive conventions for the Agents tree definition file:
-
The tree can have a maximum of eight hierarchical levels. In the root level and each folder, you can create a maximum of 64 folders and a maximum of 128 agents.
-
Element names and attribute values consisting of only spaces are assumed to be omitted. Any spaces before and after element names and attribute values are ignored.
-
If nonprintable characters are used in an element name or attribute value, an error occurs.
-
The DOCTYPE declaration in the file is fixed. In the declaration, always specify the name of the DTD file that contains file descriptive definitions. This command supports the following DTD file:
-
agttree_param.dtd
-
-
In XML, a less-than (<) sign and other characters have special meanings. If you use these characters as ordinary characters, you must follow the notations prescribed by the XML specifications.
For example, to use a less-than sign (<), specify <. To use a greater-than sign (>), specify >.
XML tag specifications
-
tree
Item
Description
Description
The tree element indicates a top (root) node in an Agents tree.
Specifiable value
None
Omissible
No
Attribute
owner
Specifies the name of the user who owns the Agents tree settings. This attribute is required.
You can specify a string of 1 to 16 bytes, consisting of single-byte alphanumeric characters, spaces, and the symbols listed below. Alphabetic characters are not case sensitive.
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
Parent element
None
Child element
folder (Multiple instances can be specified.)
agent (Multiple instances can be specified.)
-
folder
Item
Description
Description
The folder element indicates a folder node in an Agents tree.
Specifiable value
None
Omissible
Yes
Attribute
name
Specifies a folder name. This attribute is required.
The name can have 1 to 64 double-byte and/or single-byte characters.
Parent element
tree, folder
Child element
folder (Multiple instances can be specified.)
agent (Multiple instances can be specified.)
-
agent
Item
Description
Description
The agent element indicates an agent node in an Agents tree.
Specifiable value
None
Omissible
Yes
Attribute
name
Specifies a service ID as an agent name. This attribute is required. The value of this attribute must be 1 to 258 bytes long.
For the product ID part, specify the product ID of PFM - Agent or PFM - RM. For the function ID part, specify A.
Parent element
tree, folder
Child element
None
Notes
-
You can execute this command only when the View Server service is running.
-
If the Agents tree definition file includes PFM - Agent or PFM - RM products that PFM - Manager cannot recognize, the command processing is interrupted regardless of whether the -nocheck option is specified. If the command processing is interrupted for this reason, make sure that the PFM - Agent or PFM - RM products specified in the file are registered in PFM - Manager. For details about the registration procedure, see the chapter on installation and setup in the JP1/Performance Management Planning and Configuration Guide.
- Note
-
The terms PFM - Agent or PFM - RM products that PFM - Manager cannot recognize refer to agents whose product ID does not exist. Therefore, if the host TA1hostA is specified in the Agents tree definition file, the command does not fail in an environment in which that host does not exist even when the -nocheck option is specified. This is because the product ID of T is correct.
-
If you want to include non-ASCII characters in the Agents tree definition file, use only UTF-8, Shift-JIS, EUC-JP, or GB180030 encoding. In this case, in the XML declaration part in that file, set the encoding attribute to UTF-8, Shift_JIS, EUC-JP, or GB180030. Note that, if the Agents tree definition file includes only ASCII characters, specify UTF-8, Shift_JIS, EUC-JP, or GB180030 as the value of the encoding attribute in the XML declaration.
The following table describes specifiable encoding values for each encoding type of the Agents tree definition file.
Encoding of file
Specifiable values for the encoding attribute
UTF-8
Shift_JIS
EUC-JP
GB180030
ASCII
Y
Y
Y
Y
UTF-8
Y
N
N
N
Shift-JIS
N
Y
N
N
EUC-JP
N
N
Y
N
GB180030
N
N
N
Y
-
When performing multiple monitoring, you cannot execute this command from the secondary PFM - Manager host.
Return values
0 |
The command terminated normally. |
1 |
An argument specification is invalid. |
2 |
The user does not have execution permission for the command. |
5 |
An attempt was made to execute the command on the PFM - Base host, but the command can only be executed on the PFM - Manager host. Or else, an attempt was made to execute the command from the secondary PFM - Manager host when multiple monitoring is performed. |
6 |
The definition file contains errors. |
11 |
Processing was canceled by the user (N was returned as the response to a query). |
100 |
The Performance Management environment is invalid. |
101 |
A service that is prerequisite for executing this command is not running. |
102 |
The specified logical host has not been set up. |
200 |
A memory shortage occurred. |
210 |
A disk space shortage occurred. |
211 |
A file or directory cannot be accessed. |
255 |
An unexpected error occurred. |
Usage example
This example imports Agents tree definition information to the View Server service.
# jpcconf agttree import -f agttree_def.xml