Frequently Asked Questions

[ Question | Answer | Illustration | See Also ]

Question

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

Answer

This FAQ is specific to the OpenVMS operating system, please check FAQ T.08 and routine UXIDL for its adaptation to other operating systems
In IDL, under the operating systems VAX/VMS and OpenVMS/AXP, the CALL_EXTERNAL function provides an easy-to-use access to routines of the sharable image unilib.exe. Briefly, the synopsis of CALL_EXTERNAL is as follows:

      status = CALL_EXTERNAL( 'unilib', '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.

Source

; unilib_init.pro
;
 PRO unilib_init
;
;    Check that a logical is defined
;
     testdef  =  TRNLOG( 'unilib', content) mod 2  
     IF NOT testdef THEN BEGIN
        PRINT, 'The logical UNILIB has to be defined before running IDL'
        PRINT, 'Please type the following DCL command:'
        PRINT, '$ DEFINE UNILIB my_disk:[my_directory]UNILIB.EXE'
        EXIT
     ENDIF
     MESSAGE,  'File '+ strtrim( content, 2)+ ' linked', /informational
;
;    Define the different structures
;
     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, label:     0b, 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 libray
;
;    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', '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

G.06 How to start using the UNILIB library ?