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:
<1994>
1995
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:
<1994>
1995
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
|