Instructions for Developing Matlab Web Server Applications for HST.582/6.555

I. Introduction

MathWorks' Matlab Web Server product (henceforth referred to as Matweb) allows users to run Matlab applications remotely over the Web. Matweb accepts inputs from a Web browser and returns output to the browser for display. Matweb obviates the need to run a local copy of Matlab. Current Matweb is hosted on the ACS server at acs-www.mit.edu. The same server also runs a copy of Matlab. The Matweb applications for HST.582/6.555 resides in the course's Athena locker, under /afs/athena.mit.edu/course/6/6.555.

The MathWorks Web site contains more detailed information on the features of Matweb. Matweb's user manual is also available for download from the site. Please refer to the following links for more information:

There are 3 required files for a Matweb application:

Input HTML file
Application m-file
Output HTML file

MathWorks provides templates for each of these files and also a few demos illustrating their usage in the Matweb distribution. The templates and demos have been modified to suit our setup and are stored in the directories matweb/templates and matweb/demos, respectively, in the course locker.

This document provides guidelines for creating Matweb applications for use in HST.582/6.555. For the most part, this document provides information that is not available or is provided with insufficient details in the official documentation.

II. Procedure to create a new application M-file:

1. Creating an input HTML file

- The input HTML file should contain at least the following tags:

<FORM ACTION="http://acs-www.mit.edu/cgi-bin/matweb" METHOD="post">
<INPUT TYPE="hidden" NAME="mlmfile" VALUE="matweb6_555">
<INPUT TYPE="hidden" NAME="runmfile" VALUE="<my_app>">
</FORM>

Replace <my_app> with the name of the appropriate application m-file.

2. Creating an application M-file

- This file should be named <my_app>.m and placed in either the same directory as matweb6_555.m (which currently resides in /mit/6.555/matweb), or in a directory known to matweb6_555.m. This is because matweb6_555.m is actually a "launcher" script that executes <my_app>.m. This setup was needed because each Matlab application that accesses Matweb needs to be registered with Matweb. Having a single top-level script like matweb6_555.m launch the actual script means that we would not have to register each new application that we create.

- Use /mit/6.555/matweb/webmagic.m for a template to create an application that does not generate graphics. Follow /mit/6.555/matweb/webpeaks.m to create an application that generates graphics.

- The application m-file must call htmlrep with the output structure and the name of the output HTML file. Specify the absolute path for the output HTML file, as it is located in a different directory from the working directory; e.g., htmlrep(outstruct,'/afs/athena/course/6/6.555/matweb/dev/webpeaks2.html')

3. Creating an output HTML file

- The output HTML file specifies how the output will be displayed, with the output variables specified between $...$ . The names of the output variables are the same as the names of the fields of the output structure specified in <my_app>.m.

- Output variables which are matrices can be automatically displayed in a table with the AUTOGENERATE option of the <TABLE> tag; e.g.,


  <TABLE AUTOGENERATE="$my_variable$">

  <TR>

      <TD ALIGN="right">

      </TD>

  </TR>

  </TABLE>

The table should contain empty cells. Consult the Matlab Web Server manual, under the entry for HTMLREP, for more information.

- Images generated by <my_app>.m must be specified with the absolute URL as they reside on the acs-www.mit.edu server; e.g.,
<IMG SRC="http://acs-www.mit.edu/matweb/tmp/$GraphFileName$">

4. Paths and URLs

- /mit/6.555/matweb - Directory containing M-file and launcher. Note that /mit/6.555 is an alias for /afs/athena.mit.edu/course/6/6.555.

- /var/local/httpd/htdocs/matweb/tmp - temporary directory on acs-www.mit.edu for storage of graphics files (JPEG and PCX).

III. Procedure to create a stand-alone test M-file

- When using Matlab Web Server in normal mode, the user submits data to the Web server through the Common Gateway Interface (CGI). Using this method, we can't easily look at the outputs of the Matlab functions or modify the input variables for
testing purpose. The stand-alone test file is a Matlab function that mimicks data submission through the Web. By bypassing the Matlab Web Server, we can concentrate on debugging the application m-files.

- When we run the stand-alone test file, it needs access to certain Matlab functions provided with the Matweb distribution; e.g., wsprintjpeg.m, which converts a plot into a JPEG file. These functions have been copied to a directory accessible on Athena. When you start Matlab, be sure that this directory is in your search path by either entering the following command at the Matlab prompt or placing it in startup.m: addpath /afs/athena/astaff/project/instructor/matweb/toolbox. It is also advisable to place the matweb directory in your Matlab path with addpath /afs/athena.mit.edu/course/6/6.555/matweb.

1. Modifying the stand-alone test file, /mit/6.555/matweb/tlauncher.m

The value of the field mlmfile is always matweb6_555. This is our launcher application. Its name is fixed because it had to be registered with Matlab Web Server.
If the name of our application m-file is <my_app>.m, set the field runmfile to <my_app>.
The value of the field mldir is unimportant because we don't make use of it.
Set the field mlid to something unique. This value will be appended to the name of any graphics files. We have to make sure it's unique to keep from overwriting previously generated files.
Set values for input variables whose names correspond to names of fields of the input structure.
Call the launcher with the input structure and the name of an output file; e.g., str = matweb6_555(instruct, 'tlauncher.html')

2. Modifying the application M-file

- The application m-file stores any generated graphics in a temporary directory on the ACS server. It changes the working directory to this directory. When we're running a stand-alone m-file, we do not have access to this directory (we're running Matlab on a different machine from the ACS server). Therefore we must modify the application m-file to use a different working directory that's accessible to us; e.g., '/afs/athena/course/6/6.555/matweb/tmp'.

3. Modifying the output HTML file

- The output HTML file refers to the generate graphics through an absolute URL. To reflect the new location of the generated graphics, modify the link to show the new location; e.g., <IMG SRC="http://mit.edu/6.555/matweb/tmp/xxxxwebpeaks.jpeg">

After making the above modifications, run tlauncher.m in Matlab. Examine its output and also look at tlauncher.html.

Dec 2, 1999
Dinh-Yen Tran
dinhyen@mit.edu