Los Alamos National Laboratory
SNS Division
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.
Last modified 2001/10/15 21:20:58
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 EPICS system is operating in a WAN environment it may be necessary to configure routes into the vxWorks system which enable a vxWorks based CA server to respond to requests originating outside it's subnet. An EPICS system manager can 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_create_channel()#include <cadef.h>typedef void ( *pCallBack ) ( struct connection_handler_args );int epicsShareAPI ca_create_channel
(
const char *PROCESS_VARIABLE_NAME,
caCh *USERFUNC,
void *PUSER,
capri priority,
chid *PCHID
);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.
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 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.
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.
PROCESS_VARIABLE_NAMEA 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.
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.
PUSERThe 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.
PRIORITYPCHIDECA_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_create_channel().
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 blocks until outstanding ca_get requests complete, and until channels created specifying nill connection handler function pointers connect for the first 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 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 should not be reissued 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 activities.
The delay specified to ca_pend_io() should take into account worst case network delays such as Ethernet collision backoff and retransmission.
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 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.
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
PNAMEThe 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. If
ca_disable_preemptive_callback is specified when ca_context_create()
is called ( or if ca_task_initialize() is called ) then additional threads
are not allowed to join the CA context because allowing other
threads to join implies that CA callbacks will be called preemptively from
more than one thread.
CONTEXTA pointer to the CA context to join with.
ECA_ISATTACHED - already attached to a CA context
ca_current_context()
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.