sdshead

This Source-Navigator, an IDE for C/C++/Fortran/Java/Tcl/PHP/Python and a host of other languages.

Sds header description
In order 

struct sds_header {
  magic_number:4 bytes:value 0x 50 42 xx 43
               'xx' indicates the architecture of the machine on which the
               dataset was generated, or the last conversion. These are
               defined in the header sds_mdep.h: padding and size
               information are contained in sds_glob.c and accessed through
               functions in that file. When loading a dataset, its byte
               ordering is determined by the full pattern.
  controlbits:2 bytes:As of writing, (Fri Sep 30 12:16:28 EDT 1994) this
               is used to contain flags for controlling conversion to and
               from 32 and 64-bit address machines. Also, a bit may be
               used to indicate if eg a 680x0 padded datset is also, in
               fact, risc padded.
  version
  heap_size
  list_size
}
char   heap[heap_size]
               Contains the 'nameheap': heap_size bytes composed of
               a number of zero-terminated strings which are all
               the component names of user objects. The direc
               structure (below) points into here; string ordering
               is important as sub-object names are sequentially
               accessed according to the structure definitions.
struct type_list[list_size/4]
 {
 sds_code        nelems;  
 sds_code        elemcod;
 }
 This array of structures (in reality, array of unions; the union type
 is held in signal bits in the elemcod) describe the data structure of the
 user object. elemcod contains a code for the data type: this is either a
 primitive type (see sds_mdep.h for these) such as SDS_FLOAT, or is or'd
 with SDS_INDLIST (== 0x80000000) to indicate a complex data type: in this
 case, (elemcod & ~SDS_CODE_MASK) will point to the element number of the
 typelist structure where the definition of this complex type begins. 
 (SDS_CODE_MASK simply indicates the MSB, where all modifier flags sit).
 In addition, the end of a complex type is signalled by SDS_RETLIST, and
 the end of a complete type_list structure by SDS_ENDLIST. In an assembled
 dataset header, SDS_LENLIST, which will appear at the beginning of a
 complex type definition, indicates that nelems points into the header name
 heap: names begin at (&heap + (nelems & 0xffff)), and there are 
 (nelems >> 16) names in this particular list. SDS__SIZE_ALIGN, the next
 elemcod in the list, indicates that nelems gives the structure size in
 bytes (that is, the size of one element of the structure - as given by
 sizeof()) and (elemcod & 0xff) shows the byte alingment of the structure.

struct direc[N]
                       Each element of this structure refers to a data object:
                       direc[0] refers to the directory object itself, so,
                       for instance, the number of USER objects is
                       direc[0].nelems - 1. This structure should never be
                       accessed directly by the user.
{
  offst: 4 bytes;      /* offset from memory start */
  nelems: 4 bytes;     /* # elements */
  elemsz: 4 bytes;     /* size in bytes of 1 element */
  elemcod: 4 bytes;    /* code of the type */
  wtime: 4 bytes;      /* last write time  */
  structype: 2 bytes;  /* is it a list etc? */
  align_type: 1 bytes; /* alignment type  */
  illoca: 1 bytes;     /* reallocation flag */
  obj_name: 4 bytes;   /* name offset of the object */
}

After this come the user objects. There is NO further SDS meta-data
embedded in this data: each is guaranteed to lie on the proper byte
boundary for the local architecture. If fast access is required, casting to
the appropriate compiled-in structure definition will work.

Note: when loading in an Sds, the following sequence happens when NO
information is available as to size, architecture and so on:

1. Load 4 bytes. Here you can check a. Is this (probably) an Sds?
   b. Which byte-order and architecture?
2. Load next 8. This gives you address size (32 or 64) and extra pad
  information, plus version (not needed yet, all datasets so far obey the
  same layout spec) and two variable byte sizes.
3. Load in name heap and typelist, and the FIRST directory element (this
  directory element must be massaged slightly if address size is changing).
  Now one knows the number of user objects and so
4. Load in the rest of the directory.Now I have all information necessary
  for loading in the rest of teh dataset; each object is correctly sized
  (both for the local architecture and for the original, if different.) Note
  that data objects MAY have zero multiplicity (ie only the definition is
  there) or they MAY be marked 'disjoint' - that is they have a non-zero
  multiplicity but are not in this byte  stream - they exist somewhere else.
  As to where, I don't have any idea IN THE DATASET HEADER: when this has
  been implemented so far, the extra meta-data is contained in USER objects -
  for instance, objects which name datafiles in the local file system, which
  may then be mapped into process memory for access. These extra conventions
  need to be defined as requirements become clearer - this is basically the
  SDS way of ensuring that extra meta-information can be put into datasets as
  necessary.

As an example, we can look at a common Sds dataset used in several test
programs:

---------------------------------------------------------------------
 dataset 'test data' 2 user objects created Wed Mar  9 11:11:35 1994
- Sds version 3.000000 --------------------------------------------------
   flibble Structure
      x-offset Float
      y-offset Float
      x-scale Float
      y-scale Double
      x-units C-String[12]
      y-units C-String[12]
      point-style Long32
      line-style Byte
      x-object Long32
   data Long32[512]

Desribing the header in more detail, we have:

      magic 0x50420543
      version 0x3
      tlist size 104 bytes
      heap size 108 bytes

( note that od -x on this file gives the first 4 bytes as 0543 5042: this 
  indicates that the generation architecture if "the wrong way round" [or
  the right way, depending on your persuasion]).

type list:
0: 9000a code 10000000 << SDS_LENLIST set; 9 names start at heap offset 0xa
                          (that is, the 9 names of the 'flibble' structure,
                          starting with 'y-offset')
1: 38 code 20000004    << SDS_SIZE_ALIGN set: structure size is 0x38 bytes,
                          it goes on a 4-byte boundary. (This description
                          is from an Intel-486 generated dataset).

2: 1 code 8            << One float, followed by...
3: 1 code 8            << ....another...
4: 1 code 8
5: 1 code 9            << ...a double...
6: c code d            << ...two 12-byte C-strings
7: c code d            << (that is, they are zero-terminated)
8: 1 code 6            << ...a 4-byte integer...
9: 1 code 2            << a single byte (Sds marks this 8-bit integer as
                          such: display code will not treat it as a character)
a: 1 code 6            << ...another 4-byte integer.
b: 0 code 40000000     << End of this structure definition
c: 0 code 40000001     << ...and, actually, the end of the full list.
***********************
Name heap: it starts with the dataset name 
(not necessarily the name of where it came from, its "storage name"):

    0| 74 65 73 74 20 64 61 74 61  0 78 2d 6f 66 66 73 |test data.x-offs
   10| 65 74  0 79 2d 6f 66 66 73 65 74  0 78 2d 73 63 |et.y-offset.x-sc
   20| 61 6c 65  0 79 2d 73 63 61 6c 65  0 78 2d 75 6e |ale.y-scale.x-un
   30| 69 74 73  0 79 2d 75 6e 69 74 73  0 70 6f 69 6e |its.y-units.poin
   40| 74 2d 73 74 79 6c 65  0 6c 69 6e 65 2d 73 74 79 |t-style.line-sty
   50| 6c 65  0 78 2d 6f 62 6a 65 63 74  0 66 6c 69 62 |le.x-object.flib
   60| 62 6c 65  0 64 61 74 61  0  0  0  0             |ble.data....
***********************

Now the directories: first element describes itself:
      name offset 0x0
      data offset 0xe0 
      timestamp 0x2d7df537 
      code 0xe 
      number of elements 3 
      size of element 28 
      reallocation flag 0 
      structure type 0 
      align 4
****************
      name offset 0x1005c
      data offset 0xfffffffe 
      timestamp 0x0 
      code 0x80000000 
      number of elements 1 
      size of element 56