LibFunc>module,function,resultvar[,[[ref:]var1][,[ref:]var2][,...][,[ref:]varn]]

 

Not supported in Macro Scheduler Lite.

 

LibFunc can be used to call DLL functions and is therefore an ideal way of extending the language using custom DLLs or for calling Win32 API functions.  (NB: Alternatively, for language extensions, create an ActiveX object and access it using VBScript).

 

LibFunc takes the following parameters:

 

module: the DLL module filename to load or a module handle created with a previous call to LibLoad

function: the name of the function in the DLL.

resultvar: numeric value returned by the function.

parameter list: See below.

 

You can specify as many parameters as needed by the DLL function.  To pass numeric parameters by reference precede the value with "ref:" (without the quotes).  See examples below.

 

As string variables are actually pointers to memory locations strings are effectively always passed by reference and can be modified by the DLL.  String buffer sizes are set to 255 characters by default.  To set the size of a string variable to some other value create a parmname_SIZE variable, where parmname is the name of the string variable being passed, set to the length required.  See window title example below.

 

LibFunc determines whether a variable is a numeric integer or a string automatically by looking at it's contents.  However, if you need to send a number as a string you can force it to be a string by preceeding the parameter with "str:" (without the quotes).

 

Note that LibFunc supports long integer and string types only.  LibFunc supports ANSI strings only.  For Unicode strings use LibFuncW.

 

As well as returning the function result in resultvar LibFunc creates new variables corresponding to each of the passed parameters with the format resultvar_n where n is the index of the parameter, starting from 1.  If the function changed the value of any of the parameters these new variables will contain the new value.  Otherwise they will contain the value passed.  E.g. if resultvar is set to "answer" and you specified three parameters LibFunc will return four variables called answer, answer_1, answer_2 and answer_3.  See examples.

 

Beware: When you pass data to DLLs you are passing references to memory areas.  If you send the wrong type of information or the wrong number of arguments you are likely to cause an access violation error in the DLL which may cause Macro Scheduler to crash.  This function is recommended for experienced developers only.

 

Abbreviation : Lib

See also: LibLoad, LibFree

 

Examples

 

Get Windows System Directory:

 

LibFunc>Kernel32,GetSystemDirectoryA,dir,buffer,255

MessageModal>System Directory: %dir_1%

 

Use ShellExec to open a file/run an application:

 

LibFunc>shell32,ShellExecuteA,r,0,open,notepad,,,1

 

Get free disk space on drive C:

 

LibFunc>kernel32,GetDiskFreeSpaceExA,spacefree,c:\,REF:0,REF:0,REF:0

Let>used=spacefree_3/1024

Let>free=spacefree_4/1024

MessageModal> Disk space used: %used%Kb %CRLF% Free space: %free%Kb

 

Display a system yes/no message box:

 

Let>YesNo=4

LibFunc>user32,MessageBoxA,r,0,Hello World,Message!,YesNo

If>r=6

  MessageModal>You Pressed Yes

else

  MessageModal>You Pressed No

endif

 

Use the system API Beep function to play sounds:

 

Let>k=200

Repeat>k

  LibFunc>kernel32,Beep,r,k,50

  Let>k=k+10

Until>k,1000

 

Run a function in a custom DLL:

 

LibFunc>C:\mydll\testdll.dll,ChangeText,r,hello

MessageModal>%r% %r_1%

 

Get Active Window Title:

 

Let>WIN_USEHANDLE=1

GetActiveWindow>win,x,y

LibFunc>user32,GetWindowTextLengthA,wtlen,win

Let>buffer_SIZE=wtlen

Let>wtlen=wtlen+1

LibFunc>user32,GetWindowTextA,gwt,win,buffer,wtlen

MessageModal>Window Text: %gwt_2%