ezcaIDL User's Guide

December 12, 2012

Mark Rivers

Center for Advanced Radiation Sources

University of Chicago

rivers@cars.uchicago.edu

Table of Contents

Overview

ezcaIDL is a library of routines for IDL and PV-WAVE which provides an interface to EPICS Channel Access through the EZCA and EzcaScan libraries.

PV-WAVE and IDL are closely related packages which are described as Data Visualization Tools. They consist of a general purpose interpreted language with very good graphics routines. Although not described as tools for data collection and control applications, their rapid prototyping capabilities and sophisticated graphics make them a nice environment for these applications. Both also provide easy to use widget toolkits for quickly developing GUI applications.

Although there is nearly a one-for-one match between the routines in ezcaIDL and the EZCA and EzcaScan libraries, the syntax of the IDL routines is not the same as the syntax of the corresponding EZCA and EzcaScan routines. The reason for this is that IDL is more "object oriented" and relieves the programmer of much of the detailed bookkeeping required of the C programmer. Thus for example, the IDL routine caGet() returns, by default, a value which has the native data type and element count of the process variable. This is not true of the corresponding C routine ezcaGet(), which requires the user to specify the data type and number of elements to be returned.

Release notes

The following are the more important notes taken from the CVS log file.

2012/12/12

2011/10/21

2001/9/28

This was a signficant rewrite.

Procedures and Functions

PV-WAVE and IDL are similar to FORTRAN in that they have two types of routines, procedures and functions. Procedure are similar to FORTRAN subroutines: they do not return a value. Functions, as in C or FORTRAN, return a value. ezcaIDL uses functions for all EZCA routines which return either status or data. Procedures are used for routines which return void, i.e. neither data nor status.

Procedure and function names are not case sensitive. Of course, the names of channel access process variables are case sensitive and must be specified correctly.

List of Routines by Functional Group

ezcaIDL consists of the following routines, grouped by functionality:

Related Documentation

In addition to this ezcaIDL Users' Guide the following documentation will be useful to the IDL programmer using ezcaIDL.

Synchronous Groups

Normally all ezcaIDL calls, such as caGet() and caPut() wait for all required channel access operations to complete before they return. This is often convenient, but it is very inefficient if one wants to read/write a large number of process variables. In this case it is much more efficient to submit a group of channel access requests, and then wait for them all to complete.

ezcaIDL supports the concept of "synchronous groups" in the EZCA library. A synchronous group is started by calling

    caStartGroup

Once a synchronous group is started, subsequent calls to routines like caGet(), caPut(), etc. simply queue a channel access operation, and do not actually perform the channel access I/O. Calling

    status = caEndGroup()

ends a synchronous group. This causes all of the queued channel access calls to be issued and waits for them to complete.

There are two important restrictions which must be kept in mind when calling any of the caGetxxx() routines (e.g. caGet(), caGetUnits(), caGetControlLimits(), etc.) from inside a synchronous group, i.e. after calling caStartGroup and before calling caEndGroup().

  1. The IDL variable(s) which contain the return data values must not be "re-used" or deleted before the call to caEndGroup(). The reason for this is that EZCA has been passed the addresses of these variables as the locations to which the data are to be copied when caEndGroup() is called. Thus, these locations must still point to a valid memory location when caEndGroup() is called. If the output variables are re-used then IDL's behavior is unpredictable, and bus errors/access violations could occur. In practice, fatal errors have not been observed, but they are possible.
  2. When using caGet() to read strings, the data type returned will be a byte array, rather than a string. The reason has to do with the manner in which IDL passes strings, which requires that EZCA actually be passed pointers to byte arrays. When caGet() is called outside of a group it automatically converts the byte array to a string before returning the value. However when caGet() is called inside of a synchronous group it cannot perform this conversion, since it cannot be done until after the data is read, which does not occur until caEndGroup() is called. Thus, it is the user's responsibility to convert the data from a byte array to a string after calling caEndGroup(). This is done very simply with the string() function.

The following is an example of a valid grouped operation. It also shows how to handle strings.

caStartGroup
status = caGet('test_mca1.VAL', mca_value)
status = caGet('test_vme1.DESC', vme_desc) ; This is a string PV
status = caEndGroup()
vme_desc = string(vme_desc)    ; Convert from byte array to string

The following is an example of an invalid grouped operation.

caStartGroup
status = caGet('test_mca1.VAL', mca_value)
status = caGet('test_vme1.VAL', vme_value)
mca_value=0
status = caEndGroup()

Note that mca_value was redefined before calling caEndGroup(), so the previous location became undefined. Do not do this!>

Error Handling

All ezcaIDL routines which can generate errors return a status code to indicate success or failure. 0 indicates success, any other value indicates failure. These status codes are generally those returned by the routines in ezca.c, although some errors are returned directly from routines in ezcaIDL.pro and ezcaIDL.c.

The EZCA routines will, by default, print brief diagnostic error messages when errors occur. These messages can be turned off by calling:

    caError, /OFF

A message describing the most recent error can be printed on stdout by calling:

    caError, /PRINT

A string describing the most recent error can be returned to the caller with:

    caErrror, err_string

For more information on error messages see the description of caError in the ezcaIDL Reference Guide

Debugging

Detailed trace information for the EZCA routines can be obtained by calling:

    caTrace, 1

This can be turned off by calling

    caTrace, 0

Even more detailed debugging information for the EZCA routines can be obtained by calling:

    caDebug, 1

This can be turned off by calling

    caDebug, 0

Files

ezcaIDL consists of the following files:

ezcaIDL.c
This file is a thin interface between IDL and PV-WAVE and EZCA and EzcaScan. It converts the parameters passed by IDL call_external() or PV-WAVE linknload() to the form required by EZCA and EzcaScan. It directly implements some functions which are not provided in the EZCA library. These include ezcaIDLGetCountAndType() and ezcaIDLGetEnumStrings(). This file is compiled and linked into a shareable object file, typically ezcaIDL.so on Unix and ezcaIDL.EXE on VMS.
ezcaIDL.pro
This file contains the IDL/PV-WAVE functions and procedures.
ezcaWidgets.pro
This file contains routines which simplify the use of widgets in IDL channel access applications. These routines only work with IDL, not with PV-WAVE.
ezcaIDLGuide.html
This documentation file.
ezcaIDLRef.html
This document contains a detailed description of all of the routines. It is extracted directly from the standard documentation headers for each routine in ezcaIDL.pro.

Required Support Libraries

ezcaIDL requires the following support libraries in order to build the shareable object file. Users who want to port ezcaIDL to another architecture need to port these libraries first.

    extensions/src/ezca
    extensions/src/EzcaScan
    base/src/ca
    base/src/libCom

Unix Setup

The following additions to your .login file will facilitate the use of ezcaIDL. 

# Define an IDL or PV-WAVE startup file to be executed when IDL or PV-WAVE are
# started
setenv IDL_STARTUP ~/idl_startup.pro
setenv WAVE_STARTUP ~/wave_startup.pro
#
# Define the location of ezcaIDL.so so this file can be located
# no matter what the current default directory is. This needs to be modified
# according to where the .so file is placed on your system.
setenv EZCA_IDL_SHARE /usr/local/epics/extensions/bin/solaris/ezcaIDL.so

In the IDL or PV-WAVE startup files (~/idl_startup.pro or ~/wave_startup.pro in the preceeding example .login file) add the following lines

;
!QUIET=1             ; So things will compile without informational messages
.RUN ezcaIDL         ; For both IDL and PV-WAVE
.RUN ezcaIDLWidgets  ; For IDL widget users
caInit               ; To define some required constants
;

VMS Setup

The following additions to your LOGIN.COM file will facilitate the use of ezcaIDL. 

$! Define an IDL or PV-WAVE startup file to be executed when IDL or PV-WAVE 
$! are started
$ DEFINE IDL_STARTUP SYS$LOGIN:idl_startup.pro
$ DEFINE WAVE_STARTUP SYS$LOGIN:wave_startup.pro
$!
$! Define the location of ezcaIDL.EXE so this file can be 
$! located no matter what the current default directory is. 
$! These need to be modified according to where the .EXE file is placed on 
$! your system.
$ DEFINE ezcaIDL_EXE  PUBLIC_DISK:[PUBLIC.EPICS.EXTENSIONS.BIN]ezcaIDL.EXE
$ DEFINE EZCA_IDL_SHARE ezcaIDL_EXE

In the IDL or PV-WAVE startup files (idl_startup.pro or wave_startup.pro in the preceeding example login.com file) add the following lines

;
!QUIET=1             ; So things will compile without informational messages
.RUN ezcaIDL         ; For both IDL and PV-WAVE
.RUN ezcaIDLWidgets  ; For IDL widget users
caInit
;

Examples

The following examples illustrate how to use some of the routines in ezcaIDL.

; Create a sine wave array, write it to a waveform record, read it back again
; and plot it.

IDL> name = "idl_test:wf1"
IDL> status = caGetCountAndType(name, n, type)
IDL> data = sin(dindgen(n) * 2 * !PI / (n-1))
IDL> status = caPut(name, data)
IDL> status = caGet(name, readback)
IDL> plot, readback


; Print the list of valid values for the .SCAN field of a record as strings,
; one per line.
status = caGetEnumStrings('idl_test:ai1.SCAN', choices)
for i=0, n_elements(choices)-1 do print, choices(i)


; Print out the next 10 values for a process variable which is changing by
; waiting for monitor events.
;
pv = 'mlr_scanner'
status = caSetMonitor(pv)    ; Add a monitor on this pv
status = caGet(pv, data)     ; Read the value, which clears the monitor flag
for i=1, 10 do begin
   count = 0
   status = 0
   while (caCheckMonitor(pv) ne 0) and (count le 100) do begin
      wait, .01
      count = count + 1                     ; Assumes new monitors come faster
      if (count eq 100) then status = -1    ; than 1 per second
   endwhile
   if (status ne 0) then begin
      print, 'Monitor wait failed for ', pv
   endif else begin
      status = caGet(pv, data)
      print, 'New value = ', data
   endelse
endfor
status = caClearMonitor(pv)


; The following is an example of a synchronous group operation
; It also shows how to handle strings in synchronous groups.
caStartGroup
status = caGet('test_mca1.VAL', mca_value)
status = caGet('test_vme1.VAL', vme_value)
status = caGet('test_vme1.DESC', vme_desc) ; This is a string PV
status = caEndGroup()
vme_desc = string(vme_desc)    ; Convert from byte array to string

IDL Widgets

The file ezcaIDLWidgets.pro contains 3 routines which simplify the use of channel access, and particularly channel access monitors, with the IDL widget toolkit.

caWidgetSetMonitor(name, widget_id, time=time)

This function first adds a monitor on process variable "name", using routine caSetMonitor().

If this is the first time caWidgetSetMonitor has been called then it creates a dummy (iconified) widget which runs a timer routine. The timer routine periodically calls caCheckMonitor(name) to determine whether a channel access monitor has arrived for "name". If a monitor has occurred then an event will be sent to the widget whose ID is specified by "widget_id".

The event structure is as follows:

    event = 
      { id         ; The widget ID which was passed to caWidgetSetMonitor
        top:       ; The top level widget in this hierarchy
        handler:   ; The widget handler routine
        name:      ; The name of the process variable for which a monitor has
                   ; occurred.
      }

When the event is sent, the event handler routine for the specified widget will be called. Generally this routine look at the event.id field to determine that this is a monitor event (rather than a mouse event). If the same event handler can receive monitor events from more than one process variable, (because caWidgetSetMonitor was called for several process variables) the event handler will then look at the event.name field to determine which process variable generated the monitor event.

Typically the widget_id which is passed to caWidgetSetMonitor should be the id of a base widget. Base widgets cannot generate events due to mouse clicks, etc. so the widget event handler routine can distinguish monitor events from mouse events by looking at the widget.id field. This is the same concept which is described in the IDL documentation for timer events, e.g.

    widget_control, wid, timer=1.0

caWidgetSetMonitor can be called for many different process variable names and widget_ids. The widgets do not need to belong to the same widget hierarchy. Multiple widgets can monitor the same process variable, and the same widget can be used to monitor several process variables. Internally caWidgetSetMonitor maintains a list of all monitored process variables, and which widget_id(s) are to receive events from each process variable.

The "time" keyword to caWidgetSetMonitor can be used to control the time interval between polling cycles. The default is 0.1 seconds.

This routine sounds complex, but in fact it is simple to use and greatly simplifies the use of channel access monitors with IDL widget, since without it each widget event routine would have to poll to detect the arrival of channel access monitors. The following is a simple example of the use of this routine: 

pro example_event, event
    common example_common, pv_name, widget_ids
    ; This is the event handler routine, called whenever any type of event
    ; (monitor, mouse, timer) occurs.
   case event.id of
        widget_ids.monitor: begin
            ; Read the new value and display it
            status = caGet(event.name, value, /string)
            widget_control, widget_ids.value, set_value=value
        end

        widget_ids.exit: begin
            t=CaWidgetClearMonitor(pv_name, widget_ids.monitor)
            widget_control, event.top, /destroy
       	end
   endcase
end

pro example, name
    common example_common, pv_name, widget_ids
    ; This is the main routine for the example. 
    ; It is passed the name of a process variable to monitor.
    ; It creates a simple screen with a value field for the monitored process 
    ; variable and an EXIT button
    widget_ids= { $
            monitor:    0L, $
            value:      0L, $
            exit:       0L }
    base=widget_base(title="Example", /column)  ; The base widget
    widget_ids.monitor=base                     ; The monitor widget id=base
    widget_ids.value=widget_text(base, xsize=20) ; Widget to display new value
    widget_ids.exit=widget_button(base, value="Exit")  ; Exit button
    widget_control, base, /realize              ; Display the widgets
    t=caWidgetSetMonitor(name, widget_ids.monitor); Call caWidgetSetMonitor
    pv_name = name                              ; Copy name to common
    xmanager, "example", base                   ; Start the program
end

caWidgetClearMonitor(name, widget_id)

This routine cancels the effect of caWidgetSetMonitor. If there are no other widgets monitoring this process variable then caClearMonitor is called to completely remove the channel access monitor on this name.

CaWidgetAdjust(name, font=font, min=min, max=max, label=label, group=group)

This is a general purpose routine for adjusting and monitoring a process variable. It creates widget which is appropriate for the data type of "name", i.e. a mutually exclusive menu for DBF_ENUM, a text entry widget for DBF_STRING and an editable slider widget for any numeric data type. This routine can be called from the event handler of larger applications when all that needs to be done is adjust the value of a process variable.

name is the name of the process variable to be adjusted.

The font keyword can be used to specify a font to use.

The min and max keywords can be used to specify the upper and lower limits of the slider widget when adjusting numeric process variables.

The label keyword can be used to put a descriptive label at the top of the widget.

The group keyword can be used to set the id of the parent widget. If the widget specified by group is deleted, then the widget created by CaWidgetAdjust will also be deleted.