Using the NAG Library with the Absoft Fortran Compiler on Windows 32-bit Systems

Introduction

The NAG Fortran Library is very popular and users from many different backgrounds request that it be made available to them on their favourite system and using their favourite compiler. Many software vendors adopt a very hard-line and restrict their implementations to cover only a subset of the many possible. This is understandable, for to fully test a product can take a considerable investment of time and effort. Luckily on Microsoft Windows the advent of DLLs, or sharable libraries, makes it possible to exhaustively test one library implementation which may then satisfy many different calling environments.

Prior to Mark 23 of the NAG Fortran Library we described how our libraries might be used in conjunction with the Absoft Fortran compiler. Please see the Post Release Note and Users' Note if you have an old version of the Absoft Fortran compiler.

Now, with the availability of Absoft 11.5 and the extra facilities it offers, we draw attention to the relative ease with which our Windows 32 Libraries may be called from this compiler and provide examples and interface blocks to make these practical propositions for anyone with this compiler.

Dynamic Link Libraries (DLLs)

A dynamic link library consists of code that is executed at runtime but which is not fully encapsulated into the program executable. It is a 'sharable library' as defined in Unix for example.

However the position is complicated because there are differing types of DLLs. On the 32-bit Windows platform we offer FLDLL234ML as a DLL implementation. This is the only type of DLL that may be used with Visual Basic and Excel on 32-bit systems and uses a 'calling convention' called STDCALL. A calling convention is just an understanding between the library and the calling program about which of them takes responsibility for tidying up the stack when a routine has finished executing.

For historical reasons, because the original compiler we used to form a 32-bit DLL was Digital Visual Fortran a further convention was adopted for the DLL. This concerned the 'hidden' information associated with character arguments. Many compilers and systems effectively pass this information at the very end of all of the regular arguments. The Digital Fortran compiler passed the length of the character argument immediately after the argument in question. This is often termed the CVF calling convention. (This reflects the direct lineage Digital Visual Fortran -> Compaq Visual Fortran -> Intel Visual Fortran and embraces the STDCALL convention plus the hidden length requirement.)

Absoft Fortran

Prior to Mark 22 we described how to use our traditional DLL libraries with this compiler. The procedure worked well, but was a trifle inconvenient in order to match the CVF calling convention employed.

We distributed a file with Mark 21 illustrating the requisite changes.

At Mark 22 we had begun to distribute a different kind of DLL with our static library implementation FLW3222DCL. This is a sharable library too but one that uses a calling convention that is better for the Absoft compiler - this link provides the details.

Mark 23

At Mark 23 we produced corresponding products FLDLL234ML and FLW3223DCL. Again both may be called from the latest Absoft Fortran compiler but, thanks to extensions to the facilities offered by this compiler, FLW3223DCL does not have the marked advantage over FLDLL234ML that would have been exhibited by an older version of the compiler.

At Mark 23 our example programs have shifted away from a Fortran 77-like form to use more modern Fortran. In particular interface blocks are now used. Our examples illustrate the usage with both styles of programs. We also provide interface blocks that have been modified to work with FLDLL234ML and the Absoft compiler by inserting the required STDCALL instructions.

Using FLDLL234ML

From a modern Fortran90 style calling program

The required compile and link command is:

f95 -YVF_CHAR -YEXT_NAMES=UCS -YEXT_SFX="" program.f90 fldll234m_nag.lib

where program.f90 is a Fortran program calling a NAG routine. It might be d01ajfe.f90 for example.

The -YVF_CHAR flag tells the compiler to use the CVF character convention and the -YEXT_NAMES=UCS -YEXT_SFX="" flag adjusts the name mangling so that the appropriate routines may be identified and used from within the DLL.

If you are using a modern-Fortran 90 style of program the standard interface blocks distributed with the implementation will not work. Revised interface blocks suitable for use with this compiler have been developed and are available both in source and compiled form. These have an extra STDCALL, non-standard, instruction. E.g.

       INTERFACE
          SUBROUTINE E04UCA(N,NCLIN,NCNLN,LDA,LDCJ,LDR,A,BL,BU,CONFUN,OBJFUN,&
          ITER,ISTATE,C,CJAC,CLAMDA,OBJF,OBJGRD,R,X,IWORK,LIWORK,WORK,&
          LWORK,IUSER,RUSER,LWSAV,IWSAV,RWSAV,IFAIL)
!            .. Use Statements ..
             USE NAG_PRECISIONS, ONLY : WP
             STDCALL E04UCA
!            .. Non-Generic Interface Blocks ..
………….
          END SUBROUTINE E04UCA
       END INTERFACE
			 

The user-provided functions should also have the STDCALL instruction inserted e.g.

    MODULE e04ucae_mod

!      E04UCA Example Program Module:
!             Parameters and User-defined Routines

!      .. Use Statements ..
       USE nag_library, ONLY : nag_wp
!      .. Implicit None Statement ..
       IMPLICIT NONE
!      .. Parameters ..
       REAL (KIND=nag_wp), PARAMETER       :: one = 1.0_nag_wp
       REAL (KIND=nag_wp), PARAMETER       :: zero = 0.0_nag_wp
       INTEGER, PARAMETER                  :: inc1 = 1, lcwsav = 1,            &
                                              liwsav = 610, llwsav = 120,      &
                                              lrwsav = 475, nin = 5, nout = 6
    CONTAINS
       SUBROUTINE objfun(mode,n,x,objf,objgrd,nstate,iuser,ruser)
!         Routine to evaluate objective function and its 1st derivatives.

!         .. Implicit None Statement ..
          IMPLICIT NONE
          STDCALL OBJFUN
!         .. Scalar Arguments ..
…….

Three tested examples are provided. One calling d01ajf (in file d01ajfe.f90) and one calling e04uca (in file e04ucae.f90), show how to provide a user-defined function and subroutine, and the other calling f07adf (in file f07adfe.f90), demonstrates how character string arguments are handled. All example materials, including any required data files, together with the interface blocks previously described are available from here.

From a Fortran77 style calling program

If your programs are more Fortran77-like in their form i.e. do not employ interface blocks to give the compiler advance notice of routines that are to be employed then the source needs to contain special comment lines that convey information.

In the case of e04uca for example the program begins:
!dir$ name(objfun="OBJFUN@32")
!dir$ name(confun="CONFUN@44")

      program dks
!       E04UCA Example Program Text 
….

The !dir$ name tells the compiler to look for the decorated symbol OBJFUN@32 within the DLL to satisfy the program requirement for objfun. The '32' is derived from the fact that objfun has 8 arguments. The 8 is multiplied by 4 to get the 32. Similarly CONFUN has 11 arguments.

We need to note that the STDCALL statement has to be included in the main program just after the relevant external statement:

!       .. External Subroutines ..
      EXTERNAL         CONFUN, DGEMV, E04UCA, E04WBF, OBJFUN
      STDCALL          DGEMV, E04UCA, E04WBF         
!       .. Executable Statements ..
…

The three example programs described previously but this time using only Fortran77 constructs are available from here.

Using FLW3223DCL

Because the DLL distributed with this library is not STDCALL and does not use the CVF protocol the required compiler commands are just:

f95 -YEXT_NAMES=UCS -YEXT_SFX="" routine.f90 flw3223dc_nag.lib

Here again the -YEXT_NAMES=UCS -YEXT_SFX="" are required to ensure that the linker finds the required NAG routines from within the DLL and routine.f90 is the program calling the NAG routines.

With no different calling conventions to tell the compiler about no textual changes are required of the programs whether they be Fortran77-like or use interface blocks in a truly Fortran90-like manner. If you do use interface blocks though then you will need to recompile the source that we provide or download the interface blocks from here.

Summary

It is easy to use the NAG Library from the Absoft 11.5 Fortran compiler. Two library DLLs are available for this purpose. Of these FLW3223DCL provides the marginally easier fit, but FLDLL234ML has more general application. It might be called from Excel or Visual Basic for example. (Please click here for details.) The better choice depends very much upon the users requirements.

Acknowledgements

The author is indebted to Amy Hutcherson and Peter A Jacobson from Absoft for their help and advice whilst examples of use were being prepared.

David Sayers August 2012.