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

Part Number E10778-01
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

12 Creating 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. See Section 12.2.1.5, Section 12.2.2.5, and Section 12.2.3.6, respectively, for more information about using DICOM value locators in anonymity, constraint, and mapping documents.

The DICOM value locator is also used in the mid-tier Java API. See Oracle Multimedia Mid-Tier Java API Reference for reference information about the Java classes that support DICOM value locators in the middle tier.

This chapter includes these sections:

Note:

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

See Chapter 9 for more information about inserting, updating, and deleting configuration documents. See Chapter 11 for examples of these processes.

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/

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

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

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

12.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 EXP_IF_NULL_ATTR_IN_CONSTRAINT parameter in the preference document is used to specify whether to raise an exception when it encounters a null value for the attributes specified in the constraint rules. If the parameter is set to true, the isConformanceValid( ) method raises an exception; otherwise, the predicate that was encountered is evaluated to false.

12.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 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 VALIDATE_METADATA parameter in the preference document is true.

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

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

12.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 parameter names and lists of values. The user-defined preference document can update the default preference document values that were set in the Oracle-defined preference document.

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

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

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

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

12.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 12-1 describes the valid values for the action attribute.

Table 12-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 12-2 describes the elements that define the global actions in the anonymity document.

Table 12-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: '.', ' ' (space), and '/'

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

12.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 12-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 12-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 by the DICOM standard (in Part 5). 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.

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

Example 12-2 Removing All Undefined Standard Attributes

<UNDEFINED_STANDARD_ATTRIBUTES action="remove" />

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

12.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 12-4 shows a code segment that uses the action value remove to remove all private attributes in the resulting DICOM content.

Example 12-4 Removing All Private Attributes

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

Similarly, Example 12-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 12-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 12-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 12-6 Including Defined Private Attributes and Removing Undefined Private Attributes

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

Example 12-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 12-7 Removing Defined Private Attributes and Including Undefined Private Attributes

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

12.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 12-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 12-8 Simple DICOM Value Locator in an Anonymity Document

<INCIVIDUAL_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 12-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 12-9 DICOM Value Locator with a Wildcard Character in an Anonymity Document

<INCIVIDUAL_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 Chapter 10 for more information about the DICOM value locator type.

12.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 predicates (using the <PREDICATE> element). Predicates define 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 information 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/

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

Example 12-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 12-11 shows a predicate the checks whether the attribute SOP Instance UID (0008,0018) is not empty:

Example 12-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 12-10 and Example 12-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 12-12 shows a predicate with a logical AND operation for these two conditions:

Example 12-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 12-12. Thus, taking the complete constraint rule from the constraint document ordcmcmd.xml, the global rule SOPCommonModule can be defined as shown in Example 12-13:

Example 12-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 12-13 shows how to define predicates that represent Boolean functions or logical relations. Predicates that represent relational relations can be defined similarly. (See Section 12.2.2.4 for examples of predicates that represent relational relations.)

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

Example 12-14 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 12-15 shows an external rule for these constraint rules:

Example 12-15 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 12.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.

12.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 12-16 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 12-16 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 12-17 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 12-17 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 information 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.

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

The code segment in Example 12-18 is an example of recursion with a single constraint macro that invokes itself. The code segment in Example 12-19 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 12-18 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 12-18 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 12-18, 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 12-19 defines two recursive global constraint macros: DocumentContentMacroA and DocumentContentMacroB. The code statements where these macros are defined and invoked are highlighted in bold.

Example 12-19 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 12-19, the recursion occurs when DocumentContentMacroB invokes DocumentContentMacroA, and then DocumentContentMacroA invokes DocumentContentMacroB.

12.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 12-20 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 12-18.) The DICOM value locators are highlighted in bold.

Example 12-20 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 the wildcard character "*" in the DICOM value locator ensures that all the items for this attribute are checked.

Example 12-21 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 12-21 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 Chapter 10 for more information about the DICOM value locator type.

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

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

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

12.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 12-22 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 12-22 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 12-23 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 12-23 Resulting XML Document for Metadata with No Schema Constraints

<?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 12-22 and Example 12-23, 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 Chapter 5 for reference information about the extractMetadata( ) method and the supported values for the extractOption parameter.

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

Example 12-24 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 12-24 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 12-24 differs from the mapping document in Example 12-22 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 12-24 is defined in Example 12-25:

Example 12-25 Sample XML Schema for Example 12-24

<?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 12-24 and the associated XML schema (in Example 12-25), 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 12-26 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 12-26 Resulting XML Document for Metadata with Schema Constraints and a Mapped Section Only

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

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

Example 12-27 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 12-27 differs from the mapping document in Example 12-24 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 12-28 shows how to define the unmapped root element for the mapping document in Example 12-27 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 12-28 Sample XML Schema for Example 12-27

<?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 12-27 and the associated XML schema (in Example 12-28), the following actions occur:

  • Instead of defining its own data types as in Section 12.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 12-29 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 12-29 Resulting XML Document for Metadata with Schema Constraints (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 12-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 'ALL'.

Example 12-30 Resulting XML Document for Metadata with Schema Constraints (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>

12.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 12-31 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 12-31 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 12-31 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 12-32 shows how to use a DICOM value locator to specify an attribute embedded within a sequence attribute in a mapping document.

Example 12-32 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 12-32 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 12-33 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 12-33 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 12-33 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 Chapter 10 for more information about the DICOM value locator type.

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

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

Definition Using a Simple Attribute Tag

Example 12-34 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 12-34 Standard Attribute Definition 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 12-34, 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.)

Definition Using a Wildcard Attribute Tag

Example 12-35 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 12-35 Standard Attribute Definition 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 12-35, the standard attribute definition contains the wildcard tag 60xx0010.

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

Example 12-36 Retiring a Standard Attribute

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

In Example 12-36, 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.

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

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

Definition Using a Simple Attribute Tag

Example 12-37 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 12-37 Private Attribute Definition 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 12-37, 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.)

Definition Using a Wildcard Attribute Tag

Example 12-38 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 12-38 Private Attribute Definition 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 12-38, the private attribute definition contains the wildcard tag 0119XX00 and the definer name PRIVATE_ORG.

Definition Using a Range Attribute Tag

Example 12-39 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 12-39 Private Attribute Definition 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 12-39, 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).

12.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 12-40 shows how to define the definer name and UID for an organization that defines private attributes:

Example 12-40 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 12-40, 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.

12.2.5.3 Retiring Private Attributes

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

Example 12-41 Retiring a Private Attribute

<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 12-41, 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.

12.2.6 Creating Preference Documents

Preference documents are XML documents that list the set of preferences 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.

Each parameter value in a preference document is defined by a < PREFERENCE_DEF> element.

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 parameter values in preference documents change the behavior of DICOM methods, functions, and procedures. Specifically, 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 the Preference Document Schema for a detailed description of the preference parameters and their valid values.

The following subsections contain examples that show how to create preference documents.

12.2.6.1 Defining the VALIDATE_METADATA Preference

Example 12-42 shows how to define the VALIDATE_METADATA parameter in a preference document. The XML statements where this action is defined are highlighted in bold.

Example 12-42 Definition of the VALIDATE_METADATA Parameter in a Preference Document

<PREFERENCE_DEF>
    <PARAMETER>VALIDATE_METADATA</PARAMETER>
    <DESCRIPTION>Validate XML Metadata document</DESCRIPTION>
    <VALUE>true</VALUE>
 </PREFERENCE_DEF>

In Example 12-42, the <PARAMETER> element specifies the Oracle-defined parameter VALIDATE_METADATA.

The <VALUE> element represents the value of the parameter VALIDATE_METADATA, which is false by default. The value of this parameter controls whether Oracle Multimedia DICOM attempts to validate XML documents that are input to, or output from, methods and functions that operate on metadata documents. If the value is true, and an XML document declares a namespace that is registered as an XML schema with Oracle XML DB, methods and functions attempt to validate the XML document against the specified XML schema. Oracle Multimedia validates XML documents that are input to methods and functions before they are used. XML documents that are output from a method or function are validated after they are produced. If the value of this parameter is false, the rule is not enforced.

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

12.2.6.2 Defining the MANDATE_ATTR_TAGS_IN_STL Preference

Example 12-43 shows how to define the MANDATE_ATTR_TAGS_IN_STL parameter in a preference document. The XML statements where this action is defined are highlighted in bold.

Example 12-43 Definition of the MANDATE_ATTR_TAGS_IN_STL Parameter in a Preference Document

<PREFERENCE_DEF>
    <PARAMETER>MANDATE_ATTR_TAGS_IN_STL</PARAMETER>
    <DESCRIPTION>
      Enforce the rule to list all tags used by constraint and 
      mapping documents in the stored tag list document.
    </DESCRIPTION>
    <VALUE>true</VALUE>
  </PREFERENCE_DEF>

In Example 12-43, the <PARAMETER> element specifies the Oracle-defined parameter MANDATE_ATTR_TAGS_IN_STL.

The <VALUE> element represents the value of the MANDATE_ATTR_TAGS_IN_STL parameter. This rule is not enforced by default. If the value of this parameter is false, the rule is not enforced. If the value is set to true, the rule is enforced. However, if an existing stored tag list document does not satisfy the rule specified in the <DESCRIPTION> element, the value of the parameter cannot be set to true until the stored tag list document is updated. Thus, if the value of this parameter is true, only the constraint and mapping documents that use tags listed in the stored tag list document can be inserted into the repository.

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

Each UID definition in a UID definition document is defined by a <UID_DEF> element.

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.

12.2.7.1 Defining UID Definitions

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

Example 12-44 Definition of a Storage Class UID

<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 12-44, 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.

12.2.7.2 Retiring UID Definitions

Example 12-45 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 12-45 Retiring a UID Definition

<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 12-45, 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.

12.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.11 for information about using a stored tag list to extract specific attributes from DICOM content.