Overview 
Documentation 
New in 1.4

Trial download

XFuncs allows to use and insert external scripts completely compatible with xbase++ with ease inaccessible earlier. You can call from the program functions described in scripts as if they have been included in .exe file. Also all functions included in your program are callable from scripts. Index Initialization How to declare external function Filename extention of script files How to run script function Manual run How to replace function from exe to function from script Meaning of MAIN() function in script file How xFuncs search script (.prg) file How xFuncs search include (.ch) file Full list of vars and methods in xFuncs() object What is ULink? How to install ULink Known problems

you can easy call scripts from your application, call application from scripts or call scripts from scripts

Initialization of XFuncs

Insert this line somewhere in your program's start-up:

filepath - path of your scripts location. By default, this is a current path where ::install() was  called. This value stored in xFuncs():rootPath.
par1..parN - parameters for script function start(). You can create script file (start.prg) with declared start() (or Main()) function and this script will be automatically called after initialization of XFuncs.

How to declare external function (xFunc)

There is three common ways to declare external function.

• First scenario: required function is never called directly from program, only by macro.
  (For example, if macro stored in database and runs depends of situation)

  In that scenario no need to declare.

• Second scenario: required function is called directly from program and ULINK is not used.

You can declare function somewhere in your program by XFUNC <funcname>[(pars..)] command:

#include "xfuncs.ch" XFUNC myUdf XFUNC myUdf2() XFUNC myUdf3(p1,p2)

• Third scenario: required function is called directly from program and ULINK is used.

ULink is replacement of ALink. It automatically create call-bodies of external functions. more>
In that scenario no need to declare.

 

Filename extention of script files

By default, extention of script files is ".prg". To change this value for example to ".udf" do:

How to run script function

To run script function just define call to it. This call all the same as call to function linked in program. All other work, to find script file, compile and run it, XFuncs do in background, without any additional code.

For example, if you define script function MyUdfFunc in file MyUdfFunc.prg, just type:

   MyUdfFunc()

Note: function Main() have special meaning. more>

Manual run

To manual compile and run, call:

funcName - name of function
par1..parN - parameters of function
retVal - return value of called function

Another call with parameters stored in array:

funcName - name of function
parA- array of parameters
retVal - return value of called function

NOTE: If program have build-in functions with same names as functions in script, that build-in functions automatic replaces to script functions. Next calls to that functions always run script functions.

How to replace function from exe to function from script

Sometimes may be very useful to replace function builded in exe to function from script.
This is possible with two ways: make build-in function invisible, or overload this function with manual (or automatic) load script command.

• There is a command to make build-in function invisible:
  
  

  xFuncs():undefineFunc(funcName)

  
  Next call to funcName will be call to script function with same name.
  
• To manual load script into memory, just do:
  
  

  xFuncs():load(funcName|scriptFilename)

Meaning of MAIN() function in script file

Function Main() was special meaning in script file. When you try to call function with name coincided with script filename and this function do not defined in script and Main() is defined, Main() will be called. In other words, you can call Main() function by call to function with name of script file.

For example, if MyUdf.prg do not contains MyUdf(), but contains Main(), if you call MyUdf(), Main() will be called.

This section explains how XFuncs search script (.prg) file

By name of called function, in directory and subdirectories defined in xFuncs():rootPath.
For example, if you call function named MyUdfFunc, file MyUdfFunc.prg is searched in directory and all subdirectories of ::rootPath.

NOTE: Subdirectories will be checked in alphabetical order.

How XFuncs search include (.ch) file

XFuncs search an include file in next order:

• path of source file where include happens.
• ::rootPath+"INCLUDE\"
• ::rootPath+"CH\"
• ::rootPath
• and contents of SET INCLUDE=

Full list of vars and methods in xFuncs() object

xFuncs() is an object to manage xFuncs engine.

::install(path)

Initializes xFuncs and setup origin path of script files (::rootPath).

::rootPath

Root path of script files.

::fileExt

Variable contains default filename extention of scripts. By default this is ".prg".

::run(funcname[,par1..parN]) -> result of run
::runA(funcname[,parA]) -> result of run

Manual run of script function.

::load(funcname|scriptname)

Manual load script in memory. Also, all build-in functions with same name as in script file will be overloaded.

::editor

Variable to define editor. If editor an external program, just define filename to ::editor. For use your own editor, define codeblock (first par is filename to edit). Default value is "notepad.exe".

::edit(funcname|scriptname)

Edit script.

::getFilename(funcname) -> script filename

Return name of script file contains defined function.

::undefineFunc(funcname)

Undefines (disables) any function stored in .exe or .dll. Next call to this function will run script function or raise "Function is not declared" error.

::redefineFunc(funcnameFrom,funcnameTo)

Redefines (replaces) one function to another. Next call to funcnameFrom will run funcnameTo.

::restoreFunc(funcname)

Restore state of funcname function if it was undefined or redefined before.

What is ULink?

ULink is replacement of ALink. Unlike Clipper, Alaska do not allow calls to undeclared function. There is special option for ALink (/force:unresolved) to create exe-file even if function is not declared, but when program calls this undeclared function, application crashes. In Clipper just "Function is not declared" error raised. Main goal of Ulink is do same thing in Alaska Xbase++. ULink runs ALink, then analyze output file and if undeclared functions is found, creates file unres.prg, compile it, add it to link script and finally rerun ALink.

How to install ULink?

The installation of ULink is very simple. Look into your .xpj file (usually project.xpj) and replace:

Known problems

In compiler:

• The = assignment do not work yet. For assignment always use := instead of =.

In preprocessor:

• Nested optional clause [] do not supported.
• Repeating replacement clause do not supported.

In runtime:

• <threadObject>:start("funcname") may do not work if funcname placed in script. Please, declare this function by XFUNC <funcname> command or use codeblock instead.

Please note, this problems will be fixed in nearest versions of XFuncs.

©2006 Eleus Software