DML Instructions

DML Instructions

Where to use DML Instructions

How to write DML Instructions

DML Instructions

Use DML Instructions to define how the Map Engine server processes the objects that you include in a Integration-Process and Integration-Task.

Where to use DML Instructions

Each DML Instruction is only appropriate in one or more predefined contexts. For example, a given DML instruction may only be applicable to a Map or a Validation Rule. The following table summarizes where you can use each DML Instruction.

DML instruction DML Block Business Document
Decision Path Map Validation Rule

exit

x

x

x

if-then-else

x

x

x

loop

x

x

x

loop on

x

x

x

for each

 

x

 

for each do

x

n times

x

n times do

x

switch

x

x

x

where

x

x

x

while

x

x

x

in

x

x

x

out

x

x

x

defined

x

x

x

undefined

x

x

x

How to write DML Instructions

This section covers the purpose and syntax of the DML Instructions and provides an example of each one. These instructions include:

Before you begin

To write most DML Instructions, you must also specify the Business Document Paths that identify the nodes in the Business Document where you want to apply the instruction.

exit

exit Comment
Purpose

To set off an alarm, known as raising an exception, use the exit instruction with a single argument that states which behavior should be used.

Syntax

if CheckIBAN(this\\IBAN_Code) then{ exit rejectMessage }

Example of exit

if-then-else

if-then-else Comment
Purpose

To execute processing instructions based on a condition, use the if-then-else instruction Validation Rule.

Syntax

if boolean_expression then then_block

[else else_block]

Where:

  • boolean_expression is a DML expression that returns the value true or false
  • then_block includes one or more expressions that the Map Engineserver executes when boolean_expression returns true
  • else_block is optional and includes one or more expressions that the Map Engine server executes when boolean_expression returns false

Enclose multiple expressions in curly brackets ( { and }), and separate multiple expressions with the semicolon character ( ; ).

Only one expression in the then_block and else_block can return a value. By default, this is the last expression. To indicate that another expression must return a value, prefix a set of special characters to the expression, as follows: $:=expression

If you do not define else_block false returns boolean_expression and, the if-then instruction returns the value null.

If boolean_expression is a DML expression that returns the value null or absent, then the Map Engine server generates an error.

When you nest if - then instructions inside other if - then instructions, use curly brackets ( { and } ) to group the instructions that belong together. Compare the following:

  • if boolean_expression1 then if boolean_expression2 then then_block else else_block
  • if boolean_expression1 then {if boolean_expression2 then then_block} else else_block

In the first instruction, if boolean_expression1 returns false, the Map Engine server does not execute the then_blocks and the else_block. The Map Engine server executes the else_block only when boolean_expression2 returns false.

In the second instruction, if boolean_expression1 returns false, the Map Engine server executes the else_block. The Map Engine server does not execute the then_blocks and the else_block when boolean_expression2 returns false.

Example of if-then-else

loop

loop Comment

Purpose

To repeat processing instructions, use the loop instruction.
Syntax

loop(integer_expression)

loop_block

Where:

  • integer_expression is an integer expression that specifies how many times the Map Engine server executes loop_block. When integer_expression is n, the Map Engine server executes loop_block n times.
  • loop_block includes one or more expressions that the Map Engine server executes

Enclose multiple expressions in curly brackets ( { and } ), and separate multiple expressions with the semicolon character ( ; ).

Only one expression in the loop_block can return a value. By default, this is the last expression. To indicate that another expression must return a value, prefix a set of special characters to the expression, as follows: $:=expression

You can use jump instructions within a loop:

  • next

    The next instruction passes control to the next iteration of the loop instruction in which it appears, bypassing any remaining instructions in the loop instruction body.

  • break

    The break instruction terminates the execution of the nearest enclosing loop instruction in which it appears. Control is passed to the instructions that follows the terminated instruction.

    Within nested instructions, the break instruction only terminates the loop instruction that immediately encloses it.

Example of loop

loop on

loop on Comment
Purpose

To sequentially scan a list of node instances.

Syntax loop on [Business Document Path_a],[Business Document Path_b],[Business Document Path_...n]

loop_on_block

 

Where:

  • Business Document Path [a,b,...n] is an expression that identifies one or more nodes with values or nodes without values in an input Business Document. The Map Engine scans this list of nodes.

All paths must belong to the same input Business Document.

To filter the nodes in Business Document Path [a,b,...n] based on the node content, use the where clause.

  • loop_on_block: includes one or more expressions that the Map Engine server executes.

Enclose multiple expressions in curly brackets ( { and } ) and separate multiple expressions with the semicolon character ( ; ).

Within the loop_on_block, the key word this indicates the current instance.

You can use jump instructions within a loop:

  • next

    The next instruction passes control to the next iteration of the loop instruction in which it appears, bypassing any remaining instructions in the loop instruction body.

  • break

    The break instruction terminates the execution of the nearest enclosing loop instruction in which it appears. Control is passed to the instructions that follows the terminated instruction.

    Within nested instructions, the break instruction only terminates the loop instruction that immediately encloses it.

    Nested instructions loop on and for each are allowed. In the context of a nested loop, the this keyword always specifies the current instance of the nearest loop.

Example of loop on

Suppose that you have an input Business Document with the following structure:

Now suppose that you want to verify the instances of postal codes in both Orders and Invoices. You need to deal with the following problems:

  • The address block displays at several places in the Business Document.
  • Postal code validation varies depending on the country in which you plan to apply verification functions to, that are specific to the country.
  • You need to scan the entire Business Document, send a message on each error, and return a document status of either OK or NotOK.

The following Validation Rule accomplishes these tasks:

 

This example illustrates a common case of the use of the loop on instruction to perform a validation check. In this Validation Rule:

  • Each PostalCode node instance that is not empty (checked via the where clause) is tested in both the Invoices and Orders blocks (the symbol \\ specifies the inclusion of all generations of descendant child elements).
  • The Validation Rule tests the value of each CountryCode node, and then either applies the correct validation function, or generates a trace log entry that says you cannot handle this country type.
  • The variable %valid; holds a boolean value for the net result of the Validation Rule.
  • The Function addTrace generates any necessary error messages.

This example illustrates the basic difference between loop on and for each:

No output instance is created. You generate a boolean type Validation Rule result in the variable which is returned at the end.

for each

for each Comment  
Purpose

When a node without values in an output Business Document has multiple cardinality (0-n or 1-n), use the for each instruction to define the value of n. The for each instruction instructs the Map Engine server to:

  • Generate n occurrences of the output node and its descendants.
  • Evaluate any expressions that are contained in the descendants of the output node.

What is the difference between for each and n times?

In a Map, you can use either the n times or the for each instruction to the cardinality of a node without values in an output Business Document. In:

  • for each: defines cardinality (the value of n) via a node in the relevant input Business Document. When the Map Engine server processes a Business Document, the number of times that the input node occurs defines the value of n.

The for each instruction also redefines the current context of a Business Document.

  • n times: defines the cardinality (the value of n), via an integer expression.

Syntax

For each[Business Document Path_a], [Business Document Path_b], [Business Document Path_...n

All paths much belong to the same input Business Document.

Where Business Document Path [a, b,...n] is an expression that identifies one or more nodes with values or nodes without values in an input Business Document. The instruction for each Business Document Path returns the number of times that the input nodes occur.

To filter the nodes in Business Document Path [a, b,...n] based on the node content, use the where clause. See the where for more information.

In a node without values, you can also define the cardinality of the descendants that have multiple cardinality (0-n, 1-n). To refer to these descendants, extend the basic for each syntax, as described in the following table:

  Use: To generate n occurrences of each:
  for each child [Business Document Path_a], [Business Document Path_b], [Business Document Path_...n] Child node
  for each terminal child [Business Document Path_a], [Business Document Path_b], [Business Document Path_...n] LeafElement node and to evaluate the expressions contained in them n times
  for each attribute [Business Document Path_a], [Business Document Path_b], [Business Document Path_...n] Attribute node and to evaluate the expressions contained in them n times

Example 1: for each with paths to a single Business Document node

Example 2: for each with paths to multiple nodes in a Business Document

for each do

for each do Comment  
Purpose

When a node with values in an output Business Document has multiple cardinality (0-n or 1-n), use the for each do instruction to define the value of n. The for each do instruction instructs the Map Engine server to:

  • Generate n occurrences of the output node.
  • Evaluate the expressions contained in the output node n times.

What is the difference between for each do and n times do?

In a Map, you can use either the for each do or the for each do instruction to the cardinality of a node with values in an output Business Document. In:

  • for each do, define cardinality (the value of n) via one or more nodes in the relevant input Business Document. When the Mapping Services Server processes the relevant Business Document, the number of times that the input node occurs defines the value of n.

    In addition, for each do redefines the current context of a Business Document:

  • n times do, defines cardinality (the value of n) via an integer expression.

Syntax

for each [Business Document Path_a],[Business Document Path_b],[Business Document Path_...n] do do_block

All paths must belong to the same input Business Document.

Where:

  • Business Document Path [a,b,...n] are expressions that specify nodes with or without values in a Business Document. The instruction for each Business Document Path [a,b,...n] returns the number of times that the input nodes occur.
  • do_block includes one or more expressions that the Map Engine server executes to generate each occurrence of the output node.

Enclose multiple expressions in curly brackets ( { and } ), and separate multiple expressions with the semicolon character ( ; ).

Only one expression in the do_block can return a value. By default, this is the last expression. To indicate that another expression must return a value, prefix a set of special characters to the expression, as follows: $:=expression

To filter the nodes in Business Document Path [a,b,c] based on node content, use the where clause. See the where clause for more information.

In a node without values, you can also define the value of n for the descendants that have multiple cardinality (0-n, 1-n). To refer to these descendants, extend the basic for each do syntax, as described in the following table:

Use:

To generate n occurrences of each:

for each child [Business Document Path_a],[Business Document Path_b],[Business Document Path_...n] do do_block

ChildP

for each terminal child [Business Document Path_a],[Business Document Path_b],[Business Document Path_...n] do do_block

LeafElement node and to evaluate the expressions contained in them n times

for each attribute [Business Document Path_a],[Business Document Path_b],[Business Document Path_...n] do do_block

Attribute node and to evaluate the expressions contained in them n times

Example of for each-do

n times

n times Comment

Purpose

When a node without values in the output Business Document has multiple cardinality (0-n or 1-n), use the n times instruction to define the value of n as an integer expression. The n times instruction instructs the Map Engine server to:

  • Generate n occurrences of the output node and its descendants.
  • Evaluate any expressions that are contained in the descendants of the output node.

What is the difference between n times and for each?

In a Map, you can use either to define the cardinality of a node without values in an output Business Document. In the instruction n times or the:

  • for each, define cardinality (the value of n) via a node in the relevant input Business Document. When the Map Engine server processes the Business Document, the number of times that the input node occurs defines the value of n.

    The for each instruction also redefines the current context of a Business Document.

  • n times, define cardinality (the value of n) via an integer expression.

Syntax

n times

Where n is an integer expression that specifies the number of times that a node without values occurs in an output Business Document.

Example of n times

n times do

n times do Comment

Purpose

When a node with values in an output Business Document has multiple cardinality (0-n or 1-n), use the n times do instruction to define the value of n. The n times do instruction instructs the Map Engine server to:

  • Generate n occurrences of the output node.
  • Evaluate the expressions contained in the output node n times.

What is the difference between n times do and for each do?

In a Map, you can use either n times do or for each do:

  • n times do, defines cardinality (the value of n) via an integer expression.
  • for each do, defines cardinality (the value of n) via a node in the relevant input Business Document. When the Map Engine server processes the Business Document, the number of times that the input node occurs defines the value of n.
    In addition, for each do redefines the current context of a Business Document.

Syntax

n times do do_block

Where:

  • n is an integer expression that specifies the number of times that a node with values occurs in an output Business Document.
  • do_block includes one or more expressions that the Map Engine server executes to generate each occurrence of the output node.
    Enclose multiple expressions in curly brackets ( { and } ), and separate multiple expressions with the semicolon character ( ; ).
    Only one expression in the do_block can return a value. By default, this is the last expression. To indicate that another expression must return a value, prefix a set of special characters to the expression, as follows: $:=expression

Example of n times do

switch

switch Comment

Purpose

To execute processing instructions based on a condition, use the switch instruction. You can also use the switch instruction to group a set of conditions and as an alternative to using multiple if then else expressions.

Syntax

switch switch_expression

{

case case_expression_list: case_block

case case_expression_list: case_block

default: default_block

}

Where:

  • Curly brackets ({}) are required to delimit the start and end of the switch instruction.
  • The switch instruction must contain at least one case clause or one default clause.
  • The switch instruction always executes a single case clause or clause. If you do not specify a default clause and no case clause is executed, the instruction returns the value null.
  • The switch instruction evaluates each case clause in turn (in the order in which the case clauses appear), and exits the instruction when it executes a case clause or default clause.
  • Each case and default clause must contain a block. Each block is either a single instruction or a list of instructions separated by the semi-colon character (;). If you specify a list of instructions, you must enclose the instructions in curly brackets ({}). Otherwise, curly brackets are optional.
  • Each case must take a constant value. The expression 'case %variable' is not authorized.
  • The switch_expression is a DML expression that returns a value of the class B, D, I, R, S, or V. The switch_expression cannot contain the constants null or absent, but can return the values null or absent.
  • The case_expression_list is a list of case_expressions separated by a comma. For example: 2, 4, 6, 8.
  • The case_expression is an expression or a to_expression (for example: case : 0 to 10). The operands of the to_expression must be of the class B, D, I, R, S, or V and must be compatible with the class of the switch_expression. The constants null and absent are not authorized and if one of the operands returns the value null or absent, an error occurs on execution.
  • The default block is optional and does not have to be the last clause of the switch. Only one default clause is allowed.
  • The instructions next and break are not authorized.

Examples of switch

 

where

where Comment

Purpose

To filter the nodes that you identify via a Business Document Path, use the where clause.

Syntax

Business Document Path [where(boolean_expression)

Where:

  • Business Document Path is an expression that identifies one or more nodes in an input Business Document.
  • boolean_expression is a Boolean expression that the Integration Server uses to filter nodes from Business Document Path. The Map Engine server only returns the nodes in Business Document Path when boolean_expression returns the value true.

Use the reserved word item in boolean_expression to refer to specific instances of nodes. Compare the following:

  • Node_A [where (true)]

Because boolean_expression is true, the Map Engine server returns every instance of Node_A in the relevant input Business Document.

Keep in mind that any Boolean expression that is true returns the nodes that you identify via Business Document Path. The Boolean expression Node_A [where (1=1)] also returns every instance of Node A in the relevant input Business Document.

Because boolean_expression is not used in this example to filter nodes from Business Document Path, the where clause is unnecessary. By itself, the Business Document path Node_A returns every instance of Node_A in the relevant input Business Document.

  • Node_A [where (Node_A]>20

Because the reserved word item is not used in this where clause, Node_A must have single cardinality. If the relevant Business Document includes more than one instance of Node_A, the Map Engine server applies boolean_expression only to the first instance of Node_A and ignores all other instances.

Because boolean_expression compares Node_A to a value, Node_A must be a node with values.

  • Node_A [where (item>20)]

Because the reserved word item is used in this where clause, Node_A can have either single or multiple cardinality. The reserved word item instructs the Map Engine server to identify every instance of Node_A in the Business Document.

Because boolean_expression compares Node_A to a value, Node_A must be a node with values.

Examples of where

 

while

while Comment

Purpose

The while instruction lets you repeat instructions until a specified instruction is false.

Syntax

while (condition_instruction) while_body

condition_instruction: instruction that returns a Boolean value

while_body:

unique instruction or jump instruction

next

break

or a list of instructions

The execution proceeds as follows:

  1. The condition_instruction is evaluated.
  2. If condition_instruction is initially false, the body of the while instruction is never executed, and control passes from the while instruction to the next instruction in the expression. If condition_instruction is true, the body of the while instruction is executed and the process is repeated beginning at step 1.

When a break instruction within the body is executed, control is transferred to the instruction immediately following the while instruction. The exit instruction terminates only the most tightly enclosing while or loop instruction.

Use the next instruction to terminate an iteration without exiting the while loop. The next instruction forces immediate transfer of control to the next iteration of the smallest enclosing loop or while.

Usage rules

  • The while_body expression must contain at least one instruction.
  • Enclose multiple instructions in curly brackets ({ and }), and separate multiple instructions with the semicolon character (;)
  • Only one instruction in the while_body can return a value. By default, this is the last instruction. To indicate that another instruction must return a value, prefix a set of special characters to the instruction, as follows: $:=instruction.

Example of while

tree

 
treeComment
Purposetree copies the tree (nodal structure) of the input Business Document to the tree of the output Business Document.
Syntaxtree (input_Business_Document_tree)
Usage rules

To use the tree instruction, respect the following rules:

  • Use the tree instruction only in the expression of a parent node.
  • If a node has an expression that includes the tree instruction, none of the descendants of that node can contain an expression.
  • If a tree has an n cardinality, all instances are copied to the output Business Document. There is no selection filter possible.
  • You cannot use the tree instruction in the nodes: SEQUENCE, CHOICE or ALL. The tree instruction cannot be used in these nodes because they do not possess name and path characteristics. You can however, use the tree instruction on a parent node of these nodes.
  • The tree instruction must be compatible with the output tree. The input tree i is compatible with the output tree o if:
    • All of the descendants of node i have the same type of the descendants of node o. (Example: attribute, leaf, group element, parent)
    • All of the descendants of node i have a class that is compatible with all the descendants of node o. A given class is compatible with another with the first is implicitly convertible with the second.
    • All of the descendents of node i have cardinality that is compatible with all the descendants with node o.
Parameterinput_Business Document_tree
Enter a unique path in the input Business Document.
Returntree does not return a value.

 

In

InComment

Purpose

To determine whether something is within a set of values.

Two operators exist that accept lists of values as a right operand: in and out. The two functions are opposite of each other.

Syntax

%szcountry in ("FRANCE", "ROMANIA", "GERMANY")

 

Example: Considering the data defined in the following table:

The Function in this example returns True

%szCountry in ("FRANCE", "ROMANIA", "GERMANY")

The Function in this example returns True:

\company\country in ("FRANCE", "ROMANIA", "GERMANY")

Business Document definitionInstance of Business Document
 Cardinality ClassData type|_Virtual Node
1 company1-1 string (len)

   |_company

2 name1-1S - Stringstring (len)

     |_name = "PERRIER"

3 address1-1S - Stringstring (len)

     |_address = <NULL>

4 country1-1S - Stringstring (len)

     |_"FRANCE"

 

Out

OutComment

Purpose

To determine whether something is within a set of values.

Two operators exist that accept lists of values as a right operand: in and out. The two functions are opposite of each other.

Syntax

%szcountry out ("FRANCE", "ROMANIA", "GERMANY")

 

 

Defined

Defined 

Purpose

Defined is used on a Business Document path to determine whether a targeted field exists or not. Two operators exist that allow you to evaluate complex situations: defined and undefined. The two functions are opposite of each other.

Syntax

if (length(\\id[where defined item\..\discount_rate][1]) <> 19)

{

}

 

 

Undefined

UndefinedComment
Purpose

Undefined is used on a Business Document path to determine whether a targeted field exists or not. Two operators exist that allow you to evaluate complex situations: defined and undefined. The two functions are opposite of each other.

Syntax

if (length(\\id[where undefined item\..\discount_rate][1]) <> 19)

{

}

 

Related Links