9.52 DLL
Þ Note: Built-In Function Rules.
Allows processing within a standard DLL (Dynamic Link Library) object to be invoked from a LANSA component or function.
This is a generic interface to operating system DLL entry points. It may not be the most appropriate interface for specialized requirements. For specialized requirements please investigate creating your own Built-In Function. Refer to Creating Your Own Built-In Functions in the for more details of this facility.
For use with
|
Arguments
|
Return Values
|
Technical Notes
- It is obvious, but it needs to be said. By using this Built-In Function you are introducing an operating system dependency into your function.
You, the application builder, are totally responsible for doing this, and there is no guarantee, expressed or implied, that anything you do via this Built-In Function is in any way portable across different operating systems (or even versions of the same operating system).
- The DLL alias name and entry point alias name must be alphanumeric literals as the values that they specify must be determinable at compile time.
- Before a DLL can be used it must be defined in file X_USEDLL.DAT in the X_LANSA\SOURCE directory. This file provides details of the DLL and its entry points and maps alias names to real names. The alias and real name facility has been provided to:
- Provide a level of isolation between the RDML function and the real DLL. For example, you can change the name of the real DLL being used without having to change code in your RDML functions (but you will have to recompile them as the real name is referenced in the generated C code).
- To allow for RDML code that is easier to read. For example, the Crystal Reports DLL is called "CRPE", but when given an alias name of "CrystalReports" the resulting RDML code is much easier to understand. The same logic applies to entry point names.
The X_USEDLL.DAT Definition File
The X_USEDLL.DAT definition file defines the characteristics of all DLLs that can be used by the DLL Built-In Function. The following should be read and understood before attempting to create or alter this file or use this Built-In Function:
- It is an optional file. When present it must reside in the X_LANSA\SOURCE directory.
- It is only required on, and used by, development environments during code generation. Thus changes to the content of the file may require the (re)generation and (re)compilation of RDML functions that use DLLs affected by the changes.
- There is no need for this file to exist in execution environments.
- No DLL can have more than 256 entry points defined for it.
- This file is a simple keyword definition style file that can be edited with most source editors. The file is laid out as a series of keywords (which must begin in column 1 of the record, and only one keyword per line may be specified):
|
As an example of the content of this file, consider the following:
* --------------------------------------------------
* Example of defining Crystal Report DLL entry points
* ---------------------------------------------------
DLLNAM=CRPE
DLLALS=CrystalReports
*
ENTNAM=PEOpenEngine
ENTALS=OpenEngine
ENTSKL=CRPE0001.S
*
ENTNAM=PECloseEngine
ENTALS=CloseEngine
ENTSKL=CRPE0002.S
*
ENTNAM=PEPrintReport
ENTALS=PrintReport
ENTSKL=CRPE0003.S
*
ENTNAM=PEGetVersion
ENTALS=GetVersion
ENTSKL=CRPE0004.S
Here you can see the definitions for the Crystal Reports DLL named CRPE. It has four entry point aliases called OpenEngine, CloseEngine, PrintReport and GetVersion. The skeleton / template code for invoking this DLL and the entry points is to be found in the ...\X_LANSA\SOURCE directory in files CRPE0001.S, CRPE0002.S, CRPE0003.S and CRPE0004.S respectively. The skeleton code defines how the DLL is loaded, what the real entry point names are, how Built-In Function arguments are mapped to entry point arguments, how return codes and return values are handled, etc.
When setting up your own skeleton files / templates please follow these guidelines:
- Copy a shipped example and use it as a starting point.
- Always place the file in the ....\X_LANSA\SOURCE directory and make a backup copy.
- Do not use the file suffix .S, which is reserved so the Visual LANSA install/upgrade procedures can identify its own, shipped skeletons and replace them. If you use suffix .S then your files will be deleted the next time that you install/upgrade.
The DLL may need to be copied into the X_LANSA/EXECUTE directory for the application to be executed properly. For example, CRPE32.DLL has to be copied into the X_LANSA/EXECUTE directory.
At your development site, you need to decide on a convention for mapping this Built-In Function's arguments to the actual DLL entry point arguments. The convention you adopt is implemented in the skeleton/template code associated with each DLL entry point.
The skeleton template file supplied was used because it supports:
- Variable argument lists and default values for arguments that the caller has not passed.
- Variable and optional return values.
- The ability to add new arguments or return values at any time, without the need to modify or even recompile any existing caller of the DLL entry point.
- The ability to handle all calling conventions and pointer conversion requirements and, cleanly support multiple operating systems via one simple interface.
- The ability to hide the complexity of DLL loading and entry point resolution from the RDML level programming interface.
- Performance appropriate for the high level of programming used in the LANSA RDML language.
For example, the Crystal Reports entry points use the following parameter and return value conventions in their shipped format:
|