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

10 ORD_DICOM_ADMIN Package Reference

Oracle Multimedia DICOM describes the ORD_DICOM_ADMIN data model repository interface in the ORD_DICOM_ADMIN package. This package provides the data model repository interface, which is intended for use by DICOM administrators to maintain the Oracle Multimedia DICOM repository. The data model repository is a collection of documents. One set of documents is loaded during installation. After installation, DICOM administrators can add more documents to the data model repository using the procedures and functions in the ORD_DICOM_ADMIN package. Oracle Multimedia DICOM also defines information views for the DICOM repository to be used by DICOM administrators.

Note:

Administrators of the DICOM data model repository must be assigned the ORDADMIN role. See Section 9.1 for more information about administrator privileges.

The ORD_DICOM_ADMIN package is defined in the ordcrpsp.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)

Oracle Multimedia contains the following information about the ORD_DICOM_ADMIN data model repository API:

In addition,Oracle Multimedia provides DICOM value locators, which administrators can use to specify DICOM attributes or their child components within the DICOM content and with anonymity, constraint, and mapping documents. This chapter describes the General Format for DICOM Value Locators.

This chapter describes the functions, procedures, and information views in the ORD_DICOM_ADMIN data model repository interface. For information about other DICOM APIs, see these chapters:

See Oracle Multimedia DICOM Java API Reference for information about the DICOM Java API.


ORD_DICOM_ADMIN Data Model Repository Functions and Procedures

The ORD_DICOM_ADMIN package defines these ORD_DICOM_ADMIN data model repository functions and procedures:


generateTagListDocument( ) Function

Format

generateTagListDocument(docSet in varchar2 default 'USER') return XMLType

Description

Returns a stored tag list document as a data type XMLType that contains the attribute tags from the mapping and constraint documents stored in the data model repository, and which conforms to the XML schema ordcmstl.xsd. (See Section B.11 for a listing of this schema.)

Parameters

docSet

A string that lists a specified set of documents in the repository. Valid values are: 'USER', 'ALL', and 'ORACLE'. The default is 'USER'.

When the value of this parameter is 'USER', the attribute tags from the user-defined mapping and constraint documents are listed in the generated stored tag list document. If there are no user-defined constraint or mapping documents in the repository, a null value is returned. When the value is set to 'ALL', the attribute tags from all the mapping and constraint documents are listed. And, when the value is set to 'ORACLE', only the attribute tags from the Oracle-defined mapping and constraint documents are listed.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this function to generate a stored tag list document that is consistent with the repository documents.

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

Examples

Generate a stored tag list document for the user-defined mapping and constraint documents in the repository:

CONNECT pm

Enter password: password
-- user pm must be assigned the ORDADMIN role for the following example to work

exec ord_dicom.setDataModel;
 set long 50000;
 -- to see the contents on screen
 select ord_dicom_admin.generateTagListDocument from dual;

getDocumentContent( ) Function

Format

getDocumentContent(docName IN VARCHAR2) RETURN XMLTYPE

Description

Returns the document as data type XMLType. This function can be used to make copies of documents in the data model repository without changing the content of the original documents.

Parameters

docName

The name of the document whose content is to be retrieved. The document content is returned as data type XMLType. The orddcm_documents view includes the column DOC_NAME, where docName is one of the documents listed.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Note:

Call the setDataModel( ) procedure when you are not making changes to the data model, such as when calling the getDocumentContent( ) procedure or the exportDocument( ) procedure only.

Call the editDataModel( ) procedure when you are making changes to the data model, such as when inserting or deleting documents.

Examples

Get the content of a specified document (ordcmpf.xml) in the repository:

CONNECT pm

Enter password: password
-- user pm must be assigned the ORDADMIN role for the following example to work

exec ord_dicom.setDataModel;
 set long 5000;
 -- to see the contents on screen
 select ord_dicom_admin.getDocumentContent('ordcmpf.xml') from dual;
 -- to store in a table
 create table repos_exp_docs( name varchar2(100),  doc xmltype);
 insert into repos_exp_docs (name, doc) select 'ordcmpf.xml', 
 ord_dicom_admin.getDocumentContent('ordcmpf.xml') from dual;

where:


deleteDocument( ) Procedure

Format

deleteDocument(docName IN VARCHAR2)

Description

Deletes the specified document from the data model repository. Documents installed by Oracle are treated as default documents that cannot be removed.

See Section 9.8 for more information about deleting configuration documents.

Parameters

docName

The name of the document to be removed from the repository, where docName is one of the documents listed in the orddcm_documents view.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this procedure, call the editDataModel( ) procedure.

In addition, Oracle recommends calling the exportDocument( ) procedure to make a copy of the specified document before deleting it from the repository.

Examples

Copy and then delete a document (sample_pref.xml) from the repository:

CONNECT pm

Enter password: password
-- user pm must be assigned the ORDADMIN role for the following example to work

exec ord_dicom_admin.editDataModel();
 -- list most recent docs first
 select doc_name from orddcm_documents order by create_date desc;
 -- export doc
 exec ord_dicom_admin.exportDocument('sample_pref.xml', 'EXPORT_DIR', 
  'sample_pref_exp.xml');
 -- delete doc
 exec ord_dicom_admin.deleteDocument('sample_pref.xml');
 -- list remaining docs
 select doc_name from orddcm_documents order by create_date desc;
 -- publish changes and release locks
 exec ord_dicom_admin.publishDataModel();

where:


editDataModel( ) Procedure

Format

editDataModel( )

Description

Begins an administrator editing session for making changes to the data model repository. The administrator session maintains a lock on the repository until the publishDataModel( ) or rollbackDataModel( ) procedure is called, or until the session exits. Call this procedure before making changes to the repository. Upon successful completion, this procedure implicitly commits the current transaction.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Begin an editing session in the repository, while locking it from other administrators:

exec ord_dicom_admin.editDataModel();

exportDataModel( ) Procedure

Format

exportDataModel(dirName IN VARCHAR2, exportOption IN VARCHAR2 default 'USER')

Description

Exports a set of documents in the repository into a ZIP archive file in a specified Oracle directory. The name of the ZIP file is system generated and has this format: ordcm_reposdocs_<exportOption>_<timestamp>.zip.

Parameters

dirName

The directory location of the ZIP archive file containing the exported repository documents. This string is an Oracle directory object name, which is case-sensitive. The default is uppercase. The write privilege must be granted to the administrator for this directory object.

exportOption

A string that specifies the set of documents to export from the repository. Valid values are: 'USER', 'ALL', and 'ORACLE'. The default is 'USER'.

When the value of this parameter is 'USER', only the user-defined documents are exported. When the value is set to 'ALL', all the documents in the repository are exported. And, when the value is set to 'ORACLE', only the Oracle-defined documents are exported.

Pragmas

None.

Exceptions

None.

Usage Notes

Note:

This procedure does not export the corresponding metadata schemas, which are associated with any user-defined mapping documents in the DICOM data model repository. Without these metadata schemas, the data model repository is incomplete. (See Section 9.2.2 for information about how to find these XML schemas.)

Use this procedure in these situations:

Note:

The administrator of the DICOM data model repository must be granted read and write privileges on the directory object specified by the dirName parameter. The following code segment shows a sample GRANT statement for the administrator dcmadmin:
GRANT read, write on directory DICOMDIR to dcmadmin;

For security purposes in Java, the administrator of the repository and the user ORDSYS must be granted read, write, and delete privileges for the directory that contains the ZIP file. The following code segment shows a sample GRANT statement that meets both of these requirements:

dbms_java.grant_permission( 'DCMADMIN', 
                                  'SYS:java.io.FilePermission',
                                  'c:\mydir\work\*' , 'read,write,delete');
      dbms_java.grant_permission( 'ORDSYS', 'SYS:java.io.FilePermission',
                                  'c:\mydir\work\*' , 'read,write,delete');

See Section 5.1.1 for information about the definition of the DICOMDIR directory. See Chapter 10, the section entitled "Fine-Grain Definition for Each Permission" in Oracle Database Java Developer's Guide for more information about granting privileges in Java.

See the Oracle Multimedia Web page on OTN for more information about how to use this procedure.

Examples

Export all the documents in the data model repository into a system generated ZIP file:

exec ord_dicom.setDataModel();
 exec ord_dicom_admin.exportDataModel('EXPORT_DIR','ALL'); 

where:


exportDocument( ) Procedure

Format

exportDocument(docName IN VARCHAR2, dirName IN VARCHAR2, fileName IN VARCHAR2)

Description

Exports the contents of the document specified by the docName parameter to the specified file. This procedure writes the data to a file in a directory for which the administrator has been granted the write privilege.

Parameters

docName

The name of the specified document in the repository, where docName is one of the documents listed in the orddcm_documents view.

dirName

The directory location of the specified file. This string is an Oracle directory object name, and it is case-sensitive. The default is uppercase. The write privilege must be granted to the administrator for this directory object.

fileName

The name of the file, including the file extension (file type), but excluding the directory path.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this procedure, call either the setDataModel( ) or the editDataModel( ) procedure.

Note:

Call the setDataModel( ) procedure when you are not making changes to the data model, such as when calling the getDocumentContent( ) procedure or the exportDocument( ) procedure only.

Call the editDataModel( ) procedure when you are making changes to the data model, such as when inserting or deleting documents.

Examples

Export the contents of an existing file in the repository (sample_map.xml) into an external file (sample_map_export.xml):

exec ord_dicom.setDataModel();
 exec ord_dicom_admin.exportDocument('ordcmpf.xml', 'EXPORT_DIR', 
      'ordcmpf_exp.xml');

where:


importDataModel( ) Procedure

Format

importDataModel(dirName in VARCHAR2, zipFileName in varchar2)

Description

Imports the documents from a ZIP archive file in a specified Oracle directory into the repository. Use this procedure to install OTN releases and updates. This procedure can also be used to import a set of documents that was exported using the exportDataModel( ) procedure.

The set of documents to import can include only Oracle-defined documents, only user-defined documents, or a combination of both.

Parameters

dirName

The directory location of the ZIP archive file containing the set of documents to be imported into the repository. This string is an Oracle directory object name, which is case-sensitive. The default is uppercase. The write privilege must be granted to the administrator for this directory object.

zipFileName

The name of the ZIP archive file containing the set of documents to be imported. This archive file can be downloaded from OTN or generated by the exportDataModel( ) procedure.

Pragmas

None.

Exceptions

None.

Usage Notes

Caution:

Use this procedure with caution; it might affect your installation and change the behavior of your system.

Before calling this procedure, Oracle strongly recommends calling the exportDataModel( ) procedure to export the existing data model repository.

Use this procedure to download new versions of the DICOM data model from the Oracle Multimedia Software section of the Oracle Technology Network (OTN) Web site at

http://www.oracle.com/technology/products/multimedia/

If your ZIP file contains any Oracle-defined documents, these documents will replace the Oracle-defined documents in the repository.

Note:

The administrator of the DICOM data model repository must be granted read and write privileges on the directory object specified by the dirName parameter. The following code segment shows a sample GRANT statement for the administrator dcmadmin:
GRANT read, write on directory DICOMDIR to dcmadmin;

For security purposes in Java, the administrator of the repository and the user ORDSYS must be granted read, write, and delete privileges for the directory that contains the ZIP file. The following code segment shows a sample GRANT statement that meets both of these requirements:

dbms_java.grant_permission( 'DCMADMIN', 
                                  'SYS:java.io.FilePermission',
                                  'c:\mydir\work\*' , 'read,write,delete');
      dbms_java.grant_permission( 'ORDSYS', 'SYS:java.io.FilePermission',
                                  'c:\mydir\work\*' , 'read,write,delete');

See Section 5.1.1 for information about the definition of the DICOMDIR directory. See Chapter 10, the section entitled "Fine-Grain Definition for Each Permission" in Oracle Database Java Developer's Guide for more information about granting privileges in Java.

See the Oracle Multimedia Web page on OTN for more information about how to use this procedure.

Examples

None.


insertDocument( ) Procedure

Format

insertDocument(docName IN VARCHAR2, docType IN VARCHAR2, xmlDoc IN XMLType)

Description

Loads the specified XML configuration document into the data model repository. The document name must be unique. Supported document types are listed in the public information view orddcm_document_types. The document is validated against the registered schema that is associated with the document type.

Documents must be loaded into the repository in the following order:

  1. Standard data dictionary documents

  2. Private data dictionary documents

  3. Other configuration documents, including the following:

    • Constraint documents

    • XML mapping documents

    • Anonymity documents

    • Preference documents

    • UID definition documents

    Other configuration documents can be loaded in any order, unless there are dependencies between constraint documents.

There are semantic dependencies between the documents. For example, elements referenced in an XML mapping document must exist in the standard or private data dictionary documents. The information view orddcm_documents contains the details of the documents in the repository.

Parameters

docName

The unique name of the specified document. The name cannot exceed 100 characters in length, and it must not contain the reserved prefix ORD.

docType

The type of the document to be loaded into the repository. Supported values are listed in the public information view orddcm_document_types. The value of this parameter must not be NULL.

xmlDoc

The XML document to be loaded into the repository. The value of this parameter must not be NULL.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this procedure, call the editDataModel( ) procedure.

Before inserting a user-defined mapping document into the repository, its associated metadata schema must have been registered as a global schema with Oracle XML DB. See Oracle XML DB Developer's Guide for information about registering XML schemas. (The metadata schema associated with the default mapping document is registered with Oracle XML DB upon installation of Oracle Multimedia DICOM. See Appendix B for more information.)

Examples

Insert a mapping document (sample_map.xml) into the repository:

exec ord_dicom_admin.editDataModel();
   exec ord_dicom_admin.insertDocument('sample_map.xml', 'MAPPING', 
     xmltype(bfilename('DICOMDIR', 'sample_map.xml'), 
     nls_charset_id('AL32UTF8')));
   select * from orddcm_documents;
   exec ord_dicom_admin.publishDataModel();

where:


publishDataModel( ) Procedure

Format

publishDataModel( )

Description

Publishes changes to the data model repository. This procedure also unlocks the repository, making it available for updating by other administrators. By calling the setDataModel( ) procedure to refresh the data model repository, users can access the latest published changes to the repository. Upon successful completion, this procedure implicitly commits the current transaction.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this procedure, call the editDataModel( ) procedure.

Depending on when the administrator publishes changes to the data model repository, users who are connected to the repository may have to call the setDataModel( ) procedure more than once to see the latest changes. Also, based on when they call the setDataModel( ) procedure, it is possible for two users who are connected to the same data model repository to access different versions of the repository. See Figure 2-5 for more information about this possible scenario.

Examples

Publish the changes to the repository:

exec ord_dicom_admin.editDataModel();
   exec ord_dicom_admin.deleteDocument('sample_pref.xml');
   select doc_name from orddcm_documents;
   exec ord_dicom_admin.publishDataModel();

rollbackDataModel( ) Procedure

Format

rollbackDataModel( )

Description

Terminates changes to the data model since the previous call to the editDataModel( ) procedure. Call this procedure to roll back the changes and unlock the data model, making it available for updating by other administrators. Upon successful completion, this procedure implicitly commits the current transaction.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

Before calling this procedure, call the editDataModel( ) procedure.

At end of the database session, to roll back the data model call this procedure. Because the changes to the data model were terminated rather than published, the information views are populated with the data from the previously published data model.

Examples

Terminate the data model changes without publishing them to the repository:

exec ord_dicom_admin.editDataModel();
   exec ord_dicom_admin.deleteDocument('sample_pref.xml');
   select doc_name from orddcm_documents;
   exec ord_dicom_admin.rollbackDataModel();
   select doc_name from orddcm_documents;

DICOM Repository Administrator Information Views

This section describes the Oracle Multimedia DICOM repository information view for administrators. The information view is called orddcm_document_refs.

See Chapter 4 for information about the Oracle Multimedia DICOM repository public information views.


orddcm_document_refs

Format

Column Name Data Type Description
doc_name VARCHAR2(100) Document name
ref_by_doc_name VARCHAR2(100) Referenced by document name

Description

This read-only information view lists the documents that are referenced by other documents. The select privilege is granted to the ORDADMIN role for this information view. This information view is available to administrators only.

Usage Notes

Before querying this information view, call either the setDataModel( ) or the editDataModel( ) procedure. If you call the setDataModel( ) procedure, call it again whenever the application requires the new data model changes.

Note:

Call the setDataModel( ) procedure when you are not making changes to the data model, such as when calling the getDocumentContent( ) procedure or the exportDocument( ) procedure only.

Call the editDataModel( ) procedure when you are making changes to the data model, such as when inserting or deleting documents.

Examples

Show the references between a set of Oracle-installed configuration documents:

SQL> select doc_name, ref_by_doc_name from ordsys.orddcm_doc_refs;
 
-------------------------------------------------------------------------------
DOC_NAME             REF_BY_DOC_NAME
-------------------------------------------------------------------------------
ordcmpv.xml          ordcmcmc.xml
ordcmpv.xml          ordcmcmd.xml
ordcmsd.xml          ordcman.xml
ordcmsd.xml          ordcmcmc.xml
ordcmsd.xml          ordcmcmd.xml

General Format for DICOM Value Locators

Syntax

value_locator::=

Description of dicom009.gif follows
Description of the illustration dicom009.gif

sublocator::=

Description of dicom010.gif follows
Description of the illustration dicom010.gif

Description

Identifies an attribute in the DICOM content, either at the root level or from the root level down. Each level in the tree hierarchy is represented by a sublocator. DICOM value locators can include one or more sublocators, depending on the level of the attribute in the DICOM content.

DICOM value locators can be used within anonymity documents to specify the attributes to be made anonymous in the resulting DICOM content.

When DICOM value locators are used within constraint documents, they can contain macros for substitution when the constraint document is loaded into the repository. Define macro substitution strings either as valid DICOM value locators, or as one of the DICOM value locator parameters with no token separators.

DICOM value locators can be used within mapping documents to specify the attributes to be retrieved or extracted from the metadata in the resulting DICOM XML document.

Parameters

tag

A DICOM standard compliant tag in the format of an 8-digit hexadecimal number.

Example 1: A hexadecimal tag for a root-level attribute

0040A730

Example 2: A hexadecimal tag for a root-level attribute

0040A123
. (the dot character)

A sublocator separator or a special wildcard tag that matches to zero or a series of sublocators. (See DICOM Value Locator Example 4.)

definer

A string that identifies the organization creating the tag. For tags that are defined by the DICOM standard, the default (which can be omitted) is DICOM. For private tags, the value must include a definer string (which can be empty) to uniquely identify each private attribute. This parameter is optional.

Definer strings cannot contain the following unescaped token separator characters: '(', ')', '[', ']', '{', '}', '$', '#', and'*'. Although it is possible to refer to definer strings that contain these characters, you must use an escape mechanism to express definer strings with these characters. Specifically, a single "#" (the escape character) must precede each token separator character in the definer string for a specified attribute.

Example 1: A definer string for a private organization

ORACLE

Example 2: A definer string with token separators that have been escaped. The original string was $abc(#def)[ghi].

#$abc#(##def#)#[ghi#]
item_num

An integer that identifies a data element within an attribute, or a wildcard character ("*") that identifies all data elements within an attribute. The default is 1, the first data element of an attribute. This parameter is optional.

  • For the binary data types OF, OW, OB, and UN (defined in the data type definition schema ordcmrdt.xsd):

    This parameter identifies one data value within a DICOM attribute that contains a list of data values, as shown in the following table.

    Binary Data Type Data Value Identification
    OF A floating-point number
    OW A word
    OB A byte
    UN A byte

  • For the data type SQ:

    This parameter identifies one sequence item.

  • For the data types ST, LT, and UT:

    The value of this parameter is always 1 because attributes of these types always contain single values.

Note:

The concept of an item number is not well-defined by the DICOM standard. Do not confuse it with DICOM value multiplicity.

DICOM value locators with a special wildcard tag "." cannot be immediately followed by an item_num parameter.

Data elements are defined by the DICOM standard, in Part 5 (PS 3.5).

Example 1: An integer that represents a specific sequence item in an attribute

The second sequence item in attribute 0040A730:

0040A730 [2]

Example 2: An integer with a wildcard character that represents all the data elements in an attribute

All items in the sequence attribute 0040A730:

0040A730[*]
tag_field

A string that identifies a derived value within an attribute. A tag that contains this string must be the last tag of a DICOM value locator. The default is NONE. This parameter is optional.

The following table shows the supported values for the tag_field parameter:

Value Meaning
NONE N/A
UnibyteFamily Family name, in unibyte charactersFoot 1 
UnibyteGiven Given name, in unibyte charactersFootref 1
UnibyteMiddle Middle name, in unibyte charactersFootref 1
UnibytePrefix Prefix, in unibyte charactersFootref 1
UnibyteSuffix Suffix, in unibyte charactersFootref 1
IdeographicFamily Family name, in ideographic charactersFootref 1
IdeographicGiven Given name, in ideographic charactersFootref 1
IdeographicMiddle Middle name, in ideographic charactersFootref 1
IdeographicPrefix Prefix, in ideographic charactersFootref 1
IdeographicSuffix Suffix, in ideographic charactersFootref 1
PhoneticFamily Family name, in phonetic charactersFootref 1
PhoneticGiven Given name, in phonetic charactersFootref 1
PhoneticMiddle Middle name, in phonetic charactersFootref 1
PhoneticPrefix Prefix, in phonetic charactersFootref 1
PhoneticSuffix Suffix, in phonetic charactersFootref 1
PersonName Person name, as a concatenated string of characters in the convention of three groups of five components
AgeString Age, as a string
AgeInDays Age, in number of days
ByteLength Binary length of the path
ByteOffset Byte offset of the path
NumEntry Total number of data elements within an attribute
VRFoot 2  In-stream value representation (VR) of an attribute

Footnote 1 This value is a component of the attribute Person Name.

Footnote 2 See the description of the item_num parameter for more information about data types.

For complete definitions of the values in the preceding table, see Part 5 of the DICOM standard (PS 3.5) on the Web site for the National Electrical Manufacturers Association (NEMA) at

http://medical.nema.org/

Note:

DICOM value locators with a tag_field parameter are not supported in anonymity and constraint documents.

DICOM value locators with a special wildcard tag "." cannot be immediately followed by a tag_field parameter.

Examples

DICOM Value Locator Example 1

A DICOM value locator with the required tag parameters only:

00080096.00401101.00080100

where:

DICOM Value Locator Example 2

A DICOM value locator with the required tag parameter and the optional item_num parameter:

00080096[1].00401101[1].00080100[1]

where:

DICOM Value Locator Example 3

A DICOM value locator with the required tag parameter and the optional definer and item_num parameters:

00080096(DICOM)[1].00401101(DICOM)[1].00080100(DICOM)[1]

where:

DICOM Value Locator Example 4

A DICOM value locator with a special wildcard tag (".") for all code values in the DICOM content:

..00080100

DICOM Value Locator Example 5

A DICOM value locator with a special wildcard tag (".") for all code values in all the 0040A730 sequence items in the DICOM content:

0040A730[*]...00080100

DICOM Value Locator Example 6

A DICOM value locator with a private definer and escape characters:

00431028(#$abc#(##def#)#[ghi#])

where: