SLAC ESD Software Engineering Group
	AIDA Using AIDA from Matlab	SLAC Detailed SLAC Computing Software Home Software Detailed AIDA

This page describes how to setup and use AIDA from inside Matlab. Both Unix and Windows PC based Matlab installations, as available at SLAC, are covered.

Contents: Using Aida through Matlab, Configuration, Setup Aida on Unix, Setup Aida on Windows PC, Setup Aida on Mac OS X, Programmers Guide
See also: The Aida type codes, Mathwork's Matlab External Interfaces Guide (including Java), SLAC Electronic Design Applications Page (including SLAC's Matlab)

Screenshots: Matlab using Aida on Windows

In general, using Aida from Matlab is very simple. The principle is to use Matlab's existing facilities for calling Java methods directly. So Aida's application programming interface (API) for Matlab is exactly its regular Java API!

Setup: Setting up Matlab for Aida amounts to simply making the Aida jar files, and Aida's requisite CORBA jar files, available to the Matlab session in question. See the instructions for setup on AFS Unix, Windows PC, and Mac OS X below. Additionally, Matlab's Java Virtual Machine (JVM) must be started with some Java options used by Aida. See Configuration below for step-by-step instructions.

Prerequisites: on both Unix and Windows, you must use at least Matlab r14 SP2 (!) (yes, even the SP2 part is important). For Windows this implies Matlab v7.0.4, on AFS Solaris it implies starting Matlab with /afs/slac/package/matlab/14.2/bin/matlab -nodesktop. This is because r14 comes with, and uses, Java v1.4.2, which is ideal for Aida, and SP2 corrects a problem in Matlab's Java interpreter which causes an assertion in Orbacus to fail when Aida's DaObject is instantiated a second time.Aida through matlab 7 (SP2) on Mac OS X has also been tested. See CAE's Electronic Design Applications for the licensing setup.

Using Aida from Matlab

This section describes some basic commands for getting data into Matlab through Aida. To use Aida, you will code essentially Java calls through the Matlab's Java interpreter. As such, it's useful to know how Matlab understands Java objects, especially arrays. Check out Matlab's Calling Java from Matlab, in particular the sections on Invoking Methods on Java Objects, and Working with Java Arrays.

What can Aida acquire - how do I get those names?

For help with "what Aida can acquire" see the Basic Users Guide to Aida and each of Aida's Individual Data Provider Users Guides. There is Bourne shell script 'aidalist', and a matlab m-file 'aidalist.m' which can be used to get lists of acquireable names.

First Steps Tutorial

In this section we start a cmlog error message client, start Matlab, go through some steps to initialize Aida, and then make a couple of data acquisitions.

Before starting Matlab (or in another window) start a cmlog client. Aida issues errors to cmlog, so if something goes wrong with your queries it's a good idea to have a cmlog client going. At present, cmlog should be started on the PROD realm for Aida. Log into something like flora (presently there's no way to use cmlog directly on a PC, you will have to start it on Unix and use an X-server on your PC).

flora> source /afs/slac/g/cd/soft/dev/script/ENVS.csh
flora> source /afs/slac/g/cd/soft/dev/script/cmlogSetup.pepii.public
flora> cmlog -u &

Now start Matlab (see above) on unix or your PC:

[tersk09]:u/cd/greg> /afs/slac/package/matlab/14.2/bin/matlab -nodesktop
                              < M A T L A B >
                  Copyright 1984-2005 The MathWorks, Inc.
                   Version 7.0.4.352 (R14) Service Pack 2
                              January 29, 2005
 
  To get started, type one of these: helpwin, helpdesk, or demo.
  For product information, visit www.mathworks.com.

First set up the Matlab session for Aida with aidainit.m, eg:

>> aidainit

Instantiate a DaObject. This is your basic link to Aida. You can issue queries using it directly, or pass it to things like Aida reference objects. This establishes your connection to the Aida network and may take a second or two also.

>> da = DaObject()

To test it, make the simplest possible acquisition. This will get the value of TEST//VAL, a reliable test value, as a DOUBLE:

>> v = da.get('TEST//VAL',4)

v =

  567.8900

The '4' above is the given type of the value that was wanted in this case. 4 means DOUBLE. You have to tell Aida what is the type of the value you want returned (even though Aida may know that the actual type of the data item in its data store). Note that Aida can't just return a value of the type of the data, even though it knows the data's type, because it doesn't know what was on the left hand side of the equals sign.

So, you have to tell Aida the data type you want it to return. The Aida type codes are listed here (see under edu.stanford.slac.aida.lib.util.common.DaValue.Type).

Example of getting simple SLC database data

Reusing the same DaObject as was created in the previous example, we can get some SLC db data. Just name the device you want in the name syntax outlined in the SLC Database Data Provider Guide, and give the data type from the the Aida type codes. For instance:

 >> da.get('YCOR:PR12:1052//BACT',4)

ans =

    0.0017

Example of getting simple SLC Model data

da.setParam('MODE=7');                                                                    
tps = da.geta('BPMS:PR02:8032//twiss', 55);                
Twiss = double(tps)

% R-matrix (computed) of the BPM, same Mode.
R = double(da.geta('BPMS:PR02:8032//R', 55));
rmatrix=reshape(R,6,6)'         % Note transpose

Note that the acquisition of R-matrix, used the same parameter ('MODE=7') as the twiss acquisition. That's because the same DaObject was used. If you want to clear the parameters of a DaObject, use da.reset();. Alternatively, you can use different DaObjects with different parameters set in each.

Example of Getting History Data

This example demonstrates getting a DaValue structure, which may well contain complex Java constructs like an array of strings, and using Aida in a Matlab function.  The following example can be looked at in four blocks, i) aida initialization in a matlab function, ii) actually getting the data, iii) converting from Java array types to matlab array types, iv) Plotting and labeling.

Note that the Aida API method used is getDaValue(), which returns a DaValue. The SLC History Data Provider Guide tells us that AIDA's SLC History Data Provider in fact only responds to calls of getDaValue (and getAny, which is more complicated). The EPICS AIDA Data Provider also accepts getDaValue() calls, so histDemo.m can be used to get either SLC or EPICS history data.

DaValues are structures which may themselves contain fundamental types, or arrays of fundamental types, or even DaValues! This basic structure for complex data is supported by some Aida Providers, including the SLC History Data Provider. In this case, the DaValue contains an array of Doubles, and an Array of strings. This example is taken directly from histDemo.m

For correct syntax for the name, starttime, and endtime arguments, see the SLC History Data Provider Guide.

function [values, times ] = histDemo(name, starttime, endtime)

% Acquires and plots history of some Aida name between given
% starttime and endtime.
% 
% [values, times] = histDemo(name, starttime, endtime)
%
% name - is the name of an AIDA acquireable history variable. These
% typically end in //HIST, or sometimes //HIST.pepii if from
% EPICS. See aidalist unix script.
% starttime - Beginning time in format 'mm/dd/yyyy hh:mm:ss'
% endtime - Ending time in format as starttime above.
%
% Example:
%
% >> histDemo('PB60:LUMCOR//HIST.pepii','05/06/2005 00:00:00',...
% '05/07/2005 00:00:00');

aidainit; 

err=Err.getInstance();
da = DaObject();
disp 'Acquisition begins ...'
da.setParam('STARTTIME',starttime);  
da.setParam('ENDTIME',endtime);   
hist = da.getDaValue(name);                          
disp 'Acquisition ends successfully'

pts = hist.get(0).size();                        
dblArray = javaArray('java.lang.Double',pts);   
values = double(hist.get(0).toArray(dblArray));                      
StringArray = javaArray('java.lang.String',pts);
times = char(hist.get(1).toArray(StringArray));                      

disp 'Plotting...'
plot(datenum(times),values,'-+');
datetick('x');
xlabel(sprintf('%s - %s',times(1,:),times(end,:)))
title(name);
 
return;

aidalist.m

aidalist.m just runs the Bourne shell script named 'aidalist' on AFS. So, if you're not on some SLAC AFS machine, but are instead on something like your own Mac or linux, aidalist.m won't work - unless you hack it to execute aidalist over ssh. You will need to have setup "passwordless" login on your machine. Then edit your own aidalist.m and replace both of the 2 lines that look like this (taking the first as an example):

query = sprintf('aidalist %s',varargin{1});

with something like this (all one line):

query = sprintf('ssh -lyourname -x -1 -T -q slac-host-to-which-you-authenticate /afs/slac/g/cd/soft/prod/solaris/bin/aidalist %s',varargin{1});

Error Handling and Error Messages

Aida uses Exceptions to handle errors. That is, when a function is called, and it causes an error, the function itself does not "return" an error code as such. Rather it causes a special object, called an "exception" to be signaled to some special purpose code, whose job it is to listen for that signal and then take the appropriate steps. This is a powerful scheme, but it's most appropriate when working in a full Object Oriented programming language. Matlab's understanding of these signaled exception objects is pretty basic, but it does a reasonable job of detecting when one has occurred and interrupting execution. There is more information in Mathworks website.

When Aida encounters an error when processing a request, you will see output that will look something like this:

>> query='BPMS:PR08:0000//twiss';
>> tps=da.geta(query,55);        
??? Java exception occurred: 
edu.stanford.slac.except.UnableToGetDataException: IDL:slac.stanford.edu/except/UnableToGetDataException:1.0
        at edu.stanford.slac.except.UnableToGetDataExceptionHelper.read(UnableToGetDataExceptionHelper.java:67)
        at edu.stanford.slac.aida.lib.dp._AidaObjectIStub.get_floata(_AidaObjectIStub.java:1069)
        at edu.stanford.slac.aida.lib.da.DaObject.doGeta(DaObject.java:301)
        at edu.stanford.slac.aida.lib.da.DaObject.geta(DaObject.java:256).

So, matlab was "thrown" the UnableToGetDataException object. You will have to look in cmlog to see what went wrong. cmlog will tell you that, in this case, the NameServer got an UndefinedNameException when looking up BPMS:PR08:0000.

Configuration

This section describes the once only configuration of matlab necessary for using Aida from a number of platforms. Check the prerequisites above before embarking.

Setup Aida on Unix (AFS) hosted Matlab

This section discusses how to setup a Matlab session running on an SLAC AFS unix host. This will probably be some Solaris OS machine, but these instructions may be generalized for Linux.

Once Only Configuration

1. Copy /afs/slac/g/cd/soft/ref/package/aida/common/script/java.opts to your matlab startup directory (the directory from which you start matlab).
2. Copy /afs/slac/g/cd/soft/dev/matlab/aidasetup.m and /afs/slac/g/cd/soft/dev/matlab/aidainit.m to some place in your matlab path. Alternatively, make sure you source ENVS.csh before starting matlab (as described below), which sets MATLABPATH, to include that directory.

Note on starting matlab r14 on Solaris

CAE's instructions for starting matlab14 are source /afs/slac/package/ecad/custom/util/cae_aliases followed by matlab14. This, sets the appropriate license configuration right at startup time, but it necessarily implies using the "desktop" matlab configuration, which can be very slow on Solaris.

Alternatively, you may prefer to set the licensing information separately (for instance in your .cshrc), and then start matlab "manually", giving the -nodesktop option.

> /afs/slac/package/matlab/14.2/bin/matlab -nodesktop 

Setup Aida on Standalone Mac OS X hosted Matlab

This section discusses how to setup a Matlab session running on an a Mac running OS X without using AFS - that is, putting all files needed for Aida on your Mac.

Once Only Configuration

1. Copy /afs/slac/g/cd/soft/dev/matlab/aidasetup.m and /afs/slac/g/cd/soft/dev/matlab/aidainit.m to some place in your matlab path (check the value of PATH in Matlab), for instance /Applications/MATLAB702/toolbox/local/.
2. Get the JAR files referenced in aidasetup.m also onto your Mac. See the notes on aidasetup.m below and in particular the location of the files it references. On my mac I put the 6 jar files in a new directory "aida" I created under /usr/local/ (since they're utility libraries), but for that I need to sudo. If you aren't comfortable as sudo just put them somewhere accessible, such as /Applications/MATLAB702/toolbox/local/. Then edit your aidasetup.m to point to the local jar files rather than those on AFS.
3. Copy /afs/slac/g/cd/soft/ref/package/aida/common/script/java.opts to your matlab startup directory (hint: do a 'pwd' in matlab). Then edit your java.opts to change the "-Xbootclasspath:p" entry to point to the OB.jar you put on your Mac in step 2 (eg "/usr/local/aida/OB.jar"). Check the comments on java.opts below before making the edit.
4. In some circumstances you may have to edit your mac's /etc/hosts file to add the name and IP address of the EventService ($OOC_COSEVENT_HOST) - which has to be done sudo. The name of the host should only the nodename part. You have to restart the mac after making the edit and before trying aida.

Setup Aida on Windows PC hosted Matlab

This section discusses how to setup a Matlab session running on Windows.

Once Only Configuration

The following scripts configure Matlab so that it can use Aida. They both contain references to files on the Windows filesystem using the SLAC drive mapping conventions; that is, your computer must have the "V" drive mounted to use these files "as is*".

1. Copy V:\CD\soft\ref\package\aida\common\script\java.opts to your matlab system directory (this will be named something like C:\Program Files\MATLAB\<release>\bin\win32). java.opts is the file Matlab checks for on startup, which tells it which options should be passed to its Java VM. It also defines which Aida "network" is to be connected to. Matlab's failure to find this file at startup is the most common cause of errors in setting up Aida for Windows Matlab; see java.opts below.
2. Copy V:\CD\soft\ref\package\aida\common\script\aidasetup.m and aidainit.m to some place in your matlab path. Your working directory will be fine, or toolbox\local.

*If you're an AFS user, you may like to edit these files and replace references to the V drive with references to the original files on the Unix file system. That will ensure you always get the latest release of Aida

Programmers Guide to Matlab Support for Aida

This section is intended for programmers of the Aida system itself, and gives help on supporting Aida's use from Matlab.

aidainit.m

/afs/slac/g/cd/soft/dev/matlab/aidainit.m

Aidainit.m calls aidasetup.m to set the classpath (unless from inspection of the classes already loaded, it concludes this has already been done). Aidainit.m additionally creates an instance of the Err class singleton which it uses to send error messages to cmlog. Aidainit will set the user identifier for messages sent by Err to cmlog, to, on unix, the name of the Matlab user, plus "Matlab". On a PC, the user is simply "PCMatlab". If you would like to set the name of your user session to something more meaningful, you should write your own version of aidainit.m (it's very short, you only need the call to aidasetup, the imports, and the call to Err.getInstance), and where aidainit.m calls Err.getInstance("somename"), put in your own name.

Note that Aidainit checks to see if it's been run before, and doesn't re-run the slow parts, so it's safe to use in matlab functions and scripts where some speed in repeated calling is desirable.

aidasetup.m

/afs/slac/g/cd/soft/dev/matlab/aidasetup.m

Matlab uses Aida's Java API, and as such depends on a number of class and/or JAR files. This will be at least the following files, all of which must be available in Matlab's Java CLASSPATH (see matlab command javaclasspath). At the time of writing, a user puts these Jar files in their java classpath by calling aidasetup.m.

(*) Location of classes and JAR files used by Aida

The aida, except, and err classes exist in both their raw '.class' file form, and packaged into jar files. aidasetup.m detects whether it is being run on a PC, and if so uses the .jar file versions of these classes, which can be found on the V: drive (in the directories V:\cd\soft\ref\package\{aida,except,err}/lib/). Otherwise (for instance it is being run on unix) it sets the CLASSPATH to the package root of those packages on AFS (/afs/slac/g/cd/soft/ref/package/{aida,err,except}), so as to use the class files directly. This covers the majority of users (PC's with the V drive mapped, and AFS unix users). However, if you are using Aida neither from a PC with the V drive mapped, nor from a unix machine with AFS mounted, you will have to get all 6 original jar files listed above on your machine locally, and edit your aidasetup.m to point to them directly. The aida, err, and except jar files are available on AFS at: /afs/slac/g/cd/soft/ref/package/{aida,err,except}/lib/. The ORBACUS jar files are in /afs/slac/package/iona/orbacus/prod/JOB/lib/ (note "prod" here is a symlink, which may not show up in some FTP clients).

java.opts

The java.opts file is a feature of Matlab, which enables java properties to be communicated to Matlab's JVM at Matlab's startup. This is the way we communicate those JVM arguments which on unix are given by arguments to the java command itself (see eg aidatest). The contents of java.opts will be the same on Unix as on Windows, but some things should bourne in mind:

1. On both unix and PC, whitespace (blank chars) must be avoided. Each line must end immediately after the last non-blank char on a line, otherwise Matlab misses that option.
2. Relating to the interoperability of a java.opts file on AFS and Windows, be careful not to just copy the java.opts from from AFS to your PC, or to use the AFS version directly on your PC, because:
   1. The line-ending difference of Unix (on which the AFS version originated) and Windows makes a difference (CR on Unix, CR/LF on Windows). Windows Matlab can't read a Unix version of java.opts. So, on Windows, use a java.opts file on the Windows filesystem.
   2. The syntax of AFS pathnames is different. Eg, the -Xbootclasspath directive on Windows will be something like V:\CD\package\iona\orbacus\prod\JOB\lib\OB.jar.

Example java.opts:

This is the one for Unix in CVS at /afs/slac/g/cd/soft/ref/package/aida/common/script:

[tersk05]:aida/common/script> cat java.opts
-Xbootclasspath/p:/afs/slac/package/iona/orbacus/prod/JOB/lib/OB.jar
-DAIDA_DATABASE_USERID=AIDA_PROD
-DAIDA_NAMESERVER_IOR_URL=http://www.slac.stanford.edu/grp/cd/soft/slaconly/aida/NameServerPROD.ior
-DAIDA_CLIENT_TIMEOUT=30

Author: Greg White, 19-Nov-2004
Modified by: Greg White, 11-Apr-2005. Split up aidasetup stuff and created aidainit, makes setup easier.