SDML Syntax and Data Tag Expansion

The SDML is a markup language containing data tags and function tags. The basic syntax for a tag is to enclose a given tag within the tag markers << >> to denote it as an SDML tag. Within these tag markers is the name of the tag, as well as any values that may be a part of the tags expansion processing. Following is the general form of data tag and function tag syntax:

Data Tag
<<parent.tagName.parameter namedParameter="value">>
Function Tag
<<functionName argument "expression" namedParameter="value">>

Named parameters to both functions and data tags have the specific requirement that the parameter name, equal sign, and the value can not be separated by any white space:

Correct Parameter Syntax
<<functionName namedPrameter="value">>
Incorrect Parameter Syntax
<<functionName namedParameter = "value">>

Depending on the nature of the SDML logic and processing needed, it is common for one tag to be nested within another. When this is the case the end markers for such tags may be adjacent. In this situation at least one white space character must be used to separate the two end markers. This may be a space, tab, or a newline:

Incorrect
>>>>
Single Space
>> >>
Tab
>>		>>
Newline
>>
>>

Data Tag Syntax

Values within a given tag will depend upon a number of different factors. Data tags generally take one of the following forms:
<<parent.tagName namedParameter=value>>
<<parent.tagName.parameter>>

The parameter and named parameter for a given data tag will depend on the data type of that tag. Some may have no parameters or named parameters, others may support one or both. A parameter generally provides access to different contents of the data tag’s value, such as raw or string. A named parameter generally provides formatting instructions for how the value should appear when the data tag is expanded.

The value for a named parameter may be a hard coded value or another tag within the SDML. When the value is plain text, it must be enclosed in double quotes. When the value to the parameter is another SDML tag it cannot be enclosed in double quotes.

Parameter from Plain Text
<<parent.tagName namedPrameter="value">>
Parameter From Data Tag
<<parent.tagName namedParameter=<<tagName>> >>

Function Tag Syntax

Function tags within the SDML take the general form:
<<functionTag argument “expression” namedParameter=value>>

A given function may take multiple arguments, expressions, and/or named parameters, or it may not take any of these depending on that function’s prototype and purpose. Separating each of these values to the function is one or more white space characters.

Arguments should be enclosed in tag markers if a data tag is used, unless specified otherwise for a given function. Certain functions, notably <<if...>>, <<foreach...>>, and <<case...>> specify that if the first argument is a data tag it cannot be enclosed in tag markers, but rather should only be the name of the data tag. If the argument is a hard coded value it should be enclosed in double quotes.

Expressions are always enclosed in double quotes, regardless of whether or not they contain SDML tags. The contents of a given expression can span multiple lines, which is often the case as expressions tend to be longer text values.

The value for the named parameter can be a data tag, in which case the tag should be enclosed in tag markers. If the value is a hard coded value it must be enclosed in double quotes. The value for a named parameter can contain white space within the double quotes and can be a combination of SDML tags and plain text.

These values for a function tag can span multiple lines, with the opening marker preceding the function name and the closing marker somewhere after all specified values for the function, as in:
<<functionTag
		argument
		“expression”
		namedParameter=value
>>

When arguments or named parameters contain function or data tags, those tags will be expanded before being passed to the function for processing. Expressions containing tags will not be processed until the function returns that expression.

SDML Expansion

At run time, when the Agentry Server processes a script file the tags it contains are parsed and expanded. This process is called SDML expansion and occurs for all scripts not using a Java Virtual Machine system connection that are run by the Server.

Tags are expanded in a top-down, inside-out order. This means that each line of a script is processed starting with the first in the file and working in order to the last line. When a line is processed, the data tags are expanded from the innermost tag to the outermost one. Consider the following example:
3.....2....1		...................1a...................									4

<<if <<ne <<object.acctnum>> <<parent.acctnum>> >> "not equal" >>

Ignore the numerical notations for the moment, as they are for reference purposes only and not a part of the SDML text. This line says that if the values of the acctnum properties in the object and the parent of the object are not equal to return the string “not equal”. This begins with the <<if...>> function. The single argument to this function is <<ne...>>, which is another function whose name is short for “not equal”. The <<ne...>> function takes two arguments that are compared for equality. The two arguments in the example are both data tags for property values within objects.

In this case, the expansion goes as follows. First, the two arguments, noted as 1 and 1a, are expanded. These are data tags, so the tags are replaced with the values of the two acctnum properties in the object being processed and the parent of that object. If the object property acctnum has a value of 1234 and the parent has a value of 1122, the line would expand as follows:
<<if <<ne 1234 1122 >> "not equal" >>

Next, the <<ne...>> function is expanded. The two values of 1234 and 1122 are passed as arguments to this function. The function then compares the two values and determines they are not equal. The line would now then appear as:<<if true "not equal" >>

The <<if...>> function, which provides if-then-else logic, takes the return value from the <<ne...>> function value as an argument. The "not equal" text is the expression that is returned when the argument is true. In the example provided the resulting text placed at the point of the <<if...>> function call will be the text: not equal.

SDML Syntax Quick Reference

Following is a quick reference of the basic syntax rules for the Syclo Data Markup Language:
  • Function and data tags are enclosed in the tag markers <<tagname>>. Named parameters to both function and data tags, as well as function arguments and expressions are enclosed within the same set of tag markers.
  • Hard coded values passed to parameters or arguments are enclosed in double quotes. Data or function tags are enclosed in tag markers and should never be enclosed in quotes.
  • Expressions are always enclosed in double quotes, whether or not they contain tags. Tags within an expression are also enclosed in tag markers.
  • Named parameters for both function and data tags take the form of a key and value pair separated by an equal sign (=). No white space can exist between the named parameter, equal sign, and the beginning of the value for the parameter. The parameter itself can contain white space and, when it does it should be enclosed in double quotes.
  • Adjacent end tag markers must be separated by at least one white space character. Excluding this character will result in an error during tag expansion.
  • Function tags can span multiple lines in a script file. This is commonly the case with expressions.
Parent topic: Developing Agentry Apps