#RUNDLL (execute DLL procedure) 

Top  Previous  Next

 

 

#RUNDLL( library, procedure [, parameter ] ) [,

| RETAIN | ]

[, PASCAL ] [, WIN32 ]

 

 

| RELEASE |

 

#RUNDLL

Executes a procedure from any Windows-standard Dynamic Link Library (.DLL).

library

A string constant containing the name of the .DLL file, including the extension.

procedure

A string constant containing the name of the procedure in the DLL file to execute.

parameter

A string constant or expression containing a single parameter to pass to the procedure.

RETAIN

Specifies that the library stays in memory after the procedure has completed execution.

RELEASE

Specifies that the library is unloaded from memory after the procedure has completed execution.

PASCAL

Specifies that the address only of a parameter string is passed.

WIN32

Specifies that the library is a 32-bit DLL. Deprecated and ignored if present in Clarion 7 versions or higher.

The #RUNDLL statement executes the specified procedure from the specified library. The library .DLL is dynamically loaded before the procedure executes and unloaded after, unless the RETAIN attribute is specified.

If the RETAIN attribute is specified, another #RUNDLL statement with the RELEASE attribute and naming the same library must follow so that the .DLL is unloaded from memory. Failure to unload the .DLL can result in memory leaks. The RETAIN and RELEASE attributes can be nested as long as the #RUNDLL statements match up.

If a parameter is named, then the procedure must accept a single *CSTRING parameter (only). If no parameter is named, then the procedure must not accept any parameters. In either case, the procedure cannot return a value. If the parameter named is a single-valued user-defined symbol, then any changes to the passed parameter's value in the called procedure are reflected in that parameter symbol. If the called function changes the value of the passed string, the new value cannot exceed 10000 characters (including the terminating '<0>').

Example:

!A .DLL 'Services.DLL' contains these two procedures:

SoundBeep PROCEDURE

CODE

BEEP

 

AskForName PROCEDURE(*CSTRING Name)

Window  WINDOW('Enter Name),AT(,,260,100),SYSTEM,GRAY,AUTO

        ENTRY(@s20),AT(4,4),USE(Name)

        BUTTON('OK'),AT(200,4),USE(?Ok),STD(STD:Close)

       END

CODE

OPEN(Window)

ACCEPT

END

 

! The Template code that calls the procedures in Services.DLL:

#DECLARE (%UserName)

#SET (%UserName, 'Unknown')

#RUNDLL ('Services.DLL', 'SoundBeep'),RETAIN       !Use RETAIN to improve performance

#RUNDLL ('Services.DLL', 'AskForName', %UserName)

#RUNDLL ('Services.DLL', 'SoundBeep'),RELEASE      !RELEASE matches the RETAIN