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