UDF Basics
This topic explains how to create, import, edit, copy-paste, and delete user-defined functions (UDFs for short).
Create a UDF
This subsection explains how to create a UDF from scratch and from already existing components. The minimum requirement is one output component to which some data is connected. For input parameters, a function can have zero, one or more inputs. The input and output parameters can be of simple type (e.g., a string) or complex type (a structure). For more information about simple and complex parameters, see UDF Parameters.
UDF from scratch
To create a UDF from scratch, follow the instructions below:
1.Select Function | Create User-Defined Function. Alternatively, click the 
toolbar button.
2.Enter the relevant information into the Create User-defined Function dialog (see screenshot below).
The available options are listed below.
•Function Name: Mandatory field. For the name of your UDF, you can use the following characters: alphanumeric characters (a-z, A-Z, 0-9), an underscore ( _ ), a hyphen/dash ( - ), and a colon ( : ).
•Library Name: Mandatory field. This is the name of a function library (in the Libraries window) in which your function will be saved. If you do not specify the name of a library, the function will be placed into a default library called user.
•Syntax: Optional field. Enter some text that concisely describes the syntax of the function (e.g., expected parameters). This text will be displayed next to the function in the Libraries window and does not affect the implementation of the function.
•Detail: Optional field. This description will be displayed when you move the cursor over the function in the Libraries window or in other contexts.
•Inlined use: Select this check box if the function should be created as inline. For more information, see Regular vs. Inline UDFs below.
3.Click OK. The function becomes immediately visible in the Libraries window under the library name specified above. The mapping window is now redrawn to allow you to create a new function (this is a standalone mapping referred to as the function's mapping). The function's mapping includes an output component by default.
4.Add all the required components to the function's mapping. You can do this in the same way as for a standard mapping.
To use the UDF in a mapping, drag the UDF from the Libraries window onto the main mapping area. See also Call and import UDFs below.
UDF from existing components
To create a UDF from existing components, take the steps below:
1.Select the relevant components on the mapping by making a rectangular selection with the mouse. You can also select multiple components by clicking each one while holding the Ctrl key pressed.
2.Select the menu command Function | Create User-Defined Function from Selection. Alternatively, click the 
toolbar button.
3.Follow Steps 2-4 from UDF From Scratch.
Regular vs. Inline UDFs
There are two types of UDFs: regular and inline. You can specify the type of your UDF when you create it. Inline and regular functions behave differently in terms of code generation, recursiveness, and the ability to have multiple output parameters. The table below summarizes the main differences between regular and inline UDFs.
Inline functions (dashed border) | Regular functions (solid border) |
|---|---|
With inline functions, the UDF code is inserted at all locations where the function is called. If the UDF is called several times, the generated program code would be significantly longer.
| The code for the UDF is generated once, and inputs to it are passed as parameter values. If the UDF is called several times, the UDF is evaluated each time with the corresponding parameter values. |
Inline functions can have multiple outputs and thus return multiple values. | Regular functions can have only one output. To return multiple values, you can declare the output to be of complex type (e.g., an XML structure), which would allow you to pass multiple values to the caller.
|
Inline functions cannot be called recursively. | Regular functions can be called recursively.
|
Inline functions do not support setting a priority context on a parameter. | Regular functions support setting a priority context on a parameter.
|
Inline UDFs affect and are affected by the context in the mapping that calls the UDF.
| Regular UDFs have their own local context. |
| Note: | Switching a UDF from inline to regular, and vice versa, may affect the mapping context, and this may cause the mapping to produce a different result. |
Call and import UDFs
After you have created a UDF, you can call it from the same mapping where you created it or from any other mapping.
Call UDF from the same mapping
To call a UDF from the same mapping, take steps below:
1.Find the relevant function in the Libraries window under the library that you specified when you created the function. To do that, start typing the name in the Libraries window.
2.Drag the function from the Libraries window into the mapping. You can now connect all the required parameters to the function.
Import UDF from a different mapping
To import a UDF from another mapping, follow the instructions below:
1.Click the Add/Remove Libraries button at the bottom of the Libraries window. The Manage Libraries window opens (see screenshot below).
2.To import functions as a local library (in the scope of the current document only), click Add under the current mapping name. To import functions as a global library (at program level), click Add next to Global Library Imports. When you import a library locally, you can set the path of the library file to be relative to the mapping file. With globally imported libraries, the path of the imported library is always absolute.
3.Browse for the .mfd file that contains the UDF and click Open. A message box will inform you that a new library has been added and can be accessed in the Libraries window.
You can now use any of the imported functions in the current mapping by dragging them from the Libraries window into the mapping. For more information about viewing and organizing function libraries, see Manage Function Libraries.
Mapping with credentials (Enterprise Edition)
If the imported .mfd file contains credentials, these are shown as imported (with a yellow background) in the Credentials Manager. By default, imported credentials are not saved with the mapping, but you can optionally create a local copy and save them in the mapping. See Credentials in UDFs.
Edit UDFs
To edit a UDF, take the steps below:
1.Open the mapping that contains a UDF.
2.Double-click the title bar of the UDF in the mapping to see the function's contents where you can add, edit, or remove components as required.
3.To change the function's properties (e.g., the name or description), right-click an empty area in the mapping and select Function Settings from the context menu. Alternatively, click the 
toolbar button.
You can also edit a function by double-clicking its name in the Libraries window. However, only functions in the currently active document can be opened this way. Double-clicking a UDF that was created in another mapping opens that mapping in a new window. If you edit or delete a UDF that was imported into multiple mappings, all these mappings will be affected by the change.
To go back to the main mapping, click the 
button in the top-left corner of the mapping window.
MapForce allows you to navigate through different mappings and UDFs by using the 
and 
toolbar buttons. The corresponding keyboard shortcuts for these buttons are Alt+Left and Alt+Right, respectively.
Copy-paste UDFs
To copy a UDF and paste it into another mapping, follow the steps below:
1.Open the Manage Libraries window.
2.Right-click inside an empty area in the Libraries window and select the option Show All Open Documents.
3.Open both the source and destination mappings. Make sure that both mappings are saved to disk. This ensures correct resolution of paths. See also Copy-Paste and Relative Paths.
4.Right-click the relevant UDF from the source mapping in the Manage Libraries window and select Copy from the context menu (see screenshot below) or press Ctrl+C. Leave the Manage Libraries window open.
5.Switch to the destination mapping (and the Manage Libraries window will change accordingly), right-click User-Defined Functions, and select Paste from the context menu.
Delete UDFs
To delete a UDF, take the steps below:
1.Double-click the title bar of the UDF in the mapping.
2.Click the 
button in the top-right corner of the Mapping window.
3.If the function is used in the currently open mapping, MapForce will ask whether you want to replace all instances with internal components. Click Yes if you want to delete the function and replace all instances where it is called with the function's components. This lets you keep the main mapping valid even if the function is deleted. However, if the deleted function is used in any other external mappings, those will not be valid. Click No if you want to delete the function and all its internal components permanently. In this case, all the mappings where the function is used will not be valid.