calling 32-bit nag c dll functions from visual basic

21

Upload: others

Post on 11-Feb-2022

8 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Calling 32-bit NAG C DLL functions from Visual Basic

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��

Page 2: Calling 32-bit NAG C DLL functions from Visual Basic

� 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��

Page 3: Calling 32-bit NAG C DLL functions from Visual Basic

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

Page 4: Calling 32-bit NAG C DLL functions from Visual Basic

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�

Page 5: Calling 32-bit NAG C DLL functions from Visual Basic

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�

Page 6: Calling 32-bit NAG C DLL functions from Visual Basic

� 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�

Page 7: Calling 32-bit NAG C DLL functions from Visual Basic

� 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������ �

Page 8: Calling 32-bit NAG C DLL functions from Visual Basic

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�

Page 9: Calling 32-bit NAG C DLL functions from Visual Basic

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

Page 10: Calling 32-bit NAG C DLL functions from Visual Basic

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

��

Page 11: Calling 32-bit NAG C DLL functions from Visual Basic

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� �����

��

Page 12: Calling 32-bit NAG C DLL functions from Visual Basic

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��

��

Page 13: Calling 32-bit NAG C DLL functions from Visual Basic

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��

��

Page 14: Calling 32-bit NAG C DLL functions from Visual Basic

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�

��

Page 15: Calling 32-bit NAG C DLL functions from Visual Basic

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�

��

Page 16: Calling 32-bit NAG C DLL functions from Visual Basic

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�

��

Page 17: Calling 32-bit NAG C DLL functions from Visual Basic

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�

Page 18: Calling 32-bit NAG C DLL functions from Visual Basic

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���

��

Page 19: Calling 32-bit NAG C DLL functions from Visual Basic

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

��

Page 20: Calling 32-bit NAG C DLL functions from Visual Basic

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�

��

Page 21: Calling 32-bit NAG C DLL functions from Visual Basic

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�

��