GETTING ACCELERATOR DATA ON MS WINDOWS
Chris Timossi 

05/08/2008 Added sca4.dll to C/sca4. This dll was built for R3.14.9 (ca.dll,com.dll included).
02/07/2007 Added EPICS server tool. Built with EPICS R3.14.4.


Accelerator data can be read by installing an Active X Control as explained below.


1. INSTALLATION
2. GENERAL USAGE
3. USING LABVIEW
4. Borland Delphi and C++ Builder
5. MS Visual Basic
6. Error Codes
7. .NET version


1. INSTALLATION - NOTE: this installation sets EPICS_CA_ADDR_LIST for ALS subnets.
================

-Uninstall previous version using: control panel -> add/remove software 
Note: you may need to remove the following by hand from <windir>\system32:
sca3.dll, scacom.dll, ca.dll, com.dll

-Download the windows installer file: 'ScasSetup.msi' from
http://www-controls.als.lbl.gov/epics_collaboration/simple_channel_access/win32/

-run the installer
This installs several dlls in the system directory (system32) and registers the ActiveX controls. 
It also creates a directory \Program Files\LBNL\Sca for some utilities like scaget.exe

-environment
At the ALS, only certain subnets can access accelerator data from the control net. For example, beamline subnets in bld 2 can access data, subnets in other buildings (except bld 80) cannot access data. To access data from an allowed subnet, the broadcast address of the subnet to be accessed must be set as an environmental variable: 
set EPICS_CA_ADDR_LIST=131.243.71.255 (this is set by the installation procedure). For read only access, a wider number of subnets can
access data via a gateway. To use the gateway: set EPICS_CA_ADDR_LIST=131.243.90.255

-testing
Open a command window.
cd \Program Files\LBNL\Simple Channel Access
scaget cmm:beam_current
You should see the value of the beam current. 



2. GENERAL USAGE 
=======================================
The exact usage depends on the development platform used. MS Visual Basic, MS Visual C, NI Labview (see 3), Borland Delphi, and Borland C++ builder have been tried.

To use the client control to get data, you must know the PV  name of the item that you want to read or write. For example, "cmm:beam_current" is the
name for the storage ring beam current. "cmm:sr_energy" is the name for the storage ring energy.

Generally 3 steps are used to get (or send) data: add, get, and refresh (send).

For example, to get the beam current:

addDoubleItem("cmm:beam_current") one time at the beginning of the code.
getDouble("cmm:beam_current") to request the data
refreshValues() to update the values.

In C++, the code looks like:

//
// Add the names to get or set
//
mysca.addDoubleItem("first_pv_name")
mysca.addDoubleItem("second_pv_name")
mysca.addDoubleItem("third_pv_name")

// 
// now get the data
//
try {
    mysca.getDouble("first_pv_name", &return_value1)
    mysca.getDouble("second_pv_name", &return_value2)
    mysca.getDouble("third_pv_name", &return_value3)
    mysca.refreshValues(&status)
} catch (...) { //handle error }

//
// set a value
//
try {
   mysca.setDouble("first_pv_name", double_value);
   mysca.sendValues(&status);
} catch (...) { //handle error}

Similar steps are followed to make an application behave like an EPICS server. In this case the ScasCtl control is used. In this case, addItem will add a new PV with a name of your choosing (the name must be unique), then setItem sets it's value.

ERRORS

There are several possibilities for errors. The most common is to ask for a
PV name that doesnt exist. Another possibility is that communication failed
between your computer (the client) and the computer that handles that data
that you want (the server). In case of these errors, an exception will be
thrown or an error returned depending on your platform.

NOTES

The first time a 'get' is called will take longer than subsequent calls.
That's because the during the first call a search has to be done to find the
item.




3. USING LABVIEW
=================
Data comes from the accelerator via the ALS accelerator control network using the EPICS  Channel Access protocol. Direct access to the ALS control network is limited to computers in  buildings 80 and 6. For those computers, an ActiveX control 
(CSca) can be installed and used by Labview (and other ActiveX containers such as Visual Basic) to get and set values. In some cases, it may be convenient to create your own PV's for use by any EPICS clients. A separate control CScasCtl is used for this purpose (NOTE this PV name must be unique throughout the accelerator).



STEP-BY-STEP INSTRUCTIONS

	1. Add the Active X Control

	    Method 1 (Active X Container):

Right click on front panel to display controls toolbox
ActiveX->Container adds a container to the FP
On the new container: Right click->Insert ActiveX Object...
On "Select ActiveX Object Dialog Box": Select "Sca2 object (or CScaCtl for server)"
scacom.ISca appears in the container and on the wiring diagram as a 'reference'

	    Method 2 (Active X Reference number):
  

Right click on front panel to display controls toolbox
ActiveX-> Automation Refnum
Right click on Refnum -> Select ActiveX Class -> browse
'Select Object From Type Library' Dialog: Click the down arrow on the Type 
Library edit box and Scroll down to 'Sca Type Library (ScasCtl for server)'
 


	2.  ActiveX Invoke nodes (wiring diagram) for data access

On the wiring diagram: Functions->Communications->ActiveX->InvokeNode
Wire scacom.ISca reference node to the reference input Invoke node.
The Invoke node changes to 'ISca' and now gives a choice of methods.
Right click on 'Methods' and select AddDoubleItem
Wire the desired pv name to the 'pv name' input.
Create another invoke node.
Wire the reference of the 'addDoubleItem' invoke node to the inputs of the new invoke node.
Right click on Method->getDouble.
Wire the pv name output to the input of the 'getDouble' invoke node.
Create a constant double input for the 'getDouble' invoke node.
Create a FP double indicator and wire to the output of the 'getDouble' invoke node.
Create a property node for error checking.
Functions->Communications->ActiveX->PropertyNode
Wire the reference from the getDouble invoke node to the input of this property node.
Right click on the property node: properties->error (or error_code)


Errors:
Each operation must be checked for error condition. error and error_code properties must be checked for errors after each operation. error is true if there is an error, error_code can be used to check the actual error if desired (see 6).



TIPS

Often, the process of getting data involves reading multiple PVs in a loop. Sca is generally used in the following manner for this process:
-add all the pvs the will be needed using the add<type>Item methods once at the beginning of the code.
-get all the values using the get<type> methods
-invoke the refreshValue node

EXAMPLES
example_sca.vi is an example that uses the ActiveX Control to get the beam current.


 

4. Borland Delphi and C++ Builder
===================================
For Borland C++ builder and Delphi, the first step is to 'import ActiveX control'. (Delphi requires the additional step of 'make unit'). This step creates a unit that can access the activeX controls methods and properties (with some restrictions). Note that when the Active X control is updated, the component must be re-imported.

5. MS Visual Basic
===================================
For MS Visual Basic simply 'add component' to the component palette.



6. Error Codes
====================================
The application should always check for errors after and sca operation. If there is any error, the data returned cannot be trusted. 

The error property can be tested for errors: 0 means the operation was successful. 

In some cases it us useful to check the error_code property. Error codes are packed into a 32 bit word and are best interpreted in hexadecimal. The low
order 16 bits contain information about the connection and monitor status. The high order 16 bits contain the error status. The most common errors are:

0x0D0000 => cannot get: the request failed probably and invalid pv name or broken connection.
0x120000 => no callback: the data hasnt returned yet;
0x110000 => refresh incomplete: one or more of the requested values has not returned.
0x000EEE => NO ERROR


7. Access with .NET
=======================================

Access of accelerator data is also available by installing a .NET library:

install:
http://www-controls.als.lbl.gov/epics_collaboration/simple_channel_access/NET/ScaNetx86.msi

documentation is installed in:
\Program Files\LNBL\ScaNETx8y\readme.txt