Parsers

A Parser takes raw configuration data and parses it into a nested attribute structure. This structure is a tree hierarchy where nodes are containers and leaves are name value pairs of attributes, or properties.

Configuration extensions include a host of parsers provided by Oracle. Each parser consists of a base parser and parser parameters. Some parsers also contain post-parsing rules. A base parser essentially is a category of parser capable of parsing data of a particular format. Parser parameters provide a way to tailor the base format to accommodate variations in data formatting. Post-parsing rules are a mechanism for aligning nodes in the tree that otherwise have no distinct identity. This is important when comparing configurations and tracking change history to avoid flagging "false positive" differences. It also aids in specifying search criteria and crafting SQL queries used in compliance rules.

There are four varieties of base parser:

• XML

• Format-specific

• Columnar

• Properties

Some parsers have default rules provided by Oracle. These rules address well-known instances where nodes need to be aligned. Specifically, the WebLogic and WebSphere parsers contain default rules to address such instances. You can leave these rules as is, execute a subset of them, or replace them with your own custom rules.

This section covers the following topics:

• Managing Parsers

• About XML Parsers

• About Format-Specific Parsers

• About Columnar Parsers

• About Properties Parsers

• Using Parsed Files and Rules

Managing Parsers

While creating, editing, or viewing configuration extensions, you can peruse the list of available parers, their default parameters, and post-parser rules, if applicable. Parser parameters dictate formatting such as comment character, delimiters, start and end characters, and so forth. You cannot edit these parameters, but you can export a parser as an XML file, edit the file, and import it back into the application under a new name. Some parsers also have default rules that serve to align nodes in the parsed tree for purposes of comparison, for example.

1. In the Configuration Extensions library, select Manage Parsers from the Actions menu. A list of available parsers appears in a table. The column on the right (Base Parsers) denotes a general parser category, Properties for example, which implies file types that contain name/value pairs.

2. Select a parser and click Details. This dialog also shows default rules, if any.

   • Click the Parameters tab to see the parameter defaults in effect. You can then judge if you need to edit the parser to conform with your file format conventions.

   • Click the Default Rules tab to see the post-parsing rules that ship with certain parsers. This is a good way to get exposure to rules formation.

3. Assume you want to change the delimiter character in a given parser.

   1. With the parser selected in the table, click Export.

   2. In the dialog that opens click Save and navigate to a file system location. Save the XML file with an appropriate name.

   3. In making your edits, be sure to change the parser ID and parser name in the XML, as you are creating a customized version of a parser provided by Oracle.

4. Assume you now want to import the new parser you saved for use in creating configuration extensions.

   1. With the Parsers table open, click Import.

   2. In the dialog that opens, browse to the file location where you saved the exported parser file. Select it and click Import on the dialog.

   The new parser now appears in the Parsers table where it can be used in configuration extension creation.

About XML Parsers

Cloud Control has two XML parsers: a default (attribute-keyed) XML parser and a generic XML parser.

About the Default XML Parser

Parsing occurs as follows:

• XML elements with no XML attributes or child elements become parsed attributes; all other elements become containers.

• XML attributes become parsed attributes.

• Element text content becomes a parsed attribute, with its name dependent on whether or not the tag contains any XML attributes. If the tag contains XML attributes, the parsed attribute name takes the value specified in the STORE_CONTENT_AS parameter; otherwise, the parsed attribute name takes the tag name.

The default XML parser accepts the following parameters:

Parameter	Description
MULTIKEY_DELIMITER	Delimiter that separates a list of XML attribute names in the CONTAINER_NAME parameter; default is tilde (~)
STORE_CONTENT_AS	Name to give to parsed attributes derived from element text content, where the element contains XML attributes; default is text_value
CONTAINER_NAME	A list of XML attribute names delimited by the value of the MULTIKEY_DELIMITER parameter. If an attribute name in this list appears in a tag in the original file, the tag becomes a container named for the value of the XML attribute. All other XML attributes become parsed attributes as usual. The tag name itself is discarded. For example, the list includes attribute names Moe and Larry in this order. The original file contains an XML tag Stooges that has attributes Moe, Larry, and Curly. As Moe appears first in the delimited list, its value, leader, becomes the parsed container name; Larry and Curly become parsed attributes. The tag name Stooges is discarded. The original XML fragment might be as follows: <?xml version="1.0" encoding="UTF-8"?> <Comedy> <Stooges Moe="leader", Larry="zany", Curly="bald"> </Stooges> </Comedy>

WebLogic Attribute-keyed Parser

Cloud Control provides an attribute-keyed parser provided by Oracle specifically designed to parse the WebLogic config.xml file. It has the same parameters as the default XML parser and comes with 26 default post-parsing rules to uniquely identify nodes with the same name.

WebSphere Attribute-keyed Parsers

Cloud Control provides several attribute-keyed parsers provided by Oracle designed to parse specific WebSphere configuration files. Each parser has the same parameters as the default XML parser and comes with a set of default post-parsing rules to uniquely identify nodes with the same name. There are parsers for the following WebSphere configuration files:

• node.xml (1 default post-parsing rule)

• plugin-cfg.xml (7 default post-parsing rules)

• resource.xml (9 default post-parsing rules)

• server.xml (13 default post-parsing rules)

• variables.xml (1 default post-parsing rule)

About the Generic XML Parser

Parsing occurs as follows:

• All XML elements become containers.

• All XML attributes become parsed attributes.

• Element text content becomes a parsed attribute that takes the name text_value, where the text content becomes the parsed attribute value.

The generic XML parser accepts no parameters.

WebSphere Generic Parser

Cloud Control provides one generic parser provided by Oracle designed to parse the WebSphere serverindex.xml configuration file. It comes with three default post-parsing rules to uniquely identify nodes with the same name.

XML Parser Examples

This section contains three XML parser examples:

• As parsed using the default XML parser, with parameter values provided by Oracle

• As parsed using the default XML parser, with modified parameter values

• As parsed using the generic XML parser

Parsed examples derive from the following original XML file:

  <?xml version="1.0" encoding="UTF-8"?>
  <Application>
     <AppName>foo</AppName>
     <Server name="ajax" os="linux">production</Server>
  </Application>

Default XML Parser (Parameter Values Provided by Oracle)

When parsed using the default XML parser with parameter values provided by Oracle, the parsed version appears as follows:

  Application
     AppName = foo  
     Server 
        name = ajax
        os = linux
        text_value = production
         

Note the following about this parsed version:

• The element contents of the AppName and Server tags become parsed attributes.

• Since the AppName tag contains no XML attributes, the parsed attribute name takes the tag name.

• Contrast with the Server tag, which has XML attributes (name and os). This results in a container named for the tag (Server), with three parsed attributes, one for each of the XML attributes, and a third for the text content of the Server tag, which is set to the value of the STORE_CONTENT_AS parameter (text_value).

Default XML Parser (Modified Parameter Values)

To modify parameter values, you have to create a new parser by exporting the default XML parser, modifying the exported XML file, and importing the modified parser, using a new name and parser ID.

Assume you followed this process, making the following modifications:

• Set the STORE_CONTENT_AS parameter to the value myVal

• Set the CONTAINER_NAME parameter to the value name

When parsed using the default XML parser with modified parameter values, the parsed version appears as follows:

  Application
     AppName = foo  
     ajax 
        os = linux
        myVal = production
         

Note the following about this parsed version:

• The AppName tag remains the same; that is, it has no XML attributes so it becomes a parsed attribute.

• Since the Server tag has an XML attribute that matches the value of CONTAINER_NAME, the container takes the value of the attribute (ajax), obviating the name=ajax parsed attribute. Remember that the CONTAINER_NAME parameter provided by Oracle has a placeholder but no actual default value; thus, the difference in this version of the parsed representation.

• The remaining Server tag attribute (os) becomes a parsed attribute as usual, and the text content associated with the tag becomes the value of the attribute myVal, per the edited STORE_CONTENT_AS parameter.

Generic XML Parser

When parsed using the generic XML parser (the one that takes no parameters), the parsed version appears as follows:

  Application
     AppName 
        text_value = foo
     Server 
        name = ajax
        os = linux
        text_value = production
         

See About the Default XML Parser for a reminder of how parsing occurs.

About Format-Specific Parsers

Format-specific base parsers are applicable only to a particular data format. Format-specific parsers run the gamut from having no parameters to a few to many with which to tailor formatting.

Parser	Description
Blue Martini DNA	Parser for Blue Martini DNA files (no parameters).
Connect:Direct	Parser for Connect:Direct .cfg files (no parameters).
Database Query (see Sample SQL Query Parsing and Rule Application for an example)	Parser for configuration extension database query output. Cloud Control automatically transforms query results into a format the parser accepts, organizing results into sections similar to a Windows .ini file. Each section represents one record; each line in a section contains a table column name and a value. See Database Query Parser Parameters.
Database Query Paired Column	Parser for configuration extension database query output. Cloud Control automatically transforms query results into a format the parser accepts, organizing results into sections similar to a Windows .ini file. Each section represents one record; each line in a section contains a name and value, where both the name and the value are values of returned columns. As such, the parser requires an even number of columns to be returned by the query in order to parse the data. A query which returns an odd number of columns will result in a parsing error. See Database Query Paired Column Parser Parameters.
Db2	Parser for the output of the DB2 GET DATABASE CONFIGURATION command (no parameters).
Directory	Parser for files containing multiple name value pairs on the same line, where each line may have varying numbers of pairs. For example, the first line might be a=b j=k, the second line c=d m=n y=z, and so forth. See Directory Parser Parameters.
E-Business Suite	Parser for E-Business Suite .drv files. The parser converts IF...THEN...ELSE structures in the file into containers in the parsed representation, and the rest of the lines into a container with a fixed number of parsed attributes. These lines can be of two types: directory specifications, whose parsed attribute names are specified in the DIR_HEADER parser parameter; configuration file specifications, whose parsed attribute names are specified in the HEADER parser parameter. See E-Business Suite Parser Parameters.
Galaxy CFG	Parser for Galaxy .cfg files. See Galaxy CFG Parser Parameters.
Introscope	Parser for Introscope files (no parameters).
MQ-Series	Parser for MQ-Series files. See MQ-Series Parser Parameters.
Odin	Parser for Odin files (no parameters).
Oracle ORA	Parser for Oracle .ora files, such as tnsnames.ora (no parameters).
Siebel	Parser for Siebel siebns files. The parser creates a container for each unique path in the file, and attributes for name value pairs, except where a line contains the string Type=empty, in which case the parser does not create a parsed attribute for the line. See Siebel Parser Parameters.
UbbConfig	Parser for BEA Tuxedo files (no parameters). The parser converts sections prefixed with an asterisk (*), and names in double quotes at the start of a new line, into containers. It converts all other data into attributes.
Unix Installed Patches	Parser for Unix installed patches data. The parser creates one container per (non-comment) line of the file. It treats every field ending with a colon (:) on each line as a property name field and the value following, if any, as the property value. Note that a property does not have to have a value. See Unix Installed Patches Parser Parameters.
Unix Recursive Directory List	Parser for output of Unix recursive directory listing (ls -l -R). The parser converts each subdirectory line into a container, and each file information line into a container with a fixed set of attributes. See Unix Recursive Directory List Parser Parameters.

Remember, to modify a format-specific parser, you have to create a new parser by exporting the particular parser, modifying the exported XML file, and importing the modified parser, using a new name and parser ID.

Database Query Parser Parameters

The following table describes the parameters with which you can customize the Database Query parser:

Parameter	Description
CELL_DELIMITER	Character that separates name value pairs; default is =.
PROPERTY_DELIMITER	Character that separates the length of a name or value from the value itself; default is _.
COMMENT	Character that tells the parser to ignore the line that follows; default is #.
SECTION_START	Character that denotes the start of a section; default is \[ (backslash is escape character).
SECTION_END	Character that denotes the end of a section; default is \] (backslash is escape character).
USE_INI_SECTION	Flag that tells the parser to use Windows .ini type sections; default is true.

Database Query Paired Column Parser Parameters

The following table describes the parameters with which you can customize the Database Query parser:

Parameter	Description
CELL_DELIMITER	Character that separates name value pairs; default is =.
PROPERTY_DELIMITER	Character that separates the length of a name or value from the value itself; default is _.
COMMENT	Character that tells the parser to ignore the line that follows; default is #.
SECTION_START	Character that denotes the start of a section; default is \[ (backslash is escape character).
SECTION_END	Character that denotes the end of a section; default is \] (backslash is escape character).
USE_INI_SECTION	Flag that tells the parser to use Windows .ini type sections; default is true.

Directory Parser Parameters

The following table describes the parameters with which you can customize the Directory parser:

Parameter	Description
CELL_DELIMITER	Character that separates one property from another; default is a space.
EXTRA_DELIMITER	Character that separates a property name from its value; default is =.
COMMENT	Character that tells the parser to ignore the line that follows; default is #.

E-Business Suite Parser Parameters

The following table describes the parameters with which you can customize the E-Business Suite parser:

Parameter	Description
DIR_HEADER	A tilde-delimited list of attribute names for directory specifications.
STRUCTURE_START	A tilde-delimited list of regular expressions denoting the start of a structure.
CELL_DELIMITER	A tilde-delimited list of regular expressions denoting name value pair delimiters.
HEADER	A tilde-delimited list of attribute names for file specifications.
COMMENT	A tilde-delimited list of regular expressions denoting comments.
STRUCTURE_END	A tilde-delimited list of regular expressions denoting the end of a structure.
LAST_FREE_FORM	Flag that tells the parser to ignore cell delimiters in the last value of a directory or file specification; default is true.
ELEMENT_FIELD	A tilde-delimited list of file specification attribute names. The parser concatenates values of the specified attributes to form the name of the container associated with the file specification.
DIR_ELEMENT_FIELD	A tilde-delimited list of directory specification attribute names the parser uses to determine the name of the container associated with the directory specification.

Galaxy CFG Parser Parameters

The following table describes the parameters with which you can customize the Galaxy CFG parser:

Parameter	Description
COMMENT	Character that tells the parser to ignore the line that follows; default is !.
ADD_SUFFIX	Names of attributes whose values to append to a container name.
MONO_PROP_SECTION	Names of sections that have a single property.
MULTI_PROP_SECTION	Names of sections that have multiple properties.
NODES_SECTION	Names of section start and end elements

MQ-Series Parser Parameters

The MQ-Series parser has a single parameter that you can customize: COMMENT, which defaults to *.

Siebel Parser Parameters

The following table describes the parameters with which you can customize the Siebel parser:

Parameter	Description
LINES_TO_SKIP	Tells the parser the number of lines to ignore at the beginning of the file; default is 4.
CELL_DELIMITER	A tilde-delimited list of regular expressions denoting name value pair delimiters.
COMMENT	A tilde -delimited list of regular expressions denoting comments.
SECTION_START	A tilde-delimited list of regular expressions denoting the start of a unique path specification section.
SECTION_END	A tilde-delimited list of regular expressions denoting the end of a unique path specification section.
USE_INI_SECTION	Flag that tells the parser to use Windows .ini type sections; default is true.

Unix Installed Patches Parser Parameters

The following table describes the parameters with which you can customize the Unix Installed Patches parser:

Parameter	Description
CELL_DELIMITER	Character that separates name value pairs; default is a space.
EXTRA_DELIMITER	Character that separates a property name from its value; default is :.
COMMENT	Character that tells the parser to ignore the line that follows; default is #.

Unix Recursive Directory List Parser Parameters

The following table describes the parameters with which you can customize the Unix Recursive Directory List parser:

Parameter	Description
LINES_TO_SKIP	Tells the parser the number of lines to ignore at the beginning of the file; default is 4.
CELL_DELIMITER	A tilde-delimited list of regular expressions denoting name value pair delimiters.
COMMENT	A tilde-delimited list of regular expressions denoting comments.
HEADER	A tilde-delimited list of attribute names.
LAST_FREE_FORM	Flag that tells the parser to ignore cell delimiters in the last value of a line; default is true.
SECTION_START	A tilde-delimited list of regular expressions denoting the start of a subdirectory section.
SECTION_END	A tilde-delimited list of regular expressions denoting the end of a subdirectory section.
ELEMENT_FIELD	A tilde-delimited list of attribute names. The parser concatenates values of the specified attributes to form the name of the container associated with the line.

About Columnar Parsers

Columnar parsers are inherently flexible owing to the parameters they can accept to tailor formatting. All columnar parsers use a subset of the same parameters.

Parser	Description
Cron Access	Parser for cron.allow and cron.deny files.
Cron Directory	Parser for Unix etc and cron.d files.
CSV	Parser for comma-separated-value (CSV) data. Because the number of columns in the CSV parser is unknown, use the CSV parser provided by Oracle as a template for the new CSV parser. Export the provided CSV parser, update the parameters, and re-import the new CSV parser tailored to your format. The parameter values provided by Oracle support CSV files with these characteristics: Each line has the same number of values The first parsed (that is, non-comment) line is a header line whose content is a comma-separated list of column names Commas in double quotes are considered part of the value, not value delimiters One of the column names is "name" whose value becomes the container name associated with each line Text inside double quotes is considered part of a value; to specify a value that contains a double quote, escape the double quote with a backslash (\). Use a backslash to escape the backslash character itself (\\).
Hosts Access	Parser for hosts.allow and hosts.deny files.
Kernel Modules	Parser for kernel modules files.
Linux Directory List	Parser for Linux directory listing data format (for example, output of a ls -l command).
PAM Configuration	Parser for pam.conf files.
PAM Directory	Parser for Unix etc/pam.d files.
Process Local	Parser for process.local files.
Secure TTY	Parser for Unix etc/securetty files.
Solaris Installed Packages	Parser for Solaris installed packages files.
Unix Crontab	Parser for Unix crontab files.
Unix Directory List	Parser for Unix directory listing data format for example, the output of a ls -l command).
Unix Groups	Parser for Unix etc/group files. The parser ignores group name and password information.
Unix GShadow	Parser for Unix etc/gshadow files.
Unix Hosts	Parser for Unix etc/hosts files.
Unix INETD	Parser for Unix etc/inetd.conf files.
Unix Passwd	Parser for Unix etc/passwd files. The parser ignores password values.
Unix Protocols	Parser for Unix etc/hosts files.
Unix Services	Parser for Unix etc/services.conf files.
Unix Shadow	Parser for Unix etc/shadow files.
Unix System Crontab	Parser for Unix system crontab files. System crontab files are very similar to crontab files, but may contain name value pairs such as PATH=/a/b.

Columnar Parser Parameters

This section describes all columnar base parser parameters. Although the base parser can accept values for any of these parameters, a given parser specification does not necessarily need to provide values for all of them. All parameters have default values, which are used in the absence of a specified value, although in some cases, parameters have explicit values.

Use quotes when delimiters or other special text such as comment characters or new lines are part of some value. The QUOTE_DELIMITER determines the character value to use. Prefix the quote delimiter with a backslash (\) if you need to escape the character. Use a backslash to escape the backslash character itself (\\) in quoted strings.

Parameter	Description
COMMENT	A tilde-delimited list of regular expressions that denote comment characters or sequences. For example, #[^\r\n]* specifies that everything on a line following the # character is a comment. Default is an empty list; that is, parse all file contents.
LINES_TO_SKIP	The number of initial lines (excluding blank or comment lines) to ignore for parsing purposes, treating them in effect as comments. Default is 0; that is, skip no lines.
CELL_DELIMITER	A tilde-delimited list of regular expressions that delimit line values. Default is an empty list; that is, no delimiters (it is unusual to use the default).
QUOTE_DELIMITER	A tilde-delimited list of regular expressions that define how quoted values begin and end (usually either a single or double quote character). The beginning and end quote delimiter must be the same. Default is an empty list; that is, parser does not recognize quoted values.
PROPERTY_DELIMITER	A tilde-delimited list of regular expressions that delimit property names and values. Default is an empty list; that is, no property delimiters. Rarely, a columnar file may contain name value pairs of the syntax a=b.
RESERVED_DIRECTIVES	A tilde-delimited list of property keywords. Some crontab files contain lines of simple name value pairs, separated by a delimiter (foo=bar), thus violating the requirement that each line have the same number of fields. This parameter provides a workaround to specify property keywords. In the example, the property keyword would be foo. This says, in effect, parse any line beginning with this keyword as a parsed attribute name value pair under the root container. Default is an empty list; that is, no property keywords.
ALTERNATE_DELIMITER	An alternate delimiter for property names and values. Default is '/' (used only if ALTERNATE_FIELD parameter is nonempty).
ALTERNATE_FIELD	A tilde-delimited list of fields separated by alternate delimiters. Default is an empty list; that is, no alternate delimiters.
HEADER_FLAG	A flag specifying whether or not the file has a header line that specifies the column names. Default is false.
HEADER	A tilde-delimited list of column names to use if there is no header line. Default is an empty list; that is, no column names (it is unusual to use the default).
ELEMENT_FIELD	A tilde-delimited list of column names whose values the parser concatenates to create the container name associated with a line. Default is an empty list; that is, no column names (it is unusual to use the default).
IGNORE_FIELD	A tilde-delimited list of column names to ignore. No parsing of values in these columns occurs. Default is an empty list; that is, ignore nothing.
LAST_FREE_FORM	A flag that specifies whether the last column is free form. The parser ignores all delimiters in a free form column value. Default is false.
USE_LINE_COMMENT	A flag that specifies whether to treat end of line comments as a value to appear in the parsed representation of the data. Default is false.

About Properties Parsers

Properties parsers are inherently flexible owing to the parameters they can accept to tailor formatting and handle disparate organizational elements. All properties parsers use the same set of basic and advanced parameters, as well as advanced constructs.

Parser	Description
AIX Installed Packages	Parser for AIX installed packages files.
Apache HTTPD	Parser for Apache HTTPD.conf files.
Autosys	Parser for Autosys.jil files.
Custom CFG	Parser for custom .cfg files. This syntax defines an element with E = {} syntax, where the brackets may contain name value pairs, nested elements, or both.
Java Policy	Parser for java.policy files.
Java Properties	Parser for java.properties files.
LDAP	Parser for LDAP .cfg files.
Mime Types	Parser for mime.types files.
Radia	Parser for Radia .cfg files.
Sectioned Properties	Parser for files containing name value pairs organized into sections, such as a Windows .ini file.
SiteMinder Agent	Parser for SiteMinder agent files.
SiteMinder Registry	Parser for SiteMinder .registry files.
SiteMinder Report	Parser for SiteMinder SmReport.txt files.
SmWalker	Parser for SiteMinder SmWalker.dat files.
Sun ONE Magnus	Parser for Sun ONE magnus.conf files.
Sun ONE Obj	Parser for Sun ONE obj.conf files.
Tuxedo	Parser for Tuxedo files.
Unix Config	Parser for Unix etc/config files.
Unix Login	Parser for Unix etc/login.defs files.
Unix PROFTPD	Parser for Unix etc/proftpd.conf files.
Unix Resolve	Parser for Unix etc/resolve.conf files.
Unix SSH Config	Parser for Unix etc/ssh/sshd.conf files.
Unix System	Parser for Unix etc/system files.
Unix VSFTPD	Parser for Unix etc/vsftpd.conf files.
Unix XINETD	Parser for Unix etc/xinetd.conf files.
WebAgent	Parser for WebAgent files.
Windows Checksum	Parser for Windows checksum output generated with fciv.exe.

Basic Properties Parser Parameters

This section describes basic properties parser parameters that are required to parse simple property data formats. Simple property data formats specify a property as a name value pair, usually with a defined delimiter separating the name and the value: foo=bar. The basic data format is a list of properties, one property to a line, together with optional comments; a java.properties file, for example. All parameters have default values, which are used in the absence of a specified value.

Use quotes when delimiters or other special text such as comment characters or new lines are part of some value. The QUOTE_DELIMITER determines the character value to use. Prefix the quote delimiter with a backslash (\) if you need to escape the character. Use a backslash to escape the backslash character itself (\\) in quoted strings.

A comment character such as the pound sign (#), or a particular character sequence (//) usually denotes a comment. Special sequences such as a C style comment (/*….*/) might denote the beginning and end of a comment. Some files might have generic informational content in the first couple of lines. In this case, a parameter is available to tell the parser to ignore these lines.

Parameter	Description
COMMENT	A tilde-delimited list of regular expressions that denote comment characters or sequences. For example, #[^\r\n]* specifies that everything on a line following the # character is a comment. Default is an empty list; that is, parse all file contents.
LINES_TO_SKIP	The number of initial lines (excluding blank or comment lines) to ignore for parsing purposes, treating them in effect as comments. Default is 0; that is, skip no lines.
CELL_DELIMITER	A tilde-delimited list of regular expressions that delimit line values. Default is an empty list; that is, no delimiters (it is unusual to use the default).
QUOTE_DELIMITER	A tilde-delimited list of regular expressions that define how quoted values begin and end (usually either a single or double quote character). The beginning and end quote delimiter must be the same. Default is an empty list; that is, parser does not recognize quoted values.
ALLOW_NAME_ONLY_PROPERTIES	A flag that indicates whether the parser allows property names without a delimiter or a value. Default: false.
REVERSE_PROPERTY	A flag that indicates whether the parser allows the value to come before the delimiter and property name. Default: false.

Advanced Properties Parser Parameters

This section describes advanced properties parser parameters that are required to parse more complex property data formats. All parameters have default values, which are used in the absence of a specified value.

Parameter	Description
PROPERTY_DELIMITER	A tilde-delimited list of regular expressions denoting property delimiters. For example, the text "a=b : x=y" could be interpreted in either of two ways: As a single property "a" with value "b : x=y" As two separate properties, "a=b" and "x=y" If a colon (:) is the property delimiter, the parsing engine interprets the text as containing two separate properties. Default is an empty list; that is, parser does not recognize property delimiters.
LINE_END_DELIMITER	A tilde-delimited list of regular expressions denoting line end sequences. When the parser encounters a line end delimiter, it assumes a new property or construct starts on the next line. Default is an empty list; that is, parser does not recognize line end delimiters.
CONTINUE_LINE	A tilde-delimited list of regular expressions denoting continue line sequences. When the parser encounters a continue line pattern, it interprets data on the following line as a continuation of the construct or property on the previous line, as opposed to interpreting the new line as the beginning of a new property or construct. For example, the parser must encounter a line continuation pattern to recognize property values that span multiple lines. Default is an empty list; that is, parser does not recognize line continuation patterns.
SECTION_START	A tilde-delimited list of regular expressions denoting the beginning of a section. Sections cannot be nested. Default is an empty list; that is, parser does not recognize sections.
SECTION_END	A tilde-delimited list of regular expressions denoting the end of a section. Default is an empty list.
STRUCTURE_START	A tilde-delimited list of regular expressions denoting the beginning of a structure. Structures can be nested. Default is an empty list; that is, parser does not recognize structures.
STRUCTURE_END	A tilde-delimited list of regular expressions denoting the end of a structure. Default is an empty list.
XML_STYLE_TAG	A flag that indicates whether structures in the file are XML style tags. Default: false.
USE_INI_SECTION	A flag that indicates whether INI style sections are present. Default: false.
RESERVED_DIRECTIVES	A tilde-delimited list of reserved names indicating the start of a reserved directive. Default is an empty list; that is, parser does not recognize reserved directives.
RESERVED_FUNCTIONS	A tilde-delimited list of reserved names indicating the start of a reserved function. Default is an empty list; that is, parser does not recognize reserved functions.
DIRECTIVE_PROPERTIES	A tilde-delimited list of reserved directive- implicit property names. Default is an empty list.
FUNCTION_PROPERTIES	A tilde-delimited list of required reserved function-explicit property names. Default is an empty list.
SECTION_PROPERTIES	A tilde-delimited list of section-implicit property names. Default is an empty list.
STRUCTURE_PROPERTIES	A tilde-delimited list of structure-implicit property names. Default is an empty list.
ELEMENT_FIELD	A keyword to be ignored by the parser when parsing properties. This typically applies to data formats that specify a keyword before a name value pair; "set a=b" for example. Default is an empty list; that is, parser ignores nothing.
ALLOW_ELEMENT_CELL	A flag that indicates whether the file format supports element cell structures. Default: false.
SECTION_EXPLICIT_PROPERTIES	A flag that indicates whether sections support explicit properties. Default: false.
STRUCTURE_EXPLICIT_PROPERTIES	A flag that indicates whether structures support explicit properties. Default: false.
NEWLINE_CONTINUE_LIN	A flag that indicates whether newlines can be line continuation sequences. Default: false.
KEYWORD_FIELD	A tilde-delimited list of regular expressions denoting keywords that precede properties that use a whitespace delimiter. Default is an empty list; that is, parser does not recognize keywords.

Advanced Properties Parser Constructs

Properties files come in variety of file formats. To accommodate the widest possible range of formats, the generic properties base parser uses combinations of constructs found in most files.

The constructs fall into two categories:

• Container constructs, which can be reserved functions, reserved directives, XML structures, structures, delimited structures, INI sections, delimited sections, sections, and element cells

• Property constructs, which can be simple properties, reverse properties, keyword properties, keyword name properties, bracket properties, implicit properties and explicit properties

Of the element constructs, section constructs cannot be nested, but can contain any other construct. Structure constructs can be nested, and can contain any construct except a section. Element cells can be nested, but can only contain element cells and simple properties. Reserved directives and reserved functions cannot be nested, nor can they contain any other constructs.

The rest of this section describes the constructs the base properties parser supports.

Simple Property

A simple property consists of a property name, cell delimiter, property value, and newline sequence, in that order. A simple property may take up more than one line, although properties that span multiple lines usually contain a line continuation character or sequence. The parser ignores whitespace such as tabs and spaces, unless a parameter specifies whitespace as having some significance (cell delimiter, for example).

Example: name=value_that_wraps_to_next_line_/, where the forward slash serves as a line continuation character. A Java Properties file typifies this data format.

Keyword Property

This construct is the same as a simple property, only with a keyword in front, which the parser ignores.

Example: set name=value, where set is the ignored keyword. A Unix System file typifies this data format.

Keyword Name Property

This construct is a simple property where the property name matches a regular expression specified in the KEYWORD_FIELD parser parameter. This is a special case property type specific to the Unix XINETD parser. The XINETD file uses an equal sign (=) as a cell delimiter except when the property begins with the keyword "include" or "includedir", in which case the cell delimiter is whitespace.

While added specifically for XINETD files, the property can be used for other file types where appropriate.

Example: includedir /etc, where includedir is the parser parameter regular expression and whitespace is the cell delimiter.

Explicit Property

An explicit property consists of a property name, a delimiter, and a property value. Unlike a simple or keyword property, an explicit property is bound to a container construct such as a section or a structure; an XML tag attribute, for example.

Examples:

[SectionName p1=v1 p2=v2]

<StructureName p1=v1 p2=v2>
...
</StructureName>

In these constructs, the name value pairs p1 v1 and p2 v2 are explicit properties. A Sun ONE Obj file typifies this data format.

Implicit Property

An implicit property is a property value without an associated property name. Like an explicit property, an implicit property is bound to a container construct, usually a reserved directive. The DIRECTIVE_PROPERTIES parser parameter contains the property names of implicit properties.

Examples:

[SectionName myName myPath]

<StructureName myName myPath>
...
</StructureName>

In these constructs, the implicit properties have the values myName and myPath, with the presumed property names name and path, as declared in the DIRECTIVE_PROPERTIES parser parameter. An Apache HTTPD file typifies this data format.

Reserved Function

A reserved function is a keyword followed by one or more explicit properties. The RESERVED_FUNCTIONS parser parameter specifies keywords that denote reserved functions.

Example: Error fn="query-handler" type="forbidden", where Error is the reserved function keyword specified in the RESERVED_FUNCTIONS parser parameter. A Sun ONE Magnus file typifies this data format.

Reserved Directive

A reserved directive is a keyword followed by one or more implicit properties. The RESERVED_DIRECTIVES parser parameter specifies keywords that denote reserved directives.

Example: LoadModule cgi_module "/bin/modules/std/cgi", where LoadModule is the reserved function keyword specified in the RESERVED_DIRECTIVES parser parameter. An Apache HTTPD file typifies this data format.

XML Structure

An XML structure is a standard XML tag that can contain a name only, a name followed by explicit properties, or a name followed by implicit properties.

Examples:

<Name>
...
</Name>

<Name p1=v1 p2=v2>
...
</Name>
<Name "implicit_property1" "implicit_property2">
...
</Name>

A WebAgent file typifies this data format.

Delimited Structure

A delimited structure consists of the following (in the specified order):

• Structure name

• Delimiter

• Start structure character or character sequence

• Structure contents

• End structure character or character sequence

Example:

StructureName = {
...
}

Explicit and implicit properties are not allowed. Java Policy and Custom CFG files typify this data format.

Structure

A structure consists of the following (in the specified order):

• Structure name

• Start structure character or character sequence

• Structure contents

• End structure character or character sequence

The only difference between a delimited structure and a structure is the delimiter; that is, a structure does not require a delimiter between the structure name and the start structure indicator.

Example:

StructureName {
...
}

Explicit and implicit properties are not allowed. A Unix XINETD file typifies this data format.

INI Section

And INI section resembles a section heading in a Windows .ini file, characterized by:

• Section start character or character sequence

• Section name

• Optional (explicit and implicit) properties

• Section end character or character sequence

Examples:

[SectionName]

[SectionName p1=v1 p2=v2]

[SectionName "implicit_property1" "implicit_ property2"]

SmWalker and Sectioned Properties files typify this data format.

Delimited Section

A delimited section is a line that begins with a common pattern, but otherwise resembles a simple property.

Examples:

HKEY_LOCAL_MACHINE\SOFTWARE\A\B\C=789

HKEY_LOCAL_MACHINE\SOFTWARE\X\Y\Z=123

These are two delimited section headings where the common pattern is HKEY_. SiteMinder Registry and LDAP files typify this data format.

Element Cell

An element cell consists of an element cell name and a property name value pair of the form A = B = C. Element cells typically use line continuation sequences and nesting to clarify the structure. An element cell that has multiple properties uses a property delimiter to separate them.

Example 1:

EC = \
    B = C, D = F

This example is an element cell named EC with two property name value pairs, B = C and D = F, separated by a comma. The structure uses the backslash character (\) to indicate line continuation. The advanced properties parser parameters PROPERTY_DELIMITER and CONTINUE_LINE define the respective format characters.

Example 2:

EC = \
              EC2 = \
                             A = B, \
                             C = D

This example is an element cell named EC that has a nested element cell named EC2 that contains two property name value pairs, A = B and C = D. This example uses the same delimiter and line continuation characters.

Using Parsed Files and Rules

A collected configuration file is stored in raw form and, if a parser is specified, in a tree structure of nodes, or containers, and attributes, or properties. The file also is generated internally in XML format for the purpose of applying post-parsing rules, which consist of XPath conditions and expressions. Note that even non-XML files are generated in this internal format. Since the internal format must accommodate other file types, it introduces an additional root node in the XML to compensate for files such as Java properties files that have only attribute names and values.

Examples of how files are parsed and displayed, and the effects of post-parsing rules help to clarify:

• Sample XML File Parsing and Rule Application

• Sample Non-XML File Parsing and Rule Application

• Sample SQL Query Parsing and Rule Application

Sample XML File Parsing and Rule Application

Consider the following simple XML file:

  <dir name="/a/b/c">    
    <file name="file1" size=120/>    
    <file name="file2" size=350/>    
  </dir>

Its parsed form, using the default XML parser, appears in the user interface in the following tree structure:

  dir
     	name    = /a/b/c
        file
                name = file1
                size = 120
        file
                name = file2
                size = 350
         	

Notice that two containers have the same name (file), which makes it impossible to distinguish between the two, at the container level, at least. Thus, this file is a candidate for a post-parsing rule. As mentioned, there is a special internal XML format against which to apply a rule's XPath condition and expression. This format treats nodes and attributes as XML elements, and converts attribute values into corresponding element text content. It also adds a root element that doesn't appear in the original file:

  <root>  
    <dir>
        <name>/a/b/c</name>
        <file>
              <name>file1</name>
              <size>120</size>
        </file>
        <file>
              <name>file2</name>
              <size>350</size>
        </file>
    </dir>
  </root>

Given the problem in the parsed form of having two containers with the same name, a rule resolution might consist of the following:

• Condition: /root/dir/file
• Expression: name/text()

Effectively, this says: for each file evaluate name/text() to produce an identifier that distinguishes one file from another within the dir node.

After applying the post-parsing rule, the parsed tree structure appears as follows:

  dir
        name = /a/b/c
        file[file1]
              name = file1
              size = 120
        file[file2]
              name = file2
              size = 350
         

The rule resolves to an identifier appended in square brackets to the container name. The combination (file[file1], for example) enables various operations such as compare, search, change history, and so forth, to distinguish between file containers.

Sample Non-XML File Parsing and Rule Application

Consider the following simple ORA file:

  acme=
     (DESCRIPTION=
        (SOURCE_ROUTE=yes)
        (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))
        (ADDRESS_LIST=
           (FAILOVER=on)
           (LOAD_BALANCE=off)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host2a)(PORT=1630))
           (ADDRESS=(PROTOCOL=tcp)(HOST=host2b)(PORT=1630)))
        (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1630))
        (CONNECT_DATA=(SERVICE_NAME=xyz.example.com)))

Its parsed form, using the Oracle ORA parser, appears in the user interface in the following tree structure:

  acme
          DESCRIPTION
               SOURCE_ROUTE    yes
               ADDRESS
                       PROTOCOL         tcp
                       HOST             host1
                       PORT             1630
               ADDRESS_LIST
                       FAILOVER         on
                       LOAD_BALANCE     off
                       ADDRESS
                               PROTOCOL          tcp
                               HOST              host2a
                               PORT              1630
                       ADDRESS
                               PROTOCOL          tcp
                               HOST              host2b
                               PORT              1630
               ADDRESS
                       PROTOCOL         tcp
                       HOST             host3
                       PORT             1630
               CONNECT_DATA
                       SERVICE_NAME     xyz.example.com

Notice that the address containers, both standalone and within ADDRESS_LIST are indistinguishable. Thus, this file is a candidate for a post-parsing rule. As mentioned, there is a special internal XML format against which to apply a rule's XPath condition and expression. This format treats nodes and attributes as XML elements, and converts attribute values into corresponding element text content. It also adds a root element that doesn't appear in the original file:

  <root>
          <acme>
                  <DESCRIPTION>
                          <SOURCE_ROUTE>yes</SOURCE_ROUTE>
                          <ADDRESS>
                                  <PROTOCOL>tcp</PROTOCOL>
                                  <HOST>host1</HOST>
                                  <PORT>1630</PORT>
                          </ADDRESS>
                          <ADDRESS_LIST>
                                  <FAILOVER>on</FAILOVER>
                                  <LOAD_BALANCE>off</LOAD_BALANCE>
                                  <ADDRESS>
                                          <PROTOCOL>tcp</PROTOCOL>
                                          <HOST>host2a</HOST>
                                          <PORT>1630</PORT>
                                  </ADDRESS>
                                  <ADDRESS>
                                          <PROTOCOL>tcp</PROTOCOL>
                                          <HOST>host2b</HOST>
                                          <PORT>1630</PORT>
                                  </ADDRESS>
                          </ADDRESS_LIST>
                          <ADDRESS>
                                  <PROTOCOL>tcp</PROTOCOL>
                                  <HOST>host3</HOST>
                                  <PORT>1630</PORT>
                          </ADDRESS>
                          <CONNECT_DATA>
                                  <SERVICE_NAME>xyz.example.com</SERVICE_NAME>
                          </CONNECT_DATA>
                  </DESCRIPTION>
          </acme>
  </root>

Given the problem in the parsed form of having containers with the same name, a rule resolution might consist of the following:

• Condition: //ADDRESS
• Expression:/HOST/text()

Effectively, this says: for each address element evaluate /HOST/text() to extract the host name as the address identifier.

After applying the post-parsing rule, the parsed tree structure appears as follows:

  acme
          DESCRIPTION
               SOURCE_ROUTE    yes
               ADDRESS[host1]
                       PROTOCOL         tcp
                       HOST             host1
                       PORT             1630
               ADDRESS_LIST
                       FAILOVER         on
                       LOAD_BALANCE     off
                       ADDRESS[host2a]
                               PROTOCOL          tcp
                               HOST              host2a
                               PORT              1630
                       ADDRESS[host2b]
                               PROTOCOL          tcp
                               HOST              host2b
                               PORT              1630
               ADDRESS[host3]
                       PROTOCOL         tcp
                       HOST             host3
                       PORT             1630
               CONNECT_DATA
                       SERVICE_NAME     xyz.example.com

The rule resolves to an identifier appended in square brackets to the container name. The combination (ADDRESS[host2a], for example) enables various operations such as compare, search, change history, and so forth, to distinguish between address containers.

Sample SQL Query Parsing and Rule Application

Consider the following three-column database table SERVER_DETAILS:

SERVER_NAME	ENVIRONMENT	HOSTED_APPLICATIONS
webserver-100	QA	5
webserver-200	PERFORMANCE	6
webserver-500	PRODUCTION	3

The SQL query expressed as part of the configuration extension creation is as follows:

select * from SERVER_DETAILS

This query returns the following raw output:

  [row]
  11_SERVER_NAME=13_ webserver-100
  11_ENVIRONMENT=2_ QA
  19_HOSTED_APPLICATIONS=1_5
  [row]
  11_SERVER_NAME=13_ webserver-200
  11_ENVIRONMENT=11_ PERFORMANCE
  19_HOSTED_APPLICATIONS=1_6
  [row]
  11_SERVER_NAME=13_ webserver-500
  11_ENVIRONMENT=10_ PRODUCTION
  19_HOSTED_APPLICATIONS=1_3

The Configuration Browser Source tab renders the data the same way.

Its parsed form, using the Database Query parser, appears in the user interface in the following tree structure:

  row
         SERVER_NAME=webserver-100
         ENVIRONMENT=QA
         HOSTED_APPLICATIONS=5
  row
         SERVER_NAME=webserver-200
         ENVIRONMENT=PERFORMANCE
         HOSTED_APPLICATIONS=6
  row
         SERVER_NAME=webserver-500
         ENVIRONMENT=PRODUCTION
         HOSTED_APPLICATIONS=3

Notice that the row containers are indistinguishable. Thus, this query result is a candidate for a post-parsing rule. As mentioned, there is a special internal XML format against which to apply a rule's XPath condition and expression. This format treats nodes and attributes as XML elements, and converts attribute values into corresponding element text content. It also adds a root element that doesn't appear in the original file:

  <root>
              <row>
                          <SERVER_NAME>webserver-100</SERVER_NAME>
                          <ENVIRONMENT>QA</ENVIRONMENT>
                          <HOSTED_APPLICATIONS>5</HOSTED_APPLICATIONS>
              </row>
              <row>
                          <SERVER_NAME>webserver-200</SERVER_NAME>
                          <ENVIRONMENT>PERFORMANCE</ENVIRONMENT>
                          <HOSTED_APPLICATIONS>6</HOSTED_APPLICATIONS>
              </row>
              <row>
                          <SERVER_NAME>webserver-500</SERVER_NAME>
                          <ENVIRONMENT>PRODUCTION</ENVIRONMENT>
                          <HOSTED_APPLICATIONS>3</HOSTED_APPLICATIONS>
              </row>
  </root> 

Given the problem in the parsed form of having three containers with the same name, a rule resolution might consist of the following:

• Condition:/root/row/SERVER_NAME
• Expression:SERVER_NAME/text()

Effectively, this says: for each row evaluate SERVER_NAME/text() to produce an identifier that distinguishes one row from another within the tree structure.

After applying the post-parsing rule, the parsed tree structure appears as follows:

  row[webserver-100]
         SERVER_NAME=webserver-100
         ENVIRONMENT=QA
         HOSTED_APPLICATIONS=5
  row[webserver-200]
         SERVER_NAME=webserver-200
         ENVIRONMENT=PERFORMANCE
         HOSTED_APPLICATIONS=6
  row[webserver-500]
         SERVER_NAME=webserver-500
         ENVIRONMENT=PRODUCTION
         HOSTED_APPLICATIONS=3

The rule resolves to an identifier appended in square brackets to the container name. The combination (row[webserver-100], for example) enables various operations such as compare, search, change history, and so forth, to distinguish between row containers.