===================================
DCMTK COMPILE TIME FLAGS AND MACROS
===================================
The behaviour of several DCMTK tools and libraries can be modified by
a number of compile time flags (macros), which are explained below.
Most of these macros enable experimental or rarely needed features
in DCMTK, others disable certain functions. So please, use with care!
ALLOW_ILLUMINATION_OVERRIDE
Affected: dcmprscu
Type of modification: Activates experimental or rarely used feature
Explanation: Allows the settings for Illumination and Reflected
Ambient Light, which are stored in a Stored Print object, to be
overridden from the print job command file.
BUGGY_IMPLEMENTATION_CLASS_UID_PREFIX
Affected: storescp
Type of modification: Activates workaround for known bug in other product
Explanation: The dcmnet module contains a workaround that allows to
communicate with some buggy Storage SCUs. If the global flag
dcmPeerRequiresExactUIDCopy is enabled, an illegal space padding in
the Affected SOP Instance UID field of the C-STORE-RQ message is
retained in the corresponding C-STORE-RSP message. When this
preprocessor macro is defined, it should contain the prefix of an
implementation class UID of an implementation known to exhibit the
buggy behaviour. The workaround is then activated in storescp
whenever a Storage SCU with the given implementation class UID root
connects.
DCMTK_BUILD_DATE
Affected: dcmdata
Type of modification: Toolkit customization
Explanation: When this macro is defined (typically in config/Makefile.def),
the given date is used instead of the official DCMTK release data. This
allows for example to specify the date of a current development snapshot.
DCMTK_GUI
Affected: all modules
Type of modification: Activates experimental or rarely used feature
Explanation: When this macro is defined, DCMTK re-assigns the standard
output and error streams maintained by ofConsole to string streams.
This will allow a GUI based application to extract the messages and
either present them to the user or store them in a log file. See
comments in ofstd/include/dcmtk/ofstd/ofconsol.h.
DICOMDIR_WITHOUT_BACKUP
Affected: dcmdata
Type of modification: Disables feature
Explanation: By default DCMTK creates a backup of an existing DICOMDIR
(using the name DICOMDIR.$$$) when a DcmDicomDir object is written
to file. The creation of the backup can be disabled with this macro.
DISABLE_COMPRESSION_EXTENSION
Affected: dcmqrdb
Type of modification: Disables feature
Explanation: Disables the support of compression (various transfer
syntaxes) in dcmqrdb, a feature which is still experimental.
DISABLE_OFSTD_ATOF
Affected: all modules
Type of modification: Disables feature
Explanation: By default, DCMTK uses its own implementation of atof()
to convert strings to double numbers in a locale-independent manner.
This flag forces DCMTK to use the standard sscanf() function
instead, which is normally much faster and gives a higher precision
than DCMTK's built in code, but is locale dependent, i.e. cannot be
used with locales such as German since DICOM decimal strings always
use the Posix locale.
DISABLE_OFSTD_FTOA
Affected: all modules
Type of modification: Disables feature
Explanation: By default, DCMTK uses its own implementation to convert
double numbers to strings to in a locale-independent manner.
This flag forces DCMTK to use the standard sprintf() function
instead, which is locale dependent, i.e. cannot be used with locales
such as German since DICOM decimal strings always use the Posix
locale.
DISABLE_RECV_TIMEOUT
Affected: dcmnet
Type of modification: Disables feature
Explanation: By default, DCMTK specifies a timeout of 60 seconds for
the recv() function. This is especially useful in cases where the
receiver (e.g. storescp) looses the connection to the sender because
the network cable is pulled on the sender side (e.g. for a mobile
device). This flag disables the call to the setsockopt() function
so that no timeout is specified.
DONT_DISABLE_NAGLE_ALGORITHM
Affected: dcmnet
Type of modification: Disables feature
Explanation: By default, DCMTK disables the so-called Nagle algorithm
for each DICOM transport connection. This provides a 2-4 times
performance improvement (WinNT4/SP4, 100Mbit/s Ethernet). Effects on
other environments are unknown. When compiled with this macro, the
code affecting the Nagle algorithm is disabled. See documentation
for environment variable TCP_NODELAY in config/docs/envvars.txt.
DONT_LOAD_EXTERNAL_DICTIONARIES
Affected: dcmdata
Type of modification: Disables feature
Explanation: By default, DCMTK loads data dictionaries from files at
application start (before the main function is called). These files
are either specified by the DCMDICTPATH environment variable or the
default files are used. This flag disables the loading of external
dictionaries from file at application start, which might be useful
when only the builtin dictionary should be used. However, if no
dictionary gets loaded, this is likely to cause unexpected behaviour.
Even if this flag is defined, the reloadDictionaries() method can be
used to load the external dictionaries after application start.
EXPERIMENTAL_READ_FROM_FILE
Affected: dump2dcm
Type of modification: Activates experimental or rarely used feature
Explanation: When this macro is defined, the relatively new function
createValueFromTempFile() is used for reading large binary data files.
HAVE_STD_STRING
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the ANSI C++ standard string
class is used instead of DCMTK's own implementation.
HAVE_STL
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) list, map, stack, vector and auto_ptr classes as well as
the STL algorithms are used instead of DCMTK's own implementations.
HAVE_STL_ALGORITHMS
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) algorithms are used instead of DCMTK's own implementation.
Also see HAVE_STL.
HAVE_STL_AUTO_PTR
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) auto_ptr class is used instead of DCMTK's own implementation.
Also see HAVE_STL.
HAVE_STL_LIST
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) list class is used instead of DCMTK's own implementation.
Also see HAVE_STL.
HAVE_STL_MAP
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) map class is used instead of DCMTK's own implementation.
Also see HAVE_STL.
HAVE_STL_STACK
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) stack class is used instead of DCMTK's own implementation.
Also see HAVE_STL.
HAVE_STL_VECTOR
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, the STL (standard template
library) vector class is used instead of DCMTK's own implementation.
Also see HAVE_STL.
LOCK_IMAGE_FILES
Affected: dcmpstat, dcmqrdb
Type of modification: Activates experimental or rarely used feature
Explanation: When this macro is defined, the DICOM image file to be
send or received/created is locked exclusively.
LOG4CPLUS_DISABLE_xxx
(where xxx is one of TRACE, DEBUG, INFO, WARN, ERROR and FATAL)
Affected: oflog
Type of modification: Disables feature
Explanation: When one of these macros is defined all log message of
this type and lower are disabled and optimized away.
NO_GET_SUPPORT
Affected: dcmqrdb
Type of modification: Disables feature
Explanation: Disables the experimental C-GET support in dcmqrdb.
NO_IOS_BASE_ASSIGN
Affected: all command line tools
Type of modification: Disables feature
Explanation: On Win32 platforms, the prepareCmdLineArgs() function
maps cout to cerr by assignment. This does not work with all
iostream implementations and can, therefore, be disabled with this
macro.
NO_PATIENTSTUDYONLY_SUPPORT
Affected: dcmqrdb
Type of modification: Disables feature
Explanation: Disables support for the Patient/Study Only Query/Retrieve
Model in dcmqrdb.
NO_WINDOWS95_ADDRESS_TRANSLATION_WORKAROUND
Affected: dcmnet
Type of modification: Disables feature
Explanation: Under Windows 95 gethostbyname will not accept an IP
address e.g. "134.106.1.1". This appears to work without problems
with other Windows versions and several Unix variants. As a
workaround, DCMTK explicitly handles the IP address case. The
workaround can be disabled with this macro.
OFCONDITION_IMPLICIT_BOOL_CONVERSION
Affected: ofstd
Type of modification: Activates experimental or rarely used feature
Explanation: Activates an implicit conversion from OFCondition to
OFBool, i.e. operator OFBool(). Implicit conversion might not always
be a good idea since it can hide unwanted constructs. Therefore,
this operator is disabled by default.
OFCONDITION_STRICT_MODE
Affected: ofstd
Type of modification: Disables feature
Explanation: Disables the compatibility options related to the
transition to OFCondition: No OFCondition default constructor, no
typedefs for E_Condition, CONDITION, no macros for SUCCESS and
condition aliases.
ON_THE_FLY_COMPRESSION
Affected: storescu
Type of modification: Activates experimental or rarely used feature
Explanation: When this macro is defined, the storescu tries to compress
or decompress the DICOM image to be sent (if required) depending on
the negotiated transfer syntax.
OLD_USER_INFO_SUB_ITEM_ORDER
Affected: dcmnet
Type of modification: Activates experimental or rarely used feature
Explanation: Prior DCMTK releases did not encode A-ASSOCIATE user
information sub-items in ascending order, i.e. they sent 55H
followed by 54H and 56H. This behaviour has been "legalized" by
DICOM CP 280 but is known to create problems with some other
toolkits. The current DCMTK release always sends the user
information sub-items in ascending order, but can be "forced" with
this macro to revert to the old behaviour. It should be re-activated
for testing purposes only.
PASTEL_COLOR_OUTPUT
Affected: dcmimgle, dcmimage
Type of modification: Activates experimental or rarely used feature
Explanation: Activates experimental code in dcmimgle/dcmimage that
renders monochrome images with pastel colors.
PDV_TEST
Affected: dcmnet
Type of modification: Activates experimental or rarely used feature
Explanation: Causes the network module to insert a false, zero-length
PDV (2 byte header) into each P-DATA-PDU.
PIXELSTACK_MEMORY_LEAK_WORKAROUND
Affected: dcmdata
Type of modification: Activates experimental or rarely used feature
Explanation: On certain platforms there seems to be a memory leak in
DcmDataset::chooseRepresentation(). The work-around activated by
this macro should solve this issue.
PRINT_REPLACED_DICTIONARY_ENTRIES
Affected: dcmdata
Type of modification: Activates experimental or rarely used feature
Explanation: When reading the data dictionary, duplicate entries (i.e.
entries replacing an older entry in the dictionary) are reported on
console if compiled with this macro. Useful for testing a new
dictionary version.
REJECT_FILE_IF_META_GROUP_LENGTH_ABSENT
Affected: dcmdata
Type of modification: Disables feature
Explanation: When reading the a file that contains an incorrect meta
header where meta header group length (0002,0000) is absent, DCMTK
since release 3.5.4 nevertheless tries to parse the file, unless this
macro is enabled, in which case the behaviour up to DCMTK 3.5.3 is
retained.
RETAIN_ASSOCIATION
Affected: dcmqrti
Type of modification: Activates experimental or rarely used feature
Explanation: Keeps association to remote Query SCP open after
study/series/image listing. Default behaviour is to open new
association for each query.
REVERSE_OVERLAY_ORIGIN_ORDER
Affected: dcmimgle
Type of modification: Activates experimental or rarely used feature
Explanation: When compiled with this macro, dcmimgle assumes that the
values in DCM_ImageFrameOrigin are in reverse order, i.e. X\Y
instead of Y\X.
SITE_UID_ROOT
Affected: dcmdata
Type of modification: Site customization
Explanation: dcmdata contains a routine that generates DICOM unique
identifiers (UIDs). By default, these are constructed from the OFFIS
UID namespace, i.e. using the OFFIS UID Root "1.2.276.0.7230010.3".
Users who prefer to let the toolkit generate UIDs from their own UID
namespace should compile DCMTK with SITE_UID_ROOT defined to their own
UID root. Please make sure that the resulting UIDs do not exceed the
64 characters limit!
STARVIEW
Affected: dcmimgle, dcmimage
Type of modification: Activates experimental or rarely used feature
Explanation: Enables support for old StarView 2 GUI class library from
Star Division.
STRICT_COMPARE
Affected: dcmqrdb
Type of modification: Activates experimental or rarely used feature
Explanation: By default, dcmqrdb ignores illegal leading and trailing
space characters when comparing UIDs. This behaviour can be modified
by defining this macro.
SUPPRESS_CREATE_STAMP
Affected: dcmdata
Type of modification: Activates experimental or rarely used feature
Explanation: When defined, suppresses the creation of a time stamp
comment when re-generating dcdeftag.h and dcdictzz.cc.
USE__LOCKING
Affected: dcmnet
Type of modification: Activates alternative implementation
Explanation: Activates an alternative emulation of flock() on Win32
platforms using _locking(). This version should only be used on
compilers where _get_osfhandle() is not available since it does not
implement shared locks.
USE_BINARY_MODE_FOR_STDOUT_ON_WINDOWS
Affected: dcmdata
Type of modification: Activates experimental or rarely used feature
Explanation: On Windows systems, the standard output (stdout) is opened in
text mode by default. Therefore, the binary output of tools like dcm2pnm
to stdout does not work correctly (in contrast to Unix systems). When
this preprocessor macro is defined, the binary mode is enabled for stdout.
However, this causes newlines in the textual output to be converted to LF
only (instead of CR LF which would be the usual translation for Windows).
USE_NULL_SAFE_OFSTRING
Affected: ofstd
Type of modification: Activates feature
Explanation: When this macro is defined, OFString(NULL) results in an
empty string. If this macro is not defined, OFString(NULL) causes a
NULL pointer dereference. This macro has no effect when
HAVE_STD_STRING is also defined. Currently, this macro is always defined
by DCMTK's Makefiles. This will change in future releases.
USING_STD_NAMESPACE
Affected: all modules
Type of modification: Re-activated behaviour of earlier DCMTK releases
Explanation: DCMTK by default does not anymore pollute the default namespace
by importing namespace std. Earlier releases did this to simplify
compatibility with older compilers where STL classes were not consistently
defined in namespace std. We now have configure macros which should care
for this. If user code still relies on namespace std to be included,
compile with this macro defined.
WIDE_CHAR_FILE_IO_FUNCTIONS
Affects: ofstd
Type of modification: Activates currently unused feature
Explanation: In addition to the standard file I/O functions, the OFFile class
also defines the corresponding wide character functions from C99 standard.
Since these functions are currently not used within DCMTK and also not yet
supported by all compilers, this feature is disabled by default.
WRITE_VERY_LARGE_CHUNKS
Affects: dcmdata
Type of modification: Re-activated behaviour of earlier DCMTK releases
Explanation: On Windows (at least for some versions of MSVC), calls to
fwrite() for more than 67,076,095 bytes (a bit less than 64 MByte) fail if
we're writing to a network share. See MSDN KB899149. As a workaround, we
always write in chunks of 32M which should hardly negatively affect
performance. This macro enables the behaviour of earlier DCMTK releases,
i.e. to always call fwrite with as much data as possible, which is known
not to work correctly on Win32 but might offer very minor performance
benefits on other platforms.
ZLIB_ENCODE_RFC1950_HEADER
Affects: dcmdata
Type of modification: Activates experimental or rarely used feature
Explanation: When this macro is defined, the deflated ZLIB format is created
instead of the deflated bitstream format (i.e. RFC 1950 instead of RFC
1951). Please note that the resulting bitstream is not DICOM compliant.
So, use only for testing, and use with care!