- -
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.
- -