European Space Agency

European Space Agency

Royal Belgian Institute for Aeronomy

Royal Belgian Institute for Aeronomy

../_images/whiteSpace.png

T.05 - How to pass correctly the subroutine arguments in IDL ?

Answer

This FAQ is specific to the OpenVMS operating system please check T.08 - (OLD) How to link the library in IDL/PV-WAVE ? and routine UXIDL() for its adaptation to other operating systems

In IDL, the CALL_EXTERNAL function provides an easy-to-use access to routines of the sharable image unilib.so/unilib.dll. Briefly, the synopsis of CALL_EXTERNAL is as follows:

status = CALL_EXTERNAL( 'unilib.so', 'idl_uXiii', P0, ..., Pn )

where uxiii is the name of the UNILIB routine and P0 to Pn are the n+1 parameters of the subroutine. The parameters are passed by reference. Be aware that it is the responsability of the user to check that the IDL variables are initialized to the correct data type. The floating-point variables have to be of type DOUBLE (corresponding to the FORTRAN type REAL*8) and the integer variables of the type LONG (corresponding to the FORTRAN type INTEGER*4). The same rule has to be applied for the structure (see illustration). Neglecting this rule, may lead to unpredictible behaviours of IDL. Note that, for string arguments, IDL passes to the library the string descriptor which includes the length of the string.

References

  • IDL Reference Guide, Research Systems Inc., Boulder

Illustration

The small IDL code showed below

  1. verifies that the logical unilib is defined;

  2. initializes the definition of the main structures used by the UNILIB library;

  3. calls the subroutine UT990.

; unilib_init.pro
;
 PRO unilib_init
;
;    Check the environment variable to the UNILIB library is defined
;
     solib = getenv( 'UNILIB')
     IF strlen(solib) eq 0 THEN MESSAGE, 'The UNILIB environment variable has to be '+       $
                                         'defined before running idl'
     MESSAGE,  'File '+ strtrim( solib, 2)+ ' linked', /informational
;
;    Define the different structures, also see unilib.pro
;
     dummy = {zxyz, x:      0.0d0, y:         0.0d0, z:     0.0d0}
     dummy = {zgeo, radius: 0.0d0, colat:     0.0d0, elong: 0.0d0}
     dummy = {zvec, dnrm:   0.0d0, rho:       0.0d0, theta: 0.0d0,     $
                    phi:    0.0d0}
     dummy = {zpnt, coord: {zgeo}, b:        {zvec}, rcurv: 0.0d0}
     dummy = {zseg, beg:   {zpnt}, arcl:      0.0d0, csalp: 0.0d0,     $
                    dtbnd:  0.0d0, rkstp: dblarr(3)}
     dummy = {zlbl, linv:      0b, lbmp:         0b,     $
                    lkauf:     0b, llmi:         0b, lalp0:    0b,     $
                    lphi:      0b, ltim:         0b, finv:  0.0d0,     $
                    fbmp:   0.0d0, fkauf:     0.0d0, flmi:  0.0d0,     $
                    falp0:  0.0d0, fphi:      0.0d0, ftim:  0.0d0}
     dummy = {zdat, iyear:  1950L, imonth:       1L, iday:     1L,     $
                    ihour:     0L, imin:         0L, secs:  0.0d0,     $
                    amjd:   0.0d0}
;
;    Call UT990 to initialize the UNILIB library
;
;    Note that the argument version is set to the correct type
;    before the use of the function CALL_EXTERNAL.
;
     version = 0L
     status  = CALL_EXTERNAL( 'unilib', 'idl_ut990_', -6L, 1L, version)
     IF version LT 0 THEN MESSAGE, 'Unable to initialize'+             $
                                   ' the Unirad Library'
     MESSAGE, 'Unirad Library v'+ STRCOMPRESS( STRING(                 $
                       version*0.01, format= '(f10.2)'), /remove_all), $
              /informational
;
 END

See also

UNILIB/tags/v3.02