From cfa8a80ee178eb98a0ea475080ee94e5b0427df0 Mon Sep 17 00:00:00 2001 From: Jeff Hill Date: Fri, 3 Aug 2001 00:41:37 +0000 Subject: [PATCH] uninstalled --- src/ca/CAref.htm | 2415 ---------------------------------------------- 1 file changed, 2415 deletions(-) delete mode 100644 src/ca/CAref.htm diff --git a/src/ca/CAref.htm b/src/ca/CAref.htm deleted file mode 100644 index b83974009..000000000 --- a/src/ca/CAref.htm +++ /dev/null @@ -1,2415 +0,0 @@ - - - - - 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
-
-

-
-