TEXT   72

dcmtk compile time flags and macro

Guest on 3rd June 2022 03:04:02 PM

  1. ===================================
  2. DCMTK COMPILE TIME FLAGS AND MACROS
  3. ===================================
  4.  
  5. The behavior of several DCMTK tools and libraries can be modified by
  6. a number of compile time flags (macros), which are explained below.
  7. Most of these macros enable experimental or rarely needed features
  8. in DCMTK, others disable certain functions.  So please, use with care!
  9.  
  10. ALLOW_ILLUMINATION_OVERRIDE
  11.   Affected: dcmprscu
  12.   Type of modification: Activates experimental or rarely used feature
  13.   Explanation: Allows the settings for Illumination and Reflected
  14.     Ambient Light, which are stored in a Stored Print object, to be
  15.     overridden from the print job command file.
  16.  
  17. BUGGY_IMPLEMENTATION_CLASS_UID_PREFIX
  18.   Affected: storescp
  19.   Type of modification: Activates workaround for known bug in other product
  20.   Explanation: The dcmnet module contains a workaround that allows to
  21.     communicate with some buggy Storage SCUs.  If the global flag
  22.     dcmPeerRequiresExactUIDCopy is enabled, an illegal space padding in
  23.     the Affected SOP Instance UID field of the C-STORE-RQ message is
  24.     retained in the corresponding C-STORE-RSP message.  When this
  25.     preprocessor macro is defined, it should contain the prefix of an
  26.     implementation class UID of an implementation known to exhibit the
  27.     buggy behavior.  The workaround is then activated in storescp
  28.     whenever a Storage SCU with the given implementation class UID root
  29.     connects.
  30.  
  31. DCMTK_BUILD_DATE
  32.   Affected: dcmdata
  33.   Type of modification: Toolkit customization
  34.   Explanation: When this macro is defined (typically in config/Makefile.def),
  35.     the given date is used instead of the official DCMTK release data.  This
  36.     allows for example to specify the date of a current development snapshot.
  37.  
  38. DCMTK_BUILD_IN_PROGRESS
  39.   Affected: all modules
  40.   Type of modification: Toolkit customization
  41.   Explanation: When building DLLs, exported symbols must be marked differently
  42.     if the DLL itself is built or when the DLL shall be used.  This macro is
  43.     defined when the DCMTK gets built and should not be defined when user code
  44.     that just uses the DCMTK is built.  Based on this, the correct annotation
  45.     gets selected and is used in the code.  There should be no valid reasons to
  46.     define this macro yourself since this is done automatically by the build
  47.     system.
  48.  
  49. DCMTK_GUI
  50.   Affected: all modules
  51.   Type of modification: Activates experimental or rarely used feature
  52.   Explanation: When this macro is defined, DCMTK re-assigns the standard
  53.     output and error streams maintained by ofConsole to string streams.
  54.     This will allow a GUI based application to extract the messages and
  55.     either present them to the user or store them in a log file.  See
  56.     comments in ofstd/include/dcmtk/ofstd/ofconsol.h.
  57.  
  58. DCMTK_USE_CXX11_STL
  59.   Affected: ofstd
  60.   Type of modification: Activates feature
  61.   Explanation: DCMTK_USE_CXX11_STL is defined when the appropriate options are
  62.     passed to the configuration system.  DCMTK will then use the native C++11
  63.     STL classes and functions instead of it's own (legacy) implementations.
  64.  
  65. DICOMDIR_WITHOUT_BACKUP
  66.   Affected: dcmdata
  67.   Type of modification: Disables feature
  68.   Explanation: By default DCMTK creates a backup of an existing DICOMDIR
  69.     (using the name DICOMDIR.$$$) when a DcmDicomDir object is written
  70.     to file.  The creation of the backup can be disabled with this macro.
  71.  
  72. DISABLE_COMPRESSION_EXTENSION
  73.   Affected: dcmqrdb
  74.   Type of modification: Disables feature
  75.   Explanation: Disables the support of compression (various transfer
  76.     syntaxes) in dcmqrdb, a feature which is still experimental.
  77.  
  78. DISABLE_OFSTD_ATOF
  79.   Affected: all modules
  80.   Type of modification: Disables feature
  81.   Explanation: By default, DCMTK uses its own implementation of atof()
  82.     to convert strings to double numbers in a locale-independent manner.
  83.     This flag forces DCMTK to use the standard sscanf() function
  84.     instead, which is normally much faster and gives a higher precision
  85.     than DCMTK's built in code, but is locale dependent, i.e. cannot be
  86.     used with locales such as German since DICOM decimal strings always
  87.     use the Posix locale.
  88.  
  89. DISABLE_OFSTD_FTOA
  90.   Affected: all modules
  91.   Type of modification: Disables feature
  92.   Explanation: By default, DCMTK uses its own implementation to convert
  93.     double numbers to strings to in a locale-independent manner.
  94.     This flag forces DCMTK to use the standard sprintf() function
  95.     instead, which is locale dependent, i.e. cannot be used with locales
  96.     such as German since DICOM decimal strings always use the Posix
  97.     locale.
  98.  
  99. DISABLE_PORT_PERMISSION_CHECK
  100.   Affected: most/all network server tools
  101.   Type of modification: Disables feature
  102.   Explanation: By default, most network server tools (e.g. storescp) check
  103.     for sufficient privileges to listen on the specified port (if geteuid()
  104.     is available on the particular system).  For examples, on Unix systems
  105.     listening on port < 1024 usually requires root privileges.  However,
  106.     the port permission check might prevent the tool from being run on such
  107.     ports on systems with fine-grained permission control (e.g. Linux).
  108.     Therefore, this check can be disabled using this flag.
  109.  
  110. DISABLE_RECV_TIMEOUT
  111.   Affected: dcmnet
  112.   Type of modification: Disables feature
  113.   Explanation: By default, DCMTK specifies a timeout of 60 seconds for
  114.     the recv() function.  This is especially useful in cases where the
  115.     receiver (e.g. storescp) looses the connection to the sender because
  116.     the network cable is pulled (e.g. for a mobile device).  This flag
  117.     disables the call to the setsockopt() function so that no timeout is
  118.     specified.
  119.  
  120. DISABLE_SEND_TIMEOUT
  121.   Affected: dcmnet
  122.   Type of modification: Disables feature
  123.   Explanation: By default, DCMTK specifies a timeout of 60 seconds for
  124.     the send() function.  This is especially useful in cases where the
  125.     sender (e.g. storescu) looses the connection to the receiver because
  126.     the network cable is pulled (e.g. for a mobile device).  This flag
  127.     disables the call to the setsockopt() function so that no timeout is
  128.     specified.
  129.  
  130. DONT_DISABLE_NAGLE_ALGORITHM
  131.   Affected: dcmnet
  132.   Type of modification: Disables feature
  133.   Explanation: By default, DCMTK disables the so-called Nagle algorithm
  134.     for each DICOM transport connection.  This provides a 2-4 times
  135.     performance improvement (WinNT4/SP4, 100Mbit/s Ethernet).  Effects on
  136.     other environments are unknown.  When compiled with this macro, the
  137.     code affecting the Nagle algorithm is disabled.  See documentation
  138.     for environment variable TCP_NODELAY in config/docs/envvars.txt.
  139.  
  140. DONT_LOAD_EXTERNAL_DICTIONARIES
  141.   Affected: dcmdata
  142.   Type of modification: Disables feature
  143.   Explanation: By default, DCMTK loads data dictionaries from files at
  144.     application start (before the main function is called).  These files
  145.     are either specified by the DCMDICTPATH environment variable or the
  146.     default files are used.  This flag disables the loading of external
  147.     dictionaries from file at application start, which might be useful
  148.     when only the builtin dictionary should be used.  However, if no
  149.     dictionary gets loaded, this is likely to cause unexpected behavior.
  150.     Even if this flag is defined, the reloadDictionaries() method can be
  151.     used to load the external dictionaries after application start.
  152.  
  153. DOXYGEN
  154.   Affected: everything
  155.   Type of modification: Hides complexity from Doxygen
  156.   Explanation: Doxygen is unable to parse some complex statements correctly
  157.     and it is sometimes sufficient to provide documentation for the basic
  158.     functionality instead of documenting every detail.
  159.     This macro is defined when creating the documentation with Doxygen and
  160.     should NEVER be defined when compiling DCMTK with a C/C++ compiler.
  161.     NOTE: Doxygen is still unable to expand some macros correctly
  162.     (e.g. HAVE_WINDOWS_H). Using this macro at the appropriate locations
  163.     could be a solution for this problem.
  164.  
  165. EXPERIMENTAL_READ_FROM_FILE
  166.   Affected: dump2dcm
  167.   Type of modification: Activates experimental or rarely used feature
  168.   Explanation: When this macro is defined, the relatively new function
  169.     createValueFromTempFile() is used for reading large binary data files.
  170.  
  171. HAVE_STD_STRING
  172.   Affected: ofstd
  173.   Type of modification: Activates feature
  174.   Explanation: When this macro is defined, the ANSI C++ standard string
  175.     class is used instead of DCMTK's own implementation.
  176.  
  177. HAVE_STL
  178.   Affected: ofstd
  179.   Type of modification: Activates feature
  180.   Explanation: When this macro is defined, the STL (standard template
  181.     library) list, map, stack, vector and auto_ptr classes as well as
  182.     the STL algorithms are used instead of DCMTK's own implementations.
  183.  
  184. HAVE_STL_ALGORITHMS
  185.   Affected: ofstd
  186.   Type of modification: Activates feature
  187.   Explanation: When this macro is defined, the STL (standard template
  188.     library) algorithms are used instead of DCMTK's own implementation.
  189.     Also see HAVE_STL.
  190.  
  191. HAVE_STL_AUTO_PTR
  192.   Affected: ofstd
  193.   Type of modification: Activates feature
  194.   Explanation: When this macro is defined, the STL (standard template
  195.     library) auto_ptr class is used instead of DCMTK's own implementation.
  196.     Also see HAVE_STL.
  197.  
  198. HAVE_STL_LIST
  199.   Affected: ofstd
  200.   Type of modification: Activates feature
  201.   Explanation: When this macro is defined, the STL (standard template
  202.     library) list class is used instead of DCMTK's own implementation.
  203.     Also see HAVE_STL.
  204.  
  205. HAVE_STL_MAP
  206.   Affected: ofstd
  207.   Type of modification: Activates feature
  208.   Explanation: When this macro is defined, the STL (standard template
  209.     library) map class is used instead of DCMTK's own implementation.
  210.     Also see HAVE_STL.
  211.  
  212. HAVE_STL_STACK
  213.   Affected: ofstd
  214.   Type of modification: Activates feature
  215.   Explanation: When this macro is defined, the STL (standard template
  216.     library) stack class is used instead of DCMTK's own implementation.
  217.     Also see HAVE_STL.
  218.  
  219. HAVE_STL_VECTOR
  220.   Affected: ofstd
  221.   Type of modification: Activates feature
  222.   Explanation: When this macro is defined, the STL (standard template
  223.     library) vector class is used instead of DCMTK's own implementation.
  224.     Also see HAVE_STL.
  225.  
  226. LOCK_IMAGE_FILES
  227.   Affected: dcmpstat, dcmqrdb
  228.   Type of modification: Activates experimental or rarely used feature
  229.   Explanation: When this macro is defined, the DICOM image file to be
  230.     send or received/created is locked exclusively.
  231.  
  232. LOG4CPLUS_DISABLE_xxx
  233. (where xxx is one of TRACE, DEBUG, INFO, WARN, ERROR and FATAL)
  234.   Affected: oflog
  235.   Type of modification: Disables feature
  236.   Explanation: When one of these macros is defined all log message of
  237.     this type and lower are disabled and optimized away.
  238.  
  239. NO_GET_SUPPORT
  240.   Affected: dcmqrdb
  241.   Type of modification: Disables feature
  242.   Explanation: Disables the experimental C-GET support in dcmqrdb.
  243.  
  244. NO_IOS_BASE_ASSIGN
  245.   Affected: all command line tools
  246.   Type of modification: Disables feature
  247.   Explanation: On Win32 platforms, the prepareCmdLineArgs() function
  248.     maps cout to cerr by assignment.  This does not work with all
  249.     iostream implementations and can, therefore, be disabled with this
  250.     macro.
  251.  
  252. NO_PATIENTSTUDYONLY_SUPPORT
  253.   Affected: dcmqrdb
  254.   Type of modification: Disables feature
  255.   Explanation: Disables support for the Patient/Study Only Query/Retrieve
  256.     Model in dcmqrdb.
  257.  
  258. NO_WINDOWS95_ADDRESS_TRANSLATION_WORKAROUND
  259.   Affected: dcmnet
  260.   Type of modification: Disables feature
  261.   Explanation: Under Windows 95 gethostbyname() will not accept an IP
  262.     address e.g. "134.106.1.1".  This appears to work without problems
  263.     with other Windows versions and several Unix variants.  As a
  264.     workaround, DCMTK explicitly handles the IP address case.  The
  265.     workaround can be disabled with this macro.
  266.  
  267. OFCONDITION_IMPLICIT_BOOL_CONVERSION
  268.   Affected: ofstd
  269.   Type of modification: Activates experimental or rarely used feature
  270.   Explanation: Activates an implicit conversion from OFCondition to
  271.     OFBool, i.e. operator OFBool().  Implicit conversion might not always
  272.     be a good idea since it can hide unwanted constructs.  Therefore,
  273.     this operator is disabled by default.
  274.  
  275. ON_THE_FLY_COMPRESSION
  276.   Affected: storescu
  277.   Type of modification: Activates experimental or rarely used feature
  278.   Explanation: When this macro is defined, the storescu tries to compress
  279.     or decompress the DICOM image to be sent (if required) depending on
  280.     the negotiated transfer syntax.
  281.  
  282. OLD_USER_INFO_SUB_ITEM_ORDER
  283.   Affected: dcmnet
  284.   Type of modification: Activates experimental or rarely used feature
  285.   Explanation: Prior DCMTK releases did not encode A-ASSOCIATE user
  286.     information sub-items in ascending order, i.e. they sent 55H
  287.     followed by 54H and 56H.  This behavior has been "legalized" by
  288.     DICOM CP 280 but is known to create problems with some other
  289.     toolkits.  The current DCMTK release always sends the user
  290.     information sub-items in ascending order, but can be "forced" with
  291.     this macro to revert to the old behavior.  It should be re-activated
  292.     for testing purposes only.
  293.  
  294. PASTEL_COLOR_OUTPUT
  295.   Affected: dcmimgle, dcmimage
  296.   Type of modification: Activates experimental or rarely used feature
  297.   Explanation: Activates experimental code in dcmimgle/dcmimage that
  298.     renders monochrome images with pastel colors.
  299.  
  300. PDV_TEST
  301.   Affected: dcmnet
  302.   Type of modification: Activates experimental or rarely used feature
  303.   Explanation: Causes the network module to insert a false, zero-length
  304.     PDV (2 byte header) into each P-DATA-PDU.
  305.  
  306. PIXELSTACK_MEMORY_LEAK_WORKAROUND
  307.   Affected: dcmdata
  308.   Type of modification: Activates experimental or rarely used feature
  309.   Explanation: On certain platforms there seems to be a memory leak in
  310.     DcmDataset::chooseRepresentation().  The work-around activated by
  311.     this macro should solve this issue.
  312.  
  313. PRINT_REPLACED_DICTIONARY_ENTRIES
  314.   Affected: dcmdata
  315.   Type of modification: Activates experimental or rarely used feature
  316.   Explanation: When reading the data dictionary, duplicate entries (i.e.
  317.     entries replacing an older entry in the dictionary) are reported on
  318.     console if compiled with this macro.  Useful for testing a new
  319.     dictionary version.
  320.  
  321. REJECT_FILE_IF_META_GROUP_LENGTH_ABSENT
  322.   Affected: dcmdata
  323.   Type of modification: Disables feature
  324.   Explanation: When reading the a file that contains an incorrect meta
  325.     header where meta header group length (0002,0000) is absent, DCMTK
  326.     since release 3.5.4 nevertheless tries to parse the file, unless this
  327.     macro is enabled, in which case the behavior up to DCMTK 3.5.3 is
  328.     retained.
  329.  
  330. RETAIN_ASSOCIATION
  331.   Affected: dcmqrti
  332.   Type of modification: Activates experimental or rarely used feature
  333.   Explanation: Keeps association to remote Query SCP open after
  334.     study/series/image listing.  Default behavior is to open new
  335.     association for each query.
  336.  
  337. REVERSE_OVERLAY_ORIGIN_ORDER
  338.   Affected: dcmimgle
  339.   Type of modification: Activates experimental or rarely used feature
  340.   Explanation: When compiled with this macro, dcmimgle assumes that the
  341.     values in DCM_ImageFrameOrigin are in reverse order, i.e. X\Y
  342.     instead of Y\X.
  343.  
  344. SITE_UID_ROOT
  345.   Affected: dcmdata
  346.   Type of modification: Site customization
  347.   Explanation: dcmdata contains a routine that generates DICOM unique
  348.     identifiers (UIDs).  By default, these are constructed from the OFFIS
  349.     UID namespace, i.e. using the OFFIS UID Root "1.2.276.0.7230010.3".
  350.     Users who prefer to let the toolkit generate UIDs from their own UID
  351.     namespace should compile DCMTK with SITE_UID_ROOT defined to their own
  352.     UID root.  Please make sure that the resulting UIDs do not exceed the
  353.     64 characters limit!
  354.  
  355. STARVIEW
  356.   Affected: dcmimgle, dcmimage
  357.   Type of modification: Activates experimental or rarely used feature
  358.   Explanation: Enables support for old StarView 2 GUI class library from
  359.     Star Division.
  360.  
  361. STRICT_COMPARE
  362.   Affected: dcmqrdb
  363.   Type of modification: Activates experimental or rarely used feature
  364.   Explanation: By default, dcmqrdb ignores illegal leading and trailing
  365.     space characters when comparing UIDs.  This behavior can be modified
  366.     by defining this macro.
  367.  
  368. SUPPRESS_CREATE_STAMP
  369.   Affected: dcmdata
  370.   Type of modification: Activates experimental or rarely used feature
  371.   Explanation: When defined, suppresses the creation of a time stamp
  372.     comment when re-generating dcdeftag.h and dcdictzz.cc.
  373.  
  374. USE__LOCKING
  375.   Affected: dcmnet
  376.   Type of modification: Activates alternative implementation
  377.   Explanation: Activates an alternative emulation of flock() on Win32
  378.     platforms using _locking().  This version should only be used on
  379.     compilers where _get_osfhandle() is not available since it does not
  380.     implement shared locks.
  381.  
  382. USE_BINARY_MODE_FOR_STDOUT_ON_WINDOWS
  383.   Affected: dcmdata
  384.   Type of modification: Activates experimental or rarely used feature
  385.   Explanation: On Windows systems, the standard output (stdout) is opened in
  386.     text mode by default.  Therefore, the binary output of tools like dcm2pnm
  387.     to stdout does not work correctly (in contrast to Unix systems).  When
  388.     this preprocessor macro is defined, the binary mode is enabled for stdout.
  389.     However, this causes newlines in the textual output to be converted to LF
  390.     only (instead of CR LF which would be the usual translation for Windows).
  391.  
  392. USE_NULL_SAFE_OFSTRING
  393.   Affected: ofstd
  394.   Type of modification: Activates feature
  395.   Explanation: When this macro is defined, OFString(NULL) results in an
  396.     empty string.  If this macro is not defined, OFString(NULL) causes a
  397.     NULL pointer dereference.  This macro has no effect when
  398.     HAVE_STD_STRING is also defined.  Currently, this macro is always defined
  399.     by DCMTK's Makefiles.  This will change in future releases.
  400.  
  401. USING_STD_NAMESPACE
  402.   Affected: all modules
  403.   Type of modification: Re-activated behavior of earlier DCMTK releases
  404.   Explanation: DCMTK by default does not anymore pollute the default namespace
  405.     by importing namespace std.  Earlier releases did this to simplify
  406.     compatibility with older compilers where STL classes were not consistently
  407.     defined in namespace std.  We now have configure macros which should care
  408.     for this.  If user code still relies on namespace std to be included,
  409.     compile with this macro defined.
  410.  
  411. WIDE_CHAR_FILE_IO_FUNCTIONS
  412.   Affected: ofstd
  413.   Type of modification: Activates feature
  414.   Explanation: In addition to the standard file I/O functions, the OFFile class
  415.     also defines the corresponding wide character functions from C99 standard.
  416.     Since these functions are not yet supported by all compilers and the
  417.     current implementation is Windows-specific, this feature is disabled by
  418.     default.  When using CMake, you can enable this macro by setting the CMake
  419.     option DCMTK_WIDE_CHAR_FILE_IO_FUNCTIONS to "on".
  420.  
  421. WIDE_CHAR_MAIN_FUNCTION
  422.   Affected: currently not used
  423.   Type of modification: Activates experimental or rarely used feature
  424.   Explanation: On Windows (at least for MSVC), a different main function has
  425.     to be used in order to get the command line arguments with wide character
  426.     encoding (UTF-16).  By defining this flag, the macro DCMTK_MAIN_FUNCTION
  427.     expands to wmain() instead of main().  When using CMake, you can enable
  428.     this macro by setting the CMake option DCMTK_WIDE_CHAR_MAIN_FUNCTION to
  429.     "on".  Usually, WIDE_CHAR_FILE_IO_FUNCTIONS should also be enabled.
  430.  
  431. WRITE_VERY_LARGE_CHUNKS
  432.   Affected: dcmdata
  433.   Type of modification: Re-activated behavior of earlier DCMTK releases
  434.   Explanation: On Windows (at least for some versions of MSVC), calls to
  435.     fwrite() for more than 67,076,095 bytes (a bit less than 64 MByte) fail if
  436.     we're writing to a network share.  See MSDN KB899149.  As a workaround, we
  437.     always write in chunks of 32M which should hardly negatively affect
  438.     performance.  This macro enables the behavior of earlier DCMTK releases,
  439.     i.e. to always call fwrite with as much data as possible, which is known
  440.     not to work correctly on Win32 but might offer very minor performance
  441.     benefits on other platforms.
  442.  
  443. ZLIB_ENCODE_RFC1950_HEADER
  444.   Affected: dcmdata
  445.   Type of modification: Activates experimental or rarely used feature
  446.   Explanation: When this macro is defined, the deflated ZLIB format is created
  447.     instead of the deflated bitstream format (i.e. RFC 1950 instead of RFC
  448.     1951). Please note that the resulting bitstream is not DICOM compliant.
  449.     So, use only for testing, and use with care!

Raw Paste


Login or Register to edit or fork this paste. It's free.