Navigation: Templates > Template Language Reference > Complete Alpha Listing >====== #RUNDLL (execute DLL procedure)  ====== |    |
| #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