Overview and tutorial on the Fortran Application Program Interface (API) to the Data Dictionary System.

INCLUDE FILES

#include "fdds.h"		Use with fixed-format sources.
#include "f90dds.h"		Use with free-format sources.
use dds		A module with most of DDS defined. Module read/write functions support 1D buffers only.

Strong type checking of API function calls is only available with use dds, but the module does not define interfaces for all the sample types and only understands 1 dimensional I/O buffers.

These header files provide the declarations for all DDS API functions except for fdds_initopenmp and fdds_initmpi. These two should be declared manually when they are needed. Many named constants are also defined by the header files and module. The meaning of these is shown in the following examples:

#include <fdds.h>
      integer ier,i,bin,tag,ndx,rank,size(RANK_MAX)
      character*(PATHNAME_MAX) out_dict, name
      integer out_bin
      real data(*)
      pointer (ptr_data,data)
      ...
      rank=fdds_scank('axis',' ')
      ier=fdds_scanf('size','\0')
      do i=1,rank
         ier=fdds_scanf(' ','%d\0',size(i))
      enddo
      ...
!     enforce array limits when reading
      ier=fdds_scanf(data,'%'//PATHNAME_MAXQ//'s\0',name)
      ...
!     get index to trace header
      tag=fdds_member(bin,0,'SrPtXC')
      ndx=fdds_index(bin,tag,DDS_REAL)
      ptr_data=fdds_malloc(size(1)*SIZEOF_REAL)
      ...
!     open binary output stream
      bin=fdds_open(out_dict,'out_format','out_data','w+')
    

• Data Type Sizes (used for memory allocations)

  SIZEOF_INTEGER
  SIZEOF_INTEGER2
  SIZEOF_REAL
  SIZEOF_DOUBLE
  SIZEOF_COMPLEX
  SIZEOF_DBL_CPX
          

• Max Character String Sizes (Integer type suitable for character lengths and Character type suitable for scanf and printf usage.)

  Integer        Character       Max Characters 
  PATHNAME_MAX   PATHNAME_MAXQ   full filenames 
  DEFNNAME_MAX   DEFNNAME_MAXQ   definition names
  AXISNAME_MAX   AXISNAME_MAXQ   axis names
  UNITNAME_MAX   UNITNAME_MAXQ   units 
  BASENAME_MAX   BASENAME_MAXQ   base names (not used)
          

• Symbolic names are defined for DDS prime types that correspond to Fortran types on the host computer. For example, DDS_REAL is "float4" when compiled on the Sun, and "float8x" when compiled on a Linux ssytem. This allows programs to remain portable and efficient, when defining and accessing fields within type buffers. These can be used for fdds_getxx, fdds_putxx and fdds_index routines.

  DDS_CHARACTER  Character type
  DDS_LOGICAL    Logical
  DDS_LOGICAL1   Logical*1
  DDS_INTEGER    Integer
  DDS_INTEGER2   Integer*2
  DDS_REAL       Real
  DDS_DOUBLE     Real*8
  DDS_COMPLEX    {real, imag}
  DDS_DBL_CPX    {real*8, imag*8}
          

• fdds_lseek whence values

  SEEK_SET       Seek absolute position
  SEEK_CUR       Seek relative to current position
  SEEK_END       Seek relative to End-of-File
          

• fdds_read and fdds_write field tag as alternative to "0" (Trace SEQUENCE) when desiring to deal with byte stream directly without making use to the DDS mapping capabilties.

  DDS_STREAM     1-byte type size
  DDS_STREAM2    2-byte type size (Big Endian)
  DDS_STREAM4    4-byte type size (Big Endian)
          

• DDS_DEBUG options. DDS application debug control (on, off, one-time). Application users may set debug flags by defining dds_debug, DDS_DEBUG, dds_dump, or DDS_DUMP. Flags set by calling fdds_check are OR'd with defn flags.

  DDS_DBG_HEAP      (check heap once, right now)
  DDS_DBG_ALLOC     (check heap on each allocation)
  DDS_DBG_FREE      (check heap on each free)
  DDS_DBG_CALL      (check heap on each DDS API call)
  DDS_DBG_TRACE     (trace all API calls)
  DDS_DBG_SCANNER   (trace compiler scanner)
  DDS_DBG_SYMBOL    (dump binary symbol tables)
  DDS_DBG_UNCOMPILE (dump ddsUncompileFmt stacks)
  DDS_DBG_BINARY    (dump binary ? tables)
  DDS_DBG_PANIC     (dump binary tables on panic)
          

• Other utility predefined parameters

  RANK_MAX       maximum axis rank (9)      
  DDS_TRUE_KEY   true TRUE True t T yes YES Yes y Y
  DDS_FALSE_KEY  false FALSE False f F no NO No n N
  DDS_HELP_KEY   help HELP Help -help -HELP -Help -h -H -?
  DDS_HELP_ALIAS help HELP Help -help -HELP -Help
          

use dds - I/O buffer limitation

Despite the DDS module restriction that I/O buffers must be 1D, some compilers are known to create functional executables when a single trace is passed to the DDS I/O function with a trace count greater than 1. This practice is discouraged because Fortran compilers are allowed to pass copies of array sections when they choose.

      use dds
      integer :: nsmp, ntrc, fd_out
      real, allocatable :: data(:,:)
      ...
      allocate(data(nsmp, ntrc))
      ...
      ! When using #include "*.h" files
      ! ier = fddx_write(fd_out, data, ntrc)

      ! When using the dds module as intended:
      do itrc=1,ntrc
        ier = fddx_write(fd_out, data(:,itrc), 1)
      enddo

      ! A risky multi-trace write when using the dds module
      ier = fddx_write(fd_out, data(:,1), ntrc)
    

FFT wrappers

fft.h (or f90fft.h) provides definitions needed for the fft wrapper routines.

LIBRARY FILES

FILES

$DDSROOT/include/fdds.h          Fixed-format Fortran declarations
$DDSROOT/include/f90dds.h        Free-format Fortran declarations
$DDSROOT/include/fft.h           Fixed-format Fortran FFT interface
$DDSROOT/include/f90fft.h        Free-format Fortran FFT interface
$DDSROOT/src/lib/dds3/dds.F90    Fortran 90 DDS/FFT module

$DDSROOT/lib/$TARCH/libdds3.a    DDS library
$DDSROOT/lib/$TARCH/libgio.a     GIO library
$DDSROOT/lib/$TARCH/libfhost.a   Fortran Host-dependent lib