From 58db4793200fa6710dde8e92ea94b3de6f831aad Mon Sep 17 00:00:00 2001
From: Jeff Hill <johill@lanl.gov>
Date: Fri, 21 Feb 2003 15:59:11 +0000
Subject: [PATCH] better explanation of subnet masks

---
 src/ca/CAref.html | 331 ++++++++++++++++++++++++----------------------
 1 file changed, 172 insertions(+), 159 deletions(-)

diff --git a/src/ca/CAref.html b/src/ca/CAref.html
index e4ddb21a7..79bc9f608 100644
--- a/src/ca/CAref.html
+++ b/src/ca/CAref.html
@@ -102,7 +102,7 @@ height="31" width="88"></a></p>
     Common</a></li>
 </ul>
 
-<h3>Functionality Index </h3>
+<h3>Functionality Index&nbsp;</h3>
 <ul>
   <li><a href="#ca_context_create">create CA client context</a></li>
   <li><a href="#ca_context_destroy">terminate CA client context</a></li>
@@ -110,7 +110,7 @@ height="31" width="88"></a></p>
   <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_get">read from a channel</a></li>
-  <li><a href="#ca_add_event">subscribe for state change updates</a></li>
+  <li><a href="#ca_add_event">subscribe&nbsp;for state change updates</a></li>
   <li><a href="#ca_clear_event">cancel a subscription</a></li>
   <li><a href="#ca_pend_io">block for certain requests to complete</a></li>
   <li><a href="#ca_test_io">test to see if certain requests have
@@ -126,7 +126,7 @@ height="31" width="88"></a></p>
 <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 </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_client_status">ca_client_status</a></li>
@@ -240,7 +240,7 @@ files is used.</p>
     </tr>
     <tr>
       <td>EPICS_CA_SERVER_PORT</td>
-      <td>i &gt; 5000</td>
+      <td>i&nbsp;&gt; 5000</td>
       <td>5064</td>
     </tr>
     <tr>
@@ -263,7 +263,7 @@ shell that is in use.</p>
   <tbody>
     <tr>
       <td>C shell</td>
-      <td>setenv EPICS_CA_ADDR_LIST  1.2.3.4</td>
+      <td>setenv EPICS_CA_ADDR_LIST&nbsp; 1.2.3.4</td>
     </tr>
     <tr>
       <td>bash</td>
@@ -271,7 +271,7 @@ shell that is in use.</p>
     </tr>
     <tr>
       <td>vxWorks shell</td>
-      <td>putenv ( "EPICS_CA_ADDR_LIST =1.2.3.4" )</td>
+      <td>putenv ( "EPICS_CA_ADDR_LIST&nbsp;=1.2.3.4" )</td>
     </tr>
     <tr>
       <td>DOS command line</td>
@@ -299,25 +299,25 @@ when EPICS is extended to operate over a wide area network (WAN).</p>
 <h3><a name="Network">IP Network Administration Background
 Information</a></h3>
 
-<p>Channel Access is implemented using internet protocols (IP). IP addresses
-are divided into host and network portions. The boundary between each portion
-is determined by the IP netmask. Portions of the IP address corresponding to
-zeros in the netmask specify the hosts address within an IP subnet. Portions
-of the IP address corresponding to binary ones in the netmask specify the
-address of a host's IP subnet. Normally the scope of a broadcasted frame will
-be limited to one IP subnet. Addresses with the host address portion set to
-all zeros or all ones are special. Modern IP kernel implementations reserve
-destination addresses with the host portion set to all ones for the purpose
-of addressing broadcasts to a particular subnet. In theory we can issue a
-broadcast frame on any broadcast capable LAN within the interconnected
-internet by specifying the proper subnet address combined with a host portion
-set to all ones. In practice these "directed broadcasts" are frequently
-limited by the default router configuration. The proper directed broadcast
-address required to reach a particular host can be obtained by logging into
-that host and typing the command required by your local operating
-environment. Ignore the loop back interface and use the broadcast address
-associated with an interface connected to a path through the network to your
-client. Typically there will be only one Ethernet interface.</p>
+<p>Channel Access is implemented&nbsp;using internet protocols (IP). IP
+addresses are divided into host and network portions. The boundary between
+each portion is determined by the IP netmask. Portions of the IP address
+corresponding to zeros in the netmask specify the hosts address within an IP
+subnet. Portions of the IP address corresponding to binary ones in the
+netmask specify the address of a host's IP subnet. Normally the scope of a
+broadcasted frame will be limited to one IP subnet. Addresses with the host
+address portion set to all zeros or all ones are special. Modern IP kernel
+implementations reserve destination addresses with the host portion set to
+all ones for the purpose of addressing broadcasts to a particular subnet. In
+theory we can issue a broadcast frame on any broadcast capable LAN within the
+interconnected internet by specifying the proper subnet address combined with
+a host portion set to all ones. In practice these "directed broadcasts" are
+frequently limited by the default router configuration. The proper directed
+broadcast address required to reach a particular host can be obtained by
+logging into that host and typing the command required by your local
+operating environment. Ignore the loop back interface and use the broadcast
+address associated with an interface connected to a path through the network
+to your client. Typically there will be only one Ethernet interface.</p>
 
 <table border="1">
   <tbody>
@@ -354,9 +354,9 @@ instance, a site might set up an operational control system and a test
 control system on the same network. In this situation it is desirable for the
 test system and the operational system to use identical PV names without fear
 of collision. Usually the best choice is to assign new port numbers to the
-operational system and allow the test system to use the default CA port
-numbers. A site might also configure the CA port numbers because some other
-facility has already using the CA default port numbers.</p>
+operational system&nbsp;and allow the test system to use the&nbsp;default CA
+port numbers. A site might also configure the CA port numbers&nbsp;because
+some other facility is already using the default port numbers.</p>
 
 <table cellspacing="1" cellpadding="1" width="80%" border="1">
   <col><tbody>
@@ -616,9 +616,9 @@ placed in the variable EPICS_TS_MIN_WEST.</p>
 the largest array that may pass through CA. This parameter must be set
 appropriately for both the CA client and the CA server. In EPICS R3.14 CA
 maintains a free list of 16384 byte network buffers that are used for
-ordinary communication. If EPICS_CA_MAX_ARRAY_BYTES  is larger than 16384
-then a second free list of larger data buffers is established when clients
-request transportation of large arrays.</p>
+ordinary communication. If EPICS_CA_MAX_ARRAY_BYTES&nbsp; is larger than
+16384 then a second free list of larger data buffers is established when
+clients request transportation of large arrays.</p>
 
 <h3><a name="Configurin2">Configuring a CA Server</a></h3>
 
@@ -631,7 +631,7 @@ request transportation of large arrays.</p>
     </tr>
     <tr>
       <td>EPICS_CAS_SERVER_PORT</td>
-      <td>i &gt; 5000</td>
+      <td>i&nbsp;&gt; 5000</td>
       <td>EPICS_CA_SERVER_PORT</td>
     </tr>
     <tr>
@@ -646,12 +646,12 @@ request transportation of large arrays.</p>
     </tr>
     <tr>
       <td>EPICS_CAS_BEACON_PERIOD</td>
-      <td>r &gt; 0.1 seconds</td>
+      <td>r&nbsp;&gt; 0.1 seconds</td>
       <td>15.0</td>
     </tr>
     <tr>
       <td>EPICS_CAS_BEACON_PORT</td>
-      <td>i &gt; 5000</td>
+      <td>i&nbsp;&gt; 5000</td>
       <td>EPICS_CA_REPEATER_PORT</td>
     </tr>
     <tr>
@@ -810,7 +810,14 @@ Match</a></h4>
 
 <p>Verify that the broadcast addresses are identical on the server's host and
 on the client's host. This can be checked  on UNIX with "netstat -i" or
-"ifconfig -a"; on vxWorks with ifShow; and on windows with ipconfig.</p>
+"ifconfig -a"; on vxWorks with ifShow; and on windows with ipconfig. It is
+normal for the broadcast addresses to not be idenical if the client and
+server are not directl,y attached to the same IP subnet, and in this
+situtaion the EPICS_CA_ADDR_LIST must be set. Otherwise, if the client and
+server should be on the same IP subnet, then the problem may be that the
+netmask is incorrectly set in the network interface configuration. On most
+operating systems when the host's IP address is configured the host's IP
+subnet mask is also configured .</p>
 
 <h4><a name="Client">Client Isnt Configured to Use the Server's Port</a></h4>
 
@@ -1154,9 +1161,9 @@ void myCallback ( struct event_handler_args args )
 <h3><a name="Channel1">Channel Access Exceptions</a></h3>
 
 <p>When the server detects a failure, and there is no client call back
-function attached to the request, then an exception handler is executed in
-the client. The default exception handler prints a message on the console and
-exits if the exception condition is severe. Certain internal exceptions
+function attached to the request, then&nbsp;an exception handler is executed
+in the client. The default exception handler prints a message on the console
+and exits if the exception condition is severe. Certain internal exceptions
 within the CA client library, and failures detected by the SEVCHK macro may
 also cause the exception handler to be invoked. To modify this behavior see
 <a href="#ca_add_exception_event">ca_add_exception_event()</a>.</p>
@@ -1176,15 +1183,15 @@ by the CA library functions that request them.</p>
 <h3><a name="Arrays">Arrays</a></h3>
 
 <p>For routines that require an argument specifying the number of array
-elements, no more than the process variable's maximum native element count
-may be requested. The process variable's maximum native element count is
-available from ca_element_count() when the channel is connected. If less
-elements than the process variable's native element count are requested the
-requested values will be fetched beginning at element zero. By default CA
-limits the number of elements in an array to be no more than approximately
-16k divided by the size of one element in the array. Starting with EPICS
-R3.14 the maximum array size may be configured in the client and in the
-server.</p>
+elements, no more than the&nbsp;process variable's maximum&nbsp;native
+element count may be requested. The process variable's&nbsp;maximum native
+element count is available from ca_element_count() when the channel is
+connected. If less elements than the process variable's native element count
+are requested the requested values will be fetched beginning at element zero.
+By default CA limits the number of elements in an array to be no more than
+approximately 16k divided by the size of one element in the array. Starting
+with EPICS R3.14 the maximum array size may be configured in the client and
+in the server.</p>
 
 <h3><a name="Connection">Connection Management</a></h3>
 
@@ -1235,8 +1242,8 @@ called by CA's auxiliary threads when the main initiating channel access
 thread is not inside of a function in the channel access client library.
 Otherwise, the user's call back functions will be called only when the main
 initiating channel access thread is executing inside of the CA client
-library. When the CA client library invokes a user's call back function it
-will always wait for the current callback to complete prior to executing
+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>
 
 <h3><a name="Polling">Polling the CA Client Library From Single Threaded
@@ -1327,7 +1334,7 @@ void ca_context_destroy();</pre>
 
 <h4>Description</h4>
 
-<p>Shut down a channel access client context and free any resources
+<p>Shut down a&nbsp;channel access client context and free any resources
 allocated. On most operating systems this is performed automatically at
 process exit.</p>
 
@@ -1365,9 +1372,9 @@ call that operates on a channel.</p>
 
 <p>The circuit may be initially connected or disconnected depending on the
 state of the network and the location of the channel. A channel will
-only enter a connected state after server's address is determined, and only
-if channel access successfully establishes a virtual circuit through the
-network to the server. Channel access routines that send a request to a
+only&nbsp;enter a&nbsp;connected state after server's address is determined,
+and only if channel access successfully establishes a virtual circuit through
+the network to the server. Channel access routines that send a request to a
 server will return ECA_DISCONNCHID if the channel is currently
 disconnected.</p>
 
@@ -1405,9 +1412,9 @@ any time.</p>
     <dd>A nil terminated process variable name string. EPICS process control
       function block database variable names are of the form "&lt;record
       name&gt;.&lt;field name&gt;". If the field name and the period
-      separator are omitted then the "VAL" field is implicit. For example
-      "RFHV01" and "RFHV01.VAL" reference the same EPICS process control
-      function block database variable.</dd>
+      separator are omitted then&nbsp;the "VAL" field is implicit. For
+      example "RFHV01" and "RFHV01.VAL" reference the same EPICS process
+      control function block database variable.</dd>
 </dl>
 <dl>
   <dt><code>USERFUNC</code></dt>
@@ -1430,10 +1437,10 @@ any time.</p>
 </dl>
 <dl>
   <dt><code>PUSER</code></dt>
-    <dd>The value of this void pointer argument is retained in
-      storage associated with the specified channel. See the MACROS manual
-      page for reading and writing this field. Casual users of channel access
-      may wish to set this field to nil or 0.</dd>
+    <dd>The value of this void&nbsp;pointer argument is&nbsp;retained in
+      storage&nbsp;associated with the specified channel. See the MACROS
+      manual page for reading and writing this field. Casual users of channel
+      access may wish to set this field to nil or 0.</dd>
 </dl>
 <dl>
   <dt><code>PRIORITY</code></dt>
@@ -1472,7 +1479,7 @@ int ca_clear_channel (evid CHID);</code></pre>
 
 <h4>Description</h4>
 
-<p>Shutdown and reclaim resources associated with a channel created by
+<p>Shutdown and reclaim resources&nbsp;associated with a channel created by
 ca_create_channel().</p>
 
 <p>All remote operation requests such as the above are accumulated (buffered)
@@ -1482,7 +1489,7 @@ efficiently sent over the network in one message.</p>
 
 <p>Clearing a channel does not cause its disconnect handler to be called, but
 clearing a channel does shutdown and reclaim any channel state change event
-subscriptions (monitors) registered with the channel.</p>
+subscriptions&nbsp;(monitors) registered&nbsp;with the&nbsp;channel.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -1516,17 +1523,17 @@ int ca_array_put_callback ( chtype TYPE,
 
 <p>Write a scalar or array value to a process variable.</p>
 
-<p>When ca_array_put  or ca_put are invoked the client will receive no
+<p>When ca_array_put&nbsp; 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>
+is lost and then resumed outstanding ca_array_put&nbsp; or ca_put&nbsp;
+requests are not automatically reissued following reconnect, and no
+additional notification are provided to the user for each put request.</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
+back is called only after the initiated&nbsp;write operation and all actions
+resulting from the initiating&nbsp;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
@@ -1563,8 +1570,8 @@ message.</p>
 </dl>
 <dl>
   <dt><code>PFUNC</code></dt>
-    <dd>address of <a href="#User">user supplied callback function</a> to be
-      run when the requested operation completes</dd>
+    <dd>address of <a href="#User">user supplied&nbsp;callback function</a>
+      to be run when the requested operation completes</dd>
 </dl>
 <dl>
   <dt><code>USERARG</code></dt>
@@ -1617,11 +1624,11 @@ 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>
 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.
+from&nbsp;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. 
 
 <p>All of these functions return ECA_DISCONN if the channel is currently
 disconnected.</p>
@@ -1711,26 +1718,27 @@ int ca_add_masked_array_event ( chtype TYPE,
 <h4>Description</h4>
 
 <p>Register a state change subscription and specify a call back function to
-be invoked whenever the process variable undergoes significant state changes.
-A significant change can be a change in the process variable's value, alarm
-status, or alarm severity. In the process control function block database the
-deadband field determines the magnitude of a significant change for for the
-process variable's value. Each call to this function consumes resources in
-the client library and potentially a CA server until one of ca_clear_channel
-or ca_clear_event is called.</p>
+be invoked whenever&nbsp;the process variable undergoes&nbsp;significant
+state changes. A significant change can be a change in the process variable's
+value, alarm status, or alarm severity. In the process control function block
+database the deadband field determines the magnitude of a significant change
+for for the process variable's value. Each call to this function consumes
+resources in the client library and potentially a CA server until one of
+ca_clear_channel or ca_clear_event is called.</p>
 
-<p>Subscriptions may be installed or canceled against both connected and
-disconnected channels. The specified USERFUNC is called once immediately
-after the subscription is installed with the process variable's current state
-if the process variable is connected. Otherwise, the specified USERFUNC is
-called immediately after establishing a connection (or reconnection) with the
-process variable. The specified USERFUNC is called immediately with the
-process variable's current state from within ca_add_event() if the client and
-the process variable share the same address space.</p>
+<p>Subscriptions may be installed&nbsp;or canceled&nbsp;against both
+connected and disconnected channels. The specified USERFUNC is called once
+immediately after the subscription is installed with the process variable's
+current state if the process variable is connected. Otherwise, the specified
+USERFUNC is called immediately after establishing a connection (or
+reconnection) with the process variable. The specified USERFUNC is called
+immediately with the process variable's current state from within
+ca_add_event() if the client and the process variable share the same address
+space.</p>
 
-<p>If a subscription is installed on a channel in a disconnected state then
-the requested count will be set to the native maximum element count of the
-channel if the requested count is larger.</p>
+<p>If a subscription is installed&nbsp;on a channel in a disconnected state
+then the requested count will be set to the native maximum element count of
+the channel if the requested count is larger.</p>
 
 <p>All subscription requests such as the above are accumulated (buffered) and
 not forwarded to the IOC until one of ca_flush_io, ca_pend_io, ca_pend_event,
@@ -1739,9 +1747,9 @@ over the network in one message.</p>
 
 <p>If at any time after subscribing, read access to the specified process
 variable is lost, then the call back will be invoked immediately indicating
-that read access was lost via the status argument. When read access is
+that read access was lost&nbsp;via the status argument. When read access is
 restored normal event processing will resume starting always with at
-least one update indicating the current state of the channel.</p>
+least&nbsp;one update indicating the current state of the channel.</p>
 
 <p>A better name for this function might have been ca_subscribe.</p>
 
@@ -1767,8 +1775,9 @@ least
 </dl>
 <dl>
   <dt><code>USRERFUNC</code></dt>
-    <dd>The address of <a href="#User">user supplied callback function</a> to
-      be invoked with each subscription update.</dd>
+    <dd>The address of <a href="#User">user supplied
+      callback&nbsp;function</a> to be invoked with each subscription
+    update.</dd>
 </dl>
 <dl>
   <dt><code>USERARG</code></dt>
@@ -1784,7 +1793,8 @@ least
   <dt><code>PEVID</code></dt>
     <dd>This is a pointer to user supplied event id which is overwritten if
       successful. This event id can later be used to clear a specific
-      event. This option may may be omitted by passing a nil pointer.</dd>
+      event.&nbsp;This option may&nbsp;may be omitted by passing a nil
+      pointer.</dd>
 </dl>
 <dl>
   <dt><code>MASK</code></dt>
@@ -1832,7 +1842,7 @@ int ca_clear_event ( evid EVID );</code></pre>
 <p>Cancel a subscription.</p>
 
 <p>All ca_clear_event() requests such as the above are accumulated (buffered)
-and not forwarded to the server until one of ca_flush_io, ca_pend_io,
+and not forwarded to the&nbsp;server 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 together in one message.</p>
 
@@ -1869,19 +1879,19 @@ time.</p>
 </ul>
 
 <p>If ECA_TIMEOUT is returned then get requests may be reissued followed by a
-subsequent call to ca_pend_io(). Specifically, the function will block only
-for outstanding outstanding <a href="#ca_get">ca_get</a> requests issued, and
-also any channels created specifying a nill connection handler function
-pointer, after the last call to ca_pend_io() or ca client context creation
-whichever is later. Note that <a
+subsequent call to ca_pend_io().&nbsp;Specifically,&nbsp;the function will
+block&nbsp;only for outstanding outstanding <a href="#ca_get">ca_get</a>
+requests issued, and also any channels created specifying a nill connection
+handler function pointer, after the last call to ca_pend_io() or ca client
+context creation whichever is later. Note that <a
 href="#ca_create_channel">ca_create_channel</a> requests should not be
 reissued unless <a href="#ca_clear_channel">ca_clear_channel</a> is called
 first.</p>
 
 <p>If no <a href="#ca_get">ca_get</a> or connection state change events are
 outstanding then ca_pend_io() will flush the send buffer and return
-immediately <em>without processing any outstanding channel access background
-activities</em>.</p>
+immediately <em>without&nbsp;processing any outstanding channel access
+background activities</em>.</p>
 
 <p>The delay specified to ca_pend_io() should take into account worst case
 network delays such as Ethernet collision exponential back off until
@@ -1895,7 +1905,7 @@ are pending.</p>
 <dl>
   <dt>TIMEOUT</dt>
     <dd>Specifies the time out interval. A <code>TIMEOUT</code> interval of
-      zero specifies forever.</dd>
+      zero&nbsp;specifies&nbsp;forever.</dd>
 </dl>
 
 <h4>Returns</h4>
@@ -1920,12 +1930,13 @@ int ca_test_io();</code></pre>
 
 <h4>Description</h4>
 
-<p>This function tests to see if all <a href="#ca_get">ca_get</a> requests
-are complete and channels created specifying a nill connection callback
-function pointer are connected. It will report the status of outstanding <a
-href="#ca_get">ca_get</a> requests issued, and channels created specifying a
-nill connection callback function pointer, after the last call to
-ca_pend_io() or CA context initialization whichever is later.</p>
+<p>This function tests to see if all&nbsp;<a href="#ca_get">ca_get</a>
+requests are complete and channels created specifying a nill connection
+callback function pointer are connected. It will report the status of
+outstanding <a href="#ca_get">ca_get</a> requests issued, and channels
+created specifying a nill connection callback function pointer, after the
+last call to ca_pend_io() or&nbsp;CA context initialization&nbsp;whichever is
+later.</p>
 
 <h4>Returns</h4>
 
@@ -1978,9 +1989,10 @@ int ca_flush_io();</pre>
 
 <h4>Description</h4>
 
-<p>Flush outstanding IO requests to the server. This routine might be useful
-to users who need to flush requests prior to performing client side labor in
-parallel with labor performed in the server.</p>
+<p>Flush&nbsp;outstanding IO requests to the server.&nbsp;This routine might
+be useful to&nbsp;users&nbsp;who need&nbsp;to flush requests&nbsp;prior
+to&nbsp;performing client side labor in parallel with labor performed in the
+server.</p>
 
 <p>Outstanding requests are also sent whenever the buffer which holds them
 becomes full.</p>
@@ -2022,7 +2034,7 @@ for this purpose.</p>
 </dl>
 <dl>
   <dt><code>CONTEXT_STRING</code></dt>
-    <dd>A null terminated character string to supply as error context to
+    <dd>A null terminated character string to&nbsp;supply as error context to
       diagnostics.</dd>
 </dl>
 
@@ -2043,10 +2055,10 @@ back.</p>
 
 <p>When an error occurs in the server asynchronous to the clients thread then
 information about this type of error is passed from the server to the client
-in an exception message. When the client receives this exception message an
-exception handler callback is called.The default exception handler prints a
-diagnostic message on the client's standard out and terminates execution if
-the error condition is severe.</p>
+in an exception message. When the client receives&nbsp;this exception message
+an exception handler callback is called.The default exception handler prints
+a diagnostic message on the client's standard out and terminates
+execution&nbsp;if the error condition is severe.</p>
 
 <p>Note that certain fields in "struct exception_handler_args" are not
 applicable in the context of some error messages. For instance, a failed get
@@ -2161,7 +2173,7 @@ specified channel.</p>
   <li>whenever the access rights state of a connected channel changes</li>
 </ul>
 
-<p>When a channel is created no access rights handler is installed.</p>
+<p>When a channel is created&nbsp;no access rights handler is installed.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2213,8 +2225,8 @@ chtype ca_field_type ( CHID );</code></pre>
 <h4>Returns</h4>
 <dl>
   <dt><code>TYPE</code></dt>
-    <dd>The data type code will be a member of the set of DBF_XXXX in
-      db_access.h. The constant TYPENOTCONN is returned if the channel is
+    <dd>The data type code will be&nbsp;a member of the&nbsp;set of DBF_XXXX
+      in db_access.h. The constant TYPENOTCONN is returned if the channel is
       disconnected.<a name="ca_element_count"></a></dd>
 </dl>
 
@@ -2224,8 +2236,8 @@ unsigned ca_element_count ( CHID );</code></pre>
 
 <h4>Description</h4>
 
-<p>Return the maximum array element count in  the server for the specified IO
-channel.</p>
+<p>Return the maximum array element count in&nbsp; the server for the
+specified IO channel.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2236,8 +2248,8 @@ channel.</p>
 <h4>Returns</h4>
 <dl>
   <dt><code>COUNT</code></dt>
-    <dd>The maximum array element count in  the server. An element count of
-      zero is returned if the channel is disconnected.</dd>
+    <dd>The&nbsp;maximum array element count in&nbsp; the server. An element
+      count of zero is returned if the channel is disconnected.</dd>
 </dl>
 
 <h3><code><a name="L6931">ca_name()</a></code></h3>
@@ -2267,8 +2279,8 @@ void ca_set_puser ( chid CHID, void *PUSER );</code></pre>
 
 <h4>Description</h4>
 
-<p>Set a user private void pointer variable retained with each channel for
-use at the users discretion.</p>
+<p>Set&nbsp;a user private void pointer variable retained with each channel
+for use at the users discretion.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2376,8 +2388,8 @@ int ca_read_access ( CHID );</code></pre>
 
 <h4>Description</h4>
 
-<p>Returns boolean true if the client currently has read access to the
-specified channel and boolean false otherwise.</p>
+<p>Returns&nbsp;boolean true&nbsp;if the client currently has read access to
+the specified channel and&nbsp;boolean false&nbsp;otherwise.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2388,8 +2400,8 @@ specified channel and
 <h4>Returns</h4>
 <dl>
   <dt><code>STRING</code></dt>
-    <dd>boolean true if the client currently has read access to the specified
-      channel and boolean false otherwise</dd>
+    <dd>boolean true&nbsp;if the client currently has read access to the
+      specified channel and&nbsp;boolean false&nbsp;otherwise</dd>
 </dl>
 
 <h3><code><a name="L6941">ca_write_access()</a></code></h3>
@@ -2398,8 +2410,8 @@ int ca_write_access ( CHID );</code></pre>
 
 <h4>Description</h4>
 
-<p>Returns boolean true if the client currently has write access to the
-specified channel and boolean false otherwise.</p>
+<p>Returns&nbsp;boolean true&nbsp;if the client currently has&nbsp;write
+access to the specified channel and&nbsp;boolean false&nbsp;otherwise.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2410,8 +2422,8 @@ specified channel and
 <h4>Returns</h4>
 <dl>
   <dt><code>STRING</code></dt>
-    <dd>boolean true if the client currently has write access to the
-      specified channel and boolean false otherwise</dd>
+    <dd>boolean true&nbsp;if the client currently has write access to the
+      specified channel and&nbsp;boolean false&nbsp;otherwise</dd>
 </dl>
 
 <h3><code><a name="dbr_size[]">dbr_size[]</a></code></h3>
@@ -2420,13 +2432,13 @@ extern unsigned dbr_size[/*TYPE*/];</code></pre>
 
 <h4>Description</h4>
 
-<p>An array that returns the size in bytes for a DBR_XXXX type.</p>
+<p>An&nbsp;array that returns the size in bytes for a DBR_XXXX type.</p>
 
 <h4>Arguments</h4>
 <dl>
   <dt><code>TYPE</code></dt>
-    <dd>The data type code. A member of the set of DBF_XXXX in
-    db_access.h.</dd>
+    <dd>The data type code.&nbsp;A member of the&nbsp;set of DBF_XXXX in
+      db_access.h.</dd>
 </dl>
 
 <h4>Returns</h4>
@@ -2441,11 +2453,11 @@ unsigned dbr_size_n  (  TYPE, COUNT  );</code></pre>
 
 <h4>Description</h4>
 
-<p>Returns the size in bytes for a DBR_XXXX type with COUNT elements. If the
-DBR type is a structure then the value field is the last field in the
-structure. If COUNT is greater than one then COUNT-1 elements are appended to
-the end of the structure so that they can be addressed as an array through a
-pointer to the value field.</p>
+<p>Returns the size in bytes for a DBR_XXXX type with&nbsp;COUNT
+elements.&nbsp;If the DBR type is a structure then the value field is the
+last field in the structure. If COUNT is greater than one then COUNT-1
+elements are appended to the end of the structure so that they can be
+addressed as an array through a pointer to the value field.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2477,8 +2489,8 @@ field is returned otherwise the size of the type is returned.</p>
 <h4>Arguments</h4>
 <dl>
   <dt><code>TYPE</code></dt>
-    <dd>The data type code. A member of the set of DBF_XXXX in
-    db_access.h.</dd>
+    <dd>The data type code.&nbsp;A member of the&nbsp;set of DBF_XXXX in
+      db_access.h.</dd>
 </dl>
 
 <h4>Returns</h4>
@@ -2500,8 +2512,8 @@ 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>
+    <dd>The data type code.&nbsp;A member of the&nbsp;set of DBR_XXXX in
+      db_access.h.</dd>
 </dl>
 
 <h4>Returns</h4>
@@ -2625,8 +2637,9 @@ processing any pending channel access activities.</p>
 
 <p>Values written into your program's variables by a channel access
 synchronous group request should not be referenced by your program until
-ECA_NORMAL has been received from ca_sg_block(). This routine will process
-pending channel access background activity while it is waiting.</p>
+ECA_NORMAL has been received from ca_sg_block(). This routine
+will&nbsp;process pending&nbsp;channel access background activity while it is
+waiting.</p>
 
 <h4>Arguments</h4>
 <dl>
@@ -2657,7 +2670,7 @@ SEVCHK(status, Sync group block failed);</code></pre>
 
 <h3><code><a name="ca_sg_test">ca_sg_test()</a></code></h3>
 <pre><code>#include &lt;cadef.h&gt;
-int ca_sg_test  ( CA_SYNC_GID GID )</code></pre>
+int ca_sg_test&nbsp; ( CA_SYNC_GID GID )</code></pre>
 
 <h4>Description</h4>
 
@@ -2716,7 +2729,7 @@ status = ca_sg_reset(gid);</code></pre>
 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
+<p>Write a value, or array of values, to a channel and&nbsp;increment the
 outstanding request count of a synchronous group.</p>
 
 <p>All remote operation requests such as the above are accumulated (buffered)
@@ -2814,7 +2827,7 @@ reissued.</p>
 </dl>
 <dl>
   <dt><code>CHID</code></dt>
-    <dd>channel identifier</dd>
+    <dd>channel&nbsp;identifier</dd>
 </dl>
 <dl>
   <dt><code>PVALUE</code></dt>
@@ -2824,9 +2837,9 @@ reissued.</p>
 
 <h4>Returns</h4>
 
-<p>ECA_NORMAL - Normal successful completion </p>
+<p>ECA_NORMAL - Normal successful completion&nbsp;</p>
 
-<p>ECA_BADSYNCGRP - Invalid synchronous group </p>
+<p>ECA_BADSYNCGRP - Invalid synchronous group&nbsp;</p>
 
 <p>ECA_BADCHID - Corrupted CHID</p>
 
@@ -2852,7 +2865,7 @@ int ca_context_status ( struct ca_client_context *,
 <h4>Description</h4>
 
 <p>Prints information about the client context including, at higher interest
-levels, status for each channel.</p>
+levels,&nbsp;status for each channel.</p>
 
 <h4>Arguments</h4>
 <dl>