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.

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

## 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.

 JAR file Use in AIDA aida.jar(*) Aida's API, the core of Aida, the abstract client side of all data providers and server sides of Unix based data providers except.jar(*) Exception (error object) definitions err.jar(*) Error Handling and Logging OB.jar Orbacus implementation of CORBA, on which Aida is founded. OButil.jar Useful CORBA utilities OREvent.jar The mechanism for passing exception objects around.

#### (*) 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.