From 85c287774659cb32b1007cce018bc338aea7908f Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 17 Aug 2010 18:06:19 -0500 Subject: [PATCH] Document the dynamic-array changes. --- documentation/RELEASE_NOTES.html | 25 +++++++++++++++++++++++++ src/ca/CAref.html | 23 ++++++++++++----------- 2 files changed, 37 insertions(+), 11 deletions(-) diff --git a/documentation/RELEASE_NOTES.html b/documentation/RELEASE_NOTES.html index 3b0058a87..af7c595a4 100644 --- a/documentation/RELEASE_NOTES.html +++ b/documentation/RELEASE_NOTES.html @@ -12,6 +12,31 @@

Changes between 3.14.11 and 3.14.12

+

Dynamic arrays over CA

+ +

Dymanic array sizing was developed by Michael Abbott at the 2010 EPICS +Codeathon. It permits a CA client to fetch only the currently valid elements of +an array by specifying a COUNT of zero to either of the ca_array_get_callback() +or ca_create_subscription() routines. It has never before been legal to pass a +COUNT of zero to the ca_array_get_callback() routine, but this development does +introduce a subtle change to the published API of the ca_create_subscription() +routine.

+ +

In previous releases a COUNT of zero for a subscription meant use the +ca_element_count() for the channel, but from this release it can return fewer +elements (never more), at the behest of the server. The number of elements can +vary with subsequent array update events, so a client that uses this technique +must use the count field of the event_handler_args in its callback function each +time it is called to obtain the correct element count from the server. Note that +the ca_element_count() value for a channel is only updated at connection time, +and supplies the maximum number of elements that the server array variable can +hold.

+ +

Dynamic arrays are currently only supported by the CA client library and IOC +server RSRV; the portable CAS does not understand them in this release. Newer +clients using this feature with an older server will revert to the previous +behavior.

+

CA over TCP connections

Merged the CA-over-TCP changes developed by Ralph and Jeff at the 2008 EPICS diff --git a/src/ca/CAref.html b/src/ca/CAref.html index 13e6cc61e..4f156b25a 100644 --- a/src/ca/CAref.html +++ b/src/ca/CAref.html @@ -2297,11 +2297,11 @@ ca_put_callback, ca_get_callback, and ca_add_event all request notification of asynchronous completion via this mechanism. The event_handler_args structure is passed by value to the application supplied callback. In this structure the dbr field is a void pointer to any -data that might be returned. The status field will be +data that might be returned. The status field 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 dbr field will be set to a nill pointer +should expect that the dbr field will be set to a nill pointer (zero). The fields usr, chid, and type are set to the values specified when the request was made by the application. The "dbr" pointer, and any data that it points to, are valid only when @@ -2352,8 +2352,8 @@ library functions that request them.

For routines that require an argument specifying the number of array elements, no more than the process variable's maximum native element count may be requested. The process variable's maximum native element count is available -from ca_element_count() when the channel is connected. If less elements than -the process variable's native element count are requested the requested values +from ca_element_count() when the channel is connected. If fewer elements than +the process variable's native element count are requested, the requested values will be fetched beginning at element zero. By default CA limits the number of elements in an array to be no more than approximately 16k divided by the size of one element in the array. Starting with EPICS R3.14 the maximum array size @@ -2381,12 +2381,12 @@ href="#ca_create_channel">ca_create_channel. The ca_pend_io approach is best suited to simple command line programs with short runtime duration, and the connection callback method is best suited to toolkit components with long runtime duration. Use of -ca_state is appropriate only in programs +ca_state is appropriate only in programs that prefer to poll for connection state changes instead of opting for asynchronous notification. The ca_pend_io function blocks only for channels created specifying a nill connection handler callback function. The user's connection state change function will be run immediately from within -ca_create_channel if the CA +ca_create_channel if the CA client and CA server are both hosted within the same address space (within the same process).

@@ -2709,9 +2709,9 @@ time.

The following structure is passed by value to the user's connection connection callback function. The op field will be set by the CA client library to CA_OP_CONN_UP when the - channel connects, and to CA_OP_CONN_DOWN when the channel + channel connects, and to CA_OP_CONN_DOWN when the channel disconnects. See ca_puser if the - PUSER argument is required in your callback + PUSER argument is required in your callback handler.

struct  ca_connection_handler_args {
     chanId  chid;  /* channel id */
@@ -2973,7 +2973,8 @@ when a CA get request is initiated.

 

   
COUNT

     
Element count to be read from the specified channel. Must match the
-      array pointed to by PVALUE.

+      array pointed to by PVALUE. For ca_array_get_callback a count of zero
+      means use the current element count from the server.
 

 

   
CHID

@@ -3081,7 +3082,7 @@ indicating the current state of the channel.

 

   
COUNT

     
The element count to be read from the specified channel. A count of
-      zero specifies the native elemnt count.

+      zero means use the current element count from the server.
 

 

   
CHID

@@ -3391,7 +3392,7 @@ field should not be used.

     
Address of user callback function to be executed when an exceptions
       occur. Passing a nil value causes the default exception handler to be
       reinstalled. The following structure is passed by value to the user's
-      callback function. Currently, the op field can be one of
+      callback function. Currently, the op field can be one of
       CA_OP_GET, CA_OP_PUT, CA_OP_CREATE_CHANNEL, CA_OP_ADD_EVENT,
       CA_OP_CLEAR_EVENT, or CA_OP_OTHER.
       
struct exception_handler_args {