4 Validating XML

Successfully defining new Management Plug-in target definition files relies on accurate XML: It is essential that your Management Plug-in's target metadata and collection files be syntactically and structurally correct. To assist you with developing your XML files, Enterprise Manager supplies an XML verification tool called ILINT. This chapter covers the following topics:

What is ILINT?
Before Using ILINT
Using ILINT

What is ILINT?

Integrator LINT (ILINT) is a tool that helps you validate target metadata while defining new target types: You can perform real-time validation for the XML you write for target, instance, and collection metadata while you are writing the target metadata. ILINT also allows you to test runtime data collection for a new target type to validate data correctness.

This tool can also be used as an integrator certification tool to ensure that target type metadata conforms to acceptable standards.

What types of validation does ILINT perform?

ILINT allows you to perform two types of validation: static, which checks the correctness of your XML and dynamic, which checks the correctness of the data collected. ILINT validates for proper XML syntax by comparing target type metadata files against their respective DTD's ($AGENT_HOME/sysman/admin/dtds) and management agent semantics.

Static XML Validation

ILINT performs a static XML validation by performing heuristic checks, checking Management Repository constraints, and validating XML syntax on the following files:

<target_metadata>.xml

Directory Location: $AGENT_HOME/sysman/admin/metadata
<target_collection>.xml

Directory Location: $AGENT_HOME/sysman/admin/default_collection
targets.xml (target list file)

Directory Location: $AGENT_HOME/sysman/emd

Note:
In general, the targets.xml file should not be edited manually. However, when developing new metadata files, you may need to add specific target instance information to the target instance file for testing purposes. The targets.xml file must be structurally and syntactically correct because the Management Agent relies on the instance-specific information contained within the file.

Specifically, ILINT validates the metadata and, if it exists, the default collection for a specific target type using a validating parser. ILINT uses all target properties (both static and dynamic) as defined in the targets.xml file.

Heuristic Constraint Checks'

Are too many metrics being collected? If more than 50 metrics are collected for a given target type, ILINT generates a warning message.
Are too many targets being monitored? If more than 50 targets are being monitored for a given target type, ILINT generates a warning message.
Are metric collections intervals too short? If a specific metric collection interval is less than five minutes, ILINT generates a warning message.

Target Metadata Limitations Based on Management Repository Constraints

Verify that column name widths do not exceed 64 characters.
Verify that no more than 5 key columns have been set.
Check for legal characters in metadata name, type, metric name, and column names.

Dynamic Validation

Dynamic validation involves running specific metrics through the fetchlets to validate correctness and view output.

Dynamic validation allows you to check the correctness of the data collected for a target type. ILINT performs dynamic XML validation by executing all metrics defined for the new target and displaying viewable output in much the same way as the metric browser. For more information about the metric browser, see "Validate your new target type definitions.".

While performing dynamic validation, ILINT executes the specified metric and checks for errors using all properties (dynamic and static). ILINT then generates an output table containing:

Target list
Metric list for each target
Metric results

Metadata Version Checking

In order for the Enterprise Manager Grid Control console to display metrics for a specific target type, syntactic rules must be followed. ILINT can also be used to verify that the current version of a metadata file is compatible with an earlier version of the same metadata file. This compatibility check is stringent: Two target metadata files being compared by ILINT must be syntactically identical.

ILINT Output

ILINT generates two types of messages, each directed to different output file streams: STDOUT and STDERR.

Message Types

Informational/Warning--Generated when the XML is technically accurate, but may cause data collection/interpretation inaccuracies or framework performance issues. Tabular data generated during dynamic validation is also part of this message class.

Informational and Warning messages are printed to STDOUT.
Error--The XML is technically inaccurate or parameters specified violate management repository constraints.

Error messages are printed to STDERR.

Specifying Separate Output Files

You can specify separate STDOUT and STDERR output files when running ILINT. File specification may differ depending on the operating system and/or shell used for your environment.

Example 4-1 Specifying STDOUT and STDERR (ksh, bash, and sh)

emctl ilint ... 1>my_stdout_file 2>my_stderr_file

Example 4-2 Specifying STDOUT and STDERR (csh and tcsh)

(emctl ilint ... >my_stdout_file) >&my_stderr_file

Generating Syntactically Formatted XML Output

ILINT optionally allows you to generate a syntactically consistent view of a metadata file. For more information on ILINT options and generating valid XML, see "Generating Syntactically Correct XML".

Before Using ILINT

In order to validate an XML file, ILINT needs to know the location of the DTD (Document Type Declaration) associated with the XML file being validated. Make sure that the DOCTYPE directive specifying the relative path to the appropriate DTD is included in each XML file.

The following DTDs are used within the Enterprise Manager framework:

$AGENT_HOME/sysman/admin/dtds/TargetMetadata.dtd
$AGENT_HOME/sysman/admin/dtds/TargetCollection.dtd
$AGENT_HOME/sysman/admin/dtds/TargetInstance.dtd

The following example shows a DOCTYPE declaration that should be used when testing a target collection XML file located in the $AGENT_HOME/sysman/admin/default_collection directory or an instance specific collection file in the $AGENT_HOME/sysman/admin/collection directory.

Example 4-3 DOCTYPE Declaration

<!DOCTYPE TargetCollection SYSTEM "../dtds/TargetCollection.dtd">

Private external DTDs (DTDs shared between multiple documents and intended for use by a single author or group of authors) are identified by the keyword SYSTEM. In this case, anyone having the appropriate OS privileges to the machine running the Management Agent is considered an author.

Using ILINT

ILINT is part of the Enterprise Manager command line utility and is accessed as an emctl option. ILINT uses the following syntax:

emctl ilint [-o <test_name> [-p]] -m <target_metadata.xml> [-m2 <compare_metadata.xml][-c <target_collection.xml>] [-i <target_instance.xml>] [-t <target_name>] [-r <metric_name>] [-d <0|1|2|3>]

Table 4-1 ILINT Options

Option	Description
-o <test_name>	Automatically locates the metadata directory, default collection directory and collection file, and the targets.xml file. When the "-o" option is specified, the following applies: Just a file name rather than a full path and file name should be used when specifying the value for any of the options: -m, -m2, -c, -i Normally, option -c (target collection file) should be omitted. Normally, option -i (target instance file) should be omitted. If -p is specified, the formatted metadata output file(s) have the test_name as their prefix.
-p	Generate syntactically formatted XML for the metadata file. This option can only be used if the -o option is specified.
-m <target_metadata.xml>	Full path and file name of the metadata file to be checked. Note: If the -o option is specified, the value must be just a file name--the full path must be omitted. This is the only required option to ILINT.
-m2 <compare_metadata.xml>	Full path and file name of a second metadata file to be compared against the target metadata file specified by the -m option. This option can be used to check version compatibility between metadata files. Note: If the -o option is specified, the value must be just a file name--the full path must be omitted.
-c <target_collection.xml>	Full path and file name of the target collection file. Note: If the -o option is specified, the value must be just a file name--the full path must be omitted.
-i <target_instance.xml>	Full path and file name of the target instance file. Note: If the -o option is specified, the value must be just a file name--the full path must be omitted.
-t <target_name>	Name of the target (as specified in the targets.xml file) to be validated.
-r <metric_name>	Name of the metric to be executed.
-d (0-3)	Sets the debug level (default value is 1). This option specifies the type of information supplied by ILINT. 0=Error messages only. 1=Warning and Error messages. 2=Informational, Warning, and Error messages. 3=All messages: Debug, Informational, Warning, and Error messages.

ILINT Examples

The following examples demonstrate common ILINT usage scenarios discussed previously.

Static Validation

Usage

emctl ilint
-o <test_name>
-d <0-3>
-i targets.xml
-m <target_metadata.xml>
-t <target_name>

Example 4-4 Validating a Target Metadata File

> emctl ilint -o meta_test -d 0 -i targets.xml -m my_database.xml -t my_database3

The metadata directory and file (-m my_database.xml) is located automatically and associated with the test name "meta_test" (-o meta_test). The metadata file is validated against the database "my_database3" (-t my_database3) which is defined in the targets.xml file. Only error messages are returned (-d 0).

Example 4-5 Validating a Target Collection File

> emctl ilint -o collect_test -d 3 -i targets.xml -m co_database.xml -c my_collection.xml -t my_database3

The collection directory and file (-c my_collection.xml) is located automatically and associated with the test name "collect_test" (-o collect_test). Because this validation is run in full debug mode (-d 3), all error, warning, and informational messages are returned.

Example 4-6 Limited Metadata Validation (target type metadata file validation only)

emctl ilint -o test_name -d 0 -i non_existent_targets.xml -d 0 -m my_target_metadata.xml -t non_existent_target

As shown in this example, you can perform a limited target type metadata file XML validation by specifying a non-existent targets.xml file and a non-existent target. Limited validation quickly checks XML syntax used in the target metadata file as well as any limitations in metadata due to repository constraints.

Dynamic Validation

Usage

emctl ilint
-o <test_name>
-d <0-3>
-i targets.xml
-m <target_metadata.xml>
-t <target_name>
-r <metric_name>

Example 4-7 Validating a Metric

emctl ilint -o test_dynamic -d 0 -i targets.xml -m database.xml -t payroll_db -r Database_Resource_Usage

In this example, ILINT validates the database metric "Database_Resource_Usage." The metadata directory and file (-m database.xml) is located automatically and associated with the test name "test_dynamic" (-o test_dynamic). This metric is validated against the target database named "payroll_db" (-t payroll_db) which is defined in the targets.xml file. Only error messages are returned (-d 0).

Checking Metadata Version Compatibility

Usage

emctl ilint
-o <test_name>
-d <0-3>
-i targets.xml
-m <current_target_metadata.xml>
-m2 <old_target_metadata.xml>
-t <target_name>

Example 4-8 Validating Target Metadata Versions

emctl ilint -o version_test -d 3 -i targets.xml -m database.xml -m2 database.xml -t payroll_db

In this example, ILINT compares two versions of the target type metadata file "database.xml." Because the -o option is used, ILINT looks for the most recent version of "database.xml" in $AGENT_HOME/sysman/admin/metadata and the older version of this file in $AGENT_HOME/sysman/admin/metadata/old.

Note:

If you do not want to use the default directory locations, omit the -o <test_name> option and specify absolute pathnames for -m and -m2.

Generating Syntactically Correct XML

Usage

emctl ilint
-o <test_name>
-i targets.xml
-m <target_metadata.xml>
-m2 <old_target_metadata.xml> (optional)
-p

XML output is sent to a file named <test_name>.xml.tmp1

Example 4-9 Generating Syntactically Correct XML

emctl ilint -o test_generate -i targets.xml -m my_database.xml -p

The XML output from this example is sent automatically to the file "test_generate.xml.tmp1." If the "-m2" option is specified, the XML output for the second target metadata file is sent to "test_generate.xml.tmp2"

Usage Notes

If the XML/DTD cannot be parsed/validated the error messages tend to be less intuitive. The Java XML parser generates more informative messages.
The DTD path in the DOCTYPE directive in the XML file must be relative.
In debug mode, the full information about a metric whose collection depends on the value of a ValidIf element is not displayed.