MATLAB Runtime Server

Adapting the Design for Runtime Execution

Two aspects of this example make it suitable for runtime execution:

• The way its front-end GUI design passes information among the user, the Visual Basic portion, and the MATLAB portion
• The way its top-level M-file passes information between the Visual Basic portion and the rest of the MATLAB portion

This section describes each of these two aspects in turn.

The Front-End GUI

This example is a simple GUI-driven application that evaluates and plots a MATLAB expression. Its GUI is shown below.

To use the application, enter a valid MATLAB expression in the Plot field of the GUI and press the Draw button. The application opens a MATLAB figure window containing the plot, and the Draw button becomes inactive.

When you press the Erase button, the plot is erased and the Erase button becomes inactive. This illustrates how the Runtime Server can return information to the Visual Basic controller.

The following sections discuss the Visual Basic code that is executed for the GUI events and form initialization. You can look at the code (as well as the objects' properties) by opening project myappVB.Frm in Visual Basic 5 or later.

Note    You can view the available Automation methods for MATLAB from within the Visual Basic environment. First check the Matlab Application (Version 6.0) Type Library in the References dialog box (from the Project menu). Then use the Object Browser (from the View menu) to list the members of the MLApp library.

General Declarations Section.   This section makes four declarations. MatLab is declared as a variable of type Object, MLResReal and MLResImag are declared as variables of type Double, and MLStatus is declared as a variable of type String.

• Option Explicit
  Option Base 1
  Dim MatLab As Object
  Dim MLResReal(1) As Double
  Dim MLResImag(1) As Double
  Dim MLStatus(1) As String
  

MatLab is the Visual Basic variable that represents the MATLAB Automation object; the actual assignment is made in the Form_Load procedure below. MLResReal and MLResImag are the Visual Basic variables that will contain the real and imaginary parts of MATLAB workspace variables returned by the GetFullMatrix Engine method. MLStatus is the String variable that will contain any error message returned from MATLAB.

Declaring these variables in the General Declarations section (outside of any Visual Basic functions) ensures that they do not lose scope during program execution, which is especially important for the MATLAB Automation object.

Form Load Procedure: Form_Load.   The Form_Load procedure is executed as the Visual Basic program starts up.

• Private Sub Form_Load()
  Set MatLab = CreateObject("MatLab.Application")
  MatLab.Execute ("myapp('init')")
  End Sub
  

The MATLAB Automation object is now assigned to the MatLab variable, which causes MATLAB to launch. The copy of MATLAB that launches at this time is the copy that was most recently run as an Automation server on the system. If MATLAB is currently running as an Automation server on the system, the running MATLAB is used by the Automation controller.

The MatLab.Execute statement contains a function call to the top-level M-file, myapp. The string "myapp('init')" is evaluated in the MATLAB workspace, and myapp is called with the argument 'init'. See Initialization Function: myapp_init for more information about this function call.

Button Draw Procedure: btn_Draw_Click.   The btn_Draw_Click procedure is executed when a button-click event occurs at the Draw button.

• Private Sub btn_Draw_Click()
  Dim MsgBoxText As String
  Dim MsgBoxReturn As Integer
  MatLab.Execute ("myapp('draw','" + txt_Input.Text + "')")
  Call MatLab.GetFullMatrix("draw", "base", MLResReal, MLResImag)
  If MLResReal(1) = 1 Then
     btn_Draw.Enabled = False
     btn_Erase.Enabled = True
  Else
     MLStatus(1) = MatLab.Execute("disp(lasterr)")
     MsgBoxText = "Myapp cannot evaluate your input." _
                  + Chr(13) & Chr(10) + _
                  Left(MLStatus(1), (Len(MLStatus(1)) - 1))
     MsgBoxReturn = MsgBox(MsgBoxText, 0, "Error")
     btn_Draw.Enabled = True
     btn_Erase.Enabled = False
  End If
  End Sub
  

The first Execute command (line 6) evaluates the string "myapp('draw','input')" in the MATLAB workspace, where input is the expression the user enters in the Plot field. This calls myapp with two arguments. The first argument, 'draw', instructs myapp to pass the second argument, 'input', to function myapp_draw (see Draw Function: myapp_draw). myapp_draw attempts to plot the expression, and stores a value of 1 in the base workspace variable draw if it is successful. If plotting generates an error, myapp_draw stores a value of 0 in draw instead.

The GetFullMatrix statement then retrieves the value of draw into MLResReal; MLResImag remains empty because there is no imaginary component.

The If-Then-Else statement checks the value of MLResReal to determine the result of the plotting operation:

• If successful (MLResReal=1), the following statements change the state of the buttons accordingly.

• btn_Draw.Enabled = False
  btn_Erase.Enabled = True
  

• If an error occurred (MLResReal=0), the Else block performs the following operations:
• Evaluate the string "disp(lasterr)" in the MATLAB workspace. Since the disp command here is invoked via the Engine's Execute method, its output is returned in variable MLStatus rather than being displayed in the command window. MLStatus therefore contains the text of the most recent MATLAB error message.
• Compose an error message (MsgBoxText) based on the contents of MLStatus
• Display the message in a Visual Basic message box
• Change the state of the buttons appropriately

Button Erase Procedure: btn_Erase_Click.   The btn_Erase_Click procedure is executed when a button-click event occurs at the Erase button. Its Execute command passes the 'erase' argument to myapp, and again changes the state of the buttons depending on the value of draw in the workspace (see Erase Function: myapp_erase).

• Private Sub btn_Erase_Click()
  MatLab.Execute ("myapp('erase')")
  Call MatLab.GetFullMatrix("draw", "base", MLResReal, MLResImag)
  If MLResReal(1) = 1 Then
     btn_Draw.Enabled = False
     btn_Erase.Enabled = True
  Else
     btn_Draw.Enabled = True
     btn_Erase.Enabled = False
  End If
  End Sub
  

Button Quit Procedure: btn_Quit_Click.   The btn_Quit_Click procedure is executed when a button-click event occurs at the Quit button.

• Private Sub btn_Quit_Click()
  Form_Terminate
  End Sub
  

The Form_Terminate function (see below) quits the Visual Basic application.

Menu Quit Procedure: menu_Quit_Click.   The menu_Quit_Click procedure is executed when the Quit menu item is selected.

• Private Sub menu_Quit_Click()
  Form_Terminate
  End Sub
  

The Form_Terminate function (see below) quits the Visual Basic application.

Form Terminate Procedure: Form_Terminate.   The Form_Terminate procedure is executed when the Visual Basic GUI's Close box is clicked (or when this procedure is called from btn_Quit_Click or menu_Quit_Click). The End command quits the Visual Basic application.

• Private Sub Form_Terminate()
  End
  End Sub
  

The MATLAB Runtime Server detects that the Automation controller has quit, and automatically quits as well.

Creating the Top-Level M-File

This example uses a top-level M-file, myapp, to act as an intermediary between the Visual Basic front end and the application's M-files (runtime P-files, when compiled). The contents of this function are shown below. When an event occurs in the GUI that requires a MATLAB function to execute, the GUI calls myapp with an appropriate argument indicating the action to be taken. This function is the only MATLAB function that this application's GUI calls directly.

• function myapp(action,varargin)
  % Top-level M-file for an Engine-based Visual Basic application.
  switch action
  case 'init'
     myapp_init
  case 'draw'
     myapp_draw(varargin{:})
  case 'erase'
     myapp_erase
  end
  % Other application M-files, not called from myapp.m
  if 0
     matlabrt
  end
  

This top-level M-file responds to three possible calls from the Visual Basic controller: 'init', 'draw', and 'erase'. Depending on which of these action arguments Visual Basic calls it with, myapp executes one of three functions: myapp_init, myapp_draw, or myapp_erase. When myapp calls myapp_draw, it also passes the string in cell array varargin, which is the expression in the GUI's Plot field.

These three functions are discussed below. Note that the top-level M-file here does not create a GUI, since this has already been done by the Visual Basic front end.

One additional feature of the myapp function is the nonexecuting if statement containing a call to matlabrt. By including a dummy invocation of matlabrt in myapp, you can avoid having to use buildp or depfun on both files in order to analyze the entire application - you only need to apply those functions to myapp.m. The if statement is ignored at runtime.

Initialization Function: myapp_init.   This function sets up the figure window.

• function myapp_init
  %MYAPP_INIT Initialize the Figure window.
  fig = figure('Units','points','Position',[36 560 420 315],...
  'Resize','off','HandleVisibility','on','Menubar','none',...
  'NumberTitle','off','Name','Myapp',...
  'CloseRequestFcn','close force');
  ax = axes('Parent',fig,'Units','points',...
  'Position',[42 50 335 230],'HandleVisibility','on','Box','on');
  

The figure command in the above code specifies a CloseRequestFcn for the figure and includes the 'Menubar','none' specification to deactivate the default menus.

Draw Function: myapp_draw.   This function evaluates and plots the expression contained in the plottext input argument.

• function myapp_draw(plottext)
  %MYAPP_DRAW Evaluate input string and plot in the Figure window.
  Out = evalc('figure(findobj(''Name'',''Myapp''))',...
  'myapp(''init'')');
  try
     plot(eval(plottext));
     evalin('base','draw = 1;');
  catch
     evalin('base','draw = 0;');
  end
  

The 'try' part of the evalc('try','catch') statement in the definition of Out makes the Myapp figure window active if it already exists. If it does not, the 'catch' calls myapp with the 'init' switch to create a new Myapp figure window.

The try block of code then attempts to plot the plottext expression (which contains the string in the GUI's Plot field). If the plotting operation is successful, the second line sets the value of the workspace variable draw to 1. The Visual Basic application uses this as an indication that the expression was plotted. If an error occurs during plotting, the catch block of code sets the value of draw to 0. The Visual Basic application uses this as an indication that an error occurred and the expression was not drawn; see Button Draw Procedure: btn_Draw_Click.

Erase Function: myapp_erase.   This function clears the axes in the figure window.

• function myapp_erase
  %MYAPP_ERASE Erase the plot in the Figure window.
  Out = evalc('figure(findobj(''Name'',''Myapp''))',...
  'myapp(''init'')');
  cla;
  evalin('base','draw = 0;');
  

The eval('try','catch') statement is the same as that in function myapp_draw. After making Myapp the active figure window, the function clears the axes and sets the value of the workspace variable draw to 0. The Visual Basic application uses this as an indication that the plot area was erased; see Button Erase Procedure: btn_Erase_Click.

Installing the Example Files

Organizing Files and Managing Startup Tasks