Channel Access Client Reference

CHAPTER 2 Notes

If the server for a channel is located in a different node than the client then the ca_XXX() operations that communicate with the server return status indicating the validity of the request. In other words success returned from the client library routine indicates that it checked your request, it appeared to be valid, and it forwarded it to the server. 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. An example of this type of error is attempting to write the string "off" to a floating point field (writing the string "3.3" would be accepted). When the server detects a failure an exception handler is executed in the client. The default exception handler just prints a message on the console ("ca_add_exception_event()" on page 25). Not waiting for status to return from the server after each remote operation results in significant performance gains. 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 IOC database. So in this instance 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.

Some CA client initiated operations asynchronously execute an application supplied call back in the client when the requested operation completes. The functions ca_put_callback(), ca_get_callback(), and ca_add_event() all request notification of asynchronous completion via this mechanism. The structure "event_handler_args" is passed to the application supplied callback. In this structure the field "dbr" is a void pointer to any data that might be returned. The field "status" will be set to one of the CA error codes in caerr.h and will indicate the status of the operation performed in the IOC. If the status field isn't set to ECA_NORMAL or data isn't normally returned from the operation (i.e. put call back) then you should expect that the field "dbr" will be set to NULL. The fields "usr", "chid", "type", and "count" are set to the values specified when the operation was initiated by the application.

struct event_handler_args{

        void    *usr;   /* User argument supplied when event added      */
        chid    chid;   /* Channel id                                   */
        long    type;   /* the type of the value returned (long aligned)*/
        long    count;  /* the element count of the item returned       */
        void    *dbr;   /* Pointer to the value returned                */
        int     status; /* CA Status of the op from server - CA V4.1    */
};

Any process variable values written into your program's variables by ca_get() should not be referenced by your program until ECA_NORMAL has been received from ca_pend_io().

All arguments of type"chtype" expect a constant from the set of DBR_XXXX. These constants, defined in db_access.h, enumerate which of the standard data types you wish to transfer. Some routines have arguments requiring that you 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. Use the structures and size returning MACROS/arrays provided in db_access.h for this purpose. See also the MACROS manual page in this document.

For routines which require an argument specifying the number of elements no more than the channel's native count may be requested. The channels native count is available from ca_element_count(). If less elements than the channels native count are requested the requested values will be fetched from the beginning of the channels array of values. Currently channel access 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.

Channel connections across the network are inherently transient. A handler routine may be installed to be run whenever an IO channel connects or disconnects. Channels are always initially disconnected. An argument provided to the user supplied handler distinguishes between connect and disconnect events. A different handler routine may be installed for each channel. After a connection handler is established on a particular channel by the user CA will neither block for or print the results of this channel's search, or value fetch associated with the search, while in ca_pend_io(). Your connection handler (if any) will be run from inside ca_search() if your code - the CA client - and the channel searched for are both hosted by the same IOC (if it is a local channel).

CA attempts to provide an identical environment on several OS. One of the few exceptions to this involves the way that event handlers are run under each OS. Under vxWorks only, event handlers are allowed to preempt the main (initiating) channel access thread. This was allowed because preemption might be exploited for useful purposes in some cases. However, once an event handler begins it is always allowed to run to completion prior to running another event handler. That is events never preempt events. Event preemption is currently not supported under VMS because of reentrancy problems with the MULTINET socket library. When running under VMS or UNIX event handlers will not be executed unless inside of a CA client library routine such as ca_pend_event().

For proper operation CA must periodically be allowed 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 it must call ca_pend_event() at least every 15 seconds. See "ca_add_fd_registration()" on page 30 for more information about applications that perform better with multiplexed file descriptor IO.

For portability reasons CA functions do not return status following UNIX convention. The error number and the severity of the status are embedded in the CA function return. Applications shouldn't test the success of a CA function call by checking to see if the returned value is zero as is the UNIX convention. Below are several methods to test CA function returns. See "ca_signal()" on page 24 for more information on this topic.

status = ca_XXXX();

SEVCHK( status, "It failed and this is why ... ");

if(status & CA_M_SUCCESS){
	printf("The requested operation didn't complete successfully\n");
}

if(status != ECA_NORMAL){
	printf("Something off normal occurred while performing the operation");
}