DICOM Data Model Utility Reference

5 DICOM Data Model Utility Reference

Oracle Multimedia provides the DICOM data model utility in the ORD_DICOM package. Oracle Multimedia DICOM also defines public views for the DICOM repository.

The functions, procedures, and views in the DICOM data model utility interface can be used by DICOM developers and administrators of the DICOM data model repository.

For administrative operations related to the Oracle Multimedia DICOM data model repository, the setDataModel( ) procedure must be called at the beginning of each database session (see the setDataModel( ) Procedure). Developers and administrators must call the setDataModel( ) procedure before calling any other DICOM methods, functions, or procedures.

The ORD_DICOM package is defined in the ordcpksp.sql file. After installation, this file is available in the Oracle home directory at:

<ORACLE_HOME>/ord/im/admin (on Linux and UNIX)

<ORACLE_HOME>\ord\im\admin (on Windows)

This chapter describes the functions, procedures, and views in the DICOM data model utility interface, which operate on the DICOM data model repository.

This chapter contains these sections:

5.1 Directory Definition and Setup for ORD_DICOM Examples

See the examples for each function or procedure in this chapter for specific directory definitions for DICOM data files and other details specific to that function or procedure.

5.2 DICOM Data Model Utility Functions

The ORD_DICOM package defines these DICOM data model utility functions:

5.2.1 getDictionaryTag( ) Function

Format

getDictionaryTag(attributeName IN VARCHAR2,
                 definerName   IN VARCHAR2  DEFAULT 'DICOM')
 RETURN VARCHAR2

Description

Looks in the standard or private data dictionaries for the specified attribute name and definer name and returns the value of the attribute name as a hexadecimal DICOM attribute tag. This function can be used to get the hexadecimal tag value that is needed in the getMappingXpath( ) function.

Parameters

attributeName: The name of specified attribute in the standard or private data dictionary (for example: Patient's Name). The maximum length of this parameter is 128 characters.
definerName: The definer name of the specified attribute in the standard or private data dictionary. The default name, DICOM, refers to the DICOM standard. The maximum length of this parameter is 64 characters.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this function, call the setDataModel( ) procedure.

Call the setDataModel( ) procedure at these times:

At the beginning of each database session
Whenever the application requires the new data model changes

See the setDataModel( ) Procedure for more information.

Examples

Get the specified DICOM attribute name and return its value as a hexadecimal tag:

exec ord_dicom.setDataModel();
select ord_dicom.getDictionaryTag('Patient''s Name', 'DICOM') as Patient_Name 
from dual;

PATIENT_NAME
--------------------------------------------------------------------------------
00100010


select ord_dicom.getDictionaryTag('Audio Type', 'DICOM') as Audio_Type from dual;

AUDIO_TYPE
--------------------------------------------------------------------------------
50XX2000

5.2.2 getMappingXPath( ) Function

Format

getMappingXPath(tag IN VARCHAR2,
                docName IN VARCHAR2  DEFAULT 'ordcmmp.xml',
                definerName IN VARCHAR2 DEFAULT 'DICOM')
 RETURN VARCHAR2

Description

Returns the absolute XPath expression associated with the specified DICOM attribute tag and definer name from the specified mapping document. The XPath expression that is returned can be used to obtain values from an extracted XML metadata document.

Parameters

tag: A DICOM attribute tag from the specified mapping document, represented as an 8-character hexadecimal string (for example: 00100010).
docName: The name of a mapping document. The default name is ordcmmp.xml.
definerName: The definer name of the DICOM attribute tag in the specified mapping document. The default name is DICOM, which refers to the DICOM standard.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this function, call the setDataModel( ) procedure.

Call the setDataModel( ) procedure at these times:

At the beginning of each database session
Whenever the application requires the new data model changes

See the setDataModel( ) Procedure for more information.

To see a list of all the mapping documents in the data model repository, query the public view orddcm_documents.

Examples

Example 1:

Return the XPATH expression for DICOM attributes other than SEQUENCE type attributes:

    col map_xpath new_value xpath
    exec ord_dicom.setDataModel();
    select ord_dicom.getMappingXPath('00100010') map_xpath from dual;
 
    MAP_XPATH
    ----------------------------------------------------------------------------
    /DICOM_OBJECT/PERSON_NAME[@tag="00100010" and @definer="DICOM"]/VALUE/text()
 
    1 row selected.
 
    ------------- extract attribute from a document
    select '&xpath' as map_xpath from dual;
    select xmlquery(
        'declare default element namespace
        "http://xmlns.oracle.com/ord/dicom/metadata_1_0"; &xpath'
        passing t.metadata returning content) as
        Patient_Name from metadata_tab t where id=1;
 
    PATIENT_NAME
    --------------------------------------------------------------------------------
    Anonymous
 
    1 row selected.

Example 2:

Return the XPATH expression for DICOM SEQUENCE type attributes only:

    col map_xpath new_value xpath
    exec ord_dicom.setDataModel();
    select ord_dicom.getMappingXPath('00082218') map_xpath from dual;
 
    MAP_XPATH
    ------------------------------------------------------------
    /DICOM_OBJECT/SEQUENCE[@tag="00082218" and @definer="DICOM"]
 
    1 row selected.
 
    ------------- extract attribute from a document
    set long 1000
    select '&xpath' as map_xpath from dual;
    select xmlquery(
        'declare default element namespace
         "http://xmlns.oracle.com/ord/dicom/metadata_1_0"; &xpath'
        passing t.metadata returning content) as
    Anatomic_Region from metadata_tab t where id=2;
 
    ANATOMIC_REGION
    --------------------------------------------------------------------------------
    <SEQUENCE xmlns="http://xmlns.oracle.com/ord/dicom/metadata_1_0"
    tag="00082218"
    definer="DICOM" name="Anatomic Region Sequence" offset="590"
    length="52"><ITEM number="1"><SHORT_STRING tag="00080100"
    definer="DICOM" name="Code Value" offset=
    "606" length="8">T-11170</SHORT_STRING><SHORT_STRING tag="00080102"
    definer="DICOM" name="Coding Scheme Designator" offset="622"
    length="4">SNM3</SHORT_STRING><LONG_STRING tag="00080104" definer="DICOM"
    name="Code Meaning" offset="634" 
    length="8">Maxilla</LONG_STRING></ITEM></SEQUENCE>
 
 
    1 row selected.

where:

metadata_tab: a table containing metadata that has been extracted from the DICOM content.

5.3 DICOM Data Model Utility Procedures

The ORD_DICOM package defines this DICOM data model utility procedure:

setDataModel( ) Procedure

5.3.1 setDataModel( ) Procedure

Format

setDataModel(modelName IN VARCHAR2 DEFAULT 'DEFAULT')

Description

Loads the data model repository from the database into the memory structures. This procedure must be called at the beginning of each database session. It can be called again whenever the application requires the new data model changes.

Parameters

modelName: The model name of the data model repository. The default name, DEFAULT, is the only value currently supported.

Pragmas

None.

Exceptions

None.

Usage Notes

To maximize performance, you may want to call this procedure only once during a database session.

If the data model has changed since you made the original call, and your application requires these data model changes, you can call this procedure again. Keep in mind, however, that subsequent calls to this procedure may result in changed behavior.

To use the same DICOM data model throughout a session, Oracle recommends following the call to this procedure with a COMMIT statement. Because data that is loaded by the setDataModel( ) procedure is subject to transaction semantics, the database session's copy of the data model is deleted during a rollback operation if the call to the setDataModel( ) procedure is made within the transaction that you are rolling back.

If you roll back the transaction in which you call the setDataModel( ) procedure, you may get an error message indicating that the data model is not loaded when you use the DICOM feature in the same session following the rollback operation. Call the setDataModel( ) procedure to reload the data model.

See the rollbackDataModel( ) Procedure for more information.

Examples

Load the repository from the database into memory:

   exec ord_dicom.setdatamodel;
   select * from orddcm_documents;

5.4 DICOM Repository Public Views

This section describes these Oracle Multimedia DICOM repository public views:

See DICOM Repository Administrator Views for information about the Oracle Multimedia DICOM repository view for administrators.

5.4.1 orddcm_conformance_vld_msgs

Format

Column Name	Data Type	Description
SOP_INSTANCE_UID	VARCHAR2(128 CHAR)	SOP_INSTANCE_UID of DICOM content
RULE_NAME	VARCHAR2(64 CHAR)	Constraint rule name
MESSAGE	VARCHAR2(1999 CHAR)	Message
MSG_TYPE	VARCHAR2(20 CHAR)	Message type, valid values are: `log`, `warning`, or `error`
MSG_TIME	TIMESTAMP	Message generation time

Description

This view lists the constraint messages generated during constraint validation. The public READ and DELETE access privileges are granted for this view.

Usage Notes

This view shows the constraint validation messages that are generated for a specified user schema only.

Examples

Show the list of constraint validation messages that were generated for the predicate conditions defined in the specified constraint document. The conformance validation rule shown in this example is PatientModule, as defined in the DICOM standard.

----------------------------------------------------------------------------------------------------------
SOP_INSTANCE_UID        RULE_NAME            MESSAGE                MSG_TYPE         MSG_TIME             
----------------------------------------------------------------------------------------------------------
1.2.840.114346.         PatientModule        Validation error:      log              01-MAR-07
3384726461.899958945.                         missing mandatory                       01.40.21.158337 PM
2180235641.3197827030                         attribute for 
                                              patient module


1.2.840.114346.         PatientModule        Warning:               warning          01-MAR-07
3384726461.899958945.                         validation failure                      01.40.21.168322 PM
2180235641.3197827030


2 rows selected.

5.4.2 orddcm_constraint_names

Format

Column Name	Data Type	Description
NAME	VARCHAR2(100)	Constraint name

Description

This read-only view lists the constraint names. The public READ access privilege is granted for this view.

Usage Notes

Before querying this view, call the setDataModel( ) procedure at least once during the database session. Call it again whenever the application requires the new data model changes.

See the setDataModel( ) Procedure for more information.

Examples

Show a list of the constraint names that are available after installation:

------------------------------------------------------------------------------
NAME
------------------------------------------------------------------------------
PatientModule
GeneralStudyModule
GeneralSeriesModule
SOPCommonModule
ImagePixelMacro
OracleOrdDicomImage
OracleOrdObject

7 rows selected.

5.4.3 orddcm_documents

Format

Column Name	Data Type	Description
DOC_NAME	VARCHAR2(100)	Document name
DOC_TYPE	VARCHAR2(100)	Document type
CREATE_DATE	DATE	Document creation date
ISINSTALLED_BY_ORACLE	NUMBER(1)	A value of `1` indicates that the document was installed by Oracle. A value of `0` indicates that the document was loaded by an administrator.

Description

This read-only view lists details of the documents stored in the repository. The public READ access privilege is granted for this view.

Usage Notes

Before querying this view, call the setDataModel( ) procedure at least once during the database session. Call it again whenever the application requires the new data model changes.

See the setDataModel( ) Procedure for more information.

Examples

Show a list of the configuration documents in the repository, by name, type, and date of creation and indicate whether the configuration document is Oracle-defined or user-defined. This example shows details about the default Oracle-defined configuration documents that are available upon installation.

--------------------------------------------------------------------------------
DOC_NAME          DOC_TYPE               CREATE_DA        INSTALLED_BY_ORACLE   
--------------------------------------------------------------------------------
ordcmpv.xml       PRIVATE_DICTIONARY     04-FEB-09        1
ordcmmp.xml       MAPPING                04-FEB-09        1
ordcman.xml       ANONYMITY              04-FEB-09        1
ordcmpf.xml       PREFERENCE             04-FEB-09        1
ordcmui.xml       UID_DEFINITION         04-FEB-09        1
ordcmcmc.xml      CONSTRAINT             04-FEB-09        1
ordcmcmd.xml      CONSTRAINT             04-FEB-09        1
ordcmct.xml       CONSTRAINT             04-FEB-09        1
ordcmsd.xml       STANDARD_DICTIONARY    04-FEB-09        1

9 rows selected.

5.4.4 orddcm_document_types

Format

Column Name Data Type Description

Column Name	Data Type	Description
DOC_TYPE	VARCHAR2(100)	Document type code of the document type This column contains these values: `STANDARD_DICTIONARY` `PRIVATE_DICTIONARY` `CONSTRAINT` `MAPPING` `ANONYMITY` `PREFERENCE` `UID_DEFINITION` `STORED_TAG_LIST` `DICOM_PROTOCOL`
SCHEMA_URL	VARCHAR2(700)	The URL of the XML schema registered with Oracle XML DB that is associated with this document type This column contains these values, which are listed respective to the order of the values in the DOC_TYPE column: `http://xmlns.oracle.com/ord/dicom/standardDictionary_1_0` `http://xmlns.oracle.com/ord/dicom/privateDictionary_1_0` `http://xmlns.oracle.com/ord/dicom/constraint_1_0` `http://xmlns.oracle.com/ord/dicom/mapping_1_0` `http://xmlns.oracle.com/ord/dicom/anonymity_1_0` `http://xmlns.oracle.com/ord/dicom/preference_1_0` `http://xmlns.oracle.com/ord/dicom/UIDdefinition_1_0` `http://xmlns.oracle.com/ord/dicom/attributeTag_1_0` `http://xmlns.oracle.com/ord/dicom/protocol_1_0`
DOC_TYPE_DESC	VARCHAR2(4000)	Document type description This column contains these values, which are listed respective to the order of the values in the DOC_TYPE column: `DICOM standard data dictionary` `Private data dictionary` `Constraint document` `Mapping document` `Anonymity document` `Preference document` `DICOM UID definition document` `Stored tag list document` `DICOM protocol document`

DOC_TYPE

VARCHAR2(100)

Document type code of the document type

This column contains these values:

STANDARD_DICTIONARY
PRIVATE_DICTIONARY
CONSTRAINT
MAPPING
ANONYMITY
PREFERENCE
UID_DEFINITION
STORED_TAG_LIST
DICOM_PROTOCOL

SCHEMA_URL

VARCHAR2(700)

The URL of the XML schema registered with Oracle XML DB that is associated with this document type

This column contains these values, which are listed respective to the order of the values in the DOC_TYPE column:

http://xmlns.oracle.com/ord/dicom/standardDictionary_1_0
http://xmlns.oracle.com/ord/dicom/privateDictionary_1_0
http://xmlns.oracle.com/ord/dicom/constraint_1_0
http://xmlns.oracle.com/ord/dicom/mapping_1_0
http://xmlns.oracle.com/ord/dicom/anonymity_1_0
http://xmlns.oracle.com/ord/dicom/preference_1_0
http://xmlns.oracle.com/ord/dicom/UIDdefinition_1_0
http://xmlns.oracle.com/ord/dicom/attributeTag_1_0
http://xmlns.oracle.com/ord/dicom/protocol_1_0

DOC_TYPE_DESC

VARCHAR2(4000)

Document type description

This column contains these values, which are listed respective to the order of the values in the DOC_TYPE column:

DICOM standard data dictionary
Private data dictionary
Constraint document
Mapping document
Anonymity document
Preference document
DICOM UID definition document
Stored tag list document
DICOM protocol document

Description

This read-only view identifies the supported Oracle Multimedia DICOM document types. Use this view to find the list of codes for document types when inserting a new document into the Oracle Multimedia DICOM repository. The public READ access privilege is granted for this view.

Usage Notes

None.

Examples

Show the document type, schema URL, and document type description for the Oracle-installed configuration documents:

----------------------------------------------------------------------------------------------------------
DOC_TYPE               SCHEMA_URL                                                    DOC_TYPE_DSC
----------------------------------------------------------------------------------------------------------
STANDARD_DICTIONARY    http://xmlns.oracle.com/ord/dicom/standardDictionary_1_0      DICOM Standard
                                                                                       Data Dictionary

PRIVATE_DICTIONARY     http://xmlns.oracle.com/ord/dicom/privateDictionary_1_0       Private Data
                                                                                       Dictionary

MAPPING                http://xmlns.oracle.com/ord/dicom/mapping_1_0                 Mapping document

ANONYMITY              http://xmlns.oracle.com/ord/dicom/anonymity_1_0               Anonymity document

PREFERENCE             http://xmlns.oracle.com/ord/dicom/preference_1_0              Preference document

UID_DEFINITION         http://xmlns.oracle.com/ord/dicom/UIDdefinition_1_0           DICOM UID
                                                                                       definition document

CONSTRAINT             http://xmlns.oracle.com/ord/dicom/constraint_1_0              Constraint document

STORED_TAG_LIST        http://xmlns.oracle.com/ord/dicom/attributeTag_1_0            Stored tag list
                                                                                       document

DICOM_PROTOCOL         http://xmlns.oracle.com/ord/dicom/protocol_1_0                DICOM protocol 
                                                                                       document

8 rows selected.