7 ORDDicom Object Type Reference

Oracle Multimedia provides the ORDDicom object type, which supports the storage, management, and manipulation of DICOM format medical images and other data. The ORDDicom object is intended as an object that is written only once. To generate a new ORDDicom object by image processing or compression, create a new ORDDicom object, ORDImage object, or BLOB.

The ORDDicom object type is defined in the ordcspec.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 attributes, constructors, and methods in the ORDDicom object interface. See Table 3-1 for information about other DICOM application programming interfaces (APIs).

This chapter contains these sections:

7.1 ORDDicom Object Examples

The examples in this chapter use the MEDICAL_IMAGE_OBJ table, which these examples create in the Product Media (PM) sample schema. See Section 7.1.2 when reading through these examples.

Before using ORDDicom methods, you must load some data into the table. For example, you can use the SQL*Loader utility, a Java client, or the import( ) method. Substitute your DICOM files for those in the examples.

Note:

If you manipulate the DICOM content itself (by either directly modifying the BLOB or changing the external source), call the setProperties( ) method to ensure that the object attributes stay synchronized. You must also ensure that the update time is modified. Otherwise, the object attributes will not match the DICOM content.

See the setProperties( ) method for more information.

See Also:

See Oracle Database Sample Schemas for information about the PM and other sample schemas

7.1.1 Directory Definition and Setup for ORDDicom Object Examples

Issue the following statements before executing the examples, where c:\mydir\work is the directory where the user pm can find the DICOM files:

CREATE OR REPLACE DIRECTORY DICOMDIR as 'c:\mydir\work';
GRANT READ, WRITE ON DIRECTORY DICOMDIR TO pm;

Note:

At the beginning of each database session, call the setDataModel( ) procedure. See the setDataModel( ) Procedure for more information.

7.1.2 MEDICAL_IMAGE_OBJ Table Definition

Before loading data into the table, you must create the table and columns where the data is to be stored. The following PL/SQL code segment creates the MEDICAL_IMAGE_OBJ table with five columns.

CONNECT pm

Enter password: password

CREATE TABLE MEDICAL_IMAGE_OBJ
(
 id            integer primary key,
 dicom_src     ordsys.orddicom,
 dicom_dest    ordsys.orddicom,
 image_dest    ordsys.ordimage,
 blob_dest     blob 
);
COMMIT;

where:

  • dicom_src: the source DICOM content in the ORDDicom object.

  • dicom_dest: the destination DICOM content in the ORDDicom object.

  • image_dest: the destination DICOM content in the ORDImage object.

  • blob_dest: the destination DICOM content in the BLOB.


ORDDicom Object Type

The ORDDicom object type supports the storage, management, and manipulation of DICOM format medical images and other data. The attributes for this object type are defined as follows in the ordcspec.sql file:

  -------------------
  -- TYPE ATTRIBUTES
  -------------------
  SOP_INSTANCE_UID     VARCHAR2(128),
  SOP_CLASS_UID        VARCHAR2(64),
  STUDY_INSTANCE_UID   VARCHAR2(64),
  SERIES_INSTANCE_UID  VARCHAR2(64),
  source               ORDDataSource,
  metadata             SYS.XMLType,
  contentLength        INTEGER,
  flag                 INTEGER,
  extension            BLOB,
 

where:

  • SOP_INSTANCE_UID: the SOP instance UID of the embedded DICOM content.

  • SOP_CLASS_UID: the SOP class UID of the embedded DICOM content.

  • STUDY_INSTANCE_UID: the study instance UID of the embedded DICOM content.

  • SERIES_INSTANCE_UID: the series instance UID of the embedded DICOM content.

  • source: the original DICOM content stored within the database, under transaction control as a BLOB (recommended), or stored in an operating system-specific file in a local file system with pointer stored in the database.

  • metadata: the XML metadata document extracted from the embedded DICOM content.

  • contentLength: the length of the embedded DICOM content, in number of bytes.

  • flag: an Oracle reserved attribute.

  • extension: an Oracle reserved attribute.


ORDDicom Constructors

This section describes these ORDDicom constructor functions:

The ORDDicom object can be constructed using these constructors in a SQL statement or PL/SQL program.

The ORDDicom object has embedded BLOB attributes. BLOB locators must be initialized before they can be accessed. Thus, newly constructed ORDDicom objects (unless constructed from a temporary BLOB) must be inserted into a table before you can call object member methods on these ORDDicom objects.


ORDDicom( ) for BLOBs

Format

ORDDicom(SELF IN OUT NOCOPY ORDDicom, data IN BLOB, setproperties IN INTEGER DEFAULT 0) RETURN SELF AS RESULT

Description

Constructs an ORDDicom object from a BLOB. The data stored in the BLOB is copied into the ORDDicom object when the constructed ORDDicom object is inserted or updated into a table. The metadata conforms to the XML schema defined by the default mapping document.

Parameters

data

Embedded DICOM content stored in a BLOB.

setproperties

Indicator flag that determines whether the DICOM attributes are extracted from the embedded DICOM content. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the constructed ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this constructor to create an ORDDicom object when the DICOM content is stored in either a temporary or a persistent BLOB.

Examples

Create an ORDDicom object from a BLOB:

SQL> desc blob_tbl;
Name                   Null?    Type---------------------- -------- --------------------
ID                              NUMBER(38)DATA                            BLOB 

 insert into medical_image_obj (id, dicom_src)
    select s.id, ORDDicom(s.data) from blob_tbl s;

ORDDicom( ) for ORDImage

Format

ORDDicom(SELF IN OUT NOCOPY ORDDicom, data IN ORDImage, setproperties IN INTEGER DEFAULT 0) RETURN SELF AS RESULT

Description

Constructs an ORDDicom object from an ORDImage object that has either a local source (BLOB) or a file source (BFILE). If the DICOM content is stored originally in the BLOB of the ORDImage object, the data is copied into the BLOB in the ORDDicom object source attribute when the constructed ORDDicom object is inserted or updated into a table. If the DICOM content is stored originally as a BFILE source of the ORDImage object, the srcType, srcLocation, and srcName parameters from the ORDImage source are copied into the source attribute of the ORDDicom object. The metadata conforms to the XML schema defined by the default mapping document.

Parameters

data

Embedded DICOM content stored in an ORDImage object.

setproperties

Indicator flag that determines whether the DICOM attributes are extracted from the embedded DICOM content. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the constructed ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this constructor to create an ORDDicom object when the DICOM content is stored in an ORDImage object. Or, use this constructor to migrate an ORDImage object to an ORDDicom object.

Examples

Create an ORDDicom object from an ORDImage object:

SQL>  desc image_tbl;
Name                   Null?    Type---------------------- -------- --------------------
ID                              NUMBER(38)IMAGE                           ORDIMAGE 

 insert into medical_image_obj (id, dicom_src)
    select s.id, ORDDicom(s.image) from image_tbl s;

ORDDicom( ) for Other Sources

Format

ORDDicom( SELF IN OUT NOCOPY ORDDicom, source_type IN VARCHAR2 DEFAULT 'LOCAL', source_location IN VARCHAR2 DEFAULT NULL, source_name IN VARCHAR2 DEFAULT NULL, setproperties IN INTEGER DEFAULT 0 ) RETURN SELF AS RESULT

Description

Constructs an ORDDicom object from a specific source. By default, the value of the source_type parameter is set to LOCAL, which means that the source of the data is stored locally in the database in a BLOB. With the default values, an empty object with a local source is constructed. If the value of the source_type parameter is set to FILE, an ORDDicom object is constructed with the source stored as an external FILE. The metadata conforms to the XML schema defined by the default XML mapping document.

Parameters

source_type

The type of the source. Valid values are: FILE or LOCAL. The default is LOCAL.

source_location

The directory location of the source (used for source_type=FILE).

source_name

The file name of the source (used for source_type=FILE).

setproperties

Indicator flag that determines whether the DICOM attributes are extracted from the embedded DICOM content. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the constructed ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this constructor to create an ORDDicom object when the DICOM content is stored in the file system. Use the empty constructor when uploading DICOM content from a client, such as a Web browser or a Java application. Or, use the empty constructor as a destination object for methods such as processCopy( ), makeAnonymous( ), and writeMetadata( ).

Examples

Example 1:

Create an ORDDicom object from a file without populating the object attributes:

 insert into medical_image_obj (id, dicom_src)
    values (1, ORDDicom('FILE', 'DICOMDIR', 'example.dcm'));

Example 2:

Create an ORDDicom object from a file with the setProperties flag set:

 insert into medical_image_obj (id, dicom_src)
    values (2, ORDDicom('FILE', 'DICOMDIR', 'example.dcm', 1));

Example 3:

Create an empty ORDDicom object:

 insert into medical_image_obj (id, dicom_src)
    values (3, ORDDicom());

ORDDicom Methods

This section presents reference information about these ORDDicom methods:

Note:

In this section, <unique-UID> represents a 64-byte, dot-concatenated, numeric string that represents a globally unique identifier for DICOM content worldwide. The UID is commonly constructed with a root that uniquely identifies the organization producing the DICOM content, and a suffix that uniquely identifies the DICOM content within that organization. For some examples in this section, you must replace <unique-UID> with the appropriate UID.

export( )

Format

export(SELF IN ORDDicom, dest_type IN VARCHAR2, dest_location IN VARCHAR2, dest_name IN VARCHAR2)

Description

Exports embedded DICOM content to a specified destination. The data remains in the source BLOB when it is copied to the destination.

Parameters

dest_type

The type of the destination (only FILE is supported).

dest_location

The location of the destination (must be a valid Oracle directory object).

dest_name

The name of the destination file.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to export the embedded DICOM content to the local file system.

The export( ) method writes only to a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL statement CREATE DIRECTORY, or one to which you have been granted READ and WRITE access.

For example, the following SQL*Plus commands create a directory object and grant the user pm permission to read and write any file within the directory c:\mydir\work:

CONNECT sys as sysdba
Enter password: password
CREATE OR REPLACE DIRECTORY DICOMDIR AS 'c:\mydir\work';
GRANT READ,WRITE ON DIRECTORY DICOMDIR TO pm;

See Section 7.1 for more information about these directory and table definitions.

Examples

Export embedded DICOM content to a specified file:

declare
   obj orddicom;
 begin
   select dicom_src into obj from medical_image_obj where id = 1;
   obj.export('FILE', 'DICOMDIR', 'exported.dcm');
 end;
/

extractMetadata( )

Format

extractMetadata( extractOption IN VARCHAR2 DEFAULT 'ALL', docName IN VARCHAR2 DEFAULT 'ordcmmp.xml') RETURN SYS.XMLTYPE

Description

Returns the DICOM metadata as XML code for a specified mapping document. The default mapping document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0. The metadata attribute of the ORDDicom object is not affected.

Parameters

extractOption

A string that specifies the types of metadata to extract from the DICOM content. Valid values are: ALL, MAPPED, and STANDARD. The default is ALL.

When the value of this parameter is ALL, all the attributes in the embedded DICOM content are extracted. When the value is set to MAPPED, only mapped attributes are extracted. And, when the value is set to STANDARD, only attributes that conform to the DICOM standard and mapped attributes are extracted.

docName

The name of the mapping document. The default mapping document ordcmmp.xml is loaded during installation. This document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to retrieve metadata from the embedded DICOM content as XML code, and then store it in a database table for searching or viewing.

Use the preference parameter XML_SKIP_ATTR to specify size limits for DICOM attributes to be omitted when encoding into XML. See Section 10.2.6.8 for more information about this preference parameter.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against a specific XML schema that is registered with Oracle XML DB. See Section 10.2.6.7 for more information about this preference parameter.

Examples

Extract metadata from the embedded DICOM content:

 declare
   obj orddicom;
   metadata xmltype;
 begin
   select dicom_src into obj from medical_image_obj where id = 1;
 
   -- extract all the metadata using the default mapping document.
   metadata := obj.extractMetadata();
 
   -- extract the standard metadata using the default mapping document.
   metadata := obj.extractMetadata('standard');
 
   -- extract the standard metadata by specifying the mapping document.
   metadata := obj.extractMetadata('standard', 'ordcmmp.xml');
 end;
/

getAttributeByName( )

Format

getAttributeByName(attributeName IN VARCHAR2, definerName IN VARCHAR2 DEFAULT 'DICOM') RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the value of a DICOM attribute, as a VARCHAR2 string, for DICOM attributes other than SQ type attributes. For SQ type attributes, this method returns a segment of XML code, as a VARCHAR2 string. Use this method to get a single attribute from the embedded DICOM content.

Parameters

attributeName

The name of a specified attribute.

definerName

The name of the attribute definer. The default name is DICOM.

Pragmas

None.

Exceptions

None.

Usage Notes

See Section 3.2.4 for more information about the best methods to use for searching and retrieving DICOM attributes.

Examples

Return the name of a specified DICOM attribute:

 declare
   obj orddicom;
   res varchar2(4000);
 begin
   select dicom_src into obj from medical_image_obj where id = 1;
   obj.setProperties;
   
   -- Patient ID attribute, this will return patient ID value
   res := obj.getAttributeByName('Patient ID');
   dbms_output.put_line('Patient ID attribute: ' || res);
 
   -- attribute in SQ type, this will return an xml segment.
   res := obj.getAttributeByName('Source Image Sequence');
   dbms_output.put_line('Source Image Sequence attribute: ' || res);
 end ;
 /

getAttributeByTag( )

Format

getAttributeByTag(tag IN VARCHAR2, definerName IN VARCHAR2 DEFAULT 'DICOM') RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the value of a DICOM attribute, as a VARCHAR2 string, for DICOM attributes other than SQ type attributes. For SQ type attributes, this method returns a segment of XML code, as a VARCHAR2 string. Use this method to get a single attribute of the embedded DICOM content.

Parameters

tag

The code value used to specify a DICOM attribute or item tag, as a hexadecimal string.

definerName

The name of the attribute definer. The default name is DICOM.

Pragmas

None.

Exceptions

None.

Usage Notes

See Section 3.2.4 for more information about the best methods to use for searching and retrieving DICOM attributes.

Examples

Return the tag of a specified DICOM attribute:

 declare
   obj orddicom;
   res varchar2(4000);
 begin
   select dicom_src into obj from medical_image_obj where id = 1;
   obj.setProperties;
 
   -- Patient ID attribute, this will return patient ID value
   res := obj.getAttributeByTag('00100020');
   dbms_output.put_line('Patient ID attribute: ' || res);
 
   -- attribute in SQ type, this will return an xml segment.
   res := obj.getAttributeByTag('00082112');
   dbms_output.put_line('Source Image Sequence attribute: ' || res);
 end ;
 /

getContent( )

Format

getContent( ) RETURN BLOB DETERMINISTIC

Description

Returns the embedded DICOM content stored in the source attribute of the ORDDicom object. This method returns the BLOB handle, or a null value if the DICOM content has not been imported.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the content of the source attribute for the ORDDicom object:

   select t.dicom_src.getContent() from medical_image_obj t;

getContentLength( )

Format

getContentLength( ) RETURN INTEGER DETERMINISTIC PARALLEL_ENABLE

Description

Returns the length of the embedded DICOM content. This method returns the value of the contentLength attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the contentLength attribute for the ORDDicom object:

   select t.dicom_src.getContentLength() from medical_image_obj t;

getSeriesInstanceUID( )

Format

getSeriesInstanceUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE,

Description

Returns the value of the SERIES_INSTANCE_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the SERIES_INSTANCE_UID attribute for the ORDDicom object:

   select t.dicom_src.getSeriesInstanceUID() from medical_image_obj t;

getSOPClassUID( )

Format

getSOPClassUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE,

Description

Returns the value of the SOP_CLASS_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the SOP_CLASS_UID attribute for the ORDDicom object:

   select t.dicom_src.getSOPClassUID() from medical_image_obj t;

getSOPInstanceUID( )

Format

getSOPInstanceUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the value of the SOP_INSTANCE_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the SOP_INSTANCE_UID attribute for the ORDDicom object:

   select t.dicom_src.getSOPInstanceUID() from medical_image_obj t;

getSourceInformation( )

Format

getSourceInformation( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source information from the source attribute of the ORDDicom object as a URL in the form "source_type://source_location/source_name".

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source information for the ORDDicom object:

   select t.dicom_src.getSourceInformation() from medical_image_obj t;

getSourceLocation( )

Format

getSourceLocation( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source location from the source attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source location for the ORDDicom object:

   select t.dicom_src.getSourceLocation() from medical_image_obj t;

getSourceName( )

Format

getSourceName( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source name from the source attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source name for the ORDDicom object:

   select t.dicom_src.getSourceName() from medical_image_obj t;

getSourceType( )

Format

getSourceType( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source type from the source attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source type for the ORDDicom object:

   select t.dicom_src.getSourceType() from medical_image_obj t;

getStudyInstanceUID( )

Format

getStudyInstanceUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE,

Description

Returns the value of the STUDY_INSTANCE_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the STUDY_INSTANCE_UID attribute for the ORDDicom object:

   select t.dicom_src.getStudyInstanceUID() from medical_image_obj t;

import( )

Format

import(SELF IN OUT NOCOPY ORDDicom, setproperties IN INTEGER DEFAULT 1)

Description

Imports DICOM content from the current source. This method assumes that the source attributes have been set in the ORDDicom object by passing the source_type, source_location, and source_name parameters to the constructor.

Parameters

setproperties

Indicator flag that determines whether the DICOM attributes are extracted into the metadata attribute of the ORDDicom object. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 1.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method when the ORDDicom object is constructed from a source other than a BLOB, and must be imported into a BLOB.

The import( ) method reads only from a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL statement CREATE DIRECTORY, or one to which you have been granted READ access.

For example, the following SQL*Plus commands create a directory object and grant the user pm permission to read any file within the directory c:\mydir\work:

CONNECT sys as sysdba
Enter password: password
CREATE OR REPLACE DIRECTORY DICOMDIR AS 'c:\mydir\work';
GRANT READ ON DIRECTORY DICOMDIR TO pm;

Assuming that the DICOM object is inserted as follows:

insert into medical_image_obj (id, dicom_src) values 
 (1, ORDDicom('FILE', 'DICOMDIR', 'imported.dcm');

The user pm can import DICOM content from the imported.dcm file in this directory using the import( ) method of the ORDDicom object:

obj.import();

See Section 7.1 for more information about these directory and table definitions.

Examples

Import the DICOM attributes:

 declare
   obj orddicom;
 begin
   select dicom_src into obj from medical_image_obj where id = 1 for update;
   if (obj.isLocal() = 0) then
     obj.import();
   end if;
   update medical_image_obj set dicom_src = obj where id = 1;
 end;
/

isAnonymous( )

Format

isAnonymous(anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml') RETURN INTEGER

Description

Determines whether the embedded DICOM content is anonymous using a specified anonymity document, which is stored in the data model repository. This method returns a value of 1 if the data is anonymous; otherwise it returns a value of 0.

Parameters

anonymityDocName

The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method before calling the makeAnonymous( ) method to find out whether patient identifying information has been removed from the embedded DICOM content (see also the makeAnonymous( ) method).

Examples

Check if the embedded DICOM content is anonymous:

   select t.dicom_src.isAnonymous('ordcman.xml') from medical_image_obj t;

isConformanceValid( )

Format

isConformanceValid( constraintName IN VARCHAR2 ) RETURN INTEGER

Description

Performs a conformance validation check to determine whether the embedded DICOM content conforms to a specific set of constraints identified by the constraintName parameter. This method returns a value of 1 if conformance is valid; otherwise it returns a value of 0.

This method also logs error messages from the constraint documents, which can be viewed by querying the public view orddcm_conformance_vld_msgs. The public view orddcm_constraint_names contains the list of constraint names.

Parameters

constraintName

The name of the constraint to be used for conformance validation checking.

Pragmas

None.

Exceptions

None.

Usage Notes

If this method is called from a SQL query, ensure that the constraint rule definition does not contain any <ACTION> elements.

Use the preference parameter EXP_IF_NULL_ATTR_IN_CONSTRAINT to indicate whether to throw exceptions when encountering missing attributes or null attribute values during conformance validation. See Section 10.2.6.2 for more information about this preference parameter.

Examples

Check if the ORDDicom objects are conformance valid. Then, show any conformance validation messages that are generated.

   declare
     cursor dicom_src_cur is
      select dicom_src from medical_image_obj order by id;
   begin
      for rec in dicom_src_cur loop
        dbms_output.put_line('isConformanceValid(PatientModule): ' ||
          rec.dicom_src.isConformanceValid('PatientModule'));
      end loop;
   end;
   /

   select t1.id, t2.message, t2.msg_time time
    from medical_image_obj t1, orddcm_conformance_vld_msgs t2
     where t1.dicom_src.sop_instance_uid = t2.sop_instance_uid and
        t2.rule_name = 'PatientModule';

isLocal( )

Format

isLocal( ) RETURN INTEGER DETERMINISTIC PARALLEL_ENABLE

Description

Returns the local status of the source. If the DICOM content is stored in the source BLOB, the object is defined as local. If the DICOM content is stored externally in an operating system-specific file, the object is defined as not local. This method returns a value of 1 if the object is local; otherwise it returns a value of 0.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Check if the DICOM content is local:

   select t.dicom_src.isLocal() from medical_image_obj t;
 declare
   obj orddicom;
 begin
   select dicom_src into obj from medical_image_obj where id = 1 for update;
   if (obj.isLocal() = 0) then
     obj.import();
   end if;
   update medical_image_obj set dicom_src = obj where id = 1;
 end;
/

makeAnonymous( )

Format

makeAnonymous(SELF IN ORDDicom, dest_SOP_INSTANCE_UID IN VARCHAR2, dest IN OUT NOCOPY ORDDicom, anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')

Description

Removes patient identifying information from the ORDDicom object after copying it into another ORDDicom object, based on a specified anonymity document. Both the embedded DICOM content and the metadata attribute in the destination ORDDicom object are made anonymous.

Parameters

dest_SOP_INSTANCE_UID

The SOP instance UID of the destination ORDDicom object. It must ensure that the destination DICOM content is globally unique.

dest

An empty ORDDicom object in which to store the anonymous ORDDicom object.

anonymityDocName

The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to remove patient identifying information from the embedded DICOM content for use in data sharing and research.

Examples

Remove patient identifying information from the destination ORDDicom object:

Note:

Replace <unique-UID> with the UID that identifies the organization producing the DICOM content and the DICOM content within that organization.
 declare
   obj_src orddicom;
   obj_dest orddicom;
   dest_sop_instance_uid varchar2(128) := '<unique-UID>';
 begin
   select dicom_src, dicom_dest  into obj_src, obj_dest
   from medical_image_obj where id = 1 for update;
   obj_src.makeAnonymous(dest_sop_instance_uid, obj_dest, 'ordcman.xml');

   update medical_image_obj set dicom_dest = obj_dest where id = 1;
 end;
/

processCopy( ) to BLOBs

Format

processCopy(SELF IN ORDDicom, command IN VARCHAR2, dest IN OUT NOCOPY BLOB)

Description

Copies the ORDDicom object that is input into the destination BLOB, and then performs the specified processing operations on the destination BLOB. The original ORDDicom object that was input remains unchanged.

Parameters

command

A command string that accepts a processing operator as input. Valid values include: frame, contentFormat, fileFormat, compressionFormat, cut, scale, and rotate. See Appendix D for information about processing operators.

dest

The destination BLOB that contains the output of the process command on the ORDDicom object.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to process an ORDDicom object into a BLOB after copying it from the ORDDicom object. In this case, the output in the BLOB is image or video content.

See Appendix C for information about the encoding rules that support DICOM content processing. See Appendix D for more information about DICOM processing.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

Examples

Copy the DICOM content into a BLOB and then process it:

 declare
   obj orddicom;
   dest blob;
 begin
   select dicom_src, blob_dest into obj, dest 
   from medical_image_obj where id = 1 for update;
 
   obj.processCopy('fileFormat=jpeg maxScale=100 100', dest);
 end;
/

processCopy( ) to ORDDicom

Format

processCopy(SELF IN ORDDicom, command IN VARCHAR2, dest_SOP_INSTANCE_UID IN VARCHAR2, dest IN OUT NOCOPY ORDDicom, metadata IN SYS.XMLTYPE DEFAULT NULL)

Description

Copies the ORDDicom object that is input into a destination ORDDicom object, then performs the specified processing operations on the destination ORDDicom object and updates it with the new metadata. The original ORDDicom object that was input remains unchanged.

Parameters

command

A command string that accepts a processing operator as input. Valid values include: compressionFormat, frame, contentFormat, cut, scale, and rotate. See Appendix D for information about processing operators.

dest_SOP_INSTANCE_UID

The SOP instance UID of the destination ORDDicom object. It must ensure that the destination DICOM content is globally unique.

dest

An empty ORDDicom object in which to store the new DICOM content with the new metadata.

metadata

The new metadata to be written into the new DICOM content.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to process DICOM content into a destination ORDDicom object after copying it from the source ORDDicom object. In this case, the output is image or video content.

See Appendix C for information about the encoding rules that support DICOM content processing. See Appendix D for more information about DICOM processing.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

Examples

Copy the DICOM content into an ORDDicom object and then process it:

Note:

Replace <unique-UID> with the UID that identifies the organization producing the DICOM content and the DICOM content within that organization.
declare
   obj_src orddicom;
   obj_dest orddicom;
   dest_sop_instance_uid varchar2(128) := '<unique-UID>';
 begin
   select dicom_src, dicom_dest into obj_src, obj_dest
   from medical_image_obj where id = 1 for update;
   obj_src.processcopy('compressionFormat=jpeg',
                       dest_sop_instance_uid,
                       obj_dest);
 
   update medical_image_obj set dicom_dest = obj_dest where id = 1;
 end;
/

processCopy( ) to ORDImage

Format

processCopy(SELF IN ORDDicom, command IN VARCHAR2, dest IN OUT NOCOPY ORDImage)

Description

Copies the ORDDicom object that is input into the destination ORDImage object, and then performs the specified processing operations on the destination ORDImage object. The original ORDDicom object that was input remains unchanged.

Parameters

command

A command string that accepts an image processing operator as input. Valid values include: frame, contentFormat, fileFormat, compressionFormat, cut, scale, and rotate. See Appendix D for information about image processing operators.

dest

An empty ORDImage object in which to store the new, processed ORDImage object without the DICOM metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to get a non-DICOM image that is suitable for presentation on the Web from the embedded DICOM content.

See Appendix C for information about the encoding rules that support image content processing. See Appendix D for more information about DICOM processing.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

Examples

Copy the DICOM content into an ORDImage object and then process it:

 declare
   obj_src orddicom;
   obj_dest ordimage;
 begin
   select dicom_src, image_dest into obj_src, obj_dest
   from medical_image_obj where id = 1 for update;
   obj_src.processcopy('fileFormat=jpeg maxScale=100 100', obj_dest);
 
   update medical_image_obj set image_dest = obj_dest where id = 1;
 end;
/

setProperties( )

Format

setProperties(SELF IN OUT NOCOPY ORDDicom)

Description

Sets the attributes of the ORDDicom object. The attributes of the ORDDicom object are populated and the embedded DICOM content attributes are extracted into the metadata attribute of the ORDDicom object. The XML metadata conforms to the default metadata schema namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

If the repository contains a stored tag list document, the XML metadata contains only the DICOM attributes specified by the stored tag list. Otherwise, the XML metadata contains all the attributes from the embedded DICOM content.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to populate ORDDicom object attributes and to get the metadata from the embedded DICOM content.

Use the preference parameter XML_SKIP_ATTR to specify size limits for DICOM attributes to be omitted when encoding into XML. See Section 10.2.6.8 for more information about this preference parameter.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against a specific XML schema that is registered with Oracle XML DB. See Section 10.2.6.7 for more information about this preference parameter.

Examples

Set the attributes of the ORDDicom object:

 declare
   obj orddicom;
 begin
   select dicom_src into obj from medical_image_obj where id = 1 for update;
   obj.setProperties();
   update medical_image_obj set dicom_src = obj where id = 1;
 end;
/

writeMetadata( )

Format

writeMetadata(SELF IN ORDDicom, metadata IN SYS.XMLTYPE, dest IN OUT NOCOPY ORDDicom)

Description

Modifies the current ORDDicom object with the metadata provided by making a copy of the existing ORDDicom object in the destination ORDDicom object, and then modifying the metadata. The original ORDDicom object remains unchanged. The attributes in the embedded DICOM content of the destination ORDDicom object are copied from the metadata that was input.

Parameters

metadata

The input metadata stored in data type XMLType. In the destination ORDDicom object, the input metadata is used to update the values for attributes that are identical to attributes in the source ORDDicom object, or to add any new attributes. The metadata must conform to the default metadata schema with the namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0. The SOP instance UID in the metadata must ensure that the destination DICOM content is globally unique.

dest

An empty ORDDicom object in which to store the new embedded DICOM content with the new metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to update attributes in the embedded DICOM content.

In addition, you can use this method to add private attributes to the embedded DICOM content.

See Appendix C for information about the encoding rules that support metadata extraction.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

Use the preference parameter SQ_WRITE_LEN to specify how the DICOM sequence (SQ) types are encoded. See Section 10.2.6.6 for more information about this preference parameter.

Examples

Write the new metadata to the copy of the embedded DICOM content:

 declare
   obj_src orddicom;
   obj_dest orddicom;
   metadata xmltype;
 begin
   metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'),
                       nls_charset_id('AL32UTF8'),
                       'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
   select dicom_src, dicom_dest into obj_src, obj_dest
   from medical_image_obj where id = 1 for update;
 
   obj_src.writeMetadata(metadata, obj_dest);
 
   update medical_image_obj set dicom_dest = obj_dest where id = 1;
 
 end;
/