Channel Access Client Library performance test.
-If unspecified, the channel count is 10000. If the "append number to pv
-name if true" argument is specified and it is greater than zero then the
-channel names in the test are numbered as follows.
+If unspecified, the channel count is 10000. If the "append number to pv name
+if true" argument is specified and it is greater than zero then the channel
+names in the test are numbered as follows.
<PV name>000000, <PV name>000001, ... <PV name>nnnnnn
@@ -1007,17 +999,16 @@ channel names in the test are numbered as follows.
CA server "beacon anomaly" logging.
CA server beacon anomalies occur when a new server joins the network, a
-server is rebooted, network connectivity to a server is reestablished, or if
-a server's CPU exits a CPU load saturated state.
+server is rebooted, network connectivity to a server is reestablished, or if a
+server's CPU exits a CPU load saturated state.
CA clients with unresolved channels reset their search request scheduling
timers whenever they see a beacon anomaly.
This program can be used to detect situations where there are too many
-beacon anomalies. IP routing configuration problems may result in false
-beacon anomalies that might cause CA clients to use unnecessary additional
-network bandwidth and server CPU load when searching for unresolved
-channels.
+beacon anomalies. IP routing configuration problems may result in false beacon
+anomalies that might cause CA clients to use unnecessary additional network
+bandwidth and server CPU load when searching for unresolved channels.
If there are no new CA servers appearing on the network, and network
connectivity remains constant, then casw should print no messages at all. At
@@ -1030,19 +1021,19 @@ received, and anomalous entries are flagged with a star.
Connect to the specified PV, subscribe for monitor updates the specified
-number of times (default once), and periodically log the current sampled
-event rate, average event rate, and the standard deviation of the event rate
-in Hertz to standard out.
+number of times (default once), and periodically log the current sampled event
+rate, average event rate, and the standard deviation of the event rate in Hertz
+to standard out.
If a value is specified it is written to the PV. Next, the current value
-of the PV is converted to each of the many external data type that can be
-specified at the CA client library interface, and each of these is formated
-and then output to the console.
+If a value is specified it is written to the PV. Next, the current value of
+the PV is converted to each of the many external data type that can be
+specified at the CA client library interface, and each of these is formated and
+then output to the console.
The values for one or multiple PVs are read and printed to stdout. The
DBR_... format in which the data is read, the output format, and a number of
-details of how integer and float values are represented can be controlled
-using command line options.
+details of how integer and float values are represented can be controlled using
+command line options.
When getting multiple PVs, their order on the command line is retained in
the output.
@@ -1105,7 +1096,7 @@ the output.
| -t <key> |
- Specify timestamp source(s) and type, with <key>
- containing
+ | Specify timestamp source(s) and type, with <key> containing
's' = CA server (remote) timestamps
'c' = CA client (local) timestamps (shown in '()'s)
'n' = no timestamps
@@ -1434,14 +1424,14 @@ caput -a [options] <PV name> <no of elements> <value> ...Put value to a PV.
-The specified value is written to the PV (as a string). The PV value is
-read before and after the write operation and printed as "Old" and "new"
-values on stdout.
+The specified value is written to the PV (as a string). The PV value is read
+before and after the write operation and printed as "Old" and "new" values on
+stdout.
The array variant writes an array to the specified PV. The first numeric
-argument specifying the number of array elements is kept for compatibility
-with the array data format of caget - the actual number of values specified
-on the command line is used.
+argument specifying the number of array elements is kept for compatibility with
+the array data format of caget - the actual number of values specified on the
+command line is used.
@@ -1524,8 +1514,8 @@ stdout.
The -s option allows to specify an interest level for calling Channel
Access' internal report function ca_client_status(), that prints lots of
-internal informations on stdout, including environment settings, used CA
-ports etc.
+internal informations on stdout, including environment settings, used CA ports
+etc.
@@ -1571,9 +1561,9 @@ Match
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. It is
-normal for the broadcast addresses to not be identical if the client and
-server are not directly attached to the same IP subnet, and in this situation
-the EPICS_CA_ADDR_LIST must be set. Otherwise, if the client and server are
+normal for the broadcast addresses to not be identical if the client and server
+are not directly attached to the same IP subnet, and in this situation the
+EPICS_CA_ADDR_LIST must be set. Otherwise, if the client and server are
intended to be on the same IP subnet, then the problem may be that the IP
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
@@ -1591,63 +1581,62 @@ Reliably Contact Servers Sharing the Same UDP Port on the Same Host
Two servers can run on the same host with the same server port number, but
there are restrictions. 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 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. Clients can be
-configured to use the same port number for both servers. They will locate the
-2nd server via the shared UDP port, and transparently connect to the 2nd
-server's ephemeral TCP port. Be aware however that If there are two server's
-running on the same host sharing 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).
+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 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. Clients can be configured to
+use the same port number for both servers. They will locate the 2nd server via
+the shared UDP port, and transparently connect to the 2nd server's ephemeral
+TCP port. Be aware however that If there are two server's running on the same
+host sharing 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).
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 a newly introduced server's beacon, then it will take up
-to EPICS_CA_MAX_SEARCH_PERIOD to find that newly introduced server.
-Also, starting with EPICS R3.14.7 the client library does not
-suspend searching for a channel after 100 unsuccessful attempts until a
-beacon anomaly is seen. Therefore, if the client library is from before
-version R3.14.7 of EPICS and it timed out attempting to find a server whoose
-beacon cant be seen by the client library then the client application might
-need to be restarted in order to connect to this new beacon-out-of-range
-server. 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, and
-the client's 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.
+client does not see a newly introduced server's beacon, then it will take up to
+EPICS_CA_MAX_SEARCH_PERIOD to find that newly introduced server. Also,
+starting with EPICS R3.14.7 the client library does not suspend
+searching for a channel after 100 unsuccessful attempts until a beacon anomaly
+is seen. Therefore, if the client library is from before version R3.14.7 of
+EPICS and it timed out attempting to find a server whoose beacon cant be seen
+by the client library then the client application might need to be restarted in
+order to connect to this new beacon-out-of-range server. 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, and the client's 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.
When communication over a virtual circuit times out, then each channel
-attached to the circuit enters a disconnected state and the disconnect
-callback handler specified for the channel is called. However, the circuit is
-not disconnected until TCP/IP's internal, typically long duration, keep alive
-timer expires. The disconnected channels remain attached to the beleaguered
-circuit and no attempt is made to search for, or to reestablish, a new
-circuit. If, at some time in the future, the circuit becomes responsive
-again, then the attached channels enter a connected state again and reconnect
-call back handlers are called. Any monitor subscriptions that received an
-update message while the channel was disconnected are also refreshed. If at
-any time the library receives an indication from the operating system that a
-beleaguered circuit has shutdown or was disconnected then the library will
-immediately reattempt to find servers for each channel and connect circuits
-to them.
+attached to the circuit enters a disconnected state and the disconnect callback
+handler specified for the channel is called. However, the circuit is not
+disconnected until TCP/IP's internal, typically long duration, keep alive timer
+expires. The disconnected channels remain attached to the beleaguered circuit
+and no attempt is made to search for, or to reestablish, a new circuit. If, at
+some time in the future, the circuit becomes responsive again, then the
+attached channels enter a connected state again and reconnect call back
+handlers are called. Any monitor subscriptions that received an update message
+while the channel was disconnected are also refreshed. If at any time the
+library receives an indication from the operating system that a beleaguered
+circuit has shutdown or was disconnected then the library will immediately
+reattempt to find servers for each channel and connect circuits to them.
A well known negative side effect of the above behavior is that CA clients
will wait the full (typically long) duration of TCP/IP's internal keep alive
-timer prior to reconnecting under the following scenario (all of the
-following occur):
+timer prior to reconnecting under the following scenario (all of the following
+occur):
- - An server's (IOC's) operating system crashes (or is abruptly turned
- off) or a vxWorks system is stopped by any means
+ - An server's (IOC's) operating system crashes (or is abruptly turned off)
+ or a vxWorks system is stopped by any means
- This operating system does not immediately reboot using the same IP
address
- A duplicate of the server (IOC) is started appearing at a different IP
@@ -1655,20 +1644,19 @@ following occur):
It is unlikely that any rational organization will advocate the above
-scenario in a production system. Nevertheless, there are
-opportunities for users to become confused during control system
-development, but it is felt that the robustness improvements justify
-isolated confusion during the system integration and checkout activities
-where the above scenarios are most likely to occur.
+scenario in a production system. Nevertheless, there are opportunities
+for users to become confused during control system development, but it
+is felt that the robustness improvements justify isolated confusion during the
+system integration and checkout activities where the above scenarios are most
+likely to occur.
-Contrast the above behavior with the CA client library behavior of
-releases prior to R3.14.5 where the beleaguered circuit was immediately
-closed when communication over it timed out. Any attached channels were
-immediately searched for, and after successful search responses arrived then
-attempts were made to build a new circuit. This behavior could result in
-undesirable resource consumption resulting from periodic circuit setup and
-teardown overhead (thrashing) during periods of CPU / network / IP kernel
-buffer congestion.
+Contrast the above behavior with the CA client library behavior of releases
+prior to R3.14.5 where the beleaguered circuit was immediately closed when
+communication over it timed out. Any attached channels were immediately
+searched for, and after successful search responses arrived then attempts were
+made to build a new circuit. This behavior could result in undesirable resource
+consumption resulting from periodic circuit setup and teardown overhead
+(thrashing) during periods of CPU / network / IP kernel buffer congestion.
@@ -1682,56 +1670,55 @@ that the request is sent call ca_flush followed by
Many Berkley UNIX derived Internet Protocol (IP) kernels use a memory
-management scheme with a fixed sized low level memory allocation quantum
-called an "mbuf". Messages about "ENOBUFS" are an indication that your IP
-kernel is running low on mbuf buffers. An IP kernel mbuf starvation situation
-may lead to temporary IP communications stalls or reduced throughput. This
-issue has to date been primarily associated with vxWorks systems where mbuf
-starvation on earlier vxWorks versions is rumored to lead to permanent IP
-communications stalls which are resolved only by a system reboot. IP kernels
-that use mbufs frequently allow the initial and maximum number of mbufs to be
-configured. Consult your OS's documentation for configuration procedures
-which vary between OS and even between different versions of the same OS.
+management scheme with a fixed sized low level memory allocation quantum called
+an "mbuf". Messages about "ENOBUFS" are an indication that your IP kernel is
+running low on mbuf buffers. An IP kernel mbuf starvation situation may lead to
+temporary IP communications stalls or reduced throughput. This issue has to
+date been primarily associated with vxWorks systems where mbuf starvation on
+earlier vxWorks versions is rumored to lead to permanent IP communications
+stalls which are resolved only by a system reboot. IP kernels that use mbufs
+frequently allow the initial and maximum number of mbufs to be configured.
+Consult your OS's documentation for configuration procedures which vary between
+OS and even between different versions of the same OS.
Contributing Circumstances
- The total number of connected clients is high. Each active socket
- requires dedicated mbufs for protocol control blocks, and for any data
- that might be pending in the operating system for transmission to Channel
- Access or to the network at a given instant. If you increase the vxWorks
- limit on the maximum number of file descriptors then it may also be
- necessary to increase the size of the mbuf pool.
+ requires dedicated mbufs for protocol control blocks, and for any data that
+ might be pending in the operating system for transmission to Channel Access
+ or to the network at a given instant. If you increase the vxWorks limit on
+ the maximum number of file descriptors then it may also be necessary to
+ increase the size of the mbuf pool.
- The server has multiple connections where the server's sustained event
(monitor subscription update) production rate is higher than the client's
or the network's sustained event consumption rate. This ties up a per
- socket quota of mbufs for data that are pending transmission to the
- client via the network. In particular, if there are multiple clients that
+ socket quota of mbufs for data that are pending transmission to the client
+ via the network. In particular, if there are multiple clients that
subscribe for monitor events but do not call ca_pend_event() or ca_poll()
- to process their CA input queue, then a significant mbuf consuming
- backlog can occur in the server.
+ to process their CA input queue, then a significant mbuf consuming backlog
+ can occur in the server.
- The server does not get a chance to run (because some other higher
- priority thread is running) and the CA clients are sending a high volume
- of data over TCP or UDP. This ties up a quota of mbufs for each socket in
- the server that isn't being reduced by the server's socket read system
- calls.
+ priority thread is running) and the CA clients are sending a high volume of
+ data over TCP or UDP. This ties up a quota of mbufs for each socket in the
+ server that isn't being reduced by the server's socket read system
+ calls.
- - The server has multiple stale connections. Stale connections occur when
- a client is abruptly turned off or disconnected from the network, and an
+
- The server has multiple stale connections. Stale connections occur when a
+ client is abruptly turned off or disconnected from the network, and an
internal "keepalive" timer has not yet expired for the virtual circuit in
the operating system, and therefore mbufs may be dedicated to unused
- virtual circuits. This situation is made worse if there are active
- monitor subscriptions associated with stale connections which will
- rapidly increase the number of dedicated mbufs to the quota available for
- each circuit.
+ virtual circuits. This situation is made worse if there are active monitor
+ subscriptions associated with stale connections which will rapidly increase
+ the number of dedicated mbufs to the quota available for each circuit.
- When sites switch to the vxWorks 5.4 IP kernel they frequently run into
- network pool exhaustion problems. This may be because the original
- vxWorks IP kernel expanded the network pool as needed at runtime while
- the new kernel's pool is statically configured at compile time, and does
+ network pool exhaustion problems. This may be because the original vxWorks
+ IP kernel expanded the network pool as needed at runtime while the new
+ kernel's pool is statically configured at compile time, and does
not expand as needed at runtime. Also, at certain sites problems
related to vxWorks network driver pool exhaustion have also been reported
(this can also result in ENOBUF diagnostic messages).
@@ -1739,16 +1726,16 @@ which vary between OS and even between different versions of the same OS.
Related Diagnostics
- - The EPICS command "casr [interest level]" displays information about
- the CA server and how many clients are connected.
+ - The EPICS command "casr [interest level]" displays information about the
+ CA server and how many clients are connected.
- The vxWorks command "inetstatShow" indicates how many bytes are pending
in mbufs and indirectly (based on the number of circuits listed) how many
- mbuf based protocol control blocks have been consumed. The vxWorks
- commands (availability depending on vxWorks version) mbufShow,
- netStackSysPoolShow, and netStackDataPoolShow indicate how much space
- remains in the network stack pool.
- - The RTEMS command "netstat [interest level]" displays network
- information including mbuf consumption statistics.
+ mbuf based protocol control blocks have been consumed. The vxWorks commands
+ (availability depending on vxWorks version) mbufShow, netStackSysPoolShow,
+ and netStackDataPoolShow indicate how much space remains in the network
+ stack pool.
+ - The RTEMS command "netstat [interest level]" displays network information
+ including mbuf consumption statistics.
Server Subscription Update Queuing
@@ -1762,27 +1749,27 @@ isn’t allowed to grow to an infinite size. This is a law of nature
What is done depends on the version of the CA server. All server versions
place quotas on the maximum number of subscription updates allowed on the
subscription update queue at any given time. If this limit is reached, an
-intervening update is discarded in favor of a more recent update. Depending
-on the version of the server, rapidly updating subscriptions are or are not
+intervening update is discarded in favor of a more recent update. Depending on
+the version of the server, rapidly updating subscriptions are or are not
allowed to cannibalize the quotas of slow updating subscriptions in limited
ways. Nevertheless, there is always room on the queue for at least one update
for each subscription. This guarantees that the most recent update is always
sent.
Adding further complication, the CA client library also implements a
-primitive type of flow control. If the client library sees that it is reading
-a large number of messages one after another w/o intervening delay it knows
-that it is not consuming events as fast as they are produced. In that
-situation it sends a message telling the server to temporarily stop sending
-subscription update messages. When the client catches up it sends another
-message asking the server to resume with subscription updates. This prevents
-slow clients from getting time warped, but also guarantees that intervening
-events are discarded until the slow client catches up.
+primitive type of flow control. If the client library sees that it is reading a
+large number of messages one after another w/o intervening delay it knows that
+it is not consuming events as fast as they are produced. In that situation it
+sends a message telling the server to temporarily stop sending subscription
+update messages. When the client catches up it sends another message asking the
+server to resume with subscription updates. This prevents slow clients from
+getting time warped, but also guarantees that intervening events are discarded
+until the slow client catches up.
There is currently no message on the IOC’s console when a particular
client is slow on the uptake. A message of this type used to exist many years
-ago, but it was a source of confusion (and what we will call message noise)
-so it was removed.
+ago, but it was a source of confusion (and what we will call message noise) so
+it was removed.
There is unfortunately no field in the protocol allowing the server to
indicate that an intervening subscription update was discarded. We should
@@ -1795,31 +1782,30 @@ example, be beneficial when tuning an archiver installation.
Significant performance gains can be realized when the CA client library
doesn't wait for a response to return from the server after each request. All
-requests which require interaction with a CA server are accumulated
-(buffered) and not forwarded to the IOC until one of ca_flush_io, ca_pend_io,
+requests which require interaction with a CA server are accumulated (buffered)
+and not forwarded to the IOC until one of ca_flush_io, ca_pend_io,
ca_pend_event, or ca_sg_pend are called allowing several operations to be
-efficiently sent over the network together. Any process variable values
-written into your program's variables by ca_get() should not be referenced by
-your program until ECA_NORMAL has been received from ca_pend_io().
+efficiently sent over the network together. Any process variable values written
+into your program's variables by ca_get() should not be referenced by your
+program until ECA_NORMAL has been received from ca_pend_io().
If successful, the routines described here return the status code
ECA_NORMAL. Unsuccessful status codes returned from the client library are
-listed with each routine in this manual. Operations that appear to be valid
-to the client can still fail in the server. Writing the string "off" to a
-floating point field is an example of this type of error. If the server for a
-channel is located in a different address space than the client then the
-ca_xxx() operations that communicate with the server return status indicating
-the validity of the request and whether it was successfully enqueued to the
-server, but communication of completion status is deferred until a user
-callback is called, or lacking that an exception handler is called. An error
-number and the error's severity are embedded in CA status (error) constants.
-Applications shouldn't test the success of a CA function call by checking to
-see if the returned value is zero as is the UNIX convention. Below are
-several methods to test CA function returns. See ca_signal() and SEVCHK for more information on this
-topic.
+listed with each routine in this manual. Operations that appear to be valid to
+the client can still fail in the server. Writing the string "off" to a floating
+point field is an example of this type of error. If the server for a channel is
+located in a different address space than the client then the ca_xxx()
+operations that communicate with the server return status indicating the
+validity of the request and whether it was successfully enqueued to the server,
+but communication of completion status is deferred until a user callback is
+called, or lacking that an exception handler is called. An error number and the
+error's severity are embedded in CA status (error) constants. Applications
+shouldn't test the success of a CA function call by checking to see if the
+returned value is zero as is the UNIX convention. Below are several methods to
+test CA function returns. See ca_signal() and SEVCHK
+for more information on this topic.
status = ca_XXXX();
SEVCHK( status, "ca_XXXX() returned failure status");
@@ -1838,30 +1824,29 @@ if ( status != ECA_NORMAL ) {
client side application program. It is possible to connect a wide variety of
data sources into EPICS using the CA server library. When a CA channel
communicates with an EPICS Input Output Controller (IOC) then a field is a
-specialization of a PV, and an EPICS record is a plug compatible function
-block that contains fields, and the meta data below frequently are mapped
-onto specific fields within the EPICS records by the EPICS record support
-(see the EPICS Application Developer Guide).
+specialization of a PV, and an EPICS record is a plug compatible function block
+that contains fields, and the meta data below frequently are mapped onto
+specific fields within the EPICS records by the EPICS record support (see the
+EPICS Application Developer Guide).
-Arguments of type chtype specifying the data type you wish to transfer.
-They expect one of the set of DBR_XXXX data type codes defined in
-db_access.h. There are data types for all of the C primitive types, and there
-are also compound (C structure) types that include various process variable
-properties such as units, limits, time stamp, or alarm status. The primitive
-C types follow a naming convention where the C typedef dbr_xxxx_t corresponds
-to the DBR_XXXX data type code. The compound (C structure) types follow a
-naming convention where the C structure tag dbr_xxxx corresponds to the
-DBR_XXXX data type code. The following tables provides more details on the
-structure of the CA data type space. Since data addresses are passed to the
-CA client library as typeless "void *" pointers then care should be taken to
-ensure that you have passed the correct C data type corresponding to the
-DBR_XXXX type that you have specified. Architecture independent types are
-provided in db_access.h to assist programmers in writing portable code. For
-example "dbr_short_t" should be used to send or receive type DBR_SHORT. Be
-aware that type name DBR_INT has been deprecated in favor of the less
-confusing type name DBR_SHORT. In practice, both the DBR_INT type code and
-the DBR_SHORT type code refer to a 16 bit integer type, and are functionally
-equivalent.
+Arguments of type chtype specifying the data type you wish to transfer. They
+expect one of the set of DBR_XXXX data type codes defined in db_access.h. There
+are data types for all of the C primitive types, and there are also compound (C
+structure) types that include various process variable properties such as
+units, limits, time stamp, or alarm status. The primitive C types follow a
+naming convention where the C typedef dbr_xxxx_t corresponds to the DBR_XXXX
+data type code. The compound (C structure) types follow a naming convention
+where the C structure tag dbr_xxxx corresponds to the DBR_XXXX data type code.
+The following tables provides more details on the structure of the CA data type
+space. Since data addresses are passed to the CA client library as typeless
+"void *" pointers then care should be taken to ensure that you have passed the
+correct C data type corresponding to the DBR_XXXX type that you have specified.
+Architecture independent types are provided in db_access.h to assist
+programmers in writing portable code. For example "dbr_short_t" should be used
+to send or receive type DBR_SHORT. Be aware that type name DBR_INT has been
+deprecated in favor of the less confusing type name DBR_SHORT. In practice,
+both the DBR_INT type code and the DBR_SHORT type code refer to a 16 bit
+integer type, and are functionally equivalent.
Channel Access Primitive Data Types
@@ -1954,16 +1939,16 @@ equivalent.
| DBR_PUT_ACKT |
W |
dbr_put_ackt_t |
- Used for global alarm acknowledgement. Do transient alarms have to
- be acknowledged? (0,1) means (no, yes). |
+ Used for global alarm acknowledgement. Do transient alarms have to be
+ acknowledged? (0,1) means (no, yes). |
| DBR_PUT_ACKS |
W |
dbr_put_acks_t |
- Used for global alarm acknowledgement. The highest alarm severity
- to acknowledge. If the current alarm severity is less then or equal
- to this value the alarm is acknowledged. |
+ Used for global alarm acknowledgement. The highest alarm severity to
+ acknowledge. If the current alarm severity is less then or equal to
+ this value the alarm is acknowledged. |
| DBR_STSACK_STRING |
@@ -1984,13 +1969,13 @@ equivalent.
Channel value arrays can also be included within the structured CA data
-types. If more than one element is requested, then the individual elements
-can be accessed in an application program by indexing a pointer to the value
-field in the DBR_XXX structure. For example, the following code computes the
-sum of the elements in a array process variable and prints its time stamp.
-The dbr_size_n function can be used to determine the
-correct number of bytes to reserve when there are more than one value field
-elements in a structured CA data type.
+types. If more than one element is requested, then the individual elements can
+be accessed in an application program by indexing a pointer to the value field
+in the DBR_XXX structure. For example, the following code computes the sum of
+the elements in a array process variable and prints its time stamp. The dbr_size_n function can be used to determine the correct
+number of bytes to reserve when there are more than one value field elements in
+a structured CA data type.
#include <stdio.h>
#include <stdlib.h>
@@ -2059,21 +2044,20 @@ int main ( int argc, char ** argv )
Certain CA client initiated requests asynchronously execute an application
-supplied call back in the client process when a response arrives. The
-functions ca_put_callback, ca_get_callback, and ca_add_event all request
-notification of asynchronous completion via this mechanism. The
-event_handler_args structure is passed by value to the
-application supplied callback. In this structure the dbr field
-is a void pointer to any data that might be returned. The
-status field will be set to one of the CA error
-codes in caerr.h and will indicate the status of the operation performed in
-the IOC. If the status field isn't set to ECA_NORMAL or data isn't normally
-returned from the operation (i.e. put call back) then you should expect that
-the dbr field will be set to a nill pointer (zero). The fields
-usr, chid, and type are set to the
-values specified when the request was made by the application. The "dbr"
-pointer, and any data that it points to, are valid only when executing within
-the user's callback function.
+supplied call back in the client process when a response arrives. The functions
+ca_put_callback, ca_get_callback, and ca_add_event all request notification of
+asynchronous completion via this mechanism. The event_handler_args
+structure is passed by value to the application supplied
+callback. In this structure the dbr field is a void pointer to any
+data that might be returned. The status field will be
+set to one of the CA error codes in caerr.h and will indicate the status of the
+operation performed in the IOC. If the status field isn't set to ECA_NORMAL or
+data isn't normally returned from the operation (i.e. put call back) then you
+should expect that the dbr field will be set to a nill pointer
+(zero). The fields usr, chid, and type
+are set to the values specified when the request was made by the application.
+The "dbr" pointer, and any data that it points to, are valid only when
+executing within the user's callback function.
typedef struct event_handler_args {
void *usr; /* user argument supplied with request */
chanId chid; /* channel id */
@@ -2095,38 +2079,37 @@ void myCallback ( struct event_handler_args args )
-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
-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
-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. 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 ca_add_exception_event().
-
+
If the Process Variable's server and it's client are colocated within the
-same memory address space and the same host then the ca_xxx() operations
-bypass the server and directly interact with the server tool component
-(commonly the IOC's function block database). In this situation the ca_xxx()
-routines frequently return the completion status of the requested operation
-directly to the caller with no opportunity for asynchronous notification of
-failure via an exception handler. Likewise, callbacks may be directly invoked
-by the CA library functions that request them.
+same memory address space and the same host then the ca_xxx() operations bypass
+the server and directly interact with the server tool component (commonly the
+IOC's function block database). In this situation the ca_xxx() routines
+frequently return the completion status of the requested operation directly to
+the caller with no opportunity for asynchronous notification of failure via an
+exception handler. Likewise, callbacks may be directly invoked by the CA
+library functions that request them.
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.
+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.
@@ -2135,59 +2118,56 @@ that network connectivity 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 immediately initiate the
necessary actions to make a connection with it. Otherwise, the client library
-will monitor the state of servers on the network and connect or reconnect
-with the process variable's server as it becomes available. After the channel
+will monitor the state of servers on the network and connect or reconnect with
+the process variable's server as it becomes available. After the channel
connects the application program can freely perform IO operations through the
-channel, but should expect that the channel might disconnect at any time due
-to network connectivity disruptions or server restarts.
+channel, but should expect that the channel might disconnect at any time due to
+network connectivity disruptions or server restarts.
Three methods can be used to determine if a channel is connected: the
-application program might call ca_state
-to obtain the current connection state, block in ca_pend_io until the channel connects, or
-install a connection callback handler when it calls ca_state to
+obtain the current connection state, block in ca_pend_io until the channel connects, or install
+a connection callback handler when it calls ca_create_channel. The ca_pend_io approach is best suited to simple
-command line programs with short runtime duration, and the connection
-callback method is best suited to toolkit components with long runtime
-duration. Use of ca_state is appropriate
-only in programs that prefer to poll for connection state changes instead of
-opting for asynchronous notification. The ca_pend_io function
-blocks only for channels created specifying a nill connection handler
-callback function. The user's connection state change function will be run
-immediately from within ca_create_channel if the CA client and
-CA server are both hosted within the same address space (within the same
-process).
+command line programs with short runtime duration, and the connection callback
+method is best suited to toolkit components with long runtime duration. Use of
+ca_state is appropriate only in programs
+that prefer to poll for connection state changes instead of opting for
+asynchronous notification. The ca_pend_io function blocks only for
+channels created specifying a nill connection handler callback function. The
+user's connection state change function will be run immediately from within
+ca_create_channel if the CA
+client and CA server are both hosted within the same address space (within the
+same process).
-
+
Starting with EPICS R3.14 the CA client libraries are fully thread safe on
-all OS (in past releases the library was thread safe only on vxWorks). When
-the client library is initialized the programmer may specify if preemptive
-call back is enabled. Preemptive call back is disabled by default. If
-preemptive call back is enabled then the user's call back functions might be
-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
-another call back function. Programmers enabling preemptive callback should
-be familiar with using mutex locks to create a reliable multi-threaded
-program.
+all OS (in past releases the library was thread safe only on vxWorks). When the
+client library is initialized the programmer may specify if preemptive call
+back is enabled. Preemptive call back is disabled by default. If preemptive
+call back is enabled then the user's call back functions might be 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 another call back function. Programmers
+enabling preemptive callback should be familiar with using mutex locks to
+create a reliable multi-threaded program.
-To set up a traditional single threaded client you will need code like
-this (see ca_context_create and To set up a traditional single threaded client you will need code like this
+(see ca_context_create and CA Client Contexts and Application Specific Auxiliary
Threads) .
SEVCHK ( ca_context_create(ca_disable_preemptive_callback ),
"application pdq calling ca_context_create" );
-To set up a preemptive callback enabled CA client context you will need
-code like this (see ca_context_create and To set up a preemptive callback enabled CA client context you will need code
+like this (see ca_context_create and CA Client Contexts and Application Specific Auxiliary
Threads).
@@ -2199,28 +2179,28 @@ Threads
It is often necessary for several CA client side tools running in the same
address space (process) to be independent of each other. For example, the
-database CA links and the sequencer are designed to not use the same CA
-client library threads, network circuits, and data structures. Each thread
-that calls ca_context_create() for the first
-time either directly, or implicitly when calling any CA library function for
-the first time, creates a CA client library context. A CA client library
-context contains all of the threads, network circuits, and data structures
-required to connect and communicate with the channels that a CA client
-application has created. The priority of auxiliary threads spawned by the CA
-client library are at fixed offsets from the priority of the thread that
-called ca_context_create(). An application
-specific auxiliary thread can join a CA context by calling ca_context_create() for the first time either
+directly, or implicitly when calling any CA library function for the first
+time, creates a CA client library context. A CA client library context contains
+all of the threads, network circuits, and data structures required to connect
+and communicate with the channels that a CA client application has created. The
+priority of auxiliary threads spawned by the CA client library are at fixed
+offsets from the priority of the thread that called ca_context_create(). An application specific
+auxiliary thread can join a CA context by calling ca_attach_context() using the CA context
identifier that was returned from ca_current_context() when it is called by the
-thread that created the context which needs to be joined. A context which is
-to be joined must be preemptive - it must be created using ca_context_create(ca_enable_preemptive_callback).
It is not possible to attach a thread to a non-preemptive CA context created
explicitly or implicitly with
ca_create_context(ca_disable_preemptive_callback). Once a thread has joined
-with a CA context it need only make ordinary ca_xxxx() library calls to use
-the context.
+with a CA context it need only make ordinary ca_xxxx() library calls to use the
+context.
A CA client library context can be shut down and cleaned up, after
destroying any channels or application specific threads that are attached to
@@ -2232,14 +2212,13 @@ both part of the same context.
Applications
If preemptive call back is not enabled, then for proper operation CA must
-periodically be polled to take care of background activity. This requires
-that your application must either wait in one of ca_pend_event(),
-ca_pend_io(), or ca_sg_block() or alternatively it must call ca_poll() at
-least every 100 milli-seconds. In single threaded applications a file
-descriptor manager like Xt or the interface described in fdManager.h can be
-used to monitor both mouse clicks and also CA's file descriptors so that
-ca_poll() can be called immediately when CA server messages arrives over the
-network.
+periodically be polled to take care of background activity. This requires that
+your application must either wait in one of ca_pend_event(), ca_pend_io(), or
+ca_sg_block() or alternatively it must call ca_poll() at least every 100
+milli-seconds. In single threaded applications a file descriptor manager like
+Xt or the interface described in fdManager.h can be used to monitor both mouse
+clicks and also CA's file descriptors so that ca_poll() can be called
+immediately when CA server messages arrives over the network.
@@ -2253,20 +2232,19 @@ structure. A number of difficulties arise from this practice, which has long
since been deprecated. For example, prior to release 3.13 it was recognized
that transient changes in certain private fields in the per channel structure
would make it difficult to reliably test the channels connection state using
-these private fields directly. Therefore, in release 3.13 the names of
-certain fields were changed to discourage this practice. Starting with
-release 3.14 codes written this way will not compile. Codes intending to
-maintain the highest degree of portability over a wide range of EPICS
-versions should be especially careful. For example you should replace all
-instances off channel_id->count with
-ca_element_count(channel_id). This approach should be reliable
-on all versions of EPICS in use today. The construct ca_puser(chid) =
+these private fields directly. Therefore, in release 3.13 the names of certain
+fields were changed to discourage this practice. Starting with release 3.14
+codes written this way will not compile. Codes intending to maintain the
+highest degree of portability over a wide range of EPICS versions should be
+especially careful. For example you should replace all instances off
+channel_id->count with
+ca_element_count(channel_id). This approach should be reliable on
+all versions of EPICS in use today. The construct ca_puser(chid) =
xxxx is particularly problematic. The best mechanisms for setting the
per channel private pointer will be to pass the user private pointer in when
-creating the channel. This approach is implemented on all versions.
-Otherwise, you can also use ca_set_puser(CHID,PUSER), but this
-function is available only after the first official (post beta) release of
-EPICS 3.13.
+creating the channel. This approach is implemented on all versions. Otherwise,
+you can also use ca_set_puser(CHID,PUSER), but this function is
+available only after the first official (post beta) release of EPICS 3.13.
@@ -2274,38 +2252,38 @@ Thread
Calling CA functions from the vxWorks shell thread is a somewhat
questionable practice for the following reasons.
- - The vxWorks shell thread runs at the very highest priority in the
- system and therefore socket calls are made at a priority that is above
- the priority of tNetTask − a practice that has caused the WRS IP
- kernel to get sick in the past. That symptom was observed some time ago,
- but we don’t know if WRS has fixed the problem.
+ - The vxWorks shell thread runs at the very highest priority in the system
+ and therefore socket calls are made at a priority that is above the
+ priority of tNetTask − a practice that has caused the WRS IP kernel
+ to get sick in the past. That symptom was observed some time ago, but we
+ don’t know if WRS has fixed the problem.
- - The vxWorks shell thread runs at the very highest priority in the
- system and therefore certain CA auxiliary threads will not get the
- priorities that are requested for them. This might cause problems only
- when in a CPU saturation situations.
+ - The vxWorks shell thread runs at the very highest priority in the system
+ and therefore certain CA auxiliary threads will not get the priorities that
+ are requested for them. This might cause problems only when in a CPU
+ saturation situations.
- If the code does not call ca_context_destroy (ca_task_exit in past
releases) then resources are left dangling.
- - In EPICS R3.13 the CA client library installed vxWorks task exit
- handlers behaved strangely if CA functions were called from the vxWorks
- shell, ca_task_exit() wasn’t called, and the vxWorks shell
- restarted. In EPICS R3.14 vxWorks task exit handlers are not installed
- and therefore cleanup is solely the responsibility of the user. With
- EPICS R3.14 the user must call ca_context_destroy or ca_task_exit to
- clean up on vxWorks. This is the same behavior as on all other OS.
+ - In EPICS R3.13 the CA client library installed vxWorks task exit handlers
+ behaved strangely if CA functions were called from the vxWorks shell,
+ ca_task_exit() wasn’t called, and the vxWorks shell restarted. In
+ EPICS R3.14 vxWorks task exit handlers are not installed and therefore
+ cleanup is solely the responsibility of the user. With EPICS R3.14 the user
+ must call ca_context_destroy or ca_task_exit to clean up on vxWorks. This
+ is the same behavior as on all other OS.
-As you might expect, it isnt safe to call the CA client library from a
-POSIX signal handler. Likewise, it isnt safe to call the CA client library
-from interrupt context.
+As you might expect, it isnt safe to call the CA client library from a POSIX
+signal handler. Likewise, it isnt safe to call the CA client library from
+interrupt context.
Function Call Reference
@@ -2318,42 +2296,42 @@ int ca_context_create ( enum ca_preemptive_callback_select SELECT );
Description
This function, or ca_attach_context(),
-should be called once from each thread prior to making any of the other
-Channel Access calls. If one of the above is not called before making other
-CA calls then a non-preemptive context is created by default, and future
-attempts to create a preemptive context for the current threads will fail.
+should be called once from each thread prior to making any of the other Channel
+Access calls. If one of the above is not called before making other CA calls
+then a non-preemptive context is created by default, and future attempts to
+create a preemptive context for the current threads will fail.
-If ca_disable_preemptive_callback is specified then
-additional threads are not allowed to join the CA context using
+ If ca_disable_preemptive_callback is specified then additional
+threads are not allowed to join the CA context using
ca_context_attach() because allowing other threads to join implies that CA
callbacks will be called preemptively from more than one thread.
Arguments
SELECT- This argument specifies if preemptive invocation of callback
- functions is allowed. If so your callback functions might be called
- when the thread that calls this routine is not executing in the CA
- client library. There are two implications to consider.
+ - This argument specifies if preemptive invocation of callback functions
+ is allowed. If so your callback functions might be called when the thread
+ that calls this routine is not executing in the CA client library. There
+ are two implications to consider.
First, if preemptive callback mode is enabled the developer must
- provide mutual exclusion protection for his data structures. In this
- mode it's possible for two threads to touch the application's data
- structures at once: this might be the initializing thread (the thread
- that called ca_context_create) and also a private thread created by the
- CA client library for the purpose of receiving network messages and
- calling callbacks. It might be prudent for developers who are
- unfamiliar with mutual exclusion locking in a multi-threaded
- environment to specify ca_disable_preemptive_callback.
+ provide mutual exclusion protection for his data structures. In this mode
+ it's possible for two threads to touch the application's data structures
+ at once: this might be the initializing thread (the thread that called
+ ca_context_create) and also a private thread created by the CA client
+ library for the purpose of receiving network messages and calling
+ callbacks. It might be prudent for developers who are unfamiliar with
+ mutual exclusion locking in a multi-threaded environment to specify
+ ca_disable_preemptive_callback.
Second, if preemptive callback mode is enabled the application is no
- longer burdened with the necessity of periodically polling the CA
- client library in order that it might take care of its background
- activities. If ca_enable_preemptive_callback is specified
- then CA client background activities, such as connection management,
- will proceed even if the thread that calls this routine is not
- executing in the CA client library. Furthermore, in preemptive callback
- mode callbacks might be called with less latency because the library is
- not required to wait until the initializing thread (the thread that
- called ca_context_create) is executing within the CA client library.
+ longer burdened with the necessity of periodically polling the CA client
+ library in order that it might take care of its background activities. If
+ ca_enable_preemptive_callback is specified then CA client
+ background activities, such as connection management, will proceed even
+ if the thread that calls this routine is not executing in the CA client
+ library. Furthermore, in preemptive callback mode callbacks might be
+ called with less latency because the library is not required to wait
+ until the initializing thread (the thread that called ca_context_create)
+ is executing within the CA client library.
@@ -2420,45 +2398,43 @@ int ca_create_channel
Description
This function creates a CA channel. The CA client library will attempt to
-establish and maintain a virtual circuit between the caller's application and
-a named process variable in a CA server. Each call to ca_create_channel
-allocates resources in the CA client library and potentially also a CA
-server. The function ca_clear_channel() is used to release these resources.
-If successful, the routine writes a channel identifier into the user's
-variable of type "chid". This identifier can be used with any channel access
-call that operates on a channel.
+establish and maintain a virtual circuit between the caller's application and a
+named process variable in a CA server. Each call to ca_create_channel allocates
+resources in the CA client library and potentially also a CA server. The
+function ca_clear_channel() is used to release these resources. If successful,
+the routine writes a channel identifier into the user's variable of type
+"chid". This identifier can be used with any channel access call that operates
+on a channel.
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
-server will return ECA_DISCONNCHID if the channel is currently
-disconnected.
+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 server will return
+ECA_DISCONNCHID if the channel is currently disconnected.
-There are two ways to obtain asynchronous notification when a channel
-enters a connected state.
+There are two ways to obtain asynchronous notification when a channel enters
+a connected state.
- The first and simplest method requires that you call ca_pend_io(), and
wait for successful completion, prior to using a channel that was created
specifying a nil connection call back function pointer.
- The second method requires that you register a connection handler by
supplying a valid connection callback function pointer. This connection
- handler is called whenever the connection state of the channel changes.
- If you have installed a connection handler then ca_pend_io() will
- not block waiting for the channel to enter a connected
- state.
+ handler is called whenever the connection state of the channel changes. If
+ you have installed a connection handler then ca_pend_io() will not
+ block waiting for the channel to enter a connected state.
The function ca_state(CHID) can be used to test the connection state of a
-channel. Valid connections may be isolated from invalid ones with this
-function if ca_pend_io() times out.
+channel. Valid connections may be isolated from invalid ones with this function
+if ca_pend_io() times out.
Due to the inherently transient nature of network connections the order of
-connection call backs relative to the order that ca_create_channel() calls
-are made by the application can't be guaranteed, and application programs may
-need to be prepared for a connected channel to enter a disconnected state at
-any time.
+connection call backs relative to the order that ca_create_channel() calls are
+made by the application can't be guaranteed, and application programs may need
+to be prepared for a connected channel to enter a disconnected state at any
+time.
Example
@@ -2469,10 +2445,10 @@ any time.
PROCESS_VARIABLE_NAME
A nil terminated process variable name string. EPICS process control
function block database variable names are of the form "<record
- name>.<field name>". 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.
+ name>.<field name>". 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.
USERFUNC
PUSER- 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.
+ 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.
PRIORITY- The priority level for dispatch within the server or network with 0
specifying the lowest dispatch priority and 99 the highest. This
parameter currently does not impact dispatch priorities within the
- client, but this might change in the future. The abstract priority
- range specified is mapped into an operating system specific range of
- priorities within the server. This parameter is ignored if the server
- is running on a network or operating system that does not have native
- support for prioritized delivery or execution respectively. Specifying
- many different priorities within the same program can increase resource
- consumption in the client and the server because an independent virtual
- circuit, and associated data structures, is created for each priority
- that is used on a particular server.
+ client, but this might change in the future. The abstract priority range
+ specified is mapped into an operating system specific range of priorities
+ within the server. This parameter is ignored if the server is running on
+ a network or operating system that does not have native support for
+ prioritized delivery or execution respectively. Specifying many different
+ priorities within the same program can increase resource consumption in
+ the client and the server because an independent virtual circuit, and
+ associated data structures, is created for each priority that is used on
+ a particular server.
PCHIDWrite a scalar or array value to a process variable.
-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.
+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.
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.
+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.
All of these functions return ECA_DISCONN if the channel is currently
disconnected.
All put requests are accumulated (buffered) and not forwarded to the IOC
-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.
+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.
Arguments
TYPE- The external type of the supplied value to be written. Conversion
- will occur if this does not match the native type. Specify one from the
- set of DBR_XXXX in db_access.h
+ - The external type of the supplied value to be written. Conversion will
+ occur if this does not match the native type. Specify one from the set of
+ DBR_XXXX in db_access.h
COUNT
PVALUE- Pointer to a value or array of values provided by the application to
- be written to the channel.
+ - Pointer to a value or array of values provided by the application to be
+ written to the channel.
PFUNCRead a scalar or array value from a process variable.
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.
+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.
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 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.
All of these functions return ECA_DISCONN if the channel is currently
disconnected.
All get requests are accumulated (buffered) and not forwarded to the IOC
-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.
+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.
Example
@@ -2704,8 +2678,8 @@ in one message.
TYPE- The external type of the user variable to return the value into.
- Conversion will occur if this does not match the native type. Specify
- one from the set of DBR_XXXX in db_access.h
+ Conversion will occur if this does not match the native type. Specify one
+ from the set of DBR_XXXX in db_access.h
COUNTDescription
-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
+ 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.
+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.
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.
+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.
-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.
+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.
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,
@@ -2795,9 +2769,9 @@ over the network in one message.
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
-restored normal event processing will resume starting always with at
-least one update indicating the current state of the channel.
+that read access was lost 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.
A better name for this function might have been ca_subscribe.
@@ -2808,9 +2782,9 @@ least
Arguments
TYPE- The type of value presented to the call back funstion. Conversion
- will occur if it does not match native type. Specify one from the set
- of DBR_XXXX in db_access.h
+ - The type of value presented to the call back funstion. Conversion will
+ occur if it does not match native type. Specify one from the set of
+ DBR_XXXX in db_access.h
COUNT
RESERVED- Reserved for future use. Specify 0.0 to remain upwardly
- compatible.
+ - Reserved for future use. Specify 0.0 to remain upwardly compatible.
PEVID
MASK- A mask with bits set for each of the event trigger types requested.
- The event trigger mask must be a bitwise or of one or more of
- the following constants.
+
- A mask with bits set for each of the event trigger types requested. The
+ event trigger mask must be a bitwise or of one or more of the
+ following constants.
- DBE_VALUE - Trigger events when the channel value exceeds the
monitor dead band
@@ -2925,17 +2898,17 @@ time.
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 ca_get 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 ca_create_channel requests
-generally should not be reissued for the same process variable unless ca_get 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 ca_create_channel requests generally
+should not be reissued for the same process variable unless ca_clear_channel is called first.
If no ca_get or connection state change events are
-outstanding then ca_pend_io() will flush the send buffer and return
-immediately without processing any outstanding channel access background
+outstanding then ca_pend_io() will flush the send buffer and return immediately
+without processing any outstanding channel access background
activities.
The delay specified to ca_pend_io() should take into account worst case
@@ -2943,8 +2916,8 @@ network delays such as Ethernet collision exponential back off until
retransmission delays which can be quite long on overloaded networks.
Unlike ca_pend_event, this routine will
-not process CA's background activities if none of the selected IO requests
-are pending.
+not process CA's background activities if none of the selected IO requests are
+pending.
Arguments
@@ -2975,12 +2948,12 @@ int ca_test_io();
Description
-This function tests to see if all ca_get requests
-are complete and channels created specifying a nill connection callback
-function pointer are connected. It will report the status of outstanding This function tests to see if all ca_get requests are
+complete and channels created specifying a nill connection callback function
+pointer are connected. It will report the status of outstanding ca_get 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.
+nill connection callback function pointer, after the last call to ca_pend_io()
+or CA context initialization whichever is later.
Returns
@@ -3007,13 +2980,13 @@ background activity is processed.
The ca_pend_event function will not return before the specified
time-out expires and all unfinished channel access labor has been processed,
-and unlike ca_pend_io returning from
-the function does not indicate anything about the status of pending
-IO requests.
+and unlike ca_pend_io returning from the
+function does not indicate anything about the status of pending IO
+requests.
-Both ca_pend_event and ca_poll return
-ECA_TIMEOUT when successful. This behavior probably isn't intuitive, but it
-is preserved to insure backwards compatibility.
+Both ca_pend_event and ca_poll return ECA_TIMEOUT
+when successful. This behavior probably isn't intuitive, but it is preserved to
+insure backwards compatibility.
See also Thread Safety and Preemptive Callback to User
Code.
@@ -3057,13 +3030,13 @@ void SEVCHK( CA_STATUS, CONTEXT_STRING );
Description
Provide the error message character string associated with the supplied
-channel access error code and the supplied error context to diagnostics. If
-the error code indicates an unsuccessful operation a stack dump is printed,
-if this capability is available on the local operating system, and execution
-is terminated.
+channel access error code and the supplied error context to diagnostics. If the
+error code indicates an unsuccessful operation a stack dump is printed, if this
+capability is available on the local operating system, and execution is
+terminated.
-SEVCHK is a macro envelope around ca_signal which only calls ca_signal()
-if the supplied error code indicates an unsuccessful operation. SEVCHK is the
+ SEVCHK is a macro envelope around ca_signal which only calls ca_signal() if
+the supplied error code indicates an unsuccessful operation. SEVCHK is the
recommended error handler for simple applications which do not wish to write
code testing the status returned from each channel access call.
@@ -3071,9 +3044,9 @@ code testing the status returned from each channel access call.
status = ca_context_create (...);
SEVCHK ( status, "Unable to create a CA client context" );
-If the application only wishes to print the message associated with an
-error code or test the severity of an error there are also functions provided
-for this purpose.
+If the application only wishes to print the message associated with an error
+code or test the severity of an error there are also functions provided for
+this purpose.
Arguments
@@ -3102,11 +3075,11 @@ int ca_add_exception_event ( pCallback USERFUNC, void *USERARG );
back.
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
+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.
+diagnostic message on the client's standard out and terminates execution if the
+error condition is severe.
Note that certain fields in "struct exception_handler_args" are not
applicable in the context of some error messages. For instance, a failed get
@@ -3168,6 +3141,79 @@ ca_add_exception_event ( ca_exception_handler , 0 );
ECA_NORMAL - Normal successful completion
+
+
+
+#include <cadef.h>int ca_add_fd_registration ( void ( USERFUNC * ) ( void *USERARG, int FD, int OPENED ), void * USERARG )
+
+Description
+
+For use with the services provided by a file descriptor manager (IO
+multiplexor) such as ""fdmgr.c". A file descriptor manager is often needed when
+two file descriptor IO intensive libraries such as the EPICS channel access
+client library and the X window system client library must coexist in the same
+UNIX process. This function allows an application code to be notified whenever
+the CA client library places a new file descriptor into service and whenever
+the CA client library removes a file descriptor from service. Specifying
+USERFUNC=NULL disables file descriptor registration (this is the default).
+
+Arguments
+
+USERFUNC
+
+Pointer to a user supplied C function returning null with the above
+arguments.
+
+USERARG
+
+User supplied pointer sized variable passed to the above function.
+
+FD
+
+A file descriptor.
+
+OPENED
+
+Boolean argument is true if the file descriptor was opened and false if the
+file descriptor was closed.
+
+Example
+int s;
+static struct myStruct aStruct;
+
+void fdReg ( struct myStruct *pStruct, int fd, int opened )
+{
+ if ( opened ) printf ( "fd %d was opened\n", fd );
+ else printf ( "fd %d was closed\n", fd );
+}
+s = ca_add_fd_registration ( fdReg, & aStruct );
+SEVCHK ( s, NULL );
+
+
+
+Comments
+
+When using this function it is advisable to call it only once prior to
+calling any other CA function, or once just after creating the CA context (if
+you create the context explicitly). Use of this interface can improve latency
+slightly in applications that use non preemptive callback mode at the expense
+of some additional runtime overhead when compared to the alternative which is
+just polling ca_pend_event periodically. It would probably not be appropriate
+to use this function with preemptive callback mode. Starting with R3.14 this
+function is implemented in a special backward compatibility mode. if
+ca_add_fd_registration is called, a single pseudo UDP fd is
+created which CA pokes whenever something significant happens. Xt and others
+can watch this fd so that backwards compatibility is preserved, and so that
+they will not need to use preemptive callback mode but they will nevertheless
+get the lowest latency response to the arrival of CA messages.
+
+Returns
+
+"ECA_NORMAL - Normal successful completion
+
+
+
#include <cadef.h>
@@ -3182,8 +3228,8 @@ default handler uses fprintf to send messages to 'stderr'.
Arguments
PFUNC- The address of a user supplied call back handler to be invoked when
- CA prints diagnostic messages. Installing a nil pointer will cause the
+
- The address of a user supplied call back handler to be invoked when CA
+ prints diagnostic messages. Installing a nil pointer will cause the
default call back handler to be reinstalled.
@@ -3200,8 +3246,7 @@ SEVCHK ( status, "failed to install my printf handler" );
ECA_NORMAL - Normal successful completion
-
+
#include <cadef.h>
typedef void ( *pCallBack )( struct access_rights_handler_args );
int ca_replace ( chid CHAN, pCallBack PFUNC );
@@ -3231,8 +3276,8 @@ specified channel.
PFUNC- Address of user supplied call back function. A nil pointer uninstalls
- the current handler. The following arguments are passed by
- value to the supplied callback handler.
+ the current handler. The following arguments are passed by value
+ to the supplied callback handler.
typedef struct ca_access_rights {
unsigned read_access:1;
unsigned write_access:1;
@@ -3327,8 +3372,8 @@ void ca_set_puser ( chid CHID, void *PUSER );
Description
-Set a user private void pointer variable retained with each channel for
-use at the users discretion.
+Set a user private void pointer variable retained with each channel for use
+at the users discretion.
Arguments
@@ -3372,8 +3417,8 @@ enum channel_state ca_state ( CHID );
Description
-Returns an enumerated type indicating the current state of the specified
-IO channel.
+Returns an enumerated type indicating the current state of the specified IO
+channel.
Arguments
@@ -3426,8 +3471,8 @@ channel is currently connected.
Returns
STRING- The process variable server's host name. If the channel is
- disconnected the string "<disconnected>" is returned.
+ - The process variable server's host name. If the channel is disconnected
+ the string "<disconnected>" is returned.
@@ -3470,8 +3515,8 @@ specified channel and
Returns
STRING- boolean true if the client currently has write access to the
- specified channel and boolean false otherwise
+ - boolean true if the client currently has write access to the specified
+ channel and boolean false otherwise
@@ -3485,8 +3530,7 @@ extern unsigned dbr_size[/*TYPE*/];
Arguments
TYPE- The data type code. A member of the set of DBF_XXXX in
- db_access.h.
+ - The data type code. A member of the set of DBF_XXXX in db_access.h.
Returns
@@ -3537,8 +3581,7 @@ field is returned otherwise the size of the type is returned.
Arguments
TYPE- The data type code. A member of the set of DBF_XXXX in
- db_access.h.
+ - The data type code. A member of the set of DBF_XXXX in db_access.h.
Returns
@@ -3554,14 +3597,13 @@ const char * dbr_type_text ( chtype TYPE );
Description
-Returns a constant null terminated string corresponding to the specified
-dbr type.
+Returns a constant null terminated string corresponding to the specified dbr
+type.
Arguments
TYPE- The data type code. A member of the set of DBR_XXXX in
- db_access.h.
+ - The data type code. A member of the set of DBR_XXXX in db_access.h.
Returns
@@ -3577,8 +3619,8 @@ dbr type.
Description
void ca_test_event ( struct event_handler_args );
-A built-in subscription update call back handler for debugging purposes
-that prints diagnostics to standard out.
+A built-in subscription update call back handler for debugging purposes that
+prints diagnostics to standard out.
Examples
void ca_test_event ();
@@ -3598,15 +3640,15 @@ int ca_sg_create ( CA_SYNC_GID *PGID );
Create a synchronous group and return an identifier for it.
A synchronous group can be used to guarantee that a set of channel access
-requests have completed. Once a synchronous group has been created then
-channel access get and put requests may be issued within it using ca_sg_get()
-and ca_sg_put() respectively. The routines ca_sg_block() and ca_sg_test() can
-be used to block for and test for completion respectively. The routine
-ca_sg_reset() is used to discard knowledge of old requests which have timed
-out and in all likelihood will never be satisfied.
+requests have completed. Once a synchronous group has been created then channel
+access get and put requests may be issued within it using ca_sg_get() and
+ca_sg_put() respectively. The routines ca_sg_block() and ca_sg_test() can be
+used to block for and test for completion respectively. The routine
+ca_sg_reset() is used to discard knowledge of old requests which have timed out
+and in all likelihood will never be satisfied.
-Any number of asynchronous groups can have application requested
-operations outstanding within them at any given time.
+Any number of asynchronous groups can have application requested operations
+outstanding within them at any given time.
Arguments
@@ -3677,16 +3719,16 @@ int ca_sg_block ( CA_SYNC_GID GID, double timeout );
or the specified time out expires. At this time outstanding requests include
calls to ca_sg_array_get() and calls to ca_sg_array_put(). If ECA_TIMEOUT is
returned then failure must be assumed for all outstanding queries. Operations
-can be reissued followed by another ca_sg_block(). This routine will only
-block on outstanding queries issued after the last call to ca_sg_block(),
-ca_sg_reset(), or ca_sg_create() whichever occurs later in time. If no
-queries are outstanding then ca_sg_block() will return immediately without
-processing any pending channel access activities.
+can be reissued followed by another ca_sg_block(). This routine will only block
+on outstanding queries issued after the last call to ca_sg_block(),
+ca_sg_reset(), or ca_sg_create() whichever occurs later in time. If no queries
+are outstanding then ca_sg_block() will return immediately without processing
+any pending channel access activities.
-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.
+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.
Arguments
@@ -3781,8 +3823,8 @@ outstanding request count of a synchronous group.
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(),
-ca_pend_event(), or ca_sg_pend() are called. This allows several requests to
-be efficiently sent in one message.
+ca_pend_event(), or ca_sg_pend() are called. This allows several requests to be
+efficiently sent in one message.
If a connection is lost and then resumed outstanding puts are not
reissued.
@@ -3794,9 +3836,8 @@ reissued.
TYPE- The type of supplied value. Conversion will occur if it does not
- match the native type. Specify one from the set of DBR_XXXX in
- db_access.h.
+ - The type of supplied value. Conversion will occur if it does not match
+ the native type. Specify one from the set of DBR_XXXX in db_access.h.
COUNTDescription
-Read a value from a channel and increment the outstanding request count of
-a synchronous group.
+Read a value from a channel and increment the outstanding request count of a
+synchronous group.
-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 , or until ca_sg_test returns ECA_IODONE.
+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
+, or until ca_sg_test returns ECA_IODONE.
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,
@@ -3863,14 +3904,14 @@ reissued.
TYPE- External type of returned value. Conversion will occur if this does
- not match native type. Specify one from the set of DBR_XXXX in
- db_access.h
+ - External type of returned value. Conversion will occur if this does not
+ match native type. Specify one from the set of DBR_XXXX in
+ db_access.h
COUNT- Element count to be read from the specified channel. It must match
- the array pointed to by PVALUE.
+ - Element count to be read from the specified channel. It must match the
+ array pointed to by PVALUE.
CHID
PVALUE- Pointer to application supplied buffer that is to contain the value
- or array of values to be returned
+ - Pointer to application supplied buffer that is to contain the value or
+ array of values to be returned
Returns
@@ -3913,8 +3954,7 @@ int ca_context_status ( struct ca_client_context *,
Prints information about the client context including, at higher interest
levels, status for each channel. Lacking a CA context pointer,
-ca_client_status() prints information about the calling threads CA
-context.
+ca_client_status() prints information about the calling threads CA context.
Arguments
@@ -3964,8 +4004,8 @@ preemptively from more than one thread.
ECA_ISATTACHED - already attached to a CA context
-ECA_NOTTHREADED - the specified context is non-preemptive and therefore
-does not allow other threads to join
+ECA_NOTTHREADED - the specified context is non-preemptive and therefore does
+not allow other threads to join
ECA_ISATTACHED - the current thread is already attached to a CA context
@@ -4060,8 +4100,7 @@ void * PDBR );
- ECA_DBLCHNL
- Identical process variable name on multiple servers
- ECA_EVDISALLOW
- - Request inappropriate within subscription (monitor) update
- callback
+ - Request inappropriate within subscription (monitor) update callback
- ECA_BADMONID
- Bad event subscription (monitor) identifier
- ECA_BADMASK
|
