7 ACCESSING OBJECTS BY MAPPING

Another technique for accessing values stored in primitive HDS objects is termed “mapping”.2 An important advantage of this technique is that it removes a size restriction imposed by having to declare fixed size program arrays to hold data. This simplifies software, so that a single routine can handle objects of arbitrary size without recourse to accessing subsets.

HDS provides mapped access to primitive objects via the DAT_MAP routines. Essentially DAT_MAP will return a pointer to a region of the computer’s memory in which the object’s values are stored. This pointer can then be passed to another routine using the (non-standard, but widely available) Fortran “%VAL” facility,3 together with the CNF_PVAL function4 (described in SUN/209) which is defined in the CNF_PAR include file. An example will illustrate this:

        ...
        INCLUDE ’CNF_PAR’
        INTEGER PNTR, EL
  
  *  Map the DATA_ARRAY component of the NDF structure as a vector of type
  *  _REAL (even though the object is actually a 512 x 1024 array whose
  *  elements are of type _UBYTE).
        CALL DAT_FIND( NLOC, ’DATA_ARRAY’, LOC, STATUS )
        CALL DAT_MAPV( LOC, ’_REAL’, ’UPDATE’, PNTR, EL, STATUS )
  
  *  Pass the "array" to a subroutine.
        CALL SUB( EL, %VAL( CNF_PVAL( PNTR ) ), STATUS )
  
  *  Unmap the object and annul the locator.
        CALL DAT_UNMAP( LOC, STATUS )
        CALL DAT_ANNUL( LOC, STATUS )
  
        END
  
  *  Routine which takes the LOG of all values in a REAL array.
        SUBROUTINE SUB( N, A, STATUS )
        INCLUDE ’SAE_PAR’
        INTEGER N, STATUS
        REAL A( N )
        IF ( STATUS .NE. SAI__OK ) RETURN
  
        DO 1 I = 1, N
           A( I ) = LOG( A( I ) )
   1    CONTINUE
  
        END

This example illustrates two features of HDS which we haven’t already mentioned:

Vectorisation:
It is possible to force HDS to regard objects as vectors, irrespective of their true shape. This facility was useful in the above example as it made the subroutine SUB much more general in that it could be applied to any numeric primitive object.
Automatic type conversion:
The program can specify the data type it wishes to work with and the program will work even if the data is stored as a different type. HDS will (if necessary) automatically convert the data to the type required by the program.5 This useful feature can greatly simplify programming – simple programs can handle all data types. Automatic conversion works on reading, writing and mapping.

Note that once a primitive has been mapped, the associated locator cannot be used to access further data until the original object is unmapped.

2This terminology derives from the facility provided by some operating systems for mapping the contents of files into the computer’s memory, so that they appear as if they are arrays of numbers directly accessible to a program. Although HDS exploits this technique when available, other techniques can also be used to simulate this behaviour, so HDS does not depend on the operating system providing this facility.

3This technique works because Fortran normally passes the address of an array to a subroutine, so the routine is fooled into thinking it’s getting an array.

4We illustrate the use of the CNF_PVAL function in this document, although in most existing software which calls HDS this function is not used. It has been introduced because of the possibility that Fortran software which stores pointers in 32-bit INTEGERs may need to execute in circumstances where 64 bits are required to store a memory pointer. The purpose of the CNF_PVAL function is then to expand the pointer value out to its full size before use, if necessary. On currently-supported platforms, this step is not normally needed, so use of CNF_PVAL may considered optional. However, its inclusion in new software is recommended as a useful precaution.

5This will work even if the object was originally created on a different computer which formats its numbers differently.

Copyright © 2019 East Asian Observatory