Calling Functions

What Happens When You Call a Function

When you call a function from either the command line or from within another program file, MATLAB parses the function into pseudocode and stores it in memory. This prevents MATLAB from having to reparse a function each time you call it during a session. The pseudocode remains in memory until you clear it using the clear function, or until you quit MATLAB.

Clearing Functions from Memory

You can use clear in any of the following ways to remove functions from the MATLAB workspace.

Back to Top

Function Precedence Order

This topic explains how MATLAB determines which function to call when multiple functions in the current scope have the same name. The current scope includes the current file, an optional private subfolder relative to the currently running function, the current folder, and the MATLAB path.

MATLAB uses this precedence order:

1. Variables

   Before assuming that a name matches a function, MATLAB checks for a variable with that name in the current workspace.

   Note   If you create a variable with the same name as a function, MATLAB cannot run that function until you clear the variable from memory.

2. Nested functions within the current function

3. Local functions within the current file

4. Private functions

   Private functions are functions in a subfolder named private that is immediately below the folder of the currently running file.

5. Class constructors in @ folders

   MATLAB uses class constructors to create a variety of objects (such as timeseries or audioplayer), and you can define your own classes using object-oriented programming. For example, if you create a class folder @polynom and a constructor function @polynom/polynom.m, the constructor takes precedence over other functions named polynom.m anywhere on the path.

6. Overloaded methods

   Overloading refers to intentionally reusing the same name. Overloaded methods typically implement similar functionality for different data types or classes. MATLAB checks the classes of the input arguments to determine which method to use.

7. Functions in the current folder

8. Functions elsewhere on the path, in order of appearance

When determining the precedence of functions within the same folder, MATLAB considers the file type, in this order:

1. Built-in function

2. MEX-function

3. Simulink^® model, with file types in this order:

   1. SLX file

   2. MDL file

4. P-file (that is, an encoded program file with a .p extension)

5. Program file with a .m extension

For example, if MATLAB finds a .m file and a P-file with the same name in the same folder, it uses the P-file. Because P-files are not automatically regenerated, make sure that you regenerate the P-file whenever you edit the program file.

To determine the function MATLAB calls for a particular input, include the function name and the input in a call to the which function. For example, determine the location of the max method that MATLAB calls for double and int8 values:

testval = 10;
which max(testval)

built-in (matlabroot\toolbox\matlab\datafun\@double\max)  % double method

testval = int8(10);
which max(testval)

built-in (matlabroot\toolbox\matlab\datafun\@int8\max)  % int8 method

For more information, see:

• What Is the Search Path?

• Variables

• Nested Functions

• Subfunctions

• Private Functions

Back to Top

Resolving Difficulties In Calling Functions

The two most common problems related to invoking functions in MATLAB are:

• Conflicting Function and Variable Names

• Undefined Functions or Variables

Conflicting Function and Variable Names

MATLAB throws an error if a variable and function have been given the same name and there is insufficient information available for MATLAB to resolve the conflict. You may see an error message something like the following:

Error: <functionName> was previously used as a variable,
  conflicting with its use here as the name of a function 
  or command.

where <functionName> is the name of the function.

Certain uses of the eval and load functions can also result in a similar conflict between variable and function names. For more information, see:

• Troubleshooting: Loading Variables within a Function

• Alternatives to the eval Function

Undefined Functions or Variables

You may encounter the following error message, or something similar, while working with functions or variables in MATLAB:

??? Undefined function or variable 'x'.

These errors usually indicate that MATLAB cannot find a particular variable or MATLAB program file in the current directory or on the search path. The root cause is likely to be one of the following:

• The name of the function has been misspelled.

• The function name and name of the file containing the function are not the same.

• The toolbox to which the function belongs is not installed.

• The search path to the function has been changed.

• The function is part of a toolbox that you do not have a license for.

Follow the steps described in this section to resolve this situation.

Verify that You Have the Correct Spelling of the Function Name.  One of the first things to check when you are unable to invoke a function is the spelling of the function name. Especially with longer function names or names containing similar characters (e.g., letter l and numeral one), it is easy to make an error that is not easily detected.

An unrecognized function name may also be the result of case mismatch. For example, the name of the MATLAB function accumarray contains lowercase letters only. The following command fails because it includes an uppercase letter in the function name:

accumArray
??? Undefined function or variable 'accumArray'.

Using the alphabetical or categorized function lists in the MATLAB Help Browser can help you find the correct spelling.

Make Sure the Function Name Matches the File Name.  You establish the name for a function when you write its function definition line. This name should always match the name of the file you save it to. For example. if you create a function named curveplot,

function curveplot(xVal, yVal)
     - program code -

then you should name the file containing that function curveplot.m. If you create a pcode file for the function, then name that file curveplot.p. In the case of conflicting function and file names, the file name overrides the name given to the function. In this example, if you save the curveplot function to a file named curveplotfunction.m, then attempts to invoke the function using the function name will fail:

curveplot
??? Undefined function or variable 'curveplot'.

If you encounter this problem, change either the function name or file name so that they are the same. If you have difficulty locating the file that uses this function, use the MATLAB Find Files utility as follows:

1. Open the Find Files dialog box by clicking Edit > Find Files in MATLAB.

2. Under Find files named: enter *.m

3. Under Find files containing text: enter the function name.

4. Click the Find button

Make Sure the Toolbox Is Installed.  If you are unable to use a built-in function from MATLAB or its toolboxes, make sure that the function is installed. If you do not know which toolbox supports the function you need, reference the following list:

http://www.mathworks.com/support/functions/alpha_list.html

Once you know which toolbox the function belongs to, use the ver function to see which toolboxes are installed on the system from which you run MATLAB. The ver function displays a list of all currently installed MathWorks products. If you can locate the toolbox you need in the output displayed by ver, then the toolbox is installed. For help with installing MathWorks products, see the Installation Guide documentation.

If you do not see the toolbox and you believe that it is installed, then perhaps the MATLAB path has been set incorrectly. Go on to the next section.

Verify the Path Used to Access the Function.  This step resets the path to the default. Because MATLAB stores the toolbox information in a cache file, you will need to first update this cache and then reset the path. To do this,

1. Go to the File menu and select Preferences...

2. Go to the General heading. Click the button Update Toolbox Path Cache and press OK.

3. Go to the File menu and select Set Path...

4. Click Default, and a small dialog box opens warning that you will lose your current path settings if you proceed. Click Yes if you decide to proceed, and then click OK and then Save to finish.

(If you have added any custom paths to MATLAB, you will need to restore those later)

Run ver again to see if the toolbox is installed. If not, you may need to reinstall this toolbox to use this function. See the Related Solution 1-1CBD3, "How do I install additional toolboxes into my existing MATLAB" for more information about installing a toolbox.

Once ver shows your toolbox, run the following command to see if you can find the function:

which -all <functionname>

replacing <functionname> with the name of the function. You should be presented with the path(s) of the function file. If you get a message indicating that the function name was not found, you may need to reinstall that toolbox to make the function active.

Verify that Your License Covers The Toolbox.  If you receive the error message "Has no license available", there is a licensing related issue preventing you from using the function. To find the error that is occurring, you can use the following command:

license checkout <toolbox_license_key_name>

replacing <toolbox_license_key_name> with the proper key name for the toolbox that contains your function. To find the license key name, look at the INCREMENT lines in your license file. For information on how to find your license file see the related solution: 1-63ZIR6,"Where are the license files for MATLAB located?"

The license key names of all the toolboxes are located after each INCREMENT tag in the license.dat file. For example:

INCREMENT MATLAB MLM 17 00-jan-0000 0 k
B454554BADECED4258 \HOSTID=123456 SN=123456

If your license.dat file has no INCREMENT lines, refer to your license administrator for them. For example, to test the licensing for Symbolic Math Toolbox, you would run the following command:

license checkout Symbolic_Toolbox

A correct testing gives the result "ANS=1". An incorrect testing results in an error from the license manager. You can either troubleshoot the error by looking up the license manager error here:

http://www.mathworks.com/support/install.html

or you can contact the Installation Support Team with the error here:

http://www.mathworks.com/support/contact_us/index.html

When contacting support, provide your license number, your MATLAB version, the function you are using, and the license manager error (if applicable).

Back to Top

Calling External Functions

The MATLAB external interface offers a number of ways to run external functions from MATLAB. This includes programs written in C or Fortran, methods invoked on Sun Java or COM (Component Object Model) objects, functions that interface with serial port hardware, and functions stored in shared libraries.

Back to Top

Running External Programs

For information on how to invoke operating systems commands or execute programs that are external to MATLAB, see Running External Programs.

Back to Top

Share Data Between Workspaces

Functions Provided By MATLAB

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit