jpctool alarm export
- Organization of this page
Format
jpctool alarm export -f target-file-name {-key service-key [-table alarm-table-name[-alarm alarm-name]] [-only]| -template} [-y|-n] [-wait number-of-seconds]
Function
The jpctool alarm export command exports alarm definitions to the specified file.
Alarm definition information is exported in accordance with the syntax of the alarm definition file. For details about the syntax of the alarm definition file, see the chapter in the JP1/Performance Management User's Guide that describes operation monitoring by alarms.
The following table shows the range of alarm definition information that is exported depending on the combination of the -key, -table, and -alarm options that is specified:
Option specifications |
Information that is exported |
||
---|---|---|---|
-key |
-table |
-alarm |
|
S |
N |
N |
All alarm definition information for the alarm tables that are defined for the PFM - Agent or PFM - RM specified in the -key option is exported. |
S |
S |
N |
All alarm definition information in the alarm table that is specified in the -table option is exported. |
S |
S |
S |
Only the definition information for the alarm specified in the -alarm option is exported. |
- Legend:
-
S: Specified
N: Not specified
By specifying the -template option, you can output the template file that contains all the labels that are defined in the alarm definition file.
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
-f target-file-name
Specifies a name for the alarm definition file to which definition information is to be exported. The file name can be expressed as a relative path or an absolute path.
The string you specify can have double-byte characters, single-byte alphanumeric characters, single-byte spaces, and the following single-byte symbols:
% - ( ) _ . @ [ ]
If the value contains a space, enclose the entire value in double quotation marks ("). If the value contains a defined symbol, specify an escape character if necessary.
-key service-key
Specifies the service key of the PFM - Agent or PFM - RM for which alarm definition information is to be exported. A product name can also be specified when the product name display functionality is enabled. You can specify only the service key of PFM - Agent or PFM - RM here. For details about the service key of the PFM - Agent or PFM - RM, see the naming rules described in the appendix of the JP1/Performance Management Planning and Configuration Guide.
The -key and -template options are mutually exclusive.
-table alarm-table-name
Specifies the name of the alarm table that contains the alarm definition information to be exported.
For alarm-table-name, specify a string of 1 to 64 bytes long, consisting of double-byte characters, single-byte alphanumeric characters, single-byte spaces, and the following single-byte symbols:
% - ( ) _ . / @ [ ]
If the value contains a space, enclose the entire value in double quotation marks ("). If the value contains a defined symbol, specify an escape character if necessary.
Wildcard characters cannot be used.
The -table and -template options are mutually exclusive.
-alarm alarm-name
Specifies the name of the alarm whose alarm definition information is to be exported.
For alarm-table, specify a string of 1 to 20 bytes long, consisting of double-byte characters, single-byte alphanumeric characters, single-byte spaces, and the following single-byte symbols:
% - ( ) _ . / @ [ ]
If the value contains a space, enclose the entire value in double quotation marks ("). If the value contains a defined symbol, specify an escape character if necessary.
Wildcard characters cannot be used.
The -alarm and -template options are mutually exclusive.
-only
Specifies that only user-defined alarm tables are to be output#. The file output with this option specified can be used as the alarm definition file to be imported with the jpctool alarm import command.
- #
-
Monitoring templates (alarm tables whose names begin with PFM) are not output.
The -only and -template options are mutually exclusive.
-template
Specifies that the template for the alarm definition file is to be output.
This option cannot be specified together with the -key, -table, -alarm, or -only option.
-y|-n
Specifies whether or not the alarm definition file specified in the -f option is to be overwritten forcibly if it already exists.
When -y is specified, the command forcibly overwrites an existing alarm definition file.
When -n is specified, the command skips overwrite processing.
When this option is omitted, the command displays a confirmation message asking whether or not an existing alarm definition file is to be overwritten.
-wait number-of-seconds
Specifies the maximum wait period (in seconds) applied when a command that cannot be executed with this command is running. When the setting to suspend execution of alarm commands (Alarm Command Wait Mode) is enabled in the startup information file (jpccomm.ini), if you want to specify a wait period (in seconds) separately from the wait period specified in the jpccomm.ini file, specify a value in the range from 1 to 3,600 for this option.
If you omit the option, this command runs with the wait period (in seconds) specified in the jpccomm.ini file.
For details on the commands that cannot be executed with this command, see Commands that cannot be executed with alarm commands. For details on the jpccomm.ini file and Alarm Command Wait Mode, see Startup information file (jpccomm.ini).
Alarm definition file format
See the description of the alarm definition file format in the jpctool alarm import command.
Notes
-
This command cannot be executed concurrently.
-
You must start PFM - Manager (Name Server, Master Manager, and View Server services) before you can export existing alarm definition information with the -key, -table, or -alarm option specified. However, if you are outputting the template (-template option specified), it is not necessary for PFM - Manager to be running.
-
PFM - Agent and PFM - RM monitoring templates might contain alarms for which conditions for abnormal values and warning values are different. In this case, when a monitoring template is exported, conditions with warning values are given priority for export.
For example, if you export an alarm definition whose conditional expression for an abnormal value is BBB >= 90 and that for a warning value is BBB > 80, the warning value condition (>) is output to the alarm definition file as shown below:
[[Alarm Condition Expressions]] Condition=BBB>90,80
For details about settings for abnormal value and warning value conditions for monitoring templates, see the chapter describing monitoring templates in the PFM - Agent or PFM - RM manuals.
-
You can export 251 or more alarm definitions at once. Note, however, that the maximum number of alarms that can be defined in one alarm definition file is 250. An export file containing 251 or more alarm definitions cannot be imported as an alarm definition file. To import these alarm definitions, you must divide the export file into multiple alarm definition files, each of which contains no more than 250 alarm definitions.
For example, assume that you specify the -key option to export alarm tables AlarmTable1 (containing 200 alarm definitions) and AlarmTable2 (containing 100 alarm definitions) that are bound to PFM - Agent or PFM - RM. In this case, 300 alarm definitions will be exported to one file. However, because one alarm definition file can contain a maximum of 250 alarm definitions, the exported file cannot be used as an import file. To import these alarm definitions, you must prepare multiple alarm definition files, each of which contains no more than 250 alarm definitions.
-
If the alarm definitions you export include double-byte characters, the LANG environment variable for the shell that is used to execute the command must be set to Japanese (Shift JIS, EUC, or UTF-8) or Simplified Chinese (GB18030 or UTF-8). In addition, the value of that LANG environment variable must be the same as the value of the LANG environment variable that is loaded when PFM - Manager starts. Before you execute this command, make sure that the LANG environment variable setting of the shell and PFM - Manager match.
-
If the file name you specify includes double-byte characters, the LANG environment variable for the shell that is used to execute the command must be set to Japanese (Shift JIS, EUC, or UTF-8) or Simplified Chinese (GB18030 or UTF-8). Before you execute this command, check the setting of the LANG environment variable for the shell.
-
If PFM - Manager is installed on a logical host, execute the command on the executing node.
-
If you specify an alarm table that includes an alarm for which the notification of state changes for each instance has not been specified, Alarm is set for the Notify State label in the alarm definition file to be exported.
-
Even if JP1 event issuance is correctly configured in the Command Definition area of the New Alarm > Action Definitions window or the Edit > Action Definitions window, N might be output for the JP1 event label that was exported by using this command (for example, when the value of the -r option is not enclosed in double quotation marks (")). However, JP1 event issuance is actually enabled as the alarm action. There is no problem even if you import the file in which N is output for the JP1 event label because JP1 event issuance is enabled as the alarm action.
-
The character encoding of the alarm definition file and the value of the Alarm Definition File Code label in the alarm definition file are determined according to the value of the LANG environment variable for the shell that is used to execute the command. If the alarm definitions to be exported contain non-ASCII characters, check the value of the LANG environment variable in the shell before executing this command.
The tables below show, for each OS, the character encoding and the value of the Alarm Definition File Code label for each value of the LANG environment variable.
If the value of the LANG environment variable is not shown in the tables below, the command assumes that the LANG environment variable is set to C.
Table 2‒47: Correspondence between the value of the LANG environment variable, the character encoding, and the value of the Alarm Definition File Code label (Windows) Language
Value of the LANG environment variable
Character encoding
Value of the Alarm Definition File Code label
Japanese
--
Shift_JIS (SJIS)
Shift_JIS
English
--
ASCII
C
Chinese (Simplified)
--
GB18030
GB18030
Legend:
--: Not applicable.
Table 2‒48: Correspondence between the value of the LANG environment variable, the character encoding, and the value of the Alarm Definition File Code label (AIX) Language
Value of the LANG environment variable
Character encoding
Value of the Alarm Definition File Code label
Japanese
-
ja_JP
-
ja_JP.IBM-eucJP
EUC
EUC-JP
-
Ja_JP
-
Ja_JP.IBM-932
Shift_JIS (SJIS)
Shift_JIS
-
JA_JP.UTF-8
UTF-8
UTF-8
English
-
C
ASCII
C
Chinese (Simplified)
-
Zh_CN
-
Zh_CN.GB18030
GB18030
GB18030
-
ZH_CN
-
ZH_CN.UTF-8
UTF-8
UTF-8
Table 2‒49: Correspondence between the value of the LANG environment variable, the character encoding, and the value of the Alarm Definition File Code label (Linux) Language
Value of the LANG environment variable
Character encoding
Value of the Alarm Definition File Code label
Japanese
-
ja_JP.SJIS#
-
ja_JP.sjis#
Shift_JIS (SJIS)
Shift_JIS
-
ja_JP.UTF-8
-
ja_JP.utf8
UTF-8
UTF-8
English
-
C
ASCII
C
Chinese (Simplified)
-
zh_CN.gb18030
GB18030
GB18030
-
zh_CN.UTF-8
-
zh.CN.utf8
UTF-8
UTF-8
#: Available only in SUSE Linux.
-
Return values
0 |
The command terminated normally. |
1 |
An argument specification is invalid. |
2 |
The user does not have execution permission for the command. |
3 |
At least one of the Name Server, Master Manager, and View Server services is not running. |
4 |
The startup stop command or another setup command was executed on the same machine. |
5 |
The command was executed on a host that is not the PFM - Manager host. Alternatively, the agent to which alarms are to be exported has not been set up. |
6 |
The specified alarm table or alarm is missing, or the alarm definition was not found at the agent with the specified service key. |
11 |
The user canceled the processing. |
100 |
The Performance Management environment is invalid. |
200 |
A memory shortage occurred. |
210 |
A disk space shortage occurred. |
211 |
A target file cannot be accessed. |
222 |
A communication error occurred. |
223 |
Communication processing resulted in a timeout. |
255 |
An unexpected error occurred. |
Usage example 1
In this example, alarm table alarmtable1 is not a monitoring template, but is assumed to be defined for PFM - Agent for Platform (UNIX). Alarm table alarmtable1 is also assumed to have alarm alarm1 defined.
The following command exports all the alarm definitions defined for PFM - Agent for Platform (UNIX) to the alarmtable1.cfg file under the /tmp directory:
jpctool alarm export -f /tmp/alarmtable1.cfg -key UNIX
Output result 1 (alarmtable1.cfg)
Alarm Definition File Version=0002 Alarm Definition File Code=C [Alarm Data] [[General]] Product=U3.0 Alarm Table Name="PFM UNIX Solution Alarms 8.00" Alarm Name="Disk Service Time" Message Text="Average disk service time is %CVS secs" Check Value Exist=N : [Alarm Data] [[General]] Product=U4.0 Alarm Table Name=alarmtable1 Alarm Name=alarm1 Message Text= Check Value Exist=N :
Usage example 2
This example exports the Disk Service Time alarm definition to the file alarm2.cfg in the /tmp directory of the alarms defined in the PFM UNIX Solution Alarms 8.00 monitoring template for PFM - Agent for Platform (UNIX).
jpctool alarm export -f /tmp/alarm2.cfg -key UNIX -table "PFM UNIX Solution Alarms 8.00" -alarm "Disk Service Time"
Output result 2 (alarm2.cfg)
Alarm Definition File Version=0002 Alarm Definition File Code=C [Alarm Data] [[General]] Product=U3.0 Alarm Table Name="PFM UNIX Solution Alarms 8.00" Alarm Name="Disk Service Time" Message Text="Average disk service time is %CVS secs" Check Value Exist=N :
Usage example 3
This example outputs the alarm definition file template to the template3.cfg file under the /tmp directory:
jpctool alarm export -f /tmp/template3.cfg -template
Output result 3 (template3.cfg)
Alarm Definition File Version=0002 Alarm Definition File Code= [Alarm Data] [[General]] Product= Alarm Table Name= Alarm Name= Message Text= Check Value Exist=N [[Advanced Setting]] Active Alarm=Y Regular Alarm=Y Evaluate All Data=N Notify State=Alarm Monitoring Regularly=N Monitoring Time= Damping=N Damping Count= [[Check Value Exist]] Record= Field= Value= [[Alarm Condition Expressions]] Condition= [[Actions]] Report= E-mail=Abnormal,Warning,Normal Command=Abnormal,Warning,Normal SNMP=Abnormal,Warning,Normal JP1 Event=N [[Action Definition E-mail]] E-mail Address= Action Handler= [[[Message Text]]] Date: %SCT Host: %HNS Product: %PTS Agent: %ANS Alarm: %AIS (%ATS) State: %SCS Message: %MTS [[Action Definition Command]] Command Name= Action Handler= [[[Message Text]]] [[Action Definition JP1 Event]] Event ID= Action Handler= Message=%MTS Switch Alarm Level=Y Exec Logical Host=