MathScript Nugget #10: How To Call User-Defined Functions

[jattas]

Many of the questions on the MathScript discussion forum have focused on the topic of calling user-defined functions. In the next few nuggets I hope to give a "quick-start" introduction on how to do this, cover some common mistakes, and go into some cool advanced features when calling user-defined functions. 

User-defined functions in MathScript are the equivalent of subVIs in LabVIEW. You can use them to define a function in one file and call it from one or more other places in your code. User-defined functions live in .m files, which are just text files saved on disk with a .m extension. 

A .m file must be in one of two formats: function or script. Functions are more common so I'll discuss them today and describe scripts in a future nugget. A function is code that takes inputs and returns outputs. The function executes in its own workspace. This means that variables in the caller code cannot be accessed from the function unless they're passed in and variables from the function cannot be accessed from the caller unless they're passed out. To define a function in your .m file, the first line of the file must look like this: 

function [output1, output2] = function_name(input1, input2)

The name of the file must exactly match 'function_name' (plus the '.m' extension). You can have any number of inputs or outputs. Below the signature comes the body, which contains MathScript code that defines the values of the outputs based on the values of the inputs. For example:

 

output1 = input1+input2;
output2 = input1-input2;

Below this, you can put zero or more additional function signatures and definitions. These are called sub-functions. They will only be accessible from within this .m file. Check out the MathScript Function Syntax (http://zone.ni.com/reference/en-XX/help/371361F-01/lvhowto/mathscript_function_syntax/) page of the LabVIEW help for more information. 

Now that you've written a .m file, you probably want to call it. To call a function in a .m file, you must ensure that LabVIEW can find the file. You do this by setting the MathScript search path. How you do this depends on where you are calling the function. 

• To call it from the MathScript Window, go to File>>LabVIEW MathScript Properties. 
• To call it from a VI in a project, right-click on My Computer>>Properties>>MathScript: Search Paths. 
• To call it from a VI outside a project, use the Tools>>Options>>MathScript page. 
• In any of the above locations, if you need to set the search path dynamically, you can call functions like addpath to do this. Be aware that this causes a warning glyph because of its dynamic nature. 

Whichever place you set the search path, the important thing is to ensure that the search path includes the directory where your .m file is located. The default search path is the LabVIEW Data directory. If you just want to create a quick function for testing purposes, this is a good place to save it.

Once you've set the search path, you can call your function from the MathScript Window, the MathScript Node, or another .m file by using the name of the file that you saved it in (without the extension), like so:

[sum, difference] = function_name( 34, 1 )

All of the above information (and more) is contained in the LabVIEW Help topics on user-defined functions: 

Defining Functions and Calling Functions

Stay tuned next week for more useful tips on working with user-defined functions in MathScript.

jattas

LabVIEW MathScript R&D 

ps. Check out more MathScript Nuggets! 

[Doug]

"....and describe scripts in a future nugget...."

Did you ever get around to describing how to call scripts?

Thanks,

Doug

[jattas]

Hi Doug,

In fact, I did not. It's very similar to what I described above, but with a few important differences:

1. When you define your script, you don't write the first line with the "function" keyword and your function signature. The script .m file just contains lines of MathScript code.
2. When you call your script, you won't pass inputs or outputs. You'll just type the name of the script file (without the .m).
3. The script executes in the same context as the calling code. This means that the script can access all variables defined in its caller and the caller can access all variables defined by the script.
4. Scripts cause a warning glyph, meaning the code will operate with reduced edit-time error checking and slower performance. So while scripts are handy, if your code is performance-critical you might want to consider inlining the script or putting the code in a function instead.

I hope this helps!

jattas

[Doug]

Thanks for the response jattas.  Unfortunately, it looks like Mathscript won't work for us after all.  My original intent for using Mathscript was to allow one of our engineers write a script and call it from an upper level LV program.  Any changes could be made to the script, avoiding a LV recompile.  I found out however that LV wants the script at compile time.  Any changes in the script would need to be compiled in, defeating the purpose.

Thanks again,

Doug

[jattas]

Hi Doug,

You are correct in noticing that MathScript is compiled along with the rest of your VI. This is how it achieves faster performance and real-time execution.

You might be able to get around this by using the eval function, which compiles a script at run-time. However, this solution won't work in a built application or real-time application and it will offer much slower performance. You could also see if the Formula Parsing VIs work for your use case.

Good luck,

jattas

[AlbertDeWeese]

This can be done with LV OOP.  If this is still a need ping me at albert.deweese at goodautomation.com.  Create an abstract class and an abstract method that calls the math script.  Then overload it with specific implementations.  LV supports inversion of control.  I'd be happy to help.