11 Creating DICOM Configuration Documents

11.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 11-1 shows a code segment for the standard attribute Patient's Name. The XML statements where these actions are defined are highlighted in bold.

<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.

11.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 11-2 shows the XML statement where this action is defined.

<UNDEFINED_STANDARD_ATTRIBUTES action="remove" />

11.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 11-3 shows a code segment for the private attribute 10871100(PRIVATE ORG). The XML statements where these actions are defined are highlighted in bold.

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

In Example 11-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.

11.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.

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

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

Similarly, Example 11-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.

<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 11-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.

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

Example 11-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.

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

11.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 11-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.

<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 11-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.

<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.

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

11.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.

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 11-10 shows a predicate that checks whether the attribute SOP Class UID (0008,0016) is not empty:

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

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

   <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 11-10 and Example 11-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 11-12 shows a predicate with a logical AND operation for these 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 11-12. Thus, taking the complete constraint rule from the constraint document ordcmcmd.xml, the global rule SOPCommonModule can be defined as shown in Example 11-13:

  <GLOBAL_RULE name="SOPCommonModule">
    <DESCRIPTION>
      A subset of SOP Common Module defined in DICOM standard
    </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 11-13 shows how to define predicates that represent Boolean functions or logical relations. Predicates that represent relational relations can be defined similarly.

Example 11-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).

<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 11-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 11.2.2.4 for more examples of predicates that represent relational relations.

11.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 11-15 shows a global rule with a logical AND relation for these three constraint rules:

 <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 11-16 shows an external rule for these constraint rules:

 <EXTERNAL_RULE_INCLUDE name="GeneralStudyModule">
   A subset of General Study Module defined in DICOM standard
 </EXTERNAL_RULE_INCLUDE>   
 <EXTERNAL_RULE_INCLUDE name="GeneralSeriesModule">
   A subset of General Series Module defined in DICOM standard
 </EXTERNAL_RULE_INCLUDE> 
 <EXTERNAL_RULE_INCLUDE  name="SOPCommonModule">
   A subset of SOP Common Module defined in DICOM standard
 </EXTERNAL_RULE_INCLUDE>

Thus, the global rule OracleOrdObject references the global rule SOPCommonModule that is defined in Section 11.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.

11.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.

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 11-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:

  <GLOBAL_MACRO name="CodeSequenceMacro">
   <DESCRIPTION>
     A subset of Code Sequence Macro defined in DICOM standard
   </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 11-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.

<GLOBAL_RULE name="GeneralSeriesModule">
    <DESCRIPTION>
      A subset of General Series Module defined in DICOM standard
    </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.

11.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.

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 11.2.5.6 for information about defining this preference parameter in a preference document.

The code segment in Example 11-19 is an example of recursion with a single constraint macro that invokes itself. The code segment in Example 11-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.

Recursion with a Single Constraint Macro

Example 11-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.

<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 11-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 11-20 defines two recursive global constraint macros: DocumentContentMacroA and DocumentContentMacroB. The code statements where these macros are defined and invoked are highlighted in bold.

  <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 11-20, the recursion occurs when DocumentContentMacroB invokes DocumentContentMacroA, and then DocumentContentMacroA invokes DocumentContentMacroB.

11.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 11-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 11-19.) The DICOM value locators are highlighted in bold.

<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 11-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.

<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 Example 11-22, 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.

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

11.2.4.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"
  

• <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.

11.2.4.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.

11.2.4.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 11-24 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.

<?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 11-25 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.

<?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 11-24 and Example 11-25, 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.

11.2.4.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 11-26 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.

<?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 11-26 differs from the mapping document in Example 11-24 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 11-26 is defined in Example 11-27:

<?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 11-26 and the associated XML schema (in Example 11-27), 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 11-28 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.

<?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>

11.2.4.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 11-29 shows a sample mapping document that includes a sequence type attribute in the mapped section.

<?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 11-29 differs from the mapping document in Example 11-26 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 11-30 shows how to define the unmapped root element for the mapping document in Example 11-29 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.

<?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 11-29 and the associated XML schema (in Example 11-30), the following actions occur:

• Instead of defining its own data types as in Section 11.2.4.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 global and local 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 11-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 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 11-32 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.

<?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>

11.2.4.6 Using DICOM Value Locators in Mapping Documents

This subsection shows how to use DICOM value locators to specify attributes in mapping documents. Example 11-33 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.

<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 11-33 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 11-34 shows how to use a DICOM value locator to specify an attribute embedded within a 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 11-34 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 11-35 shows how to use a DICOM value locator to specify a single value of an attribute that contains multiple values 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 11-35 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.

11.2.5.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 11-36 shows how to define this preference parameter in a preference document.

  <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.

11.2.5.2 Defining the CONFORMANCE_LEVEL Preference Parameter

The CONFORMANCE_LEVEL preference parameter is used to specify which types of errors and exceptions Oracle Multimedia DICOM ignores or reports when processing DICOM content. Example 11-37 shows how to define this preference parameter in a preference document.

  <PREFERENCE_DEF>
    <PARAMETER>CONFORMANCE_LEVEL</PARAMETER>
    <DESCRIPTION>
      Ignore selected exceptions.
    </DESCRIPTION>
    <VALUE>ignoreException</VALUE>
  </PREFERENCE_DEF>

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

The <VALUE> element represents the value of the CONFORMANCE_LEVEL parameter, which is ignoreException by default. Other valid values are: leastConform and mostConform.

The default value ignoreException instructs all functions to ignore the types of exceptions specified in the preference parameter IGNORED_EXP_LIST.

The value leastConform instructs all functions to ignore errors and exceptions to maximize the processing of DICOM content.

If the value is set to mostConform, all functions throw an exception when encountering DICOM content that does not conform to the DICOM standard. (This behavior does not include backward compatibility cases that are allowed by the DICOM standard.)

11.2.5.3 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 11-38 shows how to define this preference parameter in a preference document.

  <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 11-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.

11.2.5.4 Defining the IGNORED_EXP_LIST Preference Parameter

The IGNORED_EXP_LIST preference parameter is used to specify the types of exceptions that Oracle Multimedia DICOM ignores when processing DICOM content. This preference parameter is effective only when the value of the CONFORMANCE_LEVEL preference parameter is set to ignoreException. Example 11-39 shows how to define this preference parameter in a preference document.

  <PREFERENCE_DEF>
    <PARAMETER>IGNORED_EXP_LIST</PARAMETER>
    <DESCRIPTION>
      Do not throw exceptions if: mandatory attributes are missing
      from the DICOM content (MISSING_ATTR), the DICOM file magic number
      "DICM" is missing (MISSING_MAGIC), an attribute has an invalid value
      representation value (INVALID_VR), an attribute has an incorrect
      value multiplicity (INVALID_VM), or a DICOM Part 10 file contains
      invalid data (PARSE_ERR).
    </DESCRIPTION>
    <VALUE>MISSING_ATTR MISSING_MAGIC INVALID_VR INVALID_VM PARSE_ERR</VALUE>
  </PREFERENCE_DEF>

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

The <VALUE> element represents the value of the IGNORED_EXP_LIST preference parameter, which lists one or more exceptions to be ignored.

11.2.5.5 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 11-40 shows how to define this preference parameter in a preference document.

  <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.

11.2.5.6 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 11-41 shows how to define this preference parameter in a preference document.

  <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 11.2.2.4 for more information about recursive constraint macros.

11.2.5.7 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 11-42 shows how to define this preference parameter in a preference document.

  <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:

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.

11.2.5.8 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 11-43 shows how to define this preference parameter in a preference document.

  <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.

11.2.5.9 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 11-44 shows how to define this preference parameter in a preference document.

  <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 11.1.4 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. However, if the metadata namespace in the mapping document is not available to the current user, invoking the extractMetadata( ) method with this value set to true raises an error.

11.2.5.10 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 11-45 shows how to define this preference parameter in a preference document.

  <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 2³²-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.

11.2.6.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.

Defining a Private Attribute Using a Simple Attribute Tag

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

<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 11-46, 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 11-47 shows how to define a private attribute with a wildcard attribute tag. The XML statements where this action is defined are highlighted in bold.

<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 11-47, 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 11-48 shows how to define a private attribute with a range attribute tag. The XML statements where this action is defined are highlighted in bold.

<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 11-48, 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.

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).

11.2.6.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.

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

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

<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 11-49, 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.

11.2.6.3 Retiring Private Attributes

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

<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 11-50, 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.

11.2.7.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.

Defining a Standard Attribute Using a Simple Attribute Tag

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

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

In Example 11-51, 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 11-52 shows how to define a standard attribute with a wildcard attribute tag. The XML statements where this action is defined are highlighted in bold.

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

In Example 11-52, the standard attribute definition contains the wildcard tag 60xx0010.

11.2.7.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 11-53 shows the definition of a standard attribute as retired. The XML statement where this action is defined is highlighted in bold.

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

In Example 11-53, 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.

11.2.9.1 Defining UID Definitions

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

 <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 11-54, 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.

11.2.9.2 Retiring UID Definitions

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

 <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 11-55, 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.