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 Dec 12 12:28:55 2012.


List of Routines


Routine Descriptions

ADD_CAPENDEVENT

[Next Routine] [List of Routines]
 NAME:
	add_caPendEvent

 PURPOSE:
	This routine start an IDL widget of sending channel access 
       ca_pend_event call with the user specifyable timer interval.
       Calling this rountine is required for IDL CA sesstion EPICS 3.14.4
	otherwize many CA warning message will be printed on user's IDL
	interactive terminal. 
 
 CATEGORY:
	Widgets

 CALLING SEQUENCE:
	add_caPendEvent,timer=timer

 KEYWORD:
   timer:  Specify the timer in seconds between each ca_pend_event call
	    It defaults to 10 seconds.
 EXAMPLE:
	IDL> add_caPendEvent

(See ezcaIDLWidgets.pro)


CACHECKMONITOR

[Previous Routine] [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_ELEMENTS: 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

(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 EzcaScan 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 MAX_ENUM_STATES enum strings and they must each be
       less than MAX_STRING_SIZE 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 EzcaScan 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 EzcaScan library.  It also sets the values of three
       constants, MAX_STRING_SIZE=40, MAX_ENUM_STATES=16, and MAX_PVNAME_SIZE=128 used in other functions.
       This routine MUST be called before any other routines in this file.

 CATEGORY:
       EPICS Channel Access Interface

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

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

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

 OUTPUTS:
       None.

 COMMON BLOCKS:
       ezca_common is used to hold the values of MAX_STRING_SIZE, MAX_ENUM_STATES, and MAX_PVNAME_SIZE

 SIDE EFFECTS:
       This routine set the channel access timeout values used in the
       EzcaScan library.  This routine sets 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 EzcaScan library.

 EXAMPLES:
       IDL> caInit

 MODIFICATION HISTORY:
       Written by:     Ben-chin Cha     Dec, 1995
       27-Sep-2001   MLR   Added initializtion of contants MAX_STRING_SIZE and
                           MAX_ENUM_STATES.

(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 /CLEAR 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 single 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 circular buffer, it keeps the most
               current MAXQUEUE values in the queue buffer.

               Default Vals returned in double precision form.
     /INT      Return Vals converted to integer
     /LONG     Return Vals converted to long integer
     /BYTE     Return Vals converted to byte type
     /FLOAT    Return Vals converted to float type
     /STRING   Return Vals converted to string type

 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 PVs are monitored as double values in this function
       unless the PV is a DBR_STRING type then monitored as string type.
       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 EzcaScan 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
       04-07-99    bkc   Return monitor values specification:
                         /byte,/int,/long,/float,/string

(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 EzcaScan 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
       EzcaScan library and calls the ca_pend_event.

 RESTRICTIONS:
       Positive time must be used.

 PROCEDURE:
       This routine uses Ezca_setPendTime() from the EzcaScan 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 EzcaScan 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 EzcaScan library.

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

 PROCEDURE:
       This routine uses Ezca_setPendTime() from the EzcaScan 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.

 KEYWORD PARAMETERS:
       WAIT:   Set this flag to force caPut to wait for a channel access
               callback.  The default is not to wait for a callback, using the
               ezca function ezcaPutOldCa.  The WAIT keyword results in a
               call to ezcaPut, which uses channel access callbacks.

 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() if /WAIT is specified, and ezcaPutOldCa if
       /WAIT is not specified.  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
       Sept. 16, 1998  Mark Rivers  Added WAIT keyword, made non-callback
                                    version of caput the default

(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[m,N]:  Input data array, define m values for each N PV names. 
               The data array defined must be consistant within
               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 EzcaScan 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
       11-29-2001 bkc  If pdata is string type, convert back to string after
                       calling EzcaPutArray

(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 EzcaScan 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.
       count:  The maximum number of elements to monitor.  Default (0) is native element count

 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 EzcaScan 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 EzcaScan 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] [Next 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)


EZCAPVNAMETOBYTE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ezcaPVNameToByte

 PURPOSE:
       This function converts an array of PV names to a 2-D byte array

 CATEGORY:
       EPICS Channel Access Interface

 CALLING SEQUENCE:
       byt = ezcaPVNameToByte(Str, Num)

 INPUTS:
       Str:   A 1-D array of EPICS PV names.

 OUTPUTS:
       This function returns a 2-D byte [MAX_PVNAME_SIZE, n_elements(Str)] which
       is the input string array converted to fixed-length byte arrays.

       Num: Returns n_elements(Str) as a short integer

 COMMON BLOCKS:
       ezca_common holds the value of MAX_PVNAME_SIZE.

 EXAMPLE:
       IDL> str = ['a', 'b', 'c']
       IDL> byt = ezcaStringToByte(str, num)
       IDL> help, byt, num
       BYT             BYTE      = Array[61, 3]
       NUM             INT       =        3

 MODIFICATION HISTORY:
       Written by:   Mark Rivers, 11-Dec-2012.  This function was added and all routines
                     that previously called ezcaStringToByte for PV names were changed to use
                     this function because it allows 60 character names, rather than 40.

(See ezcaIDL.pro)


EZCASTRINGTOBYTE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ezcaStringToByte

 PURPOSE:
       This function converts an array of strings to a 2-D byte array

 CATEGORY:
       EPICS Channel Access Interface

 CALLING SEQUENCE:
       byt = ezcaStringToByte(Str, Num)

 INPUTS:
       Str:   A 1-D array of strings.  Do not use this function for EPICS PV names, use ezcaPVNameToByte below.

 OUTPUTS:
       This function returns a 2-D byte array [MAX_STRING_SIZE, n_elements(Str)] which
       is the input string array converted to fixed-length byte arrays.

       Num: Returns n_elements(Str) as a short integer

 COMMON BLOCKS:
       ezca_common holds the value of MAX_STRING_SIZE.

 EXAMPLE:
       IDL> str = ['a', 'b', 'c']
       IDL> byt = ezcaStringToByte(str, num)
       IDL> help, byt, num
       BYT             BYTE      = Array[40, 3]
       NUM             INT       =        3

 MODIFICATION HISTORY:
       Written by:   Mark Rivers, 26-Sep-2001
       MLR 28-Nov-2001  Previous version replaced null string ("") with a single
                        blank character.  This was bad, unused scan record PVs were
                        coming up unable to connect.  Removed this replacement.

(See ezcaIDL.pro)


RELEASE NOTES

[Previous Routine] [List of Routines]
 NAME:
 Release notes
   Version 2:
       Everything prior to 27-Sep-2001 when I started making release notes!
       Prior to this date there are release notes for each routine but no
       global release notes for the file.

  Version 3.0
       28-Sep-2001, Mark Rivers
           Signficant rewrite.  Changed many routines so that we no longer pass
           any string variables with CALL_EXTERNAL or LINKNLOAD.  This was done
           to simplify things, since there are now at least 4 different conventions
           for passing strings to shareable libraries (PVWAVE, IDL prior to 5.1 on
           Windows, IDL 5.1-5.4, and IDL 5.5 and later).  We now only pass byte
           arrays, not strings.  This permits a single shareable library to be used
           for any version of PV-WAVE or IDL.
           There are now 2 constants in ezca_common, MAX_STRING_SIZE and
           MAX_ENUM_STATES. These values are set to 40 and 16 respectively in
           caInit.  It is now MANDATORY to call caInit before calling any other
           routine in this file, preferably in the IDL_STARTUP file.
           Reformatted a lot of the code, and used ENDIF and ENDFOR consistently
           rather than simple END statements.
           Added support for unsigned short and unsigned long integer data types.

(See ezcaIDL.pro)