Accessing Data

The basic means of storing and accessing data for ADAM is the Hierarchical Data System (HDS). SUN/92 describes this system and the DAT_ package of routines that are used to access data in this form. In HDS a data file contains a number of named components which can either be primitive items (numbers, character strings or arrays) or can themselves be structures containing further components.

To simplify the exchange of data between different applications packages, Starlink have released a set of standards for representing data within HDS. This is the Extensible N-Dimensional Data Format (NDF) - it is described in SGP/38. A library of subroutines (the NDF library, described in SUN/33) is provided for accessing these standard structures and will generally be used when writing applications.

Below is a simple example that calculates the mean value of the data in an NDF. For such data files the data will be found in a component of the file, called .DATA.

      SUBROUTINE MEAN(STATUS)
      IMPLICIT NONE
      INTEGER STATUS
      INCLUDE 'SAE_PAR'
      INTEGER NELM                       ! Number of Data elements
      CHARACTER*(DAT__SZLOC) LOC         ! HDS locator
      INTEGER PNTR                       ! Pointer to Data
      REAL MN                            ! Mean value of data

* Start an NDF context
      CALL NDF_BEGIN

* Get locator to parameter
      CALL NDF_ASSOC('INPUT','READ',LOC,STATUS)

* Map the data array
      CALL NDF_MAP(LOC,'DATA','_REAL','READ',PNTR,NELM,STATUS)

* If everything OK calculate mean value of data array and output it
      IF (STATUS .EQ. SAI__OK) THEN
          CALL MEAN_SUB(NELM,%VAL(PNTR),MN)
          CALL MSG_SETR('MEAN',MN)
          CALL MSG_OUT(' ','Mean Value of Array is ^MEAN',STATUS)
      ENDIF

* End the NDF context
      CALL NDF_END(STATUS)

      END


      SUBROUTINE MEAN_SUB(NELM,ARRAY,MEAN)

*  Subroutine to calculate the mean value of the array

      IMPLICIT NONE
      INTEGER NELM
      REAL ARRAY(NELM)
      REAL MEAN
      INTEGER I

      MEAN = 0.0
      DO I=1,NELM
         MEAN = MEAN + ARRAY(I)
      ENDDO
      MEAN = MEAN / NELM
      END

There are a number of points to note about this example:

• The routine NDF_ASSOC is analogous to SGS_ASSOC as used in the previous example. It returns an NDF identifier associated with an ADAM parameter (INPUT).

• The routine NDF_MAP returns a pointer (PNTR) to the data array. PNTR is an integer variable which contains the memory address of the data. Mapping is used in applications of this type as an alternative to reading the data into an array. The advantage of mapping is that we don't have to make a guess at the maximum size of array we expect, in order to know how big an array to declare. NDF_MAP will return a pointer to a real array. If the original data is of a different type it will be converted to real.

• The pointer concept is not supported in standard FORTRAN, but can be made use of in VAX FORTRAN by passing the pointer to a subroutine using the %VAL(PNTR) construct. In the subroutine (MEAN_SUB in this case) the corresponding parameter can then be treated as if we had passed the actual array.

• The routine NDF_END is called to end the current NDF context and unmap the mapped data array. For more information on NDF contexts see SUN/33.

The interface file for this example could be as follows:

INTERFACE MEAN

   PARAMETER INPUT
      TYPE NDF
      POSITION 1
      VPATH PROMPT
      PPATH CURRENT
      PROMPT 'NDF to calculate Mean Value from'
   ENDPARAMETER

ENDINTERFACE

The above example shows how to handle the case where an NDF file is used for input. Where output to an NDF file is involved it is usually necessary to create a new HDS file when the application runs. This can be achieved using routine NDF_CREAT or NDF_CREP. For details of their usage, see SUN/33.