From 3e782f02200e4a6061db4c5e8fec2421d0cfdfe8 Mon Sep 17 00:00:00 2001
From: Jeff Hill <johill@lanl.gov>
Date: Wed, 8 Jul 2009 23:29:51 +0000
Subject: [PATCH] test for mantis 285

---
 src/ca/CAref.html | 90 ++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 69 insertions(+), 21 deletions(-)

diff --git a/src/ca/CAref.html b/src/ca/CAref.html
index 3248f6fe3..878e1fb39 100644
--- a/src/ca/CAref.html
+++ b/src/ca/CAref.html
@@ -154,6 +154,8 @@ $Date$</span></small></p>
   <li><a href="#ca_create_channel">create a channel</a></li>
   <li><a href="#ca_clear_channel">delete a channel</a></li>
   <li><a href="#ca_put">write to a channel</a></li>
+  <li><a href="#ca_put">write to a channel and wait for initiated activities to
+    complete</a></li>
   <li><a href="#ca_get">read from a channel</a></li>
   <li><a href="#ca_add_event">subscribe for state change updates</a></li>
   <li><a href="#ca_clear_event">cancel a subscription</a></li>
@@ -171,13 +173,17 @@ $Date$</span></small></p>
 <ul>
   <li><a href="#ca_add_exception_event">ca_add_exception_event</a></li>
   <li><a href="#ca_add_fd_">ca_add_fd_registration</a></li>
+  <li><a href="#ca_get">ca_array_get</a></li>
+  <li><a href="#ca_get">ca_array_get_callback</a></li>
+  <li><a href="#ca_put">ca_array_put</a></li>
+  <li><a href="#ca_put">ca_array_put_callback</a></li>
   <li><a href="#ca_attach_context">ca_attach_context </a></li>
   <li><a href="#ca_clear_channel">ca_clear_channel</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_context_create">ca_context_create</a></li>
   <li><a href="#ca_context_destroy">ca_context_destroy</a></li>
-  <li><a href="#ca_client_status">ca_context_status</a></li>
+  <li><a href="CAref.html#ca_client_status">ca_context_status</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>
@@ -187,6 +193,7 @@ $Date$</span></small></p>
   <li><a href="#L6925">ca_field_type</a></li>
   <li><a href="#ca_flush_io">ca_flush_io</a></li>
   <li><a href="#ca_get">ca_get</a></li>
+  <li><a href="#ca_get">ca_get_callback</a></li>
   <li><a href="#L6927">ca_host_name</a></li>
   <li><a href="#L6929">ca_message</a></li>
   <li><a href="#L6931">ca_name</a></li>
@@ -203,8 +210,8 @@ $Date$</span></small></p>
   <li><a href="#ca_sg_block">ca_sg_block</a></li>
   <li><a href="#ca_sg_create">ca_sg_create</a></li>
   <li><a href="#ca_sg_delete">ca_sg_delete</a></li>
-  <li><a href="#ca_sg_get">ca_sg_get</a></li>
-  <li><a href="#ca_sg_put">ca_sg_put</a></li>
+  <li><a href="#ca_sg_get">ca_sg_array_get</a></li>
+  <li><a href="#ca_sg_put">ca_sg_array_put</a></li>
   <li><a href="#ca_sg_reset">ca_sg_reset</a></li>
   <li><a href="#ca_sg_test">ca_sg_test</a></li>
   <li><a href="#ca_state">ca_state</a></li>
@@ -2574,18 +2581,20 @@ int ca_array_put_callback ( chtype TYPE,
 
 <p>When ca_array_put  or ca_put are invoked the client will receive no response
 unless the request can not be fulfilled in the server. If unsuccessful an
-exception handler is run on the client side. If a connection is lost and then
-resumed outstanding ca_array_put  or ca_put  requests are not automatically
-reissued following reconnect, and no additional notification are provided to
-the user for each put request.</p>
+exception handler is run on the client side. </p>
 
 <p>When ca_array_put_callback are invoked the user supplied asynchronous call
-back is called only after the initiated write operation and all actions
-resulting from the initiating write operation complete. If unsuccessful the
-call back function is invoked indicating bad status. If the channel disconnects
-before a put callback request can be completed, then the client's call back
-function is called with bad status, but this does not guarantee that the server
-did not receive and process the request before the disconnect.</p>
+back is called only after the initiated write operation, and all actions
+resulting from the initiating write operation, complete.</p>
+
+<p>If unsuccessful the call back function is invoked indicating failure status.
+</p>
+
+<p>If the channel disconnects before a put callback request can be completed,
+then the client's call back function is called with failure status, but this
+does not guarantee that the server did not receive and process the request
+before the disconnect. If a connection is lost and then resumed outstanding ca
+put requests are not automatically reissued following reconnect.</p>
 
 <p>All of these functions return ECA_DISCONN if the channel is currently
 disconnected.</p>
@@ -2594,6 +2603,32 @@ disconnected.</p>
 until one of ca_flush_io, ca_pend_io, ca_pend_event, or ca_sg_pend are called.
 This allows several requests to be efficiently combined into one message.</p>
 
+<h4>Description (IOC Database Specific)</h4>
+
+<p>A CA put request causes the record to process if the record's SCAN field is
+set to passive, and the field being written has it's process passive attribute
+set to true. If such a record is already processing when a put request is
+initiated the specified field is written immediately, and the record is
+scheduled to process again as soon as it finishes processing. Earlier instances
+of multiple put requests initiated while the record is being processing may be
+discarded, but the last put request initiated is always written and
+processed.</p>
+
+<p>A CA put <span style="font-style: italic;">callback</span> request causes
+the record to process if the record's SCAN field is set to passive, and the
+field being written has it's process passive attribute set to true. For such a
+record, the user's put callback function is not called until after the record,
+and any records that the record links to, finish processing. If such a record
+is already processing when a put <span
+style="font-style: italic;">callback</span> request is initiated the put <span
+style="font-style: italic;">callback</span> request is postponed until the
+record, and any records it links to, finish processing.</p>
+
+<p>If the record's SCAN field is not set to passive, or the field being written
+has it's process passive attribute set to false then the CA put or CA put
+callback request cause the specified field to be immediately written, but they
+do not cause the record to be processed.</p>
+
 <h4>Arguments</h4>
 <dl>
   <dt><code>TYPE</code></dt>
@@ -2649,6 +2684,8 @@ ca_flush_io()
 
 <p>ca_pend_event()</p>
 
+<p>ca_sg_array_put()</p>
+
 <h3><a name="ca_get"></a><code>ca_get()</code></h3>
 <pre><code>#include &lt;cadef.h&gt;
 int ca_get ( chtype TYPE, 
@@ -2668,14 +2705,14 @@ int ca_array_get_callback ( chtype TYPE, unsigned long COUNT,
 
 <p>When ca_get or ca_array_get are invoked the returned channel value cant be
 assumed to be stable in the application supplied buffer until after ECA_NORMAL
-is returned from ca_pend_io. If a connection is lost outstanding get requests
-are not automatically reissued following reconnect.</p>
+is returned from ca_pend_io. If a connection is lost outstanding ca get
+requests are not automatically reissued following reconnect.</p>
 When ca_get_callback or ca_array_get_callback are invoked a value is read
 from the channel and then the user's callback is invoked with a pointer to the
 retrieved value. Note that ca_pend_io will not block for the delivery of values
-requested by ca_get_callback. If the channel disconnects before a get callback
-request can be completed, then the clients call back function is called with
-bad status. 
+requested by ca_get_callback. If the channel disconnects before a ca get
+callback request can be completed, then the clients call back function is
+called with failure status. 
 
 <p>All of these functions return ECA_DISCONN if the channel is currently
 disconnected.</p>
@@ -2685,6 +2722,13 @@ until one of ca_flush_io, ca_pend_io, ca_pend_event, or ca_sg_pend are called.
 This allows several requests to be efficiently sent over the network in one
 message.</p>
 
+<h4>Description (IOC Database Specific)</h4>
+
+<p>A CA get or CA get callback request causes the record's field to be read
+immediately independent of whether the record is currently being processed or
+not. There is currently no mechanism in place to cause a record to be processed
+when a CA get request is initiated.</p>
+
 <h4>Example</h4>
 
 <p>See caExample.c in the example application created by makeBaseApp.pl.</p>
@@ -2744,6 +2788,8 @@ ca_pend_io()
 
 <p>ca_pend_event()</p>
 
+<p>ca_sg_array_get()</p>
+
 <h3><a name="ca_add_event"></a><code>ca_create_subscription()</code></h3>
 <pre><code>#include &lt;cadef.h&gt;
 typedef void ( *pCallBack ) (
@@ -3264,7 +3310,7 @@ SEVCHK ( status, "failed to install my printf handler" );</code></pre>
 <h3><code><a name="ca_replace">ca_replace_access_rights_event()</a></code></h3>
 <pre><code>#include &lt;cadef.h&gt;
 typedef void ( *pCallBack )( struct access_rights_handler_args );
-int ca_replace ( chid CHAN, pCallBack PFUNC );</code></pre>
+int ca_replace_access_rights_event ( chid CHAN, pCallBack PFUNC );</code></pre>
 
 <h4>Description</h4>
 
@@ -3834,7 +3880,8 @@ int ca_sg_array_put ( CA_SYNC_GID GID, chtype TYPE,
         unsigned long COUNT, chid CHID, void *PVALUE );</code></pre>
 
 <p>Write a value, or array of values, to a channel and increment the
-outstanding request count of a synchronous group.</p>
+outstanding request count of a synchronous group. The ca_sg_array_put
+functionality is implemented using ca_array_put_callback.</p>
 
 <p>All remote operation requests such as the above are accumulated (buffered)
 and not forwarded to the server until one of ca_flush_io(), ca_pend_io(),
@@ -3898,7 +3945,8 @@ int ca_sg_array_get ( CA_SYNC_GID GID,
 <h4>Description</h4>
 
 <p>Read a value from a channel and increment the outstanding request count of a
-synchronous group.</p>
+synchronous group. The ca_sg_array_get functionality is implemented using
+ca_array_get_callback.</p>
 
 <p>The values written into your program's variables by ca_sg_get should not be
 referenced by your program until ECA_NORMAL has been received from ca_sg_block