home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / clarion / lemglue.zip / README.DOC < prev   
Text File  |  1992-04-01  |  14KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                         LEMGLUE Documentation
  7.                By Robert Cox, Wed Apr 01 10:21:29 1992
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.     A. Purpose
  21.  
  22.     B. Implementation
  23.      1. The Problem.
  24.      2. The Solution.
  25.      3. Restrictions and Pitfalls
  26.  
  27.     C. Useage
  28.      1. The Files Involved
  29.      2. Trouble to watch for.
  30.      3. Erros and solutions.
  31.  
  32.     D. Technical Tidbits
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.     A.  Purpose  To  provide  a  bridge  to  3.0  for users of LEMs
  73.       supplied by manufacturers who no long support them.
  74.  
  75.     B. Implementation
  76.  
  77.       1. The Problem.
  78.             The LEM  mechanism  in  Clarion  2.1  is  a  simplistic
  79.         interface   to   a  vast  array  of  functionality  in  the
  80.         processor.  In version 3.0, the register useage,  parameter
  81.         passing,  memory allocation, and many other conventions are
  82.         drastically different.  The existing code in a  .BIN  would
  83.         not  work  even  if  it could be linked into a 3.0 program.
  84.         This fact could  render  as  many  as  80-90%  of  existing
  85.         commercial Clarion programs unconvertible to version 3.0.
  86.             Good  news and bad news.  The bad news first.  Although
  87.         only a narrow range of functions were explicitly documented
  88.         to  be available, it is my understanding (from legend) that
  89.         lem kits were shipped  that  discussed  the  capability  of
  90.         calling  standard  C  as  well  as other esoteric processor
  91.         functions. Possibly up to  199  of  them.  In  addition  to
  92.         these,  92  global  data  items were also accessible.  This
  93.         means that some third  party  developers  could  have,  and
  94.         probably  did, use these features to a large degree.  It is
  95.         nearly impossible to support many of these vectors in  3.0,
  96.         since   most   don't   exist,  and  others  are  completely
  97.         meaningless.
  98.             Now the  good  news.  I  believe  the  afore  mentioned
  99.         dissaster  is  the  exception rather than the rule.  If so,
  100.         then the  majority  of  third  party  developers  used  the
  101.         limited set of defined vectors, outlined in the appendix to
  102.         the language reference, which all happen to be  convertible
  103.         to 3.0.  Armed with this optimistic lens, I have produced a
  104.         utility which attempts to  provide  a  practical  level  of
  105.         convertability for these "well behaved" BINs.
  106.  
  107.       2. The Solution.
  108.             To achieve coherence between the old and the new I have
  109.         applied judicious amounts of Assembler, C, and Clarion code
  110.         to  act  as  translation  units  at  various  stages of the
  111.         process.  Lets go for a walk through a typical  call  to  a
  112.         LEM.
  113.             We start in the main Clarion procedure code, and call a
  114.         lem function.  Control is then passed via a native  machine
  115.         call instruction to another Clarion function which has been
  116.         added for translation.  This Clarion function in turn calls
  117.         an Assembly language routine which does further translation
  118.         before  calling  the  actual  BIN  routine.  When  the  BIN
  119.         routine returns, control is passed back along the same path
  120.         we came in until the main Clarion code once  again  resumes
  121.         control.  The  parameters  are "magically" carried back and
  122.         forth, and the calls from the BINs into other parts of  the
  123.         program  are  "handled".  There is an awful lot more to it,
  124.         ofcourse, but this is the general idea.  In order  for  all
  125.         these   parts   to   function   there  is  some  additional
  126.         unavailable  information  that  must  be  supplied   during
  127.         "manual" conversion.
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.       3. Restrictions and Pitfalls
  139.  
  140.             What  with all this "magic" flying around there's bound
  141.         to  be  a  bang  sometime.  Clarion  2.1  had  a   slightly
  142.         different  convention for passing parameters than does 3.0.
  143.         This is  especially  true  for  STRINGS  and  GROUPS.  When
  144.         passing  STRINGS  or  GROUPS  to  a BIN function, it is now
  145.         necessary to be aware of whether or  not  the  BIN  routine
  146.         will  want to change the value of that STRING or GROUP.  If
  147.         so, some minor manual modifications will have to  be  made.
  148.         Unfortunately,  there is no way of determining exactly what
  149.         is needed, you must make a "best guess". There is  also  no
  150.         type  safe  linking.  That is; there is no way to determine
  151.         wether or not the BIN routine being converted does, or does
  152.         not  require  unsupported  vector  functions.  We  can  add
  153.         certainty after calling every  function  in  the  BIN,  and
  154.         verifying  the  results.  Unfortunately,  even  this  is no
  155.         gurantee since, different execution  conditions  may  cause
  156.         the  same  routine to make a vector call on a different day
  157.         or machine.  All the same, this is not a  life  threatening
  158.         concern in most cases, if an unsupported vector function is
  159.         ever accessed the program will  halt  with  an  appropriate
  160.         message.  Finally,  the BIN files must be accessible to the
  161.         program at execution time.
  162.  
  163.     C. Useage
  164.  
  165.       1. The Files Involved.
  166.             The  files  you  will  be  concerned  with  during  the
  167.         conversion process are the following:
  168.  
  169.       main.CLA
  170.           All  your  application .CLA files, especially the program
  171.         module.
  172.  
  173.       lem.BIN
  174.          All the .BIN files associated with the application.
  175.  
  176.       lem.CPY
  177.          The LEM routine declarations.
  178.  
  179.       LEM2CLA.EXE
  180.          The BIN conversion utility program.
  181.  
  182.       LEMGLUE.LIB
  183.          The compiled interface modules.
  184.  
  185.       lem.CLA
  186.          The generated clarion interface module.
  187.  
  188.             For future reference: "lem" is the  name  of  the  .BIN
  189.         file, without the extension, and "main" is the file name of
  190.         the  main  program  module,  without  the  extension,   and
  191.         "module"  is  the  name  of an arbitrary application module
  192.         without the extension.
  193.             To convert a program that uses a BIN do the following:
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.         Step 0.
  205.  
  206.               Backup your 2.1 application.
  207.  
  208.         Step 1.
  209.               Convert your 2.1 application to 3.0 using CLACNV.EXE,
  210.           compile it and remove all the systax errors.  Ignore link
  211.           errors that refer to BIN functions.
  212.  
  213.         Step 2.
  214.               Accumulate the following files in a directory:
  215.               main.CLA
  216.               lem.BIN
  217.               lem.CPY
  218.               LEM2CLA.EXE
  219.               LEMGLUE.LIB
  220.  
  221.         Step 3.
  222.  
  223.         !WARNING!
  224.               If you have  a  module.CLA  with  the  same  name  as
  225.           lem.BIN   rename   one   or   the  other.  LEM2CLA,  when
  226.           successful, will CREATE lem.CLA.
  227.  
  228.         NOTE:
  229.               lem.BIN must have the same primary name  as  lem.CPY.
  230.           eg: CHECK.BIN and CHECK.CPY
  231.  
  232.               From the DOS command line, enter:
  233.               LEM2CLA lem main
  234.  
  235.               If successful, this will create a lem.CLA file in the
  236.           current directory.  If not successful, see the section on
  237.           Trouble to watch for.
  238.  
  239.         Step 4.
  240.               You  will  need  an  editor  for this step.  Load the
  241.           main.CLA and the lem.CLA  files  into  your  editor.  The
  242.           lem.CLA  file contians a MAP MODULE structure and a local
  243.           MAP.  There  is  a  comment  declaring  the  MAP   MODULE
  244.           structure as:
  245.               !*** Begin Global Map Reference
  246.               Insert  a  copy  of  this entire MAP MODULE structure
  247.           into the main  programs'  MAP  structure  where  the  BIN
  248.           module  was  declared.  Remove  the  "INCLUDE('lem.CPY')"
  249.           statements, if any, from the main.CLA,  as  well  as  any
  250.           other old MAP references to the BIN routines.  Remove the
  251.           Global  MAP  MODULE  structure  from  the  lem.CLA  file,
  252.           leaving   only   the   local   MAP.   Add  the  statement
  253.           "INIT_lem()" somewhere in the application  initialization
  254.           code.  This  statement must be executed before any of the
  255.           functions in the lem LEM can be called.
  256.  
  257.         Step 5
  258.               Add the lem.CLA module to the project  system  as  an
  259.           "External   Source   File"  and  the  LEMGLUE.LIB  as  an
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.           "External   OBJ/LIB   File".   Finally,   recompile   the
  271.           application and test it.  Note, the lem.BIN file must now
  272.           reside in the directory from  which  the  application  is
  273.           executed,  or,  the flag switch "CLABIN=directory" may be
  274.           used to direct the application to a  specific  directory.
  275.           See  other  documentation  for  discussion of the COMMAND
  276.           flags.
  277.  
  278.       2. Trouble to watch for.
  279.  
  280.       GROUPS or STRINGS don't recieve expected values
  281.             As mentioned before, some parameter passing conventions
  282.         may  be  out of sync when you execute the BIN calls.  These
  283.         pertain primarily to STRINGS and  GROUPS  being  passed  by
  284.         value, or by reference.  These settings must be "intuited",
  285.         or guessed at, and tweaked manually in the  prototypes  for
  286.         the lem procedures in the main MODULE MAP.
  287.  
  288.       3. Erros and solutions.
  289.  
  290.         BIN file xxx, NOT FOUND.
  291.               The  lem.BIN  file is not in the directory from which
  292.           LEM2CLA is run.
  293.  
  294.         CPY file xxx, NOT FOUND.
  295.               The lem.CPY file is not in the directory  from  which
  296.           LEM2CLA is run. If no .CPY file is available, one must be
  297.           created.  Only the functionss need to be defined however,
  298.           the .CPY file is not needed for procedures.
  299.  
  300.         Could Not Open Output File xxx
  301.               Some  error  occured attempting to create the lem.CLA
  302.           file.
  303.  
  304.         Could Not Read .BIN
  305.               Some error occured attempting  to  read  the  lem.BIN
  306.           file.
  307.  
  308.         Invalid .BIN file
  309.               The lem.BIN file does not display the required header
  310.           signature for
  311.  
  312.         Could Not Read Routine Descriptor in .BIN file
  313.               The .BIN header may have declared more routines to be
  314.           in the file than are actually there, or the file may have
  315.           been truncated.
  316.  
  317.         Too Many Parameter In Procedure Definition
  318.               The routine in  question,  requires  more  parameters
  319.           than  LEMGLUE  is set up to handle.  Currently this value
  320.           is 64.
  321.  
  322.         Could Not Read Parameter Descriptor in .BIN file
  323.               The routine header may have declared more  parameters
  324.           than  are  actually  there,  or  the  file  may have been
  325.           truncated.
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.         Insufficient Memory
  337.  
  338.               LEM2CLA requires more available  memory  to  complete
  339.           the   conversion.  See  discussion  of  memory  in  other
  340.           documentation.
  341.  
  342.         Could not read .CPY file
  343.               The lem.CPY file is  not  the  directory  from  which
  344.           LEM2CLA is run.
  345.  
  346.         Function xxx Has No Return Type In .CPY
  347.               A  function  xxx was defined in the .BIN file, but in
  348.           the .CPY file it is declared as a PROCEDURE.  In order to
  349.           complete   the   conversion,   declare  the  function  as
  350.           returning LONG.  This return value should never be used.
  351.  
  352.         CPY Does Not Declare xxx File
  353.               A function xxx was defined in the  .BIN  file,  which
  354.           was  not  declared  in  the  .CPY  file.  The function is
  355.           prabably not meant to be a public  function,  and  should
  356.           never  be  called.  In  order to complete the conversion,
  357.           declare the function in the  .CPY  file  as  returning  a
  358.           LONG. Again, this function should never be called.
  359.  
  360.       4. Runtime errors
  361.  
  362.         xxx : Could Not Open .BIN File
  363.               The  .BIN file could not be located by the "INIT_lem"
  364.           function.  See Step 5 above.
  365.  
  366.         Could Not Read .BIN File
  367.               Some disk error occured, the BIN file  could  not  be
  368.           loaded.
  369.  
  370.         Call To Invalid or Uninitialized LEM
  371.               The Clarion main program called a LEM function before
  372.           it was  initialized.  The  "INIT_lem"  function  must  be
  373.           called  prior to calling any of the functions in the LEM.
  374.           eg: If the name of your .BIN is CHECKS.BIN, the  function
  375.           to   call,   as   declared   in  the  Global  MAP  MODULE
  376.           declaration, is "INIT_CHECKS()".
  377.  
  378.         Call To Non Existent LEM Routine
  379.               The Clarion program is corrupted.
  380.  
  381.         LEM to Library Data Vector Not Supported
  382.               The LEM  is  requesting  unsupported  data  from  the
  383.           processor.
  384.  
  385.         LEM to Library Function Vector Not Supported
  386.               The   LEM   called  back  to  the  processor  for  an
  387.           unsupported function.
  388.  
  389.     D. Technical Tidbits
  390.           To  approach  a  solution,  we  limit  ourselves  to  the
  391.       activities of entering, exiting, and the passage of parameter
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.       values between 3.0 and the  old  .BIN  routines.  Given  that
  403.       this  is  achievable,  we  are  left with the problem of call
  404.       backs from the BIN to the processor.  To  address  entry  and
  405.       return of BIN routines, I supplied translation code
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.