9.52 DLL

Note: Built-In Function Rules     Usage Options

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 Create Your Own Built-In Functions.

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Alias name of DLL to be invoked. 1 32     2 A Req Alias name of function (i.e. entry point) to be invoked. 1 32     3-20 X Opt User defined real or logical arguments to be passed to the DLL entry points. 1 Unlimited

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Return Code "OK" = Completed okay. "ER" = Error detected. 2 2     2 A Opt Error message text 1 256     3-20 X Opt User defined real or logical return values from the DLL entry point. 1 Unlimited

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):

Keyword Meaning * Line is a comment DLLNAM= Name of the real (ie: operating system level) DLL file without any form of suffix. DLLALS= The alias name for this DLL that is to be used in RDML functions. Up to 32 characters may be specified. This name must be unique within the definition file and is not case sensitive. The DLLNAM= must precede DLLALS=. ENTNAM= Name of the real (ie: operating system level) DLL entry point. This name is case sensitive in most operating systems. This name should be unique within the current DLL definition. ENTALS= The alias name for a DLL entry point that is to be used in RDML functions Up to 32 characters may be specified. This name must be unique within the current DLL and is not case sensitive. The ENTNAM= must precede ENTALS=. ENTSKL= Specifies the name of the skeleton file (including the suffix) that defines the required C code to execute the DLL entry point. This code is used as a template to generate C code to invoke the DLL entry point. Please refer to shipped samples / examples for fully commented examples of how to produce such a template. All template files must reside in the X_LANSA/SOURCE directory. The ENTNAM= must precede ENTSKL=.

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:

DLL Alias Entry Point Alias Arguments And Return Values CrystalReports OpenEngine Ret 1 Is the OK or ER return code and it is optional. CrystalReports CloseEngine Ret 1 Is the OK or ER return code and it is optional. CrystalReports PrintReport Arg 3 Is the report name and it is required. If not specified it will default to a null string causing a "not found" error. Arg 4 Is the print report option and it is optional. It should be Y or N. It defaults to Y. Arg 5 Is the show in window option and it is optional. It should be Y or N. It defaults to N. Arg 6 Is the window title and it is optional. It defaults to a null string. Ret 1 Is the OK or ER return code. CrystalReports GetVersion Ret 1 Is the OK or ER return code and it is optional. Ret 2 Is the major version number and it is optional. Ret 3 Is the minor version number, and is optional.