calling 32-bit nag c dll functions from visual basic
TRANSCRIPT
Calling ���bit NAG C DLLfunctions from Visual Basic
George Levy� NAG Ltd� Oxford
Abstract
Calling NAG routines from Visual Basic �or Excel� can provide a convenient wayquickly to develop graphical user interfaces and packages that use mathematical routines�The aim of this report is to show how the complete range of NAG C DLL routines canbe called directly from Visual Basic� and thus allow programmers�package buildersmaximum �exibility when incorporating calls to NAG routines into their Visual Basiccode�
Keywords DLLs Visual Basic Excel Visual C��
� Introduction
The PC Windows environment is constructed so that all applications make calls to DynamicLink Libraries �DLLs�� These DLLs may contain system library routines provided by aparticular computer vendor �e�g�� the DLLs for Windows �� supplied by Microsoft� or maybe customized third party DLLs which provide a set of specialised functions �e�g�� graphical�mathematical� text processing etc��
NAG has developed ��bit mathematical DLLs containing the routines in its Fortran and C numerical libraries �� � �� � It is envisaged that these routines will be mainly used bymathematical�scienti�c programmers who use Visual C��� Fortran PowerStation or VisualBasic to build their applications�
In particular� calling NAG routines from Visual Basic �or Excel �� � can provide a convenient way quickly to develop graphical user interfaces and packages that use mathematicalroutines� These interfaces� which may use dialog boxes� menus etc� are simple to use anddo not require the enduser to have any knowledge of the underlying DLL routine� or evencomputer languages such as Fortran � C and Visual Basic �� � �� �
This report is intended for Visual Basic programmers�package builders� and is concernedwith the issues involved in calling the NAG C DLL routines from Visual Basic�
The main problems associated with using the DLL routines are
� Data type matching
� Function declarations
� Null pointers
� Function arguments
� Twodimensional array arguments
� Allocation of storage
� Software limitations
One method of dealing with these issues is to do most of the programming in C and use anauxiliary DLL to pass the results back to Visual Basic� This has the disadvantage that� sincethe NAG C DLL routines cannot be accessed directly from Visual Basic� minor variationsto routine arguments may require the auxiliary DLL to be completely rebuilt�
Here we use an alternative approach and illustrate how the full range of C Library routinescan be called directly from Visual Basic� and thus give programmers maximum �exibilitywhen using the NAG C DLL�
A rudimentary understanding of pointers is required and� in certain circumstances� an auxiliary DLL needs to be built �template C code is provided for this��
�
Appendix C contains Visual Basic example code fragments which have been tested �fromWindows ��� using both Excel �� and Visual Basic ����
� Data type matching
This section considers the Visual Basic data types required to match those which occur inthe routine argument lists of a ���bit� NAG C DLL� �More detail concerning data typescan be found in the NAG C Library manuals �� ��
Fundamental types
A brief summary of the fundamental types is�
C types Size in bytes Visual Basic types
char � String � �
Integer Long
Boolean Long
int Long
double Double
In addition the NAG de�ned type Complex is�
typedef struct fdouble re�im�g Complex�
Boolean � enumeration types
In Visual Basic all Boolean or enumeration variables should be declared as type Long� Forexample the C code�
typedef enum �Nag�MeanInclude� Nag�MeanZero� Nag�IncludeMean�
typedef enum �Nag�RK����� Nag�RK����� Nag�RK� ��� Nag�RK�
Nag�IncludeMean mean�
Nag�RK rk�
Boolean printit� stopit�
mean Nag�MeanZero�
mean Nag�MeanInclude�
printit TRUE�
stopit FALSE�
rk Nag�RK� ���
rk Nag�RK����
can be written in Visual Basic as�
Dim mean As Long
Dim rk As Long
Dim printit As Long
Dim stopit As Long
mean
mean �
printit
�
stopit �
rk �
rk
where FALSE � � and TRUE � �� The above example illustrates that� by default� enumerators in a given C enumeration type declaration start at zero and increase by � as thedeclaration is read from left to right� However� if a given enumerator is assigned a valuethen subsequent enumerators continue the progression from the assigned value�
Structures
Many of the DLL routines use structures in their argument lists� Sometimes� for examplein the d�� and e�� chapters� these structures are rather complicated and may contain otherstructures� When the structure is relatively simple it is often convenient to de�ne a VisualBasic userde�ned type and then make a direct call to the DLL routine� Complicatedstructures are most easily dealt with by the use of an auxiliary DLL �this is illustrated inthe Optimize example in Appendix C��
A structure that is required by nearly all of the routines is the type NagError� This isde�ned as�
typedef struct fint code�Boolean print�char message� ����void ��handler��char�� int��char���Integer errnum�
g NagError�
The corresponding Visual Basic userde�ned type is�
Type NagErrorType
code As Longprintm As LongMessage� ��� As String � �
handler As Longerrnum As Long
End Type
where both int� Integer and Boolean types have been replaced by Long and the pointerto the handler function has been replaced by a structure member of type Long�
As another example the type Nag Spline �used by routines e��bac and e��bbc� is de�nedas�
typedef struct fInteger n�double �lamda�double �c�Integer init��Integer init��
g Nag Spline�
�
The corresponding Visual Basic userde�ned type is�
Type NagSpline
n As Longlamda As Longc As Longinit� As Longinit� As Long
End Type
where both pointers to type double have been replaced by integers of type Long�
� Function declarations
The C DLL routines are called by using the following syntax�
Declare Function name Lib �library name� Alias �decorated name� �arguments� As return type
or
Declare Sub name Lib �library name� Alias �decorated name� �arguments�
The routine arguments can be obtained from the appropriate NAG header �le and the�decorated name� is generated from the DLL routine name using the following convention�
An underscore � � is pre�xed to the routine name� The name is followed by the atsign��� character� followed by the number of bytes in the argument list� Appendix A lists thedecorated names for the functions exported from the NAG C DLL�
For instance the ANSI C declarations for routines s agc and g�aac are�
double s agc�double x� NagError �fail��
void g�aac�Integer n� double x��� double wt��� Integer �nvalid�
double �xmean� double �xsd� double �xskew� double �xkurt�
double �xmin� double �xmax� double �wsum� NagError �fail��
and they would be declared in Visual Basic as�
Declare Function s agc Lib �nagcl���noopt� Alias ��s agc��� �ByVal x As Double� �
ifail As NagErrorType� As Double
and
Declare Sub g�aac Lib �nagcl���noopt�dll� Alias ��g�aac���� �ByVal n As Long� �
x As Double� wt As double� nvalid As Long� xmean As Double� xsd As Double� �
xskew As Double� xkurt As Double� xmin As Double� xmax As Double� wsum As Double� �
ifail As NagErrorType�
In C� pointers are used to pass arguments by reference �e�g�� double �xsd� Integer �nvalid�double x��� etc�� here the notation �� is used to denote an array argument� When argumentsare passed by value in C the syntax type variable name �e�g�� Integer n� double x� etc� isused�
In Visual Basic� by default� all arguments are passed by reference� the keyword ByVal isrequired to pass an argument by value�
�
� Null pointers
Many of the NAG C Library routines make use of null pointers to indicate that an argumentis to be ignored and default action is to be taken�
For example C routine g��aac has a pointer argument wt which allows the routine to performstatistical computations involving weighted data� If this argument is set to the null pointerthen unweighted calculations are performed� all the weights are assumed to be �� In VisualBasic this can be accomplished by declaring g��aac as follows�
Declare Sub g�aac Lib �nagcl���noopt�dll� Alias ��g�aac���� �ByVal n As Long� �
x As Double� ByVal wt As Long� nvalid As Long� xmean As Double� xsd As Double� �
xskew As Double� xkurt As Double� xmin As Double� xmax As Double� �
wsum As Double� ifail As NagErrorType�
where the declaration wt As Long �instead of wt As double� has been used to allow thisargument to be used as a pointer� The routine calls
Call g�aac�n� x���� ByVal ��� nvalid� xmean� xsd� xskew� xkurt� xmin� xmax� wsum� pfail�
Call g�aac�n� x���� �� nvalid� xmean� xsd� xskew� xkurt� xmin� xmax� wsum� pfail�
are both valid and result in unweighted calculations being performed�
The use of null pointers to indicate default behaviour can also be accomplished when theroutines have function arguments� For example routine d��ejc has the function argumentsfcn� pederv� g and output� and an ANSI C function declaration�
d��ejc �Integer neq� NAG�D��EJC�FUN fcn� NAG�D��EJC�PFUN pederv� double �t� double y���
double tend� double tol� Nag�ErrorControl err�c� NAG�D��EJC�OUTFUN output�
NAG�D��EJC�GFUN g� Nag�User �comm� NagError �fail��
If it is declared in Visual Basic as�
Declare Sub d��ejc Lib �nagcl���noopt�dll� Alias ��d��ejc���� �ByVal neq As Long� �
ByVal ptr�fcn As Long� ByVal ptr�pederv As Long� x As Double� y As Double� �
ByVal xend As Double� ByVal tol As Double� ByVal err�c As Long� �
ByVal ptr�output As Long� ByVal ptr�g As Long� comm As Nag�User� �
ifail As NagErrorType�
then the calls
ptr d��ejc fcn
Call d��ejc�neq� ptr� ByVal ��� x� y���� xend� tol� err c� ByVal ���
ByVal ��� comm� pfail�
Call d��ejc�neq� ptr� �� x� y���� xend� tol� err c� �� �� comm� pfail�
both result in the internal evaluation of the Jacobian pederv� The next section gives moredetail concerning function arguments� the ODE example section illustrates the use of theroutine d��ejc�
�
� Function arguments
In contrast to C� Visual Basic procedures are not allowed to have function arguments� Thislimitation creates a problem when using and declaring DLL routines that require functionarguments �these routines are mainly in the d and e chapters of the NAG C Library�� Asolution to this problem is to create an auxiliary DLL which both de�nes the requiredfunction arguments and also exports pointers to them� These function pointers can thenbe used in the routine argument lists of DLL procedures called from Visual Basic� TheVisual Basic code fragments and auxiliary DLL template C code for the ODE� Optimizeand Integrate examples given in Appendix C illustrate this�
� Two�dimensional array arguments
In Visual Basic multidimensional arrays are stored by columns �as in Fortran� rather thanby rows� which is the C convention� This means that care must be taken when a DLLroutine has matrix �twodimensional array� arguments�
For example� assume that a �by� matrix
A �
�B�
�� ���� ���� ��
�CA
is stored in a Visual Basic �dimensional array a in the natural manner� as in the followingcode fragment�
Dim a����� As Double
a����� � ��
a����� � ��
a����� � ��
a����� � ��
a����� � ��
a����� � ��
The array a consists of � elements stored in column order� as follows�
�� �� �� �� �� ��
However� routines in the NAG C DLL follow the standard C convention that �dimensionalarrays are stored in row order� Suppose the array a were passed to a NAG C routine �f��wec�say� as in the SVD example in Appendix C��
Call f��wec�����a������ �
where the �rst two arguments specify the numbers of rows and columns in the matrix� Theroutine would treat the array as representing a �by� matrix stored in row order�
�B�
�� ���� ���� ��
�CA
which is not the intended matrix A�
One solution �which is used in Appendix C� is to store the matrix in a �dimensional arraya�� with the element ai�j stored in a���i���tda�j��� where tda is the trailing dimensionof the matrix �in this case ���
Dim a�� � As Double
Dim tda As Long
tda � �
a���� � ��
a���� � ��
a���� � ��
a���� � ��
a���� � ��
a�� � � ��
Call f��wec�����a�����tda �
Another solution is to store the transpose of the matrix A in a �dimensional array at� withtda now being the leading dimension of the array at�
Dim at����� As Double
Dim tda As Long
tda � �
at����� � ��
at����� � ��
at����� � ��
at����� � ��
at����� � ��
at����� � ��
Call f��wec�����at������tda� �
The Visual Basic array at can be larger than is needed to store the �by� matrix AT � inorder that the C routine accesses the correct array elements it is essential that tda is set tothe correct value�
�
Dim at��� � As Double
Dim tda As Long
tda � �
Call f��wec�����at������tda� �
� Allocation of storage
The DLL utility routines x��bec and x��bfc have been provided to facilitate pointer manipulation from within Visual Basic� their Visual Basic declarations are�
Declare Sub set pointer Lib �nagcl�� noopt�dll� Alias
� x��bec��� �ptr As Long� ar As Double� n As Long�
Declare Sub get pointer Lib �nagcl�� noopt�dll� Alias
� x��bfc��� �ptr As Long� ar As Double� n As Long�
The routine set pointer allocates �n bytes of internal storage to the pointer ptr and copiesn elements �of type double� from the Visual Basic array ar�
The routine get pointer copies n elements from the internal memory associated withpointer ptr� to the Visual Basic array ar �of type double��
A further utility routine x��bdc is used to free the memory allocated by x��bec� it can bedeclared as�
Declare Sub free Lib �nagcl�� noopt� Alias � x��bdc��� �ptr As Long�
The use of set pointer can be illustrated by slightly modifying the example given in thesection on null pointers� In the following code extract the �rst call to g��aac uses theweights supplied in the array wt� while the second results in unweighted computations�
set pointer�ptr�wt����n�
Call g�aac�n� x���� ptr� nvalid� xmean� xsd� xskew� xkurt� xmin� xmax� wsum� pfail�
ptr �
Call g�aac�n� x���� ptr� nvalid� xmean� xsd� xskew� xkurt� xmin� xmax� wsum� pfail�
The Spline example� in Appendix C� illustrates the use of both get pointer and set pointer
for variable assignment and retrieval within a structure of type Nag Spline�
Software limitations
It is recommended that that the unoptimised NAG C DLL� �nagcl�� noopt�� be used withinExcel�Visual Basic� tests have shown that errors occur when some functions within theoptimised DLL� �nagcl���� are called from Visual Basic�
Functions in Chapter a�� which pass the structure Complex by value cannot be called
�
from Visual Basic� This is because userde�ned types may not be passed from Visual Basicto a C DLL by value�
In Excel� function names of the form c���� �az �az �az �e�g�� c��afc� are not permitted�this means that care must be exercised when using the Visual Basic alias facility on routinesin Chapters c��� c�� and c���
Discussion of examples
This section provides brief comments on the example code fragments of Appendix C� Allthe examples use the unoptimized NAG C DLL� �nagcl�� noopt�� and some make use of anauxiliary DLL called �examples interfaces��
The example code has been written so that it can be used from either Excel �� or VisualBasic ���� It has been successfully tested with both these packages under Windows ���
Spline example
This example illustrates the use of the �previously de�ned� type Nag Spline which ispassed to the DLL routines e��bac and e��bbc� This structure contains two pointers oftype double� c and lamda� The memory associated with pointer lamda must be allocatedbefore e��bac is called while the memory associated with c is allocated internally by theroutine�
SVD example
In this example the DLL routine is given two Visual Basic declarations� The function f��wec
is used to calculate both the singular values and also the left and right singular vectors of amatrix A� it also requires the declaration of �dummy� arrays for certain array arguments thatare not referenced� The function f��wec ptr is used to calculate the singular values only�and contains the declarations ByVal q As Long� ByVal b As Long and ByVal pt As Long
within its argument list� This enables assignment of null pointers to these arguments andthus avoids the use of �dummy� array arguments when the routine is called� The example alsoillustrates how data is assigned to the input array a� note that tda is the second �trailing�dimension of matrix A�
ODE example
In the example d��ejc �rst computes a solution with a userde�ned Jacobian and thensolves the same problem using internal evaluation of the Jacobian� Use is made of pointerarguments to access functions which have return type void�
Optimize example
This example requires a variable of type Nag E�� Opt to be initialised and passed toroutine e��ucc� The type Nag E�� Opt is too complicated to be de�ned within VisualBasic and so an auxiliary DLL is used� In this approach a variable of typeNag E�� Opt isdeclared within the auxiliary DLL and a function� called e�� options ptr� is used to exporta pointer to the variable� Structure initialization and option setting can then be performed
��
using routines e��xxc and e��xyc before e�� options ptr is supplied as an argument tothe optimizer routine e��ucc�
Integrate example
The example illustrates how several integrals can be evaluated through the use of di�erentfunction pointers which are exported from an auxiliary DLL� In this case the pointers areused to access functions which have return type double�
Acknowledgements
The author acknowledges the work of A Butterworth and S Datardina� he would also liketo thank J Du Croz and D Sayers for their comments�
References
�� The NAG C Library Manual� Mark �� NAG Ltd� Oxford� UK� �����
�� The NAG Fortran Library Manual� Mark ��� NAG Ltd� Oxford� UK� �����
�� Microsoft O�ce for Windows ��� Microsoft� �����
�� B W Kernighan and D M Ritchie The C Programming Language� Prentice Hall SoftwareSeries� �����
�� Visual Basic �� Microsoft� �����
��
Appendix A � Decorated function names
The following is a list of the decorated function names exported by the NAG C DLLs�
a��aac�� a��abc�� a��bac��� a��bbc��� a��bcc��� a��cac��� a��cbc���
a��ccc��� a��cdc��� a��cec��� a��cfc��� a��cgc��� a��chc��� a��dac���
a��dbc��� a��dcc��� a��ddc��� a��dec��� a��dfc��� a��dgc��� a��dhc���
a��djc��� a��dkc��� a��dlc��� a��eic��� a��ejc���
c��afc��� c��agc��� c��adc��� c��nbc�� c��pbc��� c��zbc�� c��eac���
c��ebc��� c��ecc��� c��ekc��� c��fpc��� c��fpz��� c��fqc��� c��frc���
c��fuc�� c��gbc��� c��gcc��� c��gqc��� c��gsc��� c��gzc��� c��hac���
c��hbc��� c��hcc��� c��hdc���
d��ajc��� d��akc��� d��alc��� d��amc��� d��anc�� d��apc�� d��aqc���
d��asc��� d��bac��� d��bbc��� d��fcc��� d��gac��� d��gbc��� d��cjc���
d��ejc��� d��gac��� d��gbc�� d��nmc���� d��nsc��� d��nvc�� d��pcc���
d��pdc��� d��ppc�� d��pvc��� d��pwc��� d��pxc��� d��pyc��� d��pzc���
d��qfc��� d��qwc�� d��qyc�� d��qzc��� d��rac�� d��xkc�� d��zac���
e��bac��� e��bec��� e��bfc��� e��bgc��� e��bhc��� e��dac�� e��sac���
e��sbc��� e��szc�� e��bac�� e��bbc��� e��bcc��� e��bdc��� e��bec��
e��dcc��� e��ddc��� e��dec��� e��dfc�� e��ccc�� e��dgc��� e��fcc���
e��gbc��� e��hcc�� e��jbc��� e��kbc��� e��mfc�� e��nfc��� e��ucc���
e��xxc�� e��xyc��� e��xzc��� e��yac��� e��ycc���
f��bnc��� f��mcc�� f��qcc��� f��qdc��� f��qec��� f��rcc��� f��rdc���
f��rec��� f��aac��� f��abc�� f��adc�� f��aec��� f��afc��� f��agc���
f��awc��� f��axc�� f��bjc��� f��wec�� f��xec�� f��abc��� f��aec��
f��afc�� f��ahc�� f��adc��� f��agc��� f��ajc��� f��akc��� f��arc���
f��awc��� f��mcc�� f��eac��� f��efc��� f��pac��� f��pbc��� f��pcc��
f��pdc��� f��pec��� f��pfc��� f��pgc��� f��phc�� f��pjc��� f��pkc���
f��plc�� f��pmc��� f��ppc��� f��pqc�� f��prc��� f��psc��� f��sac��
f��sbc�� f��scc��� f��sdc�� f��sec��� f��sfc��� f��sgc��� f��shc��
f��sjc��� f��skc��� f��slc�� f��smc�� f��snc�� f��spc��� f��sqc��
f��src�� f��ssc��� f��yac��� f��ycc��� f��yfc�� f��yjc�� f��ypc��
f��yrc��� f��zac�� f��zcc�� f��zfc��� f��zjc��� f��zpc�� f��zrc���
f��ztc�� f��zuc��� f��zwc��
��
g��aac�� g��alc��� g��bjc��� g��bkc�� g��blc��� g��cec��� g��ddc��
g��dhc��� g��eac��� g��ebc��� g��ecc��� g��edc��� g��eec�� g��efc���
g��fac��� g��fbc��� g��fcc��� g��fdc�� g��fec��� g���c��� g��hac��
g��brc��� g��bxc��� g��cac��� g��cbc�� g��dac���� g��dcc��� g��ddc���
g��dec��� g��dfc��� g��dgc��� g��dkc��� g��dnc��� g��fac��� g��gac����
g��gbc���� g��gcc���� g��gdc���� g��gkc�� g��gnc��� g��hac���� g��hkc���
g��cac�� g��caz�� g��cbc�� g��ccc�� g��cfc� g��cgc��� g��dac���
g��dbc� g��ddc��� g��dyc� g��eac��� g��ecc��� g��edc��� g��ehc���
g��ejc��� g��exc��� g��eyc�� g��ezc� g��fec�� g���c�� g��hac���
g�cac�� g�dac�� g�dbc��� g�ddc��� g��cac��� g��aac��� g��aac���
g��abc��� g��acc��� g��bec��� g��bjc�� g��bxc�� g��byc��� g��bzc��
g��cac�� g��cbc��� g��ccc�� g��cdc��� g��cec��� g��cfc�� g��cgc���
g��eac� g��ebc� g��ecc� g��edc�� g��ewc��� g��exc��� g��xzc��
h��abc���
m��cac��� m��csc�� m��ctc�� m��cuc��� m��dsc�� m��esc��� m��fsc���
m��zac���
s��aac� s��abc��� s��acc��� s��aac��� s��abc� s��acc��� s��aac���
s��acc��� s��adc� s��aac��� s��abc��� s��bac��� s��abc� s��acc�
s��adc� s��aec� s�acc��� s�adc��� s�aec��� s�afc��� s�agc���
s�ahc��� s�ajc��� s�akc��� s�acc��� s�adc��� s�aec��� s�afc���
s�ccc��� s�cdc��� s�cec� s�cfc� s��aac��� s��abc��� s��acc���
s��adc��� s��acc� s��adc� s��bac��� s��bbc�� s��bcc�� s��bdc���
x��ahc�� x��ajc�� x��akc�� x��alc�� x��amc�� x��bdc�� x��bec���
x��bfc��� x��bgc��� x��aac�� x��bac��
��
Appendix B � Enumeration types
The following is a list of the enumeration types used in the NAG C DLLs �informationconcerning structure types can be found in the Nag types�h header �le��
Chapter c��typedef enum �Nag�Convolution� Nag�Correlation� Nag�VectorOp�
typedef enum �Nag�ForwardTransform� Nag�BackwardTransform� Nag�TransformDirection�
Chapter d��typedef enum �Nag�Alg� Nag�Alg�loga� Nag�Alg�logb� Nag�Alg�loga�logb� Nag�QuadWeight�
typedef enum �Nag�UpperSemiInfinite� Nag�LowerSemiInfinite� Nag�Infinite� Nag�BoundInterval�
typedef enum �Nag�Cosine� Nag�Sine� Nag�TrigTransform�
typedef enum �Nag�Legendre� Nag�Rational� Nag�Laguerre� Nag�Hermite� Nag�GaussFormulae�
typedef enum �Nag�OneIteration� Nag�ManyIterations� Nag�MCMethod�
Chapter d��typedef enum �Nag�Relative� Nag�Absolute� Nag�Mixed� Nag�ErrorControl�
typedef enum �Nag�UserInitMesh� Nag�DefInitMesh� Nag�MeshSet�
typedef enum �Nag�RK�range� Nag�RK�onestep� Nag�RK�task�
typedef enum �Nag�RK������ Nag�RK���� Nag�RK��� � Nag�RK�method�
typedef enum �Nag�ErrorAssess�off� Nag�ErrorAssess�on� Nag�ErrorAssess�
typedef enum �Nag�Sol� Nag�Der� Nag�SolDer� Nag�SolDeriv�
Chapters e��� e��� f��� f�� and f��typedef enum �Nag�RC� Nag�Shep� Nag��d�Scat�Method�
typedef enum �Nag�LeftDerivs� Nag�RightDerivs� Nag�DerivType�
typedef enum �Nag�ElementsIn� Nag�ElementsSeparate � Nag�WhereElements�
typedef enum �Nag�Supplied� Nag�NotSupplied � Nag�InitRotation�
typedef enum �Nag�LDLTX� Nag�LDX� Nag�DLTX� Nag�LLTX� Nag�LX� Nag�LTX� Nag�SolveSystem�
Chapter f��typedef enum �NoTranspose� Transpose� ConjugateTranspose � MatrixTranspose�
typedef enum �UpperTriangle� LowerTriangle � MatrixTriangle�
typedef enum �UnitTriangular� NotUnitTriangular � MatrixUnitTriangular�
typedef enum �LeftSide� RightSide � OperationSide�
typedef enum �BottomPivot� TopPivot� VariablePivot� FixedPivot � PivotType�
typedef enum �ForwardSequence� BackwardSequence � SequenceDirection�
typedef enum �OneNorm� FrobeniusNorm� MaxAbsValue � NormType�
typedef enum �General� UpperTriangular� LowerTriangular� SymmetricUpper�
SymmetricLower� HermitianUpper� HermitianLower � MatrixType�
Chapter g��typedef enum �Nag�LowerTail� Nag�UpperTail� Nag�TwoTailSignif�
Nag�TwoTailConfid� Nag�TwoTail� Nag�TailProbability�
typedef enum �Nag�RankScores� Nag�NormalScores� Nag�BlomScores�
Nag�TukeyScores� Nag�WaerdenScores� Nag�SavageScores� Nag�Scores�
typedef enum �Nag�AverageTies� Nag�LowestTies� Nag�HighestTies�
Nag�RandomTies� Nag�IgnoreTies� Nag�Ties�
��
Chapter g��typedef enum �Nag�WeightedEstimate� Nag�UnweightedEstimate� Nag�IncludeWeight�
typedef enum �Nag�MeanInclude� Nag�MeanZero� Nag�IncludeMean�
typedef enum �Nag�ObservAdd� Nag�ObservDel� Nag�UpdateObserv�
typedef enum �Nag�AboutMean� Nag�AboutZero� Nag�SumSquare�
typedef enum �Nag�FirstCall� Nag�Update� Nag�Initialize�
typedef enum �Nag�Expo� Nag�Iden� Nag�Log� Nag�Sqrt� Nag�Reci�
Nag�Logistic� Nag�Probit� Nag�Compl � Nag�Link�
typedef enum �Nag�RegNotSet � �� Nag�HuberReg� Nag�MallowsReg� Nag�SchweppeReg� Nag�RegType�
typedef enum �Nag�PsiNotSet � �� Nag�Lsq� Nag�HuberFun� Nag�HampelFun� Nag�AndrewFun�
Nag�TukeyFun� Nag�PsiFun�
typedef enum �Nag�SigmaNotSet � �� Nag�SigmaRes� Nag�SigmaConst� Nag�SigmaChi� Nag�SigmaEst�
typedef enum �Nag�CovNotSet � �� Nag�CovMatAve� Nag�CovMatObs� Nag�CovMatrixEst�
typedef enum �Nag�SigmaSimul� Nag�SigmaBypas� Nag�SigmaSimulEst�
Chapters g��� g��� g�� and g��typedef enum �Nag�PDF� Nag�CDF� Nag�DiscreteDistrib�
typedef enum �Nag�PopVarEqual� Nag�PopVarNotEqual� Nag�PopVar�
typedef enum �Nag����H� Nag��RSSH� Nag�Smooth�Type�
typedef enum �Nag�Freq� Nag�NoFreq� Nag�FreqTime�
Chapter g�typedef enum �Nag�CriteriaNotSet � �� Nag�LeastSquares� Nag�Exact� Nag�Marginal� Nag�Likelihood�
typedef enum �Nag�Rectangular� Nag�Bartlett� Nag�Tukey� Nag�Parzen� Nag�LagWindow�
typedef enum �Nag�NoCorrection� Nag�Mean� Nag�Trend� NagMeanOrTrend�
typedef enum �Nag�Unlogged� Nag�Logged� Nag�LoggedSpectra�
typedef enum �Nag�next�state� Nag�curr�state� Nag�state�
typedef enum �Nag�ab�prod� Nag�ab�sep� Nag�ab�input�
typedef enum �Nag�UH�Observer� Nag�LH�Observer� Nag�ObserverForm�
typedef enum �Nag�UH�Controller� Nag�LH�Controller� Nag�ControllerForm�
Chapter m��typedef enum �Nag�Ascending� Nag�Descending� Nag�SortOrder�
typedef enum �Nag�First� Nag�Last� Nag�SearchMatch�
Other Chapters d��� d��� e��� e�� and g�typedef enum �Nag�StartNotSet � �� Nag�Cold� Nag�Warm� Nag�Hot�
Nag�NewStart� Nag�ReStart� Nag�Continue � Nag�Start�
typedef enum �Nag�PrintNotSet � �� Nag�NoPrint� Nag�Soln� Nag�Iter� Nag�Iter�Long�
Nag�Soln�Iter� Nag�Soln�Iter�Long� Nag�Soln�Iter�Const� Nag�Soln�Iter�Diag�
Nag�Soln�Iter�Full� Nag�PrintType�
typedef enum �Nag�ChkNotSet � �� Nag�NoCheck� Nag�SimpleCheck� Nag�CheckObj� Nag�CheckCon�
Nag�CheckObjCon� Nag�XSimpleCheck� Nag�XCheckObj� Nag�XCheckCon�
Nag�XCheckObjCon� Nag�GradChk�
typedef enum �Nag�D�NotSet � �� Nag�D�NoPrint� Nag�D�Full� Nag�Print�Deriv�
typedef enum �Nag�ObjCheck� Nag�ConCheck� Nag�DiffInt� Nag�CheckType�
typedef enum �Nag�DerivNotSet � �� Nag�SomeG�SomeJ� Nag�AllG�SomeJ� Nag�SomeG�AllJ�
Nag�AllG�AllJ� Nag�DerivSet�
typedef enum �Nag�Deriv� Nag�NoDeriv� Nag�FunType�
typedef enum �Nag�LinFunNotSet � �� Nag�Lin�Deriv� Nag�Lin�NoDeriv� Nag�LinFun�
typedef enum �Nag�InitNotSet � �� Nag�Init�None� Nag�Init�F�G�H� Nag�Init�All� Nag�Init�H�S� Nag�InitType�
typedef enum �Nag�BoundNotSet � �� Nag�Bounds� Nag�BoundsZero� Nag�BoundsEqual�
Nag�NoBounds� Nag�NoBounds�One�Call� Nag�BoundType�
typedef enum �Nag�ProbTypeNotSet � �� Nag�FP� Nag�LP� Nag�QP� Nag�QP�� Nag�QP�� Nag�QP� Nag�ProblemType�
typedef enum �Nag�EndStateNotSet � �� Nag�Feasible� Nag�Optimal� Nag�Deadpoint� Nag�Weakmin�
Nag�Unbounded� Nag�Infeasible� Nag�Too�Many�Iter� Nag�Hess�Too�Big� Nag�EndState�
��
Appendix C � Examples
This section contains Visual Basic code fragments that illustrate how to call various C DLLfunctions� it also gives the C DLL function prototypes and� where required� template C codeto create the auxiliary DLL� Note that the fragments presented here are incomplete and arereproduced for illustrative purposes only� Complete code for these examples �and for a fewmore� can be obtained from the URL http���www�nag�co�uk�public�html � this code hasbeen tested using both Excel �� and Visual Basic ����
Spline example
C DLL function prototypes
extern void ��stdcall e��bac�Integer m� double x��� double y��� double weights��� double �ss�
Nag�Spline �spline� NagError �fail��
extern void ��stdcall e��bbc�double x� double �s� Nag�Spline �spline� NagError �fail��
Visual Basic declarations
Declare Sub e��bac Lib �nagcl��noopt�dll� Alias ��e��bac�� � �ByVal m As Long� x As Double� �
y As Double� weights As Double� ss As Double� spline As NagSpline� ifail As NagErrorType�
Declare Sub e��bbc Lib �nagcl��noopt�dll� Alias ��e��bbc���� �ByVal x As Double� s As Double� �
spline As NagSpline� fail As NagErrorType�
Visual Basic code
Static Aspline As NagSpline
Static nl As Long
Static lamda�� As Double
Static c� � As Double
Static ptr As Long
Dim pfail As NagErrorType
Aspline�n � nl
� allocate and assign nl elements to Aspline�lamda
Call set double pointer�Aspline�lamda� lamda���� nl�
Call e��bac�m� x���� y���� weights���� ss� Aspline� pfail�
� copy nl elements from Aspline�lamda to the Visual Basic array lamda� and
� elements from the �internally allocated� pointer Aspline�c
Call get double pointer�Aspline�lamda� lamda���� nl�
Call get double pointer�Aspline�c� c���� �
For i � � To �
Print �� Format�c�i�� � ��������������������
Next i
For i � � To m � Step
xarg � x�i�
Call e��bbc�xarg� fit� Aspline� pfail�
Print �� i� Format�x�i�� � ��������������������� Format�fit� ���������������������
If �i � m � � Then
j � j �
xarg � �x�i� � x�i � �� � ���
Call e��bbc�xarg� fit� Aspline� pfail�
Print �� Format�xarg� � ��������������������� Format�fit� ���������������������
End If
j � j �
Next i
� free allocated memory
Call free�Aspline�lamda�
Call free�Aspline�c�
��
SVD example
C DLL function prototypes
extern void ��stdcall f��wec�Integer m� Integer n� double �a� Integer tda� Integer ncolb� double �b�
Integer tdb� Boolean wantq� double �q� Integer tdq� double �sv� Boolean wantp� double �pt�
Integer tdpt� Integer �iter� double �e� Integer �failinfo� NagError �fail��
Visual Basic declarations
Standard C style declaration
Declare Sub f��wec Lib �nagcl��noopt�dll� Alias ��f��wec���� �ByVal m As Long� ByVal n As Long� �
a As Double� ByVal tda As Long� ByVal ncolb As Long� b As Double� ByVal tdb As Long� �
ByVal wantq As Long� q As Double� ByVal tdq As Long� sv As Double� ByVal wantp As Long� �
pt As Double� ByVal tdpt As Long� iter As Long� e As Double� failinfo As Long� �
ifail As NagErrorType�
Allow the use of null pointers
Declare Sub f��wec�ptr Lib �nagcl��noopt�dll� Alias ��f��wec���� �ByVal m As Long� ByVal n As Long� �
a As Double� ByVal tda As Long� ByVal ncolb As Long� ByVal b As Long� ByVal tdb As Long� �
ByVal wantq As Long� ByVal q As Long� ByVal tdq As Long� sv As Double� ByVal wantp As Long� �
ByVal pt As Long� ByVal tdpt As Long� iter As Long� e As Double� failinfo As Long� �
ifail As NagErrorType�
Visual Basic code
Static a�m�n�� As Double
Static a��m�n�� As Double
Static q�m�n�� As Double
Static sv�m�� As Double
Static pt��� As Double
Static e�m�� As Double
Static dum��� As Double
Dim pfail As NagErrorType
pfail�code � �
pfail�printm �
ncolb � �
tda � n
For i � � To m �
For j � � To n �
Input ��� a�i � tda � j�
a��i � tda � j� � a�i � tda � j�
Next j
Next i
tdb � �
tdpt � �
tdq � n
wtp �
wtq �
� calculate the singular values and also the left and right singular vectors
Call f��wec�m� n� a����� tda� ncolb� dum���� tdb� wtq� q���� tdq� sv���� wtp�
pt���� tdpt� iter� e���� info� pfail�
tdq � �
wtq � �
wtp � �
� only calculate the singular values� call f��wec ptr with � null pointers
Call f��wec ptr�m� n� a���� tda� ncolb� ByVal ��� tdb� wtq� ByVal ��� tdq� sv���� wtp�
ByVal ��� tdpt� iter� e���� info� pfail�
�
ODE example
C DLL function prototypes
typedef void ���stdcall � NAG�D��EJC�FUN��Integer neq� double x� double y��� double �f�
Nag�User �comm��
typedef void ���stdcall � NAG�D��EJC�PFUN��Integer neq� double x� double y��� double pw���
Nag�User �comm��
typedef void ���stdcall � NAG�D��EJC�OUTFUN��Integer neq� double �xsol� double y���
Nag�User �comm��
typedef double ���stdcall � NAG�D��EJC�GFUN��Integer neq� double x� double y���
Nag�User �comm��
extern void ��stdcall d��ejc�Integer neq� NAG�D��EJC�FUN fcn� NAG�D��EJC�PFUN pederv� double �t�
double y��� double tend� double tol� Nag�ErrorControl err�c� NAG�D��EJC�OUTFUN output�
NAG�D��EJC�GFUN g� Nag�User �comm� NagError �fail��
Auxiliary DLL template code
�define DllExport ��declspec� dllexport �
void local�d��ejc�fcn�Integer neq� double x� double y��� double f��� Nag�User �comm��
void local�d��ejc�pederv�Integer neq� double x� double y��� double pw��� Nag�User �comm��
DllExport long d��ejc�pederv�void� � return �long��local�d��ejc�pederv���
DllExport long d��ejc�fcn�void� � return �long��local�d��ejc�fcn���
void local�d��ejc�fcn�Integer neq� double x� double y��� double f��� Nag�User �comm� �
� ��� Insert C code ��� �
�
void local�d��ejc�pederv�Integer neq� double x� double y��� double pw��� Nag�User �comm� �
� ��� Insert C code ��� �
�
Visual Basic declarations
Declare Sub d��ejc Lib �nagcl��noopt�dll� Alias ��d��ejc���� �ByVal neq As Long� ByVal ptr�fcn As Long� �
ByVal ptr�pederv As Long� x As Double� y As Double� ByVal xend As Double� ByVal tol As Double� �
ByVal err�c As Long� ByVal ptr�output As Long� ByVal ptr�g As Long� comm As Nag�User� �
ifail As NagErrorType�
Declare Function d��ejc�fcn Lib �examples�interfaces�dll� Alias ��d��ejc�fcn��� �� As Long
Declare Function d��ejc�pederv Lib �examples�interfaces�dll� Alias ��d��ejc�pederv��� �� As Long
Visual Basic code
Static err c As Long
Static comm As Nag User
Static y��� As Double
Static fcn ptr As Long
Static pederv ptr As Long
Dim pfail As NagErrorType
� user�defined Jacobian� use pointers d��ejc fcn and d��ejc pederv
xend � x � ��
fcn ptr � d��ejc fcn
pederv ptr � d��ejc pederv
Call d��ejc�neq� fcn ptr� pederv ptr� x� y���� xend� tol� err c� �� �� comm� pfail�
Print �� x� y���� y��� y���
� internal evaluation of Jacobian� use pointer d��ejc fcn
xend � x � ��
fcn ptr � d��ejc fcn
Call d��ejc�neq� fcn ptr� ByVal ��� x� y���� xend� tol� err c� ByVal ��� ByVal ��� comm� pfail�
Print �� x� y���� y��� y���
��
Optimize example
C DLL function prototypes
typedef void ���stdcall � NAG�E�UCC�FUN��Integer� double �� double �� double �� Nag�Comm ���
typedef void ���stdcall � NAG�E�UCC�CONFUN��Integer� Integer� Integer �� double �� double ��
double �� Nag�Comm ���
extern void ��stdcall e�ucc�Integer n� Integer nclin� Integer ncnlin� double a��� Integer tda�
double bl��� double bu��� NAG�E�UCC�FUN objfun� NAG�E�UCC�CONFUN confun� double x���
double �objf� double objgrad��� Nag�E��Opt �options� Nag�Comm �user�comm� NagError �fail��
extern void ��stdcall e�xxc�Nag�E��Opt �opt��
extern void ��stdcall e�xyc�const char �name� const char �opt�file� Nag�E��Opt �opt�
Boolean print� const char �outfile� NagError �fail��
Auxiliary DLL template code
�define DllExport ��declspec� dllexport �
Nag�E��Opt options�
void local�e�ucc�objfun�Integer n� double x��� double �objf�double objgrd��� Nag�Comm �comm��
void local�e�ucc�confun�Integer n� Integer ncnlin� Integer needc��� double x��� double conf���
double conjac��� Nag�Comm �comm��
DllExport long e�ucc�objfun�void� � return �long��local�e�ucc�objfun���
DllExport long e�ucc�confun�void� � return �long��local�e�ucc�confun���
DllExport long e��options�ptr�void� �
� ��� Insert C code ��� �
return �long���options��
�
void local�e��objfun�long n� double �x� double �objf� double �g� Nag�Comm �comm� �
� ��� Insert C code ��� �
�
void local�e�ucc�objfun�Integer n� double x��� double �objf� double objgrd��� Nag�Comm �comm� �
� ��� Insert C code ��� �
�
void local�e�ucc�confun�Integer n� Integer ncnlin� Integer needc��� double x���double conf���
double conjac��� Nag�Comm �comm� �
� ��� Insert C code ��� �
�
Visual Basic declarations
Declare Sub e�ucc Lib �nagcl��noopt�dll� Alias ��e�ucc���� �ByVal n As Long� �
ByVal nclin As Integer� ByVal ncnlin As Integer� a As Double� ByVal tda As Integer� �
bl As Double� bu As Double� ByVal objfun�ptr As Long� ByVal confun�ptr As Long� �
x As Double� objf As Double� g As Double� ByVal options�ptr As Long� comm As Any� �
fail As NagErrorType�
Declare Sub e�xxc Lib �nagcl��noopt�dll� Alias ��e�xxc�� �ByVal options�ptr As Long�
Declare Sub e�xyc Lib �nagcl��noopt�dll� Alias ��e�xyc��� �ByVal routine�name As String� �
ByVal opt�file As String� ByVal options�ptr As Long� ByVal iprint As Long� �
ByVal outfile As String� ifail As NagErrorType�
Declare Function e��options�ptr Lib �examples�interfaces�dll� Alias ��e��options�ptr��� �� As Long
Declare Function e��objfun Lib �examples�interfaces�dll� Alias ��e��objfun��� �� As Long
Declare Function e�ucc�confun Lib �examples�interfaces�dll� Alias ��e�ucc�confun��� �� As Long
Visual Basic code
Static a�nclin � n�
Static bu�totalvars�
Static x�n�
Static bl�totalvars�
Static objgrd�n�
Static printit As Long
Static objf As Double
Static local e� options ptr As Long
Static objfun ptr As Long
Static confun ptr As Long
Dim pfail As NagErrorType
��
tda � n
pfail�code � �
� initialise options using options structure pointer� e� option ptr
local e� options ptr � e� options ptr
Call e�xxc�local e� options ptr�
printit �
� read the options file for e�ucc
local eo options ptr � e� options ptr
Call e�xyc��e�ucc�� �e�ucce�d�� local e� options ptr� printit� �e�ucce�r�� pfail�
� call the optimizer using function pointers e�ucc objfun� e�ucc confun and options structure
� pointer� e� options ptr
objfun ptr � e�ucc objfun
confun ptr � e�ucc confun
local eo options ptr � e� options ptr
Call e�ucc�n� nclin� ncnlin� a���� tda� bl���� bu����
objfun ptr� confun ptr� x���� objf� objgrd���� local e� options ptr� ByVal ��� pfail�
��
Integrate example
C DLL function prototypes
typedef double ���stdcall � NAG�D�AJC�FUN��double��
extern void ��stdcall d�ajc�NAG�D�AJC�FUN f� double a� double b� double epsabs� double epsrel�
Integer max�num�subint� double �result� double �abserr� Nag�QuadProgress �qp� NagError �fail��
Auxiliary DLL template code
�define DllExport ��declspec� dllexport �
double local�d�ajc�fun�double x��
double local�d�ajc�fun��double x��
DllExport long d�ajc�fun�void� � return �long��local�d�ajc�fun���
DllExport long d�ajc�fun��void� � return �long��local�d�ajc�fun����
double local�d�ajc�fun�double x� �
� ��� Insert C code ��� �
return � � ��� Insert C code ��� � ��
�
double local�d�ajc�fun��double x� �
� ��� Insert C code ��� �
return � � ��� Insert C code ��� � ��
�
Visual Basic declarations
Declare Sub d�ajc Lib �nagcl��noopt�dll� Alias ��d�ajc���� �ByVal ptr As Long� �
ByVal a As Double� ByVal b As Double� ByVal epsabs As Double� ByVal epsres As Double� �
ByVal max�num�sunint As Long� result As Double� abserr As Double� �
qp As NagQuadProgress� fail As NagErrorType�
Declare Function d�ajc�fun Lib �examples�interfaces�dll� Alias ��d�ajc�fun��� �� As Long
Declare Function d�ajc�fun� Lib �examples�interfaces�dll� Alias ��d�ajc�fun���� �� As Long
Visual Basic code
Static qp As NagQuadProgress
Static a As Double
Static b As Double
Static epsabs As Double
Static epsrel As Double
Static result As Double
Static max num subint As Long
Static abserr As Double
Static pi As Double
Static fun ptr As Long
Dim pfail As NagErrorType
pi � � � Atn���
a � ��
b � � � pi
max num subint � ���
epsabs � ��
epsrel � �����
pfail�printm �
pfail�code � �
� integrate function � use pointer d�ajc fun
fun ptr � d��ajc fun
Call d�ajc�fun ptr� a� b� epsabs� epsrel� max num subint� result� abserr� qp� pfail�
� integrate function �� use pointer d�ajc fun�
fun ptr � d��ajc fun�
Call d�ajc�fun ptr� a� b� epsabs� epsrel� max num subint� result� abserr� qp� pfail�
��