home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / AIE8911.ZIP / SPECS.DOC < prev    next >
Encoding:
Text File  |  1989-09-21  |  6.2 KB  |  214 lines
  1.  
  2.  
  3.  
  4.  
  5.        SPECS , THE INSTANT RECALL SPECIFICATION INTERPRETER
  6.  
  7.                (C) Copyright 1989 by INSTANT RECALL
  8.                       All rights reserved.
  9.                Use subject to license agreement below.
  10.  
  11.                           Instant Recall
  12.                           5900 Walton Rd.
  13.                           Bethesda, Md. 20817 USA
  14.                           (301) 530-0898
  15.  
  16.  
  17. SPECS is a program that runs an evolving system specification.
  18. SPECS lets the systems analyst
  19.  
  20. 1.  Develop a top-down specification of system logic.
  21. 2.  Supress unwanted details.
  22. 3.  Run the specification at any time.
  23.  
  24. 0.  GETTING STARTED
  25. ~~~~~~~~~~~~~~~~~~~
  26.  
  27. 1.  Un-arc the program, if necessary.
  28.  
  29. 2.  Make sure the following files are reachable by PATH and
  30.     FILEPATH commands:
  31.  
  32.     specs.exe
  33.     specs.idb
  34.  
  35. 3.  Make sure the file containing your system definition and
  36.     a SPECS.INI file which loads the system definition are
  37.     in the current directory.  NOTE: The SPECS.INI file that
  38.     comes with SPECS loads the system defined in V2.ARI.
  39.  
  40. 4.  To start SPECS, type SPECS at the DOS prompt as shown:
  41.  
  42.     >SPECS <CR>
  43.  
  44. 5.  See section 1.2 for an example of what to do when you are
  45.     in SPECS.
  46.  
  47. 6.  To exit SPECS, type
  48.  
  49.     halt.
  50.  
  51. 1.  A SIMPLE EXAMPLE
  52. ~~~~~~~~~~~~~~~~~~~~
  53.  
  54. 1.1  The Specifications
  55.  
  56. Here is a simple partial specification of a system in SPECS.
  57.  
  58. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  59.  
  60.            A System Specification for SPECS
  61.  
  62. stub  [ call : process_housing_unit( X )         ,
  63.         purpose: $processes a housing unit$].
  64.  
  65. :- turn( process_housing_unit, on).
  66. :- show( process_housing_unit, on).
  67.  
  68. process_housing_unit( X ) :-
  69.        data_collected_q( X ),
  70.        !,
  71.        put_in_sample( X ).
  72. process_housing_unit( X ) :-
  73.        write_error([ $No data for $, X]).
  74.  
  75. %%%%%%%%%%%% end process_housing_unit %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  76.  
  77. stub  [ call : data_collected_q(  Housing_unit  ),
  78.         purpose: $decides if data was collected for Housing_unit$].
  79.  
  80. stub  [ call : put_in_sample(  Housing_unit  ),
  81.         purpose: $puts data into sample for used for CPI$].
  82.  
  83.               Box 1
  84.  
  85. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  86.  
  87. The specs consist of two parts:  Prolog code that defines the
  88. procedural logic of the parts of the system that have been
  89. defined in some detail; and stubs that define the general
  90. purpose and manner to call procedures that have not been defined.
  91. In the above example, there are 3 procedures, only one of which
  92. has been defined in Prolog.
  93.  
  94. The Prolog definition of <I>process_housing_unit<R>
  95. says that when data has been collected ( <I>data_collected_q<R> succeeds)
  96. then put t he data in the sample ( with <I>put_in_sample<R>);
  97. otherwise, write an error message.  We have not yet defined
  98. how we test whether data has
  99. been collected, how we put it in the sample, or the form of
  100. the data.
  101.  
  102. Generally, as a system evolves, the definition gets more detailed.
  103. For example, the first version specs for the system in Box 1
  104. might have contained only
  105.  
  106. stub  [ call : process_housing_unit( X )         ,
  107.         purpose: $processes a housing unit$].
  108.  
  109. 1.2  A Sample Run
  110.  
  111. After following the steps of Section 0, Getting Started, you
  112. see on your screen the following: (Note: we will assume you
  113. have loaded the pre-supplied demo file V2.ARI using the
  114. pre-supplied SPECS.INI.
  115.  
  116.  Loading System Description.
  117. consulting v2...consulted!
  118. ?>
  119.  
  120.  
  121. The first thing we will do is to list the definition of our <I>test<R>.
  122. <I>test<R> is defined in Prolog in the specs file <I>v2.ari<R>.
  123. Our screen now shows
  124.  
  125. ?>listing( test).
  126. test :-
  127.     process_housing_unit(1).
  128.  
  129. Now we'll run test a couple times:
  130.  
  131. ?>test.
  132. process_housing_unit(1) processes a housing unit.
  133. data_collected_q decides if data was collected for Housing_unit.
  134. Is data_collected_q(1) true? ( y or n) : y
  135.  
  136. ?>test.
  137. process_housing_unit(1) processes a housing unit.
  138. data_collected_q decides if data was collected for Housing_unit.
  139. Is data_collected_q(1) true? ( y or n) : n
  140. ACHTUNG, ACHTUNG, ERROR -- No data for 1
  141.  
  142. Now we'll turn "showing <I>process_housing_unit<R>" off, and
  143. run <I>test<R> again:
  144.  
  145. ?>show( process_housing_unit,off).
  146. ?>test.
  147. data_collected_q decides if data was collected for Housing_unit.
  148. Is data_collected_q(1) true? ( y or n) : y
  149. put_in_sample(1) puts data into sample for used for CPI.
  150.  
  151. When we turn <I>process_housing_unit<R> off, the stub is used
  152. instead of the Prolog definition:
  153.  
  154. ?>turn( process_housing_unit,off).
  155. ?>test.
  156. process_housing_unit(1) processes a housing unit.
  157.  
  158. To leave the system and return to DOS, we do
  159.  
  160. ?>halt.
  161.  
  162.  
  163. 1.3  Execution Commands
  164.  
  165. The lines in the example specifications,
  166.  
  167. :- turn( process_housing_unit, on).
  168. :- show( process_housing_unit, on).
  169.  
  170. are commands.  The <I>turn<R> command says "turn on the Prolog
  171. definition of <I> process_housing_unit<R>.  If we wanted to
  172. turn off the Prolog definition, we would write
  173.  
  174. :- turn( process_housing_unit, off).
  175.  
  176. When a procedure defined both in Prolog and a stub is turned on,
  177. the Prolog definition is used.  When it is turned off, just the
  178. stub is used.  The default is that a Prolog-defined procedure is
  179. turned on.
  180.  
  181. When <I>show<R> for a procedure is turned on, a message is printed
  182. whenever the procedure is entered.  No message is printed when
  183. the procedure is turned off.
  184.  
  185. 1.4  Specification load file.
  186.  
  187. The special file SPECS.INI tells SPECS what specifications to
  188. read in.  For example, if the specs are stored in file V2.ARI,
  189. define SPECS.INI as follows:
  190.  
  191. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  192.  
  193.                 Example SPECS.INI file
  194.  
  195. :- rconsult( 'v2.ari' ).
  196.  
  197. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  198.  
  199.  
  200. 2.   Formal Definition of Specifications for SPECS
  201.  
  202.     (to be supplied later)
  203.  
  204. APPENDIX -- LICENSE AGREEMENT
  205.  
  206.    You may use this program in both source and executable form free of
  207.    charge for personal non-commercial use.  The program and code may not
  208.    be modified, incorporated into other programs, or used commercially
  209.    academically or by other organizations without written permission
  210.    from Instant Recall.
  211.  
  212.                     - EOF -
  213.  
  214.