User Function declaration in native languages

This section describes how to declare a user function in C, Fortran and so on. The general shape of the declaration is shown. Not all the possible arguments will necessarily be used by any particular function, and the actual arguments required will depend on the way the function is declared to Xpress NonLinear.

User function declaration in C

The XPRS_CC calling convention (equivalent to __stdcall under Windows) must be used for the function. For example:

type XPRS_CC MyFunc(double *InputValues, int *FunctionInfo,
                    char *InputNames, char *ReturnNames
                    double *Deltas, double *ReturnArray);

where type is double or double* depending on the nature of the function.

In C++, the function should be declared as having a standard C-style linkage. For example, with Microsoft C++ under Windows:

extern "C" type _declspec(dllexport) XPRS_CC
                    MyFunc(double *InputValues, int *FunctionInfo,
                    char *InputNames, char *ReturnNames
                    double *Deltas, double *ReturnArray);

If the function is placed in a library, the function name may need to be externalized. If the compiler adds "decoration" to the name of the function, the function may also need to be given an alias which is the original name. For example, with the Microsoft compiler, a definition file can be used, containing the following items:

EXPORTS
MyFunc=_MyFunc@12

where the name after the equals sign is the original function name preceded by an underscore and followed by the @ sign and the number of bytes in the arguments. As all arguments in Xpress NonLinear external function calls are pointers, each argument represents 4 bytes on a 32-bit platform, and 8 bytes on a 64-bit platform.

A user function can be included in the executable program which calls Xpress NonLinear. In such a case, the user function is declared as usual, but the address of the program is provided using XSLPchguserfuncaddress or XSLPsetuserfuncaddress. The same technique can also be used when the function has been loaded by the main program and, again, its address is already known.

The InputNames and ReturnNames arrays, if used, contain a sequence of character strings which are the names, each terminated by a null character.

Any argument omitted from the declaration in Xpress NonLinear will be omitted from the function call.

Any argument declared in Xpress NonLinear as of type NULL will generally be passed as a null pointer to the program.

User function declaration in Excel (spreadsheet)

A user function written in formulae in a spreadsheet does not have a declaration as such. Instead, the values of the arguments supplied are placed in the sheet named in the Xpress NonLinear declaration as follows:

Column A	InputValues
Column B	FunctionInfo
Column C	InputNames
Column D	ReturnNames
Column E	Deltas

The results are returned in the same sheet as follows:

Column I	Return values
Column J	Derivatives w.r.t. first required variable
Column K	Derivatives w.r.t. second required variable
...

An Excel macro can also be executed as part of the calculation. If one is required, its name is gives as Extname in the Xpress NonLinear declaration of the user function.

Any argument omitted from the declaration in Xpress NonLinear will be omitted from the function call.

Any argument declared in Xpress NonLinear as of type NULL or omitted from the declaration will leave an empty column.

User function declaration in VBA (Excel macro)

All arguments to VBA functions are passed as arrays of type Variant. This includes integer or double precision arrays, which are handled as Variant arrays of integers or doubles. The following style of function declaration should be used:

Function MyFunc ( InputValues() as Variant, FunctionInfo() as Variant, _
                  InputNames() as Variant, ReturnNames as Variant, _
                  Deltas as Variant(), ReturnArray as Variant()) as Variant

For compatibility with earlier versions of Xpress NonLinear, a return type of Double (or Double() for a multi-valued function) is also accepted. The return should be set to the value or to the array of values. For example:

	Dim myDouble as Double
	...
	MyFunc = myDouble

or

	Dim myDouble(10) as Double
	...
	MyFunc = myDouble

The return type is always Variant, regardless of whether the function returns one value or an array of values. The return should be set to the value or to the array of values as described in the VBA (Excel) section above.

All arrays are indexed from zero.

Any argument omitted from the declaration in Xpress NonLinear will be omitted from the function call.

Any argument declared in Xpress NonLinear as of type NULL will generally be passed as an empty Variant.

User function declaration in Visual Basic

All arguments to VB functions are passed as arrays of type Variant. This includes integer or double precision arrays, which are handled as Variant arrays of integers or doubles. The following style of function declaration should be used:

Public Function MyFunc ( InputValues() as Variant, FunctionInfo() as Variant,
                  InputNames() as Variant, ReturnNames as Variant, _
                  Deltas as Variant(), ReturnArray as Variant()) as Variant

The return type is always Variant, regardless of whether the function returns one value or an array of values. The return should be set to the value or to the array of values as described in the VBA (Excel) section above.

All arrays are indexed from zero.

Any argument omitted from the declaration in Xpress NonLinear will be omitted from the function call.

Any argument declared in Xpress NonLinear as of type NULL will generally be passed as an empty Variant.

User function declaration in COM

This example uses Visual Basic. All arguments to COM functions are passed as arrays of type Variant. This includes integer or double precision arrays, which are handled as Variant arrays of integers or doubles. The function must be stored in a class module, whose name will be needed to make up the PROGID for the function. The PROGID is typically of the form file.class where file is the name of the ActiveX DLL which has been created, and class is the name of the class module in which the function has been stored. If you are not sure of the name, check the registry. The following style of function declaration should be used:

Public Function MyFunc ( InputValues() as Variant, FunctionInfo() as Variant,
                  InputNames() as Variant, ReturnNames as Variant, _
                  Deltas as Variant(), ReturnArray as Variant()) as Variant

The return type is always Variant, regardless of whether the function returns one value or an array of values. The return should be set to the value or to the array of values as described in the VBA (Excel) section above.

All arrays are indexed from zero.

Any argument omitted from the declaration in Xpress NonLinear will be omitted from the function call.

Any argument declared in Xpress NonLinear as of type NULL will generally be passed as an empty Variant.

User function declaration in MOSEL

A simple function taking one or more input values and returning a single result can be declared in Mosel using the following form:

function MyFunc (InputValues:array(aRange:range) of real, Num:integer) : real

where Num will hold the number of values in the array InputValues.
The single result is placed in the reserved returned variable.

If the function returns more than one value, or calculates derivatives, then the full form of the function is used:

function MyFunc (InputValues:array(vRange:range) of real,
                 FunctionInfo:(array(fRange:range) of integer,
                 InputNames:(array(iRange:range) of string,
                 ReturnNames:(array(rRange:range) of string,
                 Deltas:(array(dRange:range) of real,
                 ReturnArray:(array(aRange:range) of real) : real

The SLPDATA declaration of the function references an array (the transfer array) which is a string array containing the names of the arrays used as arguments to the function.

The results are placed in ReturnArray and the function should return zero for success or 1 for failure.

For more details about user functions in Mosel, see the Xpress Mosel SLP Reference Manual.