 




                        LEMGLUE Documentation
               By Robert Cox, Wed Apr 01 10:21:29 1992












    A. Purpose

    B. Implementation
     1. The Problem.
     2. The Solution.
     3. Restrictions and Pitfalls

    C. Useage
     1. The Files Involved
     2. Trouble to watch for.
     3. Erros and solutions.

    D. Technical Tidbits







































    A.  Purpose  To  provide  a  bridge  to  3.0  for users of LEMs
      supplied by manufacturers who no longer support them.

    B. Implementation

      1. The Problem.
            The LEM  mechanism  in  Clarion  2.1  is  a  simplistic
        interface   to   a  vast  array  of  functionality  in  the
        processor.  In version 3.0, the register useage,  parameter
        passing,  memory allocation, and many other conventions are
        drastically different.  The existing code in a  .BIN  would
        not  work  even  if  it could be linked into a 3.0 program.
        This fact could  render  as  many  as  80-90%  of  existing
        commercial Clarion programs unconvertible to version 3.0.
            Good  news and bad news.  The bad news first.  Although
        only a narrow range of functions were explicitly documented
        to  be available, it is my understanding (from legend) that
        lem kits were shipped  that  discussed  the  capability  of
        calling  standard  C  as  well  as other esoteric processor
        functions. Possibly up to  199  of  them.  In  addition  to
        these,  92  global  data  items were also accessible.  This
        means that some third  party  developers  could  have,  and
        probably  did, use these features to a large degree.  It is
        nearly impossible to support many of these vectors in  3.0,
        since   most   don't   exist,  and  others  are  completely
        meaningless.
            Now the  good  news.  I  believe  the  afore  mentioned
        dissaster  is  the  exception rather than the rule.  If so,
        then the  majority  of  third  party  developers  used  the
        limited set of defined vectors, outlined in the appendix to
        the language reference, which all happen to be  convertible
        to 3.0.  Armed with this optimistic lens, I have produced a
        utility which attempts to  provide  a  practical  level  of
        convertability for these "well behaved" BINs.

      2. The Solution.
            To achieve coherence between the old and the new I have
        applied judicious amounts of Assembler, C, and Clarion code
        to  act  as  translation  units  at  various  stages of the
        process.  Lets go for a walk through a typical  call  to  a
        LEM.
            We start in the main Clarion procedure code, and call a
        lem function.  Control is then passed via a native  machine
        call instruction to another Clarion function which has been
        added for translation.  This Clarion function in turn calls
        an Assembly language routine which does further translation
        before  calling  the  actual  BIN  routine.  When  the  BIN
        routine returns, control is passed back along the same path
        we came in until the main Clarion code once  again  resumes
        control.  The  parameters  are "magically" carried back and
        forth, and the calls from the BINs into other parts of  the
        program  are  "handled".  There is an awful lot more to it,
        ofcourse, but this is the general idea.  In order  for  all
        these   parts   to   function   there  is  some  additional
        unavailable  information  that  must  be  supplied   during
        "manual" conversion.










      3. Restrictions and Pitfalls

            What  with all this "magic" flying around there's bound
        to  be  a  bang  sometime.  Clarion  2.1  had  a   slightly
        different  convention for passing parameters than does 3.0.
        This is  especially  true  for  STRINGS  and  GROUPS.  When
        passing  STRINGS  or  GROUPS  to  a BIN function, it is now
        necessary to be aware of whether or  not  the  BIN  routine
        will  want to change the value of that STRING or GROUP.  If
        so, some minor manual modifications will have to  be  made.
        Unfortunately,  there is no way of determining exactly what
        is needed, you must make a "best guess". There is  also  no
        type  safe  linking.  That is; there is no way to determine
        wether or not the BIN routine being converted does, or does
        not  require  unsupported  vector  functions.  We  can  add
        certainty after calling every  function  in  the  BIN,  and
        verifying  the  results.  Unfortunately,  even  this  is no
        gurantee since, different execution  conditions  may  cause
        the  same  routine to make a vector call on a different day
        or machine.  All the same, this is not a  life  threatening
        concern in most cases, if an unsupported vector function is
        ever accessed the program will  halt  with  an  appropriate
        message.  Finally,  the BIN files must be accessible to the
        program at execution time.

    C. Useage

      1. The Files Involved.
            The  files  you  will  be  concerned  with  during  the
        conversion process are the following:

      main.CLA
          All  your  application .CLA files, especially the program
        module.

      lem.BIN
         All the .BIN files associated with the application.

      lem.CPY
         The LEM routine declarations.

      LEMGLUE.EXE
         The BIN conversion utility program.

      ???LMGLU.LIB
         The compiled interface modules.

      lem.CLA
         The generated clarion interface module.

            For future reference: "lem" is the  name  of  the  .BIN
        file, without the extension, and "main" is the file name of
        the  main  program  module,  without  the  extension,   and
        "module"  is  the  name  of an arbitrary application module
        without the extension.
            To convert a program that uses a BIN do the following:










        Step 0.

              Backup your 2.1 application.

        Step 1.
              Run LEMGLUE.EXE.  Name the BIN input file, the CPY 
          input file, and the interface output file.  The output
          file will be created, and will overwrite an existing
          file of the same name.

        Step 2.
             Handle Errors....

        Step 3.
              Convert your 2.1 application to 3.0 using CLACNV.EXE,
          compile it and remove all the syntax errors.  Delete the
          BINARY attribute from the MODULE statement in the MAP 
          reference to the LEM.  Ignore link errors that refer to 
          BIN functions.

        Step 4.
              You  will  need  an  editor  for this step.  Load the
          main.CLA and the lem.CLA  files  into  your  editor.  The
          lem.CLA  file contians a MAP MODULE structure and a local
          MAP.  There  is  a  comment  declaring  the  MAP   MODULE
          structure as:
              !*** Begin Global Map Reference
              Insert  a  copy  of  this entire MAP MODULE structure
          into the main  programs'  MAP  structure  where  the  BIN
          module  was  declared.  Remove  the  "INCLUDE('lem.CPY')"
          statements, if any, from the main.CLA,  as  well  as  any
          other old MAP references to the BIN routines.  Remove the
          Global  MAP  MODULE  structure  from  the  lem.CLA  file,
          leaving   only   the   local   MAP.   Important! add  the 
          statement "INIT_lem()" somewhere in the application  
          initialization code.  This  statement must be executed 
          before any of the functions in the lem LEM can be called.
              Finally, change the MEMBER parameter in line 1 of the 
          lem.CLA file to name the main program this glue code will
          be compiled into.

        Step 5
              Add the lem.CLA module to the project  system  as  an
          "External   Source   File"  and  %clapfx%LMGLU.LIB
          as an










          "External   OBJ/LIB   File".   Finally,   recompile   the
          application and test it.  Note, the lem.BIN file must now
          reside in the directory from  which  the  application  is
          executed,  or,  the flag switch "CLABIN=directory" may be
          used to direct the application to a  specific  directory.
          See  other  documentation  for  discussion of the COMMAND
          flags.

      2. Trouble to watch for.

       GROUPS or STRINGS produce syntax error "Parameter must be variable"
            As mentioned before, some parameter passing conventions
        may  be  out of sync when you execute the BIN calls.  These
        pertain primarily to STRINGS and  GROUPS  being  passed  by
        value, or by reference.  Because the converter has no way of
        knowing whether or not the parameter is to be passed
        by value or by address the assumption is made that it
        is passed by address.  Thus if the application calls 
        it by value the programmer may assume the function
        expects the parameter by value and can modify the 
        prototype accordingly.  If on the other hand the 
        parameter is declared passed by value no warning 
        would ever be given and the program would fail 
        inexplicably.

      3. Erros and solutions.


        CPY file xxx, NOT FOUND.
              The lem.CPY file is not in the directory  from  which
          LEM2CLA is run. If no .CPY file is available, one must be
          created.  Only the functionss need to be defined however,
          the .CPY file is not needed for procedures.

        Could Not Open Output File xxx
              Some  error  occured attempting to create the lem.CLA
          file.

        Could Not Read .BIN
              Some error occured attempting  to  read  the  lem.BIN
          file.

        Invalid .BIN file
              The lem.BIN file does not display the required header
          signature for

        Could Not Read Routine Descriptor in .BIN file
              The .BIN header may have declared more routines to be
          in the file than are actually there, or the file may have
          been truncated.

        Too Many Parameter In Procedure Definition
              The routine in  question,  requires  more  parameters
          than  LEMGLUE  is set up to handle.  Currently this value
          is 64.

        Could Not Read Parameter Descriptor in .BIN file
              The routine header may have declared more  parameters
          than  are  actually  there,  or  the  file  may have been
          truncated.










        Insufficient Memory

              LEM2CLA requires more available  memory  to  complete
          the   conversion.  See  discussion  of  memory  in  other
          documentation.

        Could not read .CPY file
              The lem.CPY file is  not  the  directory  from  which
          LEM2CLA is run.

        Function xxx Has No Return Type In .CPY
              A  function  xxx was defined in the .BIN file, but in
          the .CPY file it is declared as a PROCEDURE.  In order to
          complete   the   conversion,   declare  the  function  as
          returning LONG.  This return value should never be used.

        CPY Does Not Declare xxx File
              A function xxx was defined in the  .BIN  file,  which
          was  not  declared  in  the  .CPY  file.  The function is
          prabably not meant to be a public  function,  and  should
          never  be  called.  In  order to complete the conversion,
          declare the function in the  .CPY  file  as  returning  a
          LONG. Again, this function should never be called.

      4. Runtime errors

        xxx : Could Not Open .BIN File
              The  .BIN file could not be located by the "INIT_lem"
          function.  See Step 5 above.

        Could Not Read .BIN File
              Some disk error occured, the BIN file  could  not  be
          loaded.

        Call To Invalid or Uninitialized LEM
              The Clarion main program called a LEM function before
          it was  initialized.  The  "INIT_lem"  function  must  be
          called  prior to calling any of the functions in the LEM.
          eg: If the name of your .BIN is CHECKS.BIN, the  function
          to   call,   as   declared   in  the  Global  MAP  MODULE
          declaration, is "INIT_CHECKS()".

        Call To Non Existent LEM Routine
              The Clarion program is corrupted.

        LEM to Library Data Vector Not Supported
              The LEM  is  requesting  unsupported  data  from  the
          processor.  The negative of the given vector number may used 
        to identify the exact vector by indexing into the data vector 
        table defined in LEMGLUEA.A.  If you feel brave you might even 
        want to define it via a refence to some variable in your own 
        code!

        LEM to Library Function Vector Not Supported
              The   LEM   called  back  to  the  processor  for  an
          unsupported function.  The given vector number may be used to 
        identify the exact vector by indexing into the function vector table 
        defined in LEMGLUEA.A.  If you feel brave you might even want 
        to define it via a refence to some variable in your own code!


    D. Technical Tidbits

        ...
























































