-----------------------------------------------------------------------------
DICOM DATA DICTIONARY IN DCMTK
-----------------------------------------------------------------------------

In DICOM, the Data Dictionary (part 6 of the DICOM standard) stores for all
tags their respective VR, VM, attribute name and other information.  This
information must also be made available in DCMTK.  This is accomplished
through a global data dictionary class.

The global data dictionary is loaded within a C++ constructor into the global
DcmDataDictionary class instance called dcmDataDict once it is accessed for the
first time from the code.  The dictionary content is populated by three
different approaches:  Either the content (tags, VR, ...) can be compiled
into the dictionary code, or the dictionary is filled by loading a text file
on startup from a pre-defined file path (also called an "external" data
dictionary).  Lastly, DCMTK will load one or more additional external
dictionaries from the path set in the environment variable DCMDICTPATH, if set.

The built-in approach offers the advantage that a binary will not have to
load any information from a separate file which may get lost or or used in an
outdated version.  Loading the dictionary content from a separate file,
however, has the advantage that application programs need not be recompiled
if additions or corrections are made to the data dictionary.

DCMTK uses an external data dictionary per default on Posix systems (Linux,
Mac OS X, etc.) while a built-in dictionary is used on Windows systems. How
these defaults can be changed or how both approaches can even be combined
is further explained below.

-----------------------------------------------------------------------------
DICTIONARY DEFAULT: AUTOCONF ON POSIX SYSTEMS
-----------------------------------------------------------------------------

By default on a Posix system the global data dictionary will attempt to load
the data dictionary from an external file.  The location is pre-configured
to $DCMTK_DAT_DIR/dicom.dic where $DCMTK_DAT_DIR is DCMTK's data
installation prefix chosen using configure's --datadir option (default:
/dcmtk).  See also --datarootdir and --prefix options. The resulting path is
stored as DCM_DICT_DEFAULT_PATH in the file
config/include/dcmtk/config/osconfig.h, which is created by autoconf
during the execution of the configure script and thus is available to the
dictionary code that includes osconfig.h.

-----------------------------------------------------------------------------
DICTIONARY DEFAULT: CMAKE ON WINDOWS AND POSIX SYSTEMS
-----------------------------------------------------------------------------

On Windows (and Posix if using CMake on this platform), the default behaviour
is to compile a fully-populated DICOM dictionary as global data dictionary
into the dcmdata library.  Thus, it is not required to load an external data
dictionary from a file and dcmdata will not try loading such a file by default.

-----------------------------------------------------------------------------
CHANGING DICTIONARY DEFAULTS
-----------------------------------------------------------------------------

Autoconf as well as CMake provide options to change their default dictionary
behaviour.  For autoconf, configure offers the options:

  --enable-external-dict    enable loading of external dictionary (default)
  --disable-external-dict   don't load external dictionary
  --enable-builtin-dict     enable loading of built-in dictionary (default)
  --disable-builtin-dict    don't load built-in dictionary

They can be used toggle both dictionaries on and off: If the external
dictionary is turned off, it is not tried to load it from any default
location.

When building with CMake, the related options are called

  - DCMTK_ENABLE_EXTERNAL_DICTIONARY
  - DCMTK_ENABLE_BUILTIN_DICTIONARY

-----------------------------------------------------------------------------
DICTIONARY LOAD ORDER AND USING MULTIPLE DICTIONARIES
-----------------------------------------------------------------------------

The built-in dictionary, if enabled, is always loaded first on startup,
followed by any external dictionary.  Data dictionary entries loaded later in
the load sequence override entries loaded earlier.

Note that most of the time (no matter whether using autoconf or CMake) it
makes sense to enable only the built-in dictionary or only the external
dictionary. If both external and built-in version are enabled, the global data
dictionary is populated first with the compiled-in data, and afterwards the
external dictionary is loaded. If the latter is the default one shipping with
DCMTK (dicom.dic) then the external dictionary provides no extra information
since it contains exactly the same data as the built-in one but only takes time
loading.  Thus it only makes sense to use enable both options if the external
dictionary is modified to include (only) additional information not available in
the built-in dictionary.

If the user disables both options, no dictionary will be loaded per default
on startup.  However, a dictionary can be defined using the DCMDICTPATH
environment variable (see below).  If DCMDICTPATH is used, the default external
dictionary will not be loaded at all.

Application programs should check that a data dictionary has been loaded
before using the functionality of the dcmdata library.  The absence of
a data dictionary is likely to cause unexpected behaviour (e.g. unknown
attributes will be encoded using VR=UN).

-----------------------------------------------------------------------------
CUSTOM EXTERNAL DICTIONARIES THROUGH ENVIRONMENT VARIABLE "DCMDICTPATH"
-----------------------------------------------------------------------------

Sometimes it makes sense to change the dictionary that should be loaded
without recompiling the source code.  This can be done either be modifying
the dicom.dic that is already loaded, or, by specifying a different location
in an environment variable that is evaluated on DCMTK startup.  That
enviornment variable is called "DCMDICTPATH" and is considered on Windows
and Posix platforms.  If DCMDICTPATH is not set, the behaviour described in
the the sections above takes place (built-in and/or external dictionary from
default path is loaded).

Otherwise, the file provided in the environment variable DCMDICTPATH is loaded
and any default external dictionary is ignored(!).  However, note that the
built-in dictionary (if configured) will be always loaded.

In order to set DCMDICTPATH on Unix, the csh shell command

  setenv DCMDICTPATH $HOME/dicom.dic

would cause all applications using the dcmdata library to load the data
dictionary dicom.dic from the users home directory.

For Windows, the call

  set DCMDICTPATH=c:\dicom.dic

will cause all applications using the dcmdata library to load the data
dictionary dicom.dic from the main directory on drive C.

-----------------------------------------------------------------------------
USING MORE THAN ONE EXTERNAL DICTIONARY
-----------------------------------------------------------------------------

The DCMDICTPATH environment variable can even contain several data
dictionaries separated by colons (":") on Unix systems, and semicolon on
Windows systems.  Thus the Unix csh command:

  setenv DCMDICTPATH /usr/local/share/dcmtk/dicom.dic:$HOME/dicom.dic

would cause all applications using the dcmdata library to first load the
default data dictionary and subsequently load the data dictionary dicom.dic
from the users home directory.  On Windows systems, an example could be

  set DCMDICTPATH=c:\dcmtk-install\share\dcmtk\dicom.dic;c:\dicom.dic

Also here, data dictionary entries loaded later in the load sequence override
entries loaded earlier.

-----------------------------------------------------------------------------
DATA DICTIONARIES INCLUDED IN DCMTK (DICOM.DIC, PRIVATE.DIC AND BUILT-IN)
-----------------------------------------------------------------------------

An example DICOM data dictionary can be found in dcmdata/data/dicom.dic
which is also installed (using autoconf or CMake) and used as the default
external dictionary (if external default dictionary is enabled).

The example data dictionary is relatively complete and includes all
standard DICOM tags (see the header of the file, where the implemented
version of the standard plus all supplements and CPs are listed), obsolete
ACR/NEMA version 2 tags, obsolete SPI tags, and the tags used by Papyrus
version 3.  An early version of this data dictionary was based on a data
dictionary put together by David Clunie.

Another example dictionary included is the dcmdata/data/private.dic which
includes any private tag information known to DCMTK developers and partly
taken over from other DICOM toolkits and various other sources like
Conformance Statements.  There is no guarantee that the tag information
contained is valid or even complete.  Per default, this dictionary is not
taken into account.  It can be enabled to load on startup as an extra
external dictionary using autoconf's configure option "--enable-private-tags"
and in CMake using the option "DCMTK_ENABLE_PRIVATE_TAGS".  Enabling will
result in private.dic being added to the DCM_DICT_DEFAULT_PATH which lists those
external dictionaries to be loaded on startup (see above).  Note that the
private tag option is only considered for external dictionaries if external
dictionaries are not turned off.

DCMTK also includes two predefined built-in dictionaries, one fully populated
containing the information from DCMTK's dicom.dic file, and one that is empty.
Both are defined in dcdictbi.cc and the one to be used is selected by the
builtin dictionary build options (see above).

The code for a useful built-in data dictionary can be regenerated at any time
by the mkdictbi program (dcmdata/libsrc/mkdictbi).  The dcmdata library
Makefiles (for autoconf dcmdata/libsrc/Makefile.in, and for CMake
dcmdata/libsrc/CMakeLists.txt) include a target (updatebuiltindict) for this
purpose.  After regenerating dcdictbi.cc, rebuilding the libdcmdata.a library
and relinking all your applications will ensure that the built-in data
dictionary is used.

-----------------------------------------------------------------------------
TAG NAME CONSTANTS FOR USE IN APPLICATIONS
-----------------------------------------------------------------------------

The include file dcmdata/include/dcmtk/dcmdata/dcdeftag.h can be generated
from a data dictionary by the program mkdeftag.  The include file defines
tag names for use in application programs.  The names are generated from
the names specified in the data dictionary.  Duplicate names in the data
dictionary will result in compiler warnings due to duplicate #define's
when compiling code which includes the dcdeftag.h header file.  Thus, when
adding new entries to the data dictionary, care should be taken to ensure
that attribute names are not duplicated for distinct tags.
The dcmdata library Makefiles (for autoconf dcmdata/libsrc/Makefile.in and for
CMake dcmdata/libsrc/CMakeLists.txt) include a target (updatedeftag) which
builds the mkdeftag tool and uses it to generate the
dcmdata/include/dcmtk/dcmdata/dcdeftag.h header file.  The header file should
be regenerated whenever additions or name modifications are made to the data
dictionary.  Care should be taken before modifying any tag names since existing
application programs may already use the old name and might subsequently fail
to compile.

------------

OFFIS e.V., Oldenburg, Germany

Last revised: 2015-09-16 (Onken).