| Oracle® Multimedia DICOM Developer's Guide 11g Release 2 (11.2) Part Number E10778-03 |
|
|
PDF · Mobi · ePub |
| Oracle® Multimedia DICOM Developer's Guide 11g Release 2 (11.2) Part Number E10778-03 |
|
|
PDF · Mobi · ePub |
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:
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.
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 9.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 ).
The ORD_DICOM_ADMIN package defines these ORD_DICOM_ADMIN data model repository functions:
generateTagListDocument(docSet in varchar2 default 'USER') return XMLType
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.)
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.
None.
None.
Use this function to generate a stored tag list document that is consistent with the repository documents. (See Section 10.2.8 for more information about creating stored tag list documents.)
Before calling this function, call the setDataModel( ) procedure (see the setDataModel( ) Procedure).
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(docName IN VARCHAR2) RETURN XMLTYPE
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.
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.
None.
None.
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.
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;
The ORD_DICOM_ADMIN package defines these ORD_DICOM_ADMIN data model repository procedures:
deleteDocument(docName IN VARCHAR2)
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.
The name of the document to be removed from the repository, where docName is one of the documents listed in the orddcm_documents view.
None.
None.
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).
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( )
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.
None.
None.
None.
None.
Begin an editing session in the repository, while locking it from other administrators:
exec ord_dicom_admin.editDataModel();
exportDocument(docName IN VARCHAR2, dirName IN VARCHAR2, fileName IN VARCHAR2)
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.
The name of the specified document in the repository, where docName is one of the documents listed in the orddcm_documents view.
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.
The name of the file, including the file extension (file type), but excluding the directory path.
None.
None.
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.
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(docName IN VARCHAR2, docType IN VARCHAR2, xmlDoc IN XMLType)
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
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.
The unique name of the specified document. The name cannot exceed 100 characters in length, and it must not contain the reserved prefix ORD.
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.
The XML document to be loaded into the repository. The value of this parameter must not be NULL.
None.
None.
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 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.)
See Also:
Oracle XML DB Developer's Guide for information about registering XML schemas
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 order by doc_id asc;
exec ord_dicom_admin.publishDataModel();
where:
MAPPING: the type of the document to be loaded into the repository.
DICOMDIR: the Oracle directory object that contains the file to be loaded.
publishDataModel( )
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.
None.
None.
None.
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.
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( )
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.
None.
None.
None.
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.
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();
This section describes this Oracle Multimedia DICOM repository view for administrators:
See DICOM Repository Public Views for information about the Oracle Multimedia DICOM repository public views.
| Column Name | Data Type | Description |
|---|---|---|
| doc_name | VARCHAR2(100) | Document name |
| ref_by_doc_name | VARCHAR2(100) | Referenced by document name |
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.
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.
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
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.
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
A sublocator separator or a special wildcard tag that matches to zero or a series of sublocators. (See DICOM Value Locator Example 4.)
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#]
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 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[*]
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 on the Web site for the National Electrical Manufacturers Association (NEMA) at
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.
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.
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.
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.
A DICOM value locator with a special wildcard tag (".") for all code values in the DICOM content:
..00080100
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
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 ("#").
|
 Copyright © 2007, 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|