Skip Headers
Oracle® Multimedia DICOM Developer's Guide
11g Release 2 (11.2)

Part Number E10778-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

10 Creating DICOM Configuration Documents

Administrators can perform several repository management tasks, including creating their own configuration documents. This chapter describes the characteristics of configuration documents and provides instructions on how to write configuration documents that are specific to a particular organization or enterprise.

In Oracle Database 11g Release 2 (11.2), Oracle Multimedia DICOM supports the processing of DICOM files that contain private attribute definer names consisting of special characters. To enable referencing of DICOM metadata tags that refer to private attribute definers using these special characters, Oracle Multimedia DICOM extends the syntax for value locators used in the DICOM configuration documents to enable the expression of these definers. The DICOM value locator type identifies DICOM attributes or their child components within the DICOM content. See General Format for DICOM Value Locators for reference information.

Administrators can use DICOM value locators with anonymity, constraint, and mapping documents. The DICOM value locator is also used in the mid-tier Java API. See Section 10.2.1.5, Section 10.2.2.5, and Section 10.2.3.6, respectively, for more information about using DICOM value locators in anonymity, constraint, and mapping documents. See Chapter 9 for more information about inserting, updating, and deleting configuration documents. See Chapter 11 for examples of these processes.

Note:

In this chapter, names of attributes for XML elements appear in monospace type.

This chapter includes these sections:

For more information about the data structure and encoding definitions of DICOM content, see the DICOM standard. This standard is available on the Web site for the National Electrical Manufacturers Association (NEMA) at

http://medical.nema.org/

See Also:

Oracle Multimedia Mid-Tier Java API Reference for reference information about the Java classes that support DICOM value locators in the middle tier

10.1 Characteristics of Configuration Documents

After installation, the Oracle Multimedia DICOM data model repository contains the following set of default configuration documents:

Note:

In addition, users can install an optional stored tag list document that specifies the DICOM attributes to be extracted from the embedded DICOM content and stored in the XML metadata attribute of the ORDDicom object when the setProperties( ) method is called.

See Section 2.4.1 for a brief definition of each configuration document.

Each type of configuration document has a specific set of characteristics, which are briefly described in these sections:

10.1.1 Characteristics of Anonymity Documents

Anonymity documents have these characteristics:

  • No other document types depend on anonymity documents.

  • There are no dependencies between anonymity documents.

  • Anonymity documents depend on the standard and private dictionary documents.

  • There is no maximum limit on the number of anonymity documents in the repository.

  • Changes made to anonymity documents affect the results of the isAnonymous( ) and makeAnonymous( ) methods.

10.1.2 Characteristics of Constraint Documents

Constraint documents have these characteristics:

  • No other document types depend on constraint documents.

  • There may be dependencies between constraint documents.

  • Constraint documents depend on the standard and private dictionary documents and the preference document.

  • There is no limit on the number of constraint documents in the repository.

  • Constraint documents can be written in such a way that later constraint documents depend on previously inserted constraint documents. As an example using installed constraint documents, ordcmct.xml depends on ordcmcmd.xml, and both of those documents depend on ordcmcmc.xml.

  • The isConformanceValid( ) method depends on the specified constraint rule and the DICOM content. If the constraint rule (defined in a constraint document) is changed, the DICOM content may be validated differently.

  • The preference parameter EXP_IF_NULL_ATTR_IN_CONSTRAINT in the preference document can be used to specify whether to raise an exception when encountering a null value for the attributes specified in the constraint rules. If this preference parameter is set to true, the isConformanceValid( ) method raises an exception; otherwise, the predicate that was encountered is evaluated to false.

10.1.3 Characteristics of Mapping Documents

Mapping documents have these characteristics:

  • No other document types depend on mapping documents.

  • There are no dependencies between mapping documents.

  • Mapping documents depend on the standard and private dictionary documents and the preference document.

  • There is no limit on the number of mapping documents in the repository.

  • Changes made to mapping documents affect the results of the extractMetadata( ) method, when the mapping document is used as a parameter.

  • If a mapping document specifies a metadata namespace value in the <NAMESPACE> element, the XML schema that corresponds to the metadata namespace value must be registered with Oracle XML DB.

    See Also:

    Oracle XML DB Developer's Guide for more information about registering XML schemas

    To enable the extractMetadata( ) method to function correctly, the structure of the mapping document must be consistent with the XML schema that corresponds to the value of the <NAMESPACE> element.

  • Extracted metadata is schema validated only if both of these conditions exist:

    • The mapping document specifies a value in the <NAMESPACE> element.

    • The value of the preference parameter VALIDATE_METADATA in the preference document is true.

10.1.4 Characteristics of Standard Dictionary Documents

Standard dictionary documents have these characteristics:

  • One standard dictionary document (ordcmsd.xml) is installed by Oracle.

  • Changes to standard dictionary documents must be limited to updates in the DICOM standard.

  • There is no limit on the number of standard dictionary documents in the repository.

10.1.5 Characteristics of Private Dictionary Documents

Private dictionary documents have these characteristics:

  • One private dictionary document (ordcmpv.xml) is installed by Oracle.

  • There is no limit on the number of private dictionary documents in the repository.

10.1.6 Characteristics of Preference Documents

Preference documents have these characteristics:

  • A maximum of two (one Oracle-defined and one user-defined) preference documents are permitted in the repository. The installed, Oracle-defined preference document (ordcmpf.xml) includes Oracle-fixed preference parameter names and lists of values. The user-defined preference document can update the default preference parameter values that were set in the Oracle-defined preference document.

  • Changes to preference parameter values in preference documents change the behavior of DICOM methods, functions, and procedures. Specifically, preference parameter values that are defined in the user-defined preference document override the default values defined in the Oracle-defined preference document.

10.1.7 Characteristics of UID Definition Documents

UID definition documents have these characteristics:

  • A maximum of two (one Oracle-defined and one user-defined) UID definition documents are permitted in the repository. The installed, Oracle-defined UID definition document (ordcmui.xml) includes the UID definitions listed in Part 6 of the DICOM standard.

  • Changes to user-defined UID definition documents must be limited to updates in the DICOM standard or additions of new UID values.

Note:

Existing UID values must not be changed.

10.1.8 Characteristics of Stored Tag List Documents

Stored tag list documents have these characteristics:

  • Only one stored tag list document can exist in the repository.

  • The stored tag list document depends on the standard and private dictionary documents and the preference document.

  • The preference parameter MANDATE_ATTR_TAGS_IN_STL enforces the rule that all tags used by the constraint and mapping documents are listed in the stored tag list document. The value of the MANDATE_ATTR_TAGS_IN_STL preference parameter in the preference document is false, by default. If this preference parameter is set to true, the rule is enforced; otherwise it is not enforced.

10.2 Writing Configuration Documents

Administrators can write one or more configuration documents to support specific applications or organizations. These subsections describe how to create each type of configuration document:

10.2.1 Creating Anonymity Documents

Anonymity documents specify the set of attributes to be made anonymous, and the actions to be taken to make those attributes anonymous. In the ORDDicom object, anonymity documents are used by the methods isAnonymous( ) and makeAnonymous( ) to create new objects in which personally identifying information has been removed or replaced.

The XML schema ordcman.xsd defines the XML schema that constrains anonymity documents. (See Section B.1 for a listing of the anonymity document schema ordcman.xsd.)

The default anonymity document, ordcman.xml, lists a subset of the attributes defined in the Basic Application Level Confidentiality Profile in Part 15 of the DICOM standard. These attributes are either removed or replaced with the string "anonymous" in the DICOM content. In addition, the default anonymity document removes all undefined standard attributes and all private attributes from the DICOM content.

Within each anonymity document, the <ANONYMITY_ACTION> element includes an action attribute. The value of the action attribute can apply to a single attribute or to a set of attributes within that anonymity document. Global actions apply to a set of attributes, such as all private attributes.

Table 10-1 describes the valid values for the action attribute.

Table 10-1 action Attribute Values

Value Description

none

No action is taken. The unchanged value of the specified attribute or the set of attributes appears in the resulting DICOM content.

remove

The default value. The specified attribute or the set of attributes is removed from the resulting DICOM content.

Note: Some imaging applications may depend on certain attributes (for example: SOP_INSTANCE_UID or SOP_CLASS_UID). In these cases, use the replace action with an appropriate value in place of the remove action.

replace

The attribute value is replaced by the specified value in the resulting DICOM content. The specified replacement value must be a string representation that matches the data type of the tag as defined by the <VR> element in the data dictionaries.

Note: This action value is not permitted for global actions.

For example:

The standard tag 00100022 represents the Patient ID, which has a <VR> value of CS (CODE_STRING) in the data dictionary. The data type CS is defined in the XML schema ordcmrdt.xsd as xs:token of length 16. The replacement value must be a string representation that conforms to this definition.

The standard tag 00081160 represents the Referenced Frame Number, which has a <VR> value of IS (INTEGER_STRING). The data type IS is defined in the XML schema ordcmrdt.xsd as xs:integer. The replacement value must be a string representation that conforms to this definition.


Attributes in anonymity documents can be standard or private. Standard and private attributes can be either defined or undefined. Defined standard attributes are defined in the DICOM standard and in the standard dictionary in the data model repository. Defined private attributes are defined by and specific to a particular organization. Defined private attributes known to Oracle Multimedia are defined in the private dictionary in the data model repository. Undefined attributes are defined in neither the standard dictionary nor the private dictionary in the data model repository.

The <INDIVIDUAL_ATTRIBUTE> element defines the action taken to make a defined standard or private attribute anonymous. For private attributes, the action specified in this element always overrides the global action defined by the <PRIVATE_ATTRIBUTES> element. In addition, standard or private attributes that are undefined cannot be specified as <INDIVIDUAL_ATTRIBUTE> element values in an anonymity document.

Table 10-2 describes the elements that define the global actions in the anonymity document.

Table 10-2 Global Action Elements

Element Description

<PRIVATE_ATTRIBUTES>

Specifies the action performed on all defined and undefined private attributes.

Note: The action for a private attribute defined by the <INDIVIDUAL_ATTRIBUTE> element always overrides the global action defined by the <PRIVATE_ATTRIBUTES> element.

<UNDEFINED_STANDARD_ATTRIBUTES>

Specifies the action performed on all standard attributes that are not defined in the standard dictionaries in the data model repository.

A DICOM attribute tag contains a group number and an element number.

A standard attribute tag is identified by an even-numbered group number.

<UNDEFINED_PRIVATE_ATRIBUTES>

Specifies the action performed on all private attributes that are not defined in the private dictionaries in the data model repository.

Note: The action value defined by this element takes precedence over the action value defined by the <PRIVATE_ATTRIBUTES > element.


Examples of valid values for an <ATTRIBUTE_TAG> element are as follows: 00100010, 00100010(DICOM), 10871100(PRIVATE ORG).

Note:

Currently, only these values are permitted for the definer name in a private attribute:
  • The uppercase and lowercase letters: A-Z

  • The numbers: 0-9

  • The characters: '.'(dot), ' ' (space), and '/'(forward slash)

The following subsections contain examples that show how to create anonymity documents:

10.2.1.1 Making Standard Attributes Anonymous

This subsection shows how to replace a single standard attribute with specified values that make that attribute anonymous in the resulting DICOM content. Example 10-1 shows a code segment for the standard attribute Patient's Name. The XML statements where these actions are defined are highlighted in bold.

Example 10-1 Making a Standard Attribute Anonymous

<INDIVIDUAL_ATTRIBUTE>
   <ATTRIBUTE_TAG>00100010</ATTRIBUTE_TAG>
   <DESCRIPTION>Patient's Name </DESCRIPTION>
   <ANONYMITY_ACTION action="replace">anonymous</ANONYMITY_ACTION>
</INDIVIDUAL_ATTRIBUTE>

The following code segment shows how the <ATTRIBUTE_TAG> value 00100010 is defined in the standard dictionary in the data model repository. If the definer name is not specified in the <ATTRIBUTE_TAG> value, the default value of "DICOM" is assumed. The value of the 00100010 tag is replaced with the value "anonymous" in the resulting DICOM content.

The standard attribute tag 00100010 is defined as follows in the standard dictionary:

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>00100010</TAG>
   <NAME>Patient's Name</NAME>
   <VR>PN</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

The tag definition shown in the preceding code segment represents the standard attribute Patient's Name, of data type PN as defined by the <VR> element. The <VR> element is the value representation element used to specify standard data types, as defined in Part 5 of the DICOM standard. The data type PN is defined in the XML schema ordcmrdt.xsd. The replacement value for the attribute Patient's Name must be a string representation of the value defined by the <VR> element.

10.2.1.2 Making Undefined Standard Attributes Anonymous

This subsection shows how to use the action value remove to remove all undefined standard attributes from the resulting DICOM content. Example 10-2 shows the XML statement where this action is defined.

Example 10-2 Removing All Undefined Standard Attributes

<UNDEFINED_STANDARD_ATTRIBUTES action="remove" />

10.2.1.3 Making Selected Private Attributes Anonymous

This subsection shows how to replace a single private attribute with specified values that make that attribute anonymous in the resulting DICOM content. Example 10-3 shows a code segment for the private attribute 10871100(PRIVATE ORG). The XML statements where these actions are defined are highlighted in bold.

Example 10-3 Making a Private Attribute Anonymous

<INDIVIDUAL_ATTRIBUTE>
   <ATTRIBUTE_TAG>10871100(PRIVATE ORG)</ATTRIBUTE_TAG>
   <DESCRIPTION>Media Type </DESCRIPTION>
   <ANONYMITY_ACTION action="replace"> replaced</ANONYMITY_ACTION>
</INDIVIDUAL_ATTRIBUTE>

In Example 10-3, the <ATTRIBUTE_TAG> value 10871100 with the definer name PRIVATE ORG must be defined in a private dictionary in the data model repository. The value of the private attribute 10871100(PRIVATE ORG) is replaced with the specified value in the resulting DICOM content.

The private attribute tag 10871100 is defined as follows in the private dictionary:

<PRIVATE_ATTRIBUTE_DEFINITION>
  <TAG>10871100</TAG>
  <NAME>Media Type</NAME>
  <DEFINER>PRIVATE ORG</DEFINER>
  <VR>CS</VR>
  <VM>1</VM>
</PRIVATE_ATTRIBUTE_DEFINITION>

This tag definition shown in the preceding code segment represents the private attribute 10871100(PRIVATE ORG), of data type CS and name Media Type as defined by the <VR> element. The data type CS is defined in the XML schema ordcmrdt.xsd as xs:token of length 16. The replacement value must be a string representation that conforms to the value defined by the <VR> element.

10.2.1.4 Making All Private Attributes Anonymous

This subsection shows how to make several private attributes anonymous by removing or replacing those attributes with specified values that make them anonymous in the resulting DICOM content.

Note:

Keep these guidelines in mind:
  • The action value for a specified private attribute defined by the <INDIVIDUAL_ATTRIBUTE> element always overrides the global action defined by the <PRIVATE_ATTRIBUTES> element.

  • The global action specified by the <UNDEFINED_PRIVATE_ATTRIBUTES> element overrides the global action defined by the <PRIVATE_ATTRIBUTE> element.

Example 10-4 shows a code segment that uses the action value remove to remove all private attributes in the resulting DICOM content.

Example 10-4 Removing All Private Attributes

<PRIVATE_ATTRIBUTES action="remove"></PRIVATE_ATTRIBUTES>
<UNDEFINED_PRIVATE_ATTRIBUTES action="remove" />

Similarly, Example 10-5 shows a code segment that uses the action value remove to remove all undefined private attributes from the resulting DICOM content. And, this code segment uses the action value replace to replace the value of the tag for the defined private attribute 10871100(PRIVATE ORG) with the string "anonymous" in the resulting DICOM content. The XML statements where these actions are defined are highlighted in bold.

Example 10-5 Removing All Undefined Private Attributes

<PRIVATE_ATTRIBUTES action="remove"></PRIVATE_ATTRIBUTES>
<INDIVIDUAL_ATTRIBUTE>
    <ATTRIBUTE_TAG>10871100(PRIVATE ORG)</ATTRIBUTE_TAG>
    <DESCRIPTION>Media Type </DESCRIPTION>
     <ANONYMITY_ACTION action="replace"> anonymous</ANONYMITY_ACTION>
</INDIVIDUAL_ATTRIBUTE>

Example 10-6 shows a code segment that uses the action value none to include all defined private attributes in the resulting DICOM content. And, this code segment uses the action value remove to remove all undefined private attributes from the resulting DICOM content.

Example 10-6 Including Defined Private Attributes and Removing Undefined Private Attributes

<PRIVATE_ATTRIBUTES action="none"></PRIVATE_ATTRIBUTES>
<UNDEFINED_PRIVATE_ATTRIBUTES action="remove" /> 

Example 10-7 shows a code segment that uses the action value remove to remove all defined private attributes from the resulting DICOM content. And, this code segment uses the action value none to include all undefined private attributes in the resulting DICOM content.

Example 10-7 Removing Defined Private Attributes and Including Undefined Private Attributes

<PRIVATE_ATTRIBUTES action="remove"></PRIVATE_ATTRIBUTES>
<UNDEFINED_PRIVATE_ATTRIBUTES action="none" /> 

10.2.1.5 Using DICOM Value Locators in Anonymity Documents

This subsection shows how to use DICOM value locators to specify attributes in anonymity documents. Example 10-8 shows how to specify the attribute Person Name with a DICOM value locator to make the attribute anonymous in the resulting DICOM content. This attribute is a child attribute of the attribute Content Sequence (data type SQ). The XML statement where this action is performed is highlighted in bold.

Example 10-8 Simple DICOM Value Locator in an Anonymity Document

<INDIVIDUAL_ATTRIBUTE>
  <ATTRIBUTE_TAG>0040A730[1].0040A123</ATTRIBUTE_TAG>
  <DESCRIPTION> Person Name </DESCRIPTION>
  <ANONYMITY_ACTION action="replace">anonymous</ANONYMITY_ACTION>
</INDIVIDUAL_ATTRIBUTE>

The standard attribute tags 0040A730 and 0040A123 are defined as follows in the standard dictionary:

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A730</TAG>
   <NAME>Content Sequence</NAME>
   <VR>SQ</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>
<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A123</TAG>
   <NAME>Person Name</NAME>
   <VR>PN</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

Example 10-9 shows how to use a DICOM value locator with a wildcard character in an anonymity document to remove attributes with multiple values in the resulting DICOM content. The XML statement where the DICOM value locator is used is highlighted in bold.

Example 10-9 DICOM Value Locator with a Wildcard Character in an Anonymity Document

<INDIVIDUAL_ATTRIBUTE>
  <ATTRIBUTE_TAG>00081050[*]</ATTRIBUTE_TAG>
  <DESCRIPTION> Performaing physician's name </DESCRIPTION>
  <ANONYMITY_ACTION action="remove"></ANONYMITY_ACTION>
</INDIVIDUAL_ATTRIBUTE>

The standard attribute tag 00081050 is defined as follows in the standard dictionary:

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>00081050</TAG>
   <NAME>Performing Physician's Name</NAME>
   <VR>PN</VR>
   <VM>1-n</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

In the tag definition shown in the preceding code segment, the <VM> element indicates that this attribute can contain multiple values. Using a wildcard character in the DICOM value locator ensures that all the values for this attribute are made anonymous.

Note:

DICOM value locators with the TAG_FIELD component are not supported in anonymity documents.

See General Format for DICOM Value Locators for more information about the DICOM value locator type.

10.2.2 Creating Constraint Documents

Constraint documents define one or more constraint rules. The XML schema ordcmct.xsd defines the XML schema that constrains constraint documents. (See Section B.2 for a listing of the constraint document schema ordcmct.xsd.)

The default constraint documents (ordcmct.xml, ordcmcmd.xml, ordcmcmc.xml), are XML representations of the rules to check the conformance of DICOM content, according to the DICOM standard and other organization-wide guidelines.

At run time, users can invoke a PL/SQL or Java function to check the conformance of DICOM content according to one or more invokable constraint rules. Each invokable constraint rule is defined as a global rule (using the <GLOBAL_RULE> element). Global rules are constraint rules that define requirements to be met by the DICOM content.

Constraint rules can comprise individual constraint predicates (using the <PREDICATE> element). A constraint predicate defines conditions on DICOM content. A predicate can be a logical statement, a relational statement that compares values, a function call evaluation that returns a Boolean type, or a reference to other predicate definitions. Predicate definitions are recursive. For example, when used as a logical statement, a predicate includes the logical OR of two other predicates. Each of the other predicates, in turn, can be a relational predicate.

Predicates operate on individual attributes or sets of attributes in the DICOM content. Within a predicate, attributes are specified with the <ATTRIBUTE_TAG> element. Attributes are defined by the DICOM standard or by the private organizations or enterprises that create DICOM content. Attributes can be specified using simple DICOM value locators or more complex DICOM value locators, including those with macro substitution strings (see General Format for DICOM Value Locators).

Complex constraint rules can be defined more simply using constraint macros. Each constraint macro can be defined as a global macro (using the <GLOBAL_MACRO> element). Constraint macros follow the same predicate definition grammar as constraint rules. They differ from constraint rules in that the predicate operands in constraint macros can contain macro parameters rather than the fixed values contained in constraint rules. The macro parameters in a constraint macro are replaced with parameter values when the macro is invoked (using the <INVOKE_MACRO> element). Constraint macros can also be recursive. As an example, constraint macro A is recursive if it invokes itself or other constraint macros that invoke constraint macro A. Recursive constraint macros are useful when specifying validation requirements for hierarchical or recursive structured DICOM content, such as the content in a DICOM structured report.

Constraint definitions can be separated into multiple constraint document files, with each constraint file defining one or more constraint rules or constraint macros. Global rules and global macros can reference other internal and external global rules and global macros. Internal rules and internal macros are defined within the same constraint file. External rules and external macros are imported from other constraint document files that define those rules and macros. Before referencing a set of external constraint rules or external constraint macros in your constraint file, you must specify those rules or macros in your file (using the <EXTERNAL_RULE_INCLUDE> element or the <EXTERNAL_MACRO_INCLUDE> element, respectively). In addition, DICOM administrators must insert the referenced constraint document files into the repository before inserting the referencing constraint files.

In the XML constraint schema ordcmct.xsd, <ACTION> elements are defined to associate conformance validation messages with a predicate, a constraint rule, or a constraint macro. If predicates are evaluated to the conditions specified in the <ACTION> elements associated with the predicates, you can see these messages after conformance validation by querying the view orddcm_conformance_vld_msgs. (See orddcm_conformance_vld_msgs for reference information.)

The following subsections contain examples that show how to create a variety of constraint documents:

Note:

These subsections contain references to tables in the DICOM standard. For more information about these tables, see the DICOM standard, which is available on the Web site for the National Electrical Manufacturers Association (NEMA) at

http://medical.nema.org/

10.2.2.1 Defining a Simple Constraint Rule

This subsection shows how to construct a simple constraint rule that checks two conditions required by the SOP Common Module, which is defined in the DICOM standard, in PS 3.3, Table C.12-1.

The following table shows the SOP Class UID and SOP Instance UID conditions as they are defined in the SOP Common Module of the DICOM standard.

Attribute Name Tag Type Attribute Description
SOP Class UID (0008,0016) 1 Uniquely identifies the SOP Class. See C.12.1.1.1 for further explanation. See also PS 3.4.
SOP Instance UID (0008,0018) 1 Uniquely identifies the SOP Instance. See C.12.1.1.1 for further explanation. See also PS 3.4.

The two entries in the preceding table indicate that the attributes SOP Class UID (0008,0016) and SOP Instance UID (0008,0018) must exist and cannot be empty.

The code segment in Example 10-10 shows a predicate that checks whether the attribute SOP Class UID (0008,0016) is not empty:

Example 10-10 Predicate for One Condition on SOP Class UID

<PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080016</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>

The code segment in Example 10-11 shows a predicate the checks whether the attribute SOP Instance UID (0008,0018) is not empty:

Example 10-11 Predicate for One Condition on SOP Instance UID

<PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080018</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>

Checking whether both of these attributes are not empty is equivalent to doing a logical AND operation for the two predicates shown in Example 10-10 and Example 10-11. The prescribed way to undertake this operation is to define another predicate that performs a logical AND operation on the preceding two predicates. Example 10-12 shows a predicate with a logical AND operation for these two conditions:

Example 10-12 Predicate for Two Conditions

<PREDICATE>
    <LOGICAL operator="and">
     <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080016</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080018</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
   </LOGICAL>
</PREDICATE>

A simpler way to define predicates having logical AND relations is by omitting the outer predicate that was shown in Example 10-12. Thus, taking the complete constraint rule from the constraint document ordcmcmd.xml, the global rule SOPCommonModule can be defined as shown in Example 10-13:

Example 10-13 Global Rule for Two Boolean Functions

<GLOBAL_RULE name="SOPCommonModule">
    <DESCRIPTION>
      A subset of SOP Common Module defined in DICOM standard,
      PS 3.3-2007, Table C.12-1
    </DESCRIPTION>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080016</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080018</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
  </GLOBAL_RULE>

Each global rule must have a unique name. Furthermore, each global rule can include an optional <DESCRIPTION> element to provide descriptive information about that rule.

The code segment in Example 10-13 shows how to define predicates that represent Boolean functions or logical relations. Predicates that represent relational relations can be defined similarly.

Example 10-14 is a partial code segment that shows two sample predicates within a global rule. These predicates ensure that no error is raised when the DICOM content that is being validated does not contain attributes in the global rule. Example 3-1 shows the complete code segment for this global rule (for the Patient Module).

Example 10-14 Global Rule for Two Conditions on Patient's Sex

<GLOBAL_RULE name="PatientModule">
.
.
.
   <PREDICATE>
     <BOOLEAN_FUNC operator="notEmpty">
       <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
     </BOOLEAN_FUNC>
   </PREDICATE>
   <PREDICATE>
     <DESCRIPTION>Patient's Sex</DESCRIPTION>
     <RELATIONAL operator="in">
       <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
       <STRING_VALUE>M</STRING_VALUE>
       <STRING_VALUE>F</STRING_VALUE>
       <STRING_VALUE>O</STRING_VALUE>
     </RELATIONAL>
   </PREDICATE>
.
.
.
</GLOBAL_RULE>

The first predicate in Example 10-14 tests the condition that the attribute Patient's Sex (0010, 0040) is not empty. This predicate ensures that all subsequent predicates that reference the attribute Patient's Sex (0010, 0040) are tested only when this predicate returns true during conformance validation. Thus, the second predicate is tested only when the DICOM content that is being validated contains the attribute Patient's Sex (0010, 0040) and the value is not empty. Therefore, no error is raised if the DICOM content does not contain the attribute Patient's Sex (0010, 0040).

See Section 10.2.2.4 for more examples of predicates that represent relational relations.

10.2.2.2 Defining Constraint Rules by Importing Other Constraint Rules

This subsection shows how to construct constraint rules hierarchically by referencing other external constraint rules. This section also shows how to reference external constraint rules.

The constraint document ordcmct.xml defines the global rule OracleOrdObject. This constraint rule is defined as the logical AND relation of three constraint rules: SOPCommonModule, GeneralSeriesModule, and GeneralStudyModule. Example 10-15 shows a global rule with a logical AND relation for these three constraint rules:

Example 10-15 Global Rule for a Logical Relation

<GLOBAL_RULE name="OracleOrdObject">
  <PREDICATE>
    <GLOBAL_RULE_REF>SOPCommonModule</GLOBAL_RULE_REF>
  </PREDICATE>
  <PREDICATE>
    <GLOBAL_RULE_REF>GeneralSeriesModule</GLOBAL_RULE_REF>
  </PREDICATE>
  <PREDICATE>
    <GLOBAL_RULE_REF>GeneralStudyModule</GLOBAL_RULE_REF>
  </PREDICATE>  
 </GLOBAL_RULE>

These three constraint rules are defined in the constraint document ordcmcmd.xml and imported into the DICOM constraint document ordcmct.xml. Example 10-16 shows an external rule for these constraint rules:

Example 10-16 External Rule for Three Constraint Rules

<EXTERNAL_RULE_INCLUDE name="GeneralStudyModule">
   A subset of General Study Module defined in DICOM standard, 
   PS 3.3-2007, Table C.7-3
 </EXTERNAL_RULE_INCLUDE>   
 <EXTERNAL_RULE_INCLUDE name="GeneralSeriesModule">
   A subset of General Series Module defined in DICOM standard,
   PS 3.3-2007, Table C.7-5a
 </EXTERNAL_RULE_INCLUDE> 
 <EXTERNAL_RULE_INCLUDE  name="SOPCommonModule">
   A subset of SOP Common Module defined in DICOM standard,
   PS 3.3-2007, Table C.12-1
 </EXTERNAL_RULE_INCLUDE>

Thus, the global rule OracleOrdObject references the global rule SOPCommonModule that is defined in Section 10.2.2.1. Other constraint rules can also reference the global rule SOPCommonModule. In this way, constraint documents can be written in a modular and structured fashion.

10.2.2.3 Defining and Referencing Constraint Macros

This subsection shows how to construct a constraint macro that checks whether a DICOM attribute is a code sequence attribute. The constraint macro performs this checking operation by following the first two conditions required by the Code Sequence Macro, which is defined in the DICOM standard, in PS 3.3, Table 8.8-1.

The following table shows the Code Value and Coding Scheme Designator conditions as they are defined in the Code Sequence Macro of the DICOM standard.

Attribute Name Tag Type Attribute Description
Code Value (0008,0100) 1C See Section 8.1. Required if a sequence item is present.
Coding Scheme Designator (0008,0102) 1C See Section 8.2. Required if a sequence item is present.

The two entries in the preceding table indicate that the mandatory child attributes Code Value (0008,0100) and Coding Scheme Designator (0008,0102) must not be empty.

Example 10-17 shows a global macro definition (from the default constraint document ordcmcmc.xml) that checks whether the attributes Code Value (0008,0100) and Coding Scheme Designator (0008,0102) are not empty:

Example 10-17 Global Macro for a Condition

<GLOBAL_MACRO name="CodeSequenceMacro">
   <DESCRIPTION>
     A subset of Code Sequence Macro defined in DICOM standard, 
     PS 3.3-2007, Table 8.8-1
   </DESCRIPTION>
  <PARAMETER_DECLARATION>CodeAttr</PARAMETER_DECLARATION>
  <PREDICATE>
   <DESCRIPTION>Code value must not be empty</DESCRIPTION>
   <BOOLEAN_FUNC operator="notEmpty">
    <ATTRIBUTE_TAG>${CodeAttr}.00080100</ATTRIBUTE_TAG>
   </BOOLEAN_FUNC>
  </PREDICATE>
  <PREDICATE>
   <DESCRIPTION>Coding scheme designator must not be empty</DESCRIPTION>
   <BOOLEAN_FUNC operator="notEmpty">
    <ATTRIBUTE_TAG>${CodeAttr}.00080102</ATTRIBUTE_TAG>
   </BOOLEAN_FUNC>
  </PREDICATE>
 </GLOBAL_MACRO>

Predicates that are included in constraint macros include operands that contain parameters. These parameters must be defined in <PARAMETER_DECLARATION> elements. When the parameters are referenced in these operands, the parameters must be preceded by the dollar sign symbol and enclosed within braces as in: ${ }. In the preceding code segment, the parameter CodeAttr represents the code sequence to be examined. Thus, checking whether the code value of the parameter CodeAttr is not empty is equivalent to checking whether the parameter ${CodeAttr}.00080100 is not empty.

Constraint macros can be invoked by one or more constraint rules, with the macro parameters being set to different values. To invoke a constraint macro, you must specify the name of the macro with the name value pairs of all parameters for that macro.

Example 10-18 shows the definition for the global rule GeneralSeriesModule (from the default constraint document ordcmcmd.xml), which invokes the constraint macro CodeSequenceMacro. The code statements where this macro is invoked are highlighted in bold.

Example 10-18 Global Rule with a Constraint Macro

<GLOBAL_RULE name="GeneralSeriesModule">
    <DESCRIPTION>
      A subset of General Series Module defined in DICOM standard,
      PS 3.3-2007, Table C.7-5a
    </DESCRIPTION>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>00080060</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
      <ACTION action="warning" when="false">
        missing attribute 00080060 
      </ACTION>
    </PREDICATE>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>0020000E</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
      <ACTION action="warning" when="false">
        missing attribute 0020000E 
      </ACTION>
    </PREDICATE>
    <PREDICATE>
      <LOGICAL operator="derive">
        <PREDICATE>
          <BOOLEAN_FUNC operator="notEmpty">
            <ATTRIBUTE_TAG>00400260</ATTRIBUTE_TAG>
          </BOOLEAN_FUNC>
        </PREDICATE>
        <PREDICATE>
          <INVOKE_MACRO>
            <MACRO_NAME>CodeSequenceMacro</MACRO_NAME>
            <PARAMETER>
              <NAME>CodeAttr</NAME>
              <VALUE>00400260</VALUE>
            </PARAMETER>
          </INVOKE_MACRO>
          <ACTION action="warning" when="false">
            missing attribute 00400260.00080100 or 00400260.00080102 
          </ACTION>
        </PREDICATE>
      </LOGICAL>
    </PREDICATE>
    <ACTION action="warning" when="false">
      GeneralSeriesModule is not satisfied
    </ACTION>
  </GLOBAL_RULE>  

Because the constraint macro CodeSequenceMacro is defined in a different constraint file, it is imported in the beginning of the constraint document ordcmcmd.xml, as follows:

<EXTERNAL_MACRO_INCLUDE name="CodeSequenceMacro">
Defines a code sequence macro</EXTERNAL_MACRO_INCLUDE>

When users check whether the DICOM content conforms to the constraint rule GeneralSeriesModule, the DICOM content is checked against the constraint macro CodeSequenceMacro, where the parameter CodeAttr is substituted as 00400260. Specifically, the predicate to check the <ATTRIBUTE_TAG> element ${CodeAttr}.00080100 not empty becomes 00400260.00080100 not empty. And, the <ATTRIBUTE_TAG> element ${CodeAttr}.00080102 not empty becomes 00400260.00080102 not empty.

If the constraint macro CodeSequenceMacro with the parameter CodeAttr substituted as 00400260 evaluates to false on the DICOM content, the view orddcm_conformance_vld_msgs contains the message "missing attribute 00400260.00080100 or 00400260.00080102" for the DICOM content. These conformance validation messages can be used to provide information about specific attributes in the DICOM content that do not conform to the constraint rules.

See the orddcm_conformance_vld_msgs view for more information about these messages.

10.2.2.4 Defining Recursive Constraint Macros

This subsection shows two examples that check a subset of attributes required by the SR Document Content Module, which is defined in the DICOM standard, in PS 3.3, Section C.17.3.

The following table shows the Content Sequence and Relationship Type attributes as they are defined in the Document Relationship Macro Attributes in Table C.17-6. The table also shows the Value Type attribute as it is defined in the Document Content Macro Attributes in Table C.17-5.

Attribute Name Tag Type Attribute Description
Content Sequence (0040,A730) 1C A potentially recursively nested Sequence of items that conveys content that is the Target of Relationships with the enclosing Source Content Item.

One or more Items may be included in this sequence.

Required if the enclosing Content Item has relationships.

Notes:

  1. If this Attribute is not present then the enclosing Item is a leaf.

  2. The order of Items within this Sequence is semantically significant for presentation.

See C.17.3.2.4 for further explanation.

Relationship Type (0040,A010) 1 The type of relationship between the (enclosing) Source Content Item and the Target Content Item.

IODs specify additional constraints on Relationships (including lists of Enumerated Values).

Defined Terms:


CONTAINS
HAS PROPERTIES
HAS OBS CONTEXT
HAS ACQ CONTEXT
INFERRED FROM
SELECTED FROM
HAS CONCEPT MOD

See C.17.3.2.4 for further explanation.

Value Type (0040,A040) 1 The type of the value encoded in this Content Item.

Defined Terms:


TEXT
NUM
CODE
DATETIME
DATE
TIME
UIDREF
PNAME
COMPOSITE
IMAGE
WAVEFORM
SCOORD
TCOORD
CONTAINER

See C.17.3.2.1 for further explanation.


For example, the attribute Content Sequence (0040,A730) provides the hierarchical structuring of the Content Tree (DICOM standard, PS 3.3, Section C.17.3.1) by recursively nesting Content Items. A parent (or source) Content Item has an explicit relationship to each child (or target) Content Item, which is conveyed by the attribute Relationship Type (0040,A010) (DICOM standard, PS 3.3, Section C.17.3.2.4).

To avoid infinite loops and control how many levels of the hierarchy structure to evaluate, use the preference parameter MAX_RECURSION_DEPTH in the preference document to specify the number of levels of recursion for a constraint macro. See Section 10.2.6.4 for information about defining this preference parameter in a preference document.

The code segment in Example 10-19 is an example of recursion with a single constraint macro that invokes itself. The code segment in Example 10-20 is an example of recursion between two different constraint macros, with the first macro invoking a second macro, which then invokes the first macro.

Note:

The examples in this section are not shipped with the installation software.

Recursion with a Single Constraint Macro

Example 10-19 defines the recursive global constraint macro DocumentContentMacro. This macro is invoked by the global constraint rule DocumentContentModule. The code statements where this macro is defined and invoked are highlighted in bold.

Example 10-19 One Constraint Macro with Recursion

<GLOBAL_MACRO name="DocumentContentMacro">
    <PARAMETER_DECLARATION>tag</PARAMETER_DECLARATION>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>${tag}.0040A010</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
    <PREDICATE>
      <RELATIONAL operator="in">
        <ATTRIBUTE_TAG>${tag}.0040A010</ATTRIBUTE_TAG>
        <STRING_VALUE>CONTAINS</STRING_VALUE>
        <STRING_VALUE>HAS PROPERTIES</STRING_VALUE>
        <STRING_VALUE>HAS OBS CONTEXT</STRING_VALUE>
        <STRING_VALUE>HAS ACQ CONTEXT</STRING_VALUE>
        <STRING_VALUE>INFERRED FROM</STRING_VALUE>
        <STRING_VALUE>SELECTED FROM</STRING_VALUE>
        <STRING_VALUE>HAS CONCEPT MOD</STRING_VALUE>
      </RELATIONAL>
    </PREDICATE>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>${tag}.0040A040</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
      <ACTION action="log" when="true">${RUNTIME_TAG} is not empty</ACTION>
    </PREDICATE>
    <PREDICATE>
      <LOGICAL operator="derive">
        <PREDICATE>
          <RELATIONAL operator="eq">
            <ATTRIBUTE_TAG>${tag}.0040A040</ATTRIBUTE_TAG>
            <STRING_VALUE>CONTAINER</STRING_VALUE>
          </RELATIONAL>
           <ACTION action="log" when="false">${RUNTIME_TAG} value is not
             CONTAINER</ACTION>
        </PREDICATE>
        <PREDICATE>
          <INVOKE_MACRO>
            <MACRO_NAME>DocumentContentMacro</MACRO_NAME>
            <PARAMETER>
              <NAME>tag</NAME>
              <VALUE>${tag}.0040A730[*]</VALUE>
            </PARAMETER>
          </INVOKE_MACRO>
        </PREDICATE>
      </LOGICAL>
    </PREDICATE>
  </GLOBAL_MACRO>
<GLOBAL_RULE name="DocumentContentModule">
    <PREDICATE>
      <INVOKE_MACRO>
        <MACRO_NAME>DocumentContentMacro</MACRO_NAME>
        <PARAMETER>
          <NAME>tag</NAME>
          <VALUE>0040A730[*]</VALUE>
        </PARAMETER>
      </INVOKE_MACRO>
    </PREDICATE>
  </GLOBAL_RULE>

During conformance validation, the ${RUNTIME_TAG} tags in <ACTION> elements are replaced by the DICOM value locators whose corresponding attributes in the DICOM content are evaluated to meet the condition specified by the when attribute of the <ACTION> element. The first action creates a message that contains a list of DICOM value locators, all ending with tag 0040A040, whose corresponding attributes in the DICOM content are not empty. The second action creates a message that contains a list of DICOM value locators, all ending with tag 0040A040, whose corresponding attributes in the DICOM content do not match CONTAINER.

In Example 10-19, the recursion occurs when the recursive constraint macro invokes itself by specifying the name value pair of the parameter defined for that macro.

In the definition of the macro DocumentContentMacro, the first predicate checks whether the attribute ${tag}.0040A010 is not empty. The second predicate uses a relational operation to check whether this attribute has a valid value. The third predicate checks whether the attribute ${tag}.0040A040 is not empty. The fourth predicate checks whether the value of ${tag}.0040A040 is CONTAINER. If so, then the macro DocumentContentMacro is invoked on the content sequence of ${tag}.0040A730[*]. The code [*] is a wildcard character that represents the numbered series of attributes in the constraint document to be checked by the macro.

Recursion with Two Constraint Macros

Example 10-20 defines two recursive global constraint macros: DocumentContentMacroA and DocumentContentMacroB. The code statements where these macros are defined and invoked are highlighted in bold.

Example 10-20 Two Constraint Macros with Recursion

<GLOBAL_MACRO name="DocumentContentMacroA">
    <PARAMETER_DECLARATION>attr</PARAMETER_DECLARATION>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>${attr}.0040A040</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
    <PREDICATE>
      <LOGICAL operator="derive">
        <PREDICATE>
          <RELATIONAL operator="eq">
            <ATTRIBUTE_TAG>${attr}.0040A040</ATTRIBUTE_TAG>
            <STRING_VALUE>CONTAINER</STRING_VALUE>
           </RELATIONAL>
        </PREDICATE>
        <PREDICATE>
          <INVOKE_MACRO>
            <MACRO_NAME>DocumentContentMacroB</MACRO_NAME>
            <PARAMETER>
              <NAME>tag</NAME>
              <VALUE>${attr}.0040A730[*]</VALUE>
            </PARAMETER>
          </INVOKE_MACRO>
        </PREDICATE>
      </LOGICAL>
    </PREDICATE>
  </GLOBAL_MACRO>
 
  <GLOBAL_MACRO name="DocumentContentMacroB">
    <PARAMETER_DECLARATION>tag</PARAMETER_DECLARATION>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>${tag}.0040A010</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
    <PREDICATE>
      <RELATIONAL operator="in">
        <ATTRIBUTE_TAG>${tag}.0040A010</ATTRIBUTE_TAG>
        <STRING_VALUE>CONTAINS</STRING_VALUE>
        <STRING_VALUE>HAS PROPERTIES</STRING_VALUE>
        <STRING_VALUE>HAS OBS CONTEXT</STRING_VALUE>
        <STRING_VALUE>HAS ACQ CONTEXT</STRING_VALUE>
        <STRING_VALUE>INFERRED FROM</STRING_VALUE>
        <STRING_VALUE>SELECTED FROM</STRING_VALUE>
        <STRING_VALUE>HAS CONCEPT MOD</STRING_VALUE>
      </RELATIONAL>
    </PREDICATE>
    <PREDICATE>
      <INVOKE_MACRO>
        <MACRO_NAME>DocumentContentMacroA</MACRO_NAME>
        <PARAMETER>
          <NAME>attr</NAME>
          <VALUE>${tag}</VALUE>
        </PARAMETER>
      </INVOKE_MACRO>
    </PREDICATE>
  </GLOBAL_MACRO>

In Example 10-20, the recursion occurs when DocumentContentMacroB invokes DocumentContentMacroA, and then DocumentContentMacroA invokes DocumentContentMacroB.

10.2.2.5 Using DICOM Value Locators in Constraint Documents

This subsection shows how to use DICOM value locators to specify attributes in constraint documents. DICOM value locators can be used to specify predicates that include private attributes and their definers. DICOM value locators can contain macros for substitution when the constraint document is loaded into the repository.

The following list shows a few examples of valid macro substitution strings:

  • A complete series of sublocators

  • A tag, including the special wildcard tag "."

  • A definer name (DICOM, the default name, or the name of a private definer)

  • An item number (a positive integer or the wildcard character '*')

See General Format for DICOM Value Locators for complete reference information.

Example 10-21 shows how to specify the attribute Content Sequence with a DICOM value locator in a global constraint macro and create a log of the results at run time. (This example uses some code from Example 10-19.) The DICOM value locators are highlighted in bold.

Example 10-21 DICOM Value Locator with a Wildcard Character in a Constraint Macro

<GLOBAL_MACRO name="DocumentContentMacro">
    <PARAMETER_DECLARATION>tag</PARAMETER_DECLARATION>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>${tag}.0040A010</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
    </PREDICATE>
    <PREDICATE>
      <RELATIONAL operator="in">
        <ATTRIBUTE_TAG>${tag}.0040A010</ATTRIBUTE_TAG>
        <STRING_VALUE>CONTAINS</STRING_VALUE>
        <STRING_VALUE>HAS PROPERTIES</STRING_VALUE>
        <STRING_VALUE>HAS OBS CONTEXT</STRING_VALUE>
        <STRING_VALUE>HAS ACQ CONTEXT</STRING_VALUE>
        <STRING_VALUE>INFERRED FROM</STRING_VALUE>
        <STRING_VALUE>SELECTED FROM</STRING_VALUE>
        <STRING_VALUE>HAS CONCEPT MOD</STRING_VALUE>
      </RELATIONAL>
    </PREDICATE>
    <PREDICATE>
      <BOOLEAN_FUNC operator="notEmpty">
        <ATTRIBUTE_TAG>${tag}.0040A040</ATTRIBUTE_TAG>
      </BOOLEAN_FUNC>
      <ACTION action="log" when="true">${RUNTIME_TAG} is not empty</ACTION>
    </PREDICATE>
    <PREDICATE>
      <LOGICAL operator="derive">
        <PREDICATE>
          <RELATIONAL operator="eq">
            <ATTRIBUTE_TAG>${tag}.0040A040</ATTRIBUTE_TAG>
            <STRING_VALUE>CONTAINER</STRING_VALUE>
          </RELATIONAL>
           <ACTION action="log" when="false">${RUNTIME_TAG} value is not
             CONTAINER</ACTION>
        </PREDICATE>
        <PREDICATE>
          <INVOKE_MACRO>
            <MACRO_NAME>DocumentContentMacro</MACRO_NAME>
            <PARAMETER>
              <NAME>tag</NAME>
              <VALUE>${tag}.0040A730[*]</VALUE>
            </PARAMETER>
          </INVOKE_MACRO>
        </PREDICATE>
      </LOGICAL>
    </PREDICATE>
  </GLOBAL_MACRO>
<GLOBAL_RULE name="DocumentContentModule">
    <PREDICATE>
      <INVOKE_MACRO>
        <MACRO_NAME>DocumentContentMacro</MACRO_NAME>
        <PARAMETER>
          <NAME>tag</NAME>
          <VALUE>0040A730[*]</VALUE>
        </PARAMETER>
      </INVOKE_MACRO>
    </PREDICATE>
  </GLOBAL_RULE>

The standard attribute tags 0040A010, 0040A040, and 0040A730 are defined as follows in the standard dictionary:

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A010</TAG>
   <NAME>Relationship Type</NAME>
   <VR>CS</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>
<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A040</TAG>
   <NAME>Value Type</NAME>
   <VR>CS</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>
<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A730</TAG>
   <NAME>Content Sequence</NAME>
   <VR>SQ</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

In the tag definition shown in the preceding code segment, the <VR> element of tag 0040A730 indicates that this tag is a sequence tag and the corresponding attribute in the DICOM content can contain multiple sequence items. Using a wildcard character in the DICOM value locator ensures that all the items for this attribute are checked.

Example 10-22 shows how to specify all the Relationship Type attributes with a DICOM value locator in a global rule. The DICOM value locator is highlighted in bold.

Example 10-22 DICOM Value Locator with a Special Wildcard Tag in a Global Rule

<GLOBAL_RULE name="MagicTagTest">
    <PREDICATE>
       <RELATIONAL operator="in">
        <ATTRIBUTE_TAG>..0040A010</ATTRIBUTE_TAG>
        <STRING_VALUE>CONTAINS</STRING_VALUE>
        <STRING_VALUE>HAS PROPERTIES</STRING_VALUE>
        <STRING_VALUE>HAS OBS CONTEXT</STRING_VALUE>
        <STRING_VALUE>HAS ACQ CONTEXT</STRING_VALUE>
        <STRING_VALUE>INFERRED FROM</STRING_VALUE>
        <STRING_VALUE>HAS CONCEPT MOD</STRING_VALUE>
      </RELATIONAL>
      <ACTION action="log" when="false">${RUNTIME_TAG} does not contain required
        values</ACTION>
    </PREDICATE>
  </GLOBAL_RULE>
 

In the preceding code segment, the DICOM value locator for all 0040A010 attributes includes the special wildcard tag "." to indicate that the predicate performs a relational operation to check all the Relational Type attributes in the DICOM content.

Note:

The following restrictions apply to the use of the special wildcard tag "." in a DICOM value locator:
  • It can be used by one predicate operand only.

  • It cannot be used within a recursive constraint macro, or to call a recursive constraint macro.

See General Format for DICOM Value Locators for more information about the DICOM value locator type.

10.2.3 Creating Mapping Documents and Metadata XML Schemas

Mapping documents define how the DICOM attributes are mapped into an XML document. The metadata XML document can be constrained by an XML schema, or it can be a well-formed XML document with no XML schema constraints.

The XML schema ordcmmp.xsd defines the XML schema that constrains mapping documents. (See Section B.6 for a listing of the mapping document schema ordcmmp.xsd.)

The following subsections describe the structure of mapping documents and metadata XML schemas. The subsections also contain code examples that show how to create mapping documents and corresponding metadata schemas:

10.2.3.1 Structure of a Mapping Document

Each mapping document must include a root element and a namespace declaration, similar to the following:

<XML_MAPPING_DOCUMENT xmlns="http://xmlns.oracle.com/ord/dicom/mapping_1_0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.oracle.com/ord/dicom/mapping_1_0
http://xmlns.oracle.com/ord/dicom/mapping_1_0"> 

The remaining elements in the mapping document, in order of appearance, are as follows:

  • <dt:DOCUMENT_HEADER>: This element is optional. It is used to keep the update record of the XML document. If this element is specified, add the following namespace declaration to the root element:

    namespace: xmlns:dt=http://xmlns.oracle.com/ord/dicom/datatype_1_0"
    

    See Section B.3 for more information about the data type definition schema ordcmrdt.xsd.

  • <NAMESPACE>: This mandatory element specifies the namespace of the metadata XML document. This namespace must match the target namespace of the corresponding metadata schema. If this element is empty, the extracted metadata XML is not schema constrained.

  • <ROOT_ELEM_TAG>: This mandatory element specifies the root element name of the metadata XML document.

  • <UNMAPPED_ELEM>: This element specifies the XML path to the element that is the parent element of all unmapped attributes. This XML path is relative to the root element (specified by the element <ROOT_ELEM_TAG>) of the metadata XML. If this element is omitted or empty, the parent element of the unmapped attributes is the root element of the metadata XML document. See Section 2.5 for more information about unmapped attributes.

  • <MAPPED_ELEM>: This element specifies the XML path to the element that is the parent element of all mapped attributes. This XML path is relative to the root element of the metadata XML (specified by the element <ROOT_ELEM_TAG>). If this element is omitted or empty, the parent element of the mapped attributes is the root element of the metadata XML document. See Section 2.5 for more information about mapped attributes.

  • <MAPPED_PATH>: This element specifies the XML path to a mapped attribute. This XML path is relative to the parent element of the mapped attributes as defined by the element <MAPPED_ELEM>. This element can be used multiple times within a mapping document to specify the XML paths to all mapped attributes. The order of appearance of each <MAPPED_PATH> element reflects the order of appearance of the mapped attributes in a metadata XML document. Within the <MAPPED_PATH> element, the <ATTRIBUTE_TAG> and <PATH> elements are used to define each mapped attribute tag and its XML path, respectively. See Section B.6 for more information about the mapping document schema ordcmmp.xsd.

10.2.3.2 Structure of a Metadata XML Schema

During the process of extracting DICOM metadata and encoding it into an XML document, a mapping document is used to encode the DICOM attributes into an XML document, and an XML schema is used to validate the encoded metadata XML document. To extract DICOM metadata into a schema-valid XML document, the mapping document and the XML schema definition for the metadata XML document must be synchronized.

The general rules for creating an XML schema for a metadata XML document that is specific to a particular application are as follows:

  • The order of the elements defined in the XML schema must match the order of the mapped XML paths for those elements.

  • The XML schema must use data types that are either compatible with or less restrictive than the data types defined by Oracle in the schema ordcmmddt.xsd.

  • To extract unmapped DICOM attributes into the XML document, the parent element of the unmapped attributes must be defined as type DATASET_T (as in the schema ordcmmddt.xsd).

  • If the attributes writeTag, writeName, writeDefiner, and writeRawValue of the <MAPPED_PATH> element are set to "true" in the mapping document, the XML schema must define the corresponding attributes tag, name, definer, and rawValue for each element that is described by the <MAPPED_PATH> element in the mapping document.

  • If the attribute occurs of the <MAPPED_PATH> element in the mapping document is set to "false" either implicitly or explicitly, the XML schema definition of the element must set the attribute minOccurs to "0".

  • If the attribute notEmpty of the <MAPPED_PATH> element in the mapping document is set to "false", the XML schema definition for the element must set the attribute xsi:nillable to "true". Otherwise, the element defined by the <MAPPED_PATH> element must permit an empty value.

See Section B.7 for more information about the data type definition schema ordcmmddt.xsd.

10.2.3.3 Creating a Mapping Document for Metadata with No Schema Constraints

This subsection describes how to create a mapping document and a well-formed metadata XML document with no XML schema constraints. For applications that require only a well-formed metadata XML document, the mapping document can contain an empty <NAMESPACE> element because the extracted metadata need not conform to any XML schema.

This subsection also includes a code example of a mapping document, followed by a code example of the resulting metadata XML document. Appropriate XML statements are highlighted in bold to show where the main actions occur in both the mapping document and the related XML document. Descriptions of each bolded XML statement follow the examples.

Example 10-23 shows a sample mapping document with an empty <NAMESPACE> element. This example also shows the values to be specified for the occurs, notEmpty, writeTag, writeDefiner, and writeName attributes in the <MAPPED_PATH> element to define the extracted metadata XML document. If these attributes are not specified, they are set to "false", the default value.

Example 10-23 Sample Mapping Document for Metadata with No Schema Constraints

<?xml version="1.0" encoding="UTF-8"?>
<XML_MAPPING_DOCUMENT 
    xmlns="http://xmlns.oracle.com/ord/dicom/mapping_1_0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://xmlns.oracle.com/ord/dicom/mapping_1_0
        http://xmlns.oracle.com/ord/dicom/mapping_1_0">
  <NAMESPACE></NAMESPACE>
  <ROOT_ELEM_TAG>DICOM_OBJECT</ROOT_ELEM_TAG>
  <UNMAPPED_ELEM>OTHER_ATTRIBUTES</UNMAPPED_ELEM>
  <MAPPED_ELEM>KEY_ATTRIBUTES</MAPPED_ELEM>
    
  <MAPPED_PATH occurs="true" notEmpty="true">
    <ATTRIBUTE_TAG>00100010</ATTRIBUTE_TAG>
    <PATH>PATIENT/NAME</PATH>
  </MAPPED_PATH>
    
  <MAPPED_PATH occurs="true" notEmpty="true">
    <ATTRIBUTE_TAG>00100020</ATTRIBUTE_TAG>
    <PATH>PATIENT/ID</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH occurs="true" notEmpty="false">
    <ATTRIBUTE_TAG>00100030</ATTRIBUTE_TAG>
    <PATH>PATIENT/BIRTH_DATE</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH occurs="false" notEmpty="false">
    <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
    <PATH>PATIENT/SEX</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH writeTag="true" writeDefiner="true" writeName="true">
    <ATTRIBUTE_TAG>00200010</ATTRIBUTE_TAG>
    <PATH>STUDY/ID</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH>
    <ATTRIBUTE_TAG>00080030</ATTRIBUTE_TAG>
    <PATH>STUDY/TIME</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH>
    <ATTRIBUTE_TAG>00081080</ATTRIBUTE_TAG>
    <PATH>STUDY/ADMITTING_DIAGNOSES_DESCRIPTION</PATH>
  </MAPPED_PATH>
 
</XML_MAPPING_DOCUMENT>
 

Example 10-24 shows the resulting metadata XML document whose XML metadata was extracted with the value of the extractOption parameter in the extractMetadata( ) method set to MAPPED.

Example 10-24 Resulting XML Document for Example 10-23

<?xml version="1.0" encoding="DEC-MCS"?>
<DICOM_OBJECT xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <KEY_ATTRIBUTES>
    <PATIENT>
      <NAME>
        <NAME type="unibyte">
          <FAMILY>CANCIO   2HR A-02-013</FAMILY>
        </NAME>
        <VALUE>CANCIO   2HR A-02-013</VALUE>
      </NAME>
      <ID>ISRSCT610b</ID>
      <BIRTH_DATE xsi:nil="true"/>
      <SEX xsi:nil="true"/>
    </PATIENT>
    <STUDY>
      <ID definer="DICOM" tag="00200010" name="Study ID">352</ID>
      <TIME>18:48:41.000000</TIME>
    </STUDY>
  </KEY_ATTRIBUTES>
</DICOM_OBJECT>

In Example 10-23 and Example 10-24, these actions occur:

  • In the mapping document, the <NAMESPACE> element is empty. As a result, the resulting extracted XML document does not include the default namespace declaration because it is not constrained by an XML schema.

  • The <ROOT_ELEM_TAG> element in the mapping document matches the root element tag (shown in the <DICOM_OBJECT> element) in the extracted XML document.

  • In the mapping document, the value of the notEmpty attribute of the <MAPPED_PATH> element for the DICOM attribute with tag 00100040 is "false". In the extracted XML document, the value of the xsi:nil attribute in the <BIRTH_DATE> element is set to "true" because this DICOM attribute is empty in the DICOM content.

  • In the mapping document, the <MAPPED_PATH> element for the DICOM attribute with tag 00200010, the writeTag, writeName, and writeDefiner attributes are set to "true". In the extracted XML document, the child element <ID> under the <STUDY> element has corresponding definer, tag, and name attributes.

  • In the mapping document, the <MAPPED_PATH> element for the DICOM attribute with tag 00081080 uses the default value ("false") for the occurs attribute. Because this DICOM attribute does not exist in the DICOM content, the element <ADMITTING_DIAGNOSES_DESCRIPTION> does not exist in the extracted XML document.

See extractMetadata( ) for reference information about this method and the supported values for the extractOption parameter.

10.2.3.4 Creating a Mapping Document for Metadata with Schema Constraints and a Mapped Section Only

This subsection describes how to create a mapping document and a metadata XML document with XML schema constraints, discarding the unmapped section. This example can be used in applications that require only the DICOM attributes defined in the mapped section of the XML metadata, and in metadata XML documents with XML schema constraints.

This subsection also includes code examples of a mapping document, an XML schema, and the resulting metadata XML document constrained by the schema. Appropriate XML statements are highlighted in bold to show where the main actions occur in both the mapping document and the related XML document. Descriptions of each bolded XML statement follow the examples.

The extractMetadata( ) method of the ORDDicom object can extract all or part of the metadata into an XML document based on the value of the extractOption parameter.

See extractMetadata( ) for reference information about this method and the supported values for the extractOption parameter.

Example 10-25 shows a sample mapping document that specifies the namespace of the metadata XML document, so that the metadata document can be constrained by an XML schema.

Example 10-25 Sample Mapping Document for Metadata with Schema Constraints and a Mapped Section Only

<?xml version="1.0" encoding="UTF-8"?>
<XML_MAPPING_DOCUMENT 
    xmlns="http://xmlns.oracle.com/ord/dicom/mapping_1_0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://xmlns.oracle.com/ord/dicom/mapping_1_0
        http://xmlns.oracle.com/ord/dicom/mapping_1_0">
  <NAMESPACE>http://www.mycompany.com/dicom/example2</NAMESPACE>
  <ROOT_ELEM_TAG>DICOM_OBJECT</ROOT_ELEM_TAG>
  <UNMAPPED_ELEM></UNMAPPED_ELEM>
  <MAPPED_ELEM></MAPPED_ELEM>
    
  <MAPPED_PATH occurs="true" notEmpty="true">
    <ATTRIBUTE_TAG>00100010</ATTRIBUTE_TAG>
    <PATH>PATIENT/NAME</PATH>
  </MAPPED_PATH>
    
  <MAPPED_PATH occurs="true" notEmpty="true">
    <ATTRIBUTE_TAG>00100020</ATTRIBUTE_TAG>
    <PATH>PATIENT/ID</PATH>
  </MAPPED_PATH>
  <MAPPED_PATH occurs="true" notEmpty="false">
    <ATTRIBUTE_TAG>00100030</ATTRIBUTE_TAG>
    <PATH>PATIENT/BIRTH_DATE</PATH>
  </MAPPED_PATH>
  
  <MAPPED_PATH occurs="false" notEmpty="false">
    <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
    <PATH>PATIENT/SEX</PATH>
  </MAPPED_PATH>
  
  <MAPPED_PATH writeTag="true" writeDefiner="true" writeName="true">
    <ATTRIBUTE_TAG>00200010</ATTRIBUTE_TAG>
    <PATH>STUDY/ID</PATH>
  </MAPPED_PATH>
  
  <MAPPED_PATH>
    <ATTRIBUTE_TAG>00080030</ATTRIBUTE_TAG>
    <PATH>STUDY/TIME</PATH>
  </MAPPED_PATH>
 
   <MAPPED_PATH>
    <ATTRIBUTE_TAG>00081080</ATTRIBUTE_TAG>
    <PATH>STUDY/ADMITTING_DIAGNOSES_DESCRIPTION</PATH>
  </MAPPED_PATH>
 
</XML_MAPPING_DOCUMENT>

The mapping document in Example 10-25 differs from the mapping document in Example 10-23 as follows:

  • The <NAMESPACE> element contains a value.

  • The <UNMAPPED_ELEM> and the <MAPPED_ELEM> elements are empty, thus the mapped path is relative to the <ROOT_ELEM_TAG> element.

The XML schema for the mapping document in Example 10-25 is defined in Example 10-26:

Example 10-26 Sample XML Schema for Example 10-25

<?xml version="1.0" encoding="UTF-8"?>
 <xs:schema 
    xmlns="http://www.mycompany.com/dicom/example2" 
    xmlns:xdb="http://xmlns.oracle.com/xdb" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://www.mycompany.com/dicom/example2" 
    elementFormDefault="qualified" 
    attributeFormDefault="unqualified">
   <xs:element name="DICOM_OBJECT">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="PATIENT">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="NAME" type="PERSON_NAME"/>
              <xs:element name="ID" type="xs:string"/>
              <xs:element name="BIRTH_DATE"  type="xs:date" nillable="true"/>
              <xs:element name="SEX"  type="xs:string" minOccurs="0"
                  nillable="true"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="STUDY">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="ID" type = "ID_TYPE" minOccurs="0"
                  nillable="true"/>
              <xs:element name="TIME"  type="xs:time" minOccurs="0"
                  nillable="true"/>
              <xs:element name="ADMITTING_DIAGNOSES_DESCRIPTION"  type="xs:string"
                  minOccurs="0" nillable="true"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="PERSON_NAME">
    <xs:sequence>
      <xs:element name="NAME">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="FAMILY" type="xs:string" minOccurs="0"
                nillable="true"/>
            <xs:element name="GIVEN" type="xs:string" minOccurs="0"
                nillable="true"/>
            <xs:element name="MIDDLE" type="xs:string" minOccurs="0"
                nillable="true"/>
            <xs:element name="PREFIX" type="xs:string" minOccurs="0"
                nillable="true"/>
            <xs:element name="SUFFIX" type="xs:string" minOccurs="0"
                nillable="true"/>
          </xs:sequence>
          <xs:attribute name="type" default="unibyte">
            <xs:simpleType>
              <xs:restriction base="xs:token">
                <xs:enumeration value="unibyte"/>
                <xs:enumeration value="ideographic"/>
                <xs:enumeration value="phonetic"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:complexType>
      </xs:element>
      <xs:element name="VALUE" minOccurs="0" nillable="true">
        <xs:simpleType>
          <xs:restriction base="xs:token">
            <xs:maxLength value="64"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
   </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ID_TYPE">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute name="tag" type="xs:string"/>
        <xs:attribute name="definer" type="xs:string"/>
        <xs:attribute name="name" type="xs:string"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

In Example 10-25 and the associated XML schema (in Example 10-26), the following elements and data types are defined:

  • The namespace declaration of the metadata XML schema has the same value as the <NAMESPACE> element in the mapping document.

  • For the <MAPPED_PATH> element in the mapping document that has the value of the notEmpty attribute set to "false" either explicitly, as for tag 00100030, or implicitly using the default value, as for tag 00800030, the corresponding element defined in the XML schema has the value of the nillable attribute set to "true", as in the <BIRTH_DATE> element and the <TIME> element.

  • Any <MAPPED_PATH> element in the mapping document that has the value of the occurs attribute set to "false" either explicitly, as for tag 00100040, or implicitly using the default value, as for tag 00800030, the corresponding element defined in the XML schema must have the value of the attribute minOccurs set to "0", as in the <SEX> element and the <TIME> element.

  • The data type defined in the XML schema must be compatible with the data type defined by Oracle in the schema ordcmmddt.xsd. In Example 2, the "PERSON_NAME" data type definition is copied from the schema ordcmmddt.xsd, while the "ID_TYPE" data type is defined so that the <ID> element under the <STUDY> element can have the tag, definer, and name attributes. The "ID_TYPE" data type is compatible with the "SH_ATTR_T" data type defined by Oracle. The <SEX> element is defined to use the "xs:string" data type, which is compatible with the Oracle-defined data type "CS".

  • The <UNMAPPED_ELEM> element is empty in the mapping document, and the root element <DICOM_OBJECT> of the metadata XML is not defined as the "DATASET_T" type. With this schema constraint, a valid metadata XML document can include a mapped section only. Thus, if the application attempts to extract metadata using a value of "ALL" or "STANDARD" for the extractOption parameter, the attempt returns this error:

    ORA-53259: cannot extract metadata that conforms to the schema definition

Example 10-27 shows the resulting metadata XML document whose XML metadata was extracted with the value of the extractOption parameter in the extractMetadata( ) method set to MAPPED.

Example 10-27 Resulting XML Document for Example 10-25

<?xml version="1.0" encoding="DEC-MCS"?>
<DICOM_OBJECT xmlns="http://www.mycompany.com/dicom/example2"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.mycompany.com/dicom/example2
  http://www.mycompany.com/dicom/example2">
  <PATIENT>
    <NAME>
      <NAME type="unibyte">
        <FAMILY>CANCIO   2HR A-02-013</FAMILY>
      </NAME>
      <VALUE>CANCIO   2HR A-02-013</VALUE>
    </NAME>
    <ID>ISRSCT610b</ID>
    <BIRTH_DATE xsi:nil="true"/>
    <SEX xsi:nil="true"/>
  </PATIENT>
  <STUDY>
    <ID definer="DICOM" tag="00200010" name="Study ID">352</ID>
    <TIME>18:48:41.000000</TIME>
  </STUDY>
</DICOM_OBJECT>

10.2.3.5 Creating a Mapping Document for Metadata with Schema Constraints

This subsection describes how to create a mapping document and a metadata XML document with XML schema constraints, including the unmapped section.

This subsection also includes code examples of a mapping document, an XML schema, and the resulting metadata XML document constrained by the schema. Appropriate XML statements are highlighted in bold to show where the main actions occur in both the mapping document and the related XML document. Descriptions of each bolded XML statement follow the examples.

Example 10-28 shows a sample mapping document that includes a sequence type attribute in the mapped section.

Example 10-28 Sample Mapping Document for Metadata with Schema Constraints

<?xml version="1.0" encoding="UTF-8"?>
<XML_MAPPING_DOCUMENT 
    xmlns="http://xmlns.oracle.com/ord/dicom/mapping_1_0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://xmlns.oracle.com/ord/dicom/mapping_1_0
        http://xmlns.oracle.com/ord/dicom/mapping_1_0">
  <NAMESPACE>http://www.mycompany.com/dicom/example3</NAMESPACE>
  <ROOT_ELEM_TAG>DICOM_OBJECT</ROOT_ELEM_TAG>
  <UNMAPPED_ELEM>OTHER_ATTRIBUTES</UNMAPPED_ELEM>
  <MAPPED_ELEM>KEY_ATTRIBUTES</MAPPED_ELEM>
 
  <MAPPED_PATH occurs="true" notEmpty="true">
    <ATTRIBUTE_TAG>00100010</ATTRIBUTE_TAG>
    <PATH>PATIENT/NAME</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH occurs="true" notEmpty="true">
    <ATTRIBUTE_TAG>00100020</ATTRIBUTE_TAG>
    <PATH>PATIENT/ID</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH occurs="true" notEmpty="false">
<ATTRIBUTE_TAG>00100030</ATTRIBUTE_TAG>
    <PATH>PATIENT/BIRTH_DATE</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH occurs="false" notEmpty="false">
    <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
    <PATH>PATIENT/SEX</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH writeTag="true" writeDefiner="true" writeName="true">
    <ATTRIBUTE_TAG>00200010</ATTRIBUTE_TAG>
    <PATH>STUDY/ID</PATH>
  </MAPPED_PATH>
 
  <MAPPED_PATH>
    <ATTRIBUTE_TAG>00081084</ATTRIBUTE_TAG>
    <PATH>
      STUDY/ADMITTING_DIAGNOSES_CODE_SEQUENCE
    </PATH>
  </MAPPED_PATH>
 
</XML_MAPPING_DOCUMENT>
 

The mapping document in Example 10-28 differs from the mapping document in Example 10-25 as follows:

  • The <UNMAPPED_ELEM> and <MAPPED_ELEM> elements are not empty.

  • There is a <MAPPED_PATH> element for tag 00081084, which is of DICOM sequence type.

The XML schema code segment in Example 10-29 shows how to define the unmapped root element for the mapping document in Example 10-28 to include the unmapped section in the extracted metadata XML document. This code segment also shows how to use Oracle-defined data types from the schema ordcmmddt.xsd.

Example 10-29 Sample XML Schema for Example 10-28

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="http://www.mycompany.com/dicom/example3" 
           xmlns:xdb="http://xmlns.oracle.com/xdb" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           targetNamespace="http://www.mycompany.com/dicom/example3" 
           elementFormDefault="qualified" 
           attributeFormDefault="unqualified">
  <xs:include schemaLocation="http://www.mycompany.com/dicom/datatype_3"/>
  <xs:element name="DICOM_OBJECT">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="KEY_ATTRIBUTES">
          <xs:complexType>
            <xs:sequence>
             <xs:element name="PATIENT">
               <xs:complexType>
                 <xs:sequence>
                   <xs:element name="NAME" type="PN">
                   </xs:element>
                   <xs:element name="ID" type="xs:string">
                   </xs:element>
                   <xs:element name="BIRTH_DATE" type="xs:date" nillable="true">
                   </xs:element>
                   <xs:element name="SEX" type="xs:string" minOccurs="0"
                       nillable="true">
                   </xs:element>
                 </xs:sequence>
               </xs:complexType>
             </xs:element>
             <xs:element name="STUDY">
               <xs:complexType>
                 <xs:sequence>
                   <xs:element name="ID" type="SH_ATTR_T" minOccurs="0"
                       nillable="true"/>
                   <xs:element name="ADMITTING_DIAGNOSES_CODE_SEQUENCE" type="SQ"
                       nillable="true" minOccurs="0"/>
                 </xs:sequence>
               </xs:complexType>
             </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        </xs:element>
        <xs:element name="OTHER_ATTRIBUTES" type="DATASET_T" minOccurs="0"
            maxOccurs="unbounded">
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

In Example 10-28 and the associated XML schema (in Example 10-29), the following actions occur:

  • Instead of defining its own data types as in Section 10.2.3.4, this XML schema uses the Oracle-defined data types by copying the schema ordcmmddt.xsd into an application-specific XSD file and then changing the namespace declaration, as in this XML code segment:

    <xs:schema 
    xmlns="http://www.mycompany.com/dicom/example3" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
    xmlns:xdb="http://xmlns.oracle.com/xdb" 
    targetNamespace="http://www.mycompany.com/dicom/example3"
    elementFormDefault="qualified" 
    attributeFormDefault="unqualified">
    

    This data type XML schema is registered as a global XML schema with Oracle XML DB, using the following namespace URL:

    "http://www.mycompany.com/dicom/datatype_3"
    

    Then, this registered namespace URL is included in the metadata XML schema.

    See Oracle XML DB Developer's Guide for more information about registering XML schemas.

  • Because the Oracle-defined data types are included in the XML schema, they can be referenced directly, as shown in the <NAME>, <ADMITTING_DIAGNOSES_CODE_SEQUENCE>, and <OTHER_ATTRIBUTES> elements.

  • The <OTHER_ATTRIBUTES> element is defined as type "DATASET_T" to enable the inclusion of all unmapped DICOM attributes under this element when a value of ALL or STANDARD is passed to the extractMetadata( ) method for the extractOption parameter. Because the minOccurs attribute is defined as 0, when the value MAPPED is passed to the extractMetadata( ) method, only the mapped section is included in the extracted XML document.

Example 10-30 shows the resulting metadata XML document whose XML metadata was extracted with the value of the extractOption parameter in the extractMetadata( ) method set to MAPPED.

Example 10-30 Resulting XML Document for Example 10-28 (MAPPED)

<?xml version="1.0" encoding="DEC-MCS"?>
<DICOM_OBJECT xmlns="http://www.mycompany.com/dicom/example3"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.mycompany.com/dicom/example3
   http://www.mycompany.com/dicom/example3">
  <KEY_ATTRIBUTES>
    <PATIENT>
      <NAME>
        <NAME type="unibyte">
          <FAMILY>CANCIO   2HR A-02-013</FAMILY>
        </NAME>
        <VALUE>CANCIO   2HR A-02-013</VALUE>
      </NAME>
      <ID>ISRSCT610b</ID>
      <BIRTH_DATE xsi:nil="true"/>
      <SEX xsi:nil="true"/>
    </PATIENT>
    <STUDY>
      <ID definer="DICOM" tag="00200010" name="Study ID">352</ID>
      <ADMITTING_DIAGNOSES_CODE_SEQUENCE>
        <ITEM>
          <SHORT_STRING tag="00080100" definer="DICOM" name="Code Value"
             offset="692" length="0"/>
          <SHORT_STRING tag="00080102" definer="DICOM" name="Coding Scheme
             Designator" offset="700" length="0"/>
          <SHORT_STRING tag="00080103" definer="DICOM" name="Coding Scheme
             Version" offset="708" length="0"/>
          <LONG_STRING tag="00080104" definer="DICOM" name="Code Meaning"
             offset="716" length="0"/>
          <CODE_STRING tag="00080105" definer="DICOM" name="Mapping Resource"
             offset="724" length="0"/>
          <DATE_TIME tag="00080106" definer="DICOM" name="Context Group Version"
             offset="732" length="0" xsi:nil="true" rawValue=""
               byteOrderLE="true"/>
          <DATE_TIME tag="00080107" definer="DICOM" name="Context Group Local
               Version" offset="740" length="0" xsi:nil="true" rawValue=""
               byteOrderLE="true"/>
          <CODE_STRING tag="0008010B" definer="DICOM" name="Context Group
               Extension Flag" offset="748" length="0"/>
          <UNIQUE_ID tag="0008010D" definer="DICOM" name="Context Group Extension
               Creator UID" offset="756" length="0" xsi:nil="true" rawValue=""
               byteOrderLE="true"/>
          <CODE_STRING tag="0008010F" definer="DICOM" name="Context Identifier"
               offset="764" length="0"/>
        </ITEM>
      </ADMITTING_DIAGNOSES_CODE_SEQUENCE>
    </STUDY>
  </KEY_ATTRIBUTES>
</DICOM_OBJECT>

Example 10-31 shows the resulting metadata XML document whose XML metadata was extracted with the value of the extractOption parameter in the extractMetadata( ) method set to ALL.

Example 10-31 Resulting XML Document for Example 10-28 (ALL)

<?xml version="1.0" encoding="DEC-MCS"?>
<DICOM_OBJECT xmlns="http://www.mycompany.com/dicom/example3"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.mycompany.com/dicom/example3
   http://www.mycompany.com/dicom/example3">
  <KEY_ATTRIBUTES>
    <PATIENT>
      <NAME>
        <NAME type="unibyte">
          <FAMILY>CANCIO   2HR A-02-013</FAMILY>
        </NAME>
        <VALUE>CANCIO   2HR A-02-013</VALUE>
      </NAME>
      <ID>ISRSCT610b</ID>
      <BIRTH_DATE xsi:nil="true"/>
      <SEX xsi:nil="true"/>
    </PATIENT>
    <STUDY>
      <ID definer="DICOM" tag="00200010" name="Study ID">352</ID>
      <ADMITTING_DIAGNOSES_CODE_SEQUENCE>
        <ITEM>
          <SHORT_STRING tag="00080100" definer="DICOM" name="Code Value"
             offset="692" length="0"/>
          <SHORT_STRING tag="00080102" definer="DICOM" name="Coding Scheme
             Designator" offset="700" length="0"/>
          <SHORT_STRING tag="00080103" definer="DICOM" name="Coding Scheme
             Version" offset="708" length="0"/>
          <LONG_STRING tag="00080104" definer="DICOM" name="Code Meaning"
             offset="716" length="0"/>
          <CODE_STRING tag="00080105" definer="DICOM" name="Mapping Resource"
             offset="724" length="0"/>
          <DATE_TIME tag="00080106" definer="DICOM" name="Context Group Version"
             offset="732" length="0" xsi:nil="true" rawValue=""
             byteOrderLE="true"/>
          <DATE_TIME tag="00080107" definer="DICOM" name="Context Group Local
             Version" offset="740" length="0" xsi:nil="true" rawValue=""
             byteOrderLE="true"/>
          <CODE_STRING tag="0008010B" definer="DICOM" name="Context Group
             Extension Flag" offset="748" length="0"/>
          <UNIQUE_ID tag="0008010D" definer="DICOM" name="Context Group Extension
             Creator UID" offset="756" length="0" xsi:nil="true" rawValue=""
             byteOrderLE="true"/>
          <CODE_STRING tag="0008010F" definer="DICOM" name="Context Identifier"
             offset="764" length="0"/>
        </ITEM>
      </ADMITTING_DIAGNOSES_CODE_SEQUENCE>
    </STUDY>
  </KEY_ATTRIBUTES>
  <OTHER_ATTRIBUTES>
    <OTHER_BYTE tag="00020001" definer="DICOM" name="File Meta Information
       Version" offset="156" length="2">AQA=
 
</OTHER_BYTE>
    <UNIQUE_ID tag="00020002" definer="DICOM" name="Media Storage SOP Class UID"
       offset="166" length="26">1.2.840.10008.5.1.4.1.1.2</UNIQUE_ID>
    <UNIQUE_ID tag="00020003" definer="DICOM" name="Media Storage SOP Instance
       UID" offset="200" length="54">1.2.392.200036.91</UNIQUE_ID>
    <UNIQUE_ID tag="00020010" definer="DICOM" name="Transfer Syntax UID"
       offset="262" length="18">1.2.840.10008.1.2</UNIQUE_ID>
    <UNIQUE_ID tag="00020012" definer="DICOM" name="Implementation Class UID"
       offset="288" length="16">1.2.804.114118.3</UNIQUE_ID>
<APPLICATION_ENTITY tag="00020016" definer="DICOM" name="Source Application Entity
    Title" offset="326" length="0" xsi:nil="true" rawValue="" byteOrderLE="true"/>
    <CODE_STRING tag="00080008" definer="DICOM" name="Image Type" offset="334"
       length="22">ORIGINAL</CODE_STRING>
    <CODE_STRING tag="00080008" definer="DICOM" name="Image Type" offset="334"
       length="22">PRIMARY</CODE_STRING>
    <CODE_STRING tag="00080008" definer="DICOM" name="Image Type" offset="334"
       length="22">AXIAL</CODE_STRING>
    <UNIQUE_ID tag="00080016" definer="DICOM" name="SOP Class UID" offset="364"
       length="26">1.2.840.10008.5.1.4.1.1.2</UNIQUE_ID>
    <UNIQUE_ID tag="00080018" definer="DICOM" name="SOP Instance UID" offset="398"
       length="54">1.2.392.200036.91</UNIQUE_ID>
    <DATE tag="00080020" definer="DICOM" name="Study Date" offset="460"
   length="8">2004-02-23</DATE>
    <DATE tag="00080022" definer="DICOM" name="Acquisition Date" offset="476"
   length="8">2004-02-23</DATE>
    <DATE tag="00080023" definer="DICOM" name="Content Date" offset="492"
   length="8">2004-02-23</DATE>
    <TIME tag="00080030" definer="DICOM" name="Study Time" offset="508"
   length="14">18:48:41.000000</TIME>
    <TIME tag="00080032" definer="DICOM" name="Acquisition Time" offset="530"
   length="14">18:50:52.100000</TIME>
    <TIME tag="00080033" definer="DICOM" name="Content Time" offset="552"
   length="14">18:50:52.725000</TIME>
    <SHORT_STRING tag="00080050" definer="DICOM" name="Accession Number"
   offset="574" length="4">352</SHORT_STRING>
    <CODE_STRING tag="00080060" definer="DICOM" name="Modality" offset="586"
   length="2">CT</CODE_STRING>
.
.
.
 
    <SHORT_STRING tag="00400253" definer="DICOM" name="Performed Procedure Step
      ID" offset="1742" length="4">351</SHORT_STRING>
    <OTHER_WORD tag="7FE00010" definer="DICOM" name="Pixel Data" offset="1766"
      length="524288" truncated="true" xsi:nil="true" endian="little"/>
  </OTHER_ATTRIBUTES>
</DICOM_OBJECT>

10.2.3.6 Using DICOM Value Locators in Mapping Documents

This subsection shows how to use DICOM value locators to specify attributes in mapping documents. Example 10-32 shows how to use a DICOM value locator to specify the family name field of the Patient's Name attribute with unibyte encoding in a mapping document. The XML statement where this action is performed is highlighted in bold.

Example 10-32 DICOM Value Locator for an Attribute with Unibyte Encoding in a Mapping Document

<MAPPED_PATH>
    <ATTRIBUTE_TAG>00100010#UnibyteFamily</ATTRIBUTE_TAG>
    <PATH>FAMILY_NAME</PATH>
</MAPPED_PATH>

Using the mapping document that contains the code shown in Example 10-32 in the extractMetadata( ) method results in an XML document that contains the tag <FAMILY_NAME> with the value that corresponds to the family name field of the attribute 00100010.

Example 10-33 shows how to use a DICOM value locator to specify an attribute embedded within a sequence attribute in a mapping document.

Example 10-33 DICOM Value Locator for an Embedded Sequence Attribute in a Mapping Document

<MAPPED_PATH>
    <ATTRIBUTE_TAG>0040A730[2].0040A010</ATTRIBUTE_TAG>
    <PATH>RELATIONSHIP</PATH>
</MAPPED_PATH>

Using the mapping document that contains the code shown in Example 10-33 in the extractMetadata( ) method results in an XML document that contains the tag <RELATIONSHIP> with the value that corresponds to the value of attribute 0040A010. Attribute 0040A010 is embedded within the second item of the sequence attribute 0040A730.

The standard attribute tags 0040A730 and 0040A010 are defined as follows in the standard dictionary:

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A730</TAG>
   <NAME>Content Sequence</NAME>
   <VR>SQ</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>0040A010</TAG>
   <NAME>Relationship Type</NAME>
   <VR>CS</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

In the tag definition shown in the preceding code segment, the <VR> element shows that attribute 0040A730 is an attribute of sequence type. By using the DICOM value locator, any attribute that is embedded within a sequence type attribute can be retrieved individually into the resulting XML metadata document.

Example 10-34 shows how to use a DICOM value locator to specify a single value of an attribute that contains multiple values in a mapping document.

Example 10-34 DICOM Value Locator for a Single Attribute Value in a Mapping Document

<MAPPED_PATH>
    <ATTRIBUTE_TAG>00080008[3]</ATTRIBUTE_TAG>
    <PATH>IMAGE_TYPE</PATH>
</MAPPED_PATH>

Using the mapping document that contains the code shown in Example 10-34 in the extractMetadata( ) method results in an XML document that contains the tag <IMAGE_TYPE> with the value that corresponds to the third value of the attribute 00080008.

The standard attribute tag 00080008 is defined as follows in the standard dictionary:

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>00080008</TAG>
   <NAME>Image Type</NAME>
   <VR>CS</VR>
   <VM>1-n</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

In the tag definition shown in the preceding code segment, the <VM> element shows that the attribute can contain multiple values. Using the DICOM value locator with an item number such as 00080008[3] ensures that the specific (third) value is retrieved.

See General Format for DICOM Value Locators for more information about the DICOM value locator type.

10.2.4 Creating Standard Dictionary Documents

Standard dictionary documents are XML representations of the data dictionary defined by the DICOM standard.

The XML schema ordcmsd.xsd defines the XML schema that constrains standard dictionary documents. (See Section B.10 for a listing of the standard dictionary document schema ordcmsd.xsd. See the text included within the <xs: annotation> element for a detailed description of the schema elements.)

The default standard dictionary document ordcmsd.xml is an XML representation of the data dictionary, as defined in Part 6 of the DICOM standard.

The XML schema ordcmrdt.xsd defines the DICOM standard data types and Oracle extensions to those data types, which are used by all other DICOM XML schemas. (See Section B.3 for a listing of the data type definition schema ordcmrdt.xsd.)

Note:

Standard dictionary documents must not include any other attributes, such as attributes defined by manufacturers of modalities or organizations other than the DICOM Standards Committee.

Through the Oracle Technology Network, Oracle may release new standard dictionary documents along with installation instructions for DICOM administrators. These new standard dictionary documents reflect new releases of, or addendum to, the DICOM standard.

The following subsections contain examples that show how to create standard dictionary documents:

10.2.4.1 Defining Standard Attributes

The standard attribute definition in the standard dictionary permits two types of attribute tags: simple tags and wildcard tags. An attribute tag value consists of the group number followed by an element number.

A simple attribute tag is 4-byte hexadecimal number that consists of a group number followed by an element number (for example: 10871100).

A wildcard attribute tag represents a set of hexadecimal numbers. It also consists of a group number followed by an element number, where portions of the value are replaced by the character x or X (for example: 1087xx00).

Each standard attribute in the standard dictionary document is represented by a <STANDARD_ATTRIBUTE_DEFINITION> element. Each standard attribute listed in the XML document corresponds to a related tag that is defined in Part 6 of the DICOM standard.

Note:

The definer name "DICOM" and the UID "1.2.840.10008.1" are reserved by Oracle to refer to DICOM standard attributes.

Defining a Standard Attribute Using a Simple Attribute Tag

Example 10-35 shows how to define a standard attribute with a simple attribute tag. The XML statements where this action is defined are highlighted in bold.

Example 10-35 Definition of a Standard Attribute with a Simple Attribute Tag

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>00080008</TAG>
   <NAME>Image Type</NAME>
   <VR>CS</VR>
   <VM>1-n</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

InExample 10-35, the <TAG> element represents the hexadecimal value of the attribute tag 00080008, which is defined by the DICOM standard. This attribute tag value consists of a group number, followed by an element number. The <NAME> element represents the name of the attribute tag that is defined by the DICOM standard. The <VR> element represents the value representation of the attribute tag that is defined by the DICOM standard. The <VM> element represents the value multiplicity of the attribute tag defined by the DICOM standard. (See the type <VR_T> and the type <VM_T> listed in the XML schema ordcmrdt.xsd for more information about the value representation and value multiplicity data types supported by Oracle Multimedia DICOM.)

Defining a Standard Attribute Using a Wildcard Attribute Tag

Example 10-36 shows how to define a standard attribute with a wildcard attribute tag. The XML statements where this action is defined are highlighted in bold.

Example 10-36 Definition of a Standard Attribute with a Wildcard Attribute Tag

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>60xx0010</TAG>
   <NAME>Overlay Rows</NAME>
   <VR>US</VR>
   <VM>1</VM>
</STANDARD_ATTRIBUTE_DEFINITION>

In Example 10-36, the standard attribute definition contains the wildcard tag 60xx0010.

10.2.4.2 Retiring Standard Attributes

Standard attributes included in the standard dictionary document are retired in the DICOM standard when they are no longer needed. Example 10-37 shows the definition of a standard attribute as retired. The XML statement where this action is defined is highlighted in bold.

Example 10-37 Definition of a Standard Attribute As Retired

<STANDARD_ATTRIBUTE_DEFINITION>
   <TAG>00080010</TAG>
   <NAME>Recognition Code</NAME>
   <VR>CS</VR>
   <VM>1</VM>
   <RETIRED>true</RETIRED>
</STANDARD_ATTRIBUTE_DEFINITION>

In Example 10-37, for the <RETIRED> element a value of true indicates that the attribute is retired and corresponds to the RET value used in the DICOM standard. Oracle recommends providing the <VR> and <VM> element values for a retired attribute to enable the metadata to be extracted from the DICOM content.

10.2.5 Creating Private Dictionary Documents

Private dictionary documents are XML documents that list the attributes defined by modality manufacturers or organizations other than the DICOM Standards Committee.

Private organizations or manufacturers of modalities can include attributes that are specific to their particular organizations in their DICOM content. These private attributes must be defined in a private dictionary document and stored in the data model repository to enable Oracle Multimedia to process metadata associated with the private attributes in the DICOM content.

The XML schema ordcmpv.xsd defines the XML schema that constrains private dictionary documents. (See Section B.9 for a listing of the private dictionary document schema ordcmpv.xsd.)

The default private dictionary document ordcmpv.xml lists the private attributes defined by Oracle.

The XML schema ordcmrdt.xsd defines the DICOM standard data types and Oracle extensions to those data types, which are used by all other DICOM XML schemas. (See Section B.3 for a listing of the data type definition schema ordcmrdt.xsd.)

The following subsections contain examples that show how to create private dictionary documents:

10.2.5.1 Defining Private Attributes

The private attribute definition in the private dictionary permits three types of attribute tags: simple tags, wildcard tags, and range tags. An attribute tag value consists of the group number followed by an element number.

A simple attribute tag is 4-byte hexadecimal number that consists of a group number followed by an element number (for example: 10871100).

A wildcard attribute tag represents a set of hexadecimal numbers. It also consists of a group number followed by an element number, where portions of the value are replaced by the character x or X (for example: 1087xx00).

A range attribute tag represents a range of hexadecimal numbers. It consists of two simple attribute tags that define a range of values. The starting range value must be less than the ending range value.

Each private attribute in the private dictionary document is represented by a <PRIVATE_ATTRIBUTE_DEFINITION> element.

Note:

Keep these additional guidelines in mind:
  • Do not use wildcard attribute tags within range attribute tags.

  • The definer name "DICOM" and the UID "1.2.840.10008.1" are reserved by Oracle to refer to DICOM standard attributes. Do not use them in private dictionaries.

  • Oracle recommends associating all DICOM private attributes in the DICOM content with a UID-qualified name.

  • The value of a tag-definer pair must be unique within the private dictionary document.

Defining a Private Attribute Using a Simple Attribute Tag

Example 10-38 shows how to define a private attribute with a simple attribute tag. The XML statements where this action is defined are highlighted in bold.

Example 10-38 Definition of a Private Attribute with a Simple Attribute Tag

<PRIVATE_ATTRIBUTE_DEFINITION>
  <TAG>FFFF1001</TAG>
  <NAME>locator macro tag</NAME>
  <DEFINER>ORACLE</DEFINER>
  <VR>SQ</VR>
  <VM>1</VM>
 </PRIVATE_ATTRIBUTE_DEFINITION>

In Example 10-38, the <TAG> element represents the hexadecimal value of the attribute tag FFFF1001. The <NAME> element represents the name of the organization defining the tag, ORACLE. The <VR> element represents the value representation of the attribute tag. The <VR> element is defined as type VR_T in the XML schema ordcmrdt.xsd. The <VR> element value must be one of the values that are listed for type <VR_T> in the XML schema ordcmrdt.xsd. The <VM> element represents the value multiplicity of the attribute tag. The <VM> element is defined as type VM_T in the XML schema ordcmrdt.xsd. The <VM> element value must be one of the values listed for type VM_T in the XML schema ordcmrdt.xsd. (See the type <VR_T> and the type <VM_T> listed in the XML schema ordcmrdt.xsd for more information about the value representation and value multiplicity data types supported by Oracle Multimedia DICOM.)

Defining a Private Attribute Using a Wildcard Attribute Tag

Example 10-39 shows how to define a private attribute with a wildcard attribute tag. The XML statements where this action is defined are highlighted in bold.

Example 10-39 Definition of a Private Attribute with a Wildcard Attribute Tag

<PRIVATE_ATTRIBUTE_DEFINITION>
   <TAG>0119XX00</TAG>
   <NAME>PRIVATE TAG1</NAME>
   <DEFINER>PRIVATE_ORG</DEFINER>
   <VR>IS</VR>
   <VM>1</VM>
</PRIVATE_ATTRIBUTE_DEFINITION>

In Example 10-39, the private attribute definition contains the wildcard tag 0119XX00 and the definer name PRIVATE_ORG.

Defining a Private Attribute Using a Range Attribute Tag

Example 10-40 shows how to define a private attribute with a range attribute tag. The XML statements where this action is defined are highlighted in bold.

Example 10-40 Definition of a Private Attribute with a Range Attribute Tag

<PRIVATE_ATTRIBUTE_DEFINITION>
   <TAG_RANGE>
      <dt:STARTING_TAG>A0110010</dt:STARTING_TAG>
      <dt:ENDING_TAG>A01AAA10</dt:ENDING_TAG>
    </TAG_RANGE>
   <NAME>Private Tag</NAME>
   <DEFINER>1.2.840.423</DEFINER>
   <VR>ST</VR>
   <VM>1</VM>
</PRIVATE_ATTRIBUTE_DEFINITION>

In Example 10-40, the private attribute definition contains a range tag that specifies all tag ranges from A0110010 to A01AAA10. The definer name 1.2.840.423 is a UID value.

Note:

An attribute definition cannot match another attribute definition of the same tag-definer pair within a private dictionary document.

The following XML code segment shows an example of an attribute definition that is not permitted in the private dictionary:

<PRIVATE_ATTRIBUTE_DEFINITION>
  <TAG>0119XX00</TAG>
  <NAME>private tag</NAME>
  <DEFINER>PRIVATE_ORG</DEFINER>
.
.
.
 </PRIVATE_ATTRIBUTE_DEFINITION>
 
<PRIVATE_ATTRIBUTE_DEFINITION>
  <TAG>01191100</TAG>
  <NAME>private tag</NAME>
  <DEFINER>PRIVATE_ORG</DEFINER>
.
.
.
 </PRIVATE_ATTRIBUTE_DEFINITION>

In the preceding code segment, the tag-definer pair (01191100, PRIVATE_ORG) matches the tag-definer pair (0119XX00, PRIVATE_ORG).

10.2.5.2 Defining Attribute Definers

An attribute definer refers to the definer name and UID of an organization defining private attributes.

The <ATTRIBUTE_DEFINERS> element is an optional element that represents all private definer names and definer UIDs used in a private dictionary document.

Note:

The definer name "DICOM" and the UID "1.2.840.10008.1" are reserved by Oracle to refer to DICOM standard attributes. Do not use them in private dictionaries.

The <ATTRIBUTE_DEFINERS> element is of type ATTR_DEFINERS_T. This type is defined in the XML schema ordcmrdt.xsd.

Example 10-41 shows how to define the definer name and UID for an organization that defines private attributes:

Example 10-41 Definition of an Attribute Definer

<ATTRIBUTE_DEFINERS>
  <dt:ATTR_DEFINER>
   <dt:NAME>1.2.1234.12345.123456.2.0</dt:NAME>
   <dt:UID>1.2.1234.12345.123456.2.0</dt:UID>
  </dt:ATTR_DEFINER>
  <dt:ATTR_DEFINER>
   <dt:NAME>PRIVATE ORG</dt:NAME>
   <dt:UID>1.2.123.1234</dt:UID>
  </dt:ATTR_DEFINER>
 </ATTRIBUTE_DEFINERS>

In Example 10-41, the prefix dt is mapped to the namespace http://xmlns.oracle.com/ord/dicom/datatype_1_0 where the <ATTR_DEFINER> element is defined. The value of the <dt:NAME> element represents the name of the private organization. The value of the <dt:UID> element represents the UID of the private organization.

10.2.5.3 Retiring Private Attributes

Private attributes included in private dictionary documents can be retired when they are no longer needed. Example 10-42 shows how to define a private attribute as retired. The XML statement where this action is defined is highlighted in bold.

Example 10-42 Definition of a Private Attribute as Retired

<PRIVATE_ATTRIBUTE_DEFINITION>
   <TAG>01191100</TAG>
   <NAME>locator macro tag</NAME>
   <DEFINER>PRIVATE_ORG</DEFINER>
   <VR>SQ</VR>
   <VM>1</VM>
   <RETIRED>true</RETIRED>
</PRIVATE_ATTRIBUTE_DEFINITION>

In Example 10-42, for the <RETIRED> element, a value of true indicates that the attribute is retired and corresponds to the RET value used in the DICOM standard. Oracle recommends providing the <VR> and <VM> element values for a retired attribute to enable the metadata to be extracted from the DICOM content.

10.2.6 Creating Preference Documents

Preference documents are XML documents that list the set of preference parameters that define the run-time behavior of Oracle Multimedia DICOM.

The XML document ordcmpf.xsd defines the XML schema that constrains preference documents. See Section B.8 for a listing of the preference document schema ordcmpf.xsd.

The default preference document ordcmpf.xml includes the default values for the run-time preference parameters for Oracle Multimedia DICOM.

Within a preference document, a <PREFERENCE_DEF> element is used to define each preference parameter and its value.

Note:

Keep these additional guidelines in mind:
  • A maximum of two (one Oracle-defined and one user-defined) preference documents are permitted in the repository.

  • Changes to preference parameter values in preference documents change the behavior of DICOM methods, functions, and procedures. Specifically, preference parameter values that are defined in the user-defined preference document override the default values defined in the Oracle-defined preference document ordcmpf.xml.

  • All preference parameter names and their associated values are defined by Oracle. User-defined preference documents can change the values of the Oracle-defined preference parameters.

See the text included within the <xs: annotation> element in Example B-8 for a detailed description of the preference parameters and their valid values.

The following subsections contain examples that show how to define preference parameter values in a preference document:

10.2.6.1 Defining the BINARY_SKIP_INVALID_ATTR Preference Parameter

The BINARY_SKIP_INVALID_ATTR preference parameter is used to specify whether Oracle Multimedia DICOM includes or skips invalid attributes and their values in the binary output of DICOM content when making a copy of the DICOM Part 10 file. Invalid attributes are attributes that do not conform to the specified DICOM standard. Example 10-43 shows how to define this preference parameter in a preference document.

Example 10-43 Definition of the BINARY_SKIP_INVALID_ATTR Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>BINARY_SKIP_INVALID_ATTR</PARAMETER>
    <DESCRIPTION>
      Do not skip the value of attributes that do not conform to the 
      DICOM specification when making a copy of a DICOM Part 10 file.
    </DESCRIPTION>
    <VALUE>false</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter BINARY_SKIP_INVALID_ATTR.

The <VALUE> element represents the value of the BINARY_SKIP_INVALID_ATTR preference parameter, which is false by default.

If the value of this preference parameter is false, invalid attributes and their values are included in the corresponding output. If the preference parameter value is set to true, the attribute values are included in the output with length 0.

10.2.6.2 Defining the EXP_IF_NULL_ATTR_IN_CONSTRAINT Preference Parameter

The EXP_IF_NULL_ATTR_IN_CONSTRAINT preference parameter is used to specify whether Oracle Multimedia DICOM throws an exception when encountering a missing attribute or a null attribute value during conformance validation. Example 10-44 shows how to define this preference parameter in a preference document.

Example 10-44 Definition of the EXP_IF_NULL_ATTR_IN_CONSTRAINT Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>EXP_IF_NULL_ATTR_IN_CONSTRAINT</PARAMETER>
    <DESCRIPTION>
      Throw an exception if a missing attribute or a null 
      attribute value is encountered during conformance 
      validation.
    </DESCRIPTION>
    <VALUE>true</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter EXP_IF_NULL_ATTR_IN_CONSTRAINT.

The <VALUE> element represents the value of the EXP_IF_NULL_ATTR_IN_CONSTRAINT preference parameter, which is true by default.

In a constraint predicate that is not preceded by a notEmpty Boolean function predicate on an attribute, when the value of this preference parameter is true, an exception is thrown at the first occurrence of either of these conditions:

  • The attribute is missing.

  • The attribute has a null value.

See Example 10-14 for more information.

If the value is set to false, no exception is thrown.

This preference parameter affects the results of the method isConformanceValid( ). See the isConformanceValid( ) method for more information.

10.2.6.3 Defining the MANDATE_ATTR_TAGS_IN_STL Preference Parameter

The MANDATE_ATTR_TAGS_IN_STL preference parameter is used to specify whether Oracle Multimedia DICOM enforces the rule that all tags used by the constraint and mapping documents must be listed in the stored tag list document. Example 10-45 shows how to define this preference parameter in a preference document.

Example 10-45 Definition of the MANDATE_ATTR_TAGS_IN_STL Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>MANDATE_ATTR_TAGS_IN_STL</PARAMETER>
    <DESCRIPTION>
      All tags in the constraint and mapping docs must be listed in the 
      STORED_TAG_LIST document.
    </DESCRIPTION>
    <VALUE>true</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter MANDATE_ATTR_TAGS_IN_STL.

The <VALUE> element represents the value of the MANDATE_ATTR_TAGS_IN_STL preference parameter, which is false by default.

The value of this preference parameter determines whether to enforce the rule that all tags used by the constraint and mapping documents are listed in the stored tag list document. If the value of this preference parameter is set to true, the rule is enforced. If the value is false, the rule is not enforced.

However, if an existing stored tag list document does not satisfy the rule, the value of the preference parameter cannot be set to true until the stored tag list document is updated. Also, if the value of this preference parameter is true, only constraint and mapping documents that use tags listed in the stored tag list document can be inserted into the repository.

10.2.6.4 Defining the MAX_RECURSION_DEPTH Preference Parameter

The MAX_RECURSION_DEPTH preference parameter is used to specify the maximum level of recursion Oracle Multimedia DICOM uses to evaluate recursive constraint macros during conformance validation. Example 10-46 shows how to define this preference parameter in a preference document.

Example 10-46 Definition of the MAX_RECURSION_DEPTH Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>MAX_RECURSION_DEPTH</PARAMETER>
    <DESCRIPTION>
      The maximum level of recursion when evaluating a recursive constraint 
      during conformation validation.
    </DESCRIPTION>
    <VALUE>16</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter MAX_RECURSION_DEPTH.

The <VALUE> element represents the value of the MAX_RECURSION_DEPTH preference parameter. Valid values are integers from 1 to 32767. The default is 16. If the recursion level exceeds the value of this parameter, an exception is thrown.

See Section 10.2.2.4 for more information about recursive constraint macros.

10.2.6.5 Defining the SPECIFIC_CHARACTER_SET Preference Parameter

The SPECIFIC_CHARACTER_SET preference parameter is used to specify the character set Oracle Multimedia DICOM uses to decode certain data elements (those with value representations of SH, LO, ST, LT, PN, and UT) when the standard attribute Specific Character Set is not specified. Example 10-47 shows how to define this preference parameter in a preference document.

Example 10-47 Definition of the SPECIFIC_CHARACTER_SET Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>SPECIFIC_CHARACTER_SET</PARAMETER>
    <DESCRIPTION>
      Use the ASCII character set to decode data elements SH (Short String), 
      LO (Long String), ST (Short Text), LT (Long Text), PN (Person Name), 
      and UT (Unlimited Text) when the Specific Character Set Attribute is
      missing.
    </DESCRIPTION>
    <VALUE>ASCII</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter SPECIFIC_CHARACTER_SET.

The <VALUE> element represents the value of the SPECIFIC_CHARACTER_SET preference parameter. Valid values are:

Character Sets
ASCII(default value)
ISO_IR 100
ISO_IR 101
ISO_IR 109
ISO_IR 110
ISO_IR 144
ISO_IR 127
ISO_IR 126
ISO_IR 138
ISO_IR 148
ISO_IR 13
ISO_IR 166
ISO_IR 192
GB18030

The value of this preference parameter determines how data elements with value representations of SH (Short String), LO (Long String), ST (Short Text) LT (Long Text), PN (Person Name), and UT (Unlimited Text) are decoded when the standard attribute Specific Character Set (0008,0005) is missing. The DICOM standard mandates using the default character set ISO-IR 6 or ASCII for decoding when the standard attribute Specific Character Set is not specified. This preference parameter enables applications to specify a character set other than the DICOM standard default character set in these cases.

10.2.6.6 Defining the SQ_WRITE_LEN Preference Parameter

The SQ_WRITE_LEN preference parameter is used to specify how the method writeMetadata( ) encodes DICOM sequence (SQ) types. Example 10-48 shows how to define this preference parameter in a preference document.

Example 10-48 Definition of the SQ_WRITE_LEN Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>SQ_WRITE_LEN</PARAMETER>
    <DESCRIPTION>
      All sequence types are encoded in XML with an explicit length and 
      without sequence delimiters.
    </DESCRIPTION>
    <VALUE>true</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter SQ_WRITE_LEN.

The <VALUE> element represents the value of the SQ_WRITE_LEN preference parameter, which is true by default.

The value of this preference parameter specifies how the DICOM sequence (SQ) types are encoded by the method writeMetadata( ). See the writeMetadata( ) method for more information.

If the value of this preference parameter is true, the SQ types are encoded with explicit lengths and without item or sequence delimiters. This default behavior enables DICOM viewers to skip the sequence attributes.

If the value is set to false, the SQ types are encoded with variable (undefined) lengths and terminated with sequence delimiters. This option enables backward compatibility with older DICOM viewers and DICOM applications that support only undefined lengths for SQ types.

10.2.6.7 Defining the VALIDATE_METADATA Preference Parameter

The VALIDATE_METADATA preference parameter is used to specify whether to validate XML documents that are used in DICOM functions and procedures. Example 10-49 shows how to define this preference parameter in a preference document.

Example 10-49 Definition of the VALIDATE_METADATA Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>VALIDATE_METADATA</PARAMETER>
    <DESCRIPTION>
      Do not validate XML metadata documents.
    </DESCRIPTION>
    <VALUE>false</VALUE>
 </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter VALIDATE_METADATA.

The <VALUE> element represents the value of the preference parameter VALIDATE_METADATA, which is false by default.

The value of this preference parameter determines whether to validate the XML documents used in the DICOM functions and procedures. All XML documents used in the DICOM functions and procedures, except those that are generated by the method extractMetadata( ), are validated against the Oracle default DICOM metadata schema. The XML documents generated by the method extractMetadata( ) are validated against the XML schema whose namespace is defined in the specified mapping document. See the extractMetadata( ) method and Section 10.1.3 for more information.

If the value of this preference parameter is false, the XML documents are not validated.

If the value is set to true, the XML documents are validated against a specific XML schema that is registered with Oracle XML DB.

10.2.6.8 Defining the XML_SKIP_ATTR Preference Parameter

The XML_SKIP_ATTR preference parameter is used to specify size limits for DICOM attributes to omit when encoding into XML. Example 10-50 shows how to define this preference parameter in a preference document.

Example 10-50 Definition of the XML_SKIP_ATTR Preference Parameter

<PREFERENCE_DEF>
    <PARAMETER>XML_SKIP_ATTR</PARAMETER>
    <DESCRIPTION>
      When encoding DICOM attributes into XML, omit the DICOM attributes
      with sizes larger than 512 bytes.
    </DESCRIPTION>
    <VALUE>512</VALUE>
  </PREFERENCE_DEF>

The <PARAMETER> element specifies the Oracle-defined preference parameter XML_SKIP_ATTR.

The <VALUE> element represents the value of the XML_SKIP_ATTR preference parameter. Valid values are integers from 128 to 232-1. The default is 512.

The value of this preference parameter is used to specify size limits for DICOM attributes to be omitted when encoding into XML. Omit DICOM attributes whose size (in bytes) in the DICOM content is larger than the value of this preference parameter. If an attribute of type SQ is omitted, its child items are also omitted.

In addition, the value of this preference parameter affects the following:

  • The metadata generated by the method extractMetadata( ). See the extractMetadata( ) method for more information.

  • The behavior of the setProperties( ) method. See the setProperties( ) method for more information.

10.2.7 Creating UID Definition Documents

UID definition documents are XML representations of the unique identifiers (UIDs) defined by the DICOM standard. The UID definitions are used by Oracle Multimedia DICOM to parse the DICOM content.

The XML schema ordcmui.xsd defines the XML schema that constrains UID definition documents. (See Section B.12 for a listing of the UID definition document schema ordcmui.xsd. See the text included within the <xs: annotation> element for a detailed description of the attributes used in the schema.)

The default UID definition document ordcmui.xml includes the UIDs listed in Part 6 of the DICOM standard.

Within a UID definition document, a <UID_DEF> element is used to define each UID definition.

Note:

Keep these additional guidelines in mind:
  • A maximum of two (one Oracle-defined and one user-defined) UID definition documents are permitted in the repository.

  • Changes in user-defined UID definition documents must be limited to updates in the DICOM standard or additions of new UID values. See Part 5 of the DICOM standard for more information about creating privately defined unique identifiers.

  • Existing UIDs defined by the DICOM standard can be changed only to include updates in the DICOM standard.

The following subsections contain examples that show how to create UID definitions in UID definition documents:

10.2.7.1 Defining UID Definitions

Example 10-51 shows how to define a storage class UID definition. The XML statements where this action is defined are highlighted in bold.

Example 10-51 Definition of a Storage Class UID Definition

<UID_DEF classification="storageClass" contentType="image">
    <UID>1.2.840.10008.5.1.4.1.1.2</UID>
    <NAME>CT Image Storage</NAME>
  </UID_DEF>

In Example 10-51, the <UID> element value 1.2.840.10008.5.1.4.1.1.2 represents a UID value that is defined by the DICOM standard. The <NAME> element value CT Image Storage represents the UID name that is defined by the DICOM standard. The value of the classification attribute "storageClass" in the <UID_DEF> element corresponds to the UID type SOP Class defined by the DICOM standard. The value of the contentType attribute "image" indicates that the DICOM content contains pixel data.

10.2.7.2 Retiring UID Definitions

Example 10-52 shows how to define a UID definition for transfer syntax as retired. The XML statements where this action is defined are highlighted in bold.

Example 10-52 Definition of a UID Definition as Retired

<UID_DEF classification="transferSyntax" isCompressed="true" isEVR="true"
          isLE="true" retired="true">
    <UID>1.2.840.10008.1.2.4.52</UID>
    <NAME>JPEG Extended (Process 3 and 5) (Retired)</NAME>
  </UID_DEF>

In Example 10-52, the <UID> element value 1.2.840.10008.1.2.4.52 represents a UID value that is defined by the DICOM standard. The <NAME> element value JPEG Extended (Process 3 and 5) (Retired) represents the UID name that is defined by the DICOM standard. The value of the classification attribute "transferSyntax" corresponds to the UID type Transfer Syntax defined by the DICOM standard. The values of the attributes isCompressed, isEVR (explicit VR), and isLE (little endian) are derived from the transfer syntax definitions listed in Part 5 of the DICOM standard. The value of the retired attribute "true" indicates that this UID definition is retired.

10.2.8 Creating Stored Tag List Documents

Stored tag list documents specify the DICOM attributes to be extracted from the embedded DICOM content and stored in the XML metadata attribute of the ORDDicom object when the setProperties( ) method is called. The XML schema ordcmstl.xsd defines the XML schema that constrains stored tag list documents. (See Section B.11 for a listing of the stored tag list document schema ordcmstl.xsd.)

Generally, stored tag list documents contain the attribute tags used in mapping and constraint documents. Each attribute tag value in a stored tag list document is defined by an <ATTRIBUTE_TAG> element.

Oracle recommends using the generateTagListDocument( ) Function to create a stored tag list document. For example, a stored tag list might include some tags shown in the following code segment:

<ATTRIBUTE_TAG>00080008[3]</ATTRIBUTE_TAG>
<ATTRIBUTE_TAG>00081155(DICOM)</ATTRIBUTE_TAG>
<ATTRIBUTE_TAG>00082112.00081150</ATTRIBUTE_TAG>
<ATTRIBUTE_TAG>00082112.0040A170.00080104</ATTRIBUTE_TAG>
<ATTRIBUTE_TAG>0040A730.0040A123[1]#PersonName</ATTRIBUTE_TAG>
<ATTRIBUTE_TAG>0040A730[2].0040A160</ATTRIBUTE_TAG>

See Section 11.4 for examples of generating and inserting stored tag list documents into the repository. See Section 3.2.10 for information about using a stored tag list to extract specific attributes from DICOM content.