[Previous] [Next]

XSLPchguserfunc

Purpose

Add or change a user function in an SLP problem after the problem has been input

Synopsis

int XPRS_CC XSLPchguserfunc(XSLPprob Prob, int nSLPUF, char *xName, 
               int *ArgType, int *ExeType, char *Param1, char *Param2, char *Param3);

Arguments

Prob  

The current SLP problem.

nSLPUF  

The number of the user function. This always counts from 1 and is not affected by the setting of XPRS_CSTYLE. A value of zero will create a new function.

xName  

Character string containing the null-terminated external name of the user function. Note that this is not the name used in written formulae, which is created by the XSLPaddnames function if required.

ArgType  

bitmap specifying existence and type of arguments:

Bits 0-2	Type of DVALUE. 0=omitted, 1=NULL, 3=DOUBLE, 4=VARIANT;
Bits 3-5	Type of ARGINFO. 0=omitted, 1=NULL, 2=INTEGER, 4=VARIANT;
Bits 6-8	Type of ARGNAME. 0=omitted, 4=VARIANT, 6=CHAR;
Bits 9-11	Type of RETNAME. 0=omitted, 4=VARIANT, 6=CHAR;
Bits 12-14	Type of DELTA. 0=omitted, 1=NULL, 3=DOUBLE, 4=VARIANT;
Bits 15-17	Type of RESULTS. 0=omitted, 1=NULL, 3=DOUBLE.

ExeType  

type of function:

Bits 0-2	determine the type of linkage: 1 = User library or DLL; 2 = Excel spreadsheet XLS; 3 = Excel macro XLF; 5 = MOSEL; 6 = VB; 7 = COM
Bits 3-7	re-evaluation and derivatives flags:
Bit 3-4	re-evaluation setting: 0: default; Bit 3 = 1: re-evaluation at each SLP iteration; Bit 4 = 1: re-evaluation when independent variables are outside tolerance;
Bit 5	RESERVED
Bit 6-7	derivatives setting: 0: default; Bit 6 = 1: tangential derivatives; Bit 7 = 1: forward derivatives
Bit 8	calling mechanism: 0= standard, 1=CDECL (Windows only)
Bit 9	instance setting: 0=standard, 1=function calls are grouped by instance
Bit 24	multi-valued function
Bit 28	non-differentiable function

Param1  

null-terminated character string for first parameter (FILE).

Param2  

null-terminated character string for second parameter (ITEM).

Param3  

null-terminated character string for third parameter (HEADER).

Example

Suppose we have the following user functions written in C in a library lib01:
Func1 which takes two arguments and returns two values
Func2 which takes one argument and returns the value and (optionally) the derivative of the function. Although the function is referred to as Func2 in the problem, we are actually using the function NewFunc2 from the library.

The following example adds the two functions to the SLP problem:

int nUF;

XSLPgetintattrib(Prob,XSLP_UFS,&nUF);
XSLPchguserfunc(Prob, 0, NULL, 023, 1, 
                "lib01", NULL, NULL);
XSLPchguserfunc(Prob, 0, "NewFunc2", 010023, 1,
                "lib01", NULL, NULL);

XSLPaddnames(Prob,XSLP_USERFUNCNAMES,"Func1\0Func2",
             nUF+1,nUF+2);

Note the use of zero as the number of the user function in order to create a new user function. A value of NULL for xName means that the internal and external function names are the same.

Further information

A NULL value for any of the arguments leaves the existing value (if any) unchanged. If the call is defining a new user function, a NULL value will leave the default value unchanged.

The following manifest constants are provided for setting evaluation and derivative bits in ExeType:
Setting bit 3: XSLP_RECALC
Setting bit 4: XSLP_TOLCALC
Setting bit 6: XSLP_2DERIVATIVE
Setting bit 7: XSLP_1DERIVATIVE
Setting bit 9: XSLP_INSTANCEFUNCTION
Setting bit 24: XSLP_MULTIVALUED
Setting bit 28: XSLP_NODERIVATIVES

If bit 9 (XSLP_INSTANCEFUNCTION) is set, then calls to the function will be grouped according to the argument list, so that the function is called only once for each unique set of arguments. This happens automatically if the function is "complicated" (see the section on "User function interface" for more details).

Bit 24 (XSLP_MULTIVALUED) does not have to be set if the function is multi-valued and it requires RETNAME, DELTA or RESULTS. It must be set if the function is multi-valued, does not use any of those arrays, and may be called directly by the user application using XSLPcalluserfunc.

If bit 28 (XSLP_NODERIVATIVES) is set, then formulae involving the function will always be evaluated using numerical derivatives.