EPICS Controls Argonne National Laboratory

Experimental Physics and
Industrial Control System

<19941995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  2011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024  Index <19941995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  2011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 
<== Date ==> <== Thread ==>

Subject: EZCA
From: [email protected] (Nicholas T. Karonis)
Date: Fri, 5 Aug 1994 08:51:02 -0600
    I was given the responsibility for providing an easy to use interface to
Channel Access.  To that end, I organized a task force (EZ-CA Task Force)
to hammer out the specification for that interface.  Below are our findings.

Nick Karonis
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
		    Findings of the EZ-CA Task Force
		    --------------------------------

Members:
-------
    Ned Arnold
    Mike Borland
    Ben-Chin Cha
    Bob Daily
    Nick Karonis
    Marty Kraimer
    Mark Rivers
    Claude Saunders
    Jackie Wallis


Goal:
----
    This task force is responsible for producing an Application Program 
Interface (API) to Channel Access (CA), one that is easier to use than the
current CA API.  In doing so, we recognize that the new API will not provide
all of CA's functionality and efficiency.  
    In making an easy to use API, we will strive to keep the number of functions
down to a minimum, i.e., we will strive to generate an API that can be entirely 
explained on a ``One Page User's Guide''.  Although this is not necessarily 
meant to be taken literally, it serves as a realistic goal.
    Users of this system should never need to look at the CA documentation nor
ever have to refer to header files, e.g., to see what fields in a structure
they need to be concerned with.

Supported Data Types:
---------------------
    ezcaByte and ezcaString
    ezcaShort and ezcaLong 
    ezcaFloat and ezcaDouble

Features and Description of the API:
-----------------------------------
    - We will not require the users to call to an initialization nor cleanup 
routine.

    - Get and Put.  The new API will have get and put functions.  These will 
be blocking operations.  Additionally, the API will support blocking synchronous
group gets and puts.  

    - Return status.  All routines will return a status indicating the success
or failure of the call.  In the case of a failure, the return status will
reflect the first problem encountered.  This is also true of group calls.
Once an anomaly is encountered, the function will return immediately.  This 
implies that there may have been other problems had execution continued.  
If the user wishes to investigate the problem in more detail, a function 
similar to perror() will be provided that will print a detailed description of 
the last ezca call.

    - "perror()" facility.  Provide two functions, one that prints to a stderr 
and one that places same message into a memory buffer.

    - Sync groups.  To be handled in the following way:
	    ezcaStartGroup();
	       .               -+
	    ezcaGet(...);       |
	       .                +--- arbitrary combination of gets and puts.
	    ezcaPut(...);       |    note that gets and puts here have the 
	       .               -+    syntax had they not appeared in the group.
	    ezcaEndGroup();
This no longer requires homogeneous data types for sync groups, allows users
to intermix gets and puts, and allows users to perform vector gets and puts.

    - This API should be available on IOCs as well as workstations.

    - This API should be able to co-exist with DevLib, e.g., no problem
in calling ca_task_initialize() twice in the same program, etc.

    - There will be one user-configurable global parameter, timeout.

    - Users will be able specify how their ezcaGet()s will work.  They will be 
able to identify which pvars should be retrieved via a monitor and which are 
not (the default is not) via  ezcaMonitor(pvar).  Those pvars identified in 
this manner will have a monitor established on them immediately and subsequent 
gets will retrieve the monitor value.  All others will perform an explicit 
ca_get().  

    - The API will provide a function, ezcaPvToChid(), that converts pvnames 
to chids.  This is intended to provide a quick and easy way to move into direct 
channel access calls.

    - The API will *not* support establishing callbacks for monitors nor 
callbacks for connection management.  Users requiring these functionalities
are required to call ezcaPvToChid() and then the explicit channel access
calls.

Functions of the API:
---------------------
    int ezcaGet(char *pvname, char type, int nelem, void *buff)
    int ezcaPut(char *pvname, char type, int nelem, void *buff)

    int ezcaStartGroup()
    int ezcaEndGroup()

    void ezcaAutoErrorMessageOn()
    void ezcaAutoErrorMessageOff()

    void ezcaSetMonitor(char *pvname, char type)
    void ezcaClearMonitor(char *pvname, char type)
    int ezcaNewMonitorValue(char *pvname)

    void ezcaPerror(char *msg) 
    void ezcaGetErrorString(char *msg, void **)
    void ezcaFreeErrorString(void *)

    void ezcaPvToChid(char *pvname, CHID *chid) /* #include <cadef.h> */
    void ezcaSetTimeout(float secs)
    void ezcaDelay(float secs)

    int ezcaGetUnits(char *pvname, char *units)
    int ezcaGetNelem(char *pvname, int *nelem)
    int ezcaGetPrecision(char *pvname, short *precision)
    int ezcaGetGraphicLimits(char *pvname, double *low, double *high)
    int ezcaGetControlLimits(char *pvname, double *low, double *high)
    int ezcaGetStatus(char *pvname, TS_STAMP *timestamp, short *alarm_status, 
	short *alarm_severity) /* #include <tsDefs.h> */
    int ezcaGetWithStatus(char *pvname, char type, int nelem, void *buff, 
	TS_STAMP *timestamp, short *alarm_status, 
	short *alarm_severity) /* #include <tsDefs.h> */

    Notes: 
	- ezcaGet() never forces processing, unlike the ezcaPut(), so 
	    rc will never reflect any problems associated with processing.
	- ezcaPut() is a put_notify(), meaning wait until record processing
	    chain is done.
	- the intention is that for every ezcaStartGroup() there is a matching
	    ezcaEndGroup().  
	- ezcaEndGroup() will return the first error condition from within the 
	    group.  Users can use ezcaPerror() for a more detailed description 
	    in the event that something went wrong.
	- when ezcaNewMonitorValue() is called on a non-monitored pvar, it
	    will always return a non-zero value.
	- ezcaPerror() and ezcaGetErrorString().  Each reveals the error string
	    associated with the last EZ-CA call.  If msg is non-NULL, it appears
	    before the error message generated by EZ-CA.  
	    ezcaPerror() prints the message to stderr.
	    ezcaGetErrorString() allocates sufficient memory, places the error 
	    message in there, and returns a pointer to the memory to the caller.
	    The caller is thereby responsible for freeing up the memory with
	    a subsequent call to ezcaFreeErrorString().
	- ezcaDelay().  This function provides the users an opportunity to 
	    explicitly check any monitors that they have established.  Users
	    of EZ-CA that established monitors and went into relatively long
	    processing loops without any EZ-CA calls ran the risk of losing
	    potentially valuable data as a result of not allowing the monitors
	    to be processed.  Typically this function will be called with a
	    very small value (0.0001).  It will simply call ca_pend_event().
	- ezcaGetWithStatus() is an extension of ezcaGet()
	- ezcaGetStatus() and ezcaGetWithStatus() retrieve a timestamp and 
	    places it in a special structure, TS_STAMP.  Access to that 
	    structure should be provided via routines in libCom.a.

Navigate by Date:
Prev: Granville-Phillips VG-307 vs GPIB Bill Brown
Next: N.I. GPIB-1014 hack - was Granville-Phillips VG-307 vs GPIB Bill Brown
Index: <19941995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  2011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 
Navigate by Thread:
Prev: Granville-Phillips VG-307 vs GPIB Bill Brown
Next: EZCA J.F. Gournay
Index: <19941995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  2011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 
ANJ, 10 Aug 2010 Valid HTML 4.01! · Home · News · About · Base · Modules · Extensions · Distributions · Download ·
· Search · EPICS V4 · IRMIS · Talk · Bugs · Documents · Links · Licensing ·