SNS Division
-
-Copyright © 2002 The University of Chicago, as Operator of Argonne
-National Laboratory.
-Copyright © 2002 The Regents of the University of California, as Operator
-of Los Alamos National Laboratory.
-EPICS BASE Versions 3.13.7 and higher are distributed subject to a
-Software License Agreement found in the file LICENSE that is included
-with this distribution.
-
Copyright © 2002 The University of Chicago, as Operator of
+Argonne National Laboratory.
+Copyright © 2002 The Regents of the University of California, as Operator of
+Los Alamos National Laboratory.
+EPICS BASE Versions 3.13.7 and higher are distributed subject to a Software
+License Agreement found in the file LICENSE that is included with this
+distribution.
Why Reconfigure Channel Access
+Typically reasons to reconfigure EPICS Channel Access:
The two IP port numbers used by Channel Access may be configured. This -might occur when a site decides to set up two or more completely independent -control systems that will share the same network. For 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 reserved the defaults.
+The two default IP port numbers used by Channel Access may be +reconfigured. This might occur when a site decides to set up two or more +completely independent control systems that will share the same network. For +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.
| routeShow() | -
| hostAdd "the-router", "N.N.N.N" | -
| routeAdd "0","the-router" | -
During initialization CA builds a list of the destination addresses used -when sending CA client name resolution (search) requests, and when sending CA -server beacons. This table is initialized by traversing a database of network -interfaces attached to the host. For each interface found that is attached to -a broadcast capable IP subnet the broadcast address of that subnet is added -to the list. For each point to point interface found the destination address -of that link is added to the list. This network interface introspection -driven initialization is disabled only if the EPICS environment variable -"EPICS_CA_AUTO_ADDR_LIST" exists and its value is either of "no" or "NO". The -typical default is to enable network interface introspection driven -initialization with "EPICS_CA_AUTO_ADDR_LIST" set to "YES" or "yes".
+During initialization CA builds the list of server destination addresses +used when sending CA client name resolution (search) requests. This table is +initialized by introspecting the network interfaces attached to the host. For +each interface found that is attached to a broadcast capable IP subnet, the +broadcast address of that subnet is added to the list. For each point to +point interface found, the destination address of that link is added to the +list. This automatic server address list initialization can be disabled if +the EPICS environment variable "EPICS_CA_AUTO_ADDR_LIST" exists and its value +is either of "no" or "NO". The typical default is to enable network interface +introspection driven initialization with "EPICS_CA_AUTO_ADDR_LIST" set to +"YES" or "yes".
Following network interface introspection, any IP addresses specified in the EPICS environment variable EPICS_CA_ADDR_LIST are added to the list of -destination addresses for CA client name resolution requests and CA server -beacons. In a multiple subnet EPICS system users will quickly learn that the -EPICS_CA_ADDR_LIST must be set so that CA name resolution ( search requests ) -frames pass from CA clients to the targeted CA servers. However, a more -subtle configuration mistake resulting in wasted network bandwidth will be to -not also arrange for beacons issued by the targeted CA servers to reach the -hosts of all potential clients. For this reason the EPICS_CA_ADDR_LIST -environment variable parameter will often be identical within a group of -clients and servers that communicate between themselves. The addresses in -EPICS_CA_ADDR_LIST may be dotted IP addresses or host names if the local OS -has support for host name to IP address translation. When multiple names are -added to EPICS_CA_ADDR_LIST they must be separated by while space. There is -no requirement that the addresses specified in the EPICS_CA_ADDR_LIST be a +destination addresses for CA client name resolution requests. In an EPICS +system crossing multiple subnets the EPICS_CA_ADDR_LIST must be set so that +CA name resolution ( search requests ) frames pass from CA clients to the +targeted CA servers unless a CA proxy (gateway) is installed. The addresses +in EPICS_CA_ADDR_LIST may be dotted IP addresses or host names if the local +OS has support for host name to IP address translation. When multiple names +are added to EPICS_CA_ADDR_LIST they must be separated by white space. There +is no requirement that the addresses specified in the EPICS_CA_ADDR_LIST be a broadcast addresses, but this will often be the most convenient choice.
If the CA client library does not see a beacon from a server that it is -connected to for EPICS_CA_CONN_TMO seconds then an echo message is sent to -the server over TCP/IP. If this echo message isn't promptly replied to then -the client will assume that the server is no longer present on the network -and disconnect. Disconnecting implies notification of client side application -programs. The parameter EPICS_CA_CONN_TMO is specified in floating point -seconds. The default is typically 30 seconds.
+connected to for EPICS_CA_CONN_TMO seconds then an state-of-health message is +sent to the server over TCP/IP. If this state-of-health message isn't +promptly replied to then the client will assume that the server is no longer +present on the network and disconnect. Disconnecting implies notification of +client side application programs via function callbacks. The parameter +EPICS_CA_CONN_TMO is specified in floating point seconds. The default is +typically 30 seconds. For efficient operation it is recommended that +EPICS_CA_CONN_TMO be set to no less than twice the value specified for +EPICS_CA_BEACON_PERIOD. -When a CA server initializes it sends "beacon" messages to each address -specified in EPICS_CA_ADDR_LIST, and also any addresses auto configured from -network interfaces found. Initially, there is a short period between -"beacons". However, this period is doubled each time that a "beacon" is sent -until a plateau specified by EPICS_CA_BEACON_PERIOD is reached. This -parameter is specified in floating point seconds, and the default is -typically 15 seconds. For efficient operation it is recommended that -EPICS_CA_BEACON_PERIOD be set to at least one half of the value specified for -EPICS_CA_CONN_TMO.
+The CA client library will continuously attempt to connect any CA channels +that an application has created until it is successful. The CA client library +periodically queries the server destination address list described above with +name resolution requests for any unresolved channels. Since this address list +frequently contains broadcast addresses, and because nonexistent process +variable names are frequently configured, or servers may be temporarily +unavailable, then it is necessary for the CA client library internals to +carefully schedule these requests in time to avoid introducing excessive load +on the network and the servers.
+ +When the CA client library has many channels to connect, and most of its +name resolution requests are responded to, then it sends name resolution +requests at an interval that is twice the estimated round trip interval for +the set of servers responding, or at the minimum delay quantum for the +operating system - whichever is greater. The number of UDP frames per +interval is also dynamically adjusted based on the past success rate.
+ +If name resolution requests are not responded to, then the client library +doubles the delay between name resolution attempts with each attempt +eventually limited by a maxuimum plateau interval, and it also reduces the +number of requests per interval. After some long interval, if the client +library does not receive any responses it stops sending name resolution +attempts altogether until it sees a beacon anomaly.
+ +The CA client library continually estimates the beacon period of all +server beacons received. If a particular server's beacon period becomes +significantly shorter or longer then the client is said to detect a beacon +anomaly. When a client sees a beacon anomaly then it resumes search requests +but with a longer initial interval between requests than is used when the +application creates a channel. An initial delay based on the client's +ephemeral port number is also imposed before the first name resolution +request to avoid all clients responding to a beacon anomaly at the same +instant. The program "casw" prints a message on standard out each time that a +CA client will detect a beacon anomaly.
+ +Two conclusions deserve special emphasis. First, if a client does not +see the server's beacons, then it will use additional network and server +resources sending periodic state-of-health messages. Second, if a client does +not see the server's beacons, then it may not connect to a newly introduced +server that was initially inaccessible if the client timed out attempting to +find it. The typical situation where a client would not see the server's +beacon might be when the client isnt on the same IP subnet as the server, the +EPICS_CA_ADDR_LIST was modified to include a destination address for the +server, but the server's beacon address list was not modified so that it's +beacons are received by the client.
Starting with EPICS R3.14 all of the libraries in the EPICS base -distribution rely on facilities built into the operating system to determine -the time zone. Nevertheless, several programs commonly used with EPICS use -the original "tssubr" library and therefore they still rely on proper -configuration of EPICS_TS_MIN_WEST.
+Readers Note: Starting with EPICS R3.14 all of the libraries in the +EPICS base distribution rely on facilities built into the operating system to +determine the correct time zone. Nevertheless, several programs commonly used +with EPICS still use the original "tssubr" library and therefore they still +rely on proper configuration of EPICS_TS_MIN_WEST.
While the CA client library does not translate in between the local time and the time zone independent internal storage of EPICS time stamps, many @@ -532,56 +567,126 @@ request transportation of large arrays.
Readers Note: The CA server configurationn documentation is -incomplete. Also, the configuration feature set is more advanced in the new -server than in the original server which is still employed in -iocCore.
+The server configures its UDP port number from the EPICS_CAS_SERVER_PORT +
CA servers send "beacon" messages to each address specified in +EPICS_CAS_BEACON_ADDR_LIST, and also any addresses auto configured from +network interfaces found if EPICS_CAS_AUTO_BEACON_ADDR_LIST is "yes" or +"YES".
+ +The EPICS_CAS_BEACON_PERIOD parameter determines the server's beacon +period and is specified in floating point seconds. The default is typically +15 seconds. See also EPICS_CA_CONN_TMO and Dynamic Changes in the CA Client Library Search +Interval.
+ +The server configures its port number from the EPICS_CAS_SERVER_PORT environment variable if it is specified. Otherwise the EPICS_CA_SERVER_PORT -environemnt variable determines the server's UDP port number. If two servers -share the same UDP port number on the same host then both of them may not, -depending on the local IP kernel, be reachable with IP unicast (an IP address -specifying only one recipient in the client's EPICS_CA_ADDR_LIST). If -available, the server will use the same TCP port number as its UDP port -number. Otherwise, it will use an ephemeral TCP port number assigned by the -opertaing system, and clients will discover this port number via the UDP -search response. The server must build a list of addresses to send beacons -to. If EPICS_CA_AUTO_ADDR_LIST has the value "YES" then the beacon address -list will contain at least the broadcast address of all LAN interfaces found -in the host and the destination address of all point-to-point interfaces -found in the host. 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 repeater's port number if a colun -follows the host name or IP address there. Otherwise, if EPICS_CA_ADDR_LIST -is defined, its contents will be used to augment this list, but its -individual entries will not be allowed to override the repeater's port -number.
+environment variable determines the server's port number. Two servers can +share the same UDP port number on the same machine, but there are +restrictions - see a discussion of unicast addresses and +two servers shareing the same UDP port on the same host. -CA servers build a list of addresses to send beacons to during +initialization. If EPICS_CAS_AUTO_BEACON_ADDR_LIST has the value "YES" then +the beacon address list will contain at least the broadcast address of all +LAN interfaces found in the host and the destination address of all +point-to-point interfaces found in the host. 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. Only 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 inetead be used to augment this list.
+ +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. In R3.14 the CA server used in iocCore does not +implemet this feature.
+ +See also Configuring the Maximum Array Size.
+ +Typically vxWorks hosts boot with routes configured for the host's subnet. +If a EPICS system is operating in a WAN environment it may be necessary to +configure routes into the vxWorks system which enable a vxWorks based CA +server to respond to requests originating outside it's subnet. An EPICS +system manager can implemnt an rudamentary, but robust, form of access +control for a particular host by not providing routes in that host that reach +outside of a limited set of subnets.
+ +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.
+ +Verify that the client and server are using the same UDP port. Check the +server's port by running "netstat -a | grep nnn" where nnn is the port number +configured in the client. If you do not set EPICS_CA_SERVER_PORT or +EPICS_CAS_SERVER_PORT then the default port will be 5064.
+ +Two servers can run on the same host with the same server port number if +the following restrictions are understood. If the host has a modern IP kernel +it is possible to have two or more servers share the same UDP port. It is not +possible for these servers to run on the same host using the same TCP server +port. If the CA server library detects that a server is attempting to start +on the same port as an existing CA server then both servers will use the same +UDP port, and the 2nd server will be allocated an ephemeral TCP port. In this +situation the clients could be configured to use the same port number for +both servers. The clients will find the 2nd server via the shared UDP port, +and transparently connect to the 2nd server's ephemeral TCP port. Be aware +that If there are two server's running on the same host on the same UDP port +then they will both receive UDP search requests sent as broadcasts, but +unfortunately (due to a weakness of most IP kernel implementations) only one +of the servers will typically receive UDP search requests sent to unicast +addresses (i.e. a single specific host's ip address).
+ +If successful, the routines described here return the status code ECA_NORMAL. Unsuccessful status codes returned from the client library are @@ -630,11 +735,11 @@ application.
int status; /* ECA_XXX status of the op from server */ }; -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. To modify this behavior see -ca_add_exception_event().
+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. To modify this behavior see ca_add_exception_event().
If the server for the channel and the client are located on the same node then the ca_xxx() operations bypass the server and directly interact with the @@ -760,7 +865,11 @@ channel access calls.
callbacks might be called when the thread that calls this routine is not executing in the CA client library. Programmers who are unfamiliar with mutual exclusion locking in a multi-threaded environment should - specifyca_disable_preemptive_callback.
+ specify ca_disable_preemptive_callback. If
+ ca_enable_preemptive_callback is specified then CA client background
+ activies, such as connection management, will proceed even if the
+ thread that calls this routine is not executing in the CA client
+ library.
PROCESS_VARIABLE_NAMEUSERFUNCCOUNTCHIDPVALUEPFUNCUSERARGCOUNTCHIDPVALUEUSERFUNCFor functions above that do not include a trigger specification, events will be triggered when there are significant changes in the channel's value or when there are changes in the channel's alarm state. - This is the same as "DBE_VALUE | DBE_ALARM." + This is the same as "DBE_VALUE | DBE_ALARM."
+CA_STATUSCONTEXT_STRINGECA_NORMAL - Normal successful completion
-ca_add_exception_event()ca_add_exception_event()#include <cadef.h> typedef void (*pCallback) ( struct exception_handler_args HANDLERARGS ); int ca_add_exception_event ( pCallback USERFUNC, void *USERARG );@@ -1472,14 +1582,14 @@ field should not be used.
USERFUNCUSERARGPFUNCPFUNCCOUNTca_name()Return the name provided when the supplied channel id was -created.
+Return the name provided when the supplied channel id was created.
PNAMEca_set_puser()STRINGca_write_access()TYPESIZEdbr_value_size[]TYPESIZEca_test_event()PGIDCOUNTCHIDPVALUETYPEPVALUECONTEXTLEVELcaEventRate <PV name>
Subscribe to the specified PV and periodically log its event rate.
ca_test <PV name> [value to be written]
CVS Revision -$Id$ -
+CVS Revision $Id: CAref.html,v 1.24 2002/08/06 22:48:42 anj Exp +$