Call

Syntax

   Call( ScriptFunctionName, parameter1, parameter2, ...)
or Call( ScriptFileName ! ScriptFunctionName, parameter1, parameter2, ...)
or Call( DLLFileName ! DLLFunctionName, parameter1, parameter2, ...)

Description

Call a function in an external script (e.g., Visual Basic Script of JavaScript) or DLL with any number of parameters.

Calling Scripts

A script is a text file containing user-defined functions written in a scripting language, such as Visual Basic Script (.vbs), JScript (.js), Perl (.pl), Python (.py), PHP (.php) or Ruby (.rb).  VBScript and JScript come with Windows and are always available, whereas other scripting languages must be installed by you on your computer before you can use them in WEAP.

WEAP will look in ScriptFileName for the function ScriptFunctionName.  As a convenience, if ScriptFileName is omitted, WEAP will look for a file called "functions.vbs" in the current area folder.  You can put commonly used functions into functions.vbs to make it easier to call them.  For example, two trivial examples:

Function Add(x,y)
Add = x + y
End Function

Function Multiply(x,y)
Multiply = x * y
end Function

Notice that each function starts with the keyword Function and ends with the Keywords End Function.  Function results are set by assigning values to the function name.  WEAP functions should always return numeric values (integer or floating point) and should always use numeric parameters.  Functions can have any number of parameters, but the burden is on the user to pass the correct number of parameters in a comma separated list in the Call statement.

The following example expressions in WEAP could be used to call these two functions:

Call(Add, 5, 4)
would return a value of 9

Call(Multiply, 5, 4)
would return a value of 20

An error will be reported if the number or type of parameters are incorrect, or if you call a function that does not exist in the script file.  

WEAP has its own built-in script editor that can be used to edit, interactively debug and run scripts.

Calling DLLs

A DLL is a Microsoft Windows "Dynamic Link Library" file that contains one or more functions. A DLL is a compiled executable program written in a standard programming language, such as C, Visual Basic or Delphi. The ability of WEAP to call DLL functions is very powerful, as it allows the user to add new functions or even complete models to WEAP.

The DLL function should expect a parameter that is an array of double precision numbers, and should return one double precision number as the result.   Note: When Delphi programs, such as WEAP, pass an array to a C program, Delphi automatically adds a parameter following the array which is the length of the array minus one (this is the index of the last element in the 0-based array).  For example, if the array has 5 elements, ArrayLengthMinusOne = 4.  Therefore, the C function must have two parameters: a pointer to a double array, and an integer which will be the array length minus one.

Examples

Call( C:\DLLTest.dll ! Sum, 1.5, -2.6, 3.0, 4.1, -4.2) ; will call a function called Sum in the DLL file c:\DLLTest.dll, passing it an array of 5 double precision numbers. (See C and Delphi source below)

Call( C:\DLLTest.dll ! Cos, month * 30) ; a Cosine wave, going from 30 degrees to 360 degrees over the year (See Delphi source below)

The parameters can include WEAP variables and functions, e.g.,

Call( ReservoirOperations.dll ! CalculateRelease,
    \Demand Sites\Agriculture North:Monthly Demand,
    PrevTSValue( \Supply and Resources\River\Weaping River\Reservoirs\Central Reservoir:Storage Volume[m^3] ) )

Sample C source code listing for test.c

Note: This can be compiled into Test.dll using a standard C compiler, such as the following free compilers: Tiny C, Microsoft Visual Studio Express, MinGW, GNU GCC, lcc-win, and Orange C.

#include <windows.h>

#define DLLEXPORT __declspec(dllexport)

DLLEXPORT double Sum(double *Parameters, int ArrayLengthMinusOne);

# When Delphi programs, such as WEAP, pass an array to a C program, Delphi automatically adds a parameter following the array which is the length of the array minus one (this is the index of the last element in the 0-based array).  For example, if the array has 5 elements, ArrayLengthMinusOne = 4.

DLLEXPORT double Sum(double *Parameters, int ArrayLengthMinusOne) {

  int i;

  double result;

  result = 0;

  for (i = 0; i <= ArrayLengthMinusOne; i++)
result += Parameters[i];

  return result;

}

Sample Delphi source code listing for test.dpr

Note: This can be compiled into Test.dll using the free Lazarus Delphi Compiler

library DLLTest;

{
Simple Delphi program for testing calling DLLs from WEAP
Example calls from WEAP
Call( C:\DLLTest.dll ! Sum, 1.5, -2.6, 3.0, 4.1, -4.2)
Call( C:\DLLTest.dll ! Cos, month * 30)
Call( C:\DLLTest.dll ! Sin, 90)
}

{$R *.res}

// Sum up all the parameters
function Sum(Parameters: array of double): double; stdcall;
var
i: integer;
begin
result := 0;

for i := 0 to Length(Parameters) - 1 do
  result := result + Parameters[i];
end;

const DegreeToRadianConversion = 2 * Pi / 360; // Convert from degrees to radians

// Cosine of an angle expressed in degrees.
function Cos(Parameters: array of double): double; stdcall;
begin
result := System.Cos(Parameters[0] * DegreeToRadianConversion);
end;

// Sine of an angle expressed in degrees.
function Sin(Parameters: array of double): double; stdcall;
begin
result := System.Sin(Parameters[0] * DegreeToRadianConversion);
end;


// These are the functions that can be called by WEAP or other programs
exports Sum, Cos, Sin;


begin
// nothing in the body
end.