The IDLffDicomExQuery::Query function method is used to query a remote Query/Retrieve SCP Application Entity. A query message is constructed using the appropriate query field properties for the specified query model and query level; the query message is sent to the remote node, which sends a reply for each match. See Defining a Machine to Be Queried for an overview of this process.

This method does not return to the caller until one of the following occurs:

• The query is complete (all matches have been returned)
• The number of responses defined by the MaxQueryResponses configuration parameter is reached
• The query encounters an error condition
• The callback function defined by the CALLBACK_FUNCTION property returns zero

Properties Required by a Query

The QUERY_SCP property must contain the name of a valid Application Entity that supports the Query SCP service in order for the Query method to succeed. All other properties used by the Query method have usable default values. If no properties other than QUERY_SCP are set, this method will perform a Patient Root / Patient Level query listing all patients on the remote node.

Properties Allowed by a Query

The query field properties that are used in a specific DICOM query are defined by the query model and query level chosen. For example, in a Patient Root / Patient Level query, only the values of the Patient_Name and Patient_ID properties are sent to the remote node; all other query field properties are ignored.

See IDLffDicomExQuery Properties for a complete list of properties used to define a query or that affect the operation of the Query method.

See Attribute Matching and Wildcards for a discussion of how to perform queries using wildcard values for query properties.

See Query Property Interactions With Query Model/Level for a complete list of the interactions between query properties and the selected query model and level.

Callbacks and Query Status Information

If the CALLBACK_FUNCTION property contains the name of an IDL function, that function is called each time the remote node returns a match. The function is called with an array of strings containing status information about the query as its first parameter. See Using Callbacks with the IDLffDicomExQuery Object for a discussion of callback functions.

Canceling a Query

To cancel a query before all matches are returned or the value of the MaxQueryResponses configuration parameter is reached, the callback function specified by the CALLBACK_FUNCTION property must return zero.

Syntax

Result = Obj->[IDLffDicomExQuery::]Query( [, COUNT=variable] )

Return Value

This method returns an array of IDLFFDICOMEXQRESULTS structures containing the information returned by the query, one structure per matched item. The maximum number of structures in the array is defined by the MaxQueryResponses configuration parameter.

Note: The COUNT keyword returns the number of items that match the query. Always check the number of matches before attempting to reference an element in the returned array.

The IDLFFDICOMEXQRESULTS structure is described below. With two exceptions, each field in the structure corresponds to a property of the IDLffDicomExQuery object. See the description of the property in IDLffDicomExQuery Properties for information about the range of possible values returned.

The STUDY_DESCRIPTION and SERIES_DESCRIPTION fields do not correspond to query field properties. For selected queries, these fields will contain string values describing the study or series, if the descriptions are available.

Note that a field in an IDLFFDICOMEXQRESULTS structure can contain an empty string if either of the following is true:

• No value for the field is returned by a particular combination of query model and query level. See Query Property Interactions With Query Model/Level for a discussion the fields for which values are returned for a given combination of query model and query level.
• The actual value of the field is an empty string.

The IDLFFDICOMEXQRESULTS structure has the following fields:

QUERY_MODEL (integer)

QUERY_LEVEL (integer)

PATIENT_NAME (string)

FAMILY_NAME (string)

GIVEN_NAME (string)

MIDDLE_NAME (string)

PREFIX (string)

SUFFIX (string)

PATIENT_ID (string)

STUDY_INSTANCE_UID (string)

STUDY_ID (string)

STUDY_DATE (string)

STUDY_TIME (string)

ACCESSION_NUMBER (string)

SERIES_INSTANCE_UID (string)

SERIES_NUMBER (string)

MODALITY (string)

SOP_INSTANCE_UID (string)

INSTANCE_NUMBER (string)

STUDY_DESCRIPTION (string)

SERIES_DESCRIPTION (string)

Note on Missing UIDS

If a query returns values for a field that is supposed to contain a unique identifier but does not, this method substitutes one of the following strings in the corresponding field of the returned structure:

Unknown Patient Id

Unknown Study UID

Unknown Series UID

Unknown Image UID

Arguments

None

Keywords

COUNT

Set this keyword equal to a named variable that will contain a long integer representing the number of IDLFFDICOMEXQRESULTS structures returned by the query. If no matches are found, the variable specified by COUNT will contain zero.

Example

The following example code shows how to programmatically configure a Query/Retrieve SCP Application Entity and perform a query.

Note: In order to run this code, you must supply values for the REMOTE_AET, REMOTE_HOST, and REMOTE_PORT variables.

To run the example, do the following:

1. Copy the example code and paste it into an IDL editor window or another text editor of your choice.
2. Edit the text to supply the values for the three required variables.
3. Save the file as query_patient_root_patient_level.pro.
4. Execute query_patient_root_patient_level.pro in IDL.

PRO query_patient_root_patient_level

; NOTE:

; To run this example on your own system, define the following

; variables to be valid remote query/retrieve SCP node values.

REMOTE_AET = 'remote_aet'

REMOTE_HOST = 'remote_host_name'

REMOTE_PORT = 'remote_port_number'

; Update the local user configuration file.

; First create a new local user configuration object.

ocfg = OBJ_NEW('IDLffDicomExCfg')

; Add the Remote Query/Retrieve SCP Application Entity.

ocfg->SetApplicationEntity, 'remote_qr_scp_aen', $

   REMOTE_AET, REMOTE_HOST, REMOTE_PORT, $

   'Query_SCP_Service_List', 'Query_SCP'

; Save the changes to the configuration file.

ocfg->Commit

; Destroy the configuration file object.

OBJ_DESTROY, ocfg

; Perform a patient root, patient level query against 

; the remote node. First define a new Query/Retrieve SCU object.

oqr  = OBJ_NEW('IDLffDicomExQuery')

; Specify the remote node to query.

oqr->SetProperty, QUERY_SCP = 'remote_qr_scp_aen'

; Run the query.

xResults = oqr->Query(COUNT=cnt)

; Print out the query results.

FOR i=0, cnt-1 DO BEGIN

   PRINT, 'i = ', i, '  patient_id = ',  $

      xResults[i].patient_id, '     patient_name = ', $

      xResults[i].patient_name

ENDFOR

; Destroy the Query/Retrieve SCU object.

OBJ_DESTROY, oqr

END

Version History