home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / clarion / ovlay.zip / OVLAY.DOC < prev    next >
Text File  |  1990-04-17  |  5KB  |  88 lines
  1.                 Documentation for OVLAY.CLA version 2
  2.                 -------------------------------------
  3.  
  4.         This is a method of allowing overlayed procedures to call each
  5.         other.  This is accomplished by adding the name of the called
  6.         procedure to a stack, plus (optionally) the name of the procedure
  7.         to return to, and a message (80 bytes) to be passed to the
  8.         procedure.  The first procedure then returns, allowing a master
  9.         control procedure to gain control.  The control procedure pops
  10.         the top record off the stack, determines if it is processing a
  11.         'call' or a 'return', and calls the appropriate procedure.
  12.  
  13.         4 changes were made to the original version to make it more
  14.         efficient:
  15.            1.   The mnemonic names of procedures were changed to
  16.                 numeric byte equates from 1 to n allowing
  17.                 enhancements 2 and 3.
  18.            2.   The case statements in SEL_PROC were replaced
  19.                 with an execute structure which should execute
  20.                 in the same amount of time regardless of the
  21.                 number of overlay procedures it is managing.
  22.                 (Overhead time to process a large case
  23.                 structure could have become significant if
  24.                 the number of procedures was large).
  25.            3.   The 2 12-byte strings in the stack structure
  26.                 were replaced by a pair of BYTE fields - a
  27.                 savings of 10 bytes per record in the stack.
  28.                 This would also reduce string comparison
  29.                 time overhead.
  30.            4.   The message string was moved to the end of
  31.                 the structure so that Clarion's implicit
  32.                 truncation could chop off the portion of it
  33.                 that was unused - a potential savings of up
  34.                 to 80 bytes per stack record (depending on
  35.                 the messages being passed).
  36.  
  37.         How to use it.
  38.            1.   You must assign equates for all procedures (that you will be
  39.                 using) into PROCDEFS.INC.  You must put the procedure
  40.                 names into the EXECUTE structures in the SEL_PROC function in
  41.                 OVLAY.CLA (in the same numerical order as they are
  42.                 declared in PROCDEFS.INC).  NOTE:  PRETURN EQUATE(01)
  43.                 is a MANDATORY statement in PROCDEFS.INC.
  44.            2.   Modify the MEMBER statement in OVLAY.CLA to match your
  45.                 main program.
  46.            3.   Add the line  INCLUDE('OVLAY1.CPY') to your MAP structure
  47.            4.   Add the lines INCLUDE('OVLAY2.CPY') to your global
  48.                 data area.
  49.            5.   The main program should push the first procedure onto the
  50.                 stack and call PROC_CTL to start the ball rolling.
  51.            6.   For one procedure to call another procedure, it should first
  52.                 push the call record onto the stack, and then execute
  53.                 a RETURN statement.
  54.            7.   To push a call record/procedure onto the stack, use the call
  55.  
  56.                         STACK_PROC(call proc,return proc,'message')
  57.  
  58.                 call proc is the name of the procedure you are calling as
  59.                         defined in PROCDEFS.INC
  60.                 return proc is the name of the procedure that should gain
  61.                         control after call proc terminates (it does not
  62.                         have to be the procedure that is making the call
  63.                         but imposing that restriction may make debugging
  64.                         easier).  If you do not want a return proc
  65.                         then use the name PRETURN.
  66.                 message is data to be passed to the called procedure (via
  67.                         global string variable PMSG).  It is currently 80
  68.                         bytes long but you can change it.  If you don't
  69.                         have a message to pass, just leave the quotes empty.
  70.                         Message can be a constant in single quotes, (')
  71.                         or the name of a string variable or constant.
  72.  
  73.         Limitations:
  74.            1.   All parameter passing must be through PMSG.
  75.            2.   Calling procedure should close all screen structures before
  76.                 making the call or unexpected results may occur.
  77.            3.   If control is returned to a procedure after a call, it's
  78.                 logic should either determine the difference between a first
  79.                 time call and a return so that it may jump to the appropriate
  80.                 point for resuming code execution if necessary.  This may
  81.                 require the use of global flags in the main program.
  82.            4.   If a procedure making a call to another procedure needs to
  83.                 save any of its local data, it must do so explicitly before
  84.                 making the call, and then restore it explicitly upon
  85.                 receiving control back.
  86.  
  87.         For an example of the use of OVLAY.CLA, see OVSAMPLE.CLA
  88.