Hitachi

JP1 Version 12 JP1/Integrated Management 2 - Manager Command, Definition File and API Reference


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 of JP1/IM - View or the integrated operation viewer 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.

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:

Note that you must restart JP1/IM - View or the integrated operation viewer if the definition is applied while JP1/IM - View or the integrated operation viewer are 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 or the integrated operation viewer are uniquely determined for the entire system, it is not possible to display different attributes for different JP1/IM - Viewsor the integrated operation viewerin 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 or the integrated operation viewer. 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).

Table 2‒32: Statements and blocks that can be specified 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 or the integrated operation viewer 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‒33: 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;