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:
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.|
This mapping above is available as a demo at the following path: <Documents>\Altova\MapForce2019\MapForceExamples\LookupArticle.mfd.
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 or Insert Output toolbar buttons.|
|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 XML 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.
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.
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:
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.
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.
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).
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.
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.
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:
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