Develop > Application Configuration > CML reference > CML tag types

CML tag types

The following are the main CML tags. These are described in detail below.

Comment Tag: @# and @##

This tag defines a comment in the CML template file. You can define one line comments or multiple line comments.

Syntax

@#   <one line comment>

Or:

@## <comments spanning multiple lines> 
    <comments spanning multiple lines> 
    <comments spanning multiple lines> #@

Description

The comment tag can be used to insert comments anywhere in your CML file.

As a best practice, use the comment tag at the beginning of a CML template to create a header describing the template, such as the name of the template, the configuration file the template is based on, the purpose of the template, the author, the date, and so on.

Attributes

None.

Examples

The following is a one line comment:

@# This comment ends at the end of this line.

The following is a multiple line comment:

@##

This comment spans

   multiple lines.

#@

The following is also a multiple line comment:

@########################################################
# /etc/hosts (multiplatform) #
# $Id: hosts.tpl 8650 2006-06-05 05:28:03Z joe_author $ #########################################################@

Replace Tag: @

This tag replaces text in the template file with a value from the value set.

Syntax

@{source}[;[{type}][;[{range}[;{option}[;{option}]...]]]]@

Description

The replace tag replaces the tag in a CML line with the data from the specified location in the name space. It is an indicator that the text in this location is data, and it also specifies details about how that data should be stored and validated. The source name is the index key where the data is found in the value set. The other fields of the replacement tag specify details about how the data should be stored and validated.

The replace tag is the only tag that is not indicated by a special character following the “@” character. The only required element in a replace tag is the source. All other elements are optional.

Attributes

  • Source: The source attribute is the key used to store and access the value in the value set. If the source attribute is relative (that is, it does not start with a “/” or a “.”) it gets appended to the current name space and becomes part of the key used to store the value read by this tag. If the name is absolute (that is, it starts with a “/”) it is the key, and the value gets stored under this key.
  • The only required element in a replace tag is the source. All other elements are optional. If the name starts with a “.”, it will be appended to the name space of the loop it is a part of. Tags inside a loop typically start with a “.”.
  • Type: The type attribute specifies the type of the replace tag, which applies certain predefined restrictions and error checking to different values. The default type for replace tags is “string”.
  • The available types are described at CML type attributes.
  • Range: The range attribute allows you to set the range of valued values. (Keep in mind that all ranges will be used when reading in a file as well as when accepting values from a user.) If you have a configuration file that has a value outside of the specified ranges, then an error will occur when parsing that file.
  • Ranges are described at CML range attributes.
  • Options: The option attributes modify the behavior of the tag. Multiple options can be appended to the end of most tags, separated by semicolons. Everything after the third semicolon is considered an option. Options can also be used as instruction tags.

Options are described at CML global option attributes and CML regular option attributes.

Example 1

Title=@main_title@

In this example, main_title will extract the string that follows “Title=“ text in the configuration file, and store it at key location /main_title in the value set.

Or if you are performing a push, main_title will extract the value stored from location
/main_title from the value set, and push it after the string “Title=“ text in the configuration file.

Example 2

Port = @port;port;1024<=&<=2048@
IPAddress = @ipaddress;ip;;optional;delimiter=”/”@
ServerName = @servername;hostname;”localhost”,r”server.*”@

Instruction Tags: @!

This tag specifies parser actions. For a list of available instructions, see CML global option attributes and CML regular option attributes.

Syntax

@!{option}[[;{option}]...]@

Description

The instruction tag sets options that will be used at parse time. For example, defining the name space, whether a list is sorted, ordered, or unordered, how the parser should interpret whitespace, acceptable delimiters, defining comment characters, and so on.

The only attributes used by an instruction tag are options. One or more option can appear in one instruction tag. Multiple options are separated by semicolons. To understand how any particular instruction tag affects the parser, refer to the descriptions of the embedded options.

Attribute

Only option attributes are used with an instruction tag.

Options: The option attributes in an instruction tag define the behavior of the tag. Multiple options can be appended to the end of most tags, separated by semicolons. Many options are toggles of other options. When an option from one of these toggling groups appears in a block, no other option from that group should appear in the same block.

Options are described at CML global option attributesand CML regular option attributes.

Example 1

The following instruction tag tells the CML parser that whitespace in the template will be matched by any combination of tabs and spaces.

@!relaxed-whitespace@

Example 2

The two options in the following instruction tag tell the CML parser the relative order of lines in the configuration file is not important to mapping values from those lines with the value set and it is not an error if values in the value set are not matched by text in the configuration file.

@!unordered-lines;missing-values-are-null@

Example 3

@!namespace=/test/@
@!filename-key="/test";filename-default="/tmp/test.txt"@
@!optional-whitespace@
@!boolean-yes-format="1";boolean-no-format="0"@
@!line-comment-is-semicolon@
@!unordered-lines@

Block (or Group) Tag: @[@...@]@

The Block tag is sometimes also referred to as the Group tag. This tag creates a block or group of related tags and lets you nest groups of related tags.

Syntax

The block tag can have either single line syntax or multiple line syntax.

Single line syntax for the block tag is as follows (with literal strings quoted):

"@" [{level}] "[" [ ";" {option}[ ";" {option}]...] "@" {CML statements} "@" [{level}] "]@"

Multiple line syntax for the group tag is as follows:

"@" {level} "[" [ ";" {option}[ ";" {option}]...] "@"
{CML statements}
"@" {level} "]@"

@[{level}][ [;{option}[;{option}]...]@ {set of CML tags} @[{level}]]@

@[{level}][ [;{option}[;{option}]...]@

{set of CML tags}

@[{level}]]@

The level is an integer that determines whether the block spans multiple lines or is part of a single line. If the level is between 1 and 99 it is a multiline block. If it is greater than 101, it is a block within a line. Do not use level 100 because it is reserved.

Each block can be ended explicitly or implicitly. To end a block explicitly, use an end block tag with the level number. For example, the following tag explicitly closes a level 3 block: @3]@.

To end a block implicitly, use an end block tag with a lower level number to end an enclosing block, or define a new block with a lower level. Each block open tag will close all previous blocks that have an equal or greater level.

Description

The block tag allows you to group related tags and nest groups of tags. With a block, you can define separate parsing rules for each section of a configuration file.

You can nest blocks within other blocks using a higher number for the level. Any subsequent tag with a level value will close all open levels of equal or great value. The block close tag, @]@, is not required.

The opening block tag can include option attributes. Those attributes only affect the tags inside the block at the level declared by the opening tag. Contrast that with instruction tags that appear inside the block: those instruction tags affect the behavior of the current level and any nested blocks.

By using blocks, you can specify unique options for each separate section of the configuration file. For example, you might have a section of a configuration file where the values for True and False are defined as “1” and “0”, respectively. In another section in the same file, you could define values for True and False as “T” and “F”. Use the block tag to separate the two different ways of defining True and False.

Another example could be if in one section of a configuration file a specific number of spaces are important, while in another section any number of spaces is acceptable. You can use the block tag to indicate where the number of spaces differ.

Attributes

No name, type, or range attributes are used with block tags.

  • Level: The block level is an integer that specifies the nesting level of the block. The level also determines whether the block spans multiple lines or is part of a single line. If the level is between 1 and 99 it is a multi-line block. If it is above 101, it is a block within a line. Each block open tag closes all previous blocks that have an equal or greater level.

    Note
    Do not use level 100 because level 100 is reserved.

  • Options: The option attributes modify the behavior of the CML tags in the block. Instruction tags within the block affect the behavior of CML tags in the current block and in nested blocks. Multiple options can be appended to the end of most tags, separated by semicolons. Options can also be used as instruction tags.

    Options are described at CML global option attributes and CML regular option attributes.

Example 1

The following example creates two blocks, one block nested within the other. The first line defines the first block, which is the outer block. The fourth line defines the second block, which is the inner block nested within the first block. The second to last line closes the inner block. This line is optional. The last line closes the outer block. If the second to last line were omitted, the last line would close both blocks.

@1[@
@!ordered-lines@
[SectionOne]
@2[@
@!unordered-lines@
optionA = @section_one/option_a@
optionB = @section_one/option_b@
@2]@
@1]@

Example 2

This example models two sections named [Options] and [AllowVerbs] in a Windows UrlScan.ini file. Both sections in this file contain a list of key-value pairs.

To define the first section (lines 1 through 3), you can use the block tag ([) set at two levels because there are two kinds of data in this section: a fixed heading followed by a list of key-value pairs. The first level block handles the text string “[Options]” while the second level block handles all of the key-value pairs in that section.

The second section (lines 4 through 6) defines the [AllowVerbs] section. Notice that the first section is not explicitly closed with the @2]@ and @1]@ tags as in the previous example because opening the next level 1 section (line 4) implicitly closes the previous sections.

@1[;optional;ordered-lines@
[Options]
@2[;unordered-lines@
@1[;optional;ordered-lines@
[AllowVerbs]
@2[;unordered-lines@

Loop Tag: @*

This tag defines a processing loop. See also the Loop Target Tag: @..

Syntax

@[{level}]*{source}[;[{type}][;[{range}[;{option}[;{option}]...]]]] @ {target}

Description

The Loop tag is used when a set of values may appear multiple times in a configuration file. The default behavior of the loop tag is to iterate over the line of CML directly after it, though this can be modified to iterate over multiple lines or within a single line.

Loops are a form of Group tag, see the Group tag for more information.

The Loop tag allows sequences (lists and sets) to be enumerated. The block associated with a loop element will be processed for each incident of that block in an input file, and will be generated in an output file for each incidence of that data in a value set.

The group associated with a loop element will cause a new element to be stored in the value set for each incident of that group in a configuration file, or each incidence of that data in a value set will push a value to the configuration file. The source attribute is the index key used to map values in the value set.

Attributes

  • Level: The group level is an integer that determines whether the group spans multiple lines or is part of a single line. If the level is between 1 and 99 it is a multi-line group. If it is above 101, it is a group within a line. Level 100 is reserved for internal purposes. Each group open tag will close all previous groups that have an equal or greater level.
  • Source: The source attribute is the key used to access the value in the value set. If the source attribute is relative (that is, it does not start with a “/” or a “.”) it gets appended to the current name space and becomes part of the key used to store the value read in by this tag. If the name is absolute (that is, it starts with a “/”) it is the key, and the value gets stored under this key. The only required element in a loop tag is the source; everything else is optional. If the source name starts with a “.”, it is to be appended to the name space of whatever loop it is a part of. Tags inside loops typically start with a “.”.
  • Type: The type attribute specifies the type of the replace tag, which applies certain predefined restrictions and error checking to different values. The default type for replace tags is “string”.

    For the full list of types see CML type attributes.

    You can prepend “ordered-” or “unordered-” to the type. And you can append “-set” or “-list” to the type.
    • Prepending “ordered-” specifies that the values must be in order.
    • Prepending “unordered-” specifies that the values can be in any order.
    • Appending “-set” specifies that the values must be unique.
    • Appending “-list” specifies that the values can be repeating.
  • Range: The range attribute allows you to set the range for the values. Keep in mind that all ranges will be used when reading in a file as well as when accepting values from a user. If you have a configuration file that has a value outside of the specified ranges, then an error will occur when parsing that file.
  • Ranges are described at CML range attributes.
  • Options: The options attributes modify the behavior of the tag. Multiple options can be appended to the end most tags, separated by semicolons. Everything after the third semicolon is considered an option. Options can also be used as instruction tag.

    Options are described at CML global option attributes and CML regular option attributes.

Example 1

The asterisk character indicates a loop tag. For example:

@1*includegroup;ordered-namespace-set;;optional@
#BEGIN_ALTERNATE
@*.include@
#INCLUDE @.@
#END_ALTERNATE
@1]@

Example 2

@*users;unordered-user-set;!”root”;field-delimiter-is-semicolon@
@.@;

Loop Target Tag: @.

The loop target tag defines an iteration for the Loop tag. See Loop Tag: @*.

Syntax

@.[{source}[;[{type}][;[{range}[;{option}[;{option}]...]]]]]@

Description

The loop target tag indicates the placeholder for a value in a loop. If you consider that the loop tag indicates the beginning of a loop, and is therefore similar to a group tag, the loop target tag is quite similar to a replace tag.

When encountered in a group, with each loop iteration, this tag simply maps the text at current position in the configuration file with the current value in value set. If the optional source attribute is used, the source is appended to the name space created by the loop.

Attributes

None.

Example

The loop target tag is indicated by a period following the “@” character. For example:

@*keys;unordered-namespace-set@
@.key@ = @.value@

Conditional Tag: @?

This tag defines a condition.

Syntax

@[{level}]?{source}@{text}

Description

The conditional tag maps whether or not the text exists in the configuration file with a Boolean value in the name space. When reading a target configuration file, if the text matches, the name space value gets true, otherwise false. When writing to a configuration file, if the name space value is true then the configuration files gets the text; otherwise, no text is written.

This is one of the few tags in which something outside of the tag is actually the value. The main use of this tag is to store a Boolean true value in a location in the name space if the text after the tag exists.

Attributes

No type, range or option attributes are used with conditional tags.

  • Level: The level is an integer that determines whether the group spans multiple lines or is part of a single line. If the level is between 1 and 99 it is a multi-line group, if it is above 101, it is a group within a line. Level 100 is reserved for internal purposes. Each group open tag will close all previous groups that have an equal or greater level.
  • Source: The source attribute is the key used to access the Boolean value. If the source attribute is relative (does not start with a “/” or a “.”) it gets appended to the current name space and becomes part of the key used to store the value read in by this tag. If the name is absolute (starts with a “/”) it *is* the key, and the value gets stored under this key.

    If the source name starts with a “.”, it is to be appended to the name space of whatever loop it is a part of. Typically a tag inside a loop should start with a “.”.

Example 1

The conditional tag is indicated by a question mark symbol (?). For example:

@?debug@options debug

In this example, if you were importing a configuration file into a configuration template, and if the text “options debug” exists in the configuration file, then the value at key /debug will be set to true.

If you were going to push the application configuration, if the value stored at key /debug is true, then the text “options debug” will be pushed to the configuration file.

Example 2

For example, if a configuration file specified that an application were to be threaded based on the existence of the key word “threaded” in the configuration file, the CML would look like this:

@?is_threaded@threaded

This sets the value at the name space key /is_threaded to true if the value “threaded” is in the configuration file and to false if the value “threaded” is not in the configuration file.

DTD Tag: @~

This tag defines a DTD.

Syntax

@~{source}
[type = {type}]
[description = {description}]
[printable = {printable}]
[range = {range}]
[{option}
...]
@

Description

CML supports Document Type Definition (DTD) tags that can be used to pre-define attributes for other CML tags. DTD’s can be used to make the actual functional part of the CML template a little cleaner by storing all of the characteristics of the tag in another location and just referencing the tag itself by name.

DTD definitions can be used to define any tag that has a source attribute; for example loop tags, loop target tags, replace tags, but not tags like instruction tags or group tags (which do not have a source attribute).

Another advantage of using DTD tags in CML is the ability to define 'PRINTABLE' and 'DESCRIPTION' values. The 'PRINTABLE' and 'DESCRIPTION' values give the user some feedback regarding the intended purpose of the field. The string value of the DESCRIPTION attribute is displayed when the mouse cursor rolls over the field in the value set editor screen. The string value of the Printable attribute will replace the path name in the value set editor with a easier-to-read field label.

DTD tags in CML are also inherently multi-line tags. All but the first and last line can be in any order, and all the elements here relate to the fields in a tag, except for printable and description, as those two are valid only for DTD defined tags.

For more information on using DTD tags in your configuration templates, see Use DTD tags in CML. For XML templates, see Customize XML DTD element display.

Attributes

No level attribute is used with a DTD tag. The only required attribute in a DTD tag is the source; everything else is optional. However, a DTD tag with only the name defined does nothing useful.

  • Source: The source attribute is the key used to access the value. If the source attribute is relative (does not start with a “/” or a “.”) it gets appended to the current name space and becomes part of the key used to store the value read in by this tag. If the name is absolute (starts with a “/”) it *is* the key, and the value gets stored under this key. If the source name starts with a “.”, it is to be appended to the name space of whatever loop it is a part of. Typically a tag inside a loop should start with a “.”.
  • Type: The type attribute assigns certain predefined restrictions and error checking to different values, based on well-known types. The default type for replace tags is “string”, which will match more or less anything.
  • The full list of types is available at CML type attributes of this document.
  • DESCRIPTION: The value of the description attribute is a string that is a brief description of what kind of value this tag represents. This attribute will be displayed as mouse-over text in the SA Client value set editor.
  • PRINTABLE: The value of the printable attribute is a string that is just a clean name for the variable. It will be displayed in the SA Client value set editor as the name for the attribute.
  • Range: The range attribute allows you to set the range for the values. You need to keep in mind that all ranges will be used when reading in a file as well as when accepting values from a user. If you have a configuration file that has a value outside of the ranges you set in the template, then an exception will probably get thrown when parsing that file. It is best to use ranges that are correct based on the documentation for the configuration file.
  • Ranges are described fully at CML range attributes.
  • Options: The option attributes serve to modify or affect the behavior of the tag. Multiple options can be appended to the end most tags, separated by semicolons. You may append as many options as you need to the tag, everything after the third semicolon is considered an option, and every option is separated by semicolons. Options can also be used as instruction tag.

    Options are full described at CML global option attributes and CML regular option attributes.

Example

@~port
type = port
range = 1024<=&<=2048
printable = Port
description = The port used for this application. It
should be a port number between 1024 and 2048
@

Send Help Center feedback