home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Media Share 9
/
MEDIASHARE_09.ISO
/
clarion
/
lemglue.zip
/
LEMGLUE.TXT
< prev
next >
Wrap
Text File
|
1992-04-01
|
14KB
|
463 lines
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 long 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.
LEM2CLA.EXE
The BIN conversion utility program.
LEMGLUE.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.
Convert your 2.1 application to 3.0 using CLACNV.EXE,
compile it and remove all the systax errors. Ignore link
errors that refer to BIN functions.
Step 2.
Accumulate the following files in a directory:
main.CLA
lem.BIN
lem.CPY
LEM2CLA.EXE
LEMGLUE.LIB
Step 3.
!WARNING!
If you have a module.CLA with the same name as
lem.BIN rename one or the other. LEM2CLA, when
successful, will CREATE lem.CLA.
NOTE:
lem.BIN must have the same primary name as lem.CPY.
eg: CHECK.BIN and CHECK.CPY
From the DOS command line, enter:
LEM2CLA lem main
If successful, this will create a lem.CLA file in the
current directory. If not successful, see the section on
Trouble to watch for.
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. 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.
Step 5
Add the lem.CLA module to the project system as an
"External Source File" and the LEMGLUE.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 don't recieve expected values
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. These settings must be "intuited",
or guessed at, and tweaked manually in the prototypes for
the lem procedures in the main MODULE MAP.
3. Erros and solutions.
BIN file xxx, NOT FOUND.
The lem.BIN file is not in the directory from which
LEM2CLA is run.
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.
LEM to Library Function Vector Not Supported
The LEM called back to the processor for an
unsupported function.
D. Technical Tidbits
To approach a solution, we limit ourselves to the
activities of entering, exiting, and the passage of parameter
values between 3.0 and the old .BIN routines. Given that
this is achievable, we are left with the problem of call
backs from the BIN to the processor. To address entry and
return of BIN routines, I supplied translation code