CA Lab (32 bit / 64 bit)

What is CA Lab?

CA Lab is a user-friendly, lightweight and high performance interface between LabVIEW™ and EPICS.
This project uses proven EPICS BASE libraries (V3.14.12), a CA Lab-library and 2 CA Lab-VIs to access EPICS variables.
CA Lab works with Windows^® and Linux.
This interface needs only LabVIEW™ and any EPICS IOC shell over network(~~OPC~~, ~~Shared Memory Variables~~, ~~Network variables~~, ~~NI IO Service~~).
It's not necessary to create a LabVIEW™ project to use this interface.
No problem to create an executable of your VI.
No additional licenses are required.
EPICS time stamp, status, severity and optional PV fields are bound to resulting value.
User events with EPICS variables are possible.
CA Lab is open source and works with all LabVIEW™ versions from 7.0 to 2011 (32bit/64bit). It has been tested under Windows XP^®, Windows 7^® and Ubuntu^®.

How does CA Lab work?

Any VI can use caLabGet.vi to read or caLabPut.vi to write EPICS variables. Use caLabEvent.vi to create user events for any EPICS variables. This CA Lab VIs calls interface library caLab.dll, which uses EPICS base libraries ca.dll and Com.dll to provide Channel Access functions. CA Lab-library also builds an internal PV cache to improve read and write access and reduce network traffic.

caLabGet.vi (Polymorphic VI)

This is a VI for getting values of EPICS variables.
INPUT:

PV name (array)
- name of EPICS variable OR string array of EPICS variable names
field names
- optional
- string array of static EPICS fields ("EGU", "DESCRIPTION" etc.)
timeout
- optional
- timeout for Channel Access requests
- default value: 3 seconds
error in

OUTPUT:

PV name (array)
- name of EPICS variable OR string array of EPICS variable names
1st value (string)
- value of variable as String
- shows first item of value array
1st value (number)
- value of variable as Double
- shows first item of value array
value array (number)
- all values of variable in Double array (1D/2D)
error out
result (array)
cluster (array) of full answer
- value array (number)
- PV name
- elements
  - size of value array
- value array (string)
  - all values of variable in string array
- value array (number)
- elements
  - size of value array
- status (string)
  - status of EPICS PV as String
- status (number)
  - status of EPICS PV as Long
- severity (string)
  - severity of EPICS PV as String
- severity (number)
  - severity of EPICS PV as Long
- time stamp (string)
  - stamp of EPICS PV time as String
- time stamp (number)
  - stamp of EPICS PV as Long
- field names
- field values
  - string array of requsted EPICS field values
- error IO
status
- FALSE: request(s) successful
- TRUE: warnings or errors

caLabPut.vi (Polymorphic VI)

This is a polymorphic VI for setting values of EPICS variables.
INPUT:

PV name(s)
- name of EPICS variable OR string array of EPICS variable names
values
- Boolean (array 1D/2D), String (array 1D/2D), Single (array 1D/2D), Double (array 1D/2D), Byte signed integer(array 1D/2D), Word signed integer(array 1D/2D), Quad signed integer(array 1D/2D)
timeout
- optional
- timeout for Channel Access requests
- default value: 3 seconds
error in
buffer size (since version 1.3 without function)
synchronious
- optional
- true = writes value(s) after waiting for the end of record processing
- false = writes value(s) without waiting for the end of record processing (DEFAULT)
- Note: Old projects that use the deprecated "fire and forget" feature in caLabPut, are no longer compatible!
valueSetsInColumns
- optional
- true = use columns for value sets instead of rows

OUTPUT:

PV name(s)
- name of EPICS variable OR string array of EPICS variable names
status
- FALSE: request(s) successful
- TRUE: warnings or errors
errors
- array of errors for every PV
error out

caLabEvent.vi

This is a VI for creating user events.
INPUT:

PV name
- name of EPICS variable
field names
- optional
- string array of EPICS fields ("EGU", "DESCRIPTION" etc.)
timeout
- optional
- timeout for Channel Access requests
- default value: 3 seconds
error in

OUTPUT:

event
- event structure
refnum
- event registration number
error out

Performance

caLab.dll (interface between LabVIEW™ and EPICS)

Functions:

Handles Channel Access activities
Administrates list of used EPICS variables
Monitores used EPICS variables
Buffers Channel Access requests
Works with
- DBR_TIME_STRING
- DBR_TIME_SHORT
- DBR_TIME_FLOAT
- DBR_TIME_ENUM
- DBR_TIME_CHAR
- DBR_TIME_LONG
- DBR_TIME_DOUBLE
- more info

CA tools

Additional command line tools for alternative EPICS access:

caGet (Read and print value for PVs.)
caPut (Write value to a PV.)
caMonitor (Set up monitor and continuously print incoming values for PVs.)
caInfo (Print channel access info data for a PV.)
caRepeater (Kind of proxy for Channel Access)
DemoIOC (Simple test ioc shell)

Examples

Simple VIs to read and write EPICS values:

caget example

camonitor example

caput example

event example

move mouse over image to see more

FAQ

Q: How can I do a quick check that CA Lab-installation works properly?
A: Use the full installion and run "startDemo.bat".

Q: I get a lot of warnings on first start of your VI. What's the problem?
A: The CA Lab-VIs need the absolute path to caLab.dll. This absolute path varies from computer to computer. LabVIEW™ looks for the right path at first run and reports that library paths have been changed. You should save these changes.

Q: CA Lab-VIs aren't executable, what can I do?
A: Check following:

Search your system for ca.dll, com.dll and carepeater.exe. If you can find several versions of them, then rename all outside of your installation path.
Check whether msvcp100.dll and msvcr100.dll are in "windows/system32" folder.
Open a command line and type "carepeater". You should get no error message. Terminate it with CTRL-C. If you get any error message you should reinstall CA Lab.
Open caLabGet.vi/caLabPut.vi and search for text "calab.dll". Double click on founds and check if text field "Library name or path" has same content as "path.txt" in your installation path.

Q: What is the maximum number of PVs monitored, tested up to now?
A: We have simultaneously monitored up to 1.000 PVs. But we're sure the limit is higher. A large number of PVs takes significant time to initialize when a PV is passed to the other. It's better to pass the PVs as an array. Reading, writing and monitoring after initialisation is no problem.

Q: Can CA Lab generate its own EPICS channels, or only connect to already defined channels?
A: CA Lab is a pure client application. If you want to generate your own channels, you can use "softIoc.exe". You can find an example in the demo application of caLab. Look at /db/demo.db for variable definitions.

Q: Will caLab work with any version of LabVIEW 64bit?
A: Yes, CA Lab does since V1.3.0.3. Please be sure to download the 64 bit version.

Q: I'm wondering what the timeout parameter does.
A: The timeout is the timeout for initializing and for retrieving the value for the FIRST call. After first call of any PV a background task monitors PVs and every call will be served by cached values from this task.

Q: I use caLabPut. When should I set the parameter "synchronious" to TRUE?
A: If it is necessary to wait til all record processing of written PV has been finished before next value can be set then you should set the connector of caLabPut "synchronious"=TRUE.

Any other questions are welcome! Please send me a mail.

Downloads of CA Lab

Setup for Windows^® and LabVIEW™ 2010 64 bit and higher (source code included) V1.3.1.3
05 MAR 2012

Setup for Windows^® and LabVIEW™ 8.5 32 bit and higher (source code included) V1.3.1.3
05 MAR 2012

Distribution of "caLabSetup_1313" contains:

caLabGet.vi (user VI to read values)
caLabPut.vi (user VI to write values)
caLabEvent.vi (user VI to monitor values via user events)
DemoIOC.cmd - optional (configuration of IOC shell)
path.txt (absolute path to caLab.dll)
ReadMeFirst.txt
startDemo.bat - optional (demo of CA Lab with local IOC shell)
unins000.dat, unins000.exe (uninstaller)
lib (libraries of CA Lab)
- caLab.dll (CA Lab library)
- ca.dll, Com.dll (libraries of EPICS base)
- caRepeater.exe (channel access repeater)
- asIoc.dll, dbIoc.dll, dbStaticIoc.dll, dbtoolsIoc.dll, miscIoc.dll, recIoc.dll, registryIoc.dll, rsrvIoc.dll, softDevIoc.dll, softIoc.exe - optional (IOC shell libraries)
- caget.exe, camonitor.exe, caput.exe, cainfo.exe - optional (commandline tools)
- db - optional (IOC shell)
  - demo.db (variables)
- dbd
  - softIoc.dbd (definitions)
src - optional (source code)
- caLab.cpp (c++ file)
- caLab.rc (resource file)
- caLab.vcxproj (project file)
sub (SubVIs of CA Lab)
- caLabGet01.vi, caLabGet02.vi (caLabGet.vi)
- caLabPut01.vi ... caLabPut47.vi (caLabPut.vi)
tests
- caLabEventTest.vi (example of two EPICS events)
- caLabGetTest.vi (example of reading of 3 EPICS variables with 2 fields)
- caLabMonitorTest.vi (example of monitoring a set of EPICS variables in a table)
- caLabPutTest1.vi (example of writing value arrays as Double to 5 different EPICS variable types)
- caLabPutTest2.vi (example of writing value arrays as String to 5 different EPICS variable types)
- caLabPutTest3.vi (example of writing values with time measurement)
- pvList.txt (example PV list for caLabMonitorTest.vi)
%windir%\system32
- msvcp100.dll, msvcr100.dll (Microsoft^® C Runtime Library)

CA Lab archive - sources and VIs only (Linux and Windows^®)V1.3.1.3
05 MAR 2012

Setup for Windows^® and LabVIEW™ 7.0 and higher (source code included) V1.2.1.5
02 AUG 2011

Distribution of "caLabSetup_1200_LV70" contains:

caLabGet.vi (user VI to read values)
caLabPut.vi (user VI to write values)
caLabEvent.vi (user VI to monitor values)
connectCaLab.vi (user VI to initialize Channel Access)
disconnectCaLab.vi (user VI to terminate Channel Access)
path.txt (absolute path to caLab.dll)
unins000.exe, unins000.dat (uninstaller)
readme.txt (please, don't forget to read it)
sub (sub VIs of CA Lab)
- caLabPut_Bool.vi
- caLabPut_Dbl.vi
- caLabPut_Dbl_Arr.vi
- caLabPut_Str_Arr.vi
tests (tests and examples)
- caEventExample.vi
- ~~caGetExample.vi~~
- caMonitorExample.vi
- caPutBoolExample.vi
- caPutDblArrayExample.vi
- caPutDblExample.vi
- caPutStrArrayExample.vi
lib
- ca.dll, Com.dll (libraries of EPICS base)
- caLab.dll (CA Lab library)
- caget.exe, caput.exe, camonitor.exe, cainfo.exe, caRepeater.exe (commandline tools)
%windir%\system32
- msvcp100.dll, msvcr100.dll (Microsoft^® C Runtime Library)
src (sources)
Optional "DemoIOC" brings some more libraries and config files to previous folders.

CA Lab archive - sources and VIs only (Linux and Windows^®)V1.2.1.5
02 AUG 2011

Change Log

V1.3.1.3 (Released: March 2012)
  # solved 1D-pv-array to 1D-value-array problem
  # caLabGet.vi: optimized memory allocation
  # caLabPut.vi: documentation updated
  # examples revised and documented better
  # recompiled EPICS base 3.14.12.2 with
    rules-db.patch, fix-907761.patch and str-to-enum.patch

----------------------------------------------------------------------
V1.3.1.2 (Released: February 2012)
  + caLabPut: New option valueSetsInColumns to hold value sets in columns
     instead of rows (value sets in rows for 2d arrays is default now)
  # caLabPut optimized for speed (large arrays)
  # BUG: caLabGet and caLabGet had transposed arrays in some cases
  # Fixes problems with PV names that contain white spaces
  # Better handling of oversized value arrays in caLabPut
    (Ca Lab uses max. valid array size [NELM field] instead of size=1 now)

----------------------------------------------------------------------
V1.3.1.0 (Released: January 2012)
  + caLabPut: New option "synchron" 
              (old connector name was "fire and forget")
               true  = writes value(s) after waiting for the end
                       of record processing
               false = writes value(s) without waiting for the end
                       of record processing (DEFAULT)
Note: Old projects that use the "fire and forget" feature in caLabPut,
       are no longer compatible!
 
----------------------------------------------------------------------
V1.3.0.4 (Released: December 2011)
  # Fixes problems with PV names that contain a point
  # Better enum string handling for string value output
  # Uninstaller detects and terminates running caRepeater.exe now

---------------------------------------------------------------------
V1.3.0.3 (Released: December 2011)
  + Completely rewritten
  + EPICS base 3.14.12.2
  + 64-bit support
  + !!! caLabGet and caLabPut accepts PV arrays now !!!
  + Much faster if you use name arrays
  + Optional fields are no longer static values
    (monitoring of optional fields)

  # No white spaces in results anymore
  # Fixes problem with long PV names
  # Memory leak for caLabPut Fixes
  # Works with LabVIEW 2011
  # Improved polymorphic vi handling (boolean input)
  # Fixes caLabPut2x.vi (1D-name-array with 1D-value-array)
  # Keeps last valid value in error case
  
  - Fire and forget not longer available
   (dummy connectors for compatibility only)

---------------------------------------------------------------------
V1.2.1.3 (Released: May 2011)
  # Fixes multi instances bug
  # Fixes for EPICS Base
  # Fixes lost values of reconnected channels
  # Fixes problems with multiple ioc-server-sources
  
---------------------------------------------------------------------
V1.2.0.0 (Released: February 2011)
  + Added "user event" (software trigger) to CA Lab

  # Minor changes in startDemo.bat (11 FEB 2011)
  # Fixes LabVIEW crash in case of immediately closing VI after
    stopping it
  # Faster termination of CA Lab VIs      

---------------------------------------------------------------------
V1.1.1.1 (Released: January 2011)
  # Holds last valid value of PV after channel disconnection with
    current state info
  # Fixes for EPICS Base "escape-paths.patch", "errlog-atExit.patch"
    and "rsrv.patch"

---------------------------------------------------------------------
V1.1.1.0 (Released: January 2011)
  + WORKS WITH LINUX NOW!!!
  + Works with LabVIEW 7.0 up to LabVIEW 2010
  + Improved performance (much more faster Channel Access IO,
    faster reconnect)
  + Internal PV cache to improve read and write access and reduce
    network traffic
  + User defined fields of EPICS PV such as "EGU", "DESCRIPTION" etc.
  + New additional fire-and-forget-bit for speeding up write
    If you use the fire and forget mode you'll get no success info
  + User defined timeout for Channel Access communication (optional)
  + User defined buffer for reconnect and put task (optional)
  + More PV information bundled in output cluster
  + Status bit of PV for easy health check      

  - In LabVIEW 8.5 and higher "initPV.vi" and "disconnectPV.vi"
    are no longer needed.
  - Reduced user-VIs to "caLabGet.vi" and "caLabPut.vi"
  
  # Fixes memory leak
  # Holds last valid value of PV after channel disconnection with
    current state info
  # Better error handling (no frozen LabVIEW anymore)
  # Built with EPICS Base 3.14.12

---------------------------------------------------------------------
V1.0.0.3 (Released: June 2010)
  - First Release

Authors

Carsten Winkler and Tobias Höft
05 MAR 2012

Copyright and license of CA Lab

Copyright (C) 2010 Helmholtz-Zentrum Berlin für Materialien und Energie GmbH , Berlin, Germany (HZB).
This software is distributed under the terms of the EPICS Open License .

LabVIEW is a trademark of National Instruments Corp.

http://www.ni.com

Ubuntu is a registered trademark of Canonical Ltd.

http://www.ubuntu.com

Windows is a registered trademark of Microsoft Cooperation

http://www.microsoft.com