Function Summary

Key to the terms used in the Function Summary below

key	field / method	description
any_type		The argument to ML can be a variable of any type.
builder		A Java class that allows you to build of requests before execution
dynamic		Any dynamically instantiated matlab type
fieldName		Within an AidaPvaStruct this is a field's name
exception		exception caught by a matlab try catch block
fieldValue		Within an AidaPvaStruct this is a field's value
jstruct		A Java structure that can be used as an argument or value
nturi		A special type of `PVStructure` that corresponds to the `NTURI` Normative Type
message		Custom message for handleExceptions
name		The name of a parameter / argument to the request.
nturi		A special type of `PVStructure` that corresponds to the `NTURI` Normative Type.
Object		A Java Object
PvaTable		A Java PvaTable object
	size	Contains size of vectors in this table
	labels	A Java `Object`[] array of Java Strings
	get(name)	Method that will return a Java `Object`[] array of Java `Objects` for the named vector in this table. The objects are of the Java type of the column vector
pvName		The name of the Process Variable / EPICS channel that you'll be requesting data from
PVStructure		An EPICS data type conforming to the Normative Type specifications. (see Normative Types)
scalar		A scalar matlab type
type		An AIDA-PVA type from the list below:
	AIDA_BOOLEAN
	AIDA_BYTE
	AIDA_SHORT
	AIDA_INTEGER
	AIDA_LONG
	AIDA_STRING
	AIDA_BOOLEAN_ARRAY
	AIDA_BYTE_ARRAY
	AIDA_SHORT_ARRAY
	AIDA_INTEGER_ARRAY
	AIDA_LONG_ARRAY
	AIDA_STRING_ARRAY
	AIDA_TABLE
value		Any matlab scalar value or array you want to set the given Process Variable / channel, or request argument to.
void		No value is returned

Matlab 2012 vs 2020

Accessing aida-pva-client api in function scopes

In functions, you need to use the aidapva script to bring the aida-pva-client api into the function scope. From the commandline or in scripts this is not necessary.

function example()
  aidapva;
  
  builder = pvaRequest('XCOR:LI31:41:BCON');
  builder.returning(AIDA_FLOAT);
  response = builder.get();
end

Function chaining

In matlab 2012 you can't chain functions together so instead of writing this:

mstruct = ML(pvaRequest('NDRFACET:BUFFACQ').with('BPMD', 57).with('BPMS', { 'BPMS:LI11:501' }).timeout(10).get())
mstruct =
  struct with fields:
            size: 1
          labels: {'BPM Name'  'pulse id'  'x offset (mm)'  'y offset (mm)'  'num particles (coulomb)'  'stat'  'good measurement'}
           units: []
    descriptions: []
      fieldnames: {'name'  'pulseId'  'x'  'y'  'tmits'  'stat'  'goodmeas'}
          values: [1x1 struct]

you have to write it on separate lines thus:

builder = pvaRequest('NDRFACET:BUFFACQ');
builder.with('BPMD', 57);
builder.with('BPMS', { 'BPMS:LI11:501' });
builder.timeout(10);
mstruct = ML(builder.get())
mstruct =
            size: 1
          labels: {'BPM Name'  'pulse id'  'x offset (mm)'  'y offset (mm)'  'num particles (coulomb)'  'stat'  'good measurement'}
           units: []
    descriptions: []
      fieldnames: {'name'  'pulseId'  'x'  'y'  'tmits'  'STAT'  'goodmeas'}
          values: [1x1 struct]

Note: All examples below are written for Matlab 2012 so they are much more verbose than they need to be. You can chain the function calls together when you use them in matlab 2020.

Exception handling

Matlab 2012 creates an exception message that includes much of the stack trace instead of just the short reason message that the original exception contains. Matlab 2020 contains the correct message. So instead of seeing this for errors:

try
    response = pvaRequest('NDRFACET:BUFFACQ').with('BPMD', 57).with('NRPOS', 10).with('BPMSWRONG', {'BPMS:LI02:501' 'BPMS:DR12:334' } ).get();
catch e
    handleExceptions(e);
end
NDRFACET:BUFFACQ(NRPOS=10.0, BPMD=57.0, BPMSWRONG=[BPMS:LI02:501, BPMS:DR12:334]) :NDRFACET:BUFFACQ:  BPMSWRONG is not a valid argument for get requests to this channel

You will see this in Matlab 2012

try
    builder = pvaRequest('NDRFACET:BUFFACQ');
    builder.with('BPMD', 57);
    builder.with('NRPOS', 10);
    builder.with('BPMSWRONG', {'BPMS:LI02:501' 'BPMS:DR12:334' } );
    response = builder.get();
catch e
    handleExceptions(e);
end
Java exception occurred:
org.epics.pvaccess.server.rpc.RPCRequestException: NDRFACET:BUFFACQ(BPMSWRONG=[BPMS:LI02:501, BPMS:DR12:334], BPMD=57.0, NRPOS=10.0) :NDRFACET:BUFFACQ:  BPMSWRONG is not a valid argument for get requests to this channel
    at edu.stanford.slac.aida.client.AidaPvaRequest.execute(AidaPvaRequest.java:182)
    at edu.stanford.slac.aida.client.AidaPvaRequest.getter(AidaPvaRequest.java:152)
    at edu.stanford.slac.aida.client.AidaPvaRequest$2.execute(AidaPvaRequest.java:112)
    at edu.stanford.slac.aida.client.AidaPvaClientUtils.executeRequest(AidaPvaClientUtils.java:219)
    at edu.stanford.slac.aida.client.AidaPvaRequest.get(AidaPvaRequest.java:109)

Strings

In matlab 2020 you can represent a string as as follows:

string = "matlab 2020 string";

In matlab 2012 you can only use single quotes

string = 'matlab 2020 string';

Initialisation

return	function	parameters	description
void	aidapvainit	()	to initialise access to the AIDA-PVA framework.
void	aidapvafninit	()	to initialise access to the AIDA-PVA framework for functions. Do not call this function directly, it is called automatically from aidapvainit.m
void	aidapva	()	to bring aida-pva-client functions into a function's scope. Only used at the top of function definitions before calling any aida-pva-client functions.

Note: aidapvainit.m will be called automatically when matlab starts up so there is no need to call it manually.

Simple Get: get the value of a process variable

return	function	parameters	description
scalar, Object[], PvaTable	pvaGet	(pvName[, type])	takes a `pvName` and an optional `type` and makes a data request
dynamic	pvaGetM	(pvName[, type])	takes a `pvName` and an optional `type` and makes a data request returning a matlab type directly

e.g. PvaGetM

response = pvaGet('XCOR:LI31:41:BCON', AIDA_FLOAT)
response =
     5
 
response = pvaGetM('XCOR:LI31:41:BCON', AIDA_FLOAT_ARRAY)
response =
     5
 
response = pvaGetM('DEV_DGRP:XCOR:BDES')
response =
            size: 4
          labels: {'name of magnet'  'secondary values'}
           units: []
    descriptions: []
          values: [1x1 struct]
 
response.size
ans =
     4
 
response.labels
ans =
    'name of magnet'    'secondary values'
 
response.values.name
ans =
    'XCOR:LI31:41'    'XCOR:LI31:201'    'XCOR:LI31:301'    'XCOR:LI31:401'

e.g. PvaGet

response = pvaGet('XCOR:LI31:41:BCON', AIDA_FLOAT)
response =
     5
 
response = pvaGet('XCOR:LI31:41:BCON', AIDA_FLOAT_ARRAY)
response =
java.lang.Object[]:
    [5]
 
response = pvaGet('DEV_DGRP:XCOR:BDES')
response =
PvaTable(size=4, labels=[name of magnet, secondary values], fieldNames=[name, secondary], descriptions=[], units=[], values={name=[Ljava.lang.Object;@19050a0, secondary=[Ljava.lang.Object;@19d3b3a})
 
response.size
ans =
4
 
response.labels
ans =
java.lang.String[]:
    'name of magnet'
    'secondary values'
 
response.get('name')
ans =
java.lang.Object[]:
    'XCOR:LI31:41'
    'XCOR:LI31:201'
    'XCOR:LI31:301'
    'XCOR:LI31:401'

Simple Set: set the value of a process variable

return	function	parameters	description
void, PvaTable	pvaSet	(pvName, value)	set() the `pvName` to the given value
dynamic	pvaSetM	(pvName, value)	set() the `pvName` to the given value returning a matlab type directly

e.g. pvaSet

pvaSet('XCOR:LI31:41:BCON', 5.0);

e.g. pvaSetM

response = pvaSetM('KLYS:LI31:31:KPHR', 60.0)
response =
            size: 1
          labels: {'phas'}
           units: []
    descriptions: []
          values: [1x1 struct]
 
response.size
ans =
     1
 
response.labels
ans =
    'phas'
 
response.values.phas
ans =
    5.0

Complex Request Builder: to build complex get, and set, requests

return	function	parameters	description
builder	pvaRequest	(pvName)	takes a `pvName` and creates a request builder
builder	builder. with	(name, value/jstruct)	specifies a request parameter and its value
builder	builder. returning	(type)	specified the `type` to return from the request
scalar, Object[], PvaTable	builder. get	()	executes the get request
void, PvaTable	builder. set	(value/jstruct)	executes the set request with the given `value` or `jstruct`
nturi	builder. uri	()	to create an `NTURI` PVStructure (see Normative Types) for use with EPICS/AIDA-PVA data providers

e.g. complex get request

builder = pvaRequest('NDRFACET:BUFFACQ');
builder.with('BPMD', 57);
builder.with('BPMS', { 'BPMS:LI11:501' });
mstruct = ML(builder.get())
mstruct =
            size: 1
          labels: {'BPM Name'  'pulse id'  'x offset (mm)'  'y offset (mm)'  'num particles (coulomb)'  'stat'  'good measurement'}
           units: []
    descriptions: []
      fieldnames: {'name'  'pulseId'  'x'  'y'  'tmits'  'stat'  'goodmeas'}
          values: [1x1 struct]
 
mstruct.values.pulseId
ans =
       75785
 
mstruct.values.stat
ans =
     1
 
mstruct.values.tmits
ans =
   1.0000e-10
 
mstruct.values.name
ans =
    'BPMS:LI11:501'
 
mstruct.values.x
ans =
    0.4598
 
mstruct.values.y
ans =
    0.1861

e.g with returning

builder = pvaRequest('PHAS:LI09:12:VACT');
builder.returning(AIDA_SHORT);
response = builder.get()
resonse =
     0

e.g. complex set request

builder = pvaRequest('MAGNETSET:BCON');
jstruct = AidaPvaStruct();
jstruct.put('names', { 'XCOR:LI31:41'});
jstruct.put('values', { 5.0 } );
builder.set(jstruct);

e.g. another complex set request

builder = pvaRequest('MAGNETSET:BDES');
builder.with('MAGFUNC', 'NOFUNC');
jstruct = AidaPvaStruct();
jstruct.put('names', { 'XCOR:LI31:41'});
jstruct.put('values', { 4.0 } );
mstruct= ML(builder.set(jstruct))
mstruct =
            size: 1
          labels: {'status'  'bact/vact'}
           units: []
    descriptions: []
      fieldnames: {'status'  'bact_vact'}
          values: [1x1 struct]
 
mstruct.values.status(1)
ans =
    'OUTOFTOL '
 
mstruct.values.bact_vact(1)
ans =
    0.2983          

e.g. use uri to obtain an NTURI for use with PvaClient

nturi = pvaRequest('PHAS:LI09:12:VACT').returning(AIDA_SHORT).uri();

response = pvarpc(nturi) ;

e.g. use uri to obtain an NTURI for use with EasyPVA

builder = pvaRequest('PHAS:LI09:12:VACT');
builder.returning(AIDA_SHORT);
nturi = builder.uri();
response = ezrpc(nturi) ;

Structured Data: to create data structures to be used as request arguments

return	function	parameters	description
jstruct	AidaPvaStruct	()	to create a Java structure that can be passed to AIDA-PVA request builders as an argument.
	jstruct. put	(fieldName, fieldValue)	specifies a value for given field in the AidaPvaStruct

e.g. creating a AidaPvaStruct Java structure for an argument or value

jstruct = AidaPvaStruct();
jstruct.put('names', { 'XCOR:LI31:41'});
jstruct.put('values', { 4.0 } );

Data Conversion: to convert returned data into matlab types

return	function	parameters	description
dynamic	ML	(any_type)	convert any parameters to dynamic matlab type

e.g. ML data conversion of results

mstruct = ML(builder.get())
mstruct =
            size: 4
          labels: {'name of magnet'  'secondary values'}
           units: []
    descriptions: []
          values: [1x1 struct]
 
mstruct.size
ans =
     4
 
mstruct.labels
ans =
    'name of magnet'    'secondary values'
 
mstruct.values.name
ans =
    'XCOR:LI31:41'    'XCOR:LI31:201'    'XCOR:LI31:301'    'XCOR:LI31:401'
 
mstruct.values.secondary
ans =
    5.0000         0         0    0.0300

PvaClient Executor: to execute requests using PvaClient

return	function	parameters	description
PVStructure	pvarpc	(nturi)	takes an `NTURI` and executes it using PvaClient

e.g. pvarpc PvaClient executor example

nturi = pvaRequest('PHAS:LI09:12:VACT').returning(AIDA_SHORT).uri();
response = pvarpc(nturi) ;
bval= ML(response)
bval =
     0

EasyPVA Executor: to execute requests using EasyPVA

return	function	parameters	description
PVStructure	ezrpc	(nturi)	takes an `NTURI` and executes it using EasyPVA

e.g. ezrpc EasyPVA executor example

builder = pvaRequest('PHAS:LI09:12:VACT');
builder.returning(AIDA_SHORT);
nturi = builder.uri();
response = ezrpc(nturi) ;
bval= ML(response)
bval =
     0

Error handling

return	function	parameters	description
void	handleExceptions	(exception, [message])	takes a matlab exception object, and an optional error message text and handles the error in a standard way

EasyPVA and aida-pva-client propagate errors back from the Channel Provider to the matlab client however PvaClient does not.
You can write code to intercept error that occur and display a short message. We've provided a small function that does this for you.

pvName=strcat(dbname,':EDES:VAL');
try
    pvaSet(pvName, MAGNET(n).energy0)
catch e
    handleExceptions(e);
end

PvaTables as Matlab Structures

All data returned from AIDA-PVA comes back in the form of a PVStructure. This PVStructure conforms to the Normative Type
specifications. Tables come back as a special type of Normative type, the NTTable. (see Normative Types).

When we convert this table data to a matlab structure the structure contains the following fields:

size: integer size of the homogenous vectors
labels: array of labels for the vectors
units: if available an array containing the units for the vectors
description: if available an array containing the description for the vectors
values.<field>: array containing the value of the specified field. e.g. table.values.names contains an array of names

Using EasyPVA and PvaClient

EasyPVA and PvaClient don't convert a returned NTTable to a matlab structure. But you can use the ML function to convert it for you.

e.g. Convert EasyPVA and PvaClient NTTables to matlab structure

builder = pvaRequest('DEV_DGRP:XCOR:BDES');
nturi = builder.uri();
nttable = ezrpc(nturi);
ML(nttable)
ans =
            size: 4
          labels: {'name of magnet'  'secondary values'}
           units: []
    descriptions: []
          values: [1x1 struct]

Using pvaRequest.get() and pvaRequest.set()

These methods return tables in Java PvaTable format.

e.g. You can convert the response like this.

builder = pvaRequest('DEV_DGRP:XCOR:BDES');
ML(builder.get())
ans =
            size: 4
          labels: {'name of magnet'  'secondary values'}
           units: []
    descriptions: []
          values: [1x1 struct]

e.g. Or you can use the PvaTable directly like this.

builder = pvaRequest('DEV_DGRP:XCOR:BDES');
pvatable = builder.get();
pvatable.size
ans =
4
 
pvatable.labels
ans =
java.lang.String[]:
    'name of magnet'
    'secondary values'
 
names = pvatable.get('name')
names =
java.lang.Object[]:
    'XCOR:LI31:41'
    'XCOR:LI31:201'
    'XCOR:LI31:301'
    'XCOR:LI31:401'
 
names(1)
ans =
XCOR:LI31:41

Using PvaGetM(), and PvaSetM()

When these functions return tables they are automatically formatted as matlab structures.

e.g.: Automatically generated matlab structures

mstruct = pvaGetM('DEV_DGRP:XCOR:BDES')
mstruct =
            size: 4
          labels: {'name of magnet'  'secondary values'}
           units: []
    descriptions: []
          values: [1x1 struct]
 
mstruct.size
ans =
     4
 
mstruct.labels
ans =
    'name of magnet'    'secondary values'
 
mstruct.values.name
ans =
    'XCOR:LI31:41'    'XCOR:LI31:201'    'XCOR:LI31:301'    'XCOR:LI31:401'
 
mstruct.values.secondary
ans =
    5.0000         0         0    0.0300

Legacy AIDA Type migration

In legacy AIDA types were coded using constant numbers from this table. Replace codes or types with the corresponding AIDA-PVA type.

Code	Legacy AIDA Type	AIDA-PVA Type
0	`STRUCT`	AidaPvaStruct
1	`BOOLEAN`	AIDA_BOOLEAN
2	`BYTE`	AIDA_BYTE
3	`CHAR`	unsupported use AIDA_BYTE
4	`DOUBLE`	AIDA_DOUBLE
5	`FLOAT`	AIDA_FLOAT
6	`LONG`	AIDA_LONG
7	`LONGDOUBLE`	unsupported use AIDA_DOUBLE
8	`LONGLONG`	unsupported use AIDA_LONG
9	`SHORT`	AIDA_SHORT
10	`STRING`	AIDA_STRING
11	`ULONG`	unsupported use AIDA_LONG
12	`ULONGLONG`	unsupported use AIDA_LONG
13	`USHORT`	unsupported use AIDA_SHORT
14	`WCHAR`	unsupported use AIDA_BYTE
15	`WSTRING`	unsupported use AIDA_STRING
51	`BOOLEANA`	AIDA_BOOLEAN_ARRAY
52	`BYTEA`	AIDA_BYTE_ARRAY
53	`CHARA`	unsupported use AIDA_BYTE_ARRAY
54	`DOUBLEA`	AIDA_DOUBLE_ARRAY
55	`FLOATA`	AIDA_FLOAT_ARRAY
56	`LONGA`	AIDA_LONG_ARRAY
57	`LONGDOUBLEA`	unsupported use AIDA_DOUBLE_ARRAY
58	`LONGLONGA`	unsupported use AIDA_LONG_ARRAY
59	`SHORTA`	AIDA_SHORT_ARRAY
60	`STRINGA`	AIDA_STRING_ARRAY
61	`ULONGA`	unsupported use AIDA_LONG_ARRAY
62	`ULONGLONGA`	unsupported use AIDA_LONG_ARRAY
63	`USHORTA`	unsupported use AIDA_SHORT_ARRAY
64	`WCHARA`	unsupported use AIDA_BYTE_ARRAY
65	`WSTRINGA`	unsupported use AIDA_STRING_ARRAY
99	`ANYA`	unsupported

Migration patterns

General substitutions to apply in legacy AIDA code.

pattern Migration Action/Replacement

import edu.stanford.slac.aida.lib.da.DaObject;

import edu.stanford.slac.aida.lib.da.*;

import edu.stanford.slac.aida.lib.util.common.*;

aidapva;

da = DaObject();

Remove

da.setParam('BEAM', 1);

builder = pvaRequest('KLYS:LI31:31:TACT');

builder = builder.with('BEAM', '1');

You need to know the pvName name first
Then create a builder and set parameters on it
Repeat this for as many parameters as you have

result=da.get(pvName,4);

result = ML(pvaRequest(pvName).returning(AIDA_DOUBLE).get());

or

result = pvaGetM(pvName, AIDA_DOUBLE);

Note that you need to look up the type code 4 in the conversion table above.

result.getAsDouble

various getAs...() methods on the DaObject for scalar

result

The result will already be in the correct type for all scalar results. No conversion is required

result.getAsDoubles

various getAs...s() methods on the DaObject for scalar arrays

result

The result will already be in the correct type for all scalar array results. No conversion is required

values = result.get(4).getAsDoubles;

da.Any for tables.
For example a table with the 4th vector named "x", containing an array of doubles.

values = result.values.x;

The result will already be in the correct table type for all table results. No conversion is required

value=DaValue(java.lang.Short(10));

result=da.setDaValue(channel, value);

result=pvaRequest(channel).set(10);

or

result=pvaSet(channel, 10);

or (if the result is a table)

result=pvaSetM(channel, 10);

IN:ST:ANCE//ATTRIBUTE

IN:ST:ANCE:ATTRIBUTE

Function Source code in matlab

The following source code is delivered in matlab under the ./src directory

src/aidapva.m
src/aidapvainit.m
src/aidapvafninit.m
src/ezrpc.m - A script that can be called to make requests based on ezPVA has been created. Extracted from erpc.m.
src/handleExceptions.m
src/ML.m
src/pvaGet.m
src/pvaGetM.m
src/pvarpc.m - A script that can be called to make requests based on PvaClient has been created. Extracted from erpc.m.
src/toArray.m - To convert to an array. Do not call this directly use ML.m if necessary.