Parameters in User-Defined Functions

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Functions > User-Defined Functions >

Parameters in User-Defined Functions

When you create a user-defined function, you must specify what input parameters it should take (if any) and what output it should return. While input parameters are sometimes not necessary, an output parameter is mandatory in all cases (that is, a function must always return something). For example, the function below has no inputs and one output which returns the text "hello" to the caller:

mf_udf_04

Function parameters can be of simple type (such as string or integer) or a complex structure. For example, the user-defined function "FindArticle" illustrated below has two input and one output parameters.

 

POArtNr is an input parameter of simple type "string"
Amount is an input parameter of simple type "integer"
CompletePO is an output parameter of complex XML type.

mf_udf_09

LookupArticle.mfd

This mapping above is available as a demo at the following path: <Documents>\Altova\MapForce2019\MapForceExamples\LookupArticle.mfd.

 

Adding Parameters

 

To add an input or output parameter:

1.Create a user-defined function mapping (see Creating User-Defined Functions) or open an existing one (see Editing User-Defined Functions).
2.Do one of the following:

 

Run the menu command Function |  Insert Input or Function | Insert Output.
Click the Insert Input mf_ic_udf_input or Insert Output mf_ic_udf_output toolbar buttons.

mf_udf_08

3.In the dialog box above, choose whether input or output parameters should be of simple type (such as string or integer) or a complex structure (such as an XMLor database structure). To create a parameter that is a complex XML type, click Choose next to "Structure" and browse for the XML schema that describes the required structure.

 

If the function's mapping already includes XML schemas, they are available for selection as structures. Otherwise, you can select a completely new schema that should provide the structure of the parameter. The same is true for databases or other complex structures if they are supported by your edition of MapForce.

 

With XML structures, it is possible to select a root element for your structure, if the XML schema allows it. To specify a root element, click Choose next to "Root", and select the root element from the dialog box that opens.

 

If selected, the check box Save structure file path relative to MFD file will change the structure file's absolute path into a path relative to the current mapping, when you save the mapping. For more information, see Using Relative Paths on a Component.

 

The Input is required and Input is Sequence check boxes are explained in the following sections.

 

Mandatory parameters

To make a parameter mandatory in a user-defined function, select the Input is required check box. When a parameter is mandatory, validation errors will occur if you do not connect an input to it.

 

To make a parameter optional, clear the Input is required check box. On the main mapping, optional parameters have a slightly different appearance—their input connector (small triangle) has a dashed border.

 

You can also specify a default parameter value by connecting it to the "default" input of a parameter, for example:

mf_udf_18

The default value will apply only if there is no other value. If the optional parameter receives a value when the function is called, then that value takes precedence over the default.

 

Sequence parameters

You can optionally specify that a function's parameter should be treated as a single value (this is the default behaviour), or as a sequence. To treat the parameter as a sequence as opposed to a single value, select the Input is sequence check box. Note that this check box is meaningful and enabled only if the user-defined function is of type "regular", see Inline and Regular User-Defined Functions. Otherwise, the check box is disabled.

 

A sequence is a range of zero or more values. You might want to treat a parameter as a sequence when your user-defined function expects input data as a sequence, in order to perform some aggregation of values in that sequence (for example, by calling functions such as avg, min, max). For an example, open the following demo mapping: <Documents>\Altova\MapForce2019\MapForceExamples\InputIsSequence.mfd. In this mapping, the "data" filter is connected to the user-defined function "Calculate". The filter's output is a sequence of items, so the input parameter of the function is set to sequence.

mf_udf_11

InputIsSequence.mfd

Internally, the "Calculate" function aggregates all the sequence values (as illustrated below, it runs the min, max, and avg aggregate functions on the input sequence).

mf_udf_12

As a rule of thumb, the input data, either sequence or non-sequence, determines how often the function is called.

 

When input data is connected to a sequence parameter, the user-defined function is called only once and the complete sequence is passed into the user-defined function.
When input data is connected to a non-sequence parameter, the user-defined function is called once for each single item in the sequence.

 

Connecting an empty sequence to a non-sequence parameter has the result that the function is not called at all.

 

This can happen if the source structure has optional items, or when a filter condition returns no matching items. To avoid this, either use the substitute-missing function before the function input to ensure that the sequence is never empty, or set the parameter to sequence, and add handling for the empty sequence inside the function.

 

The Output is sequence check box may be required for output parameters also. When a function passes a sequence of multiple values to its output component, and the output component is not set to sequence, the function will return only the first item in the sequence.

 

Parameter order

When a user-defined function has multiple input or output parameters, you can change the order in which parameters should appear to callers of this function. For example, the function below has three input parameters, input1, input2, and input3.

mf_udf_13

The order of parameters in the function's mapping (starting from the top) dictates the order in which they appear to callers of this function:

mf_udf_14

Note the following:

 

Input and output parameters are sorted by their position from top to bottom. Therefore, if you move parameter input3 to the top in the function's mapping, it will become the first parameter of this function.
If two parameters have the same vertical position, the leftmost takes precedence.
In the unusual case that two parameters have exactly the same position, the internal component ID is automatically used.

© 2019 Altova GmbH