From 49d0571e4ae803153c6a825081e285ab491411aa Mon Sep 17 00:00:00 2001 From: Jeff Hill Date: Fri, 22 Nov 1996 19:16:00 +0000 Subject: [PATCH] reorganized for improved readability --- src/ca/cadef.h | 971 ++++++++++++++++++++++++-------------------- src/include/cadef.h | 971 ++++++++++++++++++++++++-------------------- 2 files changed, 1048 insertions(+), 894 deletions(-) diff --git a/src/ca/cadef.h b/src/ca/cadef.h index 8a5c4c4a4..e89387c0f 100644 --- a/src/ca/cadef.h +++ b/src/ca/cadef.h @@ -74,16 +74,20 @@ #ifndef INCLcadefh #define INCLcadefh +/* + * done in two ifdef steps so that we will remain compatible with + * traditional C + */ #ifdef __cplusplus extern "C" { -#define CAC_FUNC_PROTO +#define CAC_ANSI_FUNC_PROTO +#endif +#ifdef __STDC__ +#define CAC_ANSI_FUNC_PROTO #endif #include -#ifdef __STDC__ -#define CAC_FUNC_PROTO -#endif #ifndef HDRVERSIONID # define HDRVERSIONID(NAME,VERS) @@ -91,10 +95,18 @@ extern "C" { HDRVERSIONID(cadefh, "@(#) $Id$") -/* auto include of all stuff that cadef.h uses */ -#if defined(CAC_FUNC_PROTO) && !defined(CA_DONT_INCLUDE_STDARGH) +/* + * auto include of all stuff that cadef.h uses + */ + +/* + * use two ifdef's for trad C compatibility + */ +#ifndef CA_DONT_INCLUDE_STDARGH +#ifdef CAC_ANSI_FUNC_PROTO #include #endif +#endif #ifndef INCLdb_accessh #include @@ -162,11 +174,11 @@ struct connection_handler_args{ long op; /* External codes for CA op */ }; -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO typedef void caCh(struct connection_handler_args args); -#else /*CAC_FUNC_PROTO*/ +#else /*CAC_ANSI_FUNC_PROTO*/ typedef void caCh(); -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ /* Format for the arguments to user access rights handlers */ struct access_rights_handler_args{ @@ -175,11 +187,11 @@ struct access_rights_handler_args{ caar ar; /* New access rights state */ }; -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO typedef void caArh(struct access_rights_handler_args args); -#else /*CAC_FUNC_PROTO*/ +#else /*CAC_ANSI_FUNC_PROTO*/ typedef void caArh(); -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ struct channel_in_use{ ELLNODE node; /* list ptrs */ @@ -234,11 +246,11 @@ struct event_handler_args{ struct pending_event{ ELLNODE node; /* list ptrs */ -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO void (*usr_func)(struct event_handler_args args); -#else /*CAC_FUNC_PROTO*/ +#else /*CAC_ANSI_FUNC_PROTO*/ void (*usr_func)(); -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ READONLY void *usr_arg; chid chan; chtype type; /* requested type for local CA */ @@ -256,9 +268,9 @@ struct pending_event{ void epicsShareAPI ca_test_event ( -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO struct event_handler_args -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ ); /* Format for the arguments to user exception handlers */ @@ -293,29 +305,21 @@ struct exception_handler_args{ #define CA_OP_CONN_UP 6 #define CA_OP_CONN_DOWN 7 +#ifdef CAC_ANSI_FUNC_PROTO + /************************************************************************/ /* Perform Library Initialization */ /* */ /* Must be called once before calling any of the other routines */ /************************************************************************/ -int epicsShareAPI ca_task_initialize - ( -#ifdef CAC_FUNC_PROTO - void -#endif /*CAC_FUNC_PROTO*/ - ); +int epicsShareAPI ca_task_initialize (void); /************************************************************************/ /* Remove CA facility from your task */ /* */ /* Normally called automatically at task exit */ /************************************************************************/ -int epicsShareAPI ca_task_exit - ( -#ifdef CAC_FUNC_PROTO - void -#endif /*CAC_FUNC_PROTO*/ - ); +int epicsShareAPI ca_task_exit (void); /************************************************************************ * anachronistic entry points * @@ -334,274 +338,297 @@ ca_build_and_connect(NAME, XXXXX, ZZZZZZ, CHIDPTR, YYYYY, 0, 0) /************************************************************************/ /* - * preferred search request API + * ca_search() + * + * a preferred search request API + * + * pChanName R channel name string + * pChanID RW channel id written here */ -#define ca_search(NAME,CHIDPTR)\ -ca_search_and_connect(NAME, CHIDPTR, 0, 0) -/* ca_search - ( - Name IO Value - ---- -- ----- -const char *, NAME R NULL term ASCII channel name string -chid * CHIDPTR RW channel index written here - ); -*/ +#define ca_search(pChanName, pChanID)\ +ca_search_and_connect(pChanName, pChanID, 0, 0) /* - * preferred search request API + * ca_search_and_connect() + * + * a preferred search request API + * + * pChanName R channel name string + * pChanID RW channel id written here + * pFunc R address of connection call-back function + * pArg R placed in the channel's puser field + * (fetched later by ca_puser(CHID)) + * (passed as void * arg to (*pFunc)() above) */ int epicsShareAPI ca_search_and_connect - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -const char *, - /* NAME R NULL term ASCII channel name string */ -chid *, /* CHIDPTR RW channel index written here */ -void (*)(struct connection_handler_args), - /* PFUNC R the address of user's connection handler*/ -const void * - /* PUSER R placed in the channel's puser field */ -#endif /*CAC_FUNC_PROTO*/ -); - -/************************************************************************ - * anachronistic entry point * - * **** Fetching a value while searching nolonger supported**** * - ************************************************************************/ -int epicsShareAPI ca_build_and_connect - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -char *, /* NAME R NULL term ASCII channel name string */ -chtype, /* GET_TYPE R external channel type to get */ -unsigned/* (no get if invalid type) */ -long, /* GET_COUNT R array count to get */ -chid *, /* CHIDPTR RW channel index written here */ -void *, /* PVALUE W A pointer to a user supplied buffer */ -void (*)(struct connection_handler_args), - /* PFUNC R the address of user's connection handler*/ -void * /* PUSER R placed in the channel's puser field */ -#endif /*CAC_FUNC_PROTO*/ - ); - -int epicsShareAPI ca_change_connection_event ( -#ifdef CAC_FUNC_PROTO -chid chan, -void (*pfunc)(struct connection_handler_args) -#endif /*CAC_FUNC_PROTO*/ + const char *pChanName, + chid *pChanID, + void (*pFunc)(struct connection_handler_args), + const void *pArg ); - -int epicsShareAPI ca_replace_access_rights_event( -#ifdef CAC_FUNC_PROTO -chid chan, -void (*pfunc)(struct access_rights_handler_args) -#endif /*CAC_FUNC_PROTO*/ + +/* + * anachronistic entry point + * **** Fetching a value while searching nolonger supported **** + * + * pChanName R channel name string + * pChanID RW channel id written here + * pFunc R address of connection call-back function + * pArg R placed in the channel's puser field + * (fetched later by ca_puser(CHID)) + * (passed as void * arg to (*pFunc)() above) + */ +int epicsShareAPI ca_build_and_connect +( + const char *pChanName, + chtype, /* pass TYPENOTCONN */ + unsigned long, /* pass 0 */ + chid *pChanID, + void *, /* pass NULL */ + void (*pFunc)(struct connection_handler_args), + void *pArg ); /* + * ca_change_connection_event() + * + * chan R channel identifier + * pfunc R address of connection call-back function + */ +int epicsShareAPI ca_change_connection_event +( + chid chan, + void (*pfunc)(struct connection_handler_args) +); + +/* + * ca_replace_access_rights_event () + * + * chan R channel identifier + * pfunc R address of access rights call-back function + */ +int epicsShareAPI ca_replace_access_rights_event( + chid chan, + void (*pfunc)(struct access_rights_handler_args) +); + +/* + * ca_add_exception_event () * * replace the default exception handler * + * pfunc R address of exception call-back function + * pArg R copy of this pointer passed to exception + * call-back function */ int epicsShareAPI ca_add_exception_event ( -#ifdef CAC_FUNC_PROTO -void (*pfunc)(struct exception_handler_args), -const void *arg -#endif /*CAC_FUNC_PROTO*/ + void (*pfunc) (struct exception_handler_args), + const void *pArg ); -/************************************************************************/ -/* deallocate resources reserved for a channel */ -/************************************************************************/ +/* + * ca_clear_channel() + * - deallocate resources reserved for a channel + * + * chanId R channel ID + */ int epicsShareAPI ca_clear_channel - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chid /* CHAN, R channel identifier */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + chid chanId +); /************************************************************************/ /* Write a value to a channel */ /************************************************************************/ -#define ca_bput(CHID,PVALUE) ca_array_put(DBR_STRING, 1, CHID, (PVALUE)) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -const char * PVALUE R pointer to a binary value string -*/ + * ca_bput() + * + * WARNING: this copies the new value from a string (dbr_string_t) + * (and not as an integer) + * + * chan R channel identifier + * pValue R new channel value string copied from this location + */ +#define ca_bput(chan, pValue) \ +ca_array_put(DBR_STRING, 1u, chan, (const dbr_string_t *) (pValue)) -#define ca_rput(CHID,PVALUE)\ -ca_array_put(DBR_FLOAT, 1, CHID, (PVALUE)) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -const dbr_float_t * - PVALUE R pointer to a real value -*/ + * ca_rput() + * + * WARNING: this copies the new value from a dbr_float_t + * + * chan R channel identifier + * pValue R new channel value copied from this location + */ +#define ca_rput(chan,pValue) \ +ca_array_put(DBR_FLOAT, 1u, chan, (const dbr_float_t *) pValue) -#define ca_put(CHTYPE, CHID, PVALUE) ca_array_put(CHTYPE, 1, CHID, PVALUE) /* - Name IO Value - ---- -- ----- -chtype, TYPE R channel type -chid, CHID R channel index -const void * PVALUE R pointer to new channel value of type specified - i.e. status = ca_put(DBF_INT,chid,&value) -*/ + * ca_put() + * + * type R data type from db_access.h + * chan R channel identifier + * pValue R new channel value copied from this location + */ +#define ca_put(type, chan, pValue) ca_array_put(type, 1u, chan, pValue) +/* + * ca_array_put() + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue R new channel value copied from this location + */ int epicsShareAPI ca_array_put - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -const void * - /* PVALUE R pointer to new channel value of type */ - /* specified. */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + chtype type, + unsigned long count, + chid chanId, + const void *pValue +); /* + * ca_array_put_callback() + * * This routine functions identically to the original ca put request * with the addition of a callback to the user supplied function * after recod processing completes in the IOC. The arguments * to the user supplied callback function are declared in * the structure event_handler_args and include the pointer - * sized user argument supplied when ca_array_get_callback() is called. + * sized user argument supplied when ca_array_put_callback() is called. + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue R new channel value copied from this location + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc */ int epicsShareAPI ca_array_put_callback - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -const void *, - /* PVALUE R pointer to new channel value of type */ -void (*)(struct event_handler_args), - /* USRFUNC R the address of a user supplied function */ -const void * - /* USRARG R An argument copied to the above function*/ -#endif /*CAC_FUNC_PROTO*/ - ); - - +( + chtype type, + unsigned long count, + chid chanId, + const void *pValue, + void (*pFunc)(struct event_handler_args), + const void *pArg +); /************************************************************************/ /* Read a value from a channel */ -/* */ -/* */ /************************************************************************/ -#define ca_bget(CHID,PVALUE) ca_array_get(DBR_STRING, 1, CHID, PVALUE) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -char * PVALUE W string value pointer -*/ + * ca_bget() + * + * WARNING: this copies the new value into a string (dbr_string_t) + * (and not into an integer) + * + * chan R channel identifier + * pValue W channel value copied to this location + */ +#define ca_bget(chan, pValue) \ +ca_array_get(DBR_STRING, 1u, chan, (dbr_string_t *)(pValue)) -#define ca_rget(CHID,PVALUE) ca_array_get(DBR_FLOAT, 1, CHID, PVALUE) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -dbr_float_t * PVALUE W real value pointer -*/ + * ca_rget() + * + * WARNING: this copies the new value into a 32 bit float (dbr_float_t) + * + * chan R channel identifier + * pValue W channel value copied to this location + */ +#define ca_rget(chan, pValue) \ +ca_array_get(DBR_FLOAT, 1u, chan, (dbr_float_t *)(pValue)) -#define ca_get(CHTYPE, CHID, PVALUE) ca_array_get(CHTYPE, 1, CHID, PVALUE) /* -C Type Name IO Value ------- ----- -- ----- -chtype, TYPE R channel type -chid, CHID R channel index -void * PVALUE W ptr to where channel value written -*/ + * ca_rget() + * + * type R data type from db_access.h + * chan R channel identifier + * pValue W channel value copied to this location + */ +#define ca_get(type, chan, pValue) ca_array_get(type, 1u, chan, pValue) +/* + * ca_array_get() + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue W channel value copied to this location + */ int epicsShareAPI ca_array_get - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void * /* PVALUE W ptr to where channel value written */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + chtype type, + unsigned long count, + chid chanId, + void *pValue +); + /************************************************************************/ /* Read a value from a channel and run a callback when the value */ /* returns */ /* */ /* */ /************************************************************************/ -#define ca_bget_callback(CHID,PFUNC,ARG)\ -ca_array_get_callback(DBR_STRING, 1, CHID, PFUNC, ARG) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -void (*)(struct event_handler_args), - PFUNC R the address of a user supplied function -const void *, ARG R An argument copied to the above function -*/ - -#define ca_rget_callback(CHID,PFUNC,ARG)\ -ca_array_get_callback(DBR_FLOAT, 1, CHID, PFUNC, ARG) + * ca_bget_callback() + * + * WARNING: this returns the new value as a string (dbr_string_t) + * (and not as an integer) + * + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ +#define ca_bget_callback(chan, pFunc, pArg)\ +ca_array_get_callback(DBR_STRING, 1u, chan, pFunc, pArg) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -void (*)(struct event_handler_args), - PFUNC R the address of a user supplied function -const void *, ARG R An argument copied to the above function -*/ + * ca_rget_callback() + * + * WARNING: this returns the new value as a float (dbr_float_t) + * + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ +#define ca_rget_callback(chan, pFunc, pArg)\ +ca_array_get_callback(DBR_FLOAT, 1u, chan, pFunc, pArg) -#define ca_get_callback(CHTYPE, CHID,PFUNC,ARG)\ -ca_array_get_callback(CHTYPE, 1, CHID, PFUNC, ARG) /* -C Type Name IO Value ------- ----- -- ----- -chtype, TYPE R channel type -chid, CHID R channel index -void (*)(struct event_handler_args), - PFUNC R the address of a user supplied function -const void *, ARG R An argument copied to the above function -*/ + * ca_get_callback() + * + * type R data type from db_access.h + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ +#define ca_get_callback(type, chan, pFunc, pArg)\ +ca_array_get_callback(type, 1u, chan, pFunc, pArg) +/* + * ca_array_get_callback() + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ int epicsShareAPI ca_array_get_callback - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void (*)(struct event_handler_args), - /* USRFUNC R the address of a user supplied function */ -const void * - /* USRARG R An argument copied to the above function */ -#endif /*CAC_FUNC_PROTO*/ - ); - - +( + chtype type, + unsigned long count, + chid chanId, + void (*pFunc)(struct event_handler_args), + const void *pArg +); /************************************************************************/ /* Specify a function to be executed whenever significant changes */ @@ -614,34 +641,25 @@ const void * /************************************************************************/ typedef struct event_handler_args evargs; -/* Assumes DELTA info comes from the database or defaults */ -#define ca_add_event(TYPE,CHID,ENTRY,ARG,EVID)\ -ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,0.0,0.0,0.0,EVID) - -/* Name IO Value - ---- -- ----- -chid, CHID R channel index -void (*)(struct event_handler_args), - USRFUNC R the address of a user supplied function -const void *, USRARG R An argument copied to the above function -evid * EVIDPTR W An id to refer to this event by -*/ - +/* + * ca_add_event () + * + * assumes "delta" info comes from the database or defaults + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + * pEventID W event id written at specified address + */ +#define ca_add_event(type,chan,pFunc,pArg,pEventID)\ +ca_add_array_event(type,1u,chan,pFunc,pArg,0.0,0.0,0.0,pEventID) /* Sets both P_DELTA and M_DELTA below to argument DELTA */ #define ca_add_delta_event(TYPE,CHID,ENTRY,ARG,DELTA,EVID)\ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,DELTA,DELTA,0.0,EVID) -/* Name IO Value - ---- -- ----- -chid, CHID R channel index -void (*)(struct event_handler_args), - USRFUNC R the address of a user supplied function -const void *, USRARG R An argument copied to the above function -ca_real, DELTA R Generate events after +-delta excursions -evid * EVIDPTR W An id to refer to this event by -*/ - #define ca_add_general_event(TYPE,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID) @@ -649,44 +667,48 @@ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID) #define ca_add_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\ ca_add_masked_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID, DBE_VALUE | DBE_ALARM) - - +/* + * ca_add_masked_array_event () + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + * p_delta R not currently used (set to 0.0) + * n_delta R not currently used (set to 0.0) + * timeout R not currently used (set to 0.0) + * pEventID W event id written at specified address + * mask R event mask - one of {DBE_VALUE, DBE_ALARM, DBE_LOG} + */ int epicsShareAPI ca_add_masked_array_event - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R requested external channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void (*)(struct event_handler_args), - /* USRFUNC R the address of a user supplied function */ -const void *, - /* USRARG R An argument copied to the above function*/ -ca_real,/* P_DELTA R Generate events after +delta excursions */ -ca_real,/* N_DELTA R Generate events after -delta excursions */ -ca_real,/* TIMEOUT R Generate events after timeout sec */ -evid *, /* EVIDPTR W An id to refer to this event by */ -long /* MASK R event trigger type */ -#endif /*CAC_FUNC_PROTO*/ - ); - - +( + chtype type, + unsigned long count, + chid chanId, + void (*pFunc)(struct event_handler_args), + const void *pArg, + ca_real p_delta, + ca_real n_delta, + ca_real timeout, + evid *pEventID, + long mask +); /************************************************************************/ /* Remove a function from a list of those specified to run */ /* whenever significant changes occur to a channel */ /* */ /************************************************************************/ +/* + * ca_clear_event() + * + * eventID R event id + */ int epicsShareAPI ca_clear_event - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -evid /* EVID R Event id returned by add event */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + evid eventID +); /************************************************************************/ @@ -740,67 +762,68 @@ evid /* EVID R Event id returned by add event */ #define ca_pend_event(TIMEOUT) ca_pend((TIMEOUT), 0/*FALSE*/) #define ca_pend_io(TIMEOUT) ca_pend((TIMEOUT), 1/*TRUE*/) +/* + * ca_pend() + * + * timeOut R delay in seconds + * early R T: return early if all get requests (or search + * requests with null connection handler pointer + * have completed) + * F: wait for the entire delay to expire + */ int epicsShareAPI ca_pend - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -ca_real,/* TIMEOUT R timeout in seconds */ -int /* EARLY R return early if IO completes */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + ca_real timeOut, + int early +); /* - * returns TRUE when queries are outstanding + * ca_test_io() + * + * returns TRUE when get requests (or search requests with null + * connection handler pointer) are outstanding */ -int epicsShareAPI ca_test_io - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -void -#endif /*CAC_FUNC_PROTO*/ - ); +int epicsShareAPI ca_test_io (void); /************************************************************************/ /* Send out all outstanding messages in the send queue */ /************************************************************************/ -int epicsShareAPI ca_flush_io - ( -#ifdef CAC_FUNC_PROTO - void -#endif /*CAC_FUNC_PROTO*/ - ); - - -void epicsShareAPI ca_signal - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -long, /* CODE R status returned from channel access function */ -const char * - /* MSG R null term string printed on error */ -#endif /*CAC_FUNC_PROTO*/ - ); - -void epicsShareAPI ca_signal_with_file_and_lineno - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -long, /* CODE R status returned from channel access function */ -const char *, - /* MSG R null term string printed on error */ -const char *, - /* FILE R pointer to null terminated file name string */ -int /* LINENO R line number */ -#endif /*CAC_FUNC_PROTO*/ - ); +/* + * ca_flush_io() + */ +int epicsShareAPI ca_flush_io (void); /* - * Provided for efficient test and display of channel access errors + * ca_signal() + * + * errorCode R status returned from channel access function + * pCtxStr R context string included with error print out + */ +void epicsShareAPI ca_signal +( + long errorCode, + const char *pCtxStr +); + +/* + * ca_signal_with_file_and_lineno() + * errorCode R status returned from channel access function + * pCtxStr R context string included with error print out + * pFileStr R file name string included with error print out + * lineNo R line number included with error print out + * + */ +void epicsShareAPI ca_signal_with_file_and_lineno +( + long errorCode, + const char *pCtxStr, + const char *pFileStr, + int lineNo +); + +/* + * provides efficient test and display of channel access errors */ #define SEVCHK(CA_ERROR_CODE, MESSAGE_STRING) \ { \ @@ -813,14 +836,12 @@ int /* LINENO R line number */ __LINE__); \ } -const char * epicsShareAPI ca_host_name_function - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chid /* CHID R Channel ID */ -#endif /*CAC_FUNC_PROTO*/ - ); +/* + * ca_host_name_function() + * + * channel R channel identifier + */ +const char * epicsShareAPI ca_host_name_function ( chid channel); /* * CA_ADD_FD_REGISTRATION @@ -833,41 +854,46 @@ chid /* CHID R Channel ID */ * if (!opened) then fd was deleted * */ -#ifdef CAC_FUNC_PROTO typedef void CAFDHANDLER(void *parg, int fd, int opened); -#else /*CAC_FUNC_PROTO*/ -typedef void CAFDHANDLER(); -#endif /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_add_fd_registration( -#ifdef CAC_FUNC_PROTO -CAFDHANDLER *pHandler, -const void *pArg -#endif /*CAC_FUNC_PROTO*/ +/* + * ca_add_fd_registration() + * + * pHandler R pointer to function which is to be called + * when an fd is created or deleted + * pArg R argument passsed to above function + */ +int epicsShareAPI ca_add_fd_registration +( + CAFDHANDLER *pHandler, + const void *pArg ); +/* + * ca_channel_status() + * + * tid R task id + */ #ifdef vxWorks -int epicsShareAPI ca_channel_status( -#ifdef CAC_FUNC_PROTO -int tid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_channel_status( int tid); #endif +/* + * ca_import () + * + * tid R task id + */ #ifdef vxWorks -#ifdef CAC_FUNC_PROTO int ca_import(int tid); -#else /*CAC_FUNC_PROTO*/ -int ca_import(); -#endif /*CAC_FUNC_PROTO*/ #endif /* vxWorks */ +/* + * ca_import_cancel () + * + * tid R task id + */ #ifdef vxWorks -#ifdef CAC_FUNC_PROTO int ca_import_cancel(int tid); -#else /*CAC_FUNC_PROTO*/ -int ca_import_cancel(); -#endif /*CAC_FUNC_PROTO*/ #endif /* vxWorks */ /* @@ -882,152 +908,203 @@ int ca_import_cancel(); typedef unsigned CA_SYNC_GID; /* + * ca_sg_create() + * * create a sync group + * + * pgid W pointer to sync group id that will be written */ -int epicsShareAPI ca_sg_create( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID *pgid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_create( CA_SYNC_GID * pgid); /* + * ca_sg_delete() + * * delete a sync group + * + * gid R sync group id */ -int epicsShareAPI ca_sg_delete( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_delete(const CA_SYNC_GID gid); /* + * ca_sg_block() + * * block for IO performed within a sync group to complete + * + * gid R sync group id + * timeout R wait for this duration prior to timing out + * and returning ECA_TIMEOUT */ -int epicsShareAPI ca_sg_block( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid, -ca_real timeout -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_block(const CA_SYNC_GID gid, ca_real timeout); /* + * ca_sg_test() + * * test for sync group IO operations in progress + * + * gid R sync group id + * + * returns one of ECA_BADSYNCGRP, ECA_IOINPROGRESS, ECA_IODONE */ -int epicsShareAPI ca_sg_test( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_test(const CA_SYNC_GID gid); /* * ca_sg_reset + * + * gid R sync group id */ -int epicsShareAPI ca_sg_reset( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid -#endif /*CAC_FUNC_PROTO*/ +int epicsShareAPI ca_sg_reset(const CA_SYNC_GID gid); + +/* + * ca_sg_array_get() + * + * initiate a get within a sync group + * (essentially a ca_array_get() with a sync group specified) + * + * gid R sync group id + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue W channel value copied to this location + */ +int epicsShareAPI ca_sg_array_get +( + const CA_SYNC_GID gid, + chtype type, /* TYPE R channel type */ + unsigned long count, + chid chan, + void *pValue ); /* - * initiate a get within a sync group - * (essentially a ca_array_get() with a sync group specified) - */ -int epicsShareAPI ca_sg_array_get - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -CA_SYNC_GID,/* GID R synch group id */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void * /* PVALUE W ptr to where channel value written */ -#endif /*CAC_FUNC_PROTO*/ - ); - -/* + * ca_sg_array_put() + * * initiate a put within a sync group * (essentially a ca_array_put() with a sync group specified) + * + * gid R sync group id + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue R new channel value copied from this location */ int epicsShareAPI ca_sg_array_put - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -CA_SYNC_GID,/* GID R synch group id */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -const void * - /* PVALUE R pointer to new channel value of type */ - /* specified. */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + const CA_SYNC_GID gid, + chtype type, + unsigned long count, + chid chan, + const void *pValue +); /* + * ca_sg_stat() + * * print status of a sync group + * + * gid R sync group id */ -#ifdef CAC_FUNC_PROTO -int epicsShareAPI ca_sg_stat(CA_SYNC_GID gid); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_sg_stat(); -#endif /*CAC_FUNC_PROTO*/ +int epicsShareAPI ca_sg_stat(const CA_SYNC_GID gid); /* - * CA_MODIFY_USER_NAME() + * ca_modify_user_name() * * Modify or override the default * client user name. + * + * pUserName R new user name string copied from this location */ -#ifdef CAC_FUNC_PROTO int epicsShareAPI ca_modify_user_name(const char *pUserName); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_modify_user_name(); -#endif /*CAC_FUNC_PROTO*/ /* * CA_MODIFY_HOST_NAME() * * Modify or override the default * client host name. + * + * pHostName R new host name string copied from this location */ -#ifdef CAC_FUNC_PROTO int epicsShareAPI ca_modify_host_name(const char *pHostName); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_modify_host_name(); -#endif /*CAC_FUNC_PROTO*/ /* + * ca_v42_ok() + * * Put call back is available if the CA server is on version is 4.2 * or higher. * - * (return true or false) + * chan R channel identifier + * + * (returns true or false) */ -#ifdef CAC_FUNC_PROTO int epicsShareAPI ca_v42_ok(chid chan); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_v42_ok(); -#endif /*CAC_FUNC_PROTO*/ /* - * function that returns the CA version string + * ca_version() + * + * returns the CA version string */ -READONLY char * epicsShareAPI ca_version(); +const char * epicsShareAPI ca_version(void); /* * ca_replace_printf_handler () * * for apps that want to change where ca formatted * text output goes + * + * use two ifdef's for trad C compatibility + * + * ca_printf_func R pointer to new function called when + * CA prints an error message */ -#if defined(CAC_FUNC_PROTO) && !defined(CA_DONT_INCLUDE_STDARGH) +#ifndef CA_DONT_INCLUDE_STDARGH int epicsShareAPI ca_replace_printf_handler ( -int (*ca_printf_func)(const char *pformat, va_list args) + int (*ca_printf_func)(const char *pformat, va_list args) ); -#else /*CAC_FUNC_PROTO*/ +#endif /*CA_DONT_INCLUDE_STDARGH*/ + +#else /* CAC_ANSI_FUNC_PROTO */ + +int epicsShareAPI ca_task_initialize (); +int epicsShareAPI ca_task_exit (); +int epicsShareAPI ca_search_and_connect (); +int epicsShareAPI ca_build_and_connect (); +int epicsShareAPI ca_change_connection_event (); +int epicsShareAPI ca_replace_access_rights_event (); +int epicsShareAPI ca_add_exception_event (); +int epicsShareAPI ca_clear_channel (); +int epicsShareAPI ca_array_put (); +int epicsShareAPI ca_array_put_callback (); +int epicsShareAPI ca_array_get (); +int epicsShareAPI ca_array_get_callback (); +int epicsShareAPI ca_add_masked_array_event (); +int epicsShareAPI ca_clear_event (); +int epicsShareAPI ca_pend (); +int epicsShareAPI ca_test_io (); +int epicsShareAPI ca_flush_io (); +void epicsShareAPI ca_signal (); +void epicsShareAPI ca_signal_with_file_and_lineno (); +char * epicsShareAPI ca_host_name_function (); +typedef void CAFDHANDLER(); +int epicsShareAPI ca_add_fd_registration(); int epicsShareAPI ca_replace_printf_handler (); -#endif /*CAC_FUNC_PROTO*/ +int epicsShareAPI ca_sg_create(); +int epicsShareAPI ca_sg_delete(); +int epicsShareAPI ca_sg_block(); +int epicsShareAPI ca_sg_test(); +int epicsShareAPI ca_sg_reset(); +int epicsShareAPI ca_sg_array_get(); +int epicsShareAPI ca_sg_array_put(); +int epicsShareAPI ca_sg_stat(); +int epicsShareAPI ca_modify_user_name(); +int epicsShareAPI ca_modify_host_name(); +int epicsShareAPI ca_v42_ok(); +char * epicsShareAPI ca_version(); +#ifdef vxWorks + int epicsShareAPI ca_channel_status() + int ca_import(); + int ca_import_cancel(); +#endif + +#endif /* CAC_ANSI_FUNC_PROTO */ #ifdef __cplusplus } diff --git a/src/include/cadef.h b/src/include/cadef.h index 8a5c4c4a4..e89387c0f 100644 --- a/src/include/cadef.h +++ b/src/include/cadef.h @@ -74,16 +74,20 @@ #ifndef INCLcadefh #define INCLcadefh +/* + * done in two ifdef steps so that we will remain compatible with + * traditional C + */ #ifdef __cplusplus extern "C" { -#define CAC_FUNC_PROTO +#define CAC_ANSI_FUNC_PROTO +#endif +#ifdef __STDC__ +#define CAC_ANSI_FUNC_PROTO #endif #include -#ifdef __STDC__ -#define CAC_FUNC_PROTO -#endif #ifndef HDRVERSIONID # define HDRVERSIONID(NAME,VERS) @@ -91,10 +95,18 @@ extern "C" { HDRVERSIONID(cadefh, "@(#) $Id$") -/* auto include of all stuff that cadef.h uses */ -#if defined(CAC_FUNC_PROTO) && !defined(CA_DONT_INCLUDE_STDARGH) +/* + * auto include of all stuff that cadef.h uses + */ + +/* + * use two ifdef's for trad C compatibility + */ +#ifndef CA_DONT_INCLUDE_STDARGH +#ifdef CAC_ANSI_FUNC_PROTO #include #endif +#endif #ifndef INCLdb_accessh #include @@ -162,11 +174,11 @@ struct connection_handler_args{ long op; /* External codes for CA op */ }; -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO typedef void caCh(struct connection_handler_args args); -#else /*CAC_FUNC_PROTO*/ +#else /*CAC_ANSI_FUNC_PROTO*/ typedef void caCh(); -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ /* Format for the arguments to user access rights handlers */ struct access_rights_handler_args{ @@ -175,11 +187,11 @@ struct access_rights_handler_args{ caar ar; /* New access rights state */ }; -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO typedef void caArh(struct access_rights_handler_args args); -#else /*CAC_FUNC_PROTO*/ +#else /*CAC_ANSI_FUNC_PROTO*/ typedef void caArh(); -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ struct channel_in_use{ ELLNODE node; /* list ptrs */ @@ -234,11 +246,11 @@ struct event_handler_args{ struct pending_event{ ELLNODE node; /* list ptrs */ -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO void (*usr_func)(struct event_handler_args args); -#else /*CAC_FUNC_PROTO*/ +#else /*CAC_ANSI_FUNC_PROTO*/ void (*usr_func)(); -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ READONLY void *usr_arg; chid chan; chtype type; /* requested type for local CA */ @@ -256,9 +268,9 @@ struct pending_event{ void epicsShareAPI ca_test_event ( -#ifdef CAC_FUNC_PROTO +#ifdef CAC_ANSI_FUNC_PROTO struct event_handler_args -#endif /*CAC_FUNC_PROTO*/ +#endif /*CAC_ANSI_FUNC_PROTO*/ ); /* Format for the arguments to user exception handlers */ @@ -293,29 +305,21 @@ struct exception_handler_args{ #define CA_OP_CONN_UP 6 #define CA_OP_CONN_DOWN 7 +#ifdef CAC_ANSI_FUNC_PROTO + /************************************************************************/ /* Perform Library Initialization */ /* */ /* Must be called once before calling any of the other routines */ /************************************************************************/ -int epicsShareAPI ca_task_initialize - ( -#ifdef CAC_FUNC_PROTO - void -#endif /*CAC_FUNC_PROTO*/ - ); +int epicsShareAPI ca_task_initialize (void); /************************************************************************/ /* Remove CA facility from your task */ /* */ /* Normally called automatically at task exit */ /************************************************************************/ -int epicsShareAPI ca_task_exit - ( -#ifdef CAC_FUNC_PROTO - void -#endif /*CAC_FUNC_PROTO*/ - ); +int epicsShareAPI ca_task_exit (void); /************************************************************************ * anachronistic entry points * @@ -334,274 +338,297 @@ ca_build_and_connect(NAME, XXXXX, ZZZZZZ, CHIDPTR, YYYYY, 0, 0) /************************************************************************/ /* - * preferred search request API + * ca_search() + * + * a preferred search request API + * + * pChanName R channel name string + * pChanID RW channel id written here */ -#define ca_search(NAME,CHIDPTR)\ -ca_search_and_connect(NAME, CHIDPTR, 0, 0) -/* ca_search - ( - Name IO Value - ---- -- ----- -const char *, NAME R NULL term ASCII channel name string -chid * CHIDPTR RW channel index written here - ); -*/ +#define ca_search(pChanName, pChanID)\ +ca_search_and_connect(pChanName, pChanID, 0, 0) /* - * preferred search request API + * ca_search_and_connect() + * + * a preferred search request API + * + * pChanName R channel name string + * pChanID RW channel id written here + * pFunc R address of connection call-back function + * pArg R placed in the channel's puser field + * (fetched later by ca_puser(CHID)) + * (passed as void * arg to (*pFunc)() above) */ int epicsShareAPI ca_search_and_connect - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -const char *, - /* NAME R NULL term ASCII channel name string */ -chid *, /* CHIDPTR RW channel index written here */ -void (*)(struct connection_handler_args), - /* PFUNC R the address of user's connection handler*/ -const void * - /* PUSER R placed in the channel's puser field */ -#endif /*CAC_FUNC_PROTO*/ -); - -/************************************************************************ - * anachronistic entry point * - * **** Fetching a value while searching nolonger supported**** * - ************************************************************************/ -int epicsShareAPI ca_build_and_connect - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -char *, /* NAME R NULL term ASCII channel name string */ -chtype, /* GET_TYPE R external channel type to get */ -unsigned/* (no get if invalid type) */ -long, /* GET_COUNT R array count to get */ -chid *, /* CHIDPTR RW channel index written here */ -void *, /* PVALUE W A pointer to a user supplied buffer */ -void (*)(struct connection_handler_args), - /* PFUNC R the address of user's connection handler*/ -void * /* PUSER R placed in the channel's puser field */ -#endif /*CAC_FUNC_PROTO*/ - ); - -int epicsShareAPI ca_change_connection_event ( -#ifdef CAC_FUNC_PROTO -chid chan, -void (*pfunc)(struct connection_handler_args) -#endif /*CAC_FUNC_PROTO*/ + const char *pChanName, + chid *pChanID, + void (*pFunc)(struct connection_handler_args), + const void *pArg ); - -int epicsShareAPI ca_replace_access_rights_event( -#ifdef CAC_FUNC_PROTO -chid chan, -void (*pfunc)(struct access_rights_handler_args) -#endif /*CAC_FUNC_PROTO*/ + +/* + * anachronistic entry point + * **** Fetching a value while searching nolonger supported **** + * + * pChanName R channel name string + * pChanID RW channel id written here + * pFunc R address of connection call-back function + * pArg R placed in the channel's puser field + * (fetched later by ca_puser(CHID)) + * (passed as void * arg to (*pFunc)() above) + */ +int epicsShareAPI ca_build_and_connect +( + const char *pChanName, + chtype, /* pass TYPENOTCONN */ + unsigned long, /* pass 0 */ + chid *pChanID, + void *, /* pass NULL */ + void (*pFunc)(struct connection_handler_args), + void *pArg ); /* + * ca_change_connection_event() + * + * chan R channel identifier + * pfunc R address of connection call-back function + */ +int epicsShareAPI ca_change_connection_event +( + chid chan, + void (*pfunc)(struct connection_handler_args) +); + +/* + * ca_replace_access_rights_event () + * + * chan R channel identifier + * pfunc R address of access rights call-back function + */ +int epicsShareAPI ca_replace_access_rights_event( + chid chan, + void (*pfunc)(struct access_rights_handler_args) +); + +/* + * ca_add_exception_event () * * replace the default exception handler * + * pfunc R address of exception call-back function + * pArg R copy of this pointer passed to exception + * call-back function */ int epicsShareAPI ca_add_exception_event ( -#ifdef CAC_FUNC_PROTO -void (*pfunc)(struct exception_handler_args), -const void *arg -#endif /*CAC_FUNC_PROTO*/ + void (*pfunc) (struct exception_handler_args), + const void *pArg ); -/************************************************************************/ -/* deallocate resources reserved for a channel */ -/************************************************************************/ +/* + * ca_clear_channel() + * - deallocate resources reserved for a channel + * + * chanId R channel ID + */ int epicsShareAPI ca_clear_channel - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chid /* CHAN, R channel identifier */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + chid chanId +); /************************************************************************/ /* Write a value to a channel */ /************************************************************************/ -#define ca_bput(CHID,PVALUE) ca_array_put(DBR_STRING, 1, CHID, (PVALUE)) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -const char * PVALUE R pointer to a binary value string -*/ + * ca_bput() + * + * WARNING: this copies the new value from a string (dbr_string_t) + * (and not as an integer) + * + * chan R channel identifier + * pValue R new channel value string copied from this location + */ +#define ca_bput(chan, pValue) \ +ca_array_put(DBR_STRING, 1u, chan, (const dbr_string_t *) (pValue)) -#define ca_rput(CHID,PVALUE)\ -ca_array_put(DBR_FLOAT, 1, CHID, (PVALUE)) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -const dbr_float_t * - PVALUE R pointer to a real value -*/ + * ca_rput() + * + * WARNING: this copies the new value from a dbr_float_t + * + * chan R channel identifier + * pValue R new channel value copied from this location + */ +#define ca_rput(chan,pValue) \ +ca_array_put(DBR_FLOAT, 1u, chan, (const dbr_float_t *) pValue) -#define ca_put(CHTYPE, CHID, PVALUE) ca_array_put(CHTYPE, 1, CHID, PVALUE) /* - Name IO Value - ---- -- ----- -chtype, TYPE R channel type -chid, CHID R channel index -const void * PVALUE R pointer to new channel value of type specified - i.e. status = ca_put(DBF_INT,chid,&value) -*/ + * ca_put() + * + * type R data type from db_access.h + * chan R channel identifier + * pValue R new channel value copied from this location + */ +#define ca_put(type, chan, pValue) ca_array_put(type, 1u, chan, pValue) +/* + * ca_array_put() + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue R new channel value copied from this location + */ int epicsShareAPI ca_array_put - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -const void * - /* PVALUE R pointer to new channel value of type */ - /* specified. */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + chtype type, + unsigned long count, + chid chanId, + const void *pValue +); /* + * ca_array_put_callback() + * * This routine functions identically to the original ca put request * with the addition of a callback to the user supplied function * after recod processing completes in the IOC. The arguments * to the user supplied callback function are declared in * the structure event_handler_args and include the pointer - * sized user argument supplied when ca_array_get_callback() is called. + * sized user argument supplied when ca_array_put_callback() is called. + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue R new channel value copied from this location + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc */ int epicsShareAPI ca_array_put_callback - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -const void *, - /* PVALUE R pointer to new channel value of type */ -void (*)(struct event_handler_args), - /* USRFUNC R the address of a user supplied function */ -const void * - /* USRARG R An argument copied to the above function*/ -#endif /*CAC_FUNC_PROTO*/ - ); - - +( + chtype type, + unsigned long count, + chid chanId, + const void *pValue, + void (*pFunc)(struct event_handler_args), + const void *pArg +); /************************************************************************/ /* Read a value from a channel */ -/* */ -/* */ /************************************************************************/ -#define ca_bget(CHID,PVALUE) ca_array_get(DBR_STRING, 1, CHID, PVALUE) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -char * PVALUE W string value pointer -*/ + * ca_bget() + * + * WARNING: this copies the new value into a string (dbr_string_t) + * (and not into an integer) + * + * chan R channel identifier + * pValue W channel value copied to this location + */ +#define ca_bget(chan, pValue) \ +ca_array_get(DBR_STRING, 1u, chan, (dbr_string_t *)(pValue)) -#define ca_rget(CHID,PVALUE) ca_array_get(DBR_FLOAT, 1, CHID, PVALUE) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -dbr_float_t * PVALUE W real value pointer -*/ + * ca_rget() + * + * WARNING: this copies the new value into a 32 bit float (dbr_float_t) + * + * chan R channel identifier + * pValue W channel value copied to this location + */ +#define ca_rget(chan, pValue) \ +ca_array_get(DBR_FLOAT, 1u, chan, (dbr_float_t *)(pValue)) -#define ca_get(CHTYPE, CHID, PVALUE) ca_array_get(CHTYPE, 1, CHID, PVALUE) /* -C Type Name IO Value ------- ----- -- ----- -chtype, TYPE R channel type -chid, CHID R channel index -void * PVALUE W ptr to where channel value written -*/ + * ca_rget() + * + * type R data type from db_access.h + * chan R channel identifier + * pValue W channel value copied to this location + */ +#define ca_get(type, chan, pValue) ca_array_get(type, 1u, chan, pValue) +/* + * ca_array_get() + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue W channel value copied to this location + */ int epicsShareAPI ca_array_get - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void * /* PVALUE W ptr to where channel value written */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + chtype type, + unsigned long count, + chid chanId, + void *pValue +); + /************************************************************************/ /* Read a value from a channel and run a callback when the value */ /* returns */ /* */ /* */ /************************************************************************/ -#define ca_bget_callback(CHID,PFUNC,ARG)\ -ca_array_get_callback(DBR_STRING, 1, CHID, PFUNC, ARG) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -void (*)(struct event_handler_args), - PFUNC R the address of a user supplied function -const void *, ARG R An argument copied to the above function -*/ - -#define ca_rget_callback(CHID,PFUNC,ARG)\ -ca_array_get_callback(DBR_FLOAT, 1, CHID, PFUNC, ARG) + * ca_bget_callback() + * + * WARNING: this returns the new value as a string (dbr_string_t) + * (and not as an integer) + * + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ +#define ca_bget_callback(chan, pFunc, pArg)\ +ca_array_get_callback(DBR_STRING, 1u, chan, pFunc, pArg) /* -C Type Name IO Value ------- ----- -- ----- -chid CHID R channel id -void (*)(struct event_handler_args), - PFUNC R the address of a user supplied function -const void *, ARG R An argument copied to the above function -*/ + * ca_rget_callback() + * + * WARNING: this returns the new value as a float (dbr_float_t) + * + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ +#define ca_rget_callback(chan, pFunc, pArg)\ +ca_array_get_callback(DBR_FLOAT, 1u, chan, pFunc, pArg) -#define ca_get_callback(CHTYPE, CHID,PFUNC,ARG)\ -ca_array_get_callback(CHTYPE, 1, CHID, PFUNC, ARG) /* -C Type Name IO Value ------- ----- -- ----- -chtype, TYPE R channel type -chid, CHID R channel index -void (*)(struct event_handler_args), - PFUNC R the address of a user supplied function -const void *, ARG R An argument copied to the above function -*/ + * ca_get_callback() + * + * type R data type from db_access.h + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ +#define ca_get_callback(type, chan, pFunc, pArg)\ +ca_array_get_callback(type, 1u, chan, pFunc, pArg) +/* + * ca_array_get_callback() + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + */ int epicsShareAPI ca_array_get_callback - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void (*)(struct event_handler_args), - /* USRFUNC R the address of a user supplied function */ -const void * - /* USRARG R An argument copied to the above function */ -#endif /*CAC_FUNC_PROTO*/ - ); - - +( + chtype type, + unsigned long count, + chid chanId, + void (*pFunc)(struct event_handler_args), + const void *pArg +); /************************************************************************/ /* Specify a function to be executed whenever significant changes */ @@ -614,34 +641,25 @@ const void * /************************************************************************/ typedef struct event_handler_args evargs; -/* Assumes DELTA info comes from the database or defaults */ -#define ca_add_event(TYPE,CHID,ENTRY,ARG,EVID)\ -ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,0.0,0.0,0.0,EVID) - -/* Name IO Value - ---- -- ----- -chid, CHID R channel index -void (*)(struct event_handler_args), - USRFUNC R the address of a user supplied function -const void *, USRARG R An argument copied to the above function -evid * EVIDPTR W An id to refer to this event by -*/ - +/* + * ca_add_event () + * + * assumes "delta" info comes from the database or defaults + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + * pEventID W event id written at specified address + */ +#define ca_add_event(type,chan,pFunc,pArg,pEventID)\ +ca_add_array_event(type,1u,chan,pFunc,pArg,0.0,0.0,0.0,pEventID) /* Sets both P_DELTA and M_DELTA below to argument DELTA */ #define ca_add_delta_event(TYPE,CHID,ENTRY,ARG,DELTA,EVID)\ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,DELTA,DELTA,0.0,EVID) -/* Name IO Value - ---- -- ----- -chid, CHID R channel index -void (*)(struct event_handler_args), - USRFUNC R the address of a user supplied function -const void *, USRARG R An argument copied to the above function -ca_real, DELTA R Generate events after +-delta excursions -evid * EVIDPTR W An id to refer to this event by -*/ - #define ca_add_general_event(TYPE,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID) @@ -649,44 +667,48 @@ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID) #define ca_add_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\ ca_add_masked_array_event(TYPE,COUNT,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID, DBE_VALUE | DBE_ALARM) - - +/* + * ca_add_masked_array_event () + * + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pFunc R pointer to call-back function + * pArg R copy of this pointer passed to pFunc + * p_delta R not currently used (set to 0.0) + * n_delta R not currently used (set to 0.0) + * timeout R not currently used (set to 0.0) + * pEventID W event id written at specified address + * mask R event mask - one of {DBE_VALUE, DBE_ALARM, DBE_LOG} + */ int epicsShareAPI ca_add_masked_array_event - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chtype, /* TYPE R requested external channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void (*)(struct event_handler_args), - /* USRFUNC R the address of a user supplied function */ -const void *, - /* USRARG R An argument copied to the above function*/ -ca_real,/* P_DELTA R Generate events after +delta excursions */ -ca_real,/* N_DELTA R Generate events after -delta excursions */ -ca_real,/* TIMEOUT R Generate events after timeout sec */ -evid *, /* EVIDPTR W An id to refer to this event by */ -long /* MASK R event trigger type */ -#endif /*CAC_FUNC_PROTO*/ - ); - - +( + chtype type, + unsigned long count, + chid chanId, + void (*pFunc)(struct event_handler_args), + const void *pArg, + ca_real p_delta, + ca_real n_delta, + ca_real timeout, + evid *pEventID, + long mask +); /************************************************************************/ /* Remove a function from a list of those specified to run */ /* whenever significant changes occur to a channel */ /* */ /************************************************************************/ +/* + * ca_clear_event() + * + * eventID R event id + */ int epicsShareAPI ca_clear_event - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -evid /* EVID R Event id returned by add event */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + evid eventID +); /************************************************************************/ @@ -740,67 +762,68 @@ evid /* EVID R Event id returned by add event */ #define ca_pend_event(TIMEOUT) ca_pend((TIMEOUT), 0/*FALSE*/) #define ca_pend_io(TIMEOUT) ca_pend((TIMEOUT), 1/*TRUE*/) +/* + * ca_pend() + * + * timeOut R delay in seconds + * early R T: return early if all get requests (or search + * requests with null connection handler pointer + * have completed) + * F: wait for the entire delay to expire + */ int epicsShareAPI ca_pend - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -ca_real,/* TIMEOUT R timeout in seconds */ -int /* EARLY R return early if IO completes */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + ca_real timeOut, + int early +); /* - * returns TRUE when queries are outstanding + * ca_test_io() + * + * returns TRUE when get requests (or search requests with null + * connection handler pointer) are outstanding */ -int epicsShareAPI ca_test_io - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -void -#endif /*CAC_FUNC_PROTO*/ - ); +int epicsShareAPI ca_test_io (void); /************************************************************************/ /* Send out all outstanding messages in the send queue */ /************************************************************************/ -int epicsShareAPI ca_flush_io - ( -#ifdef CAC_FUNC_PROTO - void -#endif /*CAC_FUNC_PROTO*/ - ); - - -void epicsShareAPI ca_signal - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -long, /* CODE R status returned from channel access function */ -const char * - /* MSG R null term string printed on error */ -#endif /*CAC_FUNC_PROTO*/ - ); - -void epicsShareAPI ca_signal_with_file_and_lineno - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -long, /* CODE R status returned from channel access function */ -const char *, - /* MSG R null term string printed on error */ -const char *, - /* FILE R pointer to null terminated file name string */ -int /* LINENO R line number */ -#endif /*CAC_FUNC_PROTO*/ - ); +/* + * ca_flush_io() + */ +int epicsShareAPI ca_flush_io (void); /* - * Provided for efficient test and display of channel access errors + * ca_signal() + * + * errorCode R status returned from channel access function + * pCtxStr R context string included with error print out + */ +void epicsShareAPI ca_signal +( + long errorCode, + const char *pCtxStr +); + +/* + * ca_signal_with_file_and_lineno() + * errorCode R status returned from channel access function + * pCtxStr R context string included with error print out + * pFileStr R file name string included with error print out + * lineNo R line number included with error print out + * + */ +void epicsShareAPI ca_signal_with_file_and_lineno +( + long errorCode, + const char *pCtxStr, + const char *pFileStr, + int lineNo +); + +/* + * provides efficient test and display of channel access errors */ #define SEVCHK(CA_ERROR_CODE, MESSAGE_STRING) \ { \ @@ -813,14 +836,12 @@ int /* LINENO R line number */ __LINE__); \ } -const char * epicsShareAPI ca_host_name_function - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -chid /* CHID R Channel ID */ -#endif /*CAC_FUNC_PROTO*/ - ); +/* + * ca_host_name_function() + * + * channel R channel identifier + */ +const char * epicsShareAPI ca_host_name_function ( chid channel); /* * CA_ADD_FD_REGISTRATION @@ -833,41 +854,46 @@ chid /* CHID R Channel ID */ * if (!opened) then fd was deleted * */ -#ifdef CAC_FUNC_PROTO typedef void CAFDHANDLER(void *parg, int fd, int opened); -#else /*CAC_FUNC_PROTO*/ -typedef void CAFDHANDLER(); -#endif /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_add_fd_registration( -#ifdef CAC_FUNC_PROTO -CAFDHANDLER *pHandler, -const void *pArg -#endif /*CAC_FUNC_PROTO*/ +/* + * ca_add_fd_registration() + * + * pHandler R pointer to function which is to be called + * when an fd is created or deleted + * pArg R argument passsed to above function + */ +int epicsShareAPI ca_add_fd_registration +( + CAFDHANDLER *pHandler, + const void *pArg ); +/* + * ca_channel_status() + * + * tid R task id + */ #ifdef vxWorks -int epicsShareAPI ca_channel_status( -#ifdef CAC_FUNC_PROTO -int tid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_channel_status( int tid); #endif +/* + * ca_import () + * + * tid R task id + */ #ifdef vxWorks -#ifdef CAC_FUNC_PROTO int ca_import(int tid); -#else /*CAC_FUNC_PROTO*/ -int ca_import(); -#endif /*CAC_FUNC_PROTO*/ #endif /* vxWorks */ +/* + * ca_import_cancel () + * + * tid R task id + */ #ifdef vxWorks -#ifdef CAC_FUNC_PROTO int ca_import_cancel(int tid); -#else /*CAC_FUNC_PROTO*/ -int ca_import_cancel(); -#endif /*CAC_FUNC_PROTO*/ #endif /* vxWorks */ /* @@ -882,152 +908,203 @@ int ca_import_cancel(); typedef unsigned CA_SYNC_GID; /* + * ca_sg_create() + * * create a sync group + * + * pgid W pointer to sync group id that will be written */ -int epicsShareAPI ca_sg_create( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID *pgid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_create( CA_SYNC_GID * pgid); /* + * ca_sg_delete() + * * delete a sync group + * + * gid R sync group id */ -int epicsShareAPI ca_sg_delete( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_delete(const CA_SYNC_GID gid); /* + * ca_sg_block() + * * block for IO performed within a sync group to complete + * + * gid R sync group id + * timeout R wait for this duration prior to timing out + * and returning ECA_TIMEOUT */ -int epicsShareAPI ca_sg_block( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid, -ca_real timeout -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_block(const CA_SYNC_GID gid, ca_real timeout); /* + * ca_sg_test() + * * test for sync group IO operations in progress + * + * gid R sync group id + * + * returns one of ECA_BADSYNCGRP, ECA_IOINPROGRESS, ECA_IODONE */ -int epicsShareAPI ca_sg_test( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid -#endif /*CAC_FUNC_PROTO*/ -); +int epicsShareAPI ca_sg_test(const CA_SYNC_GID gid); /* * ca_sg_reset + * + * gid R sync group id */ -int epicsShareAPI ca_sg_reset( -#ifdef CAC_FUNC_PROTO -CA_SYNC_GID gid -#endif /*CAC_FUNC_PROTO*/ +int epicsShareAPI ca_sg_reset(const CA_SYNC_GID gid); + +/* + * ca_sg_array_get() + * + * initiate a get within a sync group + * (essentially a ca_array_get() with a sync group specified) + * + * gid R sync group id + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue W channel value copied to this location + */ +int epicsShareAPI ca_sg_array_get +( + const CA_SYNC_GID gid, + chtype type, /* TYPE R channel type */ + unsigned long count, + chid chan, + void *pValue ); /* - * initiate a get within a sync group - * (essentially a ca_array_get() with a sync group specified) - */ -int epicsShareAPI ca_sg_array_get - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -CA_SYNC_GID,/* GID R synch group id */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -void * /* PVALUE W ptr to where channel value written */ -#endif /*CAC_FUNC_PROTO*/ - ); - -/* + * ca_sg_array_put() + * * initiate a put within a sync group * (essentially a ca_array_put() with a sync group specified) + * + * gid R sync group id + * type R data type from db_access.h + * count R array element count + * chan R channel identifier + * pValue R new channel value copied from this location */ int epicsShareAPI ca_sg_array_put - ( -#ifdef CAC_FUNC_PROTO - /* Name IO Value */ - /* ---- -- ----- */ -CA_SYNC_GID,/* GID R synch group id */ -chtype, /* TYPE R channel type */ -unsigned long, - /* COUNT R array element count */ -chid, /* CHID R channel index */ -const void * - /* PVALUE R pointer to new channel value of type */ - /* specified. */ -#endif /*CAC_FUNC_PROTO*/ - ); +( + const CA_SYNC_GID gid, + chtype type, + unsigned long count, + chid chan, + const void *pValue +); /* + * ca_sg_stat() + * * print status of a sync group + * + * gid R sync group id */ -#ifdef CAC_FUNC_PROTO -int epicsShareAPI ca_sg_stat(CA_SYNC_GID gid); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_sg_stat(); -#endif /*CAC_FUNC_PROTO*/ +int epicsShareAPI ca_sg_stat(const CA_SYNC_GID gid); /* - * CA_MODIFY_USER_NAME() + * ca_modify_user_name() * * Modify or override the default * client user name. + * + * pUserName R new user name string copied from this location */ -#ifdef CAC_FUNC_PROTO int epicsShareAPI ca_modify_user_name(const char *pUserName); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_modify_user_name(); -#endif /*CAC_FUNC_PROTO*/ /* * CA_MODIFY_HOST_NAME() * * Modify or override the default * client host name. + * + * pHostName R new host name string copied from this location */ -#ifdef CAC_FUNC_PROTO int epicsShareAPI ca_modify_host_name(const char *pHostName); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_modify_host_name(); -#endif /*CAC_FUNC_PROTO*/ /* + * ca_v42_ok() + * * Put call back is available if the CA server is on version is 4.2 * or higher. * - * (return true or false) + * chan R channel identifier + * + * (returns true or false) */ -#ifdef CAC_FUNC_PROTO int epicsShareAPI ca_v42_ok(chid chan); -#else /*CAC_FUNC_PROTO*/ -int epicsShareAPI ca_v42_ok(); -#endif /*CAC_FUNC_PROTO*/ /* - * function that returns the CA version string + * ca_version() + * + * returns the CA version string */ -READONLY char * epicsShareAPI ca_version(); +const char * epicsShareAPI ca_version(void); /* * ca_replace_printf_handler () * * for apps that want to change where ca formatted * text output goes + * + * use two ifdef's for trad C compatibility + * + * ca_printf_func R pointer to new function called when + * CA prints an error message */ -#if defined(CAC_FUNC_PROTO) && !defined(CA_DONT_INCLUDE_STDARGH) +#ifndef CA_DONT_INCLUDE_STDARGH int epicsShareAPI ca_replace_printf_handler ( -int (*ca_printf_func)(const char *pformat, va_list args) + int (*ca_printf_func)(const char *pformat, va_list args) ); -#else /*CAC_FUNC_PROTO*/ +#endif /*CA_DONT_INCLUDE_STDARGH*/ + +#else /* CAC_ANSI_FUNC_PROTO */ + +int epicsShareAPI ca_task_initialize (); +int epicsShareAPI ca_task_exit (); +int epicsShareAPI ca_search_and_connect (); +int epicsShareAPI ca_build_and_connect (); +int epicsShareAPI ca_change_connection_event (); +int epicsShareAPI ca_replace_access_rights_event (); +int epicsShareAPI ca_add_exception_event (); +int epicsShareAPI ca_clear_channel (); +int epicsShareAPI ca_array_put (); +int epicsShareAPI ca_array_put_callback (); +int epicsShareAPI ca_array_get (); +int epicsShareAPI ca_array_get_callback (); +int epicsShareAPI ca_add_masked_array_event (); +int epicsShareAPI ca_clear_event (); +int epicsShareAPI ca_pend (); +int epicsShareAPI ca_test_io (); +int epicsShareAPI ca_flush_io (); +void epicsShareAPI ca_signal (); +void epicsShareAPI ca_signal_with_file_and_lineno (); +char * epicsShareAPI ca_host_name_function (); +typedef void CAFDHANDLER(); +int epicsShareAPI ca_add_fd_registration(); int epicsShareAPI ca_replace_printf_handler (); -#endif /*CAC_FUNC_PROTO*/ +int epicsShareAPI ca_sg_create(); +int epicsShareAPI ca_sg_delete(); +int epicsShareAPI ca_sg_block(); +int epicsShareAPI ca_sg_test(); +int epicsShareAPI ca_sg_reset(); +int epicsShareAPI ca_sg_array_get(); +int epicsShareAPI ca_sg_array_put(); +int epicsShareAPI ca_sg_stat(); +int epicsShareAPI ca_modify_user_name(); +int epicsShareAPI ca_modify_host_name(); +int epicsShareAPI ca_v42_ok(); +char * epicsShareAPI ca_version(); +#ifdef vxWorks + int epicsShareAPI ca_channel_status() + int ca_import(); + int ca_import_cancel(); +#endif + +#endif /* CAC_ANSI_FUNC_PROTO */ #ifdef __cplusplus }