NAG recommends that you read the following minimum reference material before calling any library routine:
(a) Essential Introduction
(b) Chapter Introduction
(c) Routine Document
(d) Implementation-specific Users' Note
Items (a), (b) and (c) are included in the NAG Fortran Library on-line documentation; items (a) and (b) are also included in the NAG Fortran Library Introductory Guide; item (d) is this document which is provided in HTML form.
Because of difficulties associated with passing channel numbers between a main program and a DLL, the option setting routines E04DJF, E04MGF, E04NDF, E04NGF, E04NLF, E04UDF, E04UHF and E04UQF have been altered slightly in their specification. Please see Section 5.1 for further details.
The default Compaq Visual Fortran calling convention is used. In essence this means that parameters are accessed by reference. Character strings are passed by reference followed immediately by the value of the length of the string. (This will be of interest mainly to C and C++ users; see Section 4.4.)
There are 22 self-contained DLLs which together make up the whole of the Mark 19 Fortran Library. The individual DLLs contain a chapter or group of chapters of the NAG library as detailed below:
DLL Chapters NAGAC A00, A02, C02, C05, C06 NAGD01 D01 NAGD02 D02 NAGD03 D03 NAGD045 D04, D05 NAGE012 E01, E02 NAGE04 E04 NAGF01 F01 NAGF02 F02 NAGF0345 F03, F04, F05 NAGF06 F06 NAGF07 F07 NAGF08 F08 NAGF11 F11 NAGG01 G01 NAGG02 G02 NAGG034 G03, G04 NAGG05 G05 NAGG0712 G07, G08, G10, G11, G12 NAGG13 G13 NAGHMP H, M01, P01 NAGSX S01, S09, S10, S11, S13, S14, S15, S17, S18, S19, S20, S21, X01, X02, X03, X04, X05
Assuming that the directory containing the import libraries has been added to the LIB environment variable, you may compile and link to the NAG Fortran Library on the command line in the following manner:
df /c /Tf myprog.f link myprog nag*.libwhere myprog.f is a Fortran source program calling NAG routines and nag*.lib is replaced with the names of the actual library files required (see the list of DLLs in Section 4.1).
If you are using Developer Studio, after establishing a workspace you should make the system aware of the import libraries by clicking on Project, then Settings, then Link and entering the full path to each required library (see the list of DLLs above) under Object/library modules. Remember to link to the import libraries not the DLL themselves.
If you wish to use Developer Studio to develop Fortran 90 programs using the NAG interface blocks you should also read Section 4.13.
ftn95 myprog.f /import_lib nag*.libwhere myprog.f is a Fortran source program calling NAG routines and nag*.lib is replaced with the names of the actual library files required (see the list of DLLs in Section 4.1).
If required, the DLLs can be specified:
ftn95 myprog.f /import_lib nag*.dllwhere nag*.dll is replaced with the names of the actual DLLs required.
The effect of this is to assume that all exported names in the .lib or .dll files are CVF STDCALL and that any call to them should use the CVF STDCALL calling convention.
External names passed via the argument list to a routine in a NAG DLL are automatically adjusted for whether or not they occur in the same source file as the call to the NAG routine.
slink myprog.obj nag*.libNote that SLINK will follow the path specified in the LIB environment variable when searching for .lib files. It is not, therefore, necessary to place the path to the .lib files on the SLINK command line. Ensure that the LIB environment variable contains the path to them.
The key information is as follows:
Borland import libraries are not supplied but may easily be constructed from the DLLs as follows:
impdef name.def name.dll implib name.lib name.defwhere name denotes the name of the NAG DLL, for example, NAGAC. The first statement constructs a module definitions file, name.def, and the second takes this module definition file and constructs an import library, name.lib. Do not be alarmed by warning messages from impdef. These arise from the number of alternative symbols exported from the DLL in order to provide convenient forms for different users.
Detailed advice on the use of the DLLs from within Excel is given in the Windows Help file VBheaders.hlp.
The key information is as follows:
Detailed advice on the use of the DLLs from Visual Basic is given in the Windows Help file VBheaders.hlp.
The key information is as for VBA above.
Detailed advice on the use of the DLLs from Delphi is given in the Windows Help file Delphi.hlp.
The key informationis as follows:
Detailed advice on the use of the DLLs from PowerBuilder is given in the Windows Help file PowerBuilder.hlp.
The key information is as follows:
real - DOUBLE PRECISION basic precision - double precision complex - COMPLEX*16 additional precision - quadruple precision (REAL*16) machine precision - the machine precision, see the value returned by X02AJF in Section 4
Thus a parameter described as real should be declared as DOUBLE PRECISION in your program. If a routine accumulates an inner product in additional precision, it is using software to simulate quadruple precision.
Additional bold italicised terms are used in the example programs in the on-line documentation and they must be interpreted as follows:
real as an intrinsic function name - DBLE imag - DIMAG cmplx - DCMPLX conjg - DCONJG e in constants, e.g. 1.0e-4 - D, e.g. 1.0D-4 e in formats, e.g. e12.4 - D, e.g. D12.4
All references to routines in Chapter F07 - Linear Equations (LAPACK) and Chapter F08 - Least-squares and Eigenvalue Problems (LAPACK) use the LAPACK name, not the NAG F07/F08 name. The LAPACK name is precision dependent, and hence the name appears in a bold italicised typeface.
The examples in the on-line documentation use the single precision form of the
LAPACK name. To convert this name to its double precision form, change the
first character either from S to D or C to Z as appropriate.
For example:
sgetrf refers to the LAPACK routine name - DGETRF cpotrs - ZPOTRS
Care should be taken to ensure that X04AAF and X04ABF are taken from the DLL containing the routine producing the output. Satisfying the linker by including the NAGSX DLL will not, in general, suffice.
See Section 6 for additional documentation available from NAG.
(a) Subroutines are called as such
(b) Functions are declared with the right type
(c) The correct number of arguments are passed
(d) All arguments match in type and structure
The interface blocks were generated automatically by analysing the source code for the NAG Fortran Library. As a consequence, and because they have been thoroughly tested, they are generally more reliable than individually written declarations.
The NAG Fortran Library Interface Block files are organised by Library chapter. The module names are:
nag_f77_a_chapter nag_f77_c_chapter nag_f77_d_chapter nag_f77_e_chapter nag_f77_f_chapter nag_f77_g_chapter nag_f77_h_chapter nag_f77_m_chapter nag_f77_p_chapter nag_f77_s_chapter nag_f77_x_chapterThese are supplied in pre-compiled form (.mod files). If you are compiling on the command line, to make one or more files accessible you should either copy them to the current directory or ensure that the directory containing the .mod files has been added to the INCLUDE environment variable.
If you are using Developer Studio, after establishing a workspace you should make the system aware of any interface blocks by clicking on Project, then Settings, then Fortran, choosing Preprocessor in the Category menu and entering the full paths to the interface blocks in the box labelled INCLUDE and USE Paths.
In order to make use of these modules from existing Fortran 77 code the following changes need to be made:
These changes are illustrated by showing the conversion of the Fortran 77 version of the example program for NAG Fortran Library routine S18DEF. Please note that this is not exactly the same as the example program that is distributed with this implementation. Each change is surrounded by comments boxed with asterisks.
* S18DEF Example Program Text * Mark 14 Revised. NAG Copyright 1989. ******************************************************************* * Add USE statement for relevant chapters * USE NAG_F77_S_CHAPTER * * ******************************************************************* * .. Parameters .. INTEGER NIN, NOUT PARAMETER (NIN=5,NOUT=6) INTEGER N PARAMETER (N=2) * .. Local Scalars .. COMPLEX*16 Z DOUBLE PRECISION FNU INTEGER IFAIL, NZ CHARACTER*1 SCALE * .. Local Arrays .. COMPLEX*16 CY(N) * .. External Subroutines .. ******************************************************************* * EXTERNAL declarations need to be removed (and type declarations * * for functions). * C EXTERNAL S18DEF * * ******************************************************************* * .. Executable Statements .. WRITE (NOUT,*) 'S18DEF Example Program Results' * Skip heading in data file READ (NIN,*) WRITE (NOUT,*) WRITE (NOUT,99999) 'Calling with N =', N WRITE (NOUT,*) WRITE (NOUT,*) +' FNU Z SCALE CY(1) CY(2) + NZ IFAIL' WRITE (NOUT,*) 20 READ (NIN,*,END=40) FNU, Z, SCALE IFAIL = 0 * CALL S18DEF(FNU,Z,N,SCALE,CY,NZ,IFAIL) * WRITE (NOUT,99998) FNU, Z, SCALE, CY(1), CY(2), NZ, IFAIL GO TO 20 40 STOP * 99999 FORMAT (1X,A,I2) 99998 FORMAT (1X,F7.4,' (',F7.3,',',F7.3,') ',A, + 2(' (',F7.3,',',F7.3,')'),I4,I4) END
Routine Name Options File Name E04DJF E04DJF.OPT E04MGF E04MGF.OPT E04NDF E04NDF.OPT E04NGF E04NGF.OPT E04NLF E04NLF.OPT E04UDF E04UDF.OPT E04UHF E04UHF.OPT E04UQF E04UQF.OPT
To partially address these issues the routines X04ACF and X04ADF, whose function is to open and close files, are exported from all the DLLs. These routines are described in the on-line documentation.
Similarly, setting IFAIL to -1 before calling a NAG routine is not recommended, because output to the standard output channel will again cause the Visual Basic, VBA and Delphi packages to close (Section 5.2 explains how to avoid this effect).
S07AAF F(1) = 1.0D+13 F(2) = 1.0D-14 S10AAF E(1) = 18.50 S10ABF E(1) = 708.0 S10ACF E(1) = 708.0 S13AAF x(hi) = 708.3 S13ACF x(hi) = 1.0D+16 S13ADF x(hi) = 1.0D+17 S14AAF IFAIL = 1 if X > 170.0 IFAIL = 2 if X < -170.0 IFAIL = 3 if abs(X) < 2.23D-308 S14ABF IFAIL = 2 if X > 2.55D+305 S15ADF x(hi) = 26.6 x(low) = -6.25 S15AEF x(hi) = 6.25 S17ACF IFAIL = 1 if X > 1.0D+16 S17ADF IFAIL = 1 if X > 1.0D+16 IFAIL = 3 if 0.0 < X <= 2.23D-308 S17AEF IFAIL = 1 if abs(X) > 1.0D+16 S17AFF IFAIL = 1 if abs(X) > 1.0D+16 S17AGF IFAIL = 1 if X > 103.8 IFAIL = 2 if X < -5.6D+10 S17AHF IFAIL = 1 if X > 104.1 IFAIL = 2 if X < -5.6D+10 S17AJF IFAIL = 1 if X > 104.1 IFAIL = 2 if X < -1.8D+9 S17AKF IFAIL = 1 if X > 104.1 IFAIL = 2 if X < -1.8D+9 S17DCF IFAIL = 2 if abs (Z) < 3.93D-305 IFAIL = 4 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 5 if abs (Z) or FNU+N-1 > 1.07D+9 S17DEF IFAIL = 2 if imag (Z) > 700.0 IFAIL = 3 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 4 if abs (Z) or FNU+N-1 > 1.07D+9 S17DGF IFAIL = 3 if abs (Z) > 1.02D+3 IFAIL = 4 if abs (Z) > 1.04D+6 S17DHF IFAIL = 3 if abs (Z) > 1.02D+3 IFAIL = 4 if abs (Z) > 1.04D+6 S17DLF IFAIL = 2 if abs (Z) < 3.93D-305 IFAIL = 4 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 5 if abs (Z) or FNU+N-1 > 1.07D+9 S18ADF IFAIL = 2 if 0.0 < X <= 2.23D-308 S18AEF IFAIL = 1 if abs(X) > 711.6 S18AFF IFAIL = 1 if abs(X) > 711.6 S18CDF IFAIL = 2 if 0.0 < X <= 2.23D-308 S18DCF IFAIL = 2 if abs (Z) < 3.93D-305 IFAIL = 4 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 5 if abs (Z) or FNU+N-1 > 1.07D+9 S18DEF IFAIL = 2 if real (Z) > 700.0 IFAIL = 3 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 4 if abs (Z) or FNU+N-1 > 1.07D+9 S19AAF IFAIL = 1 if abs(x) >= 49.50 S19ABF IFAIL = 1 if abs(x) >= 49.50 S19ACF IFAIL = 1 if X > 997.26 S19ADF IFAIL = 1 if X > 997.26 S21BCF IFAIL = 3 if an argument < 1.579D-205 IFAIL = 4 if an argument >= 3.774D+202 S21BDF IFAIL = 3 if an argument < 2.820D-103 IFAIL = 4 if an argument >= 1.404D+102
X01AAF (PI) = 3.1415926535897932 X01ABF (GAMMA) = 0.5772156649015329
The basic parameters of the model
X02BHF = 2 X02BJF = 53 X02BKF = -1021 X02BLF = 1024 X02DJF = .TRUE.Derived parameters of the floating-point arithmetic
X02AJF = 1.11022302462516D-16 X02AKF = 2.22507385850721D-308 X02ALF = 1.79769313486231D+308 X02AMF = 2.22507385850721D-308 X02ANF = 2.22507385850721D-308Parameters of other aspects of the computing environment
X02AHF = 1.84467440737095D+19 X02BBF = 2147483647 X02BEF = 15 X02DAF = .FALSE.
A full on-line version of the NAG Fortran Library Manual is provided in the form of Portable Document Format (PDF) files, and is included with this implementation on the distribution medium.
Abbreviated on-line documentation of the routines is also provided in Windows Help file form as part of this implementation.
Printed copies of the NAG Fortran Library Manual are available for purchase; please refer to the NAG documentation order form (available on the NAG websites, see Section 6 (c)) for details of current prices.
The Response Centres are open during office hours, but contact is possible by fax, email and phone (answering machine) at all times.
When contacting a Response Centre please quote your NAG site reference and NAG product code (in this case FLDLL194Z).
The NAG websites are an information service providing items of interest to users and prospective users of NAG products and services. The information is reviewed and updated regularly and includes implementation availability, descriptions of products, downloadable software, product documentation and technical reports. The NAG websites can be accessed at
or
http://www.nag.com/ (in North America)
or
http://www.nag-j.co.jp/ (in Japan)
NAG Ltd Wilkinson House Jordan Hill Road OXFORD OX2 8DR NAG Ltd Response Centre United Kingdom email: support@nag.co.uk Tel: +44 (0)1865 511245 Tel: +44 (0)1865 311744 Fax: +44 (0)1865 310139 Fax: +44 (0)1865 310139 Nihon NAG KK Yaesu Nagaoka Building No. 6 1-9-8 Minato Chuo-ku Tokyo Japan email: help@nag-j.co.jp Tel: +81 (0)3 5542 6311 Fax: +81 (0)3 5542 6312 [NP3514/UN]