Overview of DICOM Administration

9 Overview of DICOM Administration

This chapter briefly describes the tasks that are related to the administration of the Oracle Multimedia DICOM data model repository.

The Oracle Multimedia DICOM data model repository is a set of collectively managed, user-configurable XML documents that defines the run-time behavior of Oracle Multimedia DICOM (see Configuration Documents in the Repository). Because Oracle Multimedia DICOM is fully functional after installing Oracle Multimedia, administrators need not access the repository unless they want to update it to configure Oracle Multimedia DICOM for a particular database instance. Each database has its own set of configuration documents. Administrators can customize the repository by adding or deleting configuration documents. Only one administrator at a time is permitted to make changes in the data model repository. Administrators of the DICOM data model repository are assigned the ORDADMIN role.

Administrators can perform several repository management tasks. This chapter provides guidelines for loading the repository, and retrieving, adding, and removing content from the repository.

The DICOM data model repository provides an administrative (PL/SQL) application programming interface (API) for managing configuration documents. See ORD_DICOM_ADMIN Package Reference for reference information about the ORD_DICOM_ADMIN data model repository API.

This chapter includes these sections:

See Also:

Creating DICOM Configuration Documents for detailed information about writing configuration documents
Table 3-1for information about other application programming interfaces (APIs) that are available to administrators

9.1 Assigning Administrator Roles and Privileges

After installing Oracle Multimedia DICOM, the ORDADMIN role is created, with the database system privileges required for administration of the DICOM data model repository.

The ORDADMIN role must be assigned to the administrator of the DICOM data model repository. The following code segment shows a sample GRANT statement for the administrator dcmadmin:

GRANT ORDADMIN to dcmadmin;

Because of the way database roles behave, tasks for which the administrator must write PL/SQL named procedures require explicit privileges. The following code segment shows a sample of a GRANT statement for an administrator named dcmadmin:

GRANT EXECUTE on ORD_DICOM_ADMIN to dcmadmin;
GRANT SELECT on orddcm_document_refs to dcmadmin;

Administrators must also be granted the WRITE privilege for specified directories. For example, during operations where configuration documents are exported, administrators must have WRITE access to the directory where those documents are to be stored.

All users can load the data model repository into memory structures and view several public views. Only administrators can export, insert, or delete configuration documents from the data model repository. And, only administrators can query administrator-only views.

Note:

Keep these administrative guidelines in mind:

The editDataModel( ) procedure enables administrators to lock the data model while making changes.
Changes in the data model repository are committed only by using the publishDataModel( ) procedure. In addition to committing the changes, this procedure unlocks the data model, making it available to other administrators.

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

9.2 Managing XML Schemas

The DICOM XML schemas in Oracle Multimedia DICOM are registered as global XML schemas in Oracle Database with Oracle XML DB. If you define any custom XML schemas, they must be also registered as global or local schemas with Oracle XML DB. You can find and examine the registered XML schemas by querying the dictionary view ALL_XML_SCHEMAS.

Note:

Custom XML schemas associated with user-defined mapping documents can be registered as local schemas with Oracle XML DB. Registering your custom XML schemas as local schemas with Oracle XML DB prevents other users from using them for validation. Register your custom XML schemas as global schemas with Oracle XML DB to allow other users to validate against them.

The following subsections briefly describe how you can use XML DB with your DICOM XML schemas:

See Also:

Oracle XML DB Developer's Guide for more information about registering XML schemas
Oracle Database Reference for more information about the dictionary view ALL_XML_SCHEMAS

9.2.1 Registering XML Schemas

The DICOM XML schemas that correspond to the default configuration documents supplied by Oracle are automatically registered during installation. (See DICOM XML Schemas for a list of the installed DICOM XML schemas.) Oracle requires that you manually register all user-defined (custom) XML schemas as global or local schemas, using Oracle XML DB.

Note:

Setting the parameter LOCAL to FALSE indicates that the schema is global.

See Also:

Oracle XML DB Developer's Guide for an example of how to register a custom schema as a global schema

9.2.2 Finding User-Defined XML Schemas

After registering the custom XML schemas for your DICOM data model repository, you can search for and examine them. Query the dictionary view ALL_XML_SCHEMAS to find all the registered XML schemas.

Example 9-1 shows a sample of how to list the namespaces for the metadata schemas associated with the user-defined mapping documents in your DICOM data model repository.

Note:

Example 9-1 includes a call to the setDataModel( ) procedure. This procedure call might not be required in all situations.

See the setDataModel( ) Procedure and Loading the Data Model Repository for more information.

See Also:

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

Example 9-1 Finding User-Registered XML Schemas

exec ord_dicom.setdatamodel;
 
select t.doc_name, xmlcast(xmlquery(
       'declare default element namespace
       "http://xmlns.oracle.com/ord/dicom/mapping_1_0"; $x//NAMESPACE'
      passing ord_dicom_admin.getdocumentcontent(t.doc_name) as "x" 
      returning content) as varchar2(4000) ) as schema_url
  from orddcm_documents  t
  where t.installed_by_oracle=0 and t.doc_type= 'MAPPING'
  order by t.doc_id asc;
 
DOC_NAME             SCHEMA_URL
-------------------- -------------------------------------
sample_map_10.xml     http://www.mycompany.com/metatest10
sample_map_11.xml     http://www.mycompany.com/metatest11

9.3 Loading the Data Model Repository

At the start of every database session, administrators and users must load the data model repository from the database into memory structures. Users load the data model by calling the setDataModel( ) procedure. Administrators load the data model by calling either the setDataModel( ) procedure or the editDataModel( ) procedure.

After loading the repository into memory, administrators and users can call the setDataModel( ) procedure whenever the application requires the new data model changes.

Note:

Keep these guidelines in mind:

Administrators and users must call the setDataModel( ) procedure before calling any other DICOM methods, functions, or procedures.
Administrators can call the setDataModel( ) procedure when no changes are being made to the data model (for example: when calling the getDocumentContent( ) procedure or the exportDocument( ) procedure only).
Administrators can call the editDataModel( ) procedure when making changes to the data model (for example: when inserting or deleting documents).

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

Using the DICOM data model utility in the ORD_DICOM package, administrators and users call the setDataModel( ) procedure as follows:

exec ord_dicom.setdatamodel;

See the setDataModel( ) Procedure for more information.

Using the ORD_DICOM_ADMIN package, administrators call the editDataModel( ) procedure as follows:

exec ord_dicom_admin.editDataModel();

See the editDataModel( ) Procedure for more information.

9.4 Managing the Impact of Oracle Data Guard Rolling Upgrades

Oracle Multimedia DICOM does not support making changes to the DICOM data model during a Data Guard rolling upgrade. Specifically, administrators cannot insert or delete documents from the repository while a rolling upgrade is in progress. Thus, avoid calling any of these procedures during a rolling upgrade:

Note:

Administrators can call the rollbackDataModel( ) procedure to terminate an editing session that began before starting a rolling upgrade operation (see the rollbackDataModel( ) Procedure).

See Also:

Oracle Database Upgrade Guide for information about database rolling upgrades
Oracle Data Guard Concepts and Administration for information about rolling upgrades and other Oracle Data Guard features

9.5 Browsing the Repository with Views

Several public views are available to all DICOM users for browsing the DICOM repository. Oracle Multimedia DICOM also provides the administrator view orddcm_document_refs, which lists the documents that are referenced by other documents in the repository.

Administrators commonly use the views orddcm_documents, orddcm_document_types, and orddcm_document_refs when inserting, updating, and deleting documents from the repository.

See Table 3-2 for the list of repository views that are available to administrators.

9.6 Exporting Documents from the Repository

Before exporting documents from the repository (and possibly before making any changes to the configuration documents), administrators should perform the following tasks:

Call the setDataModel( ) procedure at the beginning of each database session to load the repository from the database into memory structures. Locking the repository at this point is not required.

Administrators (and other users) can also call this procedure whenever the application requires the new data model changes.

See the setDataModel( ) Procedure for more information.
Obtain copies of the existing documents in the repository, using either the getDocumentContent( ) function or the exportDocument( ) procedure.

The getDocumentContent( ) function returns the specified document as data type XMLType.

The exportDocument( ) procedure writes the contents of the specified document to a specified file in a directory for which the administrator has been granted the WRITE privilege.

See the getDocumentContent( ) Function and the exportDocument( ) Procedure for more information.

9.7 Inserting Documents into the Repository

The process of inserting documents into the repository can involve the use of these procedures:

editDataModel( )
insertDocument( )
publishDataModel( )
rollbackDataModel( )

See ORD_DICOM_ADMIN Package Reference for reference information about these procedures. See Administering the DICOM Repository for examples of the insertion process.

The following subsections briefly describe the insertion process for different types of documents:

9.7.1 Inserting Anonymity, Mapping, and Constraint Documents

For anonymity documents and mapping documents, the order of insertion is irrelevant. For constraint documents, however, the order of insertion is important. If there are dependencies among any of the constraint documents to be inserted, insert the documents without dependencies first. Then, insert the remaining documents.

9.7.2 Inserting Dictionary Documents

Inserting standard or private dictionary documents requires merging all dictionary attributes each time a new dictionary document is inserted, in accordance with the following rules:

Attribute tags must be unique, and must not match existing wildcard tags.
Attribute tags must not be used in other document types.

In addition, for private dictionary documents, attribute tags must not be included in any existing range tags.

Note:

Oracle recommends limiting insertions of standard dictionary documents to reflect changes or additions to the DICOM standard only.

See the XML schemas ordcmsd.xsd and ordcmpv.xsd in DICOM XML Schemas for more information about DICOM attributes and attribute tags in dictionary documents.

9.7.3 Inserting Preference and UID Definition Documents

The installed preference document (ordcmpf.xml) assigns default preference values. Administrators can insert a user-defined preference document into the repository to override some or all of the default preference values. Preference values that are not overridden by a user-defined preference document retain their Oracle-defined default values.

Administrators can also insert user-defined UID definition documents to add new private UID values, or to reflect updates in the DICOM standard.

To insert a user-defined preference or UID definition document, follow these steps:

Export the installed, Oracle-defined document and rename it.
Update the exported, renamed document, changing the parameter values as required.
Insert the updated user-defined document into the repository.

If a user-defined preference or UID definition document is later deleted, the Oracle-installed document is reapplied.

Note:

Only one user-defined preference or UID definition document is permitted in the repository.

9.7.4 Inserting Stored Tag List Documents

Administrators can use the generateTagListDocument( ) function to create a stored tag list document, which is a list of the attribute tags used in a specified set of mapping and constraint documents in the repository.

The stored tag list document is an optional XML document that specifies the DICOM attributes to be extracted from the embedded DICOM content and stored in the XML metadata attribute of the ORDDicom object when the setProperties( ) method is called. Generally, stored tag list documents contain the attribute tags used in mapping and constraint documents.

See the generateTagListDocument( ) Function for more information. See Sample Session 4: Inserting a Stored Tag List Document for an example of the stored tag list document insertion process.

9.7.5 Inserting DICOM Protocol Documents

Administrators can use the insertDocument( ) procedure (specifying DICOM_PROTOCOL as the value of the docType parameter) to insert a new DICOM protocol document into the data model.

The DICOM protocol document is an XML document that is a named container for user-configurable parameters that govern where DICOM images and metadata are stored in Oracle Database. Each instance of the Oracle DICOM protocol adapter that is configured to connect to Oracle Database must have an associated DICOM protocol document in order to store, query, and retrieve DICOM images and metadata to and from Oracle Database.

See the insertDocument( ) Procedure for more information. See Sample Session 5: Inserting a DICOM Protocol Document for an example of the DICOM protocol document insertion process.

See Also:

Configuring DICOM Protocol Support for Oracle Database for details about configuring DICOM protocol documents
Creating DICOM Protocol Documents for more information about creating DICOM protocol documents

9.8 Updating Documents in the Repository

The process of updating documents in the repository can involve the use of these procedures:

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

See ORD_DICOM_ADMIN Package Reference for reference information about these procedures. See Sample Session 2: Updating a Mapping Document for an example of the update process.

The following subsections briefly describe the update process for different types of documents:

9.8.1 Updating Anonymity, Mapping, and Constraint Documents

Updating anonymity documents, mapping documents, and constraint documents involves a similar set of actions. For both anonymity documents and mapping documents, follow these steps:

Export the existing document.
Edit the exported document.
Delete the existing document.
Insert the edited document.

Constraint documents are updated in reverse order from their insertion order. In addition, if there are dependencies among any of the constraint documents to be updated, update the documents with no dependencies first. Then, update the remaining documents.

9.8.2 Updating Dictionary Documents

Updating standard or private dictionary documents requires checking the attribute tags and dependencies with other documents in the repository. Standard and private dictionary documents can be updated only if no other documents are using the attribute tags that are defined in the new documents. To update the attribute tags that are being used by other documents, first update the dependent documents to remove the referenced attribute tags. Then, update the dictionary tags in accordance with the following rules:

Attribute tags must be unique, and must not match existing wildcard tags.
Attribute tags must not be used in other document types.

In addition, for private dictionary documents, DICOM attribute tags must not be included in any existing range tags.

Note:

Oracle recommends limiting updates of standard dictionary documents to reflect changes or additions to the DICOM standard only.

See the XML schemas ordcmsd.xsd and ordcmpv.xsd in DICOM XML Schemas for more information about DICOM attributes and attribute tags in dictionary documents.

9.8.3 Updating Preference and UID Definition Documents

To update existing user-defined preference documents or UID definition documents, follow these steps:

Export the user-defined document.
Edit the exported document.
Delete the existing user-defined document.
Insert the edited document.

Note:

UID values defined by Oracle or the DICOM standard must not be changed.

9.9 Deleting Documents from the Repository

The process of deleting documents from the repository can involve the use of these procedures:

editDataModel( )
exportDocument( )
deleteDocument( )
publishDataModel( )
rollbackDataModel( )

Use the exportDocument( ) procedure to save a copy of an original document before deleting it from the repository.

Only user-defined documents can be deleted. Documents installed by Oracle are default documents that cannot be removed. Additionally, to ensure conformance with referenced constraints, remove documents in the reverse order from the order in which they were loaded.

See ORD_DICOM_ADMIN Package Reference for reference information about these procedures. See Sample Session 3: Deleting a Constraint Document for an example of the deletion process.

The following subsections briefly describe the deletion process for different types of documents:

9.9.1 Deleting Anonymity, Mapping, and Constraint Documents

For anonymity documents and mapping documents, the order of deletion is irrelevant. Constraint documents, however, must be deleted in reverse order from their insertion order.

9.9.2 Deleting Dictionary Documents

Deleting standard or private dictionary documents requires checking dependencies with other documents in the repository. For example, a user-defined dictionary document can be deleted only if no other documents reference it.

9.9.3 Deleting Preference and UID Definition Documents

When a user-defined preference document is deleted, the values of the preference parameters revert to the installed values from the default Oracle-defined preference document (ordcmpf.xml). Similarly, when a UID definition document is deleted, the UID values revert to the installed values from the default Oracle-defined UID definition document (ordcmui.xml).

9.10 Oracle Data Pump Utilities Support for Oracle Multimedia DICOM

Export and import operations using Oracle Data Pump are described in Oracle Database Utilities. This section provides guidelines and examples for using the Oracle Data Pump commands expdp and impdp to perform export and import operations on Oracle Multimedia DICOM.

DICOM data stored in user tables is automatically handled by Oracle Data Pump. The DICOM data model repository contains tables that are populated from Oracle-installed documents and user-supplied documents stored in the ORDDATA schema. On full mode export and import operations, user-supplied documents stored in the ORDDATA schema are exported and imported. Oracle-installed documents stored in the ORDDATA schema already exist in the source database and the target database, thus they are not exported or imported on these operations.

The examples in this section use the commands expdp and impdp. After you enter the command with your user name and the appropriate parameters, you are prompted for a password. The examples in this section do not show these prompts.

The following subsections provide information about roles and modes for export and import operations on the DICOM data model repository:

See Also:

Oracle Database Utilities for more information about Oracle Data Pump and its command-line clients, expdp and impdp

9.10.1 Roles for Export and Import Operations

Many Data Pump export and import operations require that administrators have these roles, respectively:

DATAPUMP_EXP_FULL_DATABASE
DATAPUMP_IMP_FULL_DATABASE

See Also:

Oracle Database Utilities for more information about the required roles for the Oracle Data Pump Export and Import utilities

9.10.2 Mode for Export and Import Operations

Export and import operations for multimedia data stored in user tables (whether in BLOB columns or in Oracle Multimedia data type columns) are supported in all export and import modes. However, when administrators use Oracle Multimedia DICOM to store user documents in the DICOM data model repository, export and import operations are supported in full mode only. User documents in the DICOM data model are only exported and imported in full mode.

The following subsections describe these operations:

9.10.2.1 Exporting in Full Mode

Use full mode to export when you use Oracle Multimedia DICOM and the DICOM data model repository contains user documents that you want to export.

Example 9-2 shows how to perform a full mode export.

Example 9-2 defines the following parameters and values:

Parameter and Value	Definition
`FULL=Y`	Specifies full mode export. There is no default value.
`CONTENT=ALL`	Specifies the content to export. The default value `ALL` specifies to export data and metadata.
`DIRECTORY=DUMP_DIR`	Specifies the default directory location for the dump file and the log file. The directory `DUMP_DIR` must already exist, and you must have access to it.
`DUMPFILE=exp_orddata.dmp`	Specifies the name of the dump file for the export job.
`LOGFILE=exp_orddata.dmp`	Specifies the name of the log file for the export job.

See Also:

Oracle Database Utilities for more information about full mode export

Example 9-2 Full Mode Export

expdp FULL=Y CONTENT=ALL DIRECTORY=DUMP_DIR 
  DUMPFILE=exp_orddata.dmp LOGFILE=exp_orddata.log

9.10.2.2 Importing in Full Mode

Use full mode to import when you use Oracle Multimedia DICOM and the DICOM data model repository contains user documents that you want to import.

Example 9-3 shows how to perform a full mode import, using the parameters and settings recommended by Oracle.

Example 9-3 defines the following parameters and values:

Parameter and Value	Definition
`FULL=Y`	Specifies full mode import. There is no default value.
`CONTENT=ALL`	Specifies the content to import. The default value `ALL` specifies to import data and metadata.
`DIRECTORY=DUMP_DIR`	Specifies the default directory location for the dump file and the log file. The directory `DUMP_DIR` must already exist, and you must have access to it.
`DUMPFILE=exp_orddata.dmp`	Specifies the name of the dump file for the import job.
`LOGFILE=imp_orddata.log`	Specifies the name of the log file for the import job.

See Also:

Oracle Database Utilities for more information about full mode import

Example 9-3 Full Mode Import

impdp FULL=Y CONTENT=ALL DIRECTORY=DUMP_DIR DUMPFILE=exp_orddata.dmp 
  LOGFILE=imp_orddata.log