NAME
dds_format - Data Dictionary System, binary data formats
SYNOPSIS
Data Dictionary System, generic data format.
DESCRIPTION
Standard formats have a reserved name (i.e. usp, segy,
disco, ...). They require a specific type sequence in the
data stream (line header, followed by traces) and specific
fields, within types (TrcNum, LASTTR, etc.). These restric-
tions are enforced by DDS. Standard formats are described
in other man pages: dds_usp(1), dds_segy(1), and
dds_disco(1). These formats use a subset of the generic DDS
format.
The generic DDS format is assumed, when the format name is
not a recognized standard. Generic formats may be very sim-
ple. For example, data may be accessed as a byte stream, or
as a cube of ieee floats. Generic formats may also be very
complex. This allows DDS to encompass many standard for-
mats, and allows new ones to be created as needed.
FORMAT
Formats are interpreted, starting from the format defini-
tion. It specifies the format name (root DDS type) and
attributes. Attributes are ignored, if they are not
relevant. Attribute defaults are based upon the format
name, media (tape, disk, pipe, ...), and mode (read, write,
update).
format= name attributes
tab(|); lI lB lB l. Name|Description disco|CogniSeis VDS or
tape format usp|Amoco USP format segy|SEGY standard
sep|Stanford Exploration Project cube|Samples only
cube_hdr|Header only cube_trc|Header and Samples
other|generic format
DDS automatically detects the attributes of input binary
data. If they conflict with attributes explicitly defined
by format, a warning is issued and the override is honored.
Output data attributes take predefined defaults, unless
explicitly overridden.
tab(|); lI lB lB l. Attributes|Description green|control
word prefix GREEN|control word prefix and suffix -green|no
green prefix -GREEN| ebcdic|SEGY card header ascii| integer
n|sample type and precision float n| ieee|sample style cray|
ibm| block_tape n{k/m}|tape block size
comment= standard SEGY tape format
format= segy
comment= same thing, explicitly
format= segy ebcdic float 4 ibm
TYPE DEFINITIONS
Type definitions are used to describe the structure of
existing binary data. This is distinct from format defini-
tions, which describe how to create DDS types. Type defini-
tions are saved in the dictionary used to describe the data.
DDS types are the fundamental unit for data transfer and
buffer mapping. The prime types predefined by DDS are
listed in dds_expert(1). Additional types may be derived by
combining prime types. Derived types form a tree structure,
whose root is the format name. The leaves are always prime
types. For example, usp is the root type for the USP for-
mat. Derived types include usp_trace, RecNum, and
usp_short. Prime types include integer2, integer4, float4,
and float8cray.
All types have an associated name, size, alignment and note.
Derived types may be simple or compound. Simple types con-
tain a single field. Compound types are either lists
(sequence of fields) or unions (coincident fields). Com-
pound types may also contain gaps, which reserve storage
that is not accessible by field name. Each field, within a
type, must have a unique name (subtype). Recursive type
trees are not allowed.
Type definition names are prefixed by "type:". They are
compiled into internal tables, when binary data is opened.
type:name= subtype size align "note"
comment= simple type definition
type:TVPair= usp_short 200 2 "Time/value pairs"
comment= default size, align, and note.
type:usp_short= integer2
comment= compound type, 3 field list
type:color= {red green blue} "true color type"
comment= compound type, 2 field union
type:nasty= <float4 float4ibm> "float kludge"
comment= two gaps (2 & 4 byte)
type:foo= {2 byte1 ying 4 byte1 yang}
comment= nested compound types
type:bar= {a <b c> d}
The type size specifies the number of elements (default is
1). A zero size does not reserve any storage nor influence
alignment. Negative values provide an indirect reference to
the dimensions defined by size, i.e. "-1" is the number of
points in the "first" dimension, "-2" the "second", etc.
The type align value may be specified, if size is present.
Positive values align the field starting position, negative
aligns the ending position. The position is a multiple of
the specified integer, relative to offset zero within the
parent type. If the value is zero (default), alignment is
inherited from the subtype.
The type note is a comment, surrounded by double quotes, for
human gratification. It should briefly document the purpose
of the type. The note is preserved with the type, like the
other attributes. Users may examine it within the diction-
ary. Interactive programs may retrieve it to annotate
displays.
DDS types are analogous to structured types in the C pro-
gramming languages, with a few exceptions. DDS types are
portable, i.e. host independent. Pointers and enumerated
types are not supported. Conversion routines are provided
between most DDS types and intrinsic types on the host com-
puter.
FORMAT DEFINITIONS
Format definitions describe how to derive DDS types, given
an old and new format. This is distinct from type defini-
tions, which describe the structure of existing binary data.
Format definitions reside in special dictionaries; normally
they are not in the history associated with binary data.
Standard and custom formats (disco, usp, segy, cube, sep,
...) are descibed within DDS_PATH/*.fmt dictionaries.
The cdds_open function builds a type table, when opening
binary data. The table is built from input type defini-
tions, if the data and definitions already exists. If not,
the table is built from format definitions. The type defin-
itions, implied by the table, are saved in the dictionary
that describes the binary data.
The format definition name implies three things: old for-
mat, new format, and new type. The definition value
describes the new type. The syntax is similar to type
definitions
fmt:old:new.type= subtype size align "note"
fmt:usp:disco.SHT-X= disco_float 1 0 "Shot X coord"
fmt:*:usp.RecNum= usp_short 1 0 "Record Number"
If old or type is "*" (wildcard), the definition matches any
old format or new type name. The new format name must match
the format associated with the type being created.
Attributes from existing type definitions may be substi-
tuted, within the value of format definitions. This is
specified by prefixing "$" to the type name. Substitution
is context sensitive and it provides defaults for remaining
attributes.
comment= type "yyy" is exactly like "zzz",
when creating format "xxx" from "*".
fmt:*.xxx.yyy= $zzz
comment= type "ALPHA" is a Disco float.
"beta" provides size, align and note.
fmt:*.disco.ALPHA= disco_float $beta
comment= substitute "size" from type zzz.
fmt:*.wild.thing= float4 $zzz 0 "bizzare"
Fields within compound types may be added or deleted, using
operators (+, -, ?). This allows trace headers to be exten-
sible, when combined with "$" substitution. The "-" opera-
tor deletes all previous fields named by the operand. "+"
first deletes and then appends the operand fields. The "?"
operator appends the operand field, if they don't already
exist. Operators are processed from left to right.
comment= vusp adds one field to basic usp trace
fmt:usp:vusp.vusp_trace= {$usp_trace + VspDepth}
fmt:usp:vusp.VspDepth= usp_float
comment= trace header only format.
"$target" yields fields from old format.
Drop and add provide end user control.
"- Samples" eliminates data field.
fmt:*:trc_hdr.trace_header= {
{$target} - {$drop_trc_hdr} + {$add_trc_hdr}
- Samples
} "Trace header only"
FORMAT DICTIONARIES
Format definitions are kept in special dictionaries. They
do not (normally) appear in the data history. Only the
derived type definitions are placed there.
Format dictionary names are derived from the new format
name. The path to format dictionaries is defined by
DDS_PATH. Multiple paths, delimited by white space, may be
defined. The last path normally contains the standard dic-
tionaries installed with DDS. The end user may provide for-
mat dictionaries for standard or custom formats. The first
dictionary in DDS_PATH that matches the new format name is
used by cdds_open.
tab(|); l lB lB l. Dictionary|Format usp.fmt|Amoco USP
segy.fmt|SEGY standard disco.fmt|Cogniseis Disco
sep.fmt|Stanford cube.fmt|float4 cube cube_hdr.fmt|header
only cube_trc.fmt|header and trace fIother.fmt|user format
SEE ALSO
tab(|); lB l. dds(1)|overview dds_user(1)|user guide
dds_map(1)|map expressions dds_expert(1)|symbolic names
dds_format(1)|generic format dds_disco(1)|Disco format
dds_usp(1)|Disco format dds_segy(1)|Disco format
dds_rosetta(1)|Rosetta Stone, "Standard" formats
cdds_api(3)|"C" Application Program Interface
fdds_api(3f)|Fortran Application Program Interface
AUTHOR
R. L. Selzler, APR, Tulsa
COPYRIGHT
copyright 2001, Amoco Production Company
All Rights Reserved
an affiliate of BP America Inc.
Man(1) output converted with
man2html