Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  IDL Reference  >  DICOM Toolkit  >  IDLffDicomExQuery Properties

IDLffDicomExQuery Properties

IDLffDicomExQuery Properties 

IDLffDicomExQuery objects have the following properties. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLffDicomExQuery::GetProperty. Properties with the word “Yes” in the “Init” column of the property table can be set via IDLffDicomExQuery::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLffDicomExQuery::SetProperty.

Note: For a discussion of the property description tables shown below, see About Object Property Descriptions. Tables for properties of this object do not include the DICOM Attribute or Multi-value fields.

There are two categories of properties for this object: general properties and query field properties.

  • General properties are used to specify information about the process of querying for or retrieving data: the name of the Query SCP or the level at which the query is performed, for example.
  • Query field properties are used to narrow the number of matches returned by a query: patient names and instance numbers are examples. Values of query fields can include wildcard characters: see Attribute Matching and Wildcards for details.

Note: Depending on the implementation of the remote node being queried, query field property values may be case sensitive.

The IDLffDicomExQuery object has the following properties:

ACCESSION_NUMBER

CALLBACK_DATA

CALLBACK_FUNCTION

FAMILY_NAME

GIVEN_NAME

INSTANCE_NUMBER

MIDDLE_NAME

MODALITY

PATIENT_ID

PATIENT_NAME

PREFIX

QUERY_LEVEL

QUERY_MODEL

QUERY_SCP

SERIES_INSTANCE_UID

SERIES_NUMBER

SOP_INSTANCE_UID

STORAGE_SCP

STUDY_DATE

STUDY_ID

STUDY_INSTANCE_UID

STUDY_TIME

SUFFIX

 

ACCESSION_NUMBER

This query field property represents the Accession Number attribute (0008,0050). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:SH

Get: Yes

Set: Yes

Init: No

Registered: No

CALLBACK_DATA

This general property contains data that is to be passed to the function defined by the CALLBACK_FUNCTION property when a callback is initiated. If this property is not set, the integer value zero is passed to the callback function. See Using Callbacks with the IDLffDicomExQuery Object for additional details.

This property is used by the IDLffDicomExQuery::Query and IDLffDicomExQuery::Retrieve methods.

Property Type

Any type

Name String

not displayed

VR: not applicable

Get: Yes

Set: Yes

Init: No

Registered: No

CALLBACK_FUNCTION

This general property contains the name of an IDL function to be called by the Query and Retrieve methods. If no value is defined, no callback is initiated. See Using Callbacks with the IDLffDicomExQuery Object for additional details.

This property is used by the IDLffDicomExQuery::Query and IDLffDicomExQuery::Retrieve methods.

Property Type

String

Name String

not displayed

VR: not applicable

Get: Yes

Set: Yes

Init: No

Registered: No

FAMILY_NAME

This query field property represents the family name (last name) associated with a patient record.

Note: The Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties are combined to populate the DICOM Patient Name attribute (0010,0010). If the Patient_Name property is set, this property is ignored.

If a query uses the PATIENT_NAME property but no value is specified for either the Patient_Name property or this property, the query is issued with Family_Name set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:PN

Get: Yes

Set: Yes

Init: No

Registered: No

GIVEN_NAME

This query field property represents the given name (first name) associated with a patient record.

Note: The Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties are combined to populate the DICOM Patient Name attribute (0010,0010). If the Patient_Name property is set, this property is ignored.

If a query uses the PATIENT_NAME property but no value is specified for either the Patient_Name property or this property, the query is issued with Given_Name set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:PN

Get: Yes

Set: Yes

Init: No

Registered: No

INSTANCE_NUMBER

This query field property represents the Instance Number attribute (0020,0013). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:IS

Get: Yes

Set: Yes

Init: No

Registered: No

MIDDLE_NAME

This query field property represents the middle name associated with a patient record.

Note: The Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties are combined to populate the DICOM Patient Name attribute (0010,0010). If the Patient_Name property is set, this property is ignored.

If a query uses the PATIENT_NAME property but no value is specified for either the Patient_Name property or this property, the query is issued with Middle_Name set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:PN

Get: Yes

Set: Yes

Init: No

Registered: No

MODALITY

This query field property represents the Modality attribute (0008,0060). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:CS

Get: Yes

Set: Yes

Init: No

Registered: No

PATIENT_ID

This query field property represents the Patient ID attribute (0010,0020). If this property is not set and the query level is “patient” or “study,” the query is issued with this property set to “*”. If this property is not set and the query level is “series” or “image,” the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:LO

Get: Yes

Set: Yes

Init: No

Registered: No

PATIENT_NAME

This query field property represents the Patient ID attribute (0010,0010).

Note: The Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties are combined to populate the DICOM Patient Name attribute (0010,0010). If the Patient_Name property is set, all the other name properties are ignored.

The Patient_Name property string comprises the five name sub-properties, separated by the “^” character:

Family Name^Given Name^Middle Name^Prefix^Suffix

If any of the sub-properties are omitted, you must substitute an empty string in the correct location. For example, to specify a Patient_Name without a middle name:

Family Name^Given Name^^Prefix^Suffix

See PN for details.

If a query uses this query field but no value is specified for this property, IDL constructs the value of the Patient_Name property from the values of the Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:PN

Get: Yes

Set: Yes

Init: No

Registered: No

PREFIX

This query field property represents the title (or honorific) associated with a patient record.

Note: The Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties are combined to populate the DICOM Patient Name attribute (0010,0010). If the Patient_Name property is set, this property is ignored.

If a query uses the PATIENT_NAME property but no value is specified for either the Patient_Name property or this property, the query is issued with Prefix set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:PN

Get: Yes

Set: Yes

Init: No

Registered: No

QUERY_LEVEL

This general property sets the query level to be used in a query. Valid values are:

Value

Query Level

0

Patient

1

Study

2

Series

3

Image

Note: The default value of zero is not a valid value if the QUERY_MODEL property is set equal to one. Attempting to set QUERY_LEVEL=0 and QUERY_MODEL=1 will generate a warning message, and QUERY_LEVEL will automatically be set equal to one.

Because the default value for QUERY_LEVEL is zero, you should set the value of this property before setting the value of QUERY_MODEL to avoid receiving the error message.

This property is used by the IDLffDicomExQuery::Query and IDLffDicomExQuery::Retrieve methods.

Property Type

Integer

Name String

not displayed

VR: not applicable

Get: Yes

Set: Yes

Init: No

Registered: No

QUERY_MODEL

This general property sets the query model to be used in a query. Valid values are:

Value

Query Model

0

Patient Root

1

Study Root

2

Patient Study Only

If this property is not set, the query is issued with this property set to zero (Patient Root).

Note: Attempting to set QUERY_LEVEL=0 and QUERY_MODEL=1 will generate a warning message, and QUERY_LEVEL will automatically be set equal to one.

This property is used by the IDLffDicomExQuery::Query and IDLffDicomExQuery::Retrieve methods.

Property Type

Integer

Name String

not displayed

VR: not applicable

Get: Yes

Set: Yes

Init: No

Registered: No

QUERY_SCP

This general property specifies the Application Entity name of the node to be queried. The Application Entity name must be defined in the DICOM Network Services configuration file.

Note: This property must be set prior to calling the Query or Retrieve methods.

This property is used by the IDLffDicomExQuery::Query, IDLffDicomExQuery::QueryModelsSupported, and IDLffDicomExQuery::Retrieve methods.

Property Type

String

Name String

not displayed

VR: not applicable

Get: Yes

Set: Yes

Init: No

Registered: No

SERIES_INSTANCE_UID

This query field property represents the Series Instance UID attribute (0020,000E). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:UI

Get: Yes

Set: Yes

Init: No

Registered: No

SERIES_NUMBER

This query field property represents the Series Number attribute (0020,0011). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:IS

Get: Yes

Set: Yes

Init: No

Registered: No

SOP_INSTANCE_UID

This query field property represents the SOP Instance UID attribute (0008,0018). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:UI

Get: Yes

Set: Yes

Init: No

Registered: No

STORAGE_SCP

This general property specifies the Application Entity name of the Storage SCP node that receives retrieved files. The Application Entity name must be defined in the DICOM Network Services configuration file.

Note: This property must be set prior to calling the Retrieve method.

This property is used by the IDLffDicomExQuery::Retrieve method.

Property Type

String

Name String

not displayed

VR: not applicable

Get: Yes

Set: Yes

Init: No

Registered: No

STUDY_DATE

This query field property represents the Study Date attribute (0008,0020). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:DA

Get: Yes

Set: Yes

Init: No

Registered: No

STUDY_ID

This query field property represents the Study ID attribute (0020,0010). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:SH

Get: Yes

Set: Yes

Init: No

Registered: No

STUDY_INSTANCE_UID

This query field property represents the Study Instance UID attribute (0020,000D). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:UI

Get: Yes

Set: Yes

Init: No

Registered: No

STUDY_TIME

This query field property represents the Study Time attribute (0008,0030). If this property is not set, the query is issued with this property set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:TM

Get: Yes

Set: Yes

Init: No

Registered: No

SUFFIX

This query field property represents the name suffix (Jr. or Sr., for example) associated with a patient record.

Note: The Family_Name, Given_Name, Middle_Name, Prefix, and Suffix properties are combined to populate the DICOM Patient Name attribute (0010,0010). If the Patient_Name property is set, this property is ignored.

If a query uses the PATIENT_NAME property but no value is specified for either the Patient_Name property or this property, the query is issued with Suffix set to an empty string.

This property is used by the IDLffDicomExQuery::Query method. See Query Property Interactions With Query Model/Level to determine when this property can be used in a specific query.

Property Type

String

Name String

not displayed

VR:PN

Get: Yes

Set: Yes

Init: No

Registered: No

Attribute Matching and Wildcards


The implementation of the Query/Retrieve SCP service on the remote node determines the quality of attribute matching. All attribute matching is performed by the remote service. In addition to case sensitivity, matching can include one or more of the following:

Matching

Description

Single Value

Matches single values.

Wildcard

Use * to match zero or more characters.

Use ? to match any single character.

For example, to return patients with a name beginning with HA, use HA*. To return a list of patients whose names vary by one or more instances of a single value, use the ? character to indicate the wildcard value as in M?NROE.

Range

Use the - character in between date or time values to return any matches within that range. For example, to match any date in the first six months of the year, use 20050101-20050630.

UID List

Matches a list of UIDs separated by \ character.

The following table indicates the value representation (VR) and what wildcards are supported in each query field. An "x" in the column indicates the wildcard is supported.

Field

VR

*

?

-

/

Patient Name

PN

x

x

 

 

Family Name

PN

x

x

 

 

Given Name

PN

x

x

 

 

Middle Name

PN

x

x

 

 

Prefix

PN

x

x

 

 

Suffix

PN

x

x

 

 

Patient ID

LO

x

x

 

 

Study Instance UID

UI

 

 

 

x

Study ID

SH

x

x

 

 

Study Date

DA

 

 

x

 

Study Time

TM

 

 

x

 

Accession Number

SH

x

x

 

 

Series Instance UID

UI

 

 

 

x

Series Number

IS

 

 

 

 

Modality

CS

 

 

 

 

SOP Instance UID

UI

 

 

 

x

Instance Number

IS

 

 

 

 

Query Property Interactions With Query Model/Level


The following table defines which query properties apply to different combinations of query model and query level. An "x" in the column indicates that the property is used in a query with the specified combination of query model and query level.

An "x" in the column also indicates that the corresponding field in the IDLFFDICOMEXQRESULTS structure returned by the IDLffDicomExQuery::Query method will contain a meaningful result value. If the table indicates that the field contains a meaningful value but the result is a null value, this means that the query returned a null value for that field.

 

PATIENT_NAME

PATIENT_ID

STUDY_INSTANCE_UID

STUDY_ID

STUDY_DATE

STUDY_TIME

ACCESSION_NUMBER

SERIES_INSTANCE_UID

SERIES_NUMBER

MODALITY

SOP_INSTANCE_UID

INSTANCE_NUMBER

Study Description *

Series Description *

Patient Root /
Patient Level

x

x

 

 

 

 

 

 

 

 

 

 

 

 

Patient Root /
Study Level

 

x

x

x

x

x

x

 

 

 

 

 

x

 

Patient Root /
Series Level

 

x

x

 

 

 

 

x

x

x

 

 

x

x

Patient Root /
Image Level

 

x

x

 

 

 

 

x

 

 

x

x

x

x

Study Root /
Study Level

x

x

x

x

x

x

x

 

 

 

 

 

x

 

Study Root /
Series Level

x

x

x

 

 

 

 

x

x

x

 

 

x

x

Study Root /
Image Level

x

x

x

 

 

 

 

x

 

 

x

x

x

x

Patient Study Only Root

x

x

x

x

x

x

x

 

 

 

 

 

x

 

* These structure fields cannot be used to narrow the query results, but they are included in the returned structure.

Patient Name and Name Sub-field Properties


The DICOM standard defines a Patient Name as being made up of five sub-fields:

For each of these sub-fields of the Patient Name, the IDLffDicomExQuery object has an associated property. When creating a query that uses the PATIENT_NAME property, you can specify either the value of the Patient_Name property or the values of one or more of the five sub-properties.

  • If you provide a value for the Patient_Name property, the values of the sub-properties are ignored.
  • If you do not provide a value for the Patient_Name property, the values of any of the sub-properties that are set are used to generate a value for the Patient_Name property.

Using Callbacks with the IDLffDicomExQuery Object


Callbacks from the IDLffDicomExQuery object provide a way to transmit information back to the caller based on the status of a query or retrieve operation. The value returned by the callback function is then used by the IDLffDicomExQuery object to determine whether the query or retrieve operation should continue.

The IDLffDicomExQuery object allows you to define a single function (written in IDL) that will be called based on the intermediate status of a Query or Retrieve method call. If a callback function is specified via the CALLBACK_FUNCTION property, it is called in the following circumstances:

  • For the IDLffDicomExQuery::Query method, the callback function is called each time a match is returned by the source node.
  • For the IDLffDicomExQuery::Retrieve method:
  • If the source node (the remote Query/Retrieve SCP) implements the optional response mechanism, the callback function is called each time a DICOM file is moved from the source node to the destination node.
  • If the source node (the remote Query/Retrieve SCP) does not implement the optional response mechanism, the callback function is called every 3 seconds.

Both methods invoke the callback function with an array of strings indicating status as the first parameter, and with the value (if any) specified by the CALLBACK_DATA property as the second parameter.

If the return value of the callback function is zero, a cancel message will be sent to the remote node. If the return value is one, the query or retrieve operation will continue.

Callback Routine Signature

A query/retrieve callback function is written in IDL and has the following signature:

Function Callback_Function_Name, StatusInfo, CallbackData

where

  • Callback_Function_Name is the name of the callback function. This value is specified as the value of the CALLBACK_FUNCTION property.
  • StatusInfo is an array of strings that contain status information about the query or retrieve operation. The status strings are provided for information and human inspection rather than for programmatic processing; the exact strings included in the array will depend on numerous factors including the status of the query or retrieve and the type of node being queried or retrieved from.
  • CallbackData is the data specified via the CALLBACK_DATA property. The value of this property is passed to the callback function unmodified. If the CALLBACK_DATA property is unspecified, an integer zero is passed to the callback function as the value of this parameter.
  • The CallbackData parameter is useful for passing static information, such as the widget ID of a widget where the status information is displayed, from the IDLffDicomExQuery object to the callback routine.

The return value of the callback function should be an integer zero or one. If the return value is zero, a cancel message will be sent to the remote node. If the return value is one, the query or retrieve operation will continue.



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us