Commands and functions

Mapping commands perform actions that are used to instruct Data Interchange Services client that a specific action is to occur, while mapping functions perform an action and return a result within an expression or assignment statement.

Mapping commands

Mapping commands instruct the translation process on how to move data from one element to another, how to manipulate data, how to process repeating compound elements, when to issue user specified errors, and how to perform conditional processing. Most commands require parameters, such as paths that identify where data is going to or coming from, variables, constants, and expressions.

Note:
A command name is not case-sensitive. For example, the Error() command keyword could also be specified as ERROR().

An expression as a parameter in a command can resolve to any data type as long as the data type can be converted to the data type expected by the parameter. Parameters for a command are never modified by the command. In general, data transformation maps, validation maps, and functional acknowledgment maps support most commands. Exceptions will be documented with the command.

Mapping commands example

CloseOccurence: Use the CloseOccurrence command to close the current occurrence of a repeating element and force the creation of another instance of the element. This command can be used for both source-based and target-based maps. The CloseOccurrence command has the following format:

CloseOccurrence(targetpath)

Where: targetpath specifies a repeating target element that is closed to any new elements in the current occurrence. Any additional mappings to this element or its children result in a new occurrence of the targetpath element. The CloseOccurrence command can be shortened to CloseOccur.

Example

Suppose your source document has the following structure:

Rec1

Field1

Field2

Field3

Field4

Suppose your target document has the following structure:

Seg (repeats)

Seg01

Seg02

Field1 and Field2 are to be mapped to the first occurrence of Seg (Seg01 and Seg02), and Field3 and Field4 to the second occurrence of Seg (again, Seg01 and Seg02).

The following steps describe how to accomplish this.

  1. Move down to the node in the Mapping Command window where you want the commands to be executed.
  2. Right click the node, select "Insert within, Insert Before, or Insert After" depending on where you want the commands to execute.
  3. Select Commands, then Assignment. This results in the following: Path = expression.
  4. Map Field1 to Seg01, Field2 to Seg02 using the Assignment Command, and drag/drop each source path to the "path" and the target path to the "expression." Drag Seg01 in the target document and drop on "path." Drag Field1 in the source document and drop on "expression." Result: \Seg\Seg01\\ = \Rec1\Field1\\. Click the Insert button. Drag Seg02 in the target document and drop on "path." Drag Field2 in the source document and drop on "expression." Result: \Seg\Seg02\\ = \Rec1\Field2\\. Click the Ok button.
  5. Insert a CloseOccurrence(Seg) command to close the first occurrence of Seg. Right-click the assignment statement \Seg\Seg01\\ = \Rec1\Field2\\. Select "Insert After." Select "Command", then "CloseOccurrence." This results in the following: CloseOccurrence (targetPath). Drag Seg and drop on targetPath.
  6. Map Field3 to Seg01, Field4 to Seg02, which creates a second occurrence of Seg. Right-click the CloseOccurrence command. Select "Insert After." Select "Command," then "Assigment." Repeat Step 4 with the same target document elements Seg01 and Seg02 and source document elements Field3 and Field4.

Mapping functions

Mapping functions perform an action and return a result within an expression or assignment statement. All functions take 0 or more parameters as input. The number of parameters and the data type of the return value vary from one function to the next. Appropriate type conversions are done implicitly if needed (and possible). Some functions have optional parameters. If the optional parameters are omitted from the function call, a default value will be used for that parameter.

Most functions can take an expression as a parameter, as long as the result of the expression is (or can be converted to) the correct data type. For example, the Char() function converts a value to a character string. The command:

Var1 = Char ( 1 + 2 )

Is equivalent to:

Var1 = Char ( 3 )

Note:
Function names are not case-sensitive. The function name Char() is the same as CHAR().

In general, data transformation maps, validation maps, and functional acknowledgment maps support most functions. Exceptions are documented with the function.

Mapping function example

DateCnv: The DateCnv function is used to assist in converting one date format to another. The DateCnv function uses the following format:

char DateCnv(char sourceDate, char frommask, char tomask)

The actual syntax requires quotes.

For example:

Mapping Path = DateCnv('20021216', 'CCYYMMDD', 'CCYY-MM-DD')

Where: sourceDate is the string that contains the source date, frommask is the mask that identifies the format of the date in sourceDate, and tomask is the mask that identifies the format of the date desired in the result string.

Results: The converted date is a character string.

Example: Map the target field PODate in POHeader record from the source field PurchaseOrderDate in OrderRecord record. The following steps describe how to do this.

  1. Move down to the node in the Mapping Command window where you want the commands to be executed.
  2. Right-click the node, select "Insert within, Insert Before, or Insert After" depending on where you want the commands to execute.
  3. Select Commands, then Assignment. This results in the following: Path = expression.
  4. Drag the target path PODate to the "path." Results: \POHeader\PODate\\ = expression.
  5. Right-click the expression. This results in a list of functions to select.
  6. Select DateConv. This results in the following: \POHeader\PODate\\ = DateCnv (sourceDate, fromMask, toMask).
  7. Drag the source path to 'sourceDate.' Results: \POHeader\PODate\\ = DateCnv (\OrderRecord\PurchaseOrderDate\\, fromMask, toMask)
  8. Add the frommask and tomask in quotes: \POHeader\PODate\\ = DateCnv (\OrderRecord\PurchaseOrderDate\\, 'CCYYMMDD', 'CCYY-MM-DD')
  9. Click the OK button. Results: if source date value = 20021216 target date value = 2002-12-16.

Copyright IBM Corp. 2003, 2005