EPICS通道访问库函数

1、 ca_context_create

#include 
enum ca_preemptive_callback_select
    { ca_disable_preemptive_callback, ca_enable_preemptive_callback };
int ca_context_create ( enum ca_preemptive_callback_select SELECT );

描述：在进行任何其它通道访问调用前，函数ca_context_create应该从每个线程被调用一次。如果在进行其它Ca调用前，以上之一未被调用，则默认创建一个非抢占式上下文，并且之后位这些当前线程创建一个抢占式上下文将失败。

如果ca_disable_preemptive_callback被指定，则其它线程不被允许使用ca_context_attach()加入这个CA上下文，因为允许其它线程加入隐含CA回调将抢占式地从多于一个线程被调用。

参数：

SELECT：这个参数指定是否允许回调函数的抢占式调用。如果这样，当调用这个例程的线程未在CA客户端库中执行时，你的回调函数可能被调用。有两个影响需要考虑。

首先，如果抢占式回调模式被启用，开发者必需为它的数据结构提供互斥保护。在此模式中，两个线程同时接触程序的数据结构是可能的：这可能是进行初始化的线程(调用ca_context_create的线程)和也可能是由CA客户端库为了接收网络消息创建的私有线程以及调用回调。不熟悉在多线程环境中互斥锁的开发者指定ca_disable_preemptive_callback是谨慎的。

第二，如果启动了抢占式回调模式，此应用程序不再负担为了管理其后台活动周期地查询CA客户端库的必要了。如果指定了ca_enable_preemptive_callback，则CA客户端后台活动，诸如连接管理，将继续进行，即使调用这个例程地线程未在CA客户端库中执行。更进一步，在抢占式回调模式中，因为在进行初始化的线程(调用ca_context_create的线程)在CA客户端库内执行前不需要等待，所以回调被更少延时地调用。

返回：
1、ECA_NORMAL ：正常成功结束

2、ECA_ALLOCMEM ：出错，不能在池中分配空间l

3、ECA_NOTTHREADED ：当前线程已经是一个非抢占式回调Ca上下文的成员了(可能隐式的)

2、ca_context_destroy

#include 
void ca_context_destroy();

描述：关闭调用线程地通道访问客户端上下文并且释放分配的任何资源。从任何CA客户端上下文分离调用线程。

任何用户创建的已经把它们自己连接到CA上下文的线程在其被销毁前必须停止它。在一个IOC上下文中运行的程序在调用ca_context_destroy()前必须删除所有它的通道以避免崩溃。

调用epicsExit()的CA客户端程序必须安装要给EPICS exit处理程序，其只在首次调用ca_create_context()后，调用ca_context_destroy()。这将确保EPICS exit处理程序按正确顺序被调用。

在一个基于进程环境中执行程序的很多OS上，客户端库使用的诸如套接字和分配内存的资源在进行退出并且ca_context_destroy()为被调用时自动被系统释放，但在轻量级系统，诸如vxWorks或RTEMS上，除非程序调用ca_context_destroy()，否则不发生清理。

注意：在当前上下文中为任何通道创建的任何用户回调运行结束前，这个操作阻塞。如果回调获取了一个锁(mutex)，则确保在调用ca_clear_context()时，这个锁未被持有，是用户的责任。

返回：

ECA_NORMAL：一般成功结束。

3、ca_create_channel

#include 

struct  ca_connection_handler_args {
    chanId  chid;  /* channel id */
    long    op;    /* one of CA_OP_CONN_UP or CA_OP_CONN_DOWN */
};

typedef void ( caCh ) (struct connection_handler_args);
int ca_create_channel (const char *PVNAME,
        caCh *USERFUNC, void *PUSER,
        capri PRIORITY, chid *PCHID );

描述：这个函数创建一个CA通道。CA客户端库将尝试在调用者的程序和CA服务器中指定名称过程变量之间建立和维护一个虚电路。对ca_create_channel()的每次调用在CA客户端库以及也在CA服务器中分配资源。函数ca_clear_channel()用于释放这些资源。 如果成功，这个例程写一个通道标识符到类型chid的用变量。这个标识符可以与操作通道的任何通道访问调用一起使用。

取决于网络状态以及通道的位置，虚电路初始可能连接或者断开。仅在服务器地址被确定以及仅在通道访问成功地建立了经过网络到服务器的虚电路后，通道才进入连接状态。如果通道当前是断开的，向服务器发送请求的通道访问例程将返回ECA_DISCONNCHID。

获取通道进入连接状态时异步通道有两种方法：

第一个和最简单的方法需要你调用ca_pend_io()，并且在使用指定一个null连接回调函数指针创建的通道前，等待成功结束。
第二个方法需要你通过提供一个有效连接回调函数指针注册一个连接处理程序。当通道的连接状态变化时，这个连接处理程序被调用。如果你安装了连接处理程序，则ca_pend_io()将不阻塞等待通道进入连接状态。.
函数ca_state(CHID)可以用于测试一个通道的连接状态。如果ca_pend_io()超时，有效连接可以从无效连接区分开。

由于网络连接的固有瞬态性，不能确保连接回调的顺序相对于ca_create_channel()调用的顺序，并且应用程序需要为一个连接通道在任何时候进入断开状态做好准备。

参数：

1）PVNAME：一个nil结尾的过程变量名称字符串。EPICS过程控制功能块数据库变量名称格式为"."。如果字段名和点分隔符被省略，则隐含"VAL"字段。例如，"RFHV01"和"RFHV01.VAL"引用相同的EPICS过程控制功能块数据库变量。

2）USERFUNC：指向用户的回调函数的可选指针，在连接状态变化时调用时，将被运行。如果不需要运行这个回调函数来响应每次连接状态变化事件，可以决定设置这个字段为null或0。

以下结构体通过值被传递给用户的连接回调函数。当通道访问连接时，op字段将被CA客户端库设置为CA_OP_CONN_UP，而在通道断开时，op字段被设置为CA_OP_CONN_DOWN。如果在你的回调处理程序中需要PUSER参数见ca_puser()。

3）PUSER：这个void指针参数的值被保留在与指定通道相关联的存储区。读写这个字段见MACORS手册页。不关注的通道访问用户可以设置这个字段为null或0.

4）PRIORITY：在服务器或网络中的调用优先级，0指定最低调度优先级而99指定最高。这个参数当前不影响客户端中调度优先级，但在将来这可能变化。这个指定的抽象优先级范围被映射成服务器中操作系统特定优先级范围。如果服务器运行在对优先级调度或执行没有本地支持的网络或者操作系统上，忽略这个参数。在相同程序中指定很多不同优先级会增加客户端和服务器中的资源消耗，因为为在特定服务器上使用的每个优先级创建一个独立的虚电路和相关数据结构体。5） PCHID：如果这个例程成功，用一个通道标识符重写用户提供的通道标识符

返回：
1）ECA_NORMAL - 正常成功结束。

2）ECA_BADTYPE - 无效的DBR_XXXX类型。

3）ECA_STRTOBIG - Unusually large string异常大的字符串。

4） ECA_ALLOCMEM -能分配内存

4、ca_clear_channel

​​​​​​​#include 
int ca_clear_channel (chid CHID);

描述：

关闭和回收与由ca_create_channel()创建的通道相关联的资源。诸如一行的所有远程操作请求被累积(缓存)并且在调用ca_flush()_io()， ca_pend_io()，ca_pend_event()或ca_sg_block()之一前，不被转发给IOC。这使得若干请求用一条消息在网络上被高效传递。

清理一个通道不引起断开处理程序被调用，而是清理一个通道进行关闭并且回收向通道注册的任何通道状态变化事件订阅(监视)。

注意：在对应这个通道的任何用户回调运行到结束前，这个操作阻塞。如果回调获取了一个锁(mutex)，则确保这个锁在调用ca_clear_channel()时被被持有是使用者的责任。

参数：

CHID：识别通道。

返回：

ECA_NORMAL - 正常成功结束。
ECA_BADCHID - 损坏的CHID

5、ca_put

#include 

int ca_put ( chtype TYPE,
        chid CHID, void *PVALUE );
int ca_array_put ( chtype TYPE, unsigned long COUNT,
        chid CHID, const void *PVALUE);

typedef void ( caEventCallBackFunc ) (struct event_handler_args);
int ca_put_callback ( chtype TYPE,
        chid CHID, const void *PVALUE,
        caEventCallBackFunc PFUNC, void *USERARG );
int ca_array_put_callback ( chtype TYPE, unsigned long COUNT,
        chid CHID, const void *PVALUE,
        caEventCallBackFunc PFUNC, void *USERARG );

描述：写一个标量或数组值到一个过程变量。

当ca_put()或ca_array_put被调用时，除非在服务器中不能实现这个请求，否则客户端将接收不到响应。如果不成功，在客户端运行一个异常处理程序。

当ca_put_callback()或ca_array_put_callback()被调用时，仅在被启动的写操作以及源自启动的写操作的所有操作结束后才调用用户提供的异步回调。

If unsuccessful the callback function is invoked indicating failure status.
如果不成功，回调函数被调用，表明出错状态。如果在一个put回调请求结束前，通道断开了，则
用出错状态调用客户端的回调函数，但这不保证在断开前服务器没有接收并且处理这个请求。
如果连接丢失，在重连之后，则恢复的待处理caput请求不自动再次发送。
如果通道当前断开，所有这些函数都返回ECA_DISCONN。
所有put请求都被累积(缓存)，并且在调用ca_flush_io(), ca_pend_io(), ca_pend_event()或ca_sg_block()之一前，
不被转发给IOC。这使得若干请求被高效组合成一条消息。
描述(IOC数据库说明)
如果记录的SCAN字段被设为passive，并且被写字段设其过程被动属性为true，一个CA put请求引起这个记录运行。
如果在启动一个put请求时，这样一个记录已经在运行，指定字段立即被写，并且调度这个记录在其结束运行时立即再次运行。
在记录正在运行时，启动更早的多次put请求可能被丢弃，但启动的最后put请求总是被写和处理。

如果记录的SCAN字段被设为passive，并且被写字段设其过程被动属性为true，一个CA put回调请求引起这个记录运行。
对于这样一个记录，在这个记录以及这个记录链接到的任何记录结束运行后才调用用户的put回调函数。
如果在一个put回调请求被启动时，这样一个记录已经运行，这个put回调请求被推迟到这个记录以及它链接到的任何记录结束运行。
如果记录的SCAN字段未设为passive或者被写字段设其过程被动属性为false，则CA put或者CA put回调请求引起指定的字段立即被写，
但它们不引起这个记录被运行。

参数：
1)TYPE：要被写的提供值的外部类型。如果这不匹配本地类型，将发生转换。指定db_access.h中DBR_XXXX集合之一。
2)COUNT：要被写入指定通道的元素数目。这必须匹配由PVALUE指向的数组。
3)CHID：通道标识符。
4)PVALUE：指向一个由程序提供被写入这个通道的值或者值的数组。
5)PFUNC：指向一个用户提供回调函数的指针，当请求操作结束时，被调用。
6)USERARG：保留的指针大小的变量，并且回传给以上用户提供的函数。

返回：
ECA_NORMAL - 正常成功结束
ECA_BADCHID - 损坏的CHID
ECA_BADTYPE - 无效的DBR_XXXX类型
ECA_BADCOUNT - 请求的数目大于本地元素数目
ECA_STRTOBIG - 提供的异常大的字符串
ECA_NOWTACCESS - 写访问拒绝
ECA_ALLOCMEM - 不能分配内存
ECA_DISCONN - 通道断开

6、ca_get

#include 
int ca_get ( chtype TYPE,
        chid CHID, void *PVALUE );
int ca_array_get ( chtype TYPE, unsigned long COUNT,
        chid CHID, void *PVALUE );
typedef void ( caEventCallBackFunc ) (struct event_handler_args);
int ca_get_callback ( chtype TYPE,
        chid CHID,
        caEventCallBackFunc USERFUNC, void *USERARG);
int ca_array_get_callback ( chtype TYPE, unsigned long COUNT,
        chid CHID,
        caEventCallBackFunc USERFUNC, void *USERARG);

描述：
从一个过程变量读取一个标量或者数组值。当ca_get()或ca_array_get()被调用时，在从ca_pend_io()返回ECA_NORMAL后，
才能认为在程序提供的缓存中返回的通道值是稳定的。如果一个连接丢失，待处理的ca get请求在重连后不被自动重发。
当调用ca_get_callback()或ca_array_get_callback()时，从这个通道读取一个值，接着用一个指向这个获取值的指针调用用户的回调。
注意：ca_pend_IO()将不为由ca_get_callback()请求的值的传递而阻塞。如果在ca_get_callback()请求结束前，通道断开了，
则用错误状态调用这个客户端的回调函数。
如果通道当前断开，所有这些函数都返回ECA_DISCONN。
在调用a_flush_io(), ca_pend_io(), ca_pend_event()或ca_sg_block()之一前，所有get请求被积累(缓存)并且不转发给IOC。
这使得若干请求在一条消息中被高效发送。

描述(IOC数据库特定):
一个CA get或CA回调请求使得这个记录的字段立即被读取，无论这个记录当前是否正在被处理。
当前没有在一个CA get请求被启动时引起一个记录被处理的在用机制。

参数：
1)TYPE：要返回这个值给用户变量的外部类型。指定db_access.h中DBR_XXXX集合中之一
2)COUNT：要从指定通道读取的元素数目。必须匹配由PVALUE指向的数组。对于ca_array_get_callback()，一个0计数
表示使用来自服务器的当前元素数目。
3)CHID：通道标识符。
4)PVALUE：指向程序提供缓存的指针，要写这个通道的当前值到此处。
5)USERFUNC：指向用户提供的回调函数的指针，当请求的操作结束时，运行这个函数。
6)USERARG：保留的指针大小的变量，并且回传给以上用户提供的回调函数。

返回：

• ECA_NORMAL - 正常成功结束。
• ECA_BADTYPE -无效的DBR_XXXX类型。
• ECA_BADCHID - 损坏的CHID。
• ECA_BADCOUNT - 请求的数目大于本地元素数目
• ECA_GETFAIL - 一个本地数据库出错
• ECA_NORDACCESS - 读访问拒绝
• ECA_ALLOCMEM - 不能分配内存
• ECA_DISCONN - 通道断开

7、ca_create_subscription

ca_create_subscription()
#include 
typedef void ( caEventCallBackFunc ) (struct event_handler_args);
int ca_create_subscription ( chtype TYPE, unsigned long COUNT,
        chid CHID, unsigned long MASK,
        caEventCallBackFunc USERFUNC, void *USERARG,
        evid *PEVID);

注册一个状态变化订阅，并且指定一个回调函数，当这个过程变量经历显著状态变化时被调用。
一个显著变化可以是过程变量的值，警报状态或警报严重性的变化。
在过程控制功能块数据库中，死区字段决定过程变量的值显著变化的幅度。
对这个函数的每次调用消耗客户端库和CA服务器中的资源，直到ca_clear_channel()或ca_clear_subscription()之一被调用。

对连接和断开的通道，可以安装或取消订阅。
如果过程变量是连接的，在订阅被安装后，立即用过程变量的当前状态调用指定的USERFUNC一次。
否则，在与过程变量建立连接(或重连)后，指定的USERFUNC立即被调用。
如果客户端和过程变量共享相同的地址空间，从ca_create_subscription()中用过程变量的当前状态立即调用指定的USERFUNC。
如果对一个断开状态的通道安装一个订阅，则如果请求数目更大，请求数目将被设置为这个通道的本地最大元素数目。

诸如以上的所有订阅请求被累积(缓存)，并且在ca_flush_io(), ca_pend_io(), ca_pend_event()或ca_sg_block()之一被调用前，
不被转发给IOC。这允许若干请求在一条消息中通过网络被高效的发送。
如果在订阅后任何时候，对指定过程变量的读访问权丢失，则这个回调将被立即调用，通过状态参数表明读权限丢失。
当读访问权恢复时，正常的事件运行将继续，总是以表明这个通道当前状态的至少一次更新开始。

参数：
1)TYPE：提交给回调函数的值类型。如果不匹配本地类型，转换将发生。指定db_access.h中DBR_XXXX集合之一。
2)COUNT：要从指定通道读取的元素数目。一个0计数表示使用来自服务器的当前元素数目。
3)CHID：通道标识符。
4)USERFUNC：指向一个用户提供的回调函数的指针，用每个回调更新调用这个函数。
5)USERARG：保留的指针大小的变量，并且回给用户回调函数。
6)RESERVED：保留给将来使用。指定0.0保持向后兼容。
7)PEVID：这是一个指向用户提供的事件id的指针，如果成功，将被重写。这个事件id可以在之后用于清除一个特定事件。
通过传递一个null指针，这个选项可以被省略。
8)MASK：用于请求事件触发类型的位集合掩码。事件触发掩码必须是一个以下一个或多个常量的位与。

• DBE_VALUE    - 当通道值超过监视死区时，触发事件。
• DBE_ARCHIVE (或 DBE_LOG) - 当通道值超过存档死区时，触发事件。
• DBE_ALARM    - 当通道警报状态变化时，触发事件。
• DBE_PROPERTY - 当一个通道属性变化时，触发事件。

对于以上不包含触发说明的功能，当在通道值中有显著变化或者当在通道警报状态中有变化时，事件将被触发。
这与"DBE_VALUE | DBE_ALARM"相同。

返回：

• ECA_NORMAL -  正常成功结束
• ECA_BADCHID - 损坏的CHID
• ECA_BADTYPE - 无效的DBR_XXXX类型
• ECA_ALLOCMEM -不能分配内存
• ECA_ADDFAIL -  一个本地数据库事件添加出错

8、ca_clear_subscription()

#include 
int ca_clear_subscription ( evid EVID );

描述：取消一个订阅。诸如以上的所有取消-请阅的请求被累积(缓存)，并且在调用ca_flush_io(), ca_pend_io(), 
ca_pend_event()或ca_sg_block()之一前，不被转发给IOC。这允许若干请求在一条消息中被高效地发送。
注意：在用于这个通道的任何用户回调运行到结束前，此操作阻塞。如果回调获取了一个锁(mutex)，
则确保在调用ca_clear_subscription()时，这个锁未被持有，是用户的责任，否则死锁可能发生。

参数
EVID：ca_create_subscription()返回地事件id

返回：

• ECA_NORMAL - 正常成功结束。
• ECA_BADCHID - 损坏的CHID

9、ca_pend_io()

#include 
int ca_pend_io ( double TIMEOUT );

这个函数冲刷发送缓存并且接着在待处理ca_get()请求结束前，以及指定null连接处理程序函数指针创建的通道首次连接前，阻塞。
如果返回ECA_NORMAL，则可以安全地认为所有待处理的ca_get()请求都成功的结束了以及指定null连接处理程序函数指针创建的
通道首次连接了。

如果返回ECA_TIMEOUT，则必须认为所有先前ca_get()请求以及可能符合首次通道连接失败了。
如果返回ECA_TIMEOUT, get请求可以再次被发送，后面再接一个对ca_pend_io()的调用。
尤其，在对ca_create_channel()的最新调用或者ca客户端上下文创建(无论哪个在更晚)之后，
此函数将只阻塞发送的待处理ca_get()请求，以及指定null连接处理程序函数指针创建的任何通道。

注意：除非之前调用ca_clear_channel()，否则不应该为相同过程变量再次发送ca_create_channel()。

如果没有ca_get()或连接状态变化事件是待处理，则ca_pend_io()将冲刷发送缓存并且立即返回，
而不运行任何待处理通道访问后台活动。
为ca_pend_io()指定的延时应该考虑最坏网络延时的情况。

不同于ca_pend_event()，如果所选的IO请求中美欧请求正在发生，这个例程将不处理CA的后台活动。

参数：
1)TIMEOUT: 指定超时间隔。0的TIMEOUT间隔指定永远。
返回：
ECA_NORMAL - 正常成功结束
ECA_TIMEOUT - 所选IO请求在指定超时前没有结束。
ECA_EVDISALLOW - 函数不适合在一个事件处理程序中使用

10、ca_test_io()

int ca_test_io()

这个函数测试所有ca_get()请求是否结束以及指定null连接回调函数指针创建的通道是否连接。
在上次调用ca_pend_io()或者CA上下文初始化后，它将报告待发出的待处理的ca_get()请求，以及指定null连接回调函数指针创建的通道的状态。

返回：
ECA_IODONE - 所有操作结束。
ECA_IOINPROGRESS - IO操作仍在继续

11、ca_pend_event()

#include 
int ca_pend_event ( double TIMEOUT );
int ca_poll ();

当ca_pend_event()被调用时，发送缓存被冲刷并且CA后台活动被处理TIMEOUT秒。
当调用ca_poll()时，发送缓存被冲刷并且任何待处理的CA后台活动被处理。
ca_pend_event()函数在指定的超时以及所有未完成的通道访问工作被处理前不返回，
并且不同于ca_pend_io()，从此函数返回不表明有关正在发生IO请求状态的。

ca_pend_event()和ca_poll()成功时，返回ECA_TIMEOUT。
这种行为不直接，但保留它为了确保后向兼容。
参数：
TIMEOUT:以秒为单位，在这个例程中阻塞的时长。0的超时永远阻塞。
返回：
ECA_TIMEOUT - 操作超时
ECA_EVDISALLOW - 函数不适合在一个回调处理程序中使用

12、ca_flush_io()

#include 
int ca_flush_io();

描述：冲刷待处理IO请求到服务器。
这个例程对与在服务器中工作一起并行执行客户端工作前冲刷请求的用户有用。
在保存待处理请求的缓存满时，待处理请求也被发送。

返回：
ECA_NORMAL - 正常成功结束。

13、ca_replace_access_rights_event()

#include 
typedef struct ca_access_rights {
    unsigned    read_access:1;
    unsigned    write_access:1;
} caar;

struct  access_rights_handler_args {
    chanId  chid;   /* channel id */
    caar    ar;     /* new access rights state */
};

typedef void ( caEventCallBackFunc )(struct access_rights_handler_args);
int ca_replace_access_rights_event ( chid CHAN,
        caEventCallBackFunc PFUNC );

为指定通道安装或替换访问权状态变化回调处理程序。在以下情况中调用这个回调处理程序。
就在通道的连接处理程序被调用前，CA连接了通道。
就在通道的断开回调被调用后，CA断开通道。
如果通道连接了，在安装后，立即调用一次。
在一个连接的通道访问权状态变化时。
当创建一个通道时，没有安装访问权处理程序。

参数：
CHAN：通道标识符。
PFUNC：指向一个用户提供的回调函数的指针。
一个null指针，卸载当前处理程序。以下参数通过值被传递给提供的回调处理程序。

返回：
ECA_NORMAL - 正常成功结束。

14、ca_field_type()

#include 
chtype ca_field_type ( CHID );

描述：
返回过程变量在服务器中本地类型。

参数：
CHID：通道标识符。
返回：
TYPE：数据类型代码，它是db_access.h中DBF_XXXX集合成员之一。
如果通道断开了，返回常数TYPENOTCONN

15、ca_element_count()

#include 
unsigned ca_element_count ( CHID );

描述：
返回指定IO通道在服务器中最大数组元素数目。

参数：
CHID：通道标识符。
返回：
COUNT：在服务器中最大数组元素数目。如果通道断开了，返回元素数目0

16、ca_name()

#include 
char * ca_name ( CHID );

描述：
返回在创建提供的通道时提供的名称。
参数：
CHID：通道标识符。
返回：
PNAME：通道名。只要指定的通道存在，返回的字符串是有效的。

17、ca_set_puser()

#include 
void ca_set_puser ( chid CHID, void *PUSER );

描述：
设置为每个通道保留的用户私有void指针变量，提供给用户使用。
参数：
CHID：通道标识符。
PUSER：用户私有void指针

18、ca_puser()

#include 
void * ca_puser ( CHID );

描述：
返回为每个通道保留的用户私有void指针，提供给用户使用。
参数：
CHID：通道标识符。
返回：
PUSER：用户私有指针

20、ca_state()

#include 
enum channel_state {
    cs_never_conn, //有效的chid,服务器不能找到或获取不到  
    cs_prev_conn,  //有效的chid, 之前连接了服务器
    cs_conn,       //有效的chid, 连接了服务器 
    cs_closed };   //用户删除的通道
enum channel_state ca_state ( CHID );

返回：
一个枚举类型，表明指定IO通道的当前状态
参数：
CHID：通道标识符
返回：
STATE：连接状态

21、ca_message()

#include 
const char * ca_message ( STATUS );

描述：
返回一条消息字符串，对应一个用户指定的CA状态代码。
参数：
STATUS：一个CA状态代码。
返回：对应的错误消息字符串。

22、ca_host_name()

#include 
char * ca_host_name ( CHID );

描述：返回一个字符串，它包含一个当前连接通道的主机名的字符串。
参数：
CHID：通道标识符。
返回：
STRING：过程变量的主机名。如果通道断开了，返回字符串""

23、ca_read_access()

#include 
int ca_read_access ( CHID );

描述：
如果客户端当前对指定通道有读访问权，返回true，否则返回false。
参数：
CHID：通道标识符。
the channel identifier
返回：
STRING：如果客户端当前对指定通道有读访问权，返回true，否则返回false。

24、ca_write_access()

#include 
int ca_write_access ( CHID );

描述：
如果客户端当前对指定通道有写访问权，返回true，否则返回false。
参数：
CHID：通道标识符。
返回：
STRING：如果客户端当前对指定通道有读访问权，返回true，否则返回false。

25、dbr_size[]

#include 
extern unsigned dbr_size[/* TYPE */];

描述：
一个数组，它用字节返回对应DBR_XXXX类型的大小。
An array that returns the size in bytes for a DBR_XXXX type.

参数：
TYPE：数据类型代码。它是db_access.h中集合的成员。
返回：
SIZE：指定类型的字节为单位的大小。

26、dbr_size_n()

#include 
unsigned dbr_size_n ( TYPE, COUNT );

描述：
以字节为单位返回对应数目COUNT个DBR_XXXX类型的大小。
如果DBR类型是一个结构体，则值字段是这个结构体中末尾字段。
如果COUNT大于1，则在结构体末尾添加COUNT-1个元素，因而它们可以通过指向值字段的指针以数组被寻址。
参数：
TYPE：数据类型。
COUNT：元素数目。
返回： 
SIZE：以字节为单位返回对应数目COUNT个DBR_XXXX类型的大小。

27、dbr_value_size[]

#include 
extern unsigned dbr_value_size[/* TYPE */];

描述：
数组dbr_value_size[TYPE]以字节为单位返回用DBR_XXXX类型存储的值的大小。
如果类型是一个结构体，返回值字段的大小，否则返回这个类型的大小。
参数：
TYPE：数据类型代码。db_access.h中DBF_XXXX集合的一个成员。
返回：
SIZE：如果这个类型是一个结构体，则以字节为单位的值字段的尺寸，否则以字节为单位的这个类型的尺寸

28、dbr_type_to_text()

#include 
const char * dbr_type_text ( chtype TYPE );

描述：返回对应指定dbr类型的常量null结尾字符串。
参数：ｌｆ
TYPE：数据类型代码。 在db_access.h中DBR_XXXX集合一个成员。
返回： 对应DBR_XXX类型的常量字符串。

29、ca_test_event()

#include 
void ca_test_event ( struct event_handler_args );

描述：
一个内建订阅更新回调处理程序，用于打印诊断到标准输出的调试目的。
示例：
void ca_test_event ();
status = ca_create_subscription ( type, chid, ca_test_event, NULL, NULL );
SEVCHK ( status, .... );

30、ca_signal()

#include 
int ca_signal ( long CA_STATUS, const char * CONTEXT_STRING );
void SEVCHK( CA_STATUS, CONTEXT_STRING );

描述：
提供与提供的通道错误代码相关联的错误消息字符串和提供的错误上下文给诊断。
如果错误代码表示一个不成功的操作，输出一个栈转储，
如果这个功能在本地操作系统上可用，并指执行被终止。
SEVCHK是一个对ca_signal()的宏封装，只在提供的错误代码表示一个不成功操作时，它才调用ca_signal()。
对于不想要编写测试从每次通道访问调用返回的状态代码的简单程序，SEVCHK是推荐的错误处理程序。

示例：
status = ca_context_create (...);
SEVCHK ( status, "Unable to create a CA client context" );
如果程序只想要输出与一个错误代码相关联的消息或者测试一个错误的严重性，也有为此目的提供的函数。

参数：
CA_STATUS：从通道访问调用返回的状态(错误代码)。
CONTEXT_STRING：一个null结尾的字符串，作为错误上下文提供给诊断。
返回：
ECA_NORMAL ：正常成功结束。 

31、ca_add_exception_event()

#include 

struct exception_handler_args {
    void            *usr;   // 在安装时提供的用户参数 
    chanId          chid;   // 通道id(可以时null) 
    long            type;   // 请求的类型 
    long            count;  // 请求的数目
    void            *addr;  // 写CA_OP_GET结果的用户地址 
    long            stat;   // 通道访问ECA_XXXX状态代码
    long            op;     // CA_OP_GET, CA_OP_PUT, ..., CA_OP_OTHER 
    const char      *ctx;   // 一个包含上下文信息的字符串
    sonst char      *pFile; // 源文件名称(可以是NULL) 
    unsigned        lineNo; // 源文件行号(可以是0) 
};

typedef void (*pCallback) ( struct exception_handler_args HANDLERARGS );
int ca_add_exception_event ( pCallback  USERFUNC, void *USERARG );

描述：
替代当前安装的CA上下文全局异常处理程序回调。
当在服务器中异步于客户端线程发生了错误，则有关这个错误类型的信息用一条异常消息从服务器传递到客户端。
当客户端接收到这条异常消息时，一个异常处理程序回调被调用。
默认异常处理程序在客户端标准输出上打印一条诊断消息并且如果错误情况严重终止执行。
注意：在"struct exception_handler_args"中某个字段在某些错误消息中未使用。
例如，一个出错的get将在客户端任务中提供地址，被请求的返回值被写入此处。
对于其它出错操作，addr字段的值不应该被使用。

参数：
USERFUNC: 指向一个用户回调函数的指针，在异常发生时，被执行。
传递一个null值，使得默认的异常处理程序被卸载。
以下结构体通过值被传递给用户的回调函数。当前，op字段可以是
CA_OP_GET, CA_OP_PUT, CA_OP_CREATE_CHANNEL, CA_OP_ADD_EVENT, CA_OP_CLEAR_EVENT或CA_OP_OTHER之一

USERARG：保留的指针大小的变量，并且回传给以上用户函数

示例：
void ca_exception_handler (struct exception_handler_args args)
{
    char buf[512];
    char *pName;

    if ( args.chid ) {
        pName = ca_name ( args.chid ); // 从通道标识符获取通道名称
    }
    else {
        pName = "?";
    }
    // 向缓存输出：上下文信息的字符串字符串，通道名称，操作类型，请求的数据类型，请求的数目
    sprintf ( buf,
            "%s - with request chan=%s op=%d data type=%s count=%d",
            args.ctx, pName, args.op, dbr_type_to_text ( args.type ), args.count );
    ca_signal ( args.stat, buf ); //通道访问ECA_XXXX状态代码不为ECA_NORMAL，则输出buf内容
}
ca_add_exception_event ( ca_exception_handler , 0 );
返回：
ECA_NORMAL - 正常成功结束

32、ca_replace_printf_handler ()

#include 
typedef int caPrintfFunc ( const char *pFormat, va_list args );
int ca_replace_printf_handler ( caPrintfFunc *PFUNC );

描述：
替代用于格式化的诊断消息输出的默认处理程序。默认处理程序使用fprintf发送消息给'stderr'。

参数：
PFUNC：指向用户提供的回调处理程序的指针，在CA输出诊断消息时被调用。
安装一个null指针，将使得默认的回调处理程序被卸载。

示例
int my_printf ( char *pformat, va_list args ) {
        int status;
        status = vfprintf( stderr, pformat, args);
        return status;
}
status = ca_replace_printf_handler ( my_printf );
SEVCHK ( status, "failed to install my printf handler" );
返回：
ECA_NORMAL - 正常成功结束。

33、ca_sg_create()

#include 
int ca_sg_create ( CA_SYNC_GID *PGID );

描述：
创建一个同步组，并且为它返回一个标识符。
一个同步组可以用于确保一个通道访问请求集合已经结束。
一旦创建了一个同步组，则能够各自使用ca_sg_array_get()和ca_sg_array_put发送通道访问get和put请求。
例程ca_sg_block()和ca_sg_test()可以各自用于阻塞和测试结束。
例程ca_sg_reset()用于丢弃那些已经超时以及所有可能性中将不会被满足的老请求。

任何数目的异步组能够使得在任何指定时间在它们内有待处理的程序请求的操作。

参数：
PGID：指向一个用户提供的CA_SYNC_GID的指针
示例：
CA_SYNC_GID gid;
status = ca_sg_create ( &gid );
SEVCHK ( status, Sync group create failed );
返回：
ECA_NORMAL - 正常成功结束。
ECA_ALLOCMEM - 失败，不能分配内存

34、ca_sg_delete()

#include 
int ca_sg_delete ( CA_SYNC_GID GID );

描述：
删除一个同步组。

参数：
GID：要被删除的同步组的标识符。
示例：
CA_SYNC_GID gid;
status = ca_sg_delete ( gid );
SEVCHK ( status, Sync group delete failed );
返回：
ECA_NORMAL - 正常成功结束。
ECA_BADSYNCGRP - 无效的同步组

35、ca_sg_block()

#include 
int ca_sg_block ( CA_SYNC_GID GID, double TIMEOUT );

描述：
冲刷发送缓存，并且接着等待到待处理请求结束或者指定时间超时。
此时，待处理请求包括对ca_sg_array_get()和ca_sg_array_put()的调用。
冲刷发送缓存，并且接着等待，直到待处理请求结束或者指定时间超时。
到此时，待处理请求包括对ca_sg_array_get()的调用和对ca_sg_array_put()的调用。 
如果返回了ECA_TIMEOUT,则必须认为所有待处理请求出错了。
操作可以被再次发送，后跟另一个ca_sg_block()。

这个例程将仅阻塞上次调用ca_sg_block(), ca_sg_reset()或ca_sg_create()(以较晚发生的为准)之后发出的待处理请求。
如果没有请求是待处理的，则ca_sg_block()将立即返回，而不处理任何正在发生的通道访问活动。
在从ca_sg_block()接收到ECA_NORMAL前，通过通道访问同步组请求写入你程序变量的值不应该被你的程序引用。
当这个例程正在等待时，它将处理正在发生的通道后台活动。

参数：
GID：同步组的标识符。
TIMEOUT：在这个例程中阻塞以秒为单位的持续时间。超时为0则一直阻塞。

示例：
CA_SYNC_GID gid;
status = ca_sg_block(gid, 0.0);
SEVCHK(status, Sync group block failed);

返回：
ECA_NORMAL - 正常的成功结束
ECA_TIMEOUT - 操作超时
ECA_EVDISALLOW - 函数不适合在一个事件处理程序中使用
ECA_BADSYNCGRP - 无效的同步组

36、ca_sg_test()

#include 
int ca_sg_test ( CA_SYNC_GID GID )

描述：
测试在一个同步组中所有请求是否结束。

参数：
GID：同步组的标识符。

示例：
CA_SYNC_GID gid;
status = ca_sg_test ( gid );

返回：
ECA_IODONE - IO 操作结束
ECA_IOINPROGRESS - 某些IO操作仍在进行中

37、ca_sg_reset()

#include 
int ca_sg_reset ( CA_SYNC_GID GID )

描述：
重置在指定同步组内待处理请求数目为0，使得ca_sg_test()将返回ECA_IONODE并且ca_sg_block()将不阻塞，
除非进行了另外后续的请求。
参数：
GID：同步组标识符。

示例：
CA_SYNC_GID gid;
status = ca_sg_reset(gid);
返回：
ECA_NORMAL - 正常成功结束。
ECA_BADSYNCGRP - 无效的同步组。

38、ca_sg_array_put()

#include 
int ca_sg_put ( CA_SYNC_GID GID, chtype TYPE,
        chid CHID, void *PVALUE );
int ca_sg_array_put ( CA_SYNC_GID GID, chtype TYPE,
        unsigned long COUNT, chid CHID, void *PVALUE );

描述：
写一个值或者值的数组到一个通道并且增加一个同步组的待处理请求计数。使用ca_array_put_callback()实现了
ca_sg_put()和ca_sg_array_put()功能。 
诸如以上的所有远程操作请求被累积(缓存)，并且在ca_flush_io(), ca_pend_io(), ca_pend_event()或ca_sg_block()
之一被调用前，不转发给服务器。这使得若干请求在一条消息中被高效地发送。
如果一个连接丢失了，并且接着继续，待处理puts将不被重新发送。

参数：
GID:同步组标识符。
TYPE：提供值的类型。如果它不匹配本地类型，将发生转换。从指定db_access.h中DBR_XXXX集合之一。
COUNT：要写入指定通道的元素数目，必须匹配由PVALUE指向的数组。
CHID：通道标识符。
PVALUE：指向一个程序提供缓存的指针，它包含返回的值或者值的数组。

返回：
ECA_NORMAL - 正常的成功结束
ECA_BADSYNCGRP - 无效的同步组
ECA_BADCHID - 损坏的CHID
ECA_BADTYPE - 无效的DBR_XXXX类型
ECA_BADCOUNT - 请求的计数大于本地元素数目
ECA_STRTOBIG -  提供了异常大的字符串
ECA_PUTFAIL - 一个本地数据库put出错

39、ca_sg_array_get()

#include 
int ca_sg_get ( CA_SYNC_GID GID, chtype TYPE,
        chid CHID, void *PVALUE );
int ca_sg_array_get ( CA_SYNC_GID GID,
        chtype TYPE, unsigned long COUNT,
        chid CHID, void *PVALUE );

描述：
从通道读取一个值并且增加一个异步组的待处理请求数目。
使用ca_array_get_callback()实现了ca_sg_get和ca_sg_array_put()功能。
在从ca_sg_block()接收到ECA_NORMAL前或者在ca_sg_test()返回ECA_IODONE前，由ca_sg_get()或ca_sg_array_get()写入你程序变量的值
不应该被你的程序引用。
诸如以上的所有远程操作请求被累积(缓存)，并且在ca_flush_io(), ca_pend_io(), ca_pend_event()或ca_sg_block()之一被调用前，不转发给服务器。
这使得若干请求在一条消息中被高效地发送。
如果连接丢失，接着恢复，待处理请求不被重新发送。

参数：
GID：同步组的标识符。
Identifier of the synchronous group.
TYPE：返回值的外部类型。如果它不匹配本地类型，将发生转换。从指定db_access.h中DBR_XXXX集合之一。
COUNT：从指定通道读取的元素数目。它必须匹配由PVALUE指向的数组。
CHID：通道标识符。
PVALUE：指向程序提供缓存的指针，它包含返回值或值的数组。
返回：
ECA_NORMAL - 正常的成功结束
ECA_BADSYNCGRP - 无效同步组
ECA_BADCHID - 损坏的CHID
ECA_BADCOUNT - 请求的计数大于本地元素数目
ECA_BADTYPE - 无效的DBR_XXXX类型
ECA_GETFAIL - 一个本地数据库get出错

40、ca_client_status()

int ca_client_status ( unsigned level );
int ca_context_status ( struct ca_client_context *CONTEXT,
       unsigned LEVEL );

描述：
打印有关这个客户端的信息，包括：每个通道的状态。
缺少CA上下文指针，ca_client_status()打印有关进行调用线程的CA上下文信息。
参数：
CONTEXT：指向要检查的CA上下文的指针
LEVEL：兴趣级别。增加级别产生更详细信息。

41、ca_current_context()

struct ca_client_context * ca_current_context ();

描述：
返回一个指向当前线程的CA上下文的指针。如果None，则返回null。

42、ca_attach_context()

int ca_attach_context (struct ca_client_context *CONTEXT);

描述：
调用线程变成了指定CA上下文的一个成员。如果指定了ca_disable_preemptive_callback，
当ca_context_create()被调用时(或者如果ca_task_initilize()被调用)，
则其它线程不被允许加入这个CA上下文，
因为允许其它线程加入隐含CA回调将被从多个线程抢占式回调。
参数：
CONTEXT：一个指向要加入的CA上下文的指针。
返回：
ECA_NORMAL - 正常成功结束
ECA_NOTTHREADED - 环境不是抢占式的，因而不能被加入
ECA_ISATTACHED - 线程已经连接到了一个CA上下文。

43、ca_detach_context()

void ca_detach_context();

描述：
从当前连接到调用线程分离任何CA上下文。
这不清理或关闭任何当前连接的CA上下文(要清理或关闭，使用ca_context_destroy())。

44、ca_dump_dbr()

void ca_dump_dbr (chtype TYPE, unsigned COUNT, const void * PDBR);

描述：
输出指定dbr数据类型到标志输出。
参数：
TYPE：数据类型(来自db_access.h中描述的DBR_XXX集合)。
COUNT：数组元素数目。
PDBR：一个指向指定计数和数数值的指针

45、ca_add_fd_registration()

#include 
int ca_add_fd_registration ( void ( USERFUNC * ) ( void *USERARG, int FD, int OPENED ), void * USERARG )

描述：
用于与由文件描述符管理程序(IO复用器)提供的服务一起使用，
诸如"fdmgr.c"。当两个文件描述符IO密集库，诸如EPICS通道访问客户端库和X Window系统客户端库
必须在相同UNIX进程中共存时，经常需要一个文件描述符管理器。
这个函数运行一个程序代码在CA客户端库向服务放置一个新的文件描述符以及CA客户端库从服务移除一个文件描述符时
被通知。
指定USERFUNC=NULL，禁用文件描述符注册(这是默认)。
参数：
USERFUNC：指向一个使用以上参数返回为NULL的用户提供的C函数的指针。
USERARG：用户提供的指针大小的变量，被传递给以上函数。

FD：文件描述符。

OPENED：如果文件描述符被打开，布尔参数是真，而如果文件描述符被关闭，为false。

示例：
int s;
static struct myStruct aStruct;

void fdReg ( struct myStruct *pStruct, int fd, int opened )
{
    if ( opened ) printf ( "fd %d was opened\n", fd );
    else printf ( "fd %d was closed\n", fd );
}
s = ca_add_fd_registration ( fdReg, & aStruct );
SEVCHK ( s, NULL );
注释：
当使用这个函数时，建议仅在调用任何其它CA函数前调用它一次，或者只在创建了CA上下文后调用一次
(如果你显式地创建了这个上下文)。
相较于另外的只周期进行轮询的ca_pend_event()的接口，
这个接口的使用会以某些其它运行时开销为代价稍微增加了使用非抢占式回调模式程序的延时。
对抢占式回调模式使用这个函数可能不适合。

返回：
"ECA_NORMAL - 正常成功结束。