+ +
Jeffrey O. Hill
+ +JOHill@lanl.gov
+ +Controls and Automation Group
+ +LANSCE Division
+ +Los Alamos National Laboratory
+ +Los Alamos, NM 87545
+ +Copyright Experimental Physics and Industrial Control System +(EPICS) Copyright, 1995, The University of California, The University of +Chicago Portions of this material resulted from work developed under a U.S. +Government contract and are subject to the following license: For a period of +five years from March 30, 1993, the Government is granted for itself and +others acting on its behalf a paid-up, nonexclusive, irrevocable worldwide +license in this computer software to reproduce, prepare derivative works, and +perform publicly and display publicly. Upon request of Licensee, and with DOE +and Licensors approval, this period may be renewed for two additional five +year periods. Following the expiration of this period or periods, the +Government is granted for itself and others acting on its behalf, a paid-up, +nonexclusive, irrevocable worldwide license in this computer software to +reproduce, prepare derivative works, distribute copies to the public, perform +publicly and display publicly, and to permit others to do so. NEITHER THE +UNITED STATES NOR THE UNITED STATES DEPARTMENT OF ENERGY, NOR ANY OF THEIR +EMPLOYEES, MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LEGAL +LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF +ANY INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR REPRESENTS THAT +ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS. Initial development by: The +Controls and Automation Group (AOT-8), Ground Test Accelerator, Accelerator +Technology Division, Los Alamos National Laboratory. Co-developed with: The +Controls and Computing Group, Accelerator Systems Division, Advanced Photon +Source, Argonne National Laboratory.
+ ++ +
Why Reconfigure Channel Access
+ +Typically reasons to reconfigure EPICS Channel Access:
+All Channel Access (CA) configuration occurs through EPICS environment +variables. When searching for an EPICS environment variable EPICS first looks +in the environment using the ANSI C getenv() call. If no matching variable +exists then the default specified in the EPICS build system configuration +files is used.
+ +| Name | +Range | +Default | +
| EPICS_CA_ADDR_LIST | +{N.N.N.N N.N.N.N ...} | +<none> | +
| EPICS_CA_AUTO_ADDR_LIST | +{YES, NO} | +YES | +
| EPICS_CA_CONN_TMO | +r > 0.1 seconds | +30.0 | +
| EPICS_CA_BEACON_PERIOD | +r > 0.1 seconds | +15.0 | +
| EPICS_CA_REPEATER_PORT | +i > 5000 | +5065 | +
| EPICS_CA_SERVER_PORT | +i > 5000 | +5064 | +
| EPICS_CA_MAX_ARRAY_BYTES | +i >= 16384 | +16384 | +
| EPICS_TS_MIN_WEST | +-720 < i <720 minutes | +360 | +
Environment variables are set differently depending on the command line +shell that is in use.
+ +| C shell | +setenv EPICS_CA_ADDR_LIST 1.2.3.4 | +
| bash | +export EPICS_CA_ADDR_LIST=1.2.3.4 | +
| vxWorks shell | +putenv ( "EPICS_CA_ADDR_LIST =1.2.3.4" ) | +
| DOS command line | +set EPICS_CA_ADDR_LIST=1.2.3.4 | +
| Windows NT / 2000 / XP | +control panel / system / environment tab | +
Normally in a local area network (LAN) environment CA discovers the address +of the host for an EPICS process variable by broadcasting frames containing a +list of channel names ( CA search messages ) and waiting for responses from +the servers that host the channels identified. Likewise CA clients efficiently +discover that CA servers have recently joined the LAN or disconnected from the +LAN by monitoring periodically broadcasted beacons sent out by the servers. +Since hardware broadcasting requires special hardware capabilities, we are +required to provide additional configuration information when EPICS is +extended to operate over a wide area network (WAN).
+ +Channel Access is implemented using internet protocols (IP). IP addresses +are divided into host and network portions. The boundary between each portion +is determined by the IP netmask. Portions of the IP address corresponding to +zeros in the netmask specify the hosts address within an IP subnet. Portions +of the IP address corresponding to binary ones in the netmask specify the +address of a host's IP subnet. Normally the scope of a broadcasted frame will +be limited to one IP subnet. Addresses with the host address portion set to +all zeros or all ones are special. Modern IP kernel implementations reserve +destination addresses with the host portion set to all ones for the purpose of +addressing broadcasts to a particular subnet. In theory we can issue a +broadcast frame on any broadcast capable LAN within the interconnected +internet by specifying the proper subnet address combined with a host portion +set to all ones. In practice these "directed broadcasts" are frequently +limited by the default router configuration. The proper directed broadcast +address required to reach a particular host can be obtained by logging into +that host and typing the command required by your local operating environment. +Ignore the loop back interface and use the broadcast address associated with +an interface connected to a path through the network to your client. Typically +there will be only one Ethernet interface.
+ +| UNIX | +ifconfig -a | +
| vxWorks | +ifShow | +
| Windows | +ipconfig | +
IP ports are positive integers. The IP address, port number, and protocol +type uniquely identify the source and destination of a particular frame +transmitted between computers. Servers are typically addressed by a well known +port number. Clients are assigned a unique ephemeral port number during +initialization. IP ports below 1024 are reserved for servers that provide +standardized facilities such as mail or file transfer. Port number between +1024 and 5000 are typically reserved for ephemeral port number +assignments.
+ +Typically vxWorks hosts boot with routes configured for the host's subnet. +If a EPICSsystem 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 limit access to a particular host by not providing routes in that +host that reach outside of a limited set of subnets.
+ +| 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".
+ +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 +broadcast addresses, but this will often be the most convenient choice.
+ +| C shell | +setenv EPICS_CA_ADDR_LIST "1.2.3.255 8.9.10.255" | +
| bash | +export EPICS_CA_ADDR_LIST="1.2.3.255 8.9.10.255" | +
| vxWorks | +putenv ( "EPICS_CA_ADDR_LIST=1.2.3.255 8.9.10.255" ) | +
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.
+ +| Purpose | +Default | +Environment Variable | +
| CA Server | +5064 | +EPICS_CA_SERVER_PORT | +
| CA Beacons (sent to CA repeater daemon) | +5065 | +EPICS_CA_REPEATER_PORT | +
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 15.0 seconds.
+ +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, with 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. 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.
+ +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.
+ +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 +EPICS client side applications call core EPICS libraries which provide these +services. To set the correct time zone users must compute the number of +positive minutes west of GMT (maximum 720 inclusive) or the negative number of +minutes east of GMT (minimum -720 inclusive). This integer value is then +placed in the variable EPICS_TS_MIN_WEST.
+ +| Time Zone | +EPICS_TS_MIN_WEST | +
| USA Eastern | +300 | +
| USA Central | +360 | +
| USA Mountain | +420 | +
| USA Pacific | +480 | +
| Alaska | +540 | +
| Hawaii | +600 | +
| Japan | +-540 | +
| Germany | +-120 | +
| United Kingdom | +-60 | +
The environment variable EPICS_CA_MAX_ARRAY_BYTES determines the size of +the largest array that may pass through CA. This parameter must be set +appropriately for both the CA client and the CA server. In EPICS R3.14 CA +maintains a free list of 16384 byte network buffers that are used for ordinary +communication. If EPICS_CA_MAX_ARRAY_BYTES is larger than 16384 then a second +free list of larger data buffers is established when clients request +transportation of large arrays.
+ +| Name | +Range | +Default | +
| EPICS_CAS_ADDR_LIST | +{N.N.N.NN.N.N.N...} | +<none> | +
| EPICS_CAS_SERVER_PORT | +i > 5000 | ++ |
| EPICS_CAS_BEACON_ADDR_LIST | +{N.N.N.NN.N.N.N...} | ++ |
| EPICS_CAS_BEACON_PORT | +i > 5000 | ++ |
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. Otherwise, if EPICS_CA_ADDR_LIST is define its contents +will be used to augment this list.
+ +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 returns status indicating +the validity of the request and whether it was successfully enqueued to the +server.
+ +Significant performance gains may be realized if we don'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, 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().
+ +All arguments of type chtype expect one of the set of DBR_XXXX. These +constants, defined in db_access.h, enumerate which of the standard data types +you wish to transfer. There are data types for all of the C primitive types +and there are also compound types that include various process variable +properties such as units, limits, time stamp, or alarm status.
+ +Certain CA client initiated requests asynchronously execute an application +supplied call back in the client 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 structure "event_handler_args" +is passed to the application supplied callback. In this structure the field +"dbr" is a void pointer to any data that might be returned. The field "status" +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 field "dbr" will be set to NULL. The +fields "usr", "chid", "type", and "count" are set to the values specified when +the operation was initiated by the application.
+struct event_handler_args { void *usr; /* user argument supplied when event added */ chid chid; /* channel id */ long type; /* dbr type of the value returned */ long count; /* element count of the item(s) returned */ void *dbr; /* pointer to the value returned */ 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().
+ +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 +server tool (the IOC's database). Therefore, the ca_XXX() routines always +return the status of the operation directly to the caller with no opportunity +for asynchronous notification of failure via an exception handler.
+ +Certain routines have arguments that specify an address at which channel +access is to write a value of type DBR_XXXX. Care should be taken to ensure +that you have reserved space of sufficient size. 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. The dbr type size returning MACROS provided in db_access.h may also +be used.
+ +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.
+ +Channel connections through the network are inherently transient. Channels +are always initially assumed to be disconnected. A connection state change +call back function may be installed to be run whenever a channel connects or +disconnects. If a connection state change call back function is not installed +(if a nil function pointer is supplied) then the user must wait for successful +status from ca_pend_io prior to using the channel for the first time. Once the +channel connects the user can freely perform IO operations through the +channel, but he should expect that the channel might disconnect at any time +due to network interruptions or server restarts. Otherwise, if a connection +state change call back function is supplied, one of the arguments to this +function distinguishes between connect and disconnect events. If a connection +state change call back function is installed on a particular channel by the +user ca_pend_io will not block for the channel to connect. The user's +connection state change function will be run immediately when the channel is +created if the CA client and the server are both hosted in the same address +space (IOC).
+ +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.
+ +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() every 100 +milli-seconds.
+ +When CA invokes a user's call back function it will always wait for the +callback to run to completion prior to executing another call back +function.
+ +The error number and the error 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() on page 24 +for more information on this topic.
+status = ca_XXXX(); SEVCHK( status, "ca_XXXX() returned failure status"); if ( status & CA_M_SUCCESS ) { printf ( "The requested ca_XXXX() operation didn't complete successfully\n"); } if ( status != ECA_NORMAL ) { printf("The requested ca_XXXX() operation didn't complete successfully because \"%s\"\n", ca_message ( status ) ); }ca_context_create()#include <cadef.h>+
enum ca_preemptive_callback_select
+ { ca_disable_preemptive_callback, ca_enable_preemptive_callback };
+int ca_context_create ( enum ca_preemptive_callback_select SELECT ); This function should be called once prior to making any of the other +channel access calls.
+ +SELECTSpecifies if preemptive calback is allowed. If it is allowed your
+ 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 specify
+ ca_disable_preemptive_callback.
ECA_NORMAL - Normal successful completion
+ +ECA_ALLOCMEM - Failed, unable to allocate space in pool
+ +ca_context_destroy()
+ +ca_context_destroy()#include <cadef.h>+
void ca_context_destroy();+ +
Shut down a channel access client context and free any resources allocated. +On most operating systems this is performed automatically at process exit.
+ +ECA_NORMAL - Normal successful completion
+ +ca_search()#include <cadef.h>typedef void ( *pCallBack ) ( struct connection_handler_args );int ca_search_and_connect ( const char *PROCESS_VARIABLE_NAME, chid *PCHID;, pCallBack USERFUNC, void *PUSER );int ca_search ( const char *PROCESS_VARIABLE_NAME,+ +chid *PCHID);
Create a CA channel. This function requests that the CA library should +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_search() 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 supplied 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.
+ +There are two ways to obtain asynchronous notification when a channel +enters 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.
+ +Due to the inherently transient nature of network connections CA will not +guarantee the order of connection call backs relative to the order that +ca_search() calls are made by the application, and CA will not guarantee that +once a channel enters a connected state that it will remain connected.
+ +A better name for this function would be ca_create_channel().
+ +PROCESS_VARIABLE_NAMEA nilerminated 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
+PCHIDThe user supplied channel identifier storage is overwritten with a + channel identifier if this routine is successful.
+USERFUNCOptional address of the user's call back function to be run when + the connection state changes. Casual users of channel access may decide + to set this field to nil or 0 if they do not need to have a call back + function run in response to each connection state change event.
+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.
+ECA_NORMAL - Normal successful completion
+ +ECA_BADTYPE - Invalid DBR_XXXX type
+ +ECA_STRTOBIG - Unusually large string
+ +ECA_ALLOCMEM - Unable to allocate memory
+ +ca_clear_channel()#include <cadef.h>int ca_clear_channel (evid CHID); Shutdown and reclaim resources associated with a channel created by +ca_search or ca_search_and_connect.
+ +All remote operation 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, or ca_sg_pend are called. This allows several requests to be +efficiently sent over the network in one message.
+ +Clearing a channel does not cause its disconnect handler to be called, but +clearing a channel does shutdown and reclaim any channel state change event +subscriptions (monitors) registered with the channel.
+ +CHIDIdentifies the channel to delete.
+ECA_NORMAL - Normal successful completion
+ +ECA_BADCHID - Corrupted CHID
+ +ca_put()#include <cadef.h>int ca_put ( chtype TYPE, chid CHID, void *PVALUE ); int ca_array_put ( chtype TYPE, unsigned long COUNT, chid CHID, const void *PVALUE);+typedef void ( *pCallBack ) (struct event_handler_args );
int ca_put_callback ( chtype TYPE, chid CHID, const void *PVALUE, pCallBack PFUNC, void *USERARG ); int ca_array_put_callback ( chtype TYPE, unsigned long COUNT, chid CHID, const void *PVALUE, pCallBack PFUNC, void *USERARG );Write 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_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 gaurantee that +the server did not receive and process the request before it 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 calle. +This allows several requests to be efficiently combined into one message.
+ +TYPEThe 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
+COUNTElement count to be written to the specified channel. This must + match the array pointed to by PVALUE.
+CHIDChannel identifier
+PVALUEPointer to a value or array of values provided by the application + to be written to the channel.
+PFUNCaddress of user supplied function to be run when the requested + operation completes
+USERARGpointer sized variable retained and then passed back to user + supplied function above
+ECA_NORMAL - Normal successful completion
+ +ECA_BADCHID - Corrupted CHID
+ +ECA_BADTYPE - Invalid DBR_XXXX type
+ +ECA_BADCOUNT - Requested count larger than native element count
+ +ECA_STRTOBIG - Unusually large string supplied
+ +ECA_NOWTACCESS - Write access denied
+ +ECA_ALLOCMEM - Unable to allocate memory
+ +ca_pend_event()
+ +ca_get()#include <cadef.h>int ca_get ( chtype TYPE, chid CHID, void *PVALUE ); int ca_array_get ( chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE ); +typedef void ( *pCallBack ) (struct event_handler_args );
int ca_get_callback ( chtype TYPE, chid CHID, pCallBack USERFUNC, void *USERARG);int ca_array_get_callback ( chtype TYPE, unsigned long COUNT, chid CHID, pCallBack USERFUNC, void *USERARG ); Read 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.
+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. + +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.
+ +TYPEThe 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
+COUNTElement count to be read from the specified channel. Must match the + array pointed to by PVALUE.
+CHIDChannel identifier
+PVALUEPointer to an application supplied buffer where the current value + of the channel is to be written.
+USERFUNCAddress of user supplied function to be run when the requested + operation completes.
+USERARGPointer sized variable retained and then passsed back to user + supplied call back function above.
+ECA_NORMAL - Normal successful completion
+ +ECA_BADTYPE - Invalid DBR_XXXX type
+ +ECA_BADCHID - Corrupted CHID
+ +ECA_BADCOUNT - Requested count larger than native element count
+ +ECA_GETFAIL - A local database get failed
+ +ECA_NORDACCESS - Read access denied
+ +ECA_ALLOCMEM - Unable to allocate memory
+ +ca_pend_event()
+ +ca_add_event()#include <cadef.h>typedef void ( *pCallBack ) ( struct event_handler_args );int ca_add_event( chtype TYPE, chid CHID, pCallBack USERFUNC, void *USERARG, evid *PEVID); int ca_add_array_event( chtype TYPE, unsigned long COUNT, chid CHID, pCallBack USERFUNC, void *USERARG, double RESERVED, double RESERVED, double RESERVED, evid *PEVID );+
int ca_add_masked_array_event ( chtype TYPE, unsigned long COUNT, chid CHID, pCallBack USERFUNC, void *USERARG, double RESERVED, double RESERVED, double RESERVED, evid *PEVID, unsigned long MASK ); Reguister 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.
+ +Subscriptions may be installed or canceled against both connected and +disconnected channels. The specified USERFUNC is always called once +immediately after establishing each new connection with the process variable +or immediately from within ca_add_event() if the client and server 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.
+ +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, +or ca_sg_pend are called. This allows several requests to be efficiently sent +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.
+ +A better name for this function might have been ca_subscribe.
+ +TYPECOUNTCHIDUSRERFUNCUSERARGRESERVEDPEVIDMASKFor 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."
+ECA_NORMAL - Normal successful completion
+ +ECA_BADCHID - Corrupted CHID
+ +ECA_BADTYPE - Invalid DBR_XXXX type
+ +ECA_ALLOCMEM - Unable to allocate memory
+ +ECA_ADDFAIL - A local database event add failed
+ +ca_flush_io()
+ +ca_clear_event()#include <cadef.h>int ca_clear_event ( evid EVID );Cancel a subscription.
+ +All ca_clear_event() requests such as the above are accumulated (buffered) +and not forwarded to the server until one of ca_flush_io, ca_pend_io, +ca_pend_event, or ca_sg_pend are called. This allows several requests to be +efficiently sent together in one message.
+ +event id returned by ca_add_event()
+ECA_NORMAL - Normal successful completion
+ +ECA_BADCHID - Corrupted CHID SEE ALSO ca_add_event()
+ +ca_pend_io()#include <cadef.h>int ca_pend_io ( double TIMEOUT );This function flushes the send buffer and then waits until outstanding ca_get, and possibly also ca_search requests, complete or the specified time out +expires.
+If ECA_TIMEOUT is returned then get requests may be reissued followed by a +subsequent call to ca_pend_io. Specifically, the function will block only for +outstanding outstanding ca_get, and possibly also ca_search requests issued after the last call to +ca_pend_io() or issued after ca client context initialization whichever is +later. In contrast, a ca_search request should not be +reissued unless ca_clear_channel is called +first.
+ +If no ca_get, and possibly also ca_search requests, are 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 be long enough to take care of +what needs to be done taking into account worst case network delays. If +requests are timing out during situations when the network isn't broken then +you may need to increase the specified time-out.
+ +TIMEOUT interval of
+ zero specifies forever.ECA_NORMAL - Normal successful completion
+ +ECA_EVDISALLOW - Function inappropriate for use within an event handler
+ +ca_test_io()#include <cadef.h>int ca_test_io();This function tests to see if any ca_get, and +possibly also ca_search requests, are incomplete. It +will report the status of outstanding ca_get, and +possibly also ca_search requests, issued after the +last call to ca_pend_io() or CA context initialization whichever is later.
+ +ECA_IODONE - All IO operations completed
+ +ECA_IOINPROGRESS - IO operations still in progress
+ +ca_pend_event()#include <cadef.h>+
int ca_pend_event ( double TIMEOUT );+
int ca_poll ();+ +
When ca_pend_event is invoked the send buffer is flushed and CA background +activity is processed for TIMEOUT seconds.
+ +When ca_poll is invoked the send buffer is flushed and any outstanding CA +background activity is processed.
+ +The routine will not return before the time-out expires and all unfinished +channel access labor has been processed.
+ +TIMEOUTECA_NORMAL - Normal successful completion
+ +ECA_TIMEOUT - The operation timed out
+ +ECA_EVDISALLOW - Function inappropriate for use within a call back +handler
+ +ca_flush_io()#include <cadef.h>+
int ca_flush_io();+ +
Flush outstanding IO requests to the server. This routine might be useful +to users who need to flush requests prior to performing client side labor in +parallel with labor performed in the server.
+ +Outstanding requests are also sent whenever the buffer which holds them +becomes full.
+ +ECA_NORMAL - Normal successful completion
+ +ca_signal()#include <cadef.h>+int ca_signal ( long CA_STATUS,const char * CONTEXT_STRING );
void SEVCHK( CA_STATUS, CONTEXT_STRING );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.
+ +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.
+ +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.
+ +CA_STATUSThe status (error code) returned from a channel access + function.
+CONTEXT_STRINGA null terminated character string to supply as error context to + diagnostics.
+ECA_NORMAL - Normal successful completion
+ +ca_add_exception_event()#include <cadef.h>+
typedef void (*pCallback) ( struct exception_handler_args HANDLERARGS );+
int ca_add_exception_event ( pCallback USERFUNC, void *USERARG );+ +
Replace the currently installed exception handler call 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 +exception handler callbackis called.The default exceptionhandler printsa +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 +will supply the address in the client taskwhere thereturned value wasrequested +tobe written. For other failed operations the value of the addr field should +not be used.
+ +USERFUNCAddressof usercall back functionto beexecuted when exceptions + occur. Passing a nil value causes the default exception handler to be + reinstalled.
+USERARGpointer sized variable retained and passed back to user function + above
+void ca_exception_handler (
+ struct exception_handler_args args)
+{ char buf[512];
+ char *pName;
+
+ if ( args.chid ) {
+ pName = ca_name ( args.chid );
+ }
+ else{
+ pName = "?";
+ }
+ sprintf ( buf,
+ "%s - with request chan=%s op=%d data type=%s count=%d", args.ctx, pName, args.op, dbr_type_to_text ( args.type ), args.count ); ca_signal ( args.stat, buf ); } ca_add_exception_event ( ca_exception_handler , 0 );ECA_NORMAL - Normal successful completion
+ +ca_replace_printf_handler ()#include <cadef.h>typedef int caPrintfFunc ( const char *pFromat, va_list args );int ca_replace_printf_handler ( caPrintfFunc *PFUNC );Replace the default handler for formatted diagnostic message output. The +default handler uses fprintf to send messages to 'stderr'.
+ +PFUNCThe 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.
+int my_printf ( char *pformat, va_list args ) { int status; status = vfprintf( stderr, pformat, args); return status;}status = ca_replace_printf_handler ( my_printf );SEVCHK ( status, "failed to install my printf handler" );ECA_NORMAL - Normal successful completion
+ +ca_replace_access_rights_event()#include <cadef.h>typedef void ( *pCallBack )( struct access_rights_handler_args );int ca_replace_access_rights_event ( chid CHAN, pCallBack PFUNC );Install or replace the access rights state change call back handler for the +specified channel.
+ +The call back handler is called in the following situations.
+When a channel is created no access rights handler is installed.
+ +CHANThe channel identifier.
+PFUNCAddress of user supplied call back function. A nil pointer + uninstalls the current handler.
+ECA_NORMAL - Normal successful completion
+ +ca_modify_user_name()
+ +ca_modify_host_name()
+ +ca_field_type()#include <cadef.h>chtype ca_field_type ( CHID );Return the native type in the server of the process variable.
+ +CHIDchannel identifier
+TYPEThe data type code will be a member of the set of DBF_XXXX in + db_access.h. The constant TYPENOTCONN is returned if the channel is + disconnected.
+ca_element_count()#include <cadef.h>unsigned ca_element_count ( CHID );Return the maximum array element count in the server for the specified IO +channel.
+ +CHIDchannel identifier
+COUNTThe maximum array element count in the server. An element count of + zero is returned if the channel is disconnected.
+ca_name()#include <cadef.h>char * ca_name ( CHID );
+
+Return the name provided when the supplied channel id was
+created.
CHIDchannel identifier
+sPNAMEThe channel name. The string returned is valid as long as the + channel specified exists.
+ca_set_puser()#include <cadef.h>void ca_set_puser ( chid CHID, void *PUSER );Set a user private void pointer variable retained with each channel for use +at the users discretion.
+ +channel identifier
+user private void pointer
+ca_puser()#include <cadef.h>void * ca_puser ( CHID );
+
+Return a user private void pointer variable retained with each channel for +use at the users discretion.
+ +CHIDchannel identifier
+PUSERuser private pointer
+channel_state()+
/* channel connection state */#include <cadef.h>enum channel_state { cs_never_conn, /* valid chid, server not found or unavaliable */ cs_prev_conn, /* valid chid, previously connected to server */ cs_conn, /* valid chid, connected to server */ cs_closed }; /* channel deleted by user */enum channel_state ca_state ( CHID );Returns an enumerated type indicating the current state of the specified IO +channel.
+ +CHIDchannel identifier
+STATEthe conection state
+ca_message()#include <cadef.h>const char * ca_message ( STATUS );return a message character string corresponding to a user specified CA +status code.
+ +STATUSa CA status code
+the corresponding error message string
+ca_host_name()#include <cadef.h>char * ca_host_name ( CHID );Return a character string which contains the name of the host to which a +channel is currently connected.
+ +CHIDthe channel identifier
+STRINGThe process variable server's host name. If the channel is + disconnected the string "<disconnected>" is returned.
+ca_read_access()#include <cadef.h>int ca_read_access ( CHID );Returns boolean true if the client currently has read access to the +specified channel and boolean false otherwise.
+ +CHIDthe channel identifier
+STRINGboolean true if the client currently has read access to the + specified channel and boolean false otherwisex
+ca_write_access()#include <cadef.h>int ca_write_access ( CHID );Returns boolean true if the client currently has write access to the +specified channel and boolean false otherwise.
+ +CHIDthe channel identifier
+STRINGboolean true if the client currently has write access to the + specified channel and boolean false otherwise
+dbr_size[]#include <db_access.h>extern unsigned dbr_size[/*TYPE*/];An array that returns the size in bytes for a DBR_XXXX type.
+ +TYPEThe data type code. A member of the set of DBF_XXXX in + db_access.h.
+SIZEthe size in bytes of the specified type
+dbr_size_n()#include <db_access.h>unsigned dbr_size_n ( TYPE, COUNT );Returns the size in bytes for a DBR_XXXX type with COUNT elements. If the +DBR type is a structure then the value field is the last field in the +structure. If COUNT is greater than one then COUNT-1 elements are appended to +the end of the structure so that they can be addressed as an array through a +pointer to the value field.
+ +TYPEThe data type
+COUNTThe element count
+SIZEthe size in bytes of the specified type with the specified number + of elements
+dbr_value_size[]#include <db_access.h>extern unsigned dbr_value_size[/* TYPE */];The array dbr_value_size[TYPE] returns the size in bytes for the value +stored in a DBR_XXXX type. If the type is a structure the size of the value +field is returned otherwise the size of the type is returned.
+ +TYPEThe data type code. A member of the set of DBF_XXXX in + db_access.h.
+SIZEthe size in bytes of the value field if the type is a structure and + otherwise the size in bytes of the type
+ca_test_event()#include <cadef.h>+ +
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.
+ +void ca_test_event (); status = ca_add_event ( type, chid, ca_test_event, NULL, NULL ); SEVCHK ( status, .... ); ca_sg_create()#include <cadef.h>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.
+ +Any number of asynchronous groups can have application requested operations +outstanding within them at any given time.
+ +Arguments
+PGIDPointer to a user supplied CA_SYNC_GID.
+ExamplesCA_SYNC_GID gid; status = ca_sg_create ( &gid ); SEVCHK ( status, Sync group create failed ); ReturnsECA_NORMAL - Normal successful completion
+ +ECA_ALLOCMEM - Failed, unable to allocate memory
+ +See Alsoca_sg_block()
+ +ca_sg_test()
+ +ca_sg_reset()
+ +ca_sg_put()
+ +ca_sg_get()
+ +ca_sg_delete()#include <cadef.h>int ca_sg_delete ( CA_SYNC_GID GID ); Deletes a synchronous group.
+ +Identifier of the synchronous group to be deleted.
+CA_SYNC_GID gid; status = ca_sg_delete ( gid ); SEVCHK ( status, Sync group delete failed ); ECA_NORMAL - Normal successful completion
+ +ECA_BADSYNCGRP - Invalid synchronous group
+ +ca_sg_block()#include <cadef.h>int ca_sg_block ( CA_SYNC_GID GID, double timeout );DescriptionFlushes the send buffer and then waits until outstanding requests complete +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.
+ +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.
+ +ArgumentsIdentifier of the synchronous group.
+ExamplesCA_SYNC_GID gid; status = ca_sg_block(gid); SEVCHK(status, Sync group block failed); ReturnsECA_NORMAL - Normal successful completion
+ +ECA_TIMEOUT - The operation timed out
+ +ECA_EVDISALLOW - Function inappropriate for use within an event handler
+ +ECA_BADSYNCGRP - Invalid synchronous group
+ +See Alsoca_sg_test()
+ +ca_sg_reset()
+ +ca_sg_test()#include <cadef.h>int ca_sg_test ( CA_SYNC_GID GID ) Test to see if all requests made within a synchronous group have +completed.
+ +GIDIdentifier of the synchronous group.
+Test to see if all requests made within a synchronous group have +completed.
+ +CA_SYNC_GID gid;status = ca_sg_test ( gid );ECA_IODONE - IO operations completed
+ +ECA_IOINPROGRESS - Some IO operations still in progress
+ +ca_sg_reset()#include <cadef.h>int ca_sg_reset ( CA_SYNC_GID GID ) Reset the number of outstanding requests within the specified synchronous +group to zero so that ca_sg_test() will return ECA_IODONE and ca_sg_block() +will not block unless additional subsequent requests are made.
+ +ArgumentsGIDIdentifier of the synchronous group.
+ExamplesCA_SYNC_GID gid; status = ca_sg_reset(gid); ReturnsECA_NORMAL - Normal successful completion
+ +ECA_BADSYNCGRP - Invalid synchronous group
+ +ca_sg_put()#include <cadef.h>int ca_sg_array_put ( CA_SYNC_GID GID, chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE );Write a value, or array of values, to a channel and increment the +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.
+ +If a connection is lost and then resumed outstanding puts are not +reissued.
+ +ArgumentsGIDsynchronous group identifier
+TYPEThe 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.
+COUNTelement count to be written to the specified channel - must match + the array pointed to by PVALUE
+CHIDchannel identifier
+PVALUEA pointer to an application supplied buffer containing the value or + array of valuesReturns
+ReturnsECA_NORMAL - Normal successful completion
+ +ECA_BADSYNCGRP - Invalid synchronous group
+ +ECA_BADCHID - Corrupted CHID
+ +ECA_BADTYPE - Invalid DBR_XXXX type
+ +ECA_BADCOUNT - Requested count larger than native element count
+ +ECA_STRTOBIG - Unusually large string supplied
+ +ECA_PUTFAIL - A local database put failed
+ +ca_sg_get()#include <cadef.h>+
int ca_sg_array_get ( CA_SYNC_GID GID, chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE );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.
+ +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.
+ +If a connection is lost and then resumed outstanding gets are not +reissued.
+ +GIDIdentifier of the synchronous group.
+TYPEExternal 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
+COUNTElement count to be read from the specified channel. It must match + the array pointed to by PVALUE.
+CHIDchannel identifier
+PVALUEPointer to application supplied buffer that is to contain the value + or array of values to be returned
+ECA_NORMAL - Normal successful completion
+ +ECA_BADSYNCGRP - Invalid synchronous group
+ +ECA_BADCHID - Corrupted CHID
+ +ECA_BADCOUNT - Requested count larger than native element count
+ +ECA_BADTYPE - Invalid DBR_XXXX type
+ +ECA_GETFAIL - A local database get failed
+ +ca_client_status()int ca_client_status ( unsigned level );+ +
Prints information about the client context including, at higher intereest +levels, status for each channel.
+ +LEVELThe interest level. Increasing level produces increasing + detail.
+struct ca_client_context * ca_current_context ();+ +
Returns a pointer to the current thread's CA context. If none then nil is +returned.
+ +ca_attach_context()
+ +int ca_attach_context (struct ca_client_context *CONTEXT);+ +
Become a member of the specified CA context.
+ +CONTEXTA pointer to the CA context to join with.
+ECA_ISATTACHED - already attached to a CA context
+ +ca_current_context()
+ +ca_task_initialize()#include <cadef.h>+
int ca_task_initialize();+ +
This function should be called once prior to making any of the other +channel access calls.
+ +ECA_NORMAL - Normal successful completion
+ +ECA_ALLOCMEM - Failed, unable to allocate space in pool
+ +ca_task_exit()#include <cadef.h>+
int ca_task_exit();+ +
Shut down a channel access client context and free any resources allocated. +On most operating systems this is performed automatically at process exit.
+ +ECA_NORMAL - Normal successful completion
+ +acctst <PV name> [channel duplication count] [test repetition count]+ +
Channel access Client Library regression test.
+ +Test failure is indicated if the program stops prior to printing "test +complete". If unspecified, the channel duplication count is 20000. If +unspecified, the test repetition count is once only.
+ +catime <PV name> [channel count] [append number to pv name if true]+ +
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.
+ +<PV name>000000, <PV name>000001, ... <PV name>nnnnnn
+ +casw+ +
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.
+ +CA clients with unresolved channels reset their search request schedualing +timers whenever they see a beacon anomaly.
+ +This program can be useful to verify that configuration problems have not +resulted in false beacon anomalies that might cause CA to use unnecessary +additional network bandwidth and server CPU load when searching for unresolved +channels.
+ +caEventRate <PV name>
+ +Subscribe to the specified PV and periodically log its event rate.
+ +ca_test <PV name> [value to be written]
+ +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.
+ +