MATLAB Runtime Server

Organizing Files and Managing Startup Tasks (GUI)

This section discusses the locations of the files you write for the runtime application. It also discusses the special startup and path definition functions that the Runtime Server invokes when it first runs. These utility functions, matlabrt and pathdefrt, are variations of the functions matlabrc and pathdef that commercial MATLAB invokes upon startup. The table below compares the startup sequences of the two versions of MATLAB; the file shown to the left of an arrow (->) launches the file shown to the right.

MATLAB Variant	Startup Sequence
Commercial	matlab -> matlabrc.m -> pathdef.m
Runtime Server	matlab -> matlabrt.p -> pathdefrt.p

Where to Place Your Files

When you package and ship the application, your files must reside in some directory underneath the MATLAB toolbox directory. This restriction has two important consequences, however:

• Because MATLAB caches the functions underneath toolbox, each time you change a file there you must either restart MATLAB or execute the command

• rehash toolboxreset

  to register the changes. In particular, this applies if you edit, recompile, delete, or move a file.

• If you decide to keep your own files in another location while developing the application (in order to avoid having to use rehash frequently) and move the P-files at the last minute to a subdirectory of toolbox, then you must remember to:
• List the destination subdirectory in the path definition P-file pathdefrt.p. The pathdefrt function is discussed below in Creating the Path Definition Function.
• Move the P-files to their toolbox destination during your testing process. Then use rehash toolboxreset to register the changes.
• Delete, regenerate, and move P-files to their toolbox destination each time you change the source M-files. Use rehash toolboxreset as necessary to register the changes to toolbox subdirectories.

Tip    You should avoid having multiple files on your path with the same name. You can use the which fun -all syntax to find out whether you have multiple functions named fun on your path.

Creating the Startup Function

The utility function matlabrt, essential for a MATLAB Runtime Server application, is a variation of the matlabrc function that commercial MATLAB uses. To create a matlabrt function for your application, you can modify the template toolbox\runtime\matlabrt_template.m, and place the modified file in toolbox\local. This section describes the properties that your matlabrt function should have.

Properties of the matlabrt Function.   The matlabrt function must:

• Reside in the toolbox\local directory
• Perform the ordinary startup tasks of matlabrc, such as calling the path definition function
• Launch the rest of the application, because matlabrt.p is the only file that the Runtime Server directly calls. For example, if your top-level application M-file is called myapp.m, then matlabrt.m should contain the line

• myapp

You can also choose to have matlabrt perform these optional tasks:

• (PC only) Set the global error behavior for the application. Include the command

• runtime errormode mode

  in matlabrt.m, where mode can be continue, quit, or dialog. This setting controls how the Runtime Server responds to untrapped errors: by ignoring them, prompting the user to quit, or prompting the user to decide between continuing and quitting. See Setting the Global Error Behavior on a PC for a complete description of these options. If you do not specify the global error behavior in matlabrt.m, then the Runtime Server defaults to the dialog setting.

• (UNIX only) Set the application's warning behavior. You might want to replace the warning backtrace statement in matlabrt.m with warning off. See Setting the Global Warning Behavior on UNIX and the sample matlabrt.m file.

Creating the Path Definition Function

The utility function pathdefrt, essential for a MATLAB Runtime Server application, is a variation of the pathdef function that commercial MATLAB uses. This section describes the variations involved and gives information on how you should design pathdefrt.

Properties of the pathdefrt Function.   The pathdefrt function should reside in the toolbox\local directory. It stores the path information and is called from matlabrt when the Runtime Server starts up.

All files that your application uses need to be on the Runtime Server path so that the Runtime Server can find them. This path should include only directories under the toolbox directory. For example, perhaps your own files will reside in toolbox\myapp in the end user's installation and perhaps your files depend on MATLAB functions from toolbox\matlab\general, toolbox\matlab\ops, etc.

The path should also include toolbox\local. Furthermore, if an application uses files from private or class directories (which depfun and depdir will indicate), then these directories should not be added to the path. However, their parent directories should be included on the path. For example, if depdir lists

• C:\matlab\toolbox\matlab\funfun\@inline

then the path should include the toolbox\matlab\funfun directory.

Private and class directories are described in the "Programming and Data Types" part of the MATLAB documentation. To find out whether your application uses private or class directories, apply depfun or depdir to the top-level application file and check the results for directories that either are named private or have the @ symbol at the beginning of their names.

Creating the pathdefrt.m Function.   You can adapt the template pathdefrt_template.m provided in the toolbox\runtime directory. To modify it for your application:

1. Copy pathdefrt_template.m into toolbox\local and rename it pathdefrt.m.
2. Use the depdir function to find out which directories contain necessary application files. If matlabrt.m is the top-level M-file for your application, then use the command below.

1. list = depdir('matlabrt');

3. Omit private and class directories from list.
4. Paste the contents of list into the pathdefrt.m file that you are building, and edit the lines as necessary to adjust formatting. Path elements should have the form

1. '$toolbox/matlab/general:'

   and not something like 'C:\Apps\matlab\toolbox\matlab\general'

5. If your own application files are not currently in a subdirectory of toolbox, then add entries to reflect your ultimate shipping structure. See Where to Place Your Files for more information about where to place your application files.

Other Path Specification Considerations

The Runtime Server generates warnings if it cannot locate all of the directories that are specified on the runtime path. For example, if you specify the specfun directory on the runtime path but do not ship it, then the Runtime Server generates the following warning at startup.

• Name is nonexistent or not a directory: 
  C:\matlab\toolbox\matlab\specfun
  

However, on PC platforms, this warning message is not actually visible to your end user because the command window is minimized. On UNIX platforms, if the warning level is not set to off, then the message is displayed in the terminal window.

Developing a MATLAB Runtime GUI Application

Compiling the Application (GUI)