added doc for

o EPICS_CAS_INTF_ADDR_LIST
o dbr_type_to_text
o and many small clarifications

src/ca/CAref.html

@@ -151,6 +151,7 @@ height="31" width="88"></a></p>
   <li><a href="#dbr_size[]">dbr_size[]</a></li>
   <li><a href="#L6946">dbr_size_n</a></li>
   <li><a href="#dbr_value_size">dbr_value_size[]</a></li>
+  <li><a href="#dbr_type_t">dbr_type_to_text</a></li>
   <li><a href="#ca_signal">SEVCHK</a></li>
 </ul>
 
@@ -653,6 +654,11 @@ request transportation of large arrays.</p>
       <td>{N.N.N.NN.N.N.N:P...}</td>
       <td>&lt;none&gt;</td>
     </tr>
+    <tr>
+      <td>EPICS_CAS_IGNORE_ADDR_LIST</td>
+      <td>{N.N.N.NN.N.N.N:P...}</td>
+      <td>&lt;none&gt;</td>
+    </tr>
   </tbody>
 </table>
 
@@ -682,10 +688,10 @@ point-to-point interfaces found in the host.</p>
 <p>If EPICS_CAS_BEACON_ADDR_LIST is defined then its contents will be used to
 augment this list. Individual entries in EPICS_CAS_BEACON_ADDR_LIST may
 override the destination port number if ":nnn" follows the host name or IP
-address there. <sup>1</sup>Alternatively, if EPICS_CAS_BEACON_ADDR_LIST is
-not defined, EPICS_CA_ADDR_LIST is defined, and EPICS_CAS_INTF_ADDR_LIST is
-not defined, then the contents of EPICS_CA_ADDR_LIST will be used to augment
-the list. Otherwise, the list is not augmented.</p>
+address there. Alternatively, if EPICS_CAS_BEACON_ADDR_LIST is not defined,
+EPICS_CA_ADDR_LIST is defined, and EPICS_CAS_INTF_ADDR_LIST is not defined,
+then the contents of EPICS_CA_ADDR_LIST will be used to augment the list.
+Otherwise, the list is not augmented.</p>
 
 <p>The EPICS_CAS_BEACON_PORT parameter specifies the destination port for
 server beacons. The only exception to this occurs when  ports are specified
@@ -696,10 +702,21 @@ specified in EPICS_CA_REPEATER_PORT.</p>
 <h4>Binding a Server to a Limited Set of Network Interfaces</h4>
 
 <p>The parameter EPICS_CAS_INTF_ADDR_LIST allows a ca server to bind itself
-to a limited set of network interfaces (each specified by its IP address). By
-defualt, the CA server is accessible from all network interfaces configured
-into its host.  <em>In R3.14 and R3.13 the CA server employed by iocCore does
-not implemet this feature</em>.</p>
+to, and therefore accept messages only from, a limited set of network
+interfaces (each specified by it's IP address). Specifically, UDP search
+messages addressed to both the IP addresses in EPICS_CAS_INTF_ADDR_LIST and
+also to the broadcast addresses of the corresponding LAN interfaces will be
+accepted by the server. By defualt, the CA server is accessible from all
+network interfaces configured into its host.  <em>In R3.14 and previous
+releases the CA server employed by iocCore does not implemet this
+feature</em>.</p>
+
+<h4>Ignoring Process Variable Name Resolution Requests From Certain Hosts</h4>
+
+<p>Name resolution requests originating from any of the IP addresses
+specified in the EPICS_CAS_IGNORE_ADDR_LIST parameter are not replied to.<em>
+In R3.14 and previous releases the CA server employed by iocCore does not
+implemet this feature.</em></p>
 
 <h4>Client Configuration that also Applies to Servers</h4>
 
@@ -1020,27 +1037,40 @@ server.</p>
 
 <h3><a name="Connection">Connection Management</a></h3>
 
-<p>You should assume that the availablity of paths through your network is
-transient. When you create a CA channel its initial connection state will
-most commonly be disconnected. If the Process Variable's server is available
-the library will immediatly initiate the necessary actions to make a
-connection with it. Otherwise, the client library will monitor the state of
-servers on the network and immediately connect or reconnect with the process
-variable's server when it becomes available. A connection state change call
-back function may be installed to be run whenever a CA channel connects or
-disconnects. If a connection state change call back function is not installed
-(if a nil function pointer is supplied) then the user must wait for
-successful status from ca_pend_io prior to using the channel for the first
-time. Once the channel connects the user can freely perform IO operations
-through the channel, but he should expect that the channel might disconnect
-at any time due to network connectivity disruptions or server restarts.
-Otherwise, if a connection state change call back function is supplied, one
-of the arguments to this function distinguishes between connect and
-disconnect events. If a connection state change call back function is
-installed on a particular channel by the user ca_pend_io will not block for
-the channel to connect. The user's connection state change function will be
-run immediately when the channel is created if the CA client and the server
-are both hosted in the same address space.</p>
+<p>Application programs should assume that CA server may be restarted, and
+that network connectivity is transient. When you create a CA channel it's
+initial connection state will most commonly be disconnected. If the Process
+Variable's server is available the library will immediatly initiate the
+necessary actions to make a connection with it. Otherwise, the client library
+will monitor the state of servers on the network and immediately connect or
+reconnect with the process variable's server when it becomes available.</p>
+
+<p>Two methods may be used to dermine if a channel has connected: the
+application program can block in <code><a
+href="#ca_pend_io">ca_pend_io</a></code>, or the application program can
+install a connection callback handler when it calls <code><a
+href="#ca_create_channel">ca_create_channel</a></code>. The <code><a
+href="#ca_pend_io">ca_pend_io</a></code> approach is best suited to simple
+command line programs with a short runtime duration, and the conection
+callback method is best suited to toolkit components with a long runtime
+duration. If a connection state change call back function is <em>not</em>
+installed when <code>ca_create_channel </code>is called (if a nil function
+pointer is supplied) then the application program <em>must </em>wait for
+successful status from <code><a href="#ca_pend_io">ca_pend_io</a></code>
+prior to using the channel for the first time.  Otherwise, if a connection
+state change call back function <em>is</em> supplied, then one of the
+arguments to this function distinguishes between connect and disconnect
+events, and <code><a href="#ca_pend_io">ca_pend_io</a></code> will <em>not
+</em>block for the channel to connect. The user's connection state change
+function will be run immediately from within <code><a
+href="#ca_create_channel">ca_create_channel</a> </code>if the CA client and
+the server are both hosted within the same address space (within the same
+process).</p>
+
+<p>Once the channel connects the application program can freely perform IO
+operations through the channel, but it should expect that the channel might
+disconnect at any time due to network connectivity disruptions or server
+restarts.</p>
 
 <h3><a name="Thread">Thread Safety and Preemptive Callback to User
 Code</a></h3>
@@ -1690,7 +1720,12 @@ immediately <em>without
 activities</em>.</p>
 
 <p>The delay specified to ca_pend_io() should take into account worst case
-network delays such as Ethernet collision backoff and retransmission.</p>
+network delays such as Ethernet collision exponential backoff until
+retransmission delays which can be quite long on overloaded networks.</p>
+
+<p>Unlike <code><a href="#L3249">ca_pend_event</a></code>, this routine will
+not process CA's background activities if none of the selected IO requests
+are pending.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -1703,6 +1738,9 @@ network delays such as Ethernet collision backoff and retransmission.</p>
 
 <p>ECA_NORMAL - Normal successful completion</p>
 
+<p>ECA_TIMEOUT - Selected IO requests didnt complete before specified
+timeout</p>
+
 <p>ECA_EVDISALLOW - Function inappropriate for use within an event handler</p>
 
 <h4>See Also</h4>
@@ -1748,8 +1786,11 @@ activity is processed for TIMEOUT seconds.</p>
 <p>When ca_poll is invoked the send buffer is flushed and any outstanding CA
 background activity is processed.</p>
 
-<p>The routine will not return before the time-out expires and all unfinished
-channel access labor has been processed.</p>
+<p>This routine will <em>not</em> return before the specified time-out
+expires and all unfinished channel access labor has been processed, and
+unlike <code><a href="#ca_pend_io">ca_pend_io</a></code> it does <em>not
+</em>indicate anything about the status of pending IO requests when it
+returns ECA_NORMAL.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2252,7 +2293,30 @@ field is returned otherwise the size of the type is returned.</p>
       otherwise the size in bytes of the type</dd>
 </dl>
 
-<h3><code><a name="ca_test_event">ca_test_event()</a></code></h3>
+<h3><code><a name="dbr_type_t">dbr_type_to_text</a>()</code></h3>
+<pre><code>#include &lt;db_access.h&gt;
+const char * dbr_type_text ( chtype TYPE );</code></pre>
+
+<h4>Description</h4>
+
+<p>Returns a constant null terminated string corresponding to the specified
+dbr type.</p>
+
+<h4>Arguments</h4>
+<dl>
+  <dt><code>TYPE</code></dt>
+    <dd>The data type code. A member of the set of DBR_XXXX in
+    db_access.h.</dd>
+</dl>
+
+<h4>Returns</h4>
+<dl>
+  <dt><code>STRING</code></dt>
+  <dt></dt>
+    <dd>The const string corresponding to the DBR_XXX type.</dd>
+</dl>
+
+<h3><code><a name="ca_test_event1">ca_test_event()</a></code></h3>
 <pre>#include &lt;cadef.h&gt;</pre>
 
 <h4>Description</h4>