IDLffDicomExQuery::Retrieve

The IDLffDicomExQuery::Retrieve function method moves a DICOM file or files from a source node to a destination node. The source node is the remote Query/Retrieve SCP Application Entity that is queried. The destination node is a local or remote Storage SCP Application Entity. To accomplish the retrieval, the local Query/Retrieve SCU issues a move request to the remote Query/Retrieve SCP, which moves the file to the destination node.

Note
In DICOM terminology, the process of transferring data from a Query/Retrieve SCP to a Storage SCP is called a move. Note, however, that this process actually places a copy of the data on the destination node, leaving the original data intact.

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

The retrieve is complete (all matches have been returned)

The retrieve encounters an error condition

The callback function defined by the CALLBACK_FUNCTION property returns zero

Properties Required by a Retrieve

The following properties must be defined in order for the Retrieve method to succeed:

The QUERY_SCP property must contain the name of a valid Query/Retrieve SCP node.

The STORAGE_SCP property must contain the name of a valid Storage SCP node.

All other properties used by the Retrieve method have usable default values. If no properties other than QUERY_SCP and STORAGE_SCP are set, this method will perform a Patient Root / Patient Level retrieve, retrieving all patients on the remote node.

Retrieval Specification

Specify which files to retrieve using the PATIENT_ID, STUDY_INSTANCE_UID, SERIES_INSTANCE_UID, and SOP_INSTANCE_UID keywords.

Note
Query field properties are not used by the Retrieve method to specify which files should be retrieved.

If you specify a Patient ID, all of the DICOM files or images associated with the specified patient are retrieved.

If you specify a Study Instance UID, only DICOM files or images associated with the specified study and its associated series are retrieved.

If you specify a Series Instance UID, only DICOM files or images associated with the specified series are retrieved.

If you specify an SOP Instance UID, a single DICOM file or image is retrieved.

Callbacks and Retrieval Status Information

If the CALLBACK_FUNCTION property contains the name of an IDL function, that function is called in the following circumstances:

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.

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 Retrieve

To cancel a retrieve before all matches are returned, the callback function specified by the CALLBACK_FUNCTION property must return zero.

Syntax

Result = Obj->[IDLffDicomExQuery::]Retrieve( [, COUNT=variable] [, PATIENT_ID=string] [, STUDY_INSTANCE_UID=string] [, SERIES_INSTANCE_UID=string] [, SOP_INSTANCE_UID=string] )

Return Value

This method returns one (success) if the retrieval operation completes successfully or if the retrieval is cancelled based on the return value of the callback function. This method returns zero (failure) if the retrieve does not complete because an error is encountered.

Arguments

None

Keywords

COUNT

Set this keyword equal to a named variable that will contain an integer representing the number of files successfully retrieved as reported by the remote Query SCP node.

PATIENT_ID

Set this keyword equal to a scalar string containing the value of the Patient ID attribute (0010,0020) for the DICOM files to be retrieved.

The combination of query model and query level determine whether this keyword is required. See Unique ID Keyword Interactions With Query Model/Level for details.

STUDY_INSTANCE_UID

Set this keyword equal to a scalar string containing the value of the Study Instance UID attribute (0020,000D) for the DICOM files to be retrieved.

The combination of query model and query level determine whether this keyword is required. See Unique ID Keyword Interactions With Query Model/Level for details.

SERIES_INSTANCE_UID

Set this keyword equal to a scalar string containing the value of the Series Instance UID attribute (0020,000E) for the DICOM files to be retrieved.

The combination of query model and query level determine whether this keyword is required. See Unique ID Keyword Interactions With Query Model/Level for details.

SOP_INSTANCE_UID

Set this keyword equal to a scalar string containing the value of the SOP Instance UID attribute (0008,0018) for the DICOM files to be retrieved.

The combination of query model and query level determine whether this keyword is required. See Unique ID Keyword Interactions With Query Model/Level for details.

Unique ID Keyword Interactions With Query Model/Level

Table 3-29 defines which unique ID keywords are required for different combinations of query model and query level. A "•" in the column indicates that the keyword is required when retrieving files using the specified combination of QUERY_MODEL and QUERY_LEVEL properties.

Table 3-29: Query Model/Level vs. Unique ID Keyword Usage
	Patient_ID	Study_Instance_UID	Series_Instance_UID	SOP_Instance_UID
Patient Root / Patient Level	•
Patient Root / Study Level	•	•
Patient Root / Series Level	•	•	•
Patient Root / Image Level	•	•	•	•
Study Root / Study Level		•
Study Root / Series Level		•	•
Study Root / Image Level		•	•	•
Patient Study Only Root	•	•

Example

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

Note
In order to run this code, you must supply values for the REMOTE_AET, REMOTE_HOST, REMOTE_PORT, and PATIENT_ID variables. You must also have a local storage SCP configured on a remote query/retrieve SCP node.

To run the example, do the following:

Copy the example code and paste it into an IDL editor window or another text editor of your choice.

Edit the text to supply the values for the four required variables.

Save the file as retrieve_dicom_patient_files.pro.

Execute retrieve_dicom_patient_files.pro in IDL.

PRO retrieve_dicom_patient_files 
 
; NOTE: 
; To run this example on your own system, define the following 
; variables to be valid and existing remote query/retrieve SCP 
; node values. 
REMOTE_AET = 'remote_aet' 
REMOTE_HOST = 'remote_host_name' 
REMOTE_PORT = 'remote_port_number' 
; In addition, define the following variable to contain 
; a numeric Patient ID number for a patient known to exist 
; on the remote server. 
PATIENT_ID = 000001 
 
; Update the local user configuration file. 
; Note that in a production application, you would probably 
; not need to update the configuration file each time the 
; application runs. 
; 
; 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' 
 
; Retrieve the value of the current Storage SCP Application 
; Entity. We will use this later to restore the original value. 
origStorScpAEname = ocfg->GetValue('StorScpServiceAE') 
origStorScpAE = ocfg->GetApplicationEntity(origStorScpAEname) 
 
; Add the local IDL Storage SCP Application Entity to the 
; local configuration file. Note that 'my_stor_scp' must be 
; configured on the remote query/retrieve SCP node. 
ocfg->SetApplicationEntity, 'my_stor_scp_aen', $ 
   'my_stor_scp', 'localhost', 2510, $ 
   'Storage_SCP_Service_List', 'Storage_SCP' 
ocfg->SetValue, 'StorScpServiceAE', 'my_stor_scp_aen' 
 
; Save the changes to the configuration file. 
ocfg->Commit 
 
; Destroy the configuration file object. 
OBJ_DESTROY, ocfg 
 
; Update the system configuration file. 
; Note that in a production application, you would probably 
; not need to update the configuration file each time the 
; application runs. 
; 
; First create a new system configuration object. 
ocfg = OBJ_NEW('IDLffDicomExCfg', /SYSTEM) 
 
; Stop the Storage SCP Service before making changes. 
status = ocfg->StorageScpService('stop') 
PRINT, 'Stopping Storage SCP. Status: ', status 
WAIT, 5 
 
 
; Add the Storage SCP Application Entity to the system 
; configuration file. Note that 'my_stor_scp' must be 
; configured on the remote query/retrieve SCP node. 
ocfg->SetApplicationEntity, 'my_stor_scp_aen', $ 
   'my_stor_scp', 'localhost', 2510, $ 
   'Storage_SCP_Service_List', 'Storage_SCP' 
ocfg->SetValue, 'StorScpServiceAE', 'my_stor_scp_aen' 
 
; Retrieve the original value of the Storage SCP directory. 
origStorScpDir = ocfg->GetValue('StorScpDir') 
 
; Set the Storage SCP directory to the temporary directory. 
tmpDir = FILEPATH('', /TMP) 
ocfg->SetValue, 'StorScpDir', tmpDir 
storScpDir = ocfg->GetValue('StorScpDir') 
PRINT, 'Setting Storage SCP Directory to: ', storScpDir 
 
; Save the changes to the configuration file. 
ocfg->Commit 
 
; Restart the Storage SCP Service. 
status = ocfg->StorageScpService('start') 
PRINT, 'Starting Storage SCP. Status: ', status 
WAIT, 5 
status = ocfg->StorageScpService('status') 
PRINT, 'Storage SCP Status: ', status 
WAIT, 5 
 
; Destroy the configuration file object. 
OBJ_DESTROY, ocfg 
 
; Retrieve all patient files for the patient from 
; the remote node. 
; First, create a new Query/Retrieve SCU object. 
oqr  = OBJ_NEW('IDLffDicomExQuery') 
 
; Specify the node to be queried. 
oqr->SetProperty, QUERY_SCP = 'remote_qr_scp_aen' 
 
; Specify the node to which files will be retrieved. 
oqr->SetProperty, STORAGE_SCP = 'my_stor_scp_aen' 
 
; Retrieve the files 
res = oqr->Retrieve(PATIENT_ID=PATIENT_ID, COUNT=cnt ) 
 
PRINT, 'Retrieve Status: ', cnt, ' files retrieved into ', 
storScpDir 
 
 
; Destory the Query/Retrieve SCU object. 
OBJ_DESTROY, oqr 
 
; Restore the Storage SCP Application Entity to its  
; original state. 
; 
PRINT, '' 
PRINT, 'Restoring original Storage SCP configuration.' 
 
; Get a new local user configuration object. 
ocfg = OBJ_NEW('IDLffDicomExCfg') 
 
; Replace the orginal Storage SCP Application Entity. 
ocfg->SetApplicationEntity, origStorScpAE.APPLENTITYNAME, $ 
   origStorScpAE.AET, origStorScpAE.HOSTNAME, $ 
   origStorScpAE.PORT, origStorScpAE.SERVICELISTNAME, $ 
   origStorScpAE.SERVICETYPE 
 
ocfg->SetValue, 'StorScpServiceAE', origStorScpAE.APPLENTITYNAME 
 
; Save the changes to the configuration file. 
ocfg->Commit 
 
; Destroy the local configuration file object. 
OBJ_DESTROY, ocfg 
 
 
; Get a new System configuration object. 
ocfg = OBJ_NEW('IDLffDicomExCfg', /SYSTEM) 
 
; Stop the Storage SCP Service before making changes 
; to the system configuration. 
status = ocfg->StorageScpService('stop') 
PRINT, 'Stopping Storage SCP. Status: ', status 
WAIT, 5 
 
; Replace the orginal Storage SCP Application Entity. 
ocfg->SetApplicationEntity, origStorScpAE.APPLENTITYNAME, $ 
   origStorScpAE.AET, origStorScpAE.HOSTNAME, $ 
   origStorScpAE.PORT, origStorScpAE.SERVICELISTNAME, $ 
   origStorScpAE.SERVICETYPE 
 
ocfg->SetValue, 'StorScpServiceAE', origStorScpAE.APPLENTITYNAME 
 
; Restore the Storage SCP directory. 
ocfg->SetValue, 'StorScpDir', origStorScpDir 
PRINT, 'Storage SCP Directory is now ', $ 
   ocfg->GetValue('StorScpDir') 
 
; Restart the Storage SCP Service. 
status = ocfg->StorageScpService('start') 
PRINT, 'Starting Storage SCP. Status: ', status 
WAIT, 5 
status = ocfg->StorageScpService('status') 
PRINT, 'Storage SCP Status: ', status 
WAIT, 5 
 
; Save the changes to the configuration file. 
ocfg->Commit 
 
; Destroy the configuration file object. 
OBJ_DESTROY, ocfg 
 
END

Version History


6.3	Introduced