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/
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:
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.
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.
Publish the changes and unlock the data model, as follows:
exec ord_dicom_admin.publishDataModel();
The data model includes the inserted configuration documents.
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:
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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:
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:
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;
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') ) );
Publish the changes and unlock the data model, as follows:
exec ord_dicom_admin.publishDataModel;
The data model includes the inserted configuration documents.
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:
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.
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;
/
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.
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') ) );
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 totrue 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.
Publish the changes and unlock the data model, as follows:
exec ord_dicom_admin.publishDataModel;