XMM-Newton Science Analysis System


dal (dal-1.199) [xmmsas_20230412_1735-21.0.0]

API Overview

F90 applications must use the module dal, to gain access to the DAL API.

The DAL is concerned with dataset access. A dataset is accessed with the function:

• dataSet( dataSetName, mode, memoryModel )

where,

• character(len=*), intent(in) :: dataSetName
  The name of the dataset.
• integer, intent(in) :: mode
  The access mode which the dataset should be used with. It must be one of the following values:
  • READ Read an existing dataset with the given name. An error is raised if the dataset is not found, or cannot be opened.
  • CREATE Create a new dataset with the given name. If an dataset already exisits with the given name, the behaviour is dependent on the setting of the environment variable SAS_FORMAT. Any changes made to the dataset will be discarded upon closure,
  • MODIFY Open an existing dataset with the given name. All changes made to the dataset will be written saved upon closure.
  • TEMP Open a new dataset. The dataset is discarded upon closure.
• integer, intent(in), optional :: memoryModel
  This specifies a hint to which the memory model should be used. The following values are possible:
  • HIGH_MEMORY
  • HIGH_LOW_MEMORY
  • LOW_MEMORY
  • USE_ENVIRONMENT

The code extract, shown below, is a typical example of how to use the dataSet() function:

program test
  use dal

  type(DataSetT) set                    ! Declare a dataset handle.

  set = dataSet( "myset", CREATE )      ! Create a dataset called "myset", with
                                        ! the High Memory Mode. A handle of
                                        ! the newly created dataset is returned
                                        ! and assigned to the variable set.

  ! ........................................
  !
  ! Do some operations on the dataset, using
  ! the handle set.
  !
  ! ........................................

  call release( set )                  ! Close the dataset.

end program

The dataset() function returns a handle to a dataset. This handle is used to specify the dataset in subsequent operations. The handle itself is opaque, in that its contents may not be accessed to perform dataset operations. The idea is to think of the handle as being an abstract object called a dataset.

The release function is used to close the dataset (the handle of the dataset is passed as a parameter). The behaviour of the release is dependent on the access mode which was used to access the dataset.

Most DAL procedures(functions and subroutines) require a handle as one of the arguments and/or returns a handle value. In many cases a procedure has been overloaded to operate on objects of different types. These have been provided in the form on interfaces. For example, the release interface operates on datasets, blocks, arrays, tables and columns.