Using DLL in Eloquence

14 Integrating C Functions (DLL)

Using DLL in Eloquence

You can use a DLL in Eloquence like a subprogram. You load it using LOAD DLL, call it with CALL DLL and terminate it with DEL DLL.

Example:

Subprogram: DLL:
LOAD SUB "SUBPG" LOAD DLL Subpg, 1024
CALL Numeric(A$,A) CALL DLL Subpg("Numeric", A$,A)
DEL SUB Numeric TO END DEL DLL Subpg

Subprogram:	DLL:
LOAD SUB "SUBPG"	LOAD DLL Subpg, 1024
CALL Numeric(A$,A)	CALL DLL Subpg("Numeric", A$,A)
DEL SUB Numeric TO END	DEL DLL Subpg

The following table illustrates the differences and similarities between a subprogram and a DLL.

Subprogram DLL
Programming Language: Eloquence C
Procedures Yes Yes
Functions Yes No
COM variables Yes No
Module-specific variables No Yes
File arguments Yes No
Variable arguments No Yes
Call to Eloquence Yes No
Input/Output to screen Yes No

	Subprogram	DLL
Programming Language:	Eloquence	C
Procedures	Yes	Yes
Functions	Yes	No
COM variables	Yes	No
Module-specific variables	No	Yes
File arguments	Yes	No
Variable arguments	No	Yes
Call to Eloquence	Yes	No
Input/Output to screen	Yes	No

The DLL is started from within Eloquence as a separate process.

Communication between Eloquence and the DLL process is realized using shared memory, which is a storage area that can be accessed simultaneously by several processes.

LOAD DLL starts the DLL process and initializes the shared memory. The DLL process now waits for a signal from Eloquence.

CALL DLL copies the arguments into shared memory and signals the DLL process that the arguments have been passed. Now control is passed to the DLL.

After the DLL process has finished processing, control is passed back to Eloquence.

DEL DLL terminates the DLL process and releases the shared memory.

The LOAD DLL Statement

The LOAD DLL statement starts a DLL process and assigns it to the given name.

The syntax is as follows:

LOAD DLL Name [,filename$], size

Name: the name the DLL will be referenced with. Note that this name must have an initial upper-case letter, in accordance with Eloquence syntax.
filename$: (optional). If present, specifies the file name of the DLL. If not present the file /opt/eloquence/dll/Name will be loaded.
size: specifies the size of the shared memory. The size of the shared memory depends on the number and size of the arguments.

Examples:

    LOAD DLL Sample, 512
    LOAD DLL Test, "TEST,SYSTEM", 1024

The first example starts the DLL /opt/eloquence/dll/Sample and creates a shared memory of 512 Bytes.

The second example starts the DLL Test, which is located in the file TEST in the directory specified by the volume name SYSTEM and creates a shared memory of 1024 Bytes.

A maximum of five DLL processes can be loaded.

Possible Error Messages:

56: File name or directory undefined or inaccessible
600: Unable to load DLL
601: Improper DLL memory size

The DEL DLL Statement

The DEL DLL statement terminates the DLL process specified by Name.

The syntax is as follows:

DEL DLL Name

Name: same name as used in the LOAD DLL statement. No runtime error occurs if this DLL doesn't exist.

Example:

   DEL DLL Sample

This terminates the DLL loaded with the name Sample.

The CALL DLL Statement

The CALL DLL statement starts the specified procedure of the DLL process.

The syntax is as follows:

CALL DLL Name( Proc$ [,arguments])

Name: same name as used in the LOAD DLL statement.
Proc$: name of the procedure
arguments: list of arguments to be passed to the DLL process. The arguments are passsed as if to a subprogramm. Files cannot be passed. Maximum number of arguments is 20.

Examples:

   CALL DLL Sample(P$,A$)
   CALL DLL Test("check", 1,"TEST",A$,A$(*),I,I(*))

The first example calls the procedure whose name is stored in P$ in the DLL Sample using the argument A$. The second example calls the procedure check of the DLL Test with the arguments 1, "TEST", A$, A$(*), I,I(*).

Possible Error Messages:

602: DLL not loaded
603: DLL memory overflow
604: DLL process not found
605: DLL return area destroyed
606: Number of arguments exceeds maximum

Shared Memory

The shared memory is required to exchange data between Eloquence and the DLL process.

The size of the area depends on the number and type of the arguments:

36 Bytes + 24 Bytes per argument.

Additional requirements per argument:

STRING: 4 Bytes + String length rounded up to next 4 byte boundary
INTEGER: 4 Bytes
DINTEGER: 4 Bytes
SHORT: 12 Bytes
REAL: 12 Bytes

Arrays require the above memory capacity per element

Eloquence Language Manual - 19 DEC 2002