trend

- 4

Trapped Radiation ENvironment model Development

Frequently Asked Questions

[ Question | Answer | Illustration | See Also ]

Question

    T.10 - How to call the library from a Win32 application ?

Answer

    In order to access directly the Unilib library from a Win32 application, a new version of the unilib.dll dynamic library (distributed in the archive file unilib_win32.zip) has been generated. In this version, several Unilib routines have been exported:
      UA610, UA630, UD310, UD317, UD330, UF410, UF420, UL220, UL230, UL240, UM510, UM520, UM530, UM535, UM536, UM539, UT540, UT541, UT542, UT545, UT546, UT547, UT550, UT555, UT556, UT980, UT990 and UT998.
    The distribution also contains an import library unilib.lib allowing implicit linking and a sample C code and include file (test_dll.c and unilib.h).

    For more information on load-time and/or run-time dynamic linking, please consult the manual of your favorite compiler and linker. The sample C code included in the distribution and discussed below has been test using Microsoft Visual C++.

Illustration

    Before accessing the Unilib subroutines, their synopsis has to be defined in an include file. For example, the Fortran sypnopsis of the subroutine UM510 is
          INTEGER*4      kint, kunit, ifail
          REAL*8         year
          CHARACTER*32   lbint
          CALL UM510 (kint, year, lbint, kunit, ifail)
    In C, it can be translated as
      void CALLBACK UM510 (long*, double*, char*, unsigned long, long*, long*);
    For strings, note that Win32 Fortran passes a hidden length argument by value that has to be provided by the C programme. The other arguments are always passed by reference. When defining a structure, e.g /zgeo/, the order of the variable list has to be the same as in the header file structure.h, i.e.
      typedef struct UNILIB_RECORD_ZGEO
         { double RADIUS;
           double COLAT;
           double ELONG; } RECORD_ZGEO; 
      

    Some subroutines, such as UM510, generate text output through Fortran WRITE statements. The Win32 application has to define a handle for the standard output in order to intercept the messages sent to file unit 6. This can be done by allocating a console by a call to the Win32 function AllocConsole().

    Inside the Win32 application, a typical call to UM510 reads

          long   kunit=6, ifail=0, kint=0;
          double year=1985.; 
          char   label[33];  // Fortran strings are not null-terminated:
          label[32] = '\0';  // reserved 33 bytes and set the null character.
      
          /* ... */
      
          UM510(&kint, &year, label, 32, &kunit, &ifail);
          if ( ifail < 0 ) exit(-1);
      
    Be aware to reserve and pass the correct length when string arguments are used. Fortran strings are not null-terminated, and are padded with blank spaces.

See Also

    T.07   Which subroutines are mandatory?

    [@] MSDN Library, DLLs overview (Microsoft Visual C++)
    [@] MSDN Library, Handling Data Types in Multiple Languages (Microsoft Visual C++)