# Extended IDL Help

This page was created by the IDL library routine `mk_html_help`. For more information on this routine, refer to the IDL Online Help Navigator or type:

         ? mk_html_help

at the IDL command line prompt.

Last modified: Wed Sep 16 21:11:27 1998.

# List of Routines

- CACHECKMONITOR
- CACLEARMONITOR
- CADEBUG
- CAENDGROUP
- CAERROR
- CAGET
- CAGETARRAY
- CAGETCONTROLLIMITS
- CAGETCOUNTANDTYPE
- CAGETENUMSTRINGS
- CAGETERROR
- CAGETGRAPHICLIMITS
- CAGETPRECISION
- CAGETRETRYCOUNT
- CAGETSTATUS
- CAGETTIMEOUT
- CAGETUNITS
- CAINIT
- CAMONITOR
- CAPENDEVENT
- CAPENDIO
- CAPUT
- CAPUTARRAY
- CASCAN
- CASEARCH
- CASETMONITOR
- CASETRETRYCOUNT
- CASETTIMEOUT
- CASTARTGROUP
- CATIMESTAMP
- CATRACE
- CAVERSION
- CAWIDGETADJUST
- CAWIDGETCLEARMONITOR
- CAWIDGETSETMONITOR

# Routine Descriptions

## CACHECKMONITOR

[Next Routine] [List of Routines]

     NAME:
    	caCheckMonitor

     PURPOSE:
    	This function returns a non-zero value if there is a new (unread)
           monitor for this process variable, otherwise it returns zero.
           This function is particularly useful when a caGet() operation is
           expensive in time, e.g. reading large arrays.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	state = caCheckMonitor(pvname)

     INPUTS:
    	pvname: The name of the process variable on which to check the monitor.

     OUTPUTS:
           The function return value is zero if no new monitor value is available,
           and non-zero if a new monitor value is available.

     PROCEDURE:
    	This routine uses ezcaNewMonitorValue(). The "type" parameter required
           by ezcaNewMonitorValue() is the native EZCA data type as determined
           by caGetCountAndType().

     EXAMPLES:
           IDL> state = caCheckMonitor('test_ao1',event)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CACLEARMONITOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caClearMonitor

     PURPOSE:
    	This procedure clears a monitor on the specified process variable.
           It cancels the effect of caSetMonitor().

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caClearMonitor(pvname)

     INPUTS:
    	pvname: The name of the process variable on which to clear the monitor.

     OUTPUTS:
           The function return value of caClearMonitor is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     PROCEDURE:
    	This routine uses ezcaClearMonitor(). The "type" parameter required
           by ezcaClearMonitor is the native EZCA data type as determined
           by caGetCountAndType().

     EXAMPLES:
           IDL> status = caClearMonitor('test_ao1')

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CADEBUG

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caDebug

     PURPOSE:
    	This procedure turns the EZCA debugging flag on or off. Turning on
           the debugging flag prints lots of information, which is mainly
           useful to developers.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caDebug, state

     INPUTS:
    	state:  state=1 turns debugging on, state=0 turns debugging off.

     OUTPUTS:
           None

     PROCEDURE:
    	This routine uses ezcaDebugOn() and ezcaDebugOff().

     EXAMPLES:
           IDL> caDebug, 1     ; Turn on debugging
           setting Debug
           IDL> status = caGet('test_ao1', value)
           ca_pend_event(0.000010)
           --start end-of-prologue() report
           ****** Start State:
           AutoErrorMessage T InGroup F Debug T Trace F ErrorLocation LastOnly ListPrint
           LastOnly TimeoutSeconds 0.050000
           Workp : 9cf970 trashme F (nxt 0)
           Channel_avail_hdr 0 :
           ...
           ...
           IDL> caDebug, 0 ; Turn off debugging

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAENDGROUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caEndGroup

     PURPOSE:
    	This function ends an "asynchronous group". See caStartGroup for more
           information on asynchronous groups.
           caEndGroup flushes the queue of caGet and caPut calls and waits for
           replies from the channel access servers.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	stat = caEndGroup(status)

     INPUTS:
    	None.

     OUTPUTS:
           The function return value is 0 if the operation was successful,
           otherwise it is the first encountered non-successful return code.
           The optional status parameter can be used to return the status code
           of each operation in the group.

     OPTIONAL OUTPUT PARAMETERS:
           status: If this optional parameter is present then it returns a
                   array of status information, one for each channel access
                   call in the group.

     COMMON BLOCKS:
           EZCA_COMMON contains a flag (ingroup) which indicates if we
           are currently in an asynchronous group. This routine clears that flag.

     PROCEDURE:
    	If the status parameter is present then this routine uses
           ezcaEndGroupWithReport().  If the parameter is not present then
           the routine calls ezcaEndGroup().

     RESTRICTIONS:
           When the status parameter is present, and ezcaEndGroupWithReport() is
           called, there is no way to know in advance how many status values
           will be returned.  This routine passes a status array with 1024
           elements, and then truncates it to the actual length.  The maximum
           number of status values which can be retrieved is thus 1024. No errors
           will occur if an asynchronous group has more than 1024 calls, but
           only the first 1024 status values can be obtained.
           This is probably sufficient for most applications!

     EXAMPLES:
           IDL> caStartGroup
           IDL> status = caget('test_ao1.SCAN', scan)
           IDL> status = caget('test_mca1.ERTM', ertm)
           IDL> ; Print out values - they will be zero.
           IDL> help, scan, ertm
           IDL> status = caEndGroup()
           IDL> ; Print out values after executing caEndGroup, they are non-zero
           IDL> help, scan, ertm
           Output:
               SCAN            INT       =        0
               ERTM            FLOAT     =      0.000000
               SCAN            INT       =        6
               ERTM            FLOAT     =       7.10000

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAERROR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caError

     PURPOSE:
    	This procedure controls error printing and returns error strings.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caError, err_string, /ON, /OFF, /PRINT, prefix=prefix

     INPUTS:
           None

     KEYWORD PARAMETERS:
           /ON
               Setting this switch turns on automatic error message printing
               on stdout.  Automatic printing is initially enabled.

           /OFF
               Setting this switch turns off automatic error message printing
               on stdout.

           /PRINT
               Setting this switch prints the last error message on stdout.

           prefix=prefix
               The prefix keyword can be used to pass a string which is prefixed
               to error messages printed with /PRINT or fetched via the optional
               output parameter.

     OPTIONAL OUTPUT PARAMETERS:
    	err_string:
               If this parameter is present then it will contain the text of the
               last error message.

     COMMON BLOCKS:
           EZCA_COMMON contains a flag (ingroup) which indicates if we
           are currently in an asynchronous group. This routine tests that flag.

     PROCEDURE:
    	This routine uses ezcaPerror(), ezcaAutoErrorMessageOn(),
           ezcaAutoErrorMessageOff(), and ezcaGetErrorString()

     EXAMPLE:
           IDL> ; Define a prefix and turn on error messages
           IDL> caError, prefix='My program', /ON
           IDL> ; Fetch the last error message
           IDL> caError, err_string

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGET

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGet

     PURPOSE:
    	This function reads the value of a Channel Access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	Status = caGet(pvname, value, /string, max=n)

     INPUTS:
    	pvname:	The name of the process variable for which the value is to
                   be returned.

     KEYWORD PARAMETERS:
    	STRING:	Set this flag to force caGet to return a string, rather than
                   a number.  This flag is particularly useful when the native
                   channel access data type is ENUM (3), since the string is
                   more descriptive than the number.

    	MAX:    This keyword parameter is used to limit the number of
                   values returned by caGet. caGet normally returns the native
                   element count for a process variable. Setting MAX to a
                   number less than this will cause caGet to return only the
                   first MAX values in the array.

     OUTPUTS:
    	value:  The value of the process variable. By default, caGet returns
                   "value" with the native data type and number of elements
                   of the process variable. It determines this information by
                   calling caGetCountAndType().  Note that if caGet is called
                   after calling caStartGroup but before calling caEndGroup then
                   the IDL variable "value" is created, but will not actually
                   contain the data until caEndGroup is called.

           The function return value of caGet is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.  If caGet is called from
           within an asynchronous group then the status return only indicates
           whether the operation was successfully queued.

     COMMON BLOCKS:
           EZCA_COMMON contains a flag (ingroup) which indicates if we
           are currently in an asynchronous group. This routine tests that flag.

     SIDE EFFECTS:
    	This routine will causes a channel access search to take place if
           this is the first time this process variable has been referenced. It
           performs a ca_get, unless called as part of an asynchronous group.

     RESTRICTIONS:
           There are two important restrictions which must be kept in mind when
           calling caGet from inside a "group", i.e. after calling caStartGroup
           and before calling caEndGroup.

           1) The IDL "value" variable (i.e. the second parameter
           passed to caGet) must not be "re-used" or deleted before the call to
           caEndGroup. The reason for this is that EZCA has been passed the
           address of this variable as the location in which the data is to be
           copied when caEndGroup is called. Thus, this location must still
           point to a valid memory location when caEndGroup is called.
           If the "value" variable is re-used then IDL's behavior is
           unpredictable, and bus errors/access violations could occur.

           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 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. For more information see the example below.

     PROCEDURE:
    	This routine uses ezcaGet().

     EXAMPLES:
           IDL> ; The following is an example of a single caGet
           IDL> status = caGet('test_mca1.VAL', value)

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

           IDL> ; The following is an example of an INVALID grouped operation
           IDL> caStartGroup
           IDL> status = caGet('test_mca1.VAL', mca_value)
           IDL> status = caGet('test_vme1.VAL', vme_value)
           IDL> mca_value=0
           IDL> ; We have redefined mca_value, so the previous location is
           IDL> ; undefined. NO NOT DO THIS!
           IDL> status = caEndGroup()

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995
           09-03-98        Mark Rivers  Fixed bug in "max" keyword

(See ezcaIDL.pro)

## CAGETARRAY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           caGetArray

     PURPOSE:
           This function reads values for a list of Channel Access process
           variable. It returns 0 if successful, returns -1 if failed.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           Status = caGetArray(names,pdata,max=no,type=i,/TYPE,/EVENT)

     INPUTS:
           names:	The variable for a list of channel access PV names for which
                   the array of data is to be returned.

     KEYWORD PARAMETERS:
          MAX:    Default to 1 for a list of PV names. If more than one values
                  to be returned for a list of array type PV names, this keyword
                  must be specified. If the `no' specified is greater than the
                  native count, zeros will be padded in the output array.

                  If only one PV name is input, then caGetArray returns
                  the native element count for the process variable. Setting
                  MAX to a number less than the native count this will cause
                  caGetArray to return only the first MAX values for the PV.

          TYPE:   This keyword specifies the IDL data type to be returned by
                  the output array. If not specified, it defaults to 5, i.e.
                  double precision type of data will be returned by the
                  output array.

                    1 - byte      2 - short       3 - long      4 - float
                    5 - double    7 - string

         /TYPE    Instead of type=i a user can use the IDL data type keyword
                  directly, the data type keyword supercedes the type=i
                  specification. Valid types given below

                                /double
                                /float
                                /string
                                /long
                                /short
                                /byte

        /EVENT    If specified use the ca_array_get_callback otherwise use
                  the ca_array_get

     OUTPUTS:
         pdata:  The output variable,  pdata(max,noNames), returns the data
                 array for the requested list of PV names. The `max' is the no
                 of values specified by the keyword MAX, the `noNames' is the
                 number of PV names in the input variable names.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine will causes a channel access search to take place if
           this is the first time this process variable has been referenced.

     RESTRICTIONS:
           Only one type of data can be requested for a list of PV names.

     PROCEDURE:
    	This routine uses Ezca_getArray() from the Ezca library.

     EXAMPLES:
           Three examples are given below.
           The first caGetArray call returns only the first value for each PV
           name, the second and third caGetArray call both returns 10 float
           values for each PV name

           IDL> names=['chademowf7','chademowf8']
           IDL> st = caGetArray(names,pdata)
           IDL> st = caGetArray(names,pdata,max=10,/float)
           IDL> st = caGetArray(names,pdata,max=10,type=4)

     MODIFICATION HISTORY:
           Written by:	Ben-chin Cha      Dec, 1995
          04-11-96     bkc    If array get failed, only the pvnames not found are
                              reported
          04-22-96     bkc    Replace caError by caGetError

(See ezcaIDL.pro)

## CAGETCONTROLLIMITS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetControlLimits

     PURPOSE:
    	This procedure reads the control limits for the specified channel
           access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caGetControlLimits(pvname, low, high)

     INPUTS:
    	pvname: The name of the process variable from which to read the
                   control limits.

     OUTPUTS:
           low:    The low control limit (double).

           high:   The high control limit (double).

           The function return value of caGetControlLimits is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     PROCEDURE:
    	This routine uses ezcaGetControlLimits().

     EXAMPLE:
           IDL> status = caGetControlLimits('test_ao1', low, high)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETCOUNTANDTYPE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetCountAndType

     PURPOSE:
    	This function returns the number of elements and data type of a
           Channel Access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	Status = caGetCountAndType(pvname, count, type)

     INPUTS:
    	pvname:	The name of the process variable for which information is to
                   be returned.

     OUTPUTS:
    	count:  The number of elements in the process variable. This is 1 for
                   scalar process variables and more than 1 for arrays.

           type:   This is a 3 element array containing information about the data
                   type of the process variable.
                   type(0) = Channel access data type as defined in "cadef.h"
                   type(1) = EZCA data type as defined in "ezca.h"
                   type(2) = IDL/PV-WAVE data type as defined in size()
                   These data types are as follows:

                   Name    Channel Access      EZCA        IDL/PVWAVE
                   String      0                 1             7
                   Short       1                 2             2
                   Float       2                 4             4
                   Enum        3                 2 (short)     2 (short)
                   Byte        4                 0             1
                   Long        5                 3             3
                   Double      6                 5             5

       The function return value of caGetCountAndType is a status value.  The
       status is 0 if the routine was successful (i.e. the process variable exists)
       and non-zero if the routine failed.

     SIDE EFFECTS:
    	This routine will cause a Channel Access search to take place if this is
           the first time this process variable has been referenced.

     RESTRICTIONS:
           The channel access data type enum is mapped to EZCA and IDL short
           data types.  However, application programs can use this routine to
           determine if the native channel access data type is enum, and then
           use caGet(pvname, value, /string) to read the string equivalent of the
           process variable. Programs can also use
           caGetEnumStrings(pvname, strings) to read the strings for the all of
           the possible values of an enum process variable.

     PROCEDURE:
    	This routine uses ezcaPvToChid() and then ca_element_count() and
           ca_field_type().
           Note that this routine always returns its values "immediately", even
           if it is called between a caStartGroup and caEndGroup.

     EXAMPLE:
           IDL> status = caGetCountAndType('test_mca1.VAL', count, type)
           IDL> print, status
           0                       ; Status = success
           IDL> print, count
           2048                    ; Array with 2048 elements
           IDL> print, type
               5       3       3   ; Long data type
     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETENUMSTRINGS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetEnumStrings

     PURPOSE:
    	This function returns all of the choice strings associated with a
           Channel Access "enum" process variable. It is particularly useful
           for building menus of options.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	Status = caGetEnumStrings(pvname, strings)

     INPUTS:
    	pvname:	The name of the process variable for which the enum strings
                   are to be returned. The native channel access data type of
                   this process variable must be enum (3).

     OUTPUTS:
    	strings: A string array containing the strings for each possible
                   value of the enum variable.

           The function return value of caGetEnumStrings is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists and is of type enum) and non-zero if the routine failed.

     SIDE EFFECTS:
    	This routine causes a channel access read. It does not use the
           grouping mechanism of EZCA, i.e. it always executes immediately.

     RESTRICTIONS:
           There must be less than 16 enum strings and they must each be less
           than 26 characters.

     PROCEDURE:
    	This routine uses ezcaPvToChid and then ca_get() with a request type
           of DBR_GR_ENUM.  The functionality required by this routine is not
           presently provided directly in EZCA, although it should probably be
           added.

     EXAMPLES:
           IDL> status = caGetEnumStrings('test_mca1.SCAN', strings)
           IDL> for i=0, n_elements(strings)-1 do print, strings(i)
           Passive
           Event
           I/O Intr
           10 second
           5 second
           2 second
           1 second
           .5 second
           .2 second
           .1 second

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETERROR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetError

     PURPOSE:
           This function get CA return codes for a list of process variable names.
           Return code can be 0 or -1, 0 for success, -1 for failure.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           Status = caGetError(Pvname,Err)

     INPUTS:
          Pvname: The variable for a list of process variables for which the
                  channel access return code to be checked.

     KEYWORD PARAMETERS:
           None.

     OUTPUTS:
           Err:  The corresponding return code(s) for the Pvname(s) are returned.
                 Returns array of 0 or 1. 0 indicates success, 1 indicates failed.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine will causes a channel access search to take place if
           this is the first time pvnames has been referenced.

     RESTRICTIONS:
           None.

     PROCEDURE:
           This routine uses Ezca_get_error_array() from the Ezca library.

     EXAMPLES:
           IDL> print,caGetError('chademoai1')
           IDL> x = ['chademoai1','chademoai2']
           IDL> status = caGetError(x)

     MODIFICATION HISTORY:
           Written by:	Ben-chin Cha      Dec, 1995

(See ezcaIDL.pro)

## CAGETGRAPHICLIMITS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetGraphicLimits

     PURPOSE:
    	This procedure reads the graphic limits for the specified channel
           access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caGetGraphicLimits(pvname, low, high)

     INPUTS:
    	pvname: The name of the process variable from which to read the
                   graphic limits.

     OUTPUTS:
           low:    The low graphic limit (double).

           high:   The high graphic limit (double).

           The function return value of caGetGraphicLimits is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     PROCEDURE:
    	This routine uses ezcaGetGraphicLimits().

     EXAMPLE:
           IDL> status = caGetGraphicLimits('test_ao1', low, high)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETPRECISION

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetPrecision

     PURPOSE:
    	This procedure reads the precision for the specified channel
           access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caGetPrecision(pvname, precision)

     INPUTS:
    	pvname: The name of the process variable from which to read the
                   precision.

     OUTPUTS:
           precision:  The precision (short).

           The function return value of caGetPrecision is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     PROCEDURE:
    	This routine uses ezcaGetPrecision().

     EXAMPLE:
           IDL> status = caGetPrecision('test_ao1', precision)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETRETRYCOUNT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetRetryCount

     PURPOSE:
    	This function returns the value of the EZCA retry count parameter.
           In conjunction with the EZCA Timeout parameter it determines how
           long EZCA will try to connect to a process variable before giving up.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	RetryCount = caGetRetryCount()

     INPUTS:
    	None.

     OUTPUTS:
           The function return value of caGetRetryCount is the integer
           value of the EZCA RetryCount parameter.

     PROCEDURE:
    	This routine uses ezcaGetRetryCount().

     EXAMPLES:
           IDL> print, caGetRetryCount()
           599

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETSTATUS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetStatus

     PURPOSE:
    	This procedure reads the status parameters for a channel access
           process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caGetStatus(pvname, timestamp, status, severity)

     INPUTS:
    	pvname: The name of the process variable from which to read the
                   status parameters.

     OUTPUTS:
           timestamp: The timestamp of the last time the record was processed
                   lonarr(2).

           status: The status flag (int).

           severity: The severity flag (int).

           The function return value of caGetStatus is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     PROCEDURE:
    	This routine uses ezcaGetStatus().

     EXAMPLE:
           IDL> status = caGetStatus('test_ao1', timestamp, status, severity)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETTIMEOUT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetTimeout

     PURPOSE:
    	This function returns the value of the EZCA Timeout parameter. This
           value determines the time parameter passed to ca_pend_io() in EZCA.
           In conjunction with the EZCA RetryCount parameter it determines how
           long EZCA will try to connect to a process variable before giving up.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	timeout = caGetTimeout()

     INPUTS:
    	None.

     OUTPUTS:
           The function return value of caGetTimeout is the floating point
           value of the EZCA Timeout parameter, in seconds.

     PROCEDURE:
    	This routine uses ezcaGetTimeout().

     EXAMPLES:
           IDL> print, caGetTimeout()
           0.0500000

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAGETUNITS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caGetUnits

     PURPOSE:
    	This procedure reads the units string for the specified channel
           access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caGetUnits(pvname, units)

     INPUTS:
    	pvname: The name of the process variable from which to read the units.

     OUTPUTS:
           units:  The units (string).

           The function return value of caGetUnits is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     COMMON BLOCKS:
           EZCA_COMMON contains a flag (ingroup) which indicates if we
           are currently in an asynchronous group. This routine tests that flag.

     PROCEDURE:
    	This routine uses ezcaGetUnits().

     EXAMPLE:
           IDL> status = caGetUnits('test_ao1', units)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAINIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caInit

     PURPOSE:
    	This routine sets the channel access timeout used by list array
           functions defined in Ezca library.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caInit [,flag] [,help=help]

     INPUTS:
    	flag:	Optional flag, if set to -1  Ezca library default timeout
                   settings will be used.

     KEYWORD PARAMETERS:
         HELP:  If ,/HELP is set, on-line help will be displayed.

     OUTPUTS:
           None.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine set the channel access timeout values used in the
           Ezca library.  This routine set the timeout to 3 seconds for
           lists of process variables, and sets the timeout for
           ca_pend_event to 0.001 second.

           If a value of -1 is specified for the flag, the default value
           of 10 seconds for lists of process variables will be used.

     RESTRICTIONS:
           None.

     PROCEDURE:
    	This routine uses Ezca_init() from the Ezca library.

     EXAMPLES:
           IDL> caInit

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha     Dec, 1995

(See ezcaIDL.pro)

## CAMONITOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           caMonitor

     PURPOSE:
           This function provides Add/Get/Check/Clear monitor features on a
           single PV or a list of PV names.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           Status = caMonitor(name, vals, num, overflow, op_keyword,type_keyword, max=no)

     INPUTS:
           name:	The variable for a PV or a list of PV names.

     KEYWORD PARAMETERS:
         ADD:      Set /ADD to add CA monitor for the specified name.
                   Return 0 for success, -1 for failure.

         CLEAR:    Set /CLEAAR to clear CA monitor for the specified name.
                   Return 0 for success, -1 for failure.

         CHECK:    Set /CHECK to check for new event for the specified name.
                   Return 0 for success, -1 for failure.
                   The ouput variable 'vals' contains the return event flags.
                     0 - flags no new event detected
                     1 - flags new event detected

         GET:      Set /GET to get monitor values back for the specified name.
                   Different type of monitor returns different vals array.
                   If non queue type monitor set, the vals array returns a
                   single value for each PV in the name variable.
                   If the kewword /QUEUE is specified, in addition of vals,
                   both num and overflow variables are also returned.

         QUEUE:	Set /QUEUE flag to queue the value change event for the
                   monitored channel until the user gets them.

         MAXQUEUE: The MAXQUEUE=no must be specified if /QUEUE is specified.

         MODE:     This flag indicates what type of monitor queue is desired.
                   The MODE=i where i can be 1/2/3, it defaults to 1. The
                   MODE=1 or 2 monitor fills the QUEUE buff until it is fulled.
                   If MODE=1, the /GET will clear the QUEUE buff.
                   IF MODE=2, the /GET will not clear the QUEUE buff.
                   The MODE=3 uses the circulat buffer, it keeps the most
                   current MAXQUEUE values in the queue buffer.

     OUTPUTS:
         vals:     Returns the array of data if either keyword /GET or /CHECK
                   is specified

         num:      Returns the real number of data in the vals array for the
                   /QUEUE mode

         overflow: Returns the buffer full indicator for the /QUEUE mode
                   0 - vals queue buff is not full
                   1 - vals queue buff is full

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine will causes a channel access search to take place if
           this is the first time this process variable has been referenced.

     RESTRICTIONS:
           All the PV are monitored as double precision in this function.
           For getting the monitored queue array, only a single PV name can
           be specified.  For non queue type monitor, only the first value
           for a PV can be returned by this function.  Use caGet to get
           array type of values back.

     PROCEDURE:
    	This routine uses Ezca_monitorArrayAdd(), Ezca_monitorArrayGet(),
           Ezca_monitorArrayCheck(), Ezca_monitorArrayClear(), Ezca_queueAdd(),
           Ezca_queueGet(),Ezca_queueZero(), and Ezca_queueClear()
           from the Ezca library.

     EXAMPLES:
        Single value monitor

           IDL> print,caMonitor('chademoai1',/add)
           IDL> print,caMonitor('chademoai1',vals,/get)
           IDL> print,caMonitor('chademoai1',/clear)

        Use queue array monitor with maxqueue=100

           IDL> print, caMonitor('chademoai1',/add,/queue,maxqueue=100)
           IDL> print, caMonitor('chademoai1',vals,num,overflow,/get,/queue,maxqueue=100)
           IDL> print, caMonitor('chademoai1',/clear,/queue)

     MODIFICATION HISTORY:
           Written by:	Ben-chin Cha      Dec, 1995
           04-12-96    bkc   Modified on line help syntax

(See ezcaIDL.pro)

## CAPENDEVENT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caPendEvent

     PURPOSE:
    	This function causes the Ezca to call channel access ca_pend_event
           function.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caPendEvent [,time=0.001] [,help=help]

     INPUTS:
           None.

     KEYWORD PARAMETERS:
           TIME:  This keyword parameter is used to reset the timeout in seconds
                  used by ca_pend_event in Ezca library.

           HELP:  If ,/HELP is set, on-line help will be displayed.

     OUTPUTS:
           None.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine sets the timeout for event monitor routines used in
           Ezca library and calls the ca_pend_event.

     RESTRICTIONS:
    	Positive time must be used.

     PROCEDURE:
    	This routine uses Ezca_setPendTime() from the Ezca library.

     EXAMPLES:
           IDL> caPendEvent, time=0.0001

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha      Dec, 1995

(See ezcaIDL.pro)

## CAPENDIO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caPendIO

     PURPOSE:
    	This routine sets the timeout used by ca_pend_io in array get/
           put used in Ezca library.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           caPendIO, time=time, list_time=list_time

     INPUTS:
           None.

     KEYWORD PARAMETERS:
    	TIME:   Use the TIME=time keyword to set the timeout waiting for
                   channel access I/O for single process variable name.

    	LIST_TIME: Use the LIST_TIME=list_time keyword to set the timeout
                   waiting for channel access I/O for a list of PV names.

           HELP:   If ,/HELP is specified, on line help will be displayed.

     OUTPUTS:
           None.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           These times will be used in array get/put from then on in all
           ca_pend_io calls in Ezca library.

     RESTRICTIONS:
           Positive real times should be used in those keywords.

     PROCEDURE:
    	This routine uses Ezca_setPendTime() from the Ezca library.

     EXAMPLES:
           IDL> caPendIO, time=0.1, list_time=3.
           IDL> caPendIO, /help

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha      Dec, 1995

(See ezcaIDL.pro)

## CAPUT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caPut

     PURPOSE:
    	This procedure writes a new value to a channel access process variable.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caPut(pvname, value)

     INPUTS:
    	pvname:	The name of the process variable for which the new value
                   is to be written

           value:  The new value to be written. In general this can be a scalar
                   or array of any data type.  There are of course restrictions
                   in that certain strings cannot be written to certain process
                   variables, and some process variables cannot be passed arrays.

     OUTPUTS:
           The function return value of caPut is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists and a valid value was written) and non-zero if the routine
           failed.

     PROCEDURE:
    	This routine uses ezcaPut(). The "nelem" and "type" parameters passed
           to ezcaPut are determined from the IDL data type and number of elements
           of the "value" parameter passed to caPut(). Strings are converted to
           to byte arrays before being passed.

     RESTRICTIONS:
           None.   caPut can be called inside a group, i.e. after calling
                   caStartGroup and before calling caEndGroup.  The "value"
                   variable passed to caPut can be immediately re-used when
                   inside a group, since EZCA copies it to a private location.

     EXAMPLES:
           IDL> ; Put a linear ramp (findgen()) to a waveform process variable.
           IDL> status = caPut('my_waveform.VAL', findgen(100))

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAPUTARRAY

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           caPutArray

     PURPOSE:
           This function writes an array of data to a list of Channel Access
           process variable. It returns 0 if successful, else retuns -1.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           Status = caPutArray(pvname, pdata, /event)

     INPUTS:
           pvname:	The variable specifies a list of process variables for
                   which the input array of data is to be written to IOC.
           pdata:  Input data array. The data array must be consistant with
                   the number of PV names defined in the pvname.

     KEYWORD PARAMETERS:
          EVENT:   If specified use the ca_array_put_callback otherwise
                   use the ca_array_put.

     OUTPUTS:
          None.

     COMMON BLOCKS:
          None.

     SIDE EFFECTS:
           This routine will causes a channel access search to take place if
           this is the first time this process variable has been referenced.

     RESTRICTIONS:
           Thus, it is the user's responsibility to make sure the adequate
           pdata is provided for the pvname.

     PROCEDURE:
    	This routine uses Ezca_putArray() from the Ezca library.

     EXAMPLES:
           In the following example write a string value '11' to two PV
           names: chademomask1.VAL  and chademoai2.VAL

           IDL> x = ['chademomask1', 'chademoai2']
           IDL> y = make_array(1, 2, /string)
           IDL> y(0) = '11'
           IDL> y(1) = '11'
           IDL> status = caPutArray(x,y)

           In the following example write values [1,2,3] to two waveform records
           names: chademowf2  and chademowf5

           IDL> x = ['chademowf2','chademowf5']
           IDL> y = make_array(3, 2)
           IDL> y(0,0) = [1,2,3]
           IDL> y(0,1) = [1,2,3]
           IDL> print,caPutArray(x,y)
           IDL> print,caGetArray(x,pd,max=10)
           IDL> print,pd

     MODIFICATION HISTORY:
           Written by:	Ben-chin Cha      Dec, 1995

(See ezcaIDL.pro)

## CASCAN

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           caScan

     PURPOSE:
           This function provides add/get/zero/clear monitor features on a
           scan record and a set of PV names.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           Status = caScan(name,pvnames,nonames,npts,vals,op_keyword,max=no)

     INPUTS:
           name:   The name of the process variable which has control of
                   triggering scan, e.g. the scan record name.
           pvnames: A list of detector process variables for which the values
                    are to be monitored by the trigger name.

     KEYWORD PARAMETERS:
          ADD:     Set this flag /ADD  to add a complete set of monitor for
                   name and pvnames.
                   Return 0 if successful, -1 if failed, 1 if old monitor
                   already existed. If succeeds, the output variable npts
                   is set to the number of data to be detected, and the
                   nonames is set to the number of PVs in pvnames.

          CLEAR:   Set this flag /CLEAR to clear the monitor set by add.
                   Return 0 if successful, -1 if failed.

          GET:     Set this flag /GET to get scan array of monitor values back.
                   Return -1 if failed, return 1 if scan is properly set up but
                   not triggered yet, return >1 if real data detected.
                   If succeeds, the npts is set to the number of data so far
                   detected.

          ZERO:    Set this flag /ZERO to zero the allocated space.
                   Return 0 for success, -1 for failure.

          MAX:     Specifies the max number of monitor values to be returned.
                   If the trigger name is not a scan record, the max=no must
                   be provided for this function.

     OUTPUTS:
         nonames:  This variable returns the number of PVs in pvnames.
         npts:     This variable returns the current number of data points
                   detected by the scan record.
         vals:     This detector data array buff, vals(nonames,max), stores
                   the detected data so far captured.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine will causes a channel access search to take place if
           this is the first time this process variable has been referenced.

     RESTRICTIONS:
           None.

     PROCEDURE:
           This routine uses Ezca_scanAddMonitor(), Ezca_scanClearMonitor(),
           Ezca_scanGetMonitor(), and Ezca_scanZeroMonitor() from the Ezca
           library.

     EXAMPLES:
          For scan record type triggered scan

           IDL> print,caScan('name',pvnames,/add)
           IDL> print,caScan('name',pvnames,nonames,npts,vals,/get)
           IDL> print,caScan('name',pvnames,/zero)
           IDL> print,caScan('name',pvnames,/clear)

          For non-Scan record type triggered scan

           IDL> print,caScan('name',pvnames,/add,max=100)
           IDL> print,caScan('name',pvnames,nonames,npts,vals,/get,max=100)
           IDL> print,caScan('name',pvnames,/zero,max=100)
           IDL> print,caScan('name',pvnames,/clear,max=100)

     MODIFICATION HISTORY:
           Written by:	Ben-chin Cha      Dec, 1995

(See ezcaIDL.pro)

## CASEARCH

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caSearch

     PURPOSE:
           This function searches for a list of process variable names.
           It returns 0 if successful, returns -1 if failed.

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           Status = caSearch(pvname)

     INPUTS:
          pvname: The variable for a list of process variables for which the
                  channel access search to be done.

     KEYWORD PARAMETERS:
           None.

     OUTPUTS:
           None.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           This routine will causes a channel access search to take place if
           this is the first time pvnames has been referenced.

     RESTRICTIONS:
           None.

     PROCEDURE:
           This routine uses Ezca_search_list() from the Ezca library.

     EXAMPLES:
           IDL> print,caSearch('chademoai1')
           IDL> x = ['chademoai1','chademoai2']
           IDL> status = caSearch(x)

     MODIFICATION HISTORY:
           Written by:	Ben-chin Cha      Dec, 1995
          04-11-96   bkc   Fix typo error names to name

(See ezcaIDL.pro)

## CASETMONITOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caSetMonitor

     PURPOSE:
    	This procedure sets a monitor on the specified process variable.
           This causes a channel access callback to execute whenever the value
           of that process variable changes.  Subsequent calls to caGet() after
           calling caSetMonitor will read the values provided by the callbacks,
           rather than reading from the IOC.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	status = caSetMonitor(pvname)

     INPUTS:
    	pvname: The name of the process variable on which to set the monitor.

     OUTPUTS:
           The function return value of caSetMonitor is a status value.  The
           status is 0 if the routine was successful (i.e. the process variable
           exists) and non-zero if the routine failed.

     PROCEDURE:
    	This routine uses ezcaSetMonitor(). The "type" parameter required
           by ezcaSetMonitor is the native EZCA data type as determined
           by caGetCountAndType().

     EXAMPLES:
           IDL> status = caSetMonitor('test_ao1')
           IDL> status = caGet('test_ao1', value)

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CASETRETRYCOUNT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caSetRetryCount

     PURPOSE:
    	This procedure sets the value of the EZCA RetryCount parameter.
           In conjunction with the EZCA Timeout parameter it determines how
           long EZCA will try to connect to a process variable before giving up.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caSetRetryCount, retrycount

     INPUTS:
    	RetryCount: The integer retry count.

     OUTPUTS:
           None

     PROCEDURE:
    	This routine uses ezcaSetRetryCount().

     EXAMPLES:
           IDL> caSetRetryCount, 100

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CASETTIMEOUT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caSetTimeout

     PURPOSE:
    	This procedure sets the value of the EZCA Timeout parameter. This
           value determines the time parameter passed to ca_pend_io() in EZCA.
           In conjunction with the EZCA RetryCount parameter it determines how
           long EZCA will try to connect to a process variable before giving up.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caSetTimeout, timeout

     INPUTS:
    	Timeout:  The timeout value in seconds (floating point).

     OUTPUTS:
           None

     PROCEDURE:
    	This routine uses ezcaSetTimeout().

     EXAMPLES:
           IDL> caSetTimeout, .001

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CASTARTGROUP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caStartGroup

     PURPOSE:
    	This procedure starts an "asynchronous group".  Within an asynchronous
           group all calls to caGet and caPut are asynchronous, i.e. they queue
           a request and return immediately without waiting for a reply from
           the channel access servers. Calling caEndGroup causes the queue to be
           flushed and waits for the replies. The use of asynchronous
           groups can greatly improve the efficiency of channel access. The user
           must be aware of the restrictions on caGet outlined under the
           description of that routine.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caStartGroup

     INPUTS:
    	None.

     OUTPUTS:
           None

     COMMON BLOCKS:
           EZCA_COMMON contains a flag (ingroup) which indicates if we
           are currently in an asynchronous group. This routine sets that flag.

     PROCEDURE:
    	This routine uses ezcaStartGroup().

     EXAMPLES:
           IDL> caStartGroup
           IDL> status = caget('test_ao1.SCAN', scan)
           IDL> status = caget('test_mca1.ERTM', ertm)
           IDL> ; Print out values - they will be zero.
           IDL> help, scan, ertm
           IDL> status = caEndGroup()
           IDL> ; Print out values after executing caEndGroup, they are non-zero
           IDL> help, scan, ertm
           Output:
               SCAN            INT       =        0
               ERTM            FLOAT     =      0.000000
               SCAN            INT       =        6
               ERTM            FLOAT     =       7.10000

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CATIMESTAMP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caTimeStamp

     PURPOSE:
           This function returns the time stamp of corresponding value for
           the specified record name.

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	string = caTimeStamp(pvname)

     INPUTS:
           pvname:	The name of the process variable for which the timestamp is to
                   be returned.

     KEYWORD PARAMETERS:
           None.

     OUTPUTS:
    	string:  The function returns the time stamp string for the requested
                    PV name.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
    	This routine will causes a channel access search to take place if
           this is the first time this process variable has been referenced.

     RESTRICTIONS:
           Only single PV name is allowed in input.

     PROCEDURE:
    	This routine uses Ezca_timeStamp() from the Ezca library.

     EXAMPLES:
           IDL> print,caTimeStamp('chademoai1')

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha      Dec, 1995

(See ezcaIDL.pro)

## CATRACE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caTrace

     PURPOSE:
    	This procedure turns the EZCA trace flag on or off. Turning on
           the trace flag prints lots of information which is mainly useful
           to developers.  Setting the trace flag results in less
           verbose output than setting the debug flag (see caDebug).

     CATEGORY:
    	EPICS Channel Access Interface

     CALLING SEQUENCE:
    	caTrace, state

     INPUTS:
    	state:  state=1 turns trace on, state=0 turns trace off.

     OUTPUTS:
           None

     PROCEDURE:
    	This routine uses ezcaTraceOn() and ezcaTraceOff().

     EXAMPLES:
           IDL> caTrace, 1     ;Turn on trace
           setting Trace
           IDL> status = caGet('test_ao1', value)
           ca_pend_event(0.000010)
           find_channel() found >test_ao1<
           get_channel(): was able to find_channel()
           ca_pend_event(0.000010)
           ...
           ...
           IDL> caTrace, 0     ; Turn off trace

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers
    	June 28, 1995

(See ezcaIDL.pro)

## CAVERSION

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           caVersion

     PURPOSE:
           This function returns the string of current version information
           about ezcaIDL

     CATEGORY:
           EPICS Channel Access Interface

     CALLING SEQUENCE:
           string = caVersion()

     INPUTS:
           None.

     OUTPUTS:
           Return the string which gives the version information about
           ezcaIDL, ezca, Ezca, and EPICS base verion number.

     PROCEDURE:
    	This routine uses Ezca_version() from the Ezca library.

     EXAMPLE:
           IDL> print, caVersion()

     MODIFICATION HISTORY:
           Written by:     Ben-chin Cha   Dec, 1995

(See ezcaIDL.pro)

## CAWIDGETADJUST

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caWidgetAdjust

     PURPOSE:
           This is a general purpose routine for adjusting and monitoring a process
           variable. It creates widget which is appropriate for the data type
           of "pv", 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.

     CATEGORY:
    	EPICS channel access; IDL widgets

     CALLING SEQUENCE:
    	caWidgetAdjust, pv, font=font, min=min, max=max, label=label, $
                           group=group

     INPUTS:
    	pv:     The name of the process variable to be adjusted

     KEYWORD PARAMETERS:
    	font:   This keyword can be used to specify a font to use.

    	min:    This keyword can be used to specify a lower limit for the
                   slider widget when adjusting numeric process variables.

    	min:    This keyword can be used to specify an upper limit for the
                   slider widget when adjusting numeric process variables.

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

           group:  This 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.

     SIDE EFFECTS:
    	This routine will start channel access monitoring of this process
           variable if there are not already other widgets monitoring this
           process variable.

     PROCEDURE:
           Builds a top-level widget to adjust this process variable.

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers, July 20, 1995

(See ezcaIDLWidgets.pro)

## CAWIDGETCLEARMONITOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	caWidgetClearMonitor

     PURPOSE:
    	This function clears a channel access IDL widget monitor which was
           set with caWidgetSetMonitor

     CATEGORY:
    	EPICS channel access; IDL widgets

     CALLING SEQUENCE:
    	status = caWidgetClearMonitor(pv, widget_id)

     INPUTS:
    	pv:     The name of the process variable associated with this widget

           widget_id:  The widget ID of the widget which was called on monitors.

     OUTPUTS:
       The function return value of caWidgetClearMonitor is a status value.  The
       status is 0 if the routine was successful (i.e. the process variable exists)
       and non-zero if the routine failed.

     COMMON BLOCKS:
    	caWidgetCommon:

     SIDE EFFECTS:
    	This routine will stop channel access monitoring of this process
           variable if there are no other widgets monitoring this process variable.
    	this entry.

     PROCEDURE:
    	If this is the last widget monitoring this process variable then
           caClearMonitor is called.

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers, July 20, 1995

(See ezcaIDLWidgets.pro)

## CAWIDGETSETMONITOR

[Previous Routine] [List of Routines]

     NAME:
    	caWidgetSetMonitor

     PURPOSE:
    	This function establishes a channel access monitor on a process
           variable.  It causes a widget event for widget_id to be generated
           whenever a monitor arrives for that process variable.

     CATEGORY:
    	EPICS channel access; IDL widgets

     CALLING SEQUENCE:
    	status = caWidgetSetMonitor(pv, widget_id, time=time)

     INPUTS:
    	pv:     The name of the process variable to be monitored.

           widget_id:  The widget ID of the widget to be called on monitors.

     KEYWORD PARAMETERS:
    	time:	The time interval between polling to check for new monitors.
                   The default is 0.1 seconds.

     OUTPUTS:
           The function return value of caWidgetSetMonitor is a status value.
           The status is 0 if the routine was successful (i.e. the process
           variable exists) and non-zero if the routine failed.

     COMMON BLOCKS:
    	caWidgetCommon:

     SIDE EFFECTS:
    	This routine will start channel access monitoring of this process
           variable if there are not already other widgets monitoring this
           process variable.

     PROCEDURE:
           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(pv) to determine
           whether a channel access monitor has arrived for "pv". 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.

     MODIFICATION HISTORY:
     	Written by:	Mark Rivers, July 20, 1995

(See ezcaIDLWidgets.pro)