home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / xbase / library / clipper / cgoodies / sysinfo.doc < prev    next >
Encoding:
Text File  |  1988-06-08  |  8.3 KB  |  238 lines
  1. "Sysinfo"
  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. An "internal" is a function or storage location which is not part of the
  12. published (or external) specification of a system.
  13.  
  14. A "key code" is the number used by Clipper to refer to a key on the
  15. keyboard, ala the INKEY() function.
  16.  
  17.  
  18.  
  19. Background:
  20.  
  21. Use of internals is always a tricky subject, and Clipper's open
  22. architecture compounds the problem, mainly via increased temptation.
  23. The Clipper runtime support library (CLIPPER.LIB) is a standard Intel
  24. format library, and no particular attempt is made to conceal the meaning
  25. of the items within it (although some of them are intrinsically non-
  26. obvious).  If you're good with a debugger, you may have already made
  27. interesting discoveries.  Some Clipper add-on products make use of
  28. information which the authors have laboriously derived via this method.
  29.  
  30. Use of internals, however, can be dangerous.  They are not explicity
  31. documented or supported, so you use them at your own risk.  Accessing
  32. them incorrectly can cause unexplained system failure, and Nantucket
  33. support personnel are not trained to answer questions about them.
  34.  
  35.  
  36. Version Dependence:
  37.  
  38. Many of the most coveted pieces of internal information are likely to
  39. change in future versions of Clipper.  There are two main reasons for
  40. this.
  41.  
  42. First, Clipper's internal organization tends to change significantly
  43. from one release to the next.  When new, more efficient methods are
  44. found for achieving some result, they are adopted if they are upwardly
  45. compatible with the external specification of the system.  The need
  46. to maintain internal compatibility with earlier releases would greatly
  47. complicate the task of improving the system.
  48.  
  49. Second, many of the most desired pieces of internal information are
  50. conceptually bound to the current Clipper/dBASE model of programming.
  51. In the future, this model may change significantly in order to support
  52. more powerful development models.
  53.  
  54. A simple example might be the "insert mode" setting.  Most dBASE
  55. implementations provide a single system-wide insert mode which affects
  56. keyboard input during several kinds of operations.  In Clipper this
  57. includes both the READing of GETs and input to the MEMOEDIT() function.
  58. This orientation might change in a future version in order to provide
  59. more powerful input capabilities.  For example, each window defined in
  60. the system might have its own insert mode setting.  Perhaps individual
  61. GETs would be able to have their own setting!  In either case, if you
  62. were directly reading the current internal insert flag, you might find
  63. that it no longer existed in such a version, or that its meaning had
  64. changed considerably.
  65.  
  66.  
  67.  
  68. So?
  69.  
  70. Despite the foregoing, there are those cases where access to certain
  71. global state information is valuable.  It may in fact promote better
  72. program structure (read more modularity) since the ability to preserve
  73. state information favors the creation of "black box" modules which
  74. automatically preserve the system state on entry and restore it on
  75. exit.  Certain information of this type has been made available at the
  76. "surface" level in Clipper (e.g. the SETCOLOR() function).  Other
  77. information is buried in the guts of the system, only visible to late-
  78. night hackers with symbolic debuggers and lots of coffee.
  79.  
  80. The "sysinfo" functions are a small set of C-callable functions which
  81. allow you to interrogate the values of some of Clipper's internal state
  82. variables.  They provide access to some of the most requested internal
  83. items through a procedural interface.
  84.  
  85. For the very reasons cited above:
  86.  
  87. THESE FUNCTIONS ARE VERSION DEPENDENT!
  88.  
  89. However, since they provide a procedural interface between your program
  90. and the actual internal values, an equivalent capability (if available)
  91. in future releases would probably be usable with minimal changes to your
  92. code.  The functions are also "safe."  That is, you cannot damage the
  93. system state by calling them.
  94.  
  95.  
  96.  
  97. Calling conventions:
  98.  
  99. Most of the functions allow the examination of the current setting of
  100. SET commands.  Three of them take a single parameter (referred to as
  101. 'specifier' below) which specifies the SET to be interrogated.  The
  102. file "sysinfo.h" includes a list of #define statements for these
  103. specifiers.  You should use them when calling the functions.
  104.  
  105.  
  106.     _sys_boolean(specifier)
  107.  
  108.     This function returns the current state of a system boolean (ON/OFF)
  109.     variable.  If the corresponding SET is "ON", the function returns a
  110.     value of 1 (TRUE).  Otherwise, the function returns 0 (FALSE).
  111.  
  112.  
  113.     _sys_int(specifier)
  114.  
  115.     This function returns the current state of SET commands which accept
  116.     a numeric parameter.  The current setting is returned as an integer.
  117.  
  118.  
  119.     _sys_string(specifier)
  120.  
  121.     This function returns the current state of SET commands which accept
  122.     a character parameter.  The function returns a pointer to a string
  123.     representing the current setting.
  124.  
  125.  
  126.     _setkey_count()
  127.  
  128.     This function returns the number of SET KEY's which are currently
  129.     active.  The count is returned as an integer.
  130.  
  131.  
  132.     _setkey_key(ordinal)
  133.  
  134.     This function returns the key code associated with the SET KEY
  135.     specified by 'ordinal'.  For example, if there are 10 SET KEY's
  136.     currently active, then _setkey(5) will return the code of the key
  137.     associated with the fifth SET KEY.  The value is returned as an
  138.     integer.  If 'ordinal' is greater than the number of SET KEY's
  139.     currently active, the function returns zero.  Note that adding or
  140.     clearing a SET KEY can cause the ordinal numbers to change, so you
  141.     shouldn't assume they will be the same from one call to the next.
  142.  
  143.  
  144.     _setkey_proc(key_code)
  145.  
  146.     This function returns a pointer to a string containing the name of
  147.     the procedure associated with the specified key code.  If the
  148.     specified key is not currently associated with a procedure, the
  149.     function returns a pointer to a null string.  For example, if your
  150.     application has executed the statement  SET KEY -3 TO HELP  then
  151.     _setkey_proc(-3) will return a pointer to a string containing
  152.     "HELP".  Note that the parameter is a key code, not the ordinal
  153.     number of a SET KEY.
  154.  
  155.  
  156.  
  157. Notes:
  158.  
  159. Those functions which return a character pointer return a pointer to
  160. a single statically allocated buffer.  You should make a copy of the
  161. information if you wish to preserve it, since subsequent calls will
  162. overwrite the buffer.  Also, changing the contents of this buffer has
  163. no effect on the actual internal value.
  164.  
  165. Note that the values can only be interrogated, not set, by these
  166. functions.  The intention is that you use these functions to write
  167. Clipper-callable functions which return the state information to a
  168. Clipper function.  These higher level functions could save and/or
  169. restore the state information via normal means.
  170.  
  171. There are a number of ways to arrange Clipper-callable versions of these
  172. functions.  The example below uses the Extor system and the sysinfo
  173. functions to fill in an array with the current SET KEY settings.  A
  174. Clipper function could be written which would restore the saved settings
  175. at some later time.
  176.  
  177.  
  178.  
  179. Example:
  180.  
  181. /***
  182. *    fill two arrays with SET KEY information, return SET KEY count
  183. *
  184. *    example:
  185. *
  186. *    count = GETKEYS()
  187. *    PRIVATE keys[count], procs[count]
  188. *    GETKEYS(keys, procs)
  189. *
  190. */
  191.  
  192. CLIPPER GETKEYS()
  193.  
  194. {
  195.     int count;
  196.     int index;
  197.     int key;
  198.     char *proc;
  199.  
  200.  
  201.     count = _setkey_count();
  202.  
  203.     if (ISARRAY(1))
  204.     {
  205.         for (index = 1; index <= count; index++)
  206.         {
  207.             key = _setkey_key(index);
  208.             _storni(key, 1, index);
  209.         }
  210.     }
  211.  
  212.     if (ISARRAY(2))
  213.     {
  214.         for (index = 1; index <= count; index++)
  215.         {
  216.             key = _setkey_key(index);
  217.             proc = _setkey_proc(key);
  218.             _storc(proc, 2, index);
  219.         }
  220.     }
  221.  
  222.     _retni(count);
  223. }
  224.  
  225.  
  226.  
  227. Conclusion:
  228.  
  229. The "sysinfo" functions are useful for creating "black box" modules
  230. which automatically preserve the application's state on entry and
  231. restore it on exit.  These functions are best used as the low level
  232. component of a Clipper-callable facility for state preservation and
  233. restoration.
  234.  
  235. For some general advice on Clipper-callable functions, please refer to
  236. the notes in the "readme.doc" file.
  237.  
  238.