11 Administering the DICOM Repository

This chapter uses code examples to show how to manage configuration documents in the DICOM data model repository. The code examples are written in PL/SQL to match the ORD_DICOM_ADMIN package, which is provided in PL/SQL only.

Oracle Multimedia DICOM provides capabilities for several administrative operations related to the data model repository. For example, administrators can review the Oracle-defined configuration documents in the DICOM data model repository before determining whether to add custom configuration documents for a particular organization (Steps 2 and 4 in Section 11.2 describe this process). Using views or invoking data model utility functions, administrators can obtain attributes and other detailed information about these configuration documents. Working with the procedures and functions in the ORD_DICOM_ADMIN package, administrators can insert, update, export, or delete configuration documents from the repository. Administrators of the DICOM data model repository are assigned the ORDADMIN role.

This chapter includes these sections:

See Chapter 12 for reference information about the ORD_DICOM_ADMIN package.

For additional examples, articles, and other information about Oracle Multimedia DICOM and Oracle Multimedia, see the Oracle Multimedia Software section of the Oracle Technology Network Web site at

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

11.1 Sample Session 1: Inserting Two Documents

The following sample session shows the steps for inserting a mapping document and a constraint document into the repository. This sample assumes that the following prerequisite tasks have been completed:

  • The directory object (DICOMDIR) has been created, and the administrator has been granted READ access.

  • The metadata schema associated with the mapping document has been registered with Oracle XML DB as a global XML schema.

    See Also:

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

Perform the following steps to insert a mapping document and a constraint document into the repository:

Step 1   Edit the Data Model

Prepare the data model for editing and lock it to prevent other administrators from making changes at the same time. For example:

exec ord_dicom_admin.editDataModel();

The data model remains locked until you publish the changes, perform a rollback operation, or exit the session.

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents.

Step 2   Insert the New Documents

First, insert the sample mapping document (sample_map.xml), as follows:

exec ord_dicom_admin.insertDocument('sample_map.xml', 'MAPPING',
 xmltype(bfilename('DICOMDIR', 'sample_map.xml'), nls_charset_id('AL32UTF8')));
 

See Example 2-1 for the sample mapping document (sample_map.xml).

Then, insert the sample constraint document (sample_ct.xml), as follows:

exec ord_dicom_admin.insertDocument('sample_ct.xml', 'CONSTRAINT',
 xmltype(bfilename('DICOMDIR', 'sample_ct.xml'), nls_charset_id('AL32UTF8')));

See Example 2-3 for the sample constraint document (sample_ct.xml).

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents to ensure that the inserted documents appear.

As another option, you can enter the following command to query the orddcm_document_refs view, and then review the document references:

select * from orddcm_document_refs order by doc_name, ref_by_doc_name asc;

At this point, you can run administrative tests as needed. In addition, you can call the rollbackDataModel( ) procedure to terminate the operation without publishing the changes. Or, you can continue with the next step.

Step 3   Publish the Changes

Publish the changes and unlock the data model, as follows:

exec ord_dicom_admin.publishDataModel();

The data model includes the inserted configuration documents.

11.2 Sample Session 2: Updating a Mapping Document

The following sample session shows the steps for updating a mapping document in the repository. This sample assumes that the following prerequisite tasks have been completed:

  • The directory object (DICOMDIR) has been created, and the administrator has been granted READ and WRITE access.

  • The referenced metadata schema associated with the mapping document has been registered with Oracle XML DB as a global XML schema.

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

Perform the following steps to update a mapping document in the repository:

Step 1   Edit the Data Model

As in Section 11.1, prepare the data model for editing and lock it to prevent other administrators from making changes at the same time. For example:

exec ord_dicom_admin.editDataModel();

The data model remains locked until you publish the changes, perform a rollback operation, or exit the session.

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents.

Step 2   Export the Existing Document

Export the sample mapping document (sample_map.xml) from the repository into a specified file (sample_map_export.xml) for editing. For example:

exec ord_dicom_admin.exportDocument('sample_map.xml', 'DICOMDIR', 
 'sample_map_export.xml');

See Example 2-1 for the sample mapping document (sample_map.xml).

The sample_map_export.xml file is available for editing with an XML editor.

Step 3   Delete the Existing Document

Delete the existing mapping document (sample_map.xml) from the repository, as follows:

exec ord_dicom_admin.deleteDocument('sample_map.xml');

The repository no longer includes the sample mapping document.

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents to ensure that the deleted document no longer appears.

Step 4   Edit the Exported Document

Use an XML editor to edit the file that was exported in Step 2. Then, save the changes and check the permissions on the file before inserting it into the repository.

Step 5   Insert the Edited Document

Insert the edited document (sample_map_edited.xml) into the repository, as follows:

exec ord_dicom_admin.insertDocument('sample_map_edited.xml', 'MAPPING',
 xmltype(bfilename('DICOMDIR', 'sample_map_edited.xml'), 
 nls_charset_id('AL32UTF8')));

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents to ensure that the updated document appears.

At this point, you can test your changes, run the extractMetadata( ) method on the edited mapping document to retrieve metadata from the embedded DICOM content as XML code, and then store it in a database table for searching or viewing. In addition, you can call the rollbackDataModel( ) procedure to terminate the operation without publishing the changes. Or, you can continue with the next step.

Step 6   Publish the Changes

As in Section 11.1, publish the changes and unlock the data model, as follows:

exec ord_dicom_admin.publishDataModel();

The data model includes the updated configuration document.

11.3 Sample Session 3: Deleting a Constraint Document

The following sample session shows the steps for deleting a constraint document from the repository. This sample assumes that the following prerequisite task has been completed:

The directory object (DICOMDIR) has been created, and the administrator has been granted WRITE access.

Perform the following steps to delete a constraint document from the repository:

Step 1   Edit the Data Model

As in Section 11.1, prepare the data model for editing and lock it to prevent other administrators from making changes at the same time. For example:

exec ord_dicom_admin.editDataModel();

The data model remains locked until you publish the changes, perform a rollback operation, or exit the session.

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents.

Step 2   Export the Existing Document (Optional and Recommended)

Export the sample constraint document (sample_ct.xml) from the repository into a specified file (sample_ct_export.xml) for editing. For example:

exec ord_dicom_admin.exportDocument('sample_ct.xml', 'DICOMDIR', 
'sample_ct_export.xml');

See Example 2-3 for the sample constraint document (sample_ct.xml).

Optionally, you can enter the following command to query the orddcm_document_refs view, which shows the list of documents that are referenced by other documents in the repository:

select * from orddcm_document_refs order by doc_name, ref_by_doc_name asc;

Review the list of documents to check the references for the constraint document that you intend to delete.

Step 3   Delete the Document

Delete the sample constraint document (sample_ct.xml), as follows:

exec ord_dicom_admin.deleteDocument('sample_ct.xml');

The repository no longer includes the sample constraint document.

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents to ensure that the deleted document no longer appears.

At this point, you can call the rollbackDataModel( ) procedure to terminate the operation without publishing the changes. Or, you can continue with the next step.

Step 4   Publish the Changes

Publish the changes and unlock the data model, as follows:

exec ord_dicom_admin.publishDataModel();

The data model does not include the deleted configuration document.

11.4 Sample Session 4: Inserting a Stored Tag List Document

This section describes two different approaches you can take to insert a stored tag list document into the repository:

  • Section 11.4.1 describes how to insert a stored tag list document with a known set of attribute tags.

    Follow the example in this section to create, and then insert, your own stored tag list document if you believe that you know the full set of attribute tags that all the constraint and mapping documents in your repository are likely to use.

  • Section 11.4.2 describes how to generate and insert a stored tag list document from an existing repository that is populated with constraint and mapping documents.

    Follow the examples in this section if you have an existing repository and want to generate, and then insert, a stored tag list document from tags used by your existing constraint and mapping documents.

Select the appropriate approach to take advantage of the storage and performance benefits of the stored tag list feature.

The following subsections describe each approach:

11.4.1 Inserting a Stored Tag List Document with a Known Set of Tags

You can create your own stored tag list document, and then insert it into the repository. Include all the attribute tags to be defined in the constraint and mapping documents in the repository in your document. Example 11-1 is a sample file (sample_stl.xml) that you can insert as the stored tag list document.

Example 11-1 Inserting a Stored Tag List Document with Known Attribute Tags

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
 Copyright (c) 2008, Oracle. All rights reserved.
 
   NAME
     sample_stl.xml   - sample stored tag list 
 
-->
<ATTRIBUTE_TAG_LIST xmlns="http://xmlns.oracle.com/ord/dicom/attributeTag_1_0"
 xmlns:dt="http://xmlns.oracle.com/ord/dicom/datatype_1_0" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://xmlns.oracle.com/ord/dicom/attributeTag_1_0
 http://xmlns.oracle.com/ord/dicom/attributeTag_1_0">
  <DOCUMENT_HEADER>
    <dt:DOCUMENT_CHANGE_LOG>
      <dt:DOCUMENT_MODIFIER>ORACLE</dt:DOCUMENT_MODIFIER>
      <dt:DOCUMENT_MODIFICATION_DATE>2009-02-25</dt:DOCUMENT_MODIFICATION_DATE>
      <dt:DOCUMENT_VERSION>1.0</dt:DOCUMENT_VERSION>
    </dt:DOCUMENT_CHANGE_LOG>
  </DOCUMENT_HEADER>
  <ATTRIBUTE_TAG>00020002</ATTRIBUTE_TAG>
  <ATTRIBUTE_TAG>00020003</ATTRIBUTE_TAG>
  <ATTRIBUTE_TAG>00100010</ATTRIBUTE_TAG>
</ATTRIBUTE_TAG_LIST>

This approach assumes that the following prerequisite task has been completed:

The directory object (DICOMDIR) has been created, and the administrator has been granted READ access.

Perform the following steps to insert a stored tag list document with a known set of attribute tags into the repository:

Step 1   Edit the Data Model

As in Section 11.1, prepare the data model for editing and lock it to prevent other administrators from making changes at the same time. For example:

exec ord_dicom_admin.editDataModel();

The data model remains locked until you publish the changes, perform a rollback operation, or exit the session.

At this point, to see which documents are stored in the repository, enter the following command to query the orddcm_documents view:

select doc_name from orddcm_documents order by doc_id asc;
Step 2   Insert the Stored Tag List Document

Insert the sample stored tag list document file (sample_stl.xml), as follows:

exec ord_dicom_admin.insertDocument(
                           'sample_stl.xml',
                           'STORED_TAG_LIST',
                            xmltype(bfilename('DICOMDIR', 'sample_stl.xml'),
                            nls_charset_id('AL32UTF8') ) );
Step 3   Publish the Changes

Publish the changes and unlock the data model, as follows:

exec  ord_dicom_admin.publishDataModel;

The data model includes the inserted configuration documents.

11.4.2 Generating and Inserting a Stored Tag List Document

If you have an existing repository that is populated with constraint and mapping documents, you can generate a stored tag list document from tags used by your existing constraint and mapping documents, make changes to the tags as needed, and insert the stored tag list document into the repository.

To enforce specific rules for the attributes you want to include in your stored tag list, insert a preference document that defines those attribute rules. Example 11-2 shows a preference document (sample_pf.xml) that enforces the mandate attribute tags rule for mapping and constraint documents. The code statements where this operation is performed are highlighted in bold.

Example 11-2 Sample Preference Document for the Mandate Attribute Tags Rule

<?xml version="1.0" encoding="UTF-8"?>
<DICOM_RUNTIME_PREFERENCES xmlns="http://xmlns.oracle.com/ord/dicom/preference_1_0"
  xmlns:dt="http://xmlns.oracle.com/ord/dicom/datatype_1_0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://xmlns.oracle.com/ord/dicom/preference_1_0 
  http://xmlns.oracle.com/ord/dicom/preference_1_0">
 <DOCUMENT_HEADER>
  <dt:DOCUMENT_CHANGE_LOG>
   <dt:DOCUMENT_MODIFIER>Developer 1</dt:DOCUMENT_MODIFIER>
   <dt:DOCUMENT_MODIFICATION_DATE>2009-02-20</dt:DOCUMENT_MODIFICATION_DATE>
   <dt:DOCUMENT_VERSION>0.2</dt:DOCUMENT_VERSION>
   <dt:MODIFICATION_COMMENT> enable MANDATE_ATTR_TAGS_IN_STL</dt:MODIFICATION_COMMENT>
  </dt:DOCUMENT_CHANGE_LOG>
 </DOCUMENT_HEADER>
 <PREFERENCE_DEF>
  <PARAMETER>MANDATE_ATTR_TAGS_IN_STL</PARAMETER>
  <DESCRIPTION> allowed values true or false</DESCRIPTION>
  <VALUE>true</VALUE>
 </PREFERENCE_DEF>
</DICOM_RUNTIME_PREFERENCES>

Because the value of the MANDATE_ATTR_TAGS_IN_STL parameter is set to true, all the tags used by the constraint and mapping documents are listed in the stored tag list document. See Section 10.2.6.3 for more information about defining this parameter in preference documents.

This approach assumes that the following prerequisite task has been completed:

The directory object (DICOMDIR) has been created, and the administrator has been granted READ and WRITE access.

Perform the following steps to generate and insert a stored tag list document into the repository:

Step 1   Edit the Data Model

As in Section 11.1, prepare the data model for editing and lock it to prevent other administrators from making changes at the same time. For example:

exec ord_dicom_admin.editDataModel();

The data model remains locked until you publish the changes, perform a rollback operation, or exit the session.

Optionally, you can enter the following command to query the orddcm_documents view:

select doc_name from orddcm_documents order by doc_id asc;

Review the list of documents to see which documents exist in your repository.

Step 2   Generate and Export the Stored Tag List Document to a File

Generate and export the stored tag list document to the sample stored tag list document file (sample_stl.xml), as shown in Example 11-3:

Example 11-3 Generating and Exporting a Stored Tag List Document to a File

--
-- Generate a tag list document and store in sample_stl.xml
-- in DICOMDIR
--
-- A stored tag list document must include all tags used by
-- mapping and constraint documents in the repository
-- to enforce the mandate_attr_tags_in_stl rule using a
-- preference document.
--
-- Use the 'ALL' option to ensure that the generated tag list
-- document contains all the tags used by mapping and constraint
-- documents.
--
set serveroutput on;
declare
  fid           UTL_FILE.FILE_TYPE;
  buf           VARCHAR2(32767);
  bytesLeft     INTEGER;
  pos           INTEGER;
  chunk         INTEGER;
  xml_clob      CLOB;
  xt            XMLType;
BEGIN

   xt := ORD_DICOM_ADMIN.generateTagListDocument('ALL');
   if (xt is null) then
    dbms_output.put_line('Repository has no documents');
    dbms_output.put_line('Tag list document is null');
    return;
   end if;

    -- write xml document to file using UTL_FILE
    -- let UTL_FILE report errors for directory and filename
    fid := utl_file.fopen( 'DICOMDIR', 'sample_stl.xml', 'w', 32767 );
 
 
    -- Read from clob and write to file
    select XMLSerialize(document xt as clob)        into xml_clob from dual;
    bytesLeft := dbms_lob.getLength( xml_clob );
    pos       := 1;
    WHILE bytesLeft > 0 loop
      chunk := 32767;
      IF bytesLeft < chunk THEN
        chunk := bytesLeft;
      END IF;
      dbms_lob.read(xml_clob, chunk, pos, buf );
      utl_file.put( fid, buf);  
      utl_file.fflush(fid);
      bytesLeft := bytesLeft - chunk;
      pos := pos + chunk;
    end loop;
 
    utl_file.fclose( fid );
 
    --free the temporary blob returned by xmltype
    if(dbms_lob.isTemporary(xml_clob) <> 0) then
      dbms_lob.freeTemporary(xml_clob);
    end if;
 
 
   exception
   WHEN OTHERS then
    -- free temp lobs
    if(dbms_lob.isTemporary(xml_clob) <> 0) then
      dbms_lob.freeTemporary(xml_clob);
    end if;
 
    raise;   -- original exception
END;
/
Step 3   Optional: Edit the Stored Tag List Document

Use an XML editor to edit the stored tag list document file that was exported in Step 2. Make changes to the tags as needed, save the changes, and check the permissions on the file before inserting it into the repository.

Step 4   Insert the Stored Tag List Document

Insert the generated stored tag list document (sample_stl.xml), as follows:

ord_dicom_admin.insertDocument(
                        'sample_stl.xml', 
                        'STORED_TAG_LIST',
                         xmltype(bfilename('DICOMDIR', 'sample_stl.xml'),
                         nls_charset_id('AL32UTF8') ) );
Step 5   Optional: Enforce the Mandate Attribute Tags Rule

To enforce the mandate attribute tags rule, insert a preference document with the value of the MANDATE_ATTR_TAGS_IN_STL parameter set to true, as follows:

 exec ord_dicom_admin.insertDocument(
                           'sample_pf.xml', 
                           'PREFERENCE',
                            xmltype(bfilename('DICOMDIR', 'sample_pf.xml'),
                            nls_charset_id('AL32UTF8') ) );

See Example 11-2 for a sample preference document that enforces this rule.

Note:

If the MANDATE_ATTR_TAGS_IN_STL parameter is set to true in your preference document, and you attempt to insert any mapping or constraint documents that contain tags that are not listed in your stored tag list document, those documents are not inserted into the repository. See Section 10.2.6.3 for more information about this preference parameter.

Optionally, you can enter the following command to query the orddcm_documents view:

select * from orddcm_documents order by doc_id asc;

Review the list of documents.

Step 6   Publish the Changes

Publish the changes and unlock the data model, as follows:

exec  ord_dicom_admin.publishDataModel;