User Functions

To access the User Function Editor: In the Project pane, expand Programming, and double-click User Functions.

User functions are custom functions created or imported by the user. User Functions provide flexibility and efficiency for advanced applications. Most applications do not need user functions. User functions can be used anywhere expressions are used in the RMC, including the Expression (113) command, link conditions in user programs, and the Program Triggers.

User functions can have any number of parameters, and return a single value as the result. The parameters can be input, output, or input/output types. Therefore, a function can return many values via the output or input/output type parameters.

Example User Functions

See the Example User Functions for examples that you can copy and paste into your project.

Creating a User Function

In the Project Pane, expand Programming and double-click User Functions.
In the User Function Editor toolbar, click the New User Function button.
In the New User Function dialog, type a Name for the function.
Choose the desired Return Data Type. This is the data type of the resulting value returned by the function.
Add Parameters (optional)
Do the following for each parameter you wish to add. Parameters appear as Input, Output, and Input/Output variables in the user function. Parameters can also be added and modified later when editing the user function, as described in Declaring Variables in User Functions.
1. Click the Add button.
2. Type a Name for the function.
3. Choose the desired Data Type of the parameter. To create an array parameter, set the Size parameter to a value greater than 1.
4. In the Input/Output box, choose the parameter type:
  - Input
  - Output
  - Input/Output
5. Click OK.

To adjust the order of the parameters, use the Up and Down arrows. To delete parameters, use the Delete button.

Click OK.
The new function will be added to the User Functions list, and will appear in the editor.

Editing a User Function

User Function Description

The initial comment in the user function is the function description, enclosed by green parentheses with an asterisk: (* *). This description will appear when browsing the functions in the Expression Editor.

Enter a description that describes what the function does. It is good practice to clearly describe the parameters and return value. You do not need to describe the parameter data types, as this is automatically displayed in the Expression Editor.

Function Name

The function name and return data type is defined by the keyword FUNCTION. To change the function name or data type, change the text following the FUNCTION keyword. The entire function must also end with the END_FUNCTION keyword.

For example, mm2inch is this function's name, which returns a value of type REAL:

FUNCTION mm2inch : REAL

Variable Declarations

Functions can have input variables, output variables, input/output variables, and local variables. For details, see Declaring Variables in User Functions.

Editing the Function Body

The function body contains the code that the function executes when it is called. The code in the function body must follow the same syntax as the code used in the Expression (113) command. For details, see the assignment expressions topic. The function body can use all the same operators, functions, user functions, and keywords as used in assignment expressions.

Values can be passed into and out of a function via parameters. All variables of type Input, Output, or Input/Output that are declared in the function will be the parameters of the function. See Declaring Variables in User Functions for more details.

The following limitations apply to the user function body:

Output variables can only be assigned to. That is, Output variables can only be used on the left-hand side of assignment expressions.
Input variables cannot be assigned to.

Accessing Controller Tags

The code in a user function can directly reference controller tags, such as variables in the Variable Table, axis tags, etc. However, in order to keep a user function portable between RMCTools projects, it is good practice to limit direct referencing of controller tags and instead pass values in and out via the Input, Output, and Input/Output function parameters.

Function Return Value

Each function must have a return value. This is done by assigning a value to the name of the function. For example, consider a function named Average3. The return value could be expressed as:

Average3 := (Var1 + Var2 + Var3 ) / 3;

Managing User Functions

All user functions in the project are displayed in the User Function list. To add a user function, click the New User Function button. To delete a user function, click the Delete User Function button.

User Functions Folders

User functions can be organized into folders in the user function list.

To create a new folder, click the New Folder button on the toolbar. Type the folder name and press Enter.
To add new functions to the folder, select the folder, then click the New User Function button. You can also drag existing functions into the folder with the mouse.

Click the Delete Folder button to delete a folder and it contents.

Importing User Functions

Right-click in the function list pane and choose ImportUser Functions.
Browse for the RMCTools User Function Library (.rmcflib) file and click Open.
The user functions available in the RMCTools User Function Library file will be listed. Check the desired functions in the file to import. The Select All and Clear All buttons may assist you.
Imported functions cannot have the same name as a user function already in the project. These functions are labeled (duplicate). Use the Rename button to rename a function in the import list so that it can be imported.
After selecting the desired user functions to import, click OK.

Exporting User Functions

Right-click in the function list pane and choose Export User Functions.
Choose the functions to export, then click OK.
Browse to the desired location, enter a filename, then click Save.

Calling User Functions

To insert a user function into an expression:

Begin typing the name of the function and choose the function from the pop-up list.
Or, browse for the function on the Function tab of the Expression Editor and double-click it.
Type an opening parenthesis. A pop-up window will open, listing the required parameters for your convenience.
Make sure to enter all required parameters, separated with a comma.
Type a closing parenthesis.

Using the Function's Return Value

Typically, when calling a user function, the function's return value is assigned to some register. For example, the return value of the user function inch2mm is assigned to the variable MyPos here:

MyPos := inch2mm(_Axis[0].ActPos);

A user function can also be called without assigning the function's result to a register. This is useful when the function has output parameters. For example, consider the following user function that converts polar coordinates (radius and angle) to cartesian coordinates (x and y). The function has two input parameters and two output parameters:

BOOL Polar2Cart( [in] REAL radius, [in] REAL angle, [out] REAL x, [out] REAL y)

This user function can be used in an expression as follows:

Polar2Cart(MyRadius, MyAngle, MyX, MyY);

Limitations

The following limitations apply to calling user functions:

Any Output and Input/Output type parameters can only be step-local variables or variables in the Variable Table. They cannot be system tags. If the result of the function must go to a system tag, you can use a variable for the Output parameter, then use a separate expression to assign the variable value to the system tag.