13 ORD_DICOM_ADMIN Package Reference

Oracle Multimedia DICOM provides 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 a view for the DICOM repository to be used by DICOM administrators.

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.

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)

This chapter describes the functions, procedures, and views in the
ORD_DICOM_ADMIN data model repository interface. It also describes the syntax for DICOM value locators. See Table 3-1 for information about other DICOM application programming interfaces (APIs).

This chapter contains these sections:

Directory Definition and Setup for ORD_DICOM_ADMIN Examples
Important Notes for DICOM Repository Administrators
DICOM Data Model Repository Administrator Functions
DICOM Data Model Repository Administrator Procedures
DICOM Repository Administrator Views
General Format for DICOM Value Locators

13.1 Directory Definition and Setup for ORD_DICOM_ADMIN Examples

In this chapter, some examples use c:\mydir\work to represent the directory specification where your test files can be located. Other examples use DICOMDIR to represent the directory specification for the test files. And, a few examples use dcmadmin to represent the user, who is acting as an administrator. See the example for each function or procedure for specific directory definitions for DICOM data files and other details specific to that function or procedure.

13.2 Important Notes for DICOM Repository Administrators

The following guidelines apply to administrative operations related to the Oracle Multimedia DICOM data model repository:

Administrators must be assigned the ORDADMIN role. See Section 10.1 for more information about administrator privileges.
At the start of each database session, administrators must load the data model repository from the database into memory structures. To load the data model, administrators call either the setDataModel( ) procedure or the editDataModel( ) procedure, depending on the following situations:
- When you are not making changes to the data model, call the setDataModel( ) procedure (see the setDataModel( ) Procedure).
- When you are making changes to the data model, call the editDataModel( ) procedure (see the editDataModel( ) Procedure).

DICOM Data Model Repository Administrator Functions

The ORD_DICOM_ADMIN package defines these ORD_DICOM_ADMIN data model repository functions:

generateTagListDocument( ) Function
getDocumentContent( ) Function

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.

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. (See Section 11.2.8 for more information about creating stored tag list documents.)

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

Examples

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

 exec ord_dicom.setDataModel;
 set long 50000;
 set pagesize 1000;
 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 in these situations:

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.

See the setDataModel( ) Procedure and the editDataModel( ) Procedure for more information.

Examples

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

 exec ord_dicom.setDataModel;
 set long 5000;
 set pagesize 1000;
 select ord_dicom_admin.getDocumentContent('ordcmpf.xml') from dual;

DICOM Data Model Repository Administrator Procedures

The ORD_DICOM_ADMIN package defines these ORD_DICOM_ADMIN data model repository procedures:

deleteDocument( ) Procedure
editDataModel( ) Procedure
exportDocument( ) Procedure
insertDocument( ) Procedure
publishDataModel( ) Procedure
rollbackDataModel( ) Procedure

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 10.9 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 (see 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 (see the exportDocument( ) Procedure).

You cannot modify the data model during a rolling upgrade. Therefore, do not call this procedure if a rolling upgrade is in progress.

Examples

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

exec ord_dicom_admin.editDataModel();
select doc_name from orddcm_documents order by doc_id asc;
exec ord_dicom_admin.exportDocument('sample_pf.xml', 'DICOMDIR', 
                                    'sample_pf_export.xml');
exec ord_dicom_admin.deleteDocument('sample_pf.xml');
select doc_name from orddcm_documents order by doc_id asc;
exec ord_dicom_admin.publishDataModel();

where:

DICOMDIR: an Oracle directory object for which the administrator has been granted the WRITE privilege, and to which the contents of the specified file are to be copied.

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

You cannot edit the data model during a rolling upgrade. If you begin a rolling upgrade after calling this procedure, call the rollbackDataModel( ) procedure to terminate the editing session.

Examples

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

   exec ord_dicom_admin.editDataModel();

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 in these situations:

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.

See the setDataModel( ) Procedure and the editDataModel( ) Procedure for more information.

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', 'DICOMDIR', 'ordcmpf_exp.xml');

where:

DICOMDIR: an Oracle directory object that contains the file where the contents of the specified file are to be copied.

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

Standard data dictionary documents
Private data dictionary documents
Other configuration documents, including the following:
- Constraint documents
- XML mapping documents
- Anonymity documents
- Preference documents
- UID definition documents
- DICOM protocol 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 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 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 (see the editDataModel( ) Procedure).

Before inserting a user-defined mapping document into the repository, its associated metadata schema must have been registered as a global or local schema with Oracle XML DB. (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.)

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 (see 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. See also the setDataModel( ) Procedure.

You cannot modify the data model during a rolling upgrade. Therefore, do not call this procedure if a rolling upgrade is in progress.

Examples

Publish the changes to the repository:

   exec ord_dicom_admin.editDataModel();
   select doc_name from orddcm_documents order by doc_id asc;
   exec ord_dicom_admin.insertDocument( 'sample_pf.xml', 'PREFERENCE',
     xmltype(bfilename('DICOMDIR', 'sample_pf.xml'), 
     nls_charset_id('AL32UTF8') ) );
   select doc_name from orddcm_documents order by doc_id asc;
   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 (see the editDataModel( ) Procedure).

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

You cannot modify the data model during a rolling upgrade. Therefore, if a data model editing session was in progress before a rolling upgrade was started, you must call this procedure to roll back the data model and terminate the editing session.

Examples

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

   exec ord_dicom_admin.editDataModel();
   select doc_name from orddcm_documents order by doc_id asc;
   exec ord_dicom_admin.deleteDocument('sample_pf.xml');
   select doc_name from orddcm_documents order by doc_id asc;
   exec ord_dicom_admin.rollbackDataModel();

DICOM Repository Administrator Views

This section describes this Oracle Multimedia DICOM repository view for administrators:

orddcm_document_refs

See DICOM Repository Public Views for information about the Oracle Multimedia DICOM repository public 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 view lists the documents that are referenced by other documents. The SELECT privilege is granted to the ORDADMIN role for this view. This view is available to administrators only.

Usage Notes

Before querying this view, call either the setDataModel( ) or the editDataModel( ) procedure as follows:

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.

If you call the setDataModel( ) procedure, call it again whenever the application requires the new data model changes.

See the setDataModel( ) Procedure and the editDataModel( ) Procedure for more information.

Examples

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

-------------------------------------------------------------------------------
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 the illustration imdcm009.gif

sublocator::=

Description of the illustration imdcm010.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.

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

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 in Part 5 of the DICOM standard.

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 characters^Foot 1
`UnibyteGiven`	Given name, in unibyte characters^Footref 1
`UnibyteMiddle`	Middle name, in unibyte characters^Footref 1
`UnibytePrefix`	Prefix, in unibyte characters^Footref 1
`UnibyteSuffix`	Suffix, in unibyte characters^Footref 1
`IdeographicFamily`	Family name, in ideographic characters^Footref 1
`IdeographicGiven`	Given name, in ideographic characters^Footref 1
`IdeographicMiddle`	Middle name, in ideographic characters^Footref 1
`IdeographicPrefix`	Prefix, in ideographic characters^Footref 1
`IdeographicSuffix`	Suffix, in ideographic characters^Footref 1
`PhoneticFamily`	Family name, in phonetic characters^Footref 1
`PhoneticGiven`	Given name, in phonetic characters^Footref 1
`PhoneticMiddle`	Middle name, in phonetic characters^Footref 1
`PhoneticPrefix`	Prefix, in phonetic characters^Footref 1
`PhoneticSuffix`	Suffix, in phonetic characters^Footref 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
`VR`^Foot 2	In-stream value representation (VR) of an attribute

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

^Footnote 2See 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 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:

00080096.00401101.00080100: the code value of the Person Identification Code Sequence in the Referring Physician Identification Sequence.

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:

[1]: the first data element of an attribute. This DICOM value locator is equivalent to the DICOM value locator shown in DICOM Value Locator Example 1.

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): the default definer string. Because the tag is defined by the DICOM standard, the DICOM value locator can be represented without the definer string, as in DICOM Value Locator Example 2. This DICOM value locator is equivalent to the DICOM value locator in DICOM Value Locator Example 1.

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:

(#$abc#(##def#)#[ghi#]): the private definer string. Because the definer string contains token separator characters, it must be represented by preceding each token separator character with the escape character ("#").