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

INCLUDE FILES

#include <cdds.h>

cdds.h provides the declarations required to access the DDS "C" API routines. It also defines symbolic names for API constants which can be used in the following examples:

#include <cdds.h>
      integer ier, i, bin, tag, ndx, rank, size[RANK_MAX];
      const char *out_dict, name[80];
      BIN_TAG out_bin;
      float *data;
      ...
      rank = cdds_scank("axis", "");
      cdds_scanf("size", "");
      for (i=0;i<rank,i++) {
         cdds_scanf("", "%d", size[i]);
      }
      ...
      /* enforce array limits when reading */
      cdds_scanf(data, "%80s", name);
      ...
      /* get index to trace header */
      tag = cdds_member(out_bin, 0, "SrPtXC");
      ndx = cdds_index(out_bin, tag, DDS_FLOAT);
      data = cdds_malloc(size(1)*sizeof(float));
      ...
      /* open binary output stream */
      out_bin = cdds_open(out_dict, "out_format", "out_data", "w+");
    

• 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 "C" types on the host computer. For example, DDS_FLOAT is "float4" when compiled on the Sun, and "float8x" when compiled on a Linux machine. This allows programs to remain portable and efficient, when defining and accessing fields within type buffers. These can be used for cdds_getxx, cdds_putxx and cdds_index routines.

  DDS_VOID       void
  DDS_PTR        void*
  DDS_CHAR       char
  DDS_SCHAR      signed char
  DDS_SHORT      short
  DDS_INT        int
  DDS_LONG       long
  DDS_LLONG      long long
  DDS_UCHAR      unsigned char
  DDS_USHORT     unsigned short
  DDS_UINT       unsigned int
  DDS_ULONG      unsigned long
  DDS_ULLONG     unsigned long long
  DDS_FLOAT      float
  DDS_DOUBLE     double
  DDS_LDOUBLE    long double
  DDS_CPX        complex               (Extensions)
  DDS_DBLCPX     double complex        (Extensions)
  DDS_LDBLCPX    long double complex   (Extensions)
          

• Symbolic names are defined for DDS types that are independent of the host data types.

  DDS_ASCII1         ascii
  DDS_EBCDIC1        ebcdic
  DDS_INTEGER1       1-byte integer
  DDS_INTEGER2       2-byte integer
  DDS_INTEGER2X      2-byte integer (Little Endian)
  DDS_INTEGER4       4-byte integer
  DDS_INTEGER4X      4-byte integer (Little Endian)
  DDS_INTEGER8       8-byte integer
  DDS_INTEGER8X      8-byte integer (Little Endian)
  DDS_UNSIGNED1      1-byte unsigned 
  DDS_UNSIGNED2      2-byte unsigned 
  DDS_UNSIGNED2X     2-byte unsigned (Little Endian)
  DDS_UNSIGNED4      4-byte unsigned 
  DDS_UNSIGNED4X     4-byte unsigned (Little Endian)
  DDS_UNSIGNED8      8-byte unsigned
  DDS_UNSIGNED8X     8-byte unsigned (Little Endian)
  DDS_FLOAT4         4-byte ieee float
  DDS_FLOAT4X        4-byte ieee float (Little Endian)
  DDS_FLOAT4IBM      4-byte ibm float
  DDS_FLOAT8         8-byte ieee float
  DDS_FLOAT8X        8-byte ieee float (Little Endian)
  DDS_FLOAT8IBM      8-byte ibm float
  DDS_FLOAT16        16-byte ieee float
  DDS_COMPLEX8       8-byte ieee complex
  DDS_COMPLEX8X      8-byte ieee complex (Little Endian)
  DDS_COMPLEX8IBM    8-byte ibm complex
  DDS_COMPLEX16      16-byte ieee complex
  DDS_COMPLEX16X     16-byte ieee complex (Little Endian)
  DDS_COMPLEX16IBM   16-byte ibm complex
  DDS_COMPLEX32      32-byte ieee complex
          

• Predefined API types (typedef).

  typedef int BIN_TAG   (Binary Tag type)
  typedef int SYM_TAG   (Symbol Tag type
          

• 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 cdds_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
          

cfft.h provides definitions needed for the cfft wrapper routines.

LIBRARY FILES

FILES

$DDSROOT/include/cdds.h          "C" DDS interface
$DDSROOT/include/cfft.h          "C" FFT interface

$DDSROOT/lib/$TARCH/libdds3.a    DDS library
$DDSROOT/lib/$TARCH/libgio.a     GIO library
$DDSROOT/lib/$TARCH/libchost.a   "C" Host-dependent lib