From 676d2103402817eb8b067e9c02db5ad6e0c6064d Mon Sep 17 00:00:00 2001
From: Jeff Hill <johill@lanl.gov>
Date: Wed, 23 Apr 2003 00:41:15 +0000
Subject: [PATCH] depricated ca_add_event

---
 src/ca/CAref.html  |  43 +++++++++-------
 src/ca/access.cpp  |  34 ++++++++-----
 src/ca/cadef.h     | 121 ++++++++++++++-------------------------------
 src/ca/oldAccess.h |   7 ++-
 4 files changed, 90 insertions(+), 115 deletions(-)

diff --git a/src/ca/CAref.html b/src/ca/CAref.html
index eb1bae512..818bf68d9 100644
--- a/src/ca/CAref.html
+++ b/src/ca/CAref.html
@@ -127,15 +127,15 @@ height="31" width="88"></a></p>
 
 <h3><a href="#Function Call Reference">Function Call Interface Index</a></h3>
 <ul>
-  <li><a href="#ca_add_event">ca_add_event</a></li>
   <li><a href="#ca_add_exception_event">ca_add_exception_event</a></li>
   <li><a href="#ca_attach_context">ca_attach_context&nbsp;</a></li>
   <li><a href="#ca_clear_channel">ca_clear_channel</a></li>
-  <li><a href="#ca_clear_event">ca_clear_event</a></li>
+  <li><a href="#ca_clear_event">ca_clear_subscription</a></li>
   <li><a href="#ca_client_status">ca_client_status</a></li>
   <li><a href="#ca_client_status">ca_context_status</a></li>
   <li><a href="#ca_context_destroy">ca_context_destroy</a></li>
   <li><a href="#ca_create_channel">ca_create_channel</a></li>
+  <li><a href="#ca_add_event">ca_create_subscription</a></li>
   <li><a href="#ca_current_context">ca_current_context</a></li>
   <li><a href="#ca_dump_db">ca_dump_dbr()</a></li>
   <li><a href="#ca_element_count">ca_element_count</a></li>
@@ -176,6 +176,8 @@ height="31" width="88"></a></p>
 
 <h3>Deprecated Function Call Interface Function Index</h3>
 <ul>
+  <li><a href="#ca_add_event">ca_add_event</a></li>
+  <li><a href="#ca_clear_event">ca_clear_event</a></li>
   <li><a href="#ca_create_channel">ca_search</a></li>
   <li><a href="#ca_create_channel">ca_search_and_connect</a></li>
   <li><a href="#ca_context_destroy">ca_task_exit</a></li>
@@ -1250,6 +1252,22 @@ library. When the CA client library invokes a user's&nbsp;call back function
 it will always wait for the current callback to complete prior to executing
 another call back function.</p>
 
+<p>To set up a traditional single threaded client you will need code like
+this (see <a href="#ca_context_create">ca_context_create</a> and <a
+href="#Client2">CA Client Contexts and Application Specific Auxiliary
+Threads</a>) .</p>
+
+<p><code>SEVCHK ( ca_context_create(ca_disable_preemptive_callback ),
+"application pdq calling ca_context_create" );</code></p>
+
+<p>To set up a preemptive callback enabled CA client context you will need
+code like this (see <a href="#ca_context_create">ca_context_create</a>and <a
+href="#Client2">CA Client Contexts and Application Specific Auxiliary
+Threads</a>) .</p>
+
+<p><code>SEVCHK ( ca_context_create(ca_enable_preemptive_callback ),
+"application pdq calling ca_context_create" );</code></p>
+
 <h3><a name="Client2">CA Client Contexts and Application Specific Auxiliary
 Threads</a></h3>
 
@@ -1725,23 +1743,14 @@ ca_pend_io()
 
 <p>ca_pend_event()</p>
 
-<h3><a name="ca_add_event"></a><code>ca_add_event()</code></h3>
+<h3><a name="ca_add_event"></a><code>ca_create_subscription()</code></h3>
 <pre><code>#include &lt;cadef.h&gt;
 typedef void ( *pCallBack ) (
         struct event_handler_args );
-int ca_add_event( chtype TYPE, chid CHID, 
-        pCallBack USERFUNC, void *USERARG, 
-        evid *PEVID); 
-int ca_add_array_event( chtype TYPE,
-        unsigned long COUNT, chid CHID,
-        pCallBack USERFUNC, void *USERARG, 
-        double RESERVED, double RESERVED, 
-        double RESERVED, evid *PEVID );
-int ca_add_masked_array_event ( chtype TYPE, 
+int ca_create_subscription ( chtype TYPE, 
         unsigned long COUNT, chid CHID, 
-        pCallBack USERFUNC, void *USERARG, 
-        double RESERVED, double RESERVED, double RESERVED, 
-        evid *PEVID, unsigned long MASK );</code></pre>
+        unsigned long MASK, pCallBack USERFUNC, void *USERARG, 
+        evid *PEVID );</code></pre>
 
 <h4>Description</h4>
 
@@ -1861,9 +1870,9 @@ ca_pend_event()
 
 <p>ca_flush_io()</p>
 
-<h3><a name="ca_clear_event"></a><code>ca_clear_event()</code></h3>
+<h3><a name="ca_clear_event"></a><code>ca_clear_subscription()</code></h3>
 <pre><code>#include &lt;cadef.h&gt;
-int ca_clear_event ( evid EVID );</code></pre>
+int ca_clear_subscription ( evid EVID );</code></pre>
 
 <h4>Description</h4>
 
diff --git a/src/ca/access.cpp b/src/ca/access.cpp
index 45089e6e7..997cf7af5 100644
--- a/src/ca/access.cpp
+++ b/src/ca/access.cpp
@@ -650,15 +650,10 @@ int epicsShareAPI ca_add_exception_event ( caExceptionHandler *pfunc, void *arg
     return ECA_NORMAL;
 }
 
-/*
- *  ca_add_masked_array_event
- */
-// extern "C"
-int epicsShareAPI ca_add_masked_array_event ( 
+int epicsShareAPI ca_create_subscription ( 
         chtype type, arrayElementCount count, chid pChan, 
-        caEventCallBackFunc *pCallBack, void *pCallBackArg, 
-        ca_real, ca_real, ca_real, 
-        evid *monixptr, long mask )
+        long mask, caEventCallBackFunc * pCallBack, void * pCallBackArg, 
+        evid * monixptr )
 {
     if ( type < 0 ) {
         return ECA_BADTYPE;
@@ -731,10 +726,19 @@ int epicsShareAPI ca_add_masked_array_event (
 }
 
 /*
- *  ca_clear_event ()
+ *  ca_add_masked_array_event
  */
-// extern "C"
-int epicsShareAPI ca_clear_event ( evid pMon )
+int epicsShareAPI ca_add_masked_array_event ( 
+        chtype type, arrayElementCount count, chid pChan, 
+        caEventCallBackFunc *pCallBack, void *pCallBackArg, 
+        ca_real, ca_real, ca_real, 
+        evid *monixptr, long mask )
+{
+    return ca_create_subscription ( type, count, pChan, mask,
+        pCallBack, pCallBackArg, monixptr );
+}
+
+epicsShareFunc int epicsShareAPI ca_clear_subscription ( evid pMon )
 {
     oldChannelNotify & chan = pMon->channel ();
     ca_client_context & cac = chan.getClientCtx ();
@@ -743,6 +747,14 @@ int epicsShareAPI ca_clear_event ( evid pMon )
     return ECA_NORMAL;
 }
 
+/*
+ *  ca_clear_event ()
+ */
+int epicsShareAPI ca_clear_event ( evid pMon )
+{
+    return ca_clear_subscription ( pMon );
+}
+
 // extern "C"
 chid epicsShareAPI ca_evid_to_chid ( evid pMon )
 {
diff --git a/src/ca/cadef.h b/src/ca/cadef.h
index 135353a81..9356b8c32 100644
--- a/src/ca/cadef.h
+++ b/src/ca/cadef.h
@@ -223,42 +223,6 @@ epicsShareFunc int epicsShareAPI ca_context_create (enum ca_preemptive_callback_
 epicsShareFunc int epicsShareAPI ca_task_exit (void);
 epicsShareFunc void epicsShareAPI ca_context_destroy (void);
 
-/************************************************************************
- * anachronistic entry points                                           *
- * **** Fetching a value while searching no longer supported****        *
- ************************************************************************/
-#define ca_build_channel(NAME,XXXXX,CHIDPTR,YYYYY)\
-ca_build_and_connect(NAME, XXXXX, 1, CHIDPTR, YYYYY, 0, 0)
-
-#define ca_array_build(NAME,XXXXX, ZZZZZZ, CHIDPTR,YYYYY)\
-ca_build_and_connect(NAME, XXXXX, ZZZZZZ, CHIDPTR, YYYYY, 0, 0)
-
-epicsShareFunc int epicsShareAPI ca_build_and_connect
-(
-     const char         *pChanName, 
-     chtype             , /* pass TYPENOTCONN */
-     unsigned long      , /* pass 0 */
-     chid *             pChanID, 
-     void *             , /* pass NULL */
-     caCh *             pFunc,
-     void *             pArg
-);
-
-#define ca_search(pChanName, pChanID)\
-ca_search_and_connect (pChanName, pChanID, 0, 0)
-
-epicsShareFunc int epicsShareAPI ca_search_and_connect
-(
-     const char     *pChanName, 
-     chid           *pChanID, 
-     caCh           *pFunc, 
-     void           *pArg
-);
-
-/************************************************************************/
-/*  End of anachronistic entry points                                   */
-/************************************************************************/
-
 typedef unsigned capri; 
 #define CA_PRIORITY_MAX 99
 #define CA_PRIORITY_MIN 0
@@ -543,76 +507,44 @@ epicsShareFunc int epicsShareAPI ca_array_get_callback
 /************************************************************************/
 
 /*
- * ca_add_event ()
- *
- * assumes "delta" info comes from the database or defaults
+ * ca_create_subscription ()
  *
  * type     R   data type from db_access.h
  * count    R   array element count
  * chan     R   channel identifier  
- * pFunc    R   pointer to call-back function
- * pArg     R   copy of this pointer passed to pFunc
- * pEventID W   event id written at specified address
- */
-#define ca_add_event(type,chan,pFunc,pArg,pEventID)\
-ca_add_array_event(type,1u,chan,pFunc,pArg,0.0,0.0,0.0,pEventID)
-
-
-/*  Sets both P_DELTA and M_DELTA below to argument DELTA       */
-#define ca_add_delta_event(TYPE,CHID,ENTRY,ARG,DELTA,EVID)\
-    ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,DELTA,DELTA,0.0,EVID)
-
-#define ca_add_general_event(TYPE,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\
-ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)
-
-#define ca_add_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\
-ca_add_masked_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID, DBE_VALUE | DBE_ALARM)
-
-/*
- * ca_add_masked_array_event ()
- *
- * type     R   data type from db_access.h
- * count    R   array element count
- * chan     R   channel identifier  
- * pFunc    R   pointer to call-back function
- * pArg     R   copy of this pointer passed to pFunc
- * p_delta  R   not currently used (set to 0.0) 
- * n_delta  R   not currently used (set to 0.0)
- * timeout  R   not currently used (set to 0.0)
- * pEventID W   event id written at specified address
  * mask     R   event mask - one of {DBE_VALUE, DBE_ALARM, DBE_LOG}
+ * pFunc    R   pointer to call-back function
+ * pArg     R   copy of this pointer passed to pFunc
+ * pEventID W   event id written at specified address
  */
-epicsShareFunc int epicsShareAPI ca_add_masked_array_event
+epicsShareFunc int epicsShareAPI ca_create_subscription
 (
      chtype                 type,   
      unsigned long          count,   
      chid                   chanId,
+     long                   mask,
      caEventCallBackFunc *  pFunc,
      void *                 pArg,
-     ca_real                p_delta,
-     ca_real                n_delta,
-     ca_real                timeout,
-     evid *                 pEventID, 
-     long                   mask
+     evid *                 pEventID
 );
 
-epicsShareFunc chid epicsShareAPI ca_evid_to_chid ( evid id );
-
 /************************************************************************/
 /*  Remove a function from a list of those specified to run             */
 /*  whenever significant changes occur to a channel                     */
 /*                                                                      */
 /************************************************************************/
 /*
- * ca_clear_event()
+ * ca_clear_subscription()
  *
  * eventID  R   event id
  */
-epicsShareFunc int epicsShareAPI ca_clear_event
+epicsShareFunc int epicsShareAPI ca_clear_subscription
 (
      evid eventID
 );
 
+epicsShareFunc chid epicsShareAPI ca_evid_to_chid ( evid id );
+
 
 /************************************************************************/
 /*                                                                      */
@@ -940,7 +872,6 @@ epicsShareFunc unsigned epicsShareAPI ca_search_attempts (chid chan);
 epicsShareFunc double epicsShareAPI ca_beacon_period (chid chan);
 epicsShareFunc double epicsShareAPI ca_receive_watchdog_delay (chid chan);
 
-
 /*
  * used when an auxillary thread needs to join a CA client context started
  * by another thread
@@ -952,13 +883,35 @@ epicsShareFunc int epicsShareAPI ca_attach_context ( struct ca_client_context *
 epicsShareFunc int epicsShareAPI ca_client_status ( unsigned level );
 epicsShareFunc int epicsShareAPI ca_context_status ( struct ca_client_context *, unsigned level );
 
-
 /*
  * deprecated
  */
+#define ca_build_channel(NAME,XXXXX,CHIDPTR,YYYYY)\
+ca_build_and_connect(NAME, XXXXX, 1, CHIDPTR, YYYYY, 0, 0)
+#define ca_array_build(NAME,XXXXX, ZZZZZZ, CHIDPTR,YYYYY)\
+ca_build_and_connect(NAME, XXXXX, ZZZZZZ, CHIDPTR, YYYYY, 0, 0)
+epicsShareFunc int epicsShareAPI ca_build_and_connect
+    ( const char *pChanName, chtype, unsigned long, 
+    chid * pChanID, void *, caCh * pFunc, void * pArg );
+#define ca_search(pChanName, pChanID)\
+ca_search_and_connect (pChanName, pChanID, 0, 0)
+epicsShareFunc int epicsShareAPI ca_search_and_connect
+    ( const char * pChanName, chid * pChanID, 
+    caCh *pFunc, void * pArg );
 epicsShareFunc int epicsShareAPI ca_channel_status (epicsThreadId tid);
-epicsShareFunc int epicsShareAPI ca_import (epicsThreadId tid);
-epicsShareFunc int epicsShareAPI ca_import_cancel (epicsThreadId tid);
+epicsShareFunc int epicsShareAPI ca_clear_event ( evid eventID );
+#define ca_add_event(type,chan,pFunc,pArg,pEventID)\
+ca_add_array_event(type,1u,chan,pFunc,pArg,0.0,0.0,0.0,pEventID)
+#define ca_add_delta_event(TYPE,CHID,ENTRY,ARG,DELTA,EVID)\
+    ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,DELTA,DELTA,0.0,EVID)
+#define ca_add_general_event(TYPE,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\
+ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)
+#define ca_add_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\
+ca_add_masked_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID, DBE_VALUE | DBE_ALARM)
+epicsShareFunc int epicsShareAPI ca_add_masked_array_event
+    ( chtype type, unsigned long count, chid chanId, caEventCallBackFunc * pFunc,
+        void * pArg, ca_real p_delta, ca_real n_delta, ca_real timeout,
+        evid * pEventID, long mask );
 
 /*
  * defunct
@@ -989,6 +942,8 @@ epicsShareFunc int epicsShareAPI ca_array_get ();
 epicsShareFunc int epicsShareAPI ca_array_get_callback ();
 epicsShareFunc int epicsShareAPI ca_add_masked_array_event ();
 epicsShareFunc int epicsShareAPI ca_clear_event ();
+epicsShareFunc int epicsShareAPI ca_create_subscription ();
+epicsShareFunc int epicsShareAPI ca_clear_subscription ();
 epicsShareFunc int epicsShareAPI ca_pend ();
 epicsShareFunc int epicsShareAPI ca_test_io ();
 epicsShareFunc int epicsShareAPI ca_flush_io ();
diff --git a/src/ca/oldAccess.h b/src/ca/oldAccess.h
index 81292b6b3..56bb9a9af 100644
--- a/src/ca/oldAccess.h
+++ b/src/ca/oldAccess.h
@@ -316,11 +316,10 @@ private:
     friend int epicsShareAPI ca_array_put_callback ( chtype type, 
             arrayElementCount count, chid pChan, const void *pValue, 
             caEventCallBackFunc *pfunc, void *usrarg );
-    friend int epicsShareAPI ca_add_masked_array_event ( 
+    friend int epicsShareAPI ca_create_subscription ( 
             chtype type, arrayElementCount count, chid pChan, 
-            caEventCallBackFunc *pCallBack, void *pCallBackArg, 
-            ca_real, ca_real, ca_real, 
-            evid *monixptr, long mask );
+            long mask, caEventCallBackFunc *pCallBack, void *pCallBackArg, 
+            evid *monixptr );
     friend int epicsShareAPI ca_sg_create ( CA_SYNC_GID * pgid );
     friend int epicsShareAPI ca_sg_delete ( const CA_SYNC_GID gid );
 };