2417 lines
83 KiB
HTML
2417 lines
83 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
||
"http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html">
|
||
<title>EPICS R3.14 Channel Access Reference Manual</title>
|
||
</head>
|
||
|
||
<body lang="en">
|
||
<hr>
|
||
|
||
<h1>EPICS R3.14 Channel Access Reference Manual</h1>
|
||
<address>
|
||
<a href="mailto:johill@lanl.gov">Jeffrey O. Hill</a><br>
|
||
|
||
</address>
|
||
|
||
<p><font size="2">Los Alamos National Laboratory</font></p>
|
||
|
||
<p>SNS Division<font size="2"></font></p>
|
||
|
||
<p><font size="1">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.</font></p>
|
||
|
||
<p><img src="http://www.w3.org/Amaya/Icons/w3c-amaya.gif" alt="W3C-Amaya"
|
||
height="31" width="88"> <a href="http://validator.w3.org/check/referer"> <img
|
||
border="0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"
|
||
height="31" width="88"></a></p>
|
||
|
||
<p><small>Last modified $Date$ </small></p>
|
||
<hr>
|
||
|
||
<h2>Table of Contents</h2>
|
||
|
||
<h3><a target="_top" href="#Configuration">Configuration</a></h3>
|
||
<ul>
|
||
<li><a href="#EPICS">EPICS Environment Variables</a></li>
|
||
<li><a href="#CA and Wide Area Networks">CA and Wide Area Networks</a></li>
|
||
<li><a href="#Network">IP Network Administration Background
|
||
Information</a></li>
|
||
<li><a href="#Environmen">WAN Environment</a></li>
|
||
<li><a href="#IP port numbers">IP port numbers</a></li>
|
||
<li><a href="#Disconnect">Disconnect Time Out Interval / Server Beacon
|
||
Period</a></li>
|
||
<li><a href="#Configurin">Configuring the Time Zone</a></li>
|
||
<li><a href="#Configurin1">Configuring the maximum array size</a></li>
|
||
<li><a href="#Configurin2">Configuring a CA server</a></li>
|
||
</ul>
|
||
|
||
<h3><a href="#Notes">Function Call Interface General Guidelines</a></h3>
|
||
|
||
<h3>Function Call Interface Functionality Index </h3>
|
||
<ul>
|
||
<li><a href="#ca_tasjk_initialize">initialize CA client context</a></li>
|
||
<li><a href="#ca_task_exit">terminate CA client context</a></li>
|
||
<li><a href="#ca_search">create a channel</a></li>
|
||
<li><a href="#ca_clear_channel">delete a channel</a></li>
|
||
<li><a href="#ca_put">write to a channel</a></li>
|
||
<li><a href="#ca_get">read from a channel</a></li>
|
||
<li><a href="#ca_add_event">subscribe for state change updates</a></li>
|
||
<li><a href="#ca_clear_event">cancel a subscription</a></li>
|
||
<li><a href="#ca_pend_io">block for certain requests to complete</a></li>
|
||
<li><a href="#ca_test_io">test to see if certain requests have
|
||
completed</a></li>
|
||
<li><a href="#ca_pend_event">process CA client library background
|
||
activities</a></li>
|
||
<li><a href="#ca_flush_io">flush outstanding requests to the server</a></li>
|
||
<li><a href="#ca_add_exception_event">replace the default exception
|
||
handler</a></li>
|
||
</ul>
|
||
|
||
<h3><a
|
||
href="file://E:\users\hill\epicsDvl\epics\base\src\ca\CAref.htm#Function Call Reference">Function
|
||
Call Interface Function Index</a></h3>
|
||
<ul>
|
||
<li><a href="#ca_context_create">ca_context_create</a></li>
|
||
<li><a href="#ca_context_destroy">ca_context_destroy</a></li>
|
||
<li><a href="#ca_search">ca_search</a></li>
|
||
<li><a href="#ca_clear_channel">ca_clear_channel</a></li>
|
||
<li><a href="#ca_put">ca_put</a></li>
|
||
<li><a href="#ca_get">ca_get</a></li>
|
||
<li><a href="#ca_add_event">ca_add_event</a></li>
|
||
<li><a href="#ca_clear_event">ca_clear_event</a></li>
|
||
<li><a href="#ca_pend_io">ca_pend_io</a></li>
|
||
<li><a href="#ca_test_io">ca_test_io</a></li>
|
||
<li><a href="#ca_pend_event">ca_pend_event</a></li>
|
||
<li><a href="#ca_flush_io">ca_flush_io</a></li>
|
||
<li><a href="#ca_signal">ca_signal</a></li>
|
||
<li><a href="#ca_addException_event">ca_add_exception_event</a></li>
|
||
<li><a href="#ca_replace_printf_handler ">ca_replace_printf_handler</a></li>
|
||
<li><a
|
||
href="#ca_replace_access_rights_event">ca_replace_access_rights_event</a></li>
|
||
<li><a href="#ca_field_type">ca_field_type</a></li>
|
||
<li><a href="#ca_element_count">ca_element_count</a></li>
|
||
<li><a href="#ca_name">ca_name</a></li>
|
||
<li><a href="#ca_set_puser">ca_set_puser</a></li>
|
||
<li><a href="#ca_puser">ca_puser</a></li>
|
||
<li><a href="#channel_state">channel_state</a></li>
|
||
<li><a href="#ca_message">ca_message</a></li>
|
||
<li><a href="#ca_host_name">ca_host_name</a></li>
|
||
<li><a href="#ca_read_access">ca_read_access</a></li>
|
||
<li><a href="#ca_write_access">ca_write_access</a></li>
|
||
<li><a href="#dbr_size">dbr_size</a></li>
|
||
<li><a href="#dbr_size_n">dbr_size_n</a></li>
|
||
<li><a href="#dbr_value_size">dbr_value_size</a></li>
|
||
<li><a href="#ca_test_event">ca_test_event</a></li>
|
||
<li><a href="#ca_sg_create">ca_sg_create</a></li>
|
||
<li><a href="#ca_sg_delete">ca_sg_delete</a></li>
|
||
<li><a href="#ca_sg_block">ca_sg_block</a></li>
|
||
<li><a href="#ca_sg_test">ca_sg_test</a></li>
|
||
<li><a href="#ca_sg_reset">ca_sg_reset</a></li>
|
||
<li><a href="#ca_sg_put">ca_sg_put</a></li>
|
||
<li><a href="#ca_sg_get">ca_sg_get</a></li>
|
||
<li><a href="#ca_current_context">ca_current_context</a></li>
|
||
<li><a href="#ca_attach_context">ca_attach_context </a></li>
|
||
<li><a href="#ca_client_status">ca_client_status</a></li>
|
||
</ul>
|
||
|
||
<h3><a href="#Deprecated">Deprecated Function Call Interface Function
|
||
Index</a></h3>
|
||
<ul>
|
||
<li><a href="#L6771">ca_task_initialize</a></li>
|
||
<li><a href="#ca_task_exit">ca_task_exit</a></li>
|
||
</ul>
|
||
|
||
<h3><a href="#Command">Command Line Utilities</a></h3>
|
||
<ul>
|
||
<li><a href="#acctst">acctst - CA client library regression test</a></li>
|
||
<li><a href="#catime">catime - CA client library performance test</a></li>
|
||
<li><a href="#casw">casw - CA server beacon anomaly logging</a></li>
|
||
<li><a href="#caEventRat">caEventRate - PV event rate logging</a></li>
|
||
<li><a href="#ca_test">ca_test - dump each external type to the
|
||
console</a></li>
|
||
</ul>
|
||
|
||
<h3><a href="#Return">Return Codes</a></h3>
|
||
|
||
<h2><a name="Configuration"></a>Configuration</h2>
|
||
|
||
<p>Why Reconfigure Channel Access</p>
|
||
|
||
<p>Typically reasons to reconfigure EPICS Channel Access:</p>
|
||
<ul>
|
||
<li>Two independent control systems must share a network without fear of
|
||
interaction</li>
|
||
<li>A test system must not interact with an operational system</li>
|
||
<li>Use of address lists instead of broadcasts for name resolution and
|
||
server beacons</li>
|
||
<li>Control system occupies multiple IP subnets</li>
|
||
<li>Nonstandard client disconnect time outs or server beacon intervals</li>
|
||
<li>Specify the local time zone</li>
|
||
<li>Transport of large arrays</li>
|
||
</ul>
|
||
|
||
<h3><a name="EPICS">EPICS Environment Variables</a></h3>
|
||
|
||
<p>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.</p>
|
||
|
||
<table cellspacing="1" cellpadding="1" width="75%" border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>Name</td>
|
||
<td>Range</td>
|
||
<td>Default</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_ADDR_LIST</td>
|
||
<td>{N.N.N.N N.N.N.N ...}</td>
|
||
<td><none></td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_AUTO_ADDR_LIST</td>
|
||
<td>{YES, NO}</td>
|
||
<td>YES</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_CONN_TMO</td>
|
||
<td>r > 0.1 seconds</td>
|
||
<td>30.0</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_BEACON_PERIOD</td>
|
||
<td>r > 0.1 seconds</td>
|
||
<td>15.0</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_REPEATER_PORT</td>
|
||
<td>i > 5000</td>
|
||
<td>5065</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_SERVER_PORT</td>
|
||
<td>i > 5000</td>
|
||
<td>5064</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CA_MAX_ARRAY_BYTES</td>
|
||
<td>i >= 16384</td>
|
||
<td>16384</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_TS_MIN_WEST</td>
|
||
<td>-720 < i <720 minutes</td>
|
||
<td>360</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Environment variables are set differently depending on the command line
|
||
shell that is in use.</p>
|
||
|
||
<table border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>C shell</td>
|
||
<td>setenv EPICS_CA_ADDR_LIST 1.2.3.4</td>
|
||
</tr>
|
||
<tr>
|
||
<td>bash</td>
|
||
<td>export EPICS_CA_ADDR_LIST=1.2.3.4</td>
|
||
</tr>
|
||
<tr>
|
||
<td>vxWorks shell</td>
|
||
<td>putenv ( "EPICS_CA_ADDR_LIST =1.2.3.4" )</td>
|
||
</tr>
|
||
<tr>
|
||
<td>DOS command line</td>
|
||
<td>set EPICS_CA_ADDR_LIST=1.2.3.4</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Windows NT / 2000 / XP</td>
|
||
<td>control panel / system / environment tab</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3><a name="CA and Wide Area Networks"></a>CA and Wide Area Networks</h3>
|
||
|
||
<p>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).</p>
|
||
|
||
<h3><a name="Network">IP Network Administration Background
|
||
Information</a></h3>
|
||
|
||
<p>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.</p>
|
||
|
||
<table border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>UNIX</td>
|
||
<td>ifconfig -a</td>
|
||
</tr>
|
||
<tr>
|
||
<td>vxWorks</td>
|
||
<td>ifShow</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Windows</td>
|
||
<td>ipconfig</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3><a name="Environmen">WAN Environment</a></h3>
|
||
|
||
<p>Typically vxWorks hosts boot with routes configured for the host's subnet.
|
||
If a EPICS system is operating in a WAN environment it may be necessary to
|
||
configure routes into the vxWorks system which enable a vxWorks based CA
|
||
server to respond to requests originating outside it's subnet. An EPICS system
|
||
manager can limit access to a particular host by not providing routes in that
|
||
host that reach outside of a limited set of subnets.</p>
|
||
|
||
<table border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>routeShow()</td>
|
||
</tr>
|
||
<tr>
|
||
<td>hostAdd "the-router", "N.N.N.N"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>routeAdd "0","the-router"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>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".</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<table border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>C shell</td>
|
||
<td>setenv EPICS_CA_ADDR_LIST "1.2.3.255 8.9.10.255"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>bash</td>
|
||
<td>export EPICS_CA_ADDR_LIST="1.2.3.255 8.9.10.255"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>vxWorks</td>
|
||
<td>putenv ( "EPICS_CA_ADDR_LIST=1.2.3.255 8.9.10.255" )</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3><a name="IP port numbers"></a>IP port numbers</h3>
|
||
|
||
<p>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.</p>
|
||
|
||
<table cellspacing="1" cellpadding="1" width="80%" border="1">
|
||
<col><tbody>
|
||
<tr>
|
||
<td>Purpose</td>
|
||
<td>Default</td>
|
||
<td>Environment Variable</td>
|
||
</tr>
|
||
<tr>
|
||
<td>CA Server</td>
|
||
<td>5064</td>
|
||
<td>EPICS_CA_SERVER_PORT</td>
|
||
</tr>
|
||
<tr>
|
||
<td>CA Beacons (sent to CA repeater daemon)</td>
|
||
<td>5065</td>
|
||
<td>EPICS_CA_REPEATER_PORT</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3><a name="Disconnect">Disconnect Time Out Interval / Server Beacon
|
||
Period</a></h3>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3><a name="Configurin">Configuring the Time Zone</a></h3>
|
||
|
||
<p><em>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.</em></p>
|
||
|
||
<p>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.</p>
|
||
|
||
<table cellspacing="1" cellpadding="1" width="75%" border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>Time Zone</td>
|
||
<td>EPICS_TS_MIN_WEST</td>
|
||
</tr>
|
||
<tr>
|
||
<td>USA Eastern</td>
|
||
<td>300</td>
|
||
</tr>
|
||
<tr>
|
||
<td>USA Central</td>
|
||
<td>360</td>
|
||
</tr>
|
||
<tr>
|
||
<td>USA Mountain</td>
|
||
<td>420</td>
|
||
</tr>
|
||
<tr>
|
||
<td>USA Pacific</td>
|
||
<td>480</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Alaska</td>
|
||
<td>540</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Hawaii</td>
|
||
<td>600</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Japan</td>
|
||
<td>-540</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Germany</td>
|
||
<td>-120</td>
|
||
</tr>
|
||
<tr>
|
||
<td>United Kingdom</td>
|
||
<td>-60</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3><a name="Configurin1">Configuring the Maximum Array Size</a></h3>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3><a name="Configurin2">Configuring a CA Server</a></h3>
|
||
|
||
<table cellspacing="1" cellpadding="1" width="75%" border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td>Name</td>
|
||
<td>Range</td>
|
||
<td>Default</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CAS_ADDR_LIST</td>
|
||
<td>{N.N.N.NN.N.N.N...}</td>
|
||
<td><none></td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CAS_SERVER_PORT</td>
|
||
<td>i > 5000</td>
|
||
<td></td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CAS_BEACON_ADDR_LIST</td>
|
||
<td>{N.N.N.NN.N.N.N...}</td>
|
||
<td></td>
|
||
</tr>
|
||
<tr>
|
||
<td>EPICS_CAS_BEACON_PORT</td>
|
||
<td>i > 5000</td>
|
||
<td></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>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.</p>
|
||
|
||
<h2><a name="Notes"></a>Function Call Interface General Guidelines</h2>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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().</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
<pre><code>struct event_handler_args { </code></pre>
|
||
<pre><code> void *usr; /* user argument supplied when event added */ </code></pre>
|
||
<pre><code> chid chid; /* channel id */ </code></pre>
|
||
<pre><code> long type; /* dbr type of the value returned */ </code></pre>
|
||
<pre><code> long count; /* element count of the item(s) returned */ </code></pre>
|
||
<pre><code> void *dbr; /* pointer to the value returned */ </code></pre>
|
||
<pre><code> int status; /* ECA_XXX status of the op from server */ </code></pre>
|
||
<pre><code>}; </code></pre>
|
||
|
||
<p><font face="Times New Roman">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().</font></p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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).</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
<pre><code>status = ca_XXXX(); </code></pre>
|
||
<pre><code>SEVCHK( status, "ca_XXXX() returned failure status"); </code></pre>
|
||
<pre><code></code></pre>
|
||
<pre><code>if ( status & CA_M_SUCCESS ) { </code></pre>
|
||
<pre><code> printf ( "The requested ca_XXXX() operation didn't complete successfully\n"); </code></pre>
|
||
<pre><code>} </code></pre>
|
||
<pre><code></code></pre>
|
||
<pre><code>if ( status != ECA_NORMAL ) { </code></pre>
|
||
<pre><code> printf("The requested ca_XXXX() operation didn't complete successfully because \"%s\"\n",</code></pre>
|
||
<pre><code> ca_message ( status ) ); </code></pre>
|
||
<pre><code>}</code></pre>
|
||
|
||
<h2><a name="Function Call Reference"></a>Function Call Reference</h2>
|
||
|
||
<h3><code><a name="ca_context_create">ca_context_create()</a></code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre><code>enum ca_preemptive_callback_select
|
||
{ ca_disable_preemptive_callback, ca_enable_preemptive_callback };
|
||
int ca_context_create ( enum ca_preemptive_callback_select SELECT ); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>This function should be called once prior to making any of the other
|
||
channel access calls.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>SELECT</code></dt>
|
||
<dd><p>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
|
||
<code>ca_disable_preemptive_callback.</code></p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_ALLOCMEM - Failed, unable to allocate space in pool</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p>ca_context_destroy()</p>
|
||
|
||
<h3><code><a name="ca_context_destroy">ca_context_destroy()</a></code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre>void ca_context_destroy(); </pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Shut down a channel access client context and free any resources allocated.
|
||
On most operating systems this is performed automatically at process exit.</p>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a>ca_context_create()</a></p>
|
||
|
||
<h3><a name="ca_search"><code>ca_search()</code></a></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>typedef void ( *pCallBack ) (</code></pre>
|
||
<pre><code> struct connection_handler_args );</code></pre>
|
||
<pre><code>int ca_search_and_connect (</code></pre>
|
||
<pre><code> const char *PROCESS_VARIABLE_NAME,</code></pre>
|
||
<pre><code> chid *PCHID;,</code></pre>
|
||
<pre><code> pCallBack USERFUNC,</code></pre>
|
||
<pre><code> void *PUSER );</code></pre>
|
||
<pre><code>int ca_search ( </code></pre>
|
||
<pre><code> const char *PROCESS_VARIABLE_NAME,</code></pre>
|
||
<pre><code> chid *PCHID</code><code> ); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>There are two ways to obtain asynchronous notification when a channel
|
||
enters a connected state.</p>
|
||
<ul>
|
||
<li>The first and simplest method requires that you call ca_pend_io(), and
|
||
wait for successful completion, prior to using a channel that was created
|
||
will a nil connection call back handler installed ( or by calling
|
||
ca_search() ).</li>
|
||
<li>The second method requires that you establish a connection handler by
|
||
supplying a non-zero connection callback function. This connection handler
|
||
is called whenever the connection state of the channel changes. If you
|
||
have installed a connection handler then ca_pend_io() will <em>not</em>
|
||
block waiting for the channel to enter a connected state.</li>
|
||
</ul>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>A better name for this function would be ca_create_channel().</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>PROCESS_VARIABLE_NAME</code></dt>
|
||
<dd><p>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</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PCHID</code></dt>
|
||
<dd><p>The user supplied channel identifier storage is overwritten with a
|
||
channel identifier if this routine is successful.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USERFUNC</code></dt>
|
||
<dd><p>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.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>PUSER</dt>
|
||
<dd><p>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.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADTYPE - Invalid DBR_XXXX type</p>
|
||
|
||
<p>ECA_STRTOBIG - Unusually large string</p>
|
||
|
||
<p>ECA_ALLOCMEM - Unable to allocate memory</p>
|
||
|
||
<h3><a name="ca_clear_channel"></a><code>ca_clear_channel()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_clear_channel (evid CHID); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Shutdown and reclaim resources associated with a channel created by
|
||
ca_search or ca_search_and_connect.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>Identifies the channel to delete.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID</p>
|
||
|
||
<h3><a name="ca_put"><code>ca_put()</code></a></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_put ( chtype TYPE, </code></pre>
|
||
<pre><code> chid CHID, void *PVALUE ); </code></pre>
|
||
<pre><code>int ca_array_put ( chtype TYPE, </code></pre>
|
||
<pre><code> unsigned long COUNT, </code></pre>
|
||
<pre><code> chid CHID, const void *PVALUE);</code></pre>
|
||
<pre><code>typedef void ( *pCallBack ) (</code><code>struct event_handler_args );</code></pre>
|
||
<pre><code>int ca_put_callback ( chtype TYPE, </code></pre>
|
||
<pre><code> chid CHID, const void *PVALUE, </code></pre>
|
||
<pre><code> pCallBack PFUNC, void *USERARG ); </code></pre>
|
||
<pre><code>int ca_array_put_callback ( chtype TYPE, </code></pre>
|
||
<pre><code> unsigned long COUNT, </code></pre>
|
||
<pre><code> chid CHID, const void *PVALUE, </code></pre>
|
||
<pre><code> pCallBack PFUNC, void *USERARG );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Write a scalar or array value to a process variable.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>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</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd><p>Element count to be written to the specified channel. This must
|
||
match the array pointed to by PVALUE.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>Channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PVALUE</code></dt>
|
||
<dd><p>Pointer to a value or array of values provided by the application
|
||
to be written to the channel.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PFUNC</code></dt>
|
||
<dd><p>address of user supplied function to be run when the requested
|
||
operation completes</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USERARG</code></dt>
|
||
<dd><p>pointer sized variable retained and then passed back to user
|
||
supplied function above</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID</p>
|
||
|
||
<p>ECA_BADTYPE - Invalid DBR_XXXX type</p>
|
||
|
||
<p>ECA_BADCOUNT - Requested count larger than native element count</p>
|
||
|
||
<p>ECA_STRTOBIG - Unusually large string supplied</p>
|
||
|
||
<p>ECA_NOWTACCESS - Write access denied</p>
|
||
|
||
<p>ECA_ALLOCMEM - Unable to allocate memory</p>
|
||
|
||
<h4>See Also</h4>
|
||
ca_flush_io()
|
||
|
||
<p>ca_pend_event()</p>
|
||
|
||
<h3><a name="ca_get"></a><code>ca_get()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_get ( chtype TYPE, </code></pre>
|
||
<pre><code> chid CHID, void *PVALUE ); </code></pre>
|
||
<pre><code>int ca_array_get ( chtype TYPE, unsigned long COUNT, </code></pre>
|
||
<pre><code> chid CHID, void *PVALUE ); </code></pre>
|
||
<pre><code>typedef void ( *pCallBack ) (</code><code>struct event_handler_args );</code></pre>
|
||
<pre><code>int ca_get_callback ( chtype TYPE, </code></pre>
|
||
<pre><code> chid CHID, pCallBack USERFUNC, void *USERARG);</code></pre>
|
||
<pre><code>int ca_array_get_callback ( chtype TYPE, unsigned long COUNT, </code></pre>
|
||
<pre><code> chid CHID, </code></pre>
|
||
<pre><code> pCallBack USERFUNC, void *USERARG ); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Read a scalar or array value from a process variable.</p>
|
||
|
||
<p>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.</p>
|
||
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.
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>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</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd><p>Element count to be read from the specified channel. Must match the
|
||
array pointed to by PVALUE.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>Channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PVALUE</code></dt>
|
||
<dd><p>Pointer to an application supplied buffer where the current value
|
||
of the channel is to be written.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USERFUNC</code></dt>
|
||
<dd><p>Address of user supplied function to be run when the requested
|
||
operation completes.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USERARG</code></dt>
|
||
<dd><p>Pointer sized variable retained and then passsed back to user
|
||
supplied call back function above.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADTYPE - Invalid DBR_XXXX type</p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID</p>
|
||
|
||
<p>ECA_BADCOUNT - Requested count larger than native element count</p>
|
||
|
||
<p>ECA_GETFAIL - A local database get failed</p>
|
||
|
||
<p>ECA_NORDACCESS - Read access denied</p>
|
||
|
||
<p>ECA_ALLOCMEM - Unable to allocate memory</p>
|
||
|
||
<h4>See Also</h4>
|
||
ca_pend_io()
|
||
|
||
<p>ca_pend_event()</p>
|
||
|
||
<h3><a name="ca_add_event"></a><code>ca_add_event()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>typedef void ( *pCallBack ) (</code></pre>
|
||
<pre><code> struct event_handler_args );</code></pre>
|
||
<pre><code>int ca_add_event( chtype TYPE, chid CHID, </code></pre>
|
||
<pre><code> pCallBack USERFUNC, void *USERARG, </code></pre>
|
||
<pre><code> evid *PEVID); </code></pre>
|
||
<pre><code>int ca_add_array_event( chtype TYPE,</code></pre>
|
||
<pre><code> unsigned long COUNT, chid CHID,</code></pre>
|
||
<pre><code> pCallBack USERFUNC, void *USERARG, </code></pre>
|
||
<pre><code> double RESERVED, double RESERVED, </code></pre>
|
||
<pre> double RESERVED, evid *PEVID );</pre>
|
||
<pre><code> </code></pre>
|
||
<pre><code>int ca_add_masked_array_event ( chtype TYPE, </code></pre>
|
||
<pre><code> unsigned long COUNT, chid CHID, </code></pre>
|
||
<pre><code> pCallBack USERFUNC, void *USERARG, </code></pre>
|
||
<pre><code> double RESERVED, double RESERVED, double RESERVED, </code></pre>
|
||
<pre><code> evid *PEVID, unsigned long MASK ); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>A better name for this function might have been ca_subscribe.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd>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</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd>The element count to be read from the specified channel. A count of
|
||
zero specifies the native elemnt count.</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd>channel identifier</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USRERFUNC</code></dt>
|
||
<dd>Address of user supplied callback function to be invoked with each
|
||
subscription update</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USERARG</code></dt>
|
||
<dd>pointer sized variable retained and passed back to user callback
|
||
function</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>RESERVED</code></dt>
|
||
<dd>Reserved for future use. Specify 0.0 to remain upwardly
|
||
compatible.</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PEVID</code></dt>
|
||
<dd>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.</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>MASK</code></dt>
|
||
<dd>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.
|
||
<ul>
|
||
<li>DBE_VALUE - Trigger events when the channel value exceeds the
|
||
monitor dead band</li>
|
||
<li>DBE_LOG - Trigger events when the channel value exceeds the
|
||
archival dead band</li>
|
||
<li>DBE_ALARM - Trigger events when the channel alarm state
|
||
changes.</li>
|
||
</ul>
|
||
<p>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."</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID</p>
|
||
|
||
<p>ECA_BADTYPE - Invalid DBR_XXXX type</p>
|
||
|
||
<p>ECA_ALLOCMEM - Unable to allocate memory</p>
|
||
|
||
<p>ECA_ADDFAIL - A local database event add failed</p>
|
||
|
||
<h4>See Also</h4>
|
||
ca_pend_event()
|
||
|
||
<p>ca_flush_io()</p>
|
||
|
||
<h3><a name="ca_clear_event"></a><code>ca_clear_event()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_clear_event ( evid EVID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Cancel a subscription.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt>EVID</dt>
|
||
<dd><p>event id returned by ca_add_event()</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID SEE ALSO ca_add_event()</p>
|
||
|
||
<h3><a name="ca_pend_io"></a><code>ca_pend_io()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_pend_io ( double TIMEOUT );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>This function flushes the send buffer and then waits until outstanding <a
|
||
href="#ca_get">ca_get</a>, and possibly also <a
|
||
href="#ca_search">ca_search</a> requests, complete or the specified time out
|
||
expires.</p>
|
||
<ul>
|
||
<li>If ECA_NORMAL is returned then it can be safely assumed that all
|
||
outstanding <a href="#ca_get">ca_get</a>, and possibly also <a
|
||
href="#ca_search">ca_search</a> requests, have completed
|
||
successfully.</li>
|
||
<li>If ECA_TIMEOUT is returned then it must be assumed for all previous <a
|
||
href="#ca_get">ca_get</a>, and possibly also <a
|
||
href="#ca_search">ca_search</a> requests, requests have failed.</li>
|
||
</ul>
|
||
|
||
<p>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 <a href="#ca_get">ca_get</a>, and possibly also <a
|
||
href="#ca_search">ca_search</a> requests issued after the last call to
|
||
ca_pend_io() or issued after ca client context initialization whichever is
|
||
later. In contrast, a <a href="#ca_search">ca_search</a> request should not be
|
||
reissued unless <a href="#ca_clear_channel">ca_clear_channel</a> is called
|
||
first.</p>
|
||
|
||
<p>If no <a href="#ca_get">ca_get</a>, and possibly also <a
|
||
href="#ca_search">ca_search</a> requests, are outstanding then ca_pend_io()
|
||
will flush the send buffer and return immediately <em>without processing any
|
||
outstanding channel access background activities</em>.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt>TIMEOUT</dt>
|
||
<dd>Specifies the time out interval. A <code>TIMEOUT</code> interval of
|
||
zero specifies forever.</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_EVDISALLOW - Function inappropriate for use within an event handler</p>
|
||
|
||
<h4>See Also</h4>
|
||
<a href="#ca_get">ca_get</a>()
|
||
|
||
<p><a name="#ca_search" href="#ca_search">ca_search</a>()</p>
|
||
|
||
<p><a href="#ca_test_io">ca_test_io</a>()</p>
|
||
|
||
<h3><code>ca_test_io()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_test_io();</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>This function tests to see if any <a href="#ca_get">ca_get</a>, and
|
||
possibly also <a href="#ca_search">ca_search</a> requests, are incomplete. It
|
||
will report the status of outstanding <a href="#ca_get">ca_get</a>, and
|
||
possibly also <a href="#ca_search">ca_search</a> requests, issued after the
|
||
last call to ca_pend_io() or CA context initialization whichever is later.</p>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_IODONE - All IO operations completed</p>
|
||
|
||
<p>ECA_IOINPROGRESS - IO operations still in progress</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_pend_io">ca_pend_io</a>()</p>
|
||
|
||
<h3><code>ca_pend_event()</code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre>int ca_pend_event ( double TIMEOUT ); </pre>
|
||
<pre>int ca_poll (); </pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>When ca_pend_event is invoked the send buffer is flushed and CA background
|
||
activity is processed for TIMEOUT seconds.</p>
|
||
|
||
<p>When ca_poll is invoked the send buffer is flushed and any outstanding CA
|
||
background activity is processed.</p>
|
||
|
||
<p>The routine will not return before the time-out expires and all unfinished
|
||
channel access labor has been processed.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TIMEOUT</code></dt>
|
||
<dd>The duration to block in this routine in seconds. A timeout of zero
|
||
seconds blocks forever.</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_TIMEOUT - The operation timed out</p>
|
||
|
||
<p>ECA_EVDISALLOW - Function inappropriate for use within a call back
|
||
handler</p>
|
||
|
||
<h3><code>ca_flush_io()</code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre>int ca_flush_io(); </pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>Outstanding requests are also sent whenever the buffer which holds them
|
||
becomes full.</p>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h3><code>ca_signal()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_signal ( long CA_STATUS,</code><code> const char * CONTEXT_STRING ); </code></pre>
|
||
<pre><code>void SEVCHK( CA_STATUS, CONTEXT_STRING );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Examples</h4>
|
||
<pre><code>status = ca_context_create (...); </code></pre>
|
||
<pre><code>SEVCHK ( status, "Unable to create a CA client context" ); </code></pre>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CA_STATUS</code></dt>
|
||
<dd><p>The status (error code) returned from a channel access
|
||
function.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>CONTEXT_STRING</code></dt>
|
||
<dd><p>A null terminated character string to supply as error context to
|
||
diagnostics.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h3><code>ca_add_exception_event()</code></h3>
|
||
<pre>#include <cadef.h> </pre>
|
||
<pre>typedef void (*pCallback) ( struct exception_handler_args HANDLERARGS );</pre>
|
||
<pre>int ca_add_exception_event ( pCallback USERFUNC, void *USERARG );</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Replace the currently installed exception handler call back.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>USERFUNC</code></dt>
|
||
<dd><p>Addressof usercall back functionto beexecuted when exceptions
|
||
occur. Passing a nil value causes the default exception handler to be
|
||
reinstalled.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>USERARG</code></dt>
|
||
<dd><p>pointer sized variable retained and passed back to user function
|
||
above</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Example</h4>
|
||
<pre><code>void ca_exception_handler (
|
||
struct exception_handler_args args)
|
||
{</code></pre>
|
||
<pre><code> 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", </code></pre>
|
||
<pre><code> args.ctx, pName, args.op, dbr_type_to_text ( args.type ), args.count ); </code></pre>
|
||
<pre><code> ca_signal ( args.stat, buf ); </code></pre>
|
||
<pre><code> </code></pre>
|
||
<pre><code>} </code></pre>
|
||
<pre><code>ca_add_exception_event ( ca_exception_handler , 0 );</code></pre>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h3><code>ca_replace_printf_handler ()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>typedef int caPrintfFunc ( const char *pFromat, va_list args );</code></pre>
|
||
<pre><code>int ca_replace_printf_handler ( caPrintfFunc *PFUNC );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Replace the default handler for formatted diagnostic message output. The
|
||
default handler uses fprintf to send messages to 'stderr'.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>PFUNC</code></dt>
|
||
<dd><p>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.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Examples</h4>
|
||
<pre><code>int my_printf ( char *pformat, va_list args ) {</code></pre>
|
||
<pre><code> int status;</code></pre>
|
||
<pre><code> status = vfprintf( stderr, pformat, args);</code></pre>
|
||
<pre><code> return status;</code></pre>
|
||
<pre><code>}</code></pre>
|
||
<pre><code>status = ca_replace_printf_handler ( my_printf );</code></pre>
|
||
<pre><code>SEVCHK ( status, "failed to install my printf handler" );</code></pre>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h3><code>ca_replace_access_rights_event()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>typedef void ( *pCallBack )( struct access_rights_handler_args );</code></pre>
|
||
<pre><code>int ca_replace_access_rights_event ( chid CHAN, pCallBack PFUNC );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Install or replace the access rights state change call back handler for the
|
||
specified channel.</p>
|
||
|
||
<p>The call back handler is called in the following situations.</p>
|
||
<ul>
|
||
<li>whenever CA connects the channel immediately before the channel's
|
||
connection handler is called</li>
|
||
<li>whenever CA disconnects the channel immediately after the channel's
|
||
disconnect call back is called</li>
|
||
<li>once immediately after installation if the channel is connected.</li>
|
||
<li>whenever the access rights state of a connected channel changes</li>
|
||
</ul>
|
||
|
||
<p>When a channel is created no access rights handler is installed.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHAN</code></dt>
|
||
<dd><p>The channel identifier.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PFUNC</code></dt>
|
||
<dd><p>Address of user supplied call back function. A nil pointer
|
||
uninstalls the current handler.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p>ca_modify_user_name()</p>
|
||
|
||
<p>ca_modify_host_name()</p>
|
||
|
||
<h3><code>ca_field_type()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>chtype ca_field_type ( CHID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Return the native type in the server of the process variable.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>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.<a name="ca_element_count"></a></p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_element_count()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>unsigned ca_element_count ( CHID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Return the maximum array element count in the server for the specified IO
|
||
channel.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd><p>The maximum array element count in the server. An element count of
|
||
zero is returned if the channel is disconnected.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_name()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<code>char * ca_name ( CHID );</code>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Return the name provided when the supplied channel id was
|
||
created.<code></code></p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Return<code>s</code></h4>
|
||
<dl>
|
||
<dt><code>PNAME</code></dt>
|
||
<dd><p>The channel name. The string returned is valid as long as the
|
||
channel specified exists.<a name="ca_puser"></a><a
|
||
name="ca_set_puser"></a></p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_set_puser()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>void ca_set_puser ( chid CHID, void *PUSER );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Set a user private void pointer variable retained with each channel for use
|
||
at the users discretion.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt>CHID</dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>PUSER</dt>
|
||
<dd><p>user private void pointer</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_puser()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<code>void * ca_puser ( CHID );</code>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Return a user private void pointer variable retained with each channel for
|
||
use at the users discretion.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>PUSER</code></dt>
|
||
<dd><p>user private pointer</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>channel_state()</code></h3>
|
||
<pre><a name="ca_set_puser"></a></pre>
|
||
<pre><code>/* channel connection state */</code></pre>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>enum channel_state {</code></pre>
|
||
<pre><code> cs_never_conn, /* valid chid, server not found or unavaliable */</code></pre>
|
||
<pre><code> cs_prev_conn, /* valid chid, previously connected to server */</code></pre>
|
||
<pre><code> cs_conn, /* valid chid, connected to server */</code></pre>
|
||
<pre><code> cs_closed }; /* channel deleted by user */</code></pre>
|
||
<pre><code>enum channel_state ca_state ( CHID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Returns an enumerated type indicating the current state of the specified IO
|
||
channel.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>STATE</code></dt>
|
||
<dd><p>the conection state</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_message()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>const char * ca_message ( STATUS );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>return a message character string corresponding to a user specified CA
|
||
status code.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>STATUS</code></dt>
|
||
<dd><p>a CA status code</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt>STR<code></code>ING</dt>
|
||
<dd><p>the corresponding error message string</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_host_name()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>char * ca_host_name ( CHID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Return a character string which contains the name of the host to which a
|
||
channel is currently connected.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>the channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>STRING</code></dt>
|
||
<dd><p>The process variable server's host name. If the channel is
|
||
disconnected the string "<disconnected>" is returned.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_read_access()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_read_access ( CHID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Returns boolean true if the client currently has read access to the
|
||
specified channel and boolean false otherwise.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>the channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>STRING</code></dt>
|
||
<dd><p>boolean true if the client currently has read access to the
|
||
specified channel and boolean false otherwisex</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>ca_write_access()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_write_access ( CHID );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Returns boolean true if the client currently has write access to the
|
||
specified channel and boolean false otherwise.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>the channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>STRING</code></dt>
|
||
<dd><p>boolean true if the client currently has write access to the
|
||
specified channel and boolean false otherwise</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>dbr_size[]</code></h3>
|
||
<pre><code>#include <db_access.h></code></pre>
|
||
<pre><code>extern unsigned dbr_size[/*TYPE*/];</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>An array that returns the size in bytes for a DBR_XXXX type.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>The data type code. A member of the set of DBF_XXXX in
|
||
db_access.h.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>SIZE</code></dt>
|
||
<dd><p>the size in bytes of the specified type</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code>dbr_size_n()</code></h3>
|
||
<pre><code>#include <db_access.h></code></pre>
|
||
<pre><code>unsigned dbr_size_n ( TYPE, COUNT );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>The data type</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd><p>The element count</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>SIZE</code></dt>
|
||
<dd><p>the size in bytes of the specified type with the specified number
|
||
of elements</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4><code><a name="dbr_value_size">dbr_value_size[]</a></code></h4>
|
||
<pre><code>#include <db_access.h></code></pre>
|
||
<pre><code>extern unsigned dbr_value_size[/* TYPE */];</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>The data type code. A member of the set of DBF_XXXX in
|
||
db_access.h.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
<dl>
|
||
<dt><code>SIZE</code></dt>
|
||
<dd><p>the size in bytes of the value field if the type is a structure and
|
||
otherwise the size in bytes of the type</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><code><a name="ca_test_event">ca_test_event()</a></code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
|
||
<h4>Description</h4>
|
||
<pre>void ca_test_event ( struct event_handler_args );</pre>
|
||
|
||
<p>A built-in subscription update call back handler for debugging purposes
|
||
that prints diagnostics to standard out.</p>
|
||
|
||
<h4><strong>Examples</strong></h4>
|
||
<pre><code>void ca_test_event (); </code></pre>
|
||
<pre><code>status = ca_add_event ( type, chid, ca_test_event, NULL, NULL ); </code></pre>
|
||
<pre><code>SEVCHK ( status, .... ); </code></pre>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_add_event">ca_add_event</a>()</p>
|
||
|
||
<h3><code><a name="ca_sg_create">ca_sg_create()</a></code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_sg_create ( CA_SYNC_GID *PGID ); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Create a synchronous group and return an identifier for it.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>Any number of asynchronous groups can have application requested operations
|
||
outstanding within them at any given time.</p>
|
||
|
||
<p><strong>Arguments</strong></p>
|
||
<dl>
|
||
<dt><code>PGID</code></dt>
|
||
<dd><p>Pointer to a user supplied CA_SYNC_GID.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4><code>Examples</code></h4>
|
||
<pre><code>CA_SYNC_GID gid; </code></pre>
|
||
<pre><code>status = ca_sg_create ( &gid ); </code></pre>
|
||
<pre><code>SEVCHK ( status, Sync group create failed ); </code></pre>
|
||
|
||
<h4><code>Returns</code></h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_ALLOCMEM - Failed, unable to allocate memory</p>
|
||
|
||
<h4><code>See Also</code></h4>
|
||
ca_sg_delete()
|
||
|
||
<p>ca_sg_block()</p>
|
||
|
||
<p>ca_sg_test()</p>
|
||
|
||
<p>ca_sg_reset()</p>
|
||
|
||
<p>ca_sg_put()</p>
|
||
|
||
<p>ca_sg_get()</p>
|
||
|
||
<h3><code><a name="ca_sg_delete">ca_sg_delete()</a></code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_sg_delete ( CA_SYNC_GID GID ); </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Deletes a synchronous group.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt>GID</dt>
|
||
<dd><p>Identifier of the synchronous group to be deleted.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Examples</h4>
|
||
<pre><code>CA_SYNC_GID gid; </code></pre>
|
||
<pre><code>status = ca_sg_delete ( gid ); </code></pre>
|
||
<pre><code>SEVCHK ( status, Sync group delete failed ); </code></pre>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADSYNCGRP - Invalid synchronous group</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_sg_create">ca_sg_create</a>()</p>
|
||
|
||
<h3><a name="ca_sg_block"><code>ca_sg_block</code></a><code>()</code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_sg_block ( CA_SYNC_GID GID, double timeout );</code></pre>
|
||
|
||
<h4><code>Description</code></h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4><code>Arguments</code></h4>
|
||
<dl>
|
||
<dt>GID</dt>
|
||
<dd><p>Identifier of the synchronous group.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4><code>Examples</code></h4>
|
||
<pre><code>CA_SYNC_GID gid; </code></pre>
|
||
<pre><code>status = ca_sg_block(gid); </code></pre>
|
||
<pre><code>SEVCHK(status, Sync group block failed); </code></pre>
|
||
|
||
<h4><code>Returns</code></h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_TIMEOUT - The operation timed out</p>
|
||
|
||
<p>ECA_EVDISALLOW - Function inappropriate for use within an event handler</p>
|
||
|
||
<p>ECA_BADSYNCGRP - Invalid synchronous group</p>
|
||
|
||
<h4><code>See Also</code></h4>
|
||
|
||
<p>ca_sg_test()</p>
|
||
|
||
<p>ca_sg_reset()</p>
|
||
|
||
<h3><code><a name="ca_sg_test">ca_sg_test()</a></code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_sg_test ( CA_SYNC_GID GID ) </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Test to see if all requests made within a synchronous group have
|
||
completed.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>GID</code></dt>
|
||
<dd><p>Identifier of the synchronous group.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Test to see if all requests made within a synchronous group have
|
||
completed.</p>
|
||
|
||
<h4>Examples</h4>
|
||
<pre><code>CA_SYNC_GID gid;</code></pre>
|
||
<pre><code>status = ca_sg_test ( gid );</code></pre>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_IODONE - IO operations completed</p>
|
||
|
||
<p>ECA_IOINPROGRESS - Some IO operations still in progress</p>
|
||
|
||
<h3><code><a name="ca_sg_reset">ca_sg_reset()</a></code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_sg_reset ( CA_SYNC_GID GID ) </code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<h4><code>Arguments</code></h4>
|
||
<dl>
|
||
<dt><code>GID</code></dt>
|
||
<dd><p>Identifier of the synchronous group.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4><code>Examples</code></h4>
|
||
<pre><code>CA_SYNC_GID gid; </code></pre>
|
||
<pre><code>status = ca_sg_reset(gid); </code></pre>
|
||
|
||
<h4><code>Returns</code></h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADSYNCGRP - Invalid synchronous group</p>
|
||
|
||
<h3><code><a name="ca_sg_put">ca_sg_put()</a></code></h3>
|
||
<pre><code>#include <cadef.h></code></pre>
|
||
<pre><code>int ca_sg_array_put ( CA_SYNC_GID GID, chtype TYPE, </code></pre>
|
||
<pre><code> unsigned long COUNT, chid CHID, void *PVALUE );</code></pre>
|
||
|
||
<p>Write a value, or array of values, to a channel and increment the
|
||
outstanding request count of a synchronous group.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>If a connection is lost and then resumed outstanding puts are not
|
||
reissued.</p>
|
||
|
||
<h4><code>Arguments</code></h4>
|
||
<dl>
|
||
<dt><code>GID</code></dt>
|
||
<dd><p>synchronous group identifier</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>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.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd><p>element count to be written to the specified channel - must match
|
||
the array pointed to by PVALUE</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PVALUE</code></dt>
|
||
<dd><p>A pointer to an application supplied buffer containing the value or
|
||
array of valuesReturns</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4><code>Returns</code></h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_BADSYNCGRP - Invalid synchronous group</p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID</p>
|
||
|
||
<p>ECA_BADTYPE - Invalid DBR_XXXX type</p>
|
||
|
||
<p>ECA_BADCOUNT - Requested count larger than native element count</p>
|
||
|
||
<p>ECA_STRTOBIG - Unusually large string supplied</p>
|
||
|
||
<p>ECA_PUTFAIL - A local database put failed</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_flush_io">ca_flush_io</a>()</p>
|
||
|
||
<h3><code><a name="ca_sg_get">ca_sg_get()</a></code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre><code>int ca_sg_array_get ( CA_SYNC_GID GID, </code></pre>
|
||
<pre><code> chtype TYPE, unsigned long COUNT, </code></pre>
|
||
<pre><code> chid CHID, void *PVALUE );</code></pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Read a value from a channel and increment the outstanding request count of
|
||
a synchronous group.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>If a connection is lost and then resumed outstanding gets are not
|
||
reissued.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>GID</code></dt>
|
||
<dd><p> Identifier of the synchronous group.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>TYPE</code></dt>
|
||
<dd><p>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</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>COUNT</code></dt>
|
||
<dd><p>Element count to be read from the specified channel. It must match
|
||
the array pointed to by PVALUE.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>CHID</code></dt>
|
||
<dd><p>channel identifier</p>
|
||
</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt><code>PVALUE</code></dt>
|
||
<dd><p>Pointer to application supplied buffer that is to contain the value
|
||
or array of values to be returned</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion </p>
|
||
|
||
<p>ECA_BADSYNCGRP - Invalid synchronous group </p>
|
||
|
||
<p>ECA_BADCHID - Corrupted CHID</p>
|
||
|
||
<p>ECA_BADCOUNT - Requested count larger than native element count</p>
|
||
|
||
<p>ECA_BADTYPE - Invalid DBR_XXXX type</p>
|
||
|
||
<p>ECA_GETFAIL - A local database get failed</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_pend_io">ca_pend_io</a>()</p>
|
||
|
||
<p><a href="#ca_flush_io">ca_flush_io</a>()</p>
|
||
|
||
<p><a href="#ca_get_callback">ca_get_callback</a>()</p>
|
||
|
||
<h3><code><a name="ca_client_status">ca_client_status()</a></code></h3>
|
||
<pre>int ca_client_status ( unsigned level );</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Prints information about the client context including, at higher intereest
|
||
levels, status for each channel.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>LEVEL</code></dt>
|
||
<dd><p>The interest level. Increasing level produces increasing
|
||
detail.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3><a name="ca_current_context">ca_current_context()</a></h3>
|
||
<pre>struct ca_client_context * ca_current_context ();</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Returns a pointer to the current thread's CA context. If none then nil is
|
||
returned.</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p>ca_attach_context()</p>
|
||
|
||
<h3><a name="ca_attach_context">ca_attach_context()</a></h3>
|
||
<pre>int ca_attach_context (struct ca_client_context *CONTEXT); </pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Become a member of the specified CA context.</p>
|
||
|
||
<h4>Arguments</h4>
|
||
<dl>
|
||
<dt><code>CONTEXT</code></dt>
|
||
<dd><p>A pointer to the CA context to join with.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_ISATTACHED - already attached to a CA context</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p>ca_current_context()</p>
|
||
|
||
<h2><a name="Deprecated">Deprecated Functions</a></h2>
|
||
|
||
<h3><code><a name="L6771">ca_task_initialize()</a></code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre>int ca_task_initialize();</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>This function should be called once prior to making any of the other
|
||
channel access calls.</p>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<p>ECA_ALLOCMEM - Failed, unable to allocate space in pool</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_task_exit">ca_task_exit()</a><a></a><a></a><a></a></p>
|
||
|
||
<h3><a name="ca_task_exit"></a><code>ca_task_exit()</code></h3>
|
||
<pre>#include <cadef.h></pre>
|
||
<pre>int ca_task_exit(); </pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Shut down a channel access client context and free any resources allocated.
|
||
On most operating systems this is performed automatically at process exit.</p>
|
||
|
||
<h4>Returns</h4>
|
||
|
||
<p>ECA_NORMAL - Normal successful completion</p>
|
||
|
||
<h4>See Also</h4>
|
||
|
||
<p><a href="#ca_task_initialize">ca_task_initialize()</a></p>
|
||
|
||
<h2><a name="Command">Command Line Utilities</a></h2>
|
||
|
||
<h3><a name="acctst">acctst</a></h3>
|
||
<pre>acctst <PV name> [channel duplication count] [test repetition count]</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Channel access Client Library regression test.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3><a name="catime">catime</a></h3>
|
||
<pre>catime <PV name> [channel count] [append number to pv name if true]</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Channel Access Client Library performance test.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p><PV name>000000, <PV name>000001, ... <PV name>nnnnnn</p>
|
||
|
||
<h3><a name="casw">casw</a></h3>
|
||
<pre>casw</pre>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>CA server "beacon anomaly" logging.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>CA clients with unresolved channels reset their search request schedualing
|
||
timers whenever they see a beacon anomaly.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3><a name="caEventRat">caEventRate</a></h3>
|
||
|
||
<p>caEventRate <PV name></p>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>Subscribe to the specified PV and periodically log its event rate.</p>
|
||
|
||
<h3><a name="ca_test">ca_test</a></h3>
|
||
|
||
<p>ca_test <PV name> [value to be written]</p>
|
||
|
||
<h4>Description</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<h2><a name="Return">Return Codes</a></h2>
|
||
<dl>
|
||
<dt>ECA_NORMAL</dt>
|
||
<dd>normal successful completion</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_ALLOCMEM</dt>
|
||
<dd>unable to allocate memory</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_BADTYPE</dt>
|
||
<dd>invalid DBR_XXXX type</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_STRTOBIG</dt>
|
||
<dd>unusually large string supplied</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_BADCHID</dt>
|
||
<dd>ivalid channel identifier</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_BADCOUNT</dt>
|
||
<dd>requested count larger than native element count</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_PUTFAIL</dt>
|
||
<dd>a write request failed in the server</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_GETFAIL</dt>
|
||
<dd>a read request faile din the server</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_ADDFAIL</dt>
|
||
<dd>unable to instal subscription request</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_TIMEOUT</dt>
|
||
<dd>requested operation timed out</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_EVDISALLOW</dt>
|
||
<dd>function called was inappropriate for use within a callback
|
||
function</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_IODONE</dt>
|
||
<dd>IO operations completed</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_IOINPROGRESS</dt>
|
||
<dd>some IO operations still in progress</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_BADSYNCGRP</dt>
|
||
<dd>invalid synchronous group identifier</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_NORDACCESS</dt>
|
||
<dd>read access denied</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>ECA_NOWTACCESS</dt>
|
||
<dd>write access denied</dd>
|
||
</dl>
|
||
<pre></pre>
|
||
</body>
|
||
</html>
|