NAME
dds - Data Dictionary System, end user overview
SYNOPSIS
Data Dictionary System, end user overview.
DESCRIPTION
The Data Dictionary System allows parameter definitions and
binary data to be exchanged among application programs and
end users. This manual page provides an overview of DDS and
available documentation. Many concepts were borrowed from
the Stanford Exploration Project SEP lib utilities.
The following documentation is available for end users of
DDS applications. Application programmers should also
review it, to maintain a consistent user interface.
tab(|); lB l. dds(1)|(this) end user overview
dds_user(1)|generic guide for DDS applications
dds_apps(1)|list of current DDS applications dds_usp(1)|USP
seismic format description dds_segy(1)|SEGY seismic format
description dds_disco(1)|Disco seismic format description
dds_rosetta(1)|Rosetta stone for standard formats
dds_map(1)|algebraic notation for field maps
dds_device(1)|tape and disk device attributes
dds_format(1)|generic DDS format description dds_type(1)|DDS
binary data types dds_expert(1)|advanced topics for end
users dds_help(1)|what to do, when things go wrong
Programmers may use either the "C" or Fortran Application
Program Interface. They are documented by the following:
tab(|); lB l. cdds_api(3)|"C" Application Program Interface
c_tutorial(3)|verbose commentary for c_template.c
cdds_*(3)|"C" API functions
fdds_api(3)|Fortran Application Program Interface
f_tutorial(3)|verbose commentary for f_template.f
fdds_*(3)|Fortran API functions
DICTIONARY versus DATA
Information is divided into two categories, parameter dic-
tionaries and binary data. Dictionaries and binary data are
normally kept in separate disk file. When pipes are used,
data follows a dictionary in the stream. These conventions
may be circumvented, when mixing DDS and non-DDS applica-
tions.
Definitions are kept within dictionaries (plain text files).
They describe processing history and meta information about
the binary data. Dictionary support emphasizes convenience
and flexibility, for small quantities (<< 1 mb) of
information.
Binary data support emphasizes speed and efficiency, for
large volumes (>> 1 mb) of information. DDS supports a
variety of seismic formats (USP, Disco, SEGY, cube, ...)
and binary types (ieee, cray, ibm, ascii, ebcdic, ...).
DICTIONARIES
Dictionaries contain a chronological sequence of defini-
tions. Each dictionary is identified by its filename or a
special mnemonic. Dictionary names must not contain white
space (blanks or tabs). Names terminated by ":" (colon) are
reserved for mnemonics. Mnemonic dictionaries include
stdin:, stdout:, par:, cmd:, env:, and tmpxxx:.
Dictionaries are kept in plain (ascii) text. Each defini-
tion has a name and value. Definition names are a sequence
of non-white space characters (maximum of 63). Names within
dictionaries must be suffixed with '='. The value begins
with the first character following the '=' and continues
until the next name or EOF. Values must not contain "=",
unless escaped ("\="). Each definition within a dictionary
is like a sub-file; it has a name, byte sequence, and defin-
ition EOF. Example dictionary contents:
comment= example definition within dictionary
axis= t x y
size.t= 1024
size.x= 400
size.y= 200
delta.t= 4
units.t= msec
origin.x= 4800.
delta.x= 25.
units.x= feet
format= usp
data= /m/zwrk/zrls13/line207.usp
mixed= 123 3.14 abc "quoted string"
foo= values span multiple lines,
until the next definition.
bar= "oldest value" bar= "changed value"
bar= "newest value"
The same name may be defined more than once in a dictionary.
The most recent name defines the current value. Definition
names within dictionaries are scanned from bottom up and
right-to-left.
Definitions may be appended to dictionaries. If the name
already exists, the new definition re-defines the current
value. It is bad style to change the current value in
place; lying about the true history creates trouble. If a
definition must be changed, append a new one!
A name prefixed by "$" is an alias definition. It defines a
symbolic link between the original name and alias values.
The alias modifies the search for older definitions, but not
newer ones. The first definition name, that matches any
alias, is selected. This example illustrates alias basics:
FOO= normal definition, seen by $foo
comment= define alias names for "foo"
$foo= foo FOO Foo fOO
$bar= bar BAR Bar bAR
comment= relative order IS important
BAR= normal definition, NOT seen by $bar
comment= undefine "dead_end" (empty alias)
$dead_end=
comment= user defines an output format
out_format= segy charisma float 4 ieee
comment= alias "format" to user's override
$format= out_format
unit_test3= /long/path/name/test3.usp
comment= select unit test "3" input
$in_data= unit_test3
comment= an alias tree with branches, %^(
$a= a x
$b= b y
$c= c z
$abc_xyz= a b c
Definitions can not be commented out using "#", like lines
in a shell script. The "#" is simply another non-white
space character. Hint: a definition name can begin with
"#", i.e. "#in_data= example.test". This bizarre name
should elude routine searches, but can be easily activated
with an editor.
Comments do not exist within a dictionary. All characters
are either part of a definition name or value. Hint: any
innocuous name may be used to define a text value, i.e.
"comment= DDS Virus Strikes Again".
Remember, definition values must not contain "=", unless
escaped ("\=")!
Dictionaries can be manipulated by users with standard text
processing tools (vi, grep, cat, echo, lpr, ...). This
eliminates the need for auxiliary programs (utop, HMATH,
...) to perform analogous operations on seismic data. This
also reduces the software development, user training and
need for unique skills. Examples of commands applied to
dictionary line207:
% vi line207
% lpr line207
% grep cmd_name= line207
% grep data= line207
BINARY DATA
Binary data is described by a dictionary. The dictionary
contains many definitions that describe the binary data in
excruciating detail. The end user is primarely interested
in only two of these, data= and format=.
The current name for binary data is defined by data=. The
alias mechanism may be used to reference an override defined
by the user, i.e. "$data= in_data".
If binary data is stored on disk, its normally in a dif-
ferent file than the dictionary. The default filename for
the data is the dictionary name, with a suffix corresponding
to the current format. For example, a dictionary in file
"line5" may describe binary data in "line5.usp".
If binary data is attached to a dictionary then "data=
dict:". If a dictionary is written to a pipe, the binary
data is attached to it by default. Binary data can be
attached to a dictionary in a regular disk file, if expli-
citly requested. This "single disk file" technique has
several disadvantages that are non-obvious: The dictionary
can't be manipulated with standard text processing tools. A
small dictionary can't be preserved on disk, while keeping
massive data on auxiliary storage. Attached data is not
compatible with CM5 processing.
If data is not attached to a dictionary, it can be read from
standard input by defining "in_data= stdin:". Data can be
written to standard output, without a dictionary, by defin-
ing "out_data= stdout:". This technique may be used to
exchange data with USP (non-DDS) applications through a
pipe.
The current format of the binary data is defined by format=.
The alias mechanism may be used to reference an override
defined by the user, i.e. "$format= out_format".
DDS currently support three standard seismic formats, usp,
segy, and disco. All other format names are associated with
the generic DDS format.
It is unlikely that any single format will dominate the
seismic industry, or even Amoco. Many applications can pro-
cess seismic data in one standard format, such as usp, segy,
disco, Western, Geoquest, Landmark, Promax, etc. If the
format and application are not compatible, then the data
must be converted. Conversion may introduce significant
overhead for storage, cpu, and turn around time. Worse, it
may mangle header information. End users often abandon
superior applications, because of conversion trauma.
DDS provides "Seamless Seismic Data Access". DDS applica-
tions can exchange data with existing software that use
standard formats. DDS applications have a broader customer
base, because they don't alienate all formats except one
standard.
FILES
tab(|); lB l. $(HOME)/.ddsrc|user default dictionary
$(DDS_PATH)/$(HOST).dds|host default dictionary
$(DDS_PATH)/site.dds|site default dictionary
$(DDS_PATH)/fmt_name.fmt.dds|format dictionary
$(DDS_PATH)/fmt_name.map.dds|mapping dictionary
/explprod/phase2/usp/dds|nominal DDS_PATH
~usp/man/man1/dds*.1|end user man pages
~usp/man/man3/cdds*.3|"C" API man pages
~usp/man/man3/fdds*.3f|Fortran API man pages
~usp/include/${TARCH}/cdds.h|C language interface.
~usp/include/${TARCH}/fdds.h|Fortran language interface.
~usp/lib/${TARCH}/libdds.a|DDS library.
~usp/lib/${TARCH}/librlsc.a|C main utilities.
~usp/lib/${TARCH}/librlsf.a|Fortran utilities.
~usp/lib/${TARCH}/libNoDisco.a|Dummy Disco linkage.
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