User-Defined Functions (UDFs) are custom functions defined once, and reusable multiple times within the same mapping or across multiple mappings. User-defined functions are like mini-mappings themselves: they typically consist of one or more input parameters, some intermediary components to process data, and an output to return data to the caller. The caller is either the main mapping or another user-defined function.
|Tip:||It is also possible to create user-defined functions that return multiple outputs. This is supported when the function is defined as "inline", see Inline and Regular User-Defined Functions.|
Apart from being reusable, user-defined functions are also helpful when you want to package parts of the mapping into smaller components and abstract away the implementation details, thus making the main mapping easier to read.
You typically create user-defined functions to process strings, numbers, dates, and other data in a custom way that extends the built-in MapForce functions. For example, you might want to concatenate or split text in a particular way, or perform some advanced calculations, or manipulate dates and times, or simply hide parts of a mapping by packaging them into a reusable function. Another common use of user-defined functions is to look up a field in a file, database or some other data store supported by MapForce.
The following is an example of a user-defined function that splits a string into two separate strings. This user-defined function is part of the following demo mapping: <Documents>\Altova\MapForce2020\MapForceExamples\ContactsFromPO.mfd. It takes a name as parameter (for example, "Helen Smith"), applies the built-in functions substring-before and substring-after, and then returns two resulting values ("Helen" and "Smith").
As stated before, you can call a user-defined function either from the main mapping, or from another user-defined function. In other words, user-defined functions can be nested if so required, as illustrated below.
For example, the mapping below calls a user-defined function ("LookupPerson") to look up a person's name in an XML file. If you double-click the header of the "LookupPerson" component, its definition opens in the mapping window, and you will notice that this function calls other user-defined functions in its turn: "EqualAnd" and "Person2Details". This mapping is available as a demo at the following path: <Documents>\Altova\MapForce2020\MapForceExamples\PersonListByBranchOffice.mfd.
User-defined functions can also be called recursively (that is, a user-defined function calls itself). This requires, however, that the user-defined function be defined as a regular (not inline) function, see Inline and Regular User-Defined Functions.
Recursive user-defined functions let you solve various advanced mapping requirements, such as iterating over data structures having a depth of N children, where N is not known in advance, see Example: Recursive Search.
After you create a user-defined function, it is saved in the same mapping where you created it. However, you can import it into other mappings as well and call it from there. For more information, see Calling and Importing User-Defined Functions.