Definition file for extended event attributes (extended file)
- Organization of this page
Format
[@encode character-encoding] @file type="extended-attributes-definition", version="0300"; @define-block type="event-attr-def"; attr name="attribute-name", title="item-name"; ... @define-block-end;
File
template_extend_attr_ja.conf (Japanese extended file)
template_extend_attr_ja.conf.model (model file for the Japanese extended file)
template_extend_attr_en.conf (English extended file)
template_extend_attr_en.conf.model (model file for the English extended file)
template_extend_attr_zh.conf (Chinese extended file)
template_extend_attr_zh.conf.model (model file for the Chinese extended file)
Storage directory
- In Windows
-
- For a physical host:
-
Console-path\conf\console\attribute\extend
- For a logical host:
-
shared-folder\JP1Cons\conf\console\attribute\extend
- In UNIX
-
- For a physical host:
-
/etc/opt/jp1cons/conf/console/attribute/extend
- For a logical host:
-
shared-directory/jp1cons/conf/console/attribute/extend
Description
The definition file for extended event attributes (extended file) defines program-specific extended attributes to be displayed as item names on the screen or output as item names in event reports.
Note that the definition file included with JP1/IM-Manager is prefixed with template_. Rename the file to extend_attr_ja.conf before you use it.
For details about a definition file for extended event attributes that is not an extended file, see Definition file for extended event attributes in Chapter 2. Definition Files.
Note that the Web-based JP1/IM - View event list cannot display item names defined in the definition file for extended event attributes (extended file).
Creation timing
The files are created when JP1/IM - Manager is installed.
When the definitions are applied
The definitions in the definition file for extended event attributes (extended file) take effect after either of the following occurs:
-
JP1/IM - Manager is restarted.
-
The command jco_spmd_reload is executed.
Note that you must restart JP1/IM - View if the definition is applied while JP1/IM - View is connected.
Information that is specified
The definition file for extended event attributes (extended file) defines program-specific extended attributes to be displayed as item names on the screen or output as item names in event reports. The extended files are JP1/IM - Manager definition files that are defined for each language used by JP1/IM - Manager.
If you use extended files for multiple languages in JP1/IM - Manager, the same attribute names must be specified in all the extended files. Because the attributes to be displayed in JP1/IM - View are uniquely determined for the entire system, it is not possible to display different attributes for different JP1/IM - Views in each language.
If there is a mismatch in the attribute names specified in the extended files, the warning message KAVB5820-W will be output when you check the extended files using the jcoattrfcheck command. In addition, attributes not specified in the extended files might appear in JP1/IM - View. For example, if the attribute E.SYSTEM is specified only in the English extended file, E.SYSTEM will also appear in the Japanese and Chinese JP1/IM - Views. In this case, the item name of E.SYSTEM displayed in the Japanese and Chinese JP1/IM - Views will be identical to the attribute name, namely E.SYSTEM.
JP1/IM provides the jcoattrfcheck command for checking the contents of a definition file for extended event attributes (extended file). For details about this command, see jcoattrfcheck in Chapter 1. Commands.
You can specify the statements and blocks described in the table below in a definition file for extended event attributes (extended file).
Statement or block |
Description |
---|---|
@encode statement |
Specifies the character encoding used in the definition file |
@file statement |
Declares the definition file type and version |
Definition block for extended event attributes |
Defines the display of event attributes |
Any statement or block that is not listed in the table above is ignored. If a definition file for extended event attributes (extended file) includes an invalid element, the invalid line is ignored while other valid lines work successfully. However, an error is issued if an invalid element is found in a statement that can be read from a definition file for extended event attributes (non-extended file) but cannot be read from a definition file for extended event attributes (extended file), for example, the block statement (block lang="";). For details about definition files for extended event attributes (non-extended files), see Definition file for extended event attributes in Chapter 2. Definition Files.
Information that is specified (specification of character encoding)
- @encode
-
Specifies the character encoding that is to be used in the definition file for extended event attributes (extended file).
Item names will be expressed in characters that can be represented in the character encoding specified in the @encode statement. In addition, the definition file for extended event attributes (extended file) will be saved in the character encoding specified in the @encode statement.
In the following circumstances, item names displayed in JP1/IM - View might be garbled:
-
If the item name uses characters that cannot be represented in the character encoding specified in the @encode statement
-
If the character encoding specified in the @encode statement does not match the character encoding in which the file was saved
If no @encode statement exists or if there is an error in the specified character set name that follows the @encode statement, the character set is determined automatically. However, depending on the content of the definition file, the character encoding might not be determined correctly.
The following character encodings can be specified.
Table 2‒28: Definition file character encodings that can be specified No.
Character encoding of file
Can be specified?
OS other than Linux
Linux
1
C
Y
Y
2
EUCJIS
Y
N
3
SJIS
Y
Y#
4
UTF-8
Y
Y
5
GB18030
Y
Y
- Legend:
-
Y: Can be specified
N: Cannot be specified
- #
-
Can be specified only in SUSE Linux.
- Note:
-
If you use UTF-8 as the encoding to save a definition file, save the file without attaching a BOM (byte order mark).
An error is output in the following cases:
-
A character encoding other than C, EUCJIS, SJIS, UTF-8, or GB18030 is specified
-
The definition file does not begin with @encode
-
@encode is not followed by a character encoding value
-
Information that is specified (rules for generating in-file statements)
- @file statement
-
Declares that this is a definition file for extended event attributes (extended file) and that the version of the definition specification format is 0300. This statement is required.
This statement must be on the first line of the file. If the statement is not specified on the first line, the integrity of operations cannot be guaranteed.
- Syntax
-
@file type="extended-attributes-definition", version="0300";
Information that is specified (rules for generating blocks in the definition file for extended event attributes)
This subsection describes the blocks that can be specified in a definition file for extended event attributes (extended file). If an invalid statement is specified in a block, an error is output but only the statement with the error is ignored.
- Definition block for extended event attributes
-
This block associates the event attribute name with its display item name. You can specify this block only once within the definition file. If you specify more than one definition block for extended event attributes, no error or warning is output, but the second and subsequent blocks are ignored.
- Types of statements that can be specified
-
You can specify the following statements in this block:
attr statement
Information that is specified (rules for generating statements in a definition block for extended event attributes)
- attr statement
-
Specifies the name of a program-specific extended attribute and the item name corresponding to that attribute, which is to be displayed on the screen or in event reports. You can specify this statement up to 100 times in a block. If you specify more than 100 attr statements, message KAVB5803-W will be output when you check the definition file with the jcoattrfcheck command.
- Syntax
-
attr name=attribute-name, title=item-name;
- name=attribute-name
-
Specifies the name of the extended attribute. The format is as follows:
"E.extended-attribute-name"
For the attribute name, you can specify a name with a maximum length of 32 bytes that begins with an uppercase letter and consists of uppercase letters, numeric characters, and the underscore (_).
If you specify an extended attribute name that exceeds 32 bytes, message KAVB5803-W will be output when you check the definition file with the jcoattrfcheck command or execute the jcoevtreport command. In addition, message KAVB5822-W will be output when the definition file for extended event attributes (extended file) is loaded when JP1/IM - Manager starts or the jco_spmd_reload command is executed.
Only a program-specific extended attribute can be specified. However, you cannot specify attributes that overlap with the extended attributes specified in the standard definition file for extended event attributes (default.conf), such as the event source host name (E.JP1_SOURCEHOST) or the log file trap name (E.JP1_TRAP_NAME). If you specify extended attributes that overlap with the standard definition file for extended event attributes (default.conf), the item names specified in the standard file will be applied.
If you specify extended attributes that overlap with the standard definition file for extended event attributes (default.conf), message KAVB5802-W# will be output after the definition file for extended event attributes (extended file) is loaded when you execute the jcoevtreport or jcoattrfcheck command. The jcoevtreport command proceeds by ignoring overlapping attributes specified in the definition file for extended event attributes (extended file). In addition, message KAVB5822-W will be output after the definition file for extended event attributes (extended file) is loaded when you restart JP1/IM - Manager or execute the jco_spmd_reload command. JP1/IM - Manager proceeds by ignoring overlapping attributes specified in the definition file for extended event attributes (extended file).
If you specify a basic attribute (B.attribute-name) or an IM attribute (E.@attribute-name), or some other attribute that is not an extended attribute (E.attribute-name), message KAVB5821-W# will be output after the definition file for extended event attributes (extended file) is loaded when you execute the jcoevtreport or jcoattrfcheck command. In addition, message KAVB5822-W will be output after the definition file for extended event attributes (extended file) is loaded when you restart JP1/IM - Manager or execute the jco_spmd_reload command.
#: When the jcoevtreport command generates reports successfully or when the jcoattrfcheck command checks the definition file completely, the return value of the commands is 0 (normal end), regardless of whether message KAVB5802-W or KAVB5821-W was output.
If you use extended files for multiple languages in JP1/IM - Manager, all the attribute names specified in the definition files for extended event attributes (extended files) must match. Otherwise, message KAVB5820-W will be output after the definition file for extended event attributes (extended file) is loaded when you execute the jcoevtreport or jcoattrfcheck command. In addition, message KAVB5822-W will be output after the definition file for extended event attributes (extended file) is loaded when you restart JP1/IM - Manager or execute the jco_spmd_reload command.
- title=item-name
-
Defines the item name of the program-specific extended attribute. item-name is expressed in characters that can be represented in the character encoding specified in the @encode statement. item-name might appear garbled in JP1/IM - View if it uses characters that cannot be represented in the character encoding specified in the @encode statement.
In addition, item-name might appear garbled in CSV files if it uses characters that cannot be represented in the character encoding of the report output by the jcoevtreport command.
Specify a character string that will serve as the program-specific extended attribute's item name for display on the screen and output in event reports. Half-width kana characters and the comma (,) cannot be used in this parameter. If half-width kana characters and the comma (,) are specified in the character string, they will not be output correctly.
The maximum length of item-name is 255 bytes. If you specify more than 255 bytes for item-name, message KAVB5803-W will be output when you check the definition file with the jcoattrfcheck command or execute the jcoevtreport command. In addition, message KAVB5822-W will be output after the definition file for extended event attributes (extended file) is loaded when you restart JP1/IM - Manager or execute the jco_spmd_reload command.
- Note:
-
If you specify program-specific extended attributes in the definition file for extended event attributes (extended file) that overlap with the attributes in the standard definition file for extended event attributes (default.conf), the program-specific extended attribute item names specified in the standard definition file for extended event attributes (default.conf) will be displayed in the list of events in the Event Console window and will be output in the CSV header that is output with event reports.
Example definition
The following shows an example of a definition file for extended event attributes (extended file):
@encode UTF-8 @file type="extended-attributes-definition", version="0300"; @define-block type="event-attr-def"; attr name="E.SYSTEM", title="System name"; attr name="E.ROLE", title="Server role"; @define-block-end;