From 6beb555fcce4e60c5e3e6be4a1e1b873973fca9c Mon Sep 17 00:00:00 2001 From: Jeff Hill Date: Fri, 3 Aug 2001 00:41:56 +0000 Subject: [PATCH] installed into CVS --- src/ca/CAref.html | 2415 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2415 insertions(+) create mode 100644 src/ca/CAref.html diff --git a/src/ca/CAref.html b/src/ca/CAref.html new file mode 100644 index 000000000..b83974009 --- /dev/null +++ b/src/ca/CAref.html @@ -0,0 +1,2415 @@ + + + + + EPICS R3.14 Channel Access Reference Manual + + + +

 

+ +

EPICS R3.14 Channel Access Reference Manual

+ +

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.

+ +

 

+ +

Table of Contents

+ +

Configuration

+ + +

Function Call Interface General Guidelines

+ +

Function Call Interface Functionality Index 

+ + +

Function +Call Interface Function Index

+ + +

Deprecated Function Call Interface Function +Index

+ + +

Command Line Utilities

+ + +

Return Codes

+ +

Configuration

+ +

Why Reconfigure Channel Access

+ +

Typically reasons to reconfigure EPICS Channel Access:

+ + +

EPICS Environment Variable

+ +

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameRangeDefault
EPICS_CA_ADDR_LIST{N.N.N.N N.N.N.N ...}<none>
EPICS_CA_AUTO_ADDR_LIST{YES, NO}YES
EPICS_CA_CONN_TMOr > 0.1 seconds30.0
EPICS_CA_BEACON_PERIODr > 0.1 seconds15.0
EPICS_CA_REPEATER_PORTi > 50005065
EPICS_CA_SERVER_PORTi > 50005064
EPICS_CA_MAX_ARRAY_BYTESi >= 1638416384
EPICS_TS_MIN_WEST-720 < i <720 minutes360
+ +

Environment variables are set differently depending on the command line +shell that is in use.

+ + + + + + + + + + + + + + + + + + + + + + + + +
C shellsetenv EPICS_CA_ADDR_LIST  1.2.3.4
bashexport EPICS_CA_ADDR_LIST=1.2.3.4
vxWorks shellputenv ( "EPICS_CA_ADDR_LIST =1.2.3.4" )
DOS command lineset EPICS_CA_ADDR_LIST=1.2.3.4
Windows NT / 2000 / XPcontrol panel / system / environment tab
+ +

CA and Wide Area Networks

+ +

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

+ +

IP Network Administration Background Information

+ +

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.

+ + + + + + + + + + + + + + + + +
UNIXifconfig -a
vxWorksifShow
Windowsipconfig
+ +

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.

+ +

WAN Environment

+ +

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 shellsetenv EPICS_CA_ADDR_LIST "1.2.3.255 8.9.10.255"
bashexport EPICS_CA_ADDR_LIST="1.2.3.255 8.9.10.255"
vxWorksputenv ( "EPICS_CA_ADDR_LIST=1.2.3.255 8.9.10.255" )
+ +

IP port numbers

+ +

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.

+ + + + + + + + + + + + + + + + + + + +
PurposeDefaultEnvironment Variable
CA Server5064EPICS_CA_SERVER_PORT
CA Beacons (sent to CA repeater daemon)5065EPICS_CA_REPEATER_PORT
+ +

Disconnect Time Out Interval / Server Beacon Period

+ +

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.

+ +

Configuring the Time Zone

+ +

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 ZoneEPICS_TS_MIN_WEST
USA Eastern300
USA Central360
USA Mountain420
USA Pacific480
Alaska540
Hawaii600
Japan-540
Germany-120
United Kingdom-60
+ +

Configuring the Maximum Array Size

+ +

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.

+ +

Configuring a CA Server

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameRangeDefault
EPICS_CAS_ADDR_LIST{N.N.N.NN.N.N.N...}<none>
EPICS_CAS_SERVER_PORTi > 5000
EPICS_CAS_BEACON_ADDR_LIST{N.N.N.NN.N.N.N...}
EPICS_CAS_BEACON_PORTi > 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.

+ +

Function Call Interface General Guidelines

+ +

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 ) );
+
}
+ +

Function Call Reference

+ +

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 );
+ +

Description

+ +

This function should be called once prior to making any of the other +channel access calls.

+ +

Arguments

+
+
SELECT
+

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

+
+
+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

ECA_ALLOCMEM - Failed, unable to allocate space in pool

+ +

See Also

+ +

ca_context_destroy()

+ +

ca_context_destroy()

+
#include <cadef.h>
+
void ca_context_destroy();
+ +

Description

+ +

Shut down a channel access client context and free any resources allocated. +On most operating systems this is performed automatically at process exit.

+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

See Also

+ +

ca_context_create()

+ +

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 ); 
+ +

Description

+ +

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

+ +

Arguments

+
+
PROCESS_VARIABLE_NAME
+

A 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

+
+
+
+
PCHID
+

The user supplied channel identifier storage is overwritten with a + channel identifier if this routine is successful.

+
+
+
+
USERFUNC
+

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

+
+
+
+
PUSER
+

The value of this void pointer argument is retained in + storage associated with the specified channel. See the MACROS manual + page for reading and writing this field. Casual users of channel access + may wish to set this field to nil or 0.

+
+
+ +

Returns

+ +

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);
+ +

Description

+ +

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.

+ +

Arguments

+
+
CHID
+

Identifies the channel to delete.

+
+
+ +

Returns

+ +

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 );
+ +

Description

+ +

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.

+ +

Arguments

+
+
TYPE
+

The external type of the supplied value to be written. Conversion + will occur if this does not match the native type. Specify one from the + set of DBR_XXXX in db_access.h

+
+
+
+
COUNT
+

Element count to be written to the specified channel. This must + match the array pointed to by PVALUE.

+
+
+
+
CHID
+

Channel identifier

+
+
+
+
PVALUE
+

Pointer to a value or array of values provided by the application + to be written to the channel.

+
+
+
+
PFUNC
+

address of user supplied function to be run when the requested + operation completes

+
+
+
+
USERARG
+

pointer sized variable retained and then passed back to user + supplied function above

+
+
+ +

Returns

+ +

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

+ +

See Also

+ca_flush_io() + +

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 );
+ +

Description

+ +

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.

+ +

Arguments

+
+
TYPE
+

The external type of the user variable to return the value into. + Conversion will occur if this does not match the native type. Specify + one from the set of DBR_XXXX in db_access.h

+
+
+
+
COUNT
+

Element count to be read from the specified channel. Must match the + array pointed to by PVALUE.

+
+
+
+
CHID
+

Channel identifier

+
+
+
+
PVALUE
+

Pointer to an application supplied buffer where the current value + of the channel is to be written.

+
+
+
+
USERFUNC
+

Address of user supplied function to be run when the requested + operation completes.

+
+
+
+
USERARG
+

Pointer sized variable retained and then passsed back to user + supplied call back function above.

+
+
+ +

Returns

+ +

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

+ +

See Also

+ca_pend_io() + +

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 );
+ +

Description

+ +

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.

+ +

Arguments

+
+
TYPE
+
The type of value presented to the call back funstion. Conversion will + occur if it does not match native type. Specify one from the set of + DBR_XXXX in db_access.h
+
+
+
COUNT
+
The element count to be read from the specified channel. A count of + zero specifies the native elemnt count.
+
+
+
CHID
+
channel identifier
+
+
+
USRERFUNC
+
Address of user supplied callback function to be invoked with each + subscription update
+
+
+
USERARG
+
pointer sized variable retained and passed back to user callback + function
+
+
+
RESERVED
+
Reserved for future use. Specify 0.0 to remain upwardly + compatible.
+
+
+
PEVID
+
This is a pointer to user supplied event id which is overwritten if + successful. This event id can later be used to clear a specific + event. This option may may be omitted by passing a nil pointer.
+
+
+
MASK
+
A mask with bits set for each of the event trigger types requested. + The event trigger mask must be a logical or of one or more of the + following constants. +
    +
  • DBE_VALUE - Trigger events when the channel value exceeds the + monitor dead band
    • +
  • DBE_LOG - Trigger events when the channel value exceeds the + archival dead band
    • +
  • DBE_ALARM - Trigger events when the channel alarm state + changes.
    • +
+

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

+
+
+ +

Returns

+ +

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

+ +

See Also

+ca_pend_event() + +

ca_flush_io()

+ +

ca_clear_event()

+
#include <cadef.h>
+
int ca_clear_event ( evid EVID );
+ +

Description

+ +

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.

+ +

Arguments

+
+
EVID
+

event id returned by ca_add_event()

+
+
+ +

Returns

+ +

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 );
+ +

Description

+ +

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.

+ +

Arguments

+
+
TIMEOUT
+
Specifies the time out interval. A TIMEOUT interval of + zero specifies forever.
+
+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

ECA_EVDISALLOW - Function inappropriate for use within an event handler

+ +

See Also

+ca_get() + +

ca_search()

+ +

ca_test_io()

+ +

ca_test_io()

+
#include <cadef.h>
+
int ca_test_io();
+ +

Description

+ +

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.

+ +

Returns

+ +

ECA_IODONE - All IO operations completed

+ +

ECA_IOINPROGRESS - IO operations still in progress

+ +

See Also

+ +

ca_pend_io()

+ +

ca_pend_event()

+
#include <cadef.h>
+
int ca_pend_event ( double TIMEOUT );
+
int ca_poll ();
+ +

Description

+ +

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.

+ +

Arguments

+
+
TIMEOUT
+
The duration to block in this routine in seconds. A timeout of zero + seconds blocks forever.
+
+ +

Returns

+ +

ECA_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();
+ +

Description

+ +

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.

+ +

Returns

+ +

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 );
+ +

Description

+ +

Provide the error message character string associated with the supplied +channel access error code and the supplied error context to diagnostics. If +the error code indicates an unsuccessful operation a stack dump is printed, if +this capability is available on the local operating system, and execution is +terminated.

+ +

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.

+ +

Examples

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

+ +

Arguments

+
+
CA_STATUS
+

The status (error code) returned from a channel access + function.

+
+
+
+
CONTEXT_STRING
+

A null terminated character string to supply as error context to + diagnostics.

+
+
+ +

Returns

+ +

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 );
+ +

Description

+ +

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.

+ +

Arguments

+
+
USERFUNC
+

Addressof usercall back functionto beexecuted when exceptions + occur. Passing a nil value causes the default exception handler to be + reinstalled.

+
+
+
+
USERARG
+

pointer sized variable retained and passed back to user function + above

+
+
+ +

Example

+
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 );
+ +

Returns

+ +

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 );
+ +

Description

+ +

Replace the default handler for formatted diagnostic message output. The +default handler uses fprintf to send messages to 'stderr'.

+ +

Arguments

+
+
PFUNC
+

The address of a user supplied call back handler to be invoked when + CA prints diagnostic messages. Installing a nil pointer will cause the + default call back handler to be reinstalled.

+
+
+ +

Examples

+
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" );
+ +

Returns

+ +

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 );
+ +

Description

+ +

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.

+ +

Arguments

+
+
CHAN
+

The channel identifier.

+
+
+
+
PFUNC
+

Address of user supplied call back function. A nil pointer + uninstalls the current handler.

+
+
+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

See Also

+ +

ca_modify_user_name()

+ +

ca_modify_host_name()

+ +

ca_field_type()

+
#include <cadef.h>
+
chtype ca_field_type ( CHID );
+ +

Description

+ +

Return the native type in the server of the process variable.

+ +

Arguments

+
+
CHID
+

channel identifier

+
+
+ +

Returns

+
+
TYPE
+

The 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 );
+ +

Description

+ +

Return the maximum array element count in  the server for the specified IO +channel.

+ +

Arguments

+
+
CHID
+

channel identifier

+
+
+ +

Returns

+
+
COUNT
+

The 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 ); + +

Description

+ +

Return the name provided when the supplied channel id was +created.

+ +

Arguments

+
+
CHID
+

channel identifier

+
+
+ +

Returns

+
+
PNAME
+

The 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 );
+ +

Description

+ +

Set a user private void pointer variable retained with each channel for use +at the users discretion.

+ +

Arguments

+
+
CHID
+

channel identifier

+
+
+
+
PUSER
+

user private void pointer

+
+
+ +

ca_puser()

+
#include <cadef.h>
+void * ca_puser ( CHID ); + +

Description

+ +

Return a user private void pointer variable retained with each channel for +use at the users discretion.

+ +

Arguments

+
+
CHID
+

channel identifier

+
+
+ +

Returns

+
+
PUSER
+

user 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 );
+ +

Description

+ +

Returns an enumerated type indicating the current state of the specified IO +channel.

+ +

Arguments

+
+
CHID
+

channel identifier

+
+
+ +

Returns

+
+
STATE
+

the conection state

+
+
+ +

ca_message()

+
#include <cadef.h>
+
const char * ca_message ( STATUS );
+ +

Description

+ +

return a message character string corresponding to a user specified CA +status code.

+ +

Arguments

+
+
STATUS
+

a CA status code

+
+
+ +

Returns

+
+
STRING
+

the corresponding error message string

+
+
+ +

ca_host_name()

+
#include <cadef.h>
+
char * ca_host_name ( CHID );
+ +

Description

+ +

Return a character string which contains the name of the host to which a +channel is currently connected.

+ +

Arguments

+
+
CHID
+

the channel identifier

+
+
+ +

Returns

+
+
STRING
+

The 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 );
+ +

Description

+ +

Returns boolean true if the client currently has read access to the +specified channel and boolean false otherwise.

+ +

Arguments

+
+
CHID
+

the channel identifier

+
+
+ +

Returns

+
+
STRING
+

boolean 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 );
+ +

Description

+ +

Returns boolean true if the client currently has write access to the +specified channel and boolean false otherwise.

+ +

Arguments

+
+
CHID
+

the channel identifier

+
+
+ +

Returns

+
+
STRING
+

boolean 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*/];
+ +

Description

+ +

An array that returns the size in bytes for a DBR_XXXX type.

+ +

Arguments

+
+
TYPE
+

The data type code. A member of the set of DBF_XXXX in + db_access.h.

+
+
+ +

Returns

+
+
SIZE
+

the size in bytes of the specified type

+
+
+ +

dbr_size_n()

+
#include <db_access.h>
+
unsigned dbr_size_n  (  TYPE, COUNT  );
+ +

Description

+ +

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.

+ +

Arguments

+
+
TYPE
+

The data type

+
+
+
+
COUNT
+

The element count

+
+
+ +

Returns

+
+
SIZE
+

the 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 */];
+ +

Description

+ +

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.

+ +

Arguments

+
+
TYPE
+

The data type code. A member of the set of DBF_XXXX in + db_access.h.

+
+
+ +

Returns

+
+
SIZE
+

the 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>
+ +

Description

+
void ca_test_event ( struct event_handler_args );
+ +

A built-in subscription update call back handler for debugging purposes +that prints diagnostics to standard out.

+ +

Examples

+
void ca_test_event ();
+
status = ca_add_event ( type, chid, ca_test_event, NULL, NULL );
+
SEVCHK ( status, .... );
+ +

See Also

+ +

ca_add_event()

+ +

ca_sg_create()

+
#include <cadef.h>
+
int ca_sg_create ( CA_SYNC_GID *PGID );
+ +

Description

+ +

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

+
+
PGID
+

Pointer to a user supplied CA_SYNC_GID.

+
+
+ +

Examples

+
CA_SYNC_GID gid;
+
status = ca_sg_create ( &gid );
+
SEVCHK ( status, Sync group create failed );
+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

ECA_ALLOCMEM - Failed, unable to allocate memory

+ +

See Also

+ca_sg_delete() + +

ca_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 );
+ +

Description

+ +

Deletes a synchronous group.

+ +

Arguments

+
+
GID
+

Identifier of the synchronous group to be deleted.

+
+
+ +

Examples

+
CA_SYNC_GID gid;
+
status = ca_sg_delete ( gid );
+
SEVCHK ( status, Sync group delete failed );
+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

ECA_BADSYNCGRP - Invalid synchronous group

+ +

See Also

+ +

ca_sg_create()

+ +

ca_sg_block()

+
#include <cadef.h>
+
int ca_sg_block ( CA_SYNC_GID GID, double timeout );
+ +

Description

+ +

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

+ +

Arguments

+
+
GID
+

Identifier of the synchronous group.

+
+
+ +

Examples

+
CA_SYNC_GID gid;
+
status = ca_sg_block(gid);
+
SEVCHK(status, Sync group block failed);
+ +

Returns

+ +

ECA_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 Also

+ +

ca_sg_test()

+ +

ca_sg_reset()

+ +

ca_sg_test()

+
#include <cadef.h>
+
int ca_sg_test  ( CA_SYNC_GID GID )
+ +

Description

+ +

Test to see if all requests made within a synchronous group have +completed.

+ +

Arguments

+
+
GID
+

Identifier of the synchronous group.

+
+
+ +

Description

+ +

Test to see if all requests made within a synchronous group have +completed.

+ +

Examples

+
CA_SYNC_GID gid;
+
status = ca_sg_test ( gid );
+ +

Returns

+ +

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 )
+ +

Description

+ +

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.

+ +

Arguments

+
+
GID
+

Identifier of the synchronous group.

+
+
+ +

Examples

+
CA_SYNC_GID gid;
+
status = ca_sg_reset(gid);
+ +

Returns

+ +

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

+ +

Arguments

+
+
GID
+

synchronous group identifier

+
+
+
+
TYPE
+

The type of supplied value. Conversion will occur if it does not + match the native type. Specify one from the set of DBR_XXXX in + db_access.h.

+
+
+
+
COUNT
+

element count to be written to the specified channel - must match + the array pointed to by PVALUE

+
+
+
+
CHID
+

channel identifier

+
+
+
+
PVALUE
+

A pointer to an application supplied buffer containing the value or + array of valuesReturns

+
+
+ +

Returns

+ +

ECA_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

+ +

See Also

+ +

ca_flush_io()

+ +

ca_sg_get()

+
#include <cadef.h>
+
int ca_sg_array_get ( CA_SYNC_GID GID,
+
        chtype TYPE, unsigned long COUNT,
+
        chid CHID, void *PVALUE );
+ +

Description

+ +

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.

+ +

Arguments

+
+
GID
+

 Identifier of the synchronous group.

+
+
+
+
TYPE
+

External type of returned value. Conversion will occur if this does + not match native type. Specify one from the set of DBR_XXXX in + db_access.h

+
+
+
+
COUNT
+

Element count to be read from the specified channel. It must match + the array pointed to by PVALUE.

+
+
+
+
CHID
+

channel identifier

+
+
+
+
PVALUE
+

Pointer to application supplied buffer that is to contain the value + or array of values to be returned

+
+
+ +

Returns

+ +

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

+ +

See Also

+ +

ca_pend_io()

+ +

ca_flush_io()

+ +

ca_get_callback()

+ +

ca_client_status()

+
int ca_client_status ( unsigned level );
+ +

Description

+ +

Prints information about the client context including, at higher intereest +levels, status for each channel.

+ +

Arguments

+
+
LEVEL
+

The interest level. Increasing level produces increasing + detail.

+
+
+ +

ca_current_context()

+
struct ca_client_context * ca_current_context ();
+ +

Description

+ +

Returns a pointer to the current thread's CA context. If none then nil is +returned.

+ +

See Also

+ +

ca_attach_context()

+ +

ca_attach_context()

+
int ca_attach_context (struct ca_client_context *CONTEXT);
+ +

Description

+ +

Become a member of the specified CA context.

+ +

Arguments

+
+
CONTEXT
+

A pointer to the CA context to join with.

+
+
+ +

Returns

+ +

ECA_ISATTACHED - already attached to a CA context

+ +

See Also

+ +

ca_current_context()

+ +

Deprecated Functions

+ +

ca_task_initialize()

+
#include <cadef.h>
+
int ca_task_initialize();
+ +

Description

+ +

This function should be called once prior to making any of the other +channel access calls.

+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

ECA_ALLOCMEM - Failed, unable to allocate space in pool

+ +

See Also

+ +

ca_task_exit()

+ +

ca_task_exit()

+
#include <cadef.h>
+
int ca_task_exit();
+ +

Description

+ +

Shut down a channel access client context and free any resources allocated. +On most operating systems this is performed automatically at process exit.

+ +

Returns

+ +

ECA_NORMAL - Normal successful completion

+ +

See Also

+ +

ca_task_initialize()

+ +

Command Line Utilities

+ +

acctst

+
acctst <PV name> [channel duplication count] [test repetition count]
+ +

Description

+ +

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

+
catime <PV name> [channel count] [append number to pv name if true]
+ +

Description

+ +

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

+
casw
+ +

Description

+ +

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

+ +

caEventRate <PV name>

+ +

Description

+ +

Subscribe to the specified PV and periodically log its event rate.

+ +

ca_test

+ +

ca_test <PV name> [value to be written]

+ +

Description

+ +

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.

+ +

Return Codes

+
+
ECA_NORMAL
+
normal successful completion
+
+
+
ECA_ALLOCMEM
+
unable to allocate memory
+
+
+
ECA_BADTYPE
+
invalid DBR_XXXX type
+
+
+
ECA_STRTOBIG
+
unusually large string supplied
+
+
+
ECA_BADCHID
+
ivalid channel identifier
+
+
+
ECA_BADCOUNT
+
requested count larger than native element count
+
+
+
ECA_PUTFAIL
+
a write request failed in the server
+
+
+
ECA_GETFAIL
+
a read request faile din the server
+
+
+
ECA_ADDFAIL
+
unable to instal subscription request
+
+
+
ECA_TIMEOUT
+
requested operation timed out
+
+
+
ECA_EVDISALLOW
+
function called was inappropriate for use within a callback + function
+
+
+
ECA_IODONE
+
IO operations completed
+
+
+
ECA_IOINPROGRESS
+
some IO operations still in progress
+
+
+
ECA_BADSYNCGRP
+
invalid synchronous group identifier
+
+
+
ECA_NORDACCESS
+
read access denied
+
+
+
ECA_NOWTACCESS
+
write access denied
+
+

+
+