home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / xbase / library / clipper / cgoodies / extor.doc next >
Encoding:
Text File  |  1988-06-08  |  7.9 KB  |  230 lines

  1. The "Extor System."
  2. Copyright (c) 1988 Nantucket Corp.  All rights reserved.
  3.  
  4.  
  5. Terms:
  6.  
  7. "Clipper" refers to the Summer87 version of Nantucket's Clipper
  8. compiler for dBASE.  None of this information should be assumed to
  9. apply to any other version of Clipper.
  10.  
  11. A "foreign function" is a Clipper-callable function or procedure written
  12. in a language other than Clipper.
  13.  
  14. The "Extend System" is the set of functions, header files, etc. supplied
  15. with Clipper which allow a foreign function to retrieve the values of
  16. parameters passed from a Clipper program.
  17.  
  18. The phrase "by reference" refers to a style of parameter passing in
  19. which a reference to a memory variable is passed instead of the memory
  20. variable's current value.  In Clipper, you achieve this by preceding the
  21. variable name with the  @  character in the function invocation (note
  22. that this is not necessary for arrays, which are always passed by
  23. reference).
  24.  
  25.  
  26.  
  27. Background:
  28.  
  29. The Extend System is a key element in Clipper's open architecture.  It
  30. allows you to write a foreign function which can be used much as if you
  31. had written it in Clipper.  The function can be written in any language
  32. which provides a C-compatible calling mechanism.  Parameters can be
  33. retrieved via a set of C-callable "par" functions, and a return value
  34. can be posted using one of several "ret" functions.
  35.  
  36. One limitation of the Extend System is that your foreign function can
  37. return only a single value to the calling program (by posting it with a
  38. "ret" function) .  If a large volume of data is to be supplied or
  39. processed by a foreign function, you may need to make numerous function
  40. calls in order to tranfer all of the data.  Function calling and
  41. parameter passing involve significant overhead, so the extra calls may
  42. degrade performance.  (Also they're a pain in the neck.)
  43.  
  44. If you write your function in Clipper, on the other hand, you can
  45. directly modify memory variables which were passed by reference.  This
  46. is especially useful with arrays;  a single function call can fill an
  47. array with an arbitrarily large set of values (assuming the passed array
  48. is large enough to contain them).
  49.  
  50. The "Extor System" comprises a small set of "stor" functions which allow
  51. your foreign functions to reassign memory variables which were passed by
  52. reference from a Clipper program.  This includes both individual memory
  53. variables and array elements.
  54.  
  55.  
  56.  
  57. Calling Conventions:
  58.  
  59. The functions follow (sort of) the naming conventions established in the
  60. "par" functions.  In general the form is:
  61.  
  62.     _stor...(value, param_number [, index])
  63.  
  64.     'value' is the value to be stored to the memory variable.  There is
  65.     a different "stor" function for each possible data type.
  66.  
  67.     'param_number' is the ordinal number (starting with one, like the
  68.     "par" functions) which designates the parameter to be affected.
  69.  
  70.     'index' (optional) is used to specify which array element you wish
  71.     to store into.  It is only meaningful if the designated parameter
  72.     is an array (in which case it is required).
  73.  
  74.  
  75. This general form is used by the following "stor" functions:
  76.  
  77.     _storc(string, param_number [, index])
  78.  
  79.     Stores a null terminated string to the designated parameter.
  80.  
  81.  
  82.     _storni(int_val, param_number [, index])
  83.  
  84.     Stores an integer numeric value to the designated parameter.
  85.  
  86.  
  87.     _stornl(long_val, param_number [, index])
  88.  
  89.     Stores a long numeric value to the designated parameter.
  90.  
  91.  
  92.     _stornd(double_val, param_number [, index])
  93.  
  94.     Stores a double numeric value to the designated parameter.
  95.  
  96.  
  97.     _storl(int_val, param_number [, index])
  98.  
  99.     Stores a logical value to the designated parameter.  The value is
  100.     supplied as an integer.  If it is zero, a .F. (FALSE) is stored,
  101.     otherwise a .T. (TRUE) is stored.
  102.  
  103.  
  104.     _stords(date_string, param_number [, index])
  105.  
  106.     Stores a date value to the designated parameter.  The value is
  107.     supplied as a null terminated string containing a printable
  108.     representation (in the form YYYYMMDD) of the date to be stored.
  109.     If you supply a string which does not represent a valid date, a
  110.     "blank date" value will be stored to the designated parameter.
  111.  
  112.  
  113. Two other "stor" functions require an extra argument which specifies
  114. length information:
  115.  
  116.     _storclen(string, length, param_num [, index])
  117.  
  118.     Stores a string to the designated parameter.  The length of the
  119.     string is assumed to be as specified by the 'length' argument
  120.     (an unsigned integer).  This allows you to store strings which
  121.     contain embedded null bytes.  Note that the supplied string need
  122.     not be null terminated, since this function does not scan for a
  123.     null in order to determine the string's length.  The function
  124.     also automatically appends an internal terminator to the stored
  125.     copy of the string.  (Nonetheless, it's a good idea to maintain
  126.     null terminators on your strings for consistency.)
  127.  
  128.  
  129.     _storndec(double_val, decimals, param_num [, index])
  130.  
  131.     Stores a double numeric value to the designated parameter.  The
  132.     'decimals' argument specifies the number of decimal places to be
  133.     shown by default when the associated memory variable is displayed.
  134.     Note that this display default has no effect on the actual value of
  135.     the variable; only the display format is affected.
  136.  
  137.  
  138. All of the functions return an integer.  The return value is 1 (TRUE) if
  139. the function completed successfully, 0 (FALSE) otherwise.
  140.  
  141.  
  142.  
  143. Notes:
  144.  
  145. If a designated parameter is not a memory variable passed by reference,
  146. attempts to "stor" it will be ignored, and the function will return
  147. FALSE.  This means you can safely call these functions on parameters
  148. that were supposed to have been passed by reference, without checking
  149. to see that they really were.  If you do want to check them, you can
  150. use the Extend System macro ISBYREF().
  151.  
  152. If the designated parameter is an array but you fail to supply the
  153. 'index' argument, the "stor" function will select the element that it
  154. feels is most appropriate.  Just kidding.  Actually the results are
  155. unpredictable, so you should always specify an index if the parameter
  156. is an array.  The Extend System macro ISARRAY() can be used to determine
  157. whether a particular parameter is an array.
  158.  
  159. If you try to store an array element which is beyond the limit of the
  160. associated array, the attempt will be ignored, and the function will
  161. return FALSE.
  162.  
  163. It is not possible to create or dimension an array with these functions,
  164. nor is it possible to change an array to a scalar (non-array).
  165.  
  166. These functions automatically allocate memory to contain the variable's
  167. new value.  The new value you supply is automatically copied into the
  168. newly allocated space.  If sufficient memory cannot be allocated, the
  169. variable will remain unchanged and the function will return FALSE.  No
  170. other error is generated.
  171.  
  172. As with any assignment, the previous contents of the designated memory
  173. variable are lost if the "stor" function is successful (returns TRUE).
  174. Any memory that was occupied by the old contents is automatically
  175. reclaimed.
  176.  
  177. Future versions of Clipper will likely provide a similar capability.  It
  178. will not necessarily take the same form as this system, however, so you
  179. would be wise to isolate the use of these functions to easily identified
  180. areas of your code.
  181.  
  182.  
  183.  
  184. Example:
  185.  
  186. /***
  187. *    fill an array with zeros
  188. *
  189. *    example:
  190. *
  191. *    PRIVATE a[10]
  192. *    AZERO(a)
  193. *
  194. */
  195.  
  196. CLIPPER AZERO()
  197.  
  198. {
  199.     int count;
  200.     int index;
  201.  
  202.  
  203.     if (ISARRAY(1))
  204.     {
  205.         count = ALENGTH(1);
  206.         index = 1;
  207.  
  208.         while (index <= count)
  209.         {
  210.             _storni(0, 1, index);
  211.             index++;
  212.         }
  213.     }
  214.  
  215.     _ret();
  216. }
  217.  
  218.  
  219.  
  220. Conclusion:
  221.  
  222. The "Extor System" is a handy thing to have on those occasions when you
  223. need to retrieve a lot of data from an external source.  Other creative
  224. uses are possible, such as more efficient packing and unpacking of
  225. structured data.
  226.  
  227. For some general advice on Clipper-callable functions, please refer to
  228. the notes in the "readme.doc" file.
  229.  
  230.