SLAC ESD Software Engineering Group
Stanford Linear Accelerator Center
AIDA

SLC Magnet Data Provider Guide

SLAC Detailed
SLAC Computing
Software Home
Software Detailed
AIDA
SLC Peer PG

This page provides documentation for users and programmers of AIDA's SLC Magnet Data Provider. This data provider allows the retrieval of magnet primary/micro/unit names and BDES/VDES secondary values for a specified display group, primary, and secondary. It also allows the setting of BDES/VDES values for specified magnet primary/micro/unit names and optionally performs either a trim or perturb operation. This set operation returns the state names and new BACT/VACT values. Finally, this data provider allows for the setting of BCON values for specified magnet primary/micro/unit names.

See Also: Basic Users Guide to Aida, REF_AIDASHR; AIDA SLC Peer Programmers Guide


Users Guide

This section descibes what an AIDA user should know about using the SLC Magnet data provider. For general information on using AIDA see Basic Users Guide to Aida, and the Aida javadoc, in particular the classes DaObject and DaReference, in aida.lib.da which form Aida's programming interface. One can also use Aida through Matlab.

Table 1: Summary of AIDA Data Provider for SLC Magnet

SUMMARY
Supports get and set operations. The get operation obtains primary/micro/unit strings and BDES/VDES values for a specified display group, primary, and secondary name (with optional micro and unit range filters). One set operation sets BDES/VDES values for specified primary/micro/unit name strings to specified values and optionally performs a specified operation (trim or perturb). This set operation returns the resulting state names and BACT/VACT values. The other set operation sets BCON values for specified primary/micro/unit name strings to specified values.
Status and limitations

The data provider is complete and there are no known limitations

Plan No active plans for extensions.

EXAMPLES
Schematic Java examples, see DpSlcMagnetTests.java for more examples:
String query  = "DEV_DGRP//XCOR:BDES";
da.setParam("MICROS", "LI31-LI31");   /* Optional parameter specifying micro range in display group. */
da.setParam("UNITS", "1-100");        /* Optional parameter specifying unit range in display group. */
DaValue v = da.getDaValue(query);     /* Get primary/micro/unit strings and BDES/VDES settings. */

String query = "MAGNETSET//BDES";     /* Indication of set operation requested for specified BDES secondary */ 
String [] stringsParam = {"XCOR:LI31:41"}; /* Array of specified primary/micro/unit strings. */
float [] setValues = {4.0f};          /* Array of specified set values. */
DaValue inData = new DaValue();       /* Creation of DaValue to hold stringsParam and setValues arrays */
inData.type = DaValue.Type.STRUCT;
inData.addElement(new DaValue(stringsParam));
inData.addElement(new DaValue(setValues));
da.setParam("MAGFUNC", "TRIM");       /* Required MAGFUNC parameter set to TRIM, PTRB, or NOFUNC. */
DaValue outData = da.setDaValue(query, inData); /* Perform set operation for setting specified values and optionally performing a TRIM/PTRB operation. */

String query = "MAGNETSET//BCON";     /* Indication of set operation requested for specified BCON secondary */ 
String [] stringsParam = {"XCOR:LI31:41"}; /* Array of specified primary/micro/unit strings. */
float [] setValues = {5.0f};          /* Array of specified set values. */
DaValue inData = new DaValue();       /* Creation of DaValue to hold stringsParam and setValues arrays */
inData.type = DaValue.Type.STRUCT;
inData.addElement(new DaValue(stringsParam));
inData.addElement(new DaValue(setValues));
da.setDaValue(query, inData); /* Perform set operation for setting specified BCON values (no value is returned). */

Java $CD_SOFT/ref/package/aida/test/java/DpSlcMagnetTests.java
Matlab $CD_SOFT/ref/package/aida/test/matlab/magnetGetDemo.m performs a get operation.

INSTANCES and ATTRIBUTES
Instance Type Description
Get Syntax <dgrp-mnemonic>//<prim>:<secn>
Examples

DEV_DGRP//XCOR:BDES

Set Syntax MAGNETSET//<secn>
Examples MAGNETSET//BDES
MAGNETSET//BCON
Attributes
Attribute Description
<prim>:<secn> Gets an array of magnet primary/micro/unit strings and an array of BDES/VDES values.
Methods Name* Returns
getDaValue(q) Returns a DaValue containing a heterogenous vector of 2 homogenous congruent vectors:
  • name of each magnet for specified display group and primary (optionally filtered by specified micro and unit ranges)
  • secondary values (BDES or VDES)
  • Parameters Name

    Req/
    Opt

    Syntax Semantics
    MICROS

    opt

    Start_micro-end_micro This specifies a range of micro names of interest within the specified display group.
    UNITS opt Start_unit-end_unit This specified a range of unit numbers of interest within the specified display group.
    BDES or VDES Sets specified BDES or VDES secondary values for specified array of magnet names to an array of corresponding set values. Then optionally performs a specified trim or perturb operation. The parameter data argument (p) is a DaValue containing two elements: an array of magnet names and an array of corresponding set values.
    Methods Name* Returns
    setDaValue(q, p) Returns a DaValue containing a heterogenous vector of 2 homogenous congruent vectors containing the following information after the performance of the specified operation:
  • a string indicating the state of each specified magnet device. Set to blanks (checking that the first character is blank is all that is necessary) if the state is good. Set to the string "Outside Limits" if a set value is outside of its limits and the optional parameter LIMITCHECK is set to SOME.
  • BACT/VACT value for each device
  • Parameters Name

    Req/
    Opt

    Syntax Semantics
    MAGFUNC req TRIM, PTRB, or NOFUNC Specifies whether a trim or perturb operation will be performed. If NOFUNC, neither a trim nor a perturb operation will be performed.
    LIMITCHECK opt ALL or SOME Used to determine behavior when the set value for one or more devices is outside of its low/high limits. If this parameter is set to ALL, the entire request will fail resulting in an exception being thrown and no BDES/VDES values being set for any of the request devices. If this parameter is set to SOME, the set value action will succeed for those set values that are within limits and will not be performed for those set values outside their limits (the state string return values for these devices will be set to the string "Outside Limits"). The default setting of this parameter is ALL.
    BCON Sets specified BCON secondary values for specified array of magnet names to an array of corresponding set values. The parameter data argument (p) is a DaValue containing two elements: an array of magnet names and an array of corresponding set values.
    Methods Name* Returns
    setDaValue(q, p) No data is returned.
    Parameters None

    * See DaObject and DaReference (and DaReference's parent _DaReference) in aida.lib.da for full API and method signatures.


    Programmers Guide

    The SLC Magnet Data Provider is a provider in the AIDA SLC Peer (along with the SLC DB Data Provider, the SLC History Data Provider, the SLC Model Data provider, the SLC BPM Data Provider, the SLC Multiknob Data Provider, the SLC Master Oscillator Data Provider, and the SLC Klystron Data Provider). Development of all these data providers is described in a Programmers Guide here.


    [SLAC ESD Software Engineering Group][ SLAC Home Page]

    Author:  Bob Hall 16-Oct-2006
    Modified by: Bob Hall 08-Oct-2007, Added description for new MAGFUNC=NOFUNC and set BCON functionality.
    Modified by: Bob Hall 25-Feb-2009, Added description for the BDES/VDES setDaValue new optional parameter LIMITCHECK.