Channel Access Client Reference
#include <cadef.h>
int ca_task_initialize();ARGUMENTS
DESCRIPTION
Should be called once prior to making any of the other channel access calls.
COMMENTS
Invoked once at first call to any ca_xxx() function if you forget.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_ALLOCMEM - Failed, unable to allocate memory" on page 38
SEE ALSO
"ca_task_exit()" on page 13
#include <cadef.h>
int ca_task_exit();ARGUMENTS
DESCRIPTION
Close channel access facility and free any resources allocated.
COMMENTS
Performed automatically at task (or process) exit.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
SEE ALSO
"ca_task_initialize()" on page 13
#include <cadef.h>
int ca_search_and_connect ( char *CHANNEL_NAME; chid *PCHID; void (*USERFUNC)(struct connection_handler_args ARGS); void *PUSER; );ALIASES
int ca_search(NAME,PCHID)
ARGUMENTS
NULL terminated ASCII channel name string. ASCII channel names are of the form "<channel name>.[<field name>]". If the field name and the separator is omitted the ".VAL" field is assumed. For Example "RFHV01" and "RFHV01.VAL" reference the same channel.
Channel identifier written into user supplied channel id pointed to by PCHID
Optional address of user subroutine to be run when the connection state changes. Casual users of channel access may wish to set this field to nill or 0 if they do not need to have a connection handler run.
The value of this argument is stored in a pointer sized user available field 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 nill or 0.
DESCRIPTION
This function requests that the CA library should attempt to establish and maintain a virtual circuit between the caller's application and a named variable in a CA server. Each call to ca_search() allocates resources in the client library and potentially in the server. The function ca_clear_channel() is used to release these resources. The circuit may be initially connected or disconnected depending on the state of the network and the location of the channel. If there are sufficient resources to initiate this process then the routine writes a channel identifier into the application supplied variable pointed to by PCHID and returns ECA_NORMAL. This identifier can be used with all of the other channel access calls that operate on a channel.
A channel will only become connected after channel access is able to locate a channel access server that has access to the named variable and only if channel access is able to find a path through the network to this server. All of the channel access routines that send a request to a channel access server will refuse to operate on a channel that is disconnected. There are two ways to obtain asynchronous notification when a channel enters a connected state. The first and simplest method requires that you call ca_pend_io() prior to using a channel id returned by ca_search(). The second requires that you establish a connection handler by supplying a non-zero USERFUNC. 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 not block waiting for this channel's connection to occur.
COMMENTS
A better name for this function would be ca_create_channel().
The MACRO ca_state(CHID) can be used to test the connection state of a channel. Valid connections may be isolated from invalid ones with this MACRO if ca_pend_io() times out.
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 allowing several operations to be efficiently sent over the network in one message.
Note that due to the inherent 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.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_STRTOBIG - Unusually large string supplied" on page 38
"ECA_ALLOCMEM - Unable to allocate memory" on page 38
"ECA_GETFAIL - A local database get failed" on page 38
SEE ALSO
"ca_pend_io()" on page 22
"ca_change_connection_event()" on page 25
"macros" on page 28
#include <cadef.h>
int ca_clear_channel ( evid CHID );ARGUMENTS
identifier of the channel to close (returned by "ca_search()" on page 14).
DESCRIPTION
Close a channel created by ca_search().
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 allowing several operations to be efficiently sent over the network in one message.
COMMENTS
Clearing a channel does not cause its disconnect handler to be called. Clearing a channel does remove any events (monitors) registered for that channel. If the channel is currently connected then resources are freed only some time after this request is flushed out to the server,
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
SEE ALSO
"ca_add_event()" on page 20
#include <cadef.h>
int ca_array_put( chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE )ALIASES
int ca_bput(chid CHID, char *PVALUE);
int ca_rput(chid CHID, dbr_float_t *PVALUE); int ca_put(chtype TYPE, chid CHID, void *PVALUE);ARGUMENTS
The external type of the 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
Element count to be written to the specified channel. This must match the array pointed to by PVALUE.
Channel identifier
Pointer to a value or array of values provided by the application to be written to the channel.
DESCRIPTION
Write a value or array of values to a channel.
COMMENTS
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 allowing several operations to be efficiently combined into one network frame.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_BADCOUNT - Requested count larger than native element count" on page 38
"ECA_STRTOBIG - Unusually large string supplied" on page 38
"ECA_NOWTACCESS - Write access denied" on page 39
SEE ALSO
"ca_flush_io()" on page 24
#include <cadef.h>
int ca_array_put_callback ( chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE, void (*PFUNC)(struct event_handler_args ARGS), void *USERARG, );ARGUMENTS
The external type of the 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
ARGUMENTS
Element count to be written to the specified channel. This must match the array pointed to by PVALUE.
Channel identifier
Pointer to a value or array of values provided by the application to be written to the channel.
address of user subroutine to be run when the requested operation completes
pointer sized object passed to user function above
DESCRIPTION
Write a value (or array of values) to a channel and run the user supplied asynchronous call back only after the initiating put operation and all actions resulting from the initiating put operation complete.
COMMENTS
The structure"event_handler_args" is defined in the file ''cadef.h''.
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 allowing several operations to be efficiently combined into one network frame.
If a connection is lost and then resumed outstanding put requests are not automatically reissued following reconnect.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADCOUNT - Requested count larger than native element count" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_ALLOCMEM - Unable to allocate memory" on page 38
"ECA_NOWTACCESS - Write access denied" on page 39
SEE ALSO
"ca_pend_event()" on page 23, "ca_flush_io()" on page 24
#include <cadef.h>
int ca_array_get ( chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE );ALIASES
int ca_bget(chid CHID, char *PVALUE);
/* NOTE: bget fetches the binary value as a string */
int ca_rget(chid *CHID, dbr_float_t *PVALUE); int ca_get(chtype TYPE, chid CHID, void *PVALUE);ARGUMENTS
The external type of the value to be returned. Conversion will occur if this does not match the native type. Specify one from the set of DBR_XXXX in db_access.h
Element count to be read from the specified channel. Must match the array pointed to by PVALUE.
Channel identifier
Pointer to an application supplied buffer where the current value of the channel is to be written.
DESCRIPTION
Read a value from a channel.
COMMENTS
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().
See ca_get_callback() if it is important to know when an individual get completes.
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 allowing several operations to be efficiently sent over the network in one message.
If a connection is lost and then resumed outstanding get requests are not automatically reissued following reconnect
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADCOUNT - Requested count larger than native element count" on page 38
"ECA_GETFAIL - A local database get failed" on page 38
"ECA_NORDACCESS - Read access denied" on page 39
SEE ALSO
"ca_pend_io()" on page 22
"ca_get_callback()" on page 19
#include <cadef.h>
int ca_array_get_callback ( chtype TYPE, unsigned long COUNT, chid CHID, void (*USERFUNC)(struct event_handler_args ARGS), void *USERARG );ALIASES
int ca_bget_callback(CHID, USERFUNC, USERARG);
int ca_rget_callback(CHID, USERFUNC, USERARG); int ca_get_callback(TYPE, CHID, USERFUNC, USERARG);ARGUMENTS
The external type of the returned value. Conversion will occur if this does not match the native type. Specify one from the set of DBR_XXXX in db_access.h
The element count to be read from the specified channel.
Channel index
Address of user subroutine to be run when the requested operation completes.
Pointer sized object passed to user function above
DESCRIPTION
Read a value from a channel and run a callback when the operation completes.
COMMENTS
The structure "event_handler_args" is defined in the file ''cadef.h''.
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 allowing several operations to be efficiently sent over the network in one message.
Note however that ca_pend_io() will not wait for the delivery of values requested by ca_get_callback().
If a connection is lost and then resumed outstanding gets are not reissued.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADCOUNT - Requested count larger than native element count" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_GETFAIL - A local database get failed" on page 38
"ECA_ALLOCMEM - Unable to allocate memory" on page 38
"ECA_NORDACCESS - Read access denied" on page 39
SEE ALSO
"ca_clear_event()" on page 22
"ca_flush_io()" on page 24
#include <cadef.h>
int ca_add_masked_array_event ( chtype TYPE, unsigned long COUNT, chid CHID, void (*USERFUNC)(struct event_handler_args ARGS), void *USERARG, float 0 float 0 float 0 evid *PEVID, unsigned long MASK );ALIASES
int ca_add_array_event(TYPE,COUNT,CHID,USERFUNC,USERARG,
(double)0.0, (double)0.0,(double)0.0,PEVID); int ca_add_event(TYPE, CHID, USERFUNC, USERARG, PEVID);ARGUMENTS
type of returned value- conversion will occur if it does not match native type. Specify one from the set of DBR_XXXX in db_access.h
element count to be read from the specified channel - a count of zero specifies the DB native count.
channel index
address of user subroutine to be run when events occur
pointer sized object passed to user function above
Three double precision, floating-point zeros--double (0) or 0.0--that must be included in all calls to ca_add_masked_array_event() or ca_add_array_event(), but not ca_add_event(). They are reserved for future use. Your code will remain upwardly compatible if you specify (double) 0.0.
pointer to user supplied event id which is initialized by this subroutine call. User's event id can later be used to clear a specific event. PEVID may be omitted by passing a NULL pointer.
A mask with bits set for each of the event trigger types required. The event trigger mask must be a logical or of one or more of the following constants.
DBE_VALUE:
Trigger events when the channel value exceeds the monitor dead band
DBE_LOG:
Trigger events when the channel value exceeds the archival dead band
DBE_ALARM:
Trigger events when the channel alarm state changes.
For aliases which do not include a trigger specification events will be triggered when the channel's value exceeds the monitor dead band or when the channel's alarm state changes (that is DBE_VALUE | DBE_ALARM).
DESCRIPTION
Specify a subroutine to be run whenever significant changes occur to a channel. A significant change can be a change in the channels value, alarm status, or severity status. Events may be added and deleted from 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 it is a local channel. If an event is added prior to channel connection the requested count will be set to the native count of the channel if the requested count is larger.
COMMENTS
The structure"event_handler_args" is defined in the file ''cadef.h''. 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 allowing several operations to be efficiently sent over the network in one message.
If at any time after registering the event read access to the specified channel is lost then the call back will be called immediately, indicating that read access was lost with the status argument. When read access is restored normal event processing will resume.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_ALLOCMEM - Unable to allocate memory" on page 38
"ECA_ADDFAIL - A local database event add failed" on page 38
SEE ALSO
"ca_pend_event()" on page 23
"ca_flush_io()" on page 24
#include <cadef.h>
int ca_clear_event(evid EVID);ARGUMENTS
event id returned by add_event()
DESCRIPTION
Remove a subroutine from a list of those run whenever significant changes occur on an IO channel. Event is disabled immediately. However resources are not recovered until the operation has completed in the server. 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 allowing several operations to be efficiently sent over the network in one message.
COMMENTS
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADCHID - Corrupted CHID" on page 38
SEE ALSO
"ca_add_event()" on page 20
#include <cadef.h>
int ca_pend_io(double TIMEOUT);ARGUMENTS
time out after TIMEOUT seconds (TIMEOUT of zero is forever).
DESCRIPTION
Flushes the send buffer and then waits until outstanding queries complete or the specified time out expires. At this time queries include calls to ca_get() and calls to ca_search() which don't specify a connection handler. If ECA_TIMEOUT is returned then failure must be assumed for all outstanding queries. Operations can be reissued followed by another ca_pend_io(). This routine will only block on outstanding queries issued after the last call to ca_pend_io() or the start of program execution whichever occurs later in time. If no queries are outstanding then ca_pend_io() will flush the send buffer and return immediately without processing any additional outstanding channel access labor.
COMMENTS
Any values written into your program's variables by a channel access synchronous request should not be referenced by your program until ECA_NORMAL has been received from ca_pend_io().
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 you find that operations are timing out during situations when the network isn't broken then you may need to increase the specified time-out. If ca_pend_io() prematurely times out then the requests are lost and must be reissued.
This routine will handle channel access background activity while it is waiting.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_EVDISALLOW - Function inappropriate for use within an event handler" on page 39
SEE ALSO
"ca_get()" on page 18
"ca_search()" on page 14
"ca_test_io()" on page 23
#include <cadef.h>
int ca_test_io();ARGUMENTS
DESCRIPTION
Determines if any queries are outstanding. This routine will only report the status of outstanding query operations issued after the last call to ca_pend_io() or the start of program execution whichever occurs later in time.
RETURNS
"ECA_IODONE - IO operations completed" on page 39
"ECA_IOINPROGRESS - Some IO operations still in progress" on page 39
SEE ALSO
"ca_pend_io()" on page 22
#include <cadef.h>
int ca_pend_event(double TIMEOUT);ARGUMENTS
time out after TIMEOUT seconds.
DESCRIPTION
Flushes the send buffer and waits for asynchronous events for TIMEOUT seconds (TIMEOUT of zero is forever). This routine will not return before the time-out expires and all unfinished channel access labor has been processed.
COMMENTS
A very short TIMEOUT (see ca_poll() below) will result in a poll (i.e. channel access will process outstanding background activity and then return).
This routine will perform channel access background activity while it is waiting.
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_TIMEOUT - The operation timed out" on page 38
"ECA_EVDISALLOW - Function inappropriate for use within an event handler" on page 39
SEE ALSO
"ca_poll()" on page 24
#include <cadef.h>
int ca_poll();DESCRIPTION
COMMENTS
This routine will perform outstanding channel access background activity and then return.
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_TIMEOUT - The operation timed out" on page 38
"ECA_EVDISALLOW - Function inappropriate for use within an event handler" on page 39
SEE ALSO
"ca_pend_event()" on page 23
#include <cadef.h>
int ca_flush_io();ARGUMENTS
DESCRIPTION
Send (flush) buffered IO requests. Normally performed by ca_pend_io() or ca_pend_event(). However, some users may wish to flush remote operation request messages early so they can perform operations in parallel with outstanding remote operations.
COMMENTS
Outstanding requests are also sent whenever the buffer which holds them becomes full.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
SEE ALSO
#include <cadef.h>
int ca_signal(long CA_STATUS, char *CONTEXT_STRING);ALIASES
void SEVCHK(CA_STATUS, CONTEXT_STRING)
ARGUMENTS
The status (error code) returned from a channel access function.
A null terminated character string to print as error context.
DESCRIPTION
Print the error message character string associated with the supplied channel access error code and the supplied error context. If the error code indicates an unsuccessful operation a stack dump is printed, if this capability is available on the local operating system, and execution is terminated. SEVCHK is a macro envelope around ca_signal which only calls ca_signal() if the supplied error code indicates an unsuccessful operation. SEVCHK is the recommended error handler for those applications which do not wish to write code testing the status returned from each channel access call.
EXAMPLES
status = ca_task_initialize(...);
SEVCHK(status,"Unable to start the CA client");
COMMENTS
If the application only wishes to print the message associated with an error code or test the severity of an error there are MACROS provided for this purpose.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
SEE ALSO
#include <cadef.h>
int ca_change_connection_event ( chid CHID, void (*USERFUNC)(struct connection_handler_args handlerargs) );ARGUMENTS
channel index
address of user subroutine to be run when the connection state changes
DESCRIPTION
This function installs a user supplied handler routine which will be run whenever an IO channel connects or disconnects.
COMMENTS
See the ca_search() manual page for a description of the preferred mechanism for accessing this functionality.
The structure "connection_handler_args" is defined in the file ''cadef.h''. Installing a null exception handler will cause the default handler to be reinstalled.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
SEE ALSO
"ca_search()" on page 14
#include <cadef.h>
int ca_add_exception_event( void (*USERFUNC)(struct exception_handler_args HANDLERARGS), void *USERARG );ARGUMENTS
address of user subroutine to be run when exceptions occur
pointer sized object passed to user function above
DESCRIPTION
Synchronous channel access status is returned as status from each channel access function (subroutine). However sometimes client initiated errors occur in the server asynchronously to the client thread. These errors are normally handled by printing them at the client's standard out. The routine documented here allows the application to replace the default asynchronous exception handler with a application specified function and argument. This allows the application to take corrective action to an exception when required.
COMMENTS
The structure"exception_handler_args" is defined in the file ''cadef.h''. Note that the contents of some arguments are invalid in the context of some error messages. For instance, a failed get will supply the address in the client task where the returned value was requested to be written. For other failed operations the value of the ADDR argument should not be used.
Installing a null exception handler will cause the default handler to be reinstalled.
More information needs to be provided about which arguments are valid with each exception. More information needs to be provided correlating exceptions with the routines which cause them.
/*
* Default Exception Handler
*/
LOCAL void ca_default_exception_handler(
struct exception_handler_args args)
{
char *pName;
if(args.chid){
pName = ca_name(args.chid);
}
else{
pName = "?";
}
/*
* LOCK around use of sprintf buffer
*/
LOCK;
sprintf(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, sprintf_buf);
UNLOCK;
}
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
#include <stdarg.h>
#include <cadef.h> int ca_replace_printf_handler( char *pFormat; va_list args; );ARGUMENTS
This is the address of user supplied subroutine to be run when CA prints formatted text.
A variable argument list (see ANSI C 'stdargs.h') similar in format to the argument expected by ANSI C 'vfprintf()'.
DESCRIPTION
This entry point is provided for applications that are particular about how CA error messages are handled. By default CA error messages are sent to 'stderr'.
EXAMPLES
#include <cadef.h>
status = ca_replace_printf_handler (my_printf);
SEVCHK (status, "failed to install my printf handler");
/*
* my_printf()
*/
int my_printf(char *pformat, va_list args)
{
int status;
status = vfprintf(
stderr,
pformat,
args);
return status;
}
COMMENTS RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
#include <cadef.h>
int ca_replace_access_rights_event(
chid CHAN,
void (*PFUNC)(struct access_rights_handler_args ARGS)
);
ARGUMENTS
address of user subroutine to be run when exceptions occur
address of user supplied call back function
DESCRIPTION
Replace the existing access rights state change asynchronous call back handler.
COMMENTS
The call back is called whenever CA connects to a process variable immediately before CA calls the applications connection handler. The call back is called whenever CA disconnects from a process variable immediately after the disconnect call back is called. The call back is always called once immediately after installation if the process variable is already connected. The call back is called when ever the access rights state of connected channel changes.
The structure"access_rights_handler_args" is defined in the file ''cadef.h''. A nill function pointer is initially installed and can be used to disable an existing handler installation.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
SEE ALSO
"macros" on page 28
"ca_modify_user_name()" on page 31
"ca_modify_host_name()" on page 31
#include <cadef.h> chtype ca_field_type(CHID) unsigned ca_element_count(CHID) char * ca_name(CHID) void * ca_puser(CHID) enum channel_state ca_state(CHID) char * ca_message(STATUS) char * ca_host_name(CHID) int ca_read_access(CHID) int ca_write_access(CHID) #include <db_access.h> unsigned dbr_size_n(TYPE,COUNT) unsigned dbr_size[TYPE] unsigned dbr_value_size[TYPE]ARGUMENTS
channel index
status returned from a channel access function.
DESCRIPTION
The MACRO ca_field_type() returns the native type for the specified IO channel. This type will be one from the set of DBF_XXXX in db_access.h. The MACRO ca_element_count() returns the native array element count for the specified IO channel. The MACRO ca_name() returns the name provided as an argument to ca_search when the supplied channel id was created. The MACRO ca_puser() returns or sets a pointer sized region available with each channel for use at the users discretion. The MACRO ca_state() returns an enumerated value indicating the current state of the specified IO channel. See cadef.h for a description of each of the potential channel states. The MACRO ca_message() returns a message character string corresponding to a status code provided by channel access. The MACRO ca_host_name() returns a pointer to a character string which contains the name of the host to which a channel is currently connected. The macro ca_read_access() returns TRUE if the client currently has read access to the specified channel and FALSE otherwise. The macro ca_write_access() returns TRUE if the client currently has write access to the specified channel and FALSE otherwise.
The MACRO dbr_size_n(TYPE, COUNT) returns the size in bytes for a DBR_XXXX with n elements. The Array dbr_size[TYPE] returns the size in bytes for a DBR_XXXX. The Array dbr_value_size[TYPE] returns the size in bytes for the value of a DBR_XXXX.
EXAMPLES
struct users_data mydata;
struct users_data *pmydata;
enum channel_state mystate;
type = ca_field_type(waveform_chid);
nelements = ca_element_count(waveform_chid);
status = ca_add_event(...)
printf("the operation completed with status: %s\n",ca_message(status));
ca_puser(chid) = (void *) &mydata;
pmydata = (struct users_data *) ca_puser(chid)
if(pmydata->notdone)try_again();
mystate = ca_state(chid);
printf("The current connection is %s\n", ca_host_name(chid));
if(ca_write_access(chid) && ca_read_access(chid)){
}
COMMENTS
SEE ALSO
cadef.h, caerr.h, db_access.h
#include <cadef.h> void ca_test_event( struct event_handler_args HANDLERARGS }ARGUMENTS
Arguments passed to all channel access event handlers.
DESCRIPTION
A canned event handler for debugging purposes. ca_test_event() prints information about the event and then returns.
EXAMPLES
void ca_test_event();
status = ca_add_event(type, chid, ca_test_event, NULL, NULL);
SEVCHK(status, " .... ");
COMMENTS
SEE ALSO
ca_add_event()
#include <cadef.h> int ca_add_fd_registration( void (USERFUNC*)(void *USERARG, int FD, int OPENED), void *USERARG )ARGUMENTS
Pointer to a user supplied C function returning null with the above arguments.
User supplied pointer sized variable passed to the above function.
A file descriptor.
Boolean argument is true if the file descriptor was opened and false if the file descriptor was closed.
DESCRIPTION
For use with the services provided by a file descriptor manager (IO multiplexor) such as ""fdmgr.c". A file descriptor manager is often needed when two file descriptor IO intensive libraries such as the EPICS channel access client library and the X window system client library must coexist in the same UNIX process.
This function allows an application code to be notified whenever the CA client library places a new file descriptor into service and whenever the CA client library removes a file descriptor from service.
Specifying USERFUNC=NULL disables file descriptor registration (this is the default).
EXAMPLES
int s;
static struct myStruct aStruct;
void fdReg(pStruct, fd, opened)
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);
COMMENTS
When using this function it is advisable to call it only once prior to calling any other CA function.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
SEE ALSO
#include <cadef.h> int ca_modify_user_name(char *PUSERNAME);ARGUMENTS
Pointer to a user supplied user name string.
DESCRIPTION
Replace the default user name communicated to the CA server for this client.
EXAMPLES
int status;
status = ca_modify_user_name("Flintstone");
SEVCHK(status,NULL);
COMMENTS
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_STRTOBIG - Unusually large string supplied" on page 38
"ECA_ALLOCMEM - Failed, unable to allocate memory" on page 38
SEE ALSO
"ca_replace_access_rights_event()" on page 27
"macros" on page 28
#include <cadef.h> int ca_modify_host_name(char *PHOSTNAME);ARGUMENTS
Pointer to a user supplied host name string.
DESCRIPTION
Replace the default host name communicated to the CA server for this client.
EXAMPLES
int status;
status = ca_modify_host_name("Bedrock");
SEVCHK(status,NULL);
COMMENTS
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_STRTOBIG - Unusually large string supplied" on page 38
"ECA_ALLOCMEM - Unable to allocate memory" on page 38
SEE ALSO
"ca_replace_access_rights_event()" on page 27
"macros" on page 28
#include <cadef.h> int ca_sg_create( CA_SYNC_GID *PGID );ARGUMENTS
Pointer to a user supplied CA_SYNC_GID.
DESCRIPTION
Create a synchronous group and return an identifier for it. A synchronous group can be used to guarantee that a set of channel access requests have completed. Once a synchronous group has been created then channel access get and put requests may be issued within it using ca_sg_get() and ca_sg_put() respectively. The routines ca_sg_block() and ca_sg_test() can be used to block for and test for completion respectively. The routine ca_sg_reset() is used to discard knowledge of old requests which have timed out and in all likelihood will never be satisfied.
EXAMPLES
CA_SYNC_GID gid;
status = ca_sg_create(&gid);
SEVCHK(status, "Sync group create failed");
COMMENTS
Any number of asynchronous groups can have application requested operations outstanding within them at any given time.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_ALLOCMEM - Failed, unable to allocate memory" on page 38
SEE ALSO
"ca_sg_delete()" on page 32
"ca_sg_block()" on page 33
"ca_sg_test()" on page 34
"ca_sg_reset()" on page 34
"ca_sg_put()" on page 35
"ca_sg_get()" on page 36
#include <cadef.h> int ca_sg_delete( CA_SYNC_GID GID );ARGUMENTS
Identifier of the synchronous group to be deleted.
DESCRIPTION
Deletes a synchronous group.
EXAMPLES
CA_SYNC_GID gid;
status = ca_sg_delete(gid);
SEVCHK(status, "Sync group delete failed");
COMMENTS
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADSYNCGRP - Invalid synchronous group" on page 39
SEE ALSO
"ca_sg_create()" on page 32
#include <cadef.h> int ca_sg_block ( CA_SYNC_GID GID, double timeout )ARGUMENTS
Identifier of the synchronous group.
DESCRIPTION
Flushes the send buffer and then waits until outstanding requests complete or the specified time out expires. At this time outstanding requests include calls to ca_sg_array_get() and calls to ca_sg_array_put(). If ECA_TIMEOUT is returned then failure must be assumed for all outstanding queries. Operations can be reissued followed by another ca_sg_block(). This routine will only block on outstanding queries issued after the last call to ca_sg_block(), ca_sg_reset(), or ca_sg_create() whichever occurs later in time. If no queries are outstanding then ca_sg_block() will return immediately without processing any additional outstanding channel access labor.
EXAMPLES
CA_SYNC_GID gid;
status = ca_sg_block(gid);
SEVCHK(status, "Sync group block failed");
COMMENTS
Any 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 handle channel access background activity while it is waiting.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_TIMEOUT - The operation timed out" on page 38
"ECA_EVDISALLOW - Function inappropriate for use within an event handler" on page 39
"ECA_BADSYNCGRP - Invalid synchronous group" on page 39
SEE ALSO
"ca_sg_test()" on page 34
"ca_sg_reset()" on page 34
#include <cadef.h> int ca_sg_test ( CA_SYNC_GID GID )ARGUMENTS
Identifier of the synchronous group.
DESCRIPTION
Test to see if all requests made within a synchronous group have completed.
EXAMPLES
CA_SYNC_GID gid;
status = ca_sg_test(gid);
COMMENTS
RETURNS
"ECA_IODONE - IO operations completed" on page 39
"ECA_IOINPROGRESS - Some IO operations still in progress" on page 39
SEE ALSO
#include <cadef.h> int ca_sg_reset( CA_SYNC_GID GID )ARGUMENTS
Identifier of the synchronous group.
DESCRIPTION
Reset the number of outstanding requests within the specified synchronous group to zero so that ca_sg_test() will return ECA_IODONE and ca_sg_block() will not block unless additional subsequent requests are made.
EXAMPLES
CA_SYNC_GID gid;
status = ca_sg_reset(gid);
COMMENTS
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADSYNCGRP - Invalid synchronous group" on page 39
SEE ALSO
#include <cadef.h> int ca_sg_array_put( CA_SYNC_GID GID, chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE )ARGUMENTS
Identifier of the synchronous group.
type of supplied value- conversion will occur if it does not match native type. Specify one from the set of DBR_XXXX in db_access.h
element count to be written to the specified channel (matches the array pointed to by PVALUE)
channel index
A pointer to an application supplied buffer containing the value or array of values
DESCRIPTION
Write a value (or array of values) to a channel while updating the outstanding request count of a synchronous group.
COMMENTS
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 allowing several operations to be efficiently sent in one network frame.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADSYNCGRP - Invalid synchronous group" on page 39
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_BADCOUNT - Requested count larger than native element count" on page 38
"ECA_STRTOBIG - Unusually large string supplied" on page 38
"ECA_PUTFAIL - A local database put failed" on page 38
SEE ALSO
ca_flush_io()
#include <cadef.h> int ca_sg_array_get( CA_SYNC_GID GID, chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE )ARGUMENTS
Identifier of the synchronous group.
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
Element count to be read from the specified channel. Must match the array pointed to by PVALUE)
channel index
Pointer to application supplied buffer that is to contain the value or area of values to be returned
DESCRIPTION
Read a value from a channel while updating the outstanding request count of a synchronous group.
COMMENTS
The process variable values written into your program's variables by a channel access synchronous request should not be referenced by your program until ECA_NORMAL has been received from ca_sg_block() or until ca_sg_test() returns ECA_IODONE.
All remote operation requests such as the above are accumulated (buffered) and not forwarded to the 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 in one network frame.
If a connection is lost and then resumed outstanding gets are not reissued.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_BADSYNCGRP - Invalid synchronous group" on page 39
"ECA_BADCHID - Corrupted CHID" on page 38
"ECA_BADCOUNT - Requested count larger than native element count" on page 38
"ECA_BADTYPE - Invalid DBR_XXXX type" on page 38
"ECA_GETFAIL - A local database get failed" on page 38
SEE ALSO
"ca_pend_io()" on page 22
"ca_flush_io()" on page 24
"ca_get_callback()" on page 19
int ca_import(TASKID); int TASKID;ARGUMENTS
vxWorks task identifier.
DESCRIPTION
Each vxWorks task which calls channel access receives a channel access context. This context is shared by the calling task and several additional satellite tasks created to handle channel access events. Normally channel identifiers created in a context cant be used from other vxWorks tasks. Within an IOC a group of cooperating channel access client tasks all use the same channel access client context. Using the same context implies that all of the cooperating tasks use the same TCP/IP connections and other internal resources to access remote servers. It is sometimes necessary to create an additional task that will run in parallel with an existing channel access context. If so you must call ca_import() from this new task with the task identifier of one of the tasks in the desired channel access context prior to calling any channel access functions.
COMMENTS
Available on vxWorks only.
EXAMPLES
void new_task();
sp(new_task, taskIdSelf());
.
.
void new_task(parent)
int parent;
{
SEVCHK(ca_import(parent), NULL);
.
.
.
}
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_NOCACTX - Import from a task without a CA context failed" on page 39
SEE ALSO
"ca_import_cancel()" on page 38
int ca_import_cancel(TASKID); int TASKID;ARGUMENTS
vxWorks task identifier.
DESCRIPTION
Reverses the effect of ca_import().
EXAMPLES
SEVCHK(ca_import_cancel(taskIdCurrent), NULL);
COMMENTS
Available on vxWorks only.
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
"ECA_NOCACTX - Import from a task without a CA context failed" on page 39
SEE ALSO
"ca_import()" on page 37
int ca_channel_status(TASKID) int TASKID;ARGUMENTS
vxWorks task identifier.
DESCRIPTION
Available on vxWorks only. Prints status for each channel in use by the specified vxWorks task. Can be run from the vxWorks shell.
COMMENTS
RETURNS
"ECA_NORMAL - Normal successful completion" on page 38
ECA_NORMAL - Normal successful completion ECA_ALLOCMEM - Failed, unable to allocate memory ECA_BADTYPE - Invalid DBR_XXXX type ECA_STRTOBIG - Unusually large string supplied ECA_ALLOCMEM - Unable to allocate memory ECA_BADCHID - Corrupted CHID ECA_BADCOUNT - Requested count larger than native element count ECA_PUTFAIL - A local database put failed ECA_GETFAIL - A local database get failed ECA_ADDFAIL - A local database event add failed ECA_TIMEOUT - The operation timed out ECA_EVDISALLOW - Function inappropriate for use within an event handler ECA_IODONE - IO operations completed ECA_IOINPROGRESS - Some IO operations still in progress ECA_BADSYNCGRP - Invalid synchronous group ECA_NOCACTX - Import from a task without a CA context failed ECA_NORDACCESS - Read access denied ECA_NOWTACCESS - Write access denied