The IDLffDicomEx::QueryPrivateValue function method checks a DICOM file for the presence of a specified private attribute. This method allows you to verify the presence of a tag prior to calling a method that requires a DICOM attribute to be present in order to succeed. Attempting to call GetPrivateValue, GetPrivateValueCount, GetPrivateValueLength, and GetPrivateVR methods all return an error when you attempt to access an attribute that does not exist in a DICOM file. GetPrivateValue also fails when attempting to access an attribute that does not have a value.

Syntax

Result = Obj->[IDLffDicomEx::]QueryPrivateValue(PrivateCode, Group, Element [, SEQID=integer] )

Return Value

  • 0 = tag not found
  • 1 = tag found but does not have a value
  • 2 = tag found and has a value

A return value of 0 or 1 indicates attempting to call GetPrivateValue would cause an error. A return value of 2 means GetPrivateValue would succeed for the specified attribute.

Arguments

PrivateCode

A string identification code that identifies the private block of data. Within a given private group PrivateCode labels are stored sequentially in the element addresses ranging from '0010' to '00FF'. For example, the string value stored at DICOM tag address '0029,0010' is the PrivateCode for the block of data tagged at '0029,1000' ‑ '0029,10FF'. The label stored at '0029,0011' would be the PrivateCode for the data in tags '0029,1100' - '0029,11 FF'.

Group

A string identifying the group tag number of the private attribute (the first four digits of a DICOM tag). This must be an odd number and in the form 'XXXX'.

Element

A string identifying the last two digits of the element associated with the private attribute. This must be in the form 'XX'. Valid values are 10 - FF.

The first two digits of the Element are implicit in the PrivateCode argument.

Keywords

SEQID

Set this keyword to a long integer only if the private attribute exists within a sequence. Use this keyword to specify a sequence identifier as follows:

  • Set to a non-zero value (a sequence identifier) indicating the sequence in which the value is contained. This sequence identifier may have been returned via a previous call to the GetPrivateValue method.
  • Set to 0 or do not specify this keyword to indicate the private attribute exists at the root level of the DICOM file. This is the default.

Example

The following example verifies the existence of a private tag that has just been committed to a file. If the tag exists, a message is printed to the Output Log window. Typically you would proceed to access private values as shown in the code in the “Examples” section of IDLffDicomEx::GetPrivateValueLength. 

PRO dicom_queryprivate_doc
 
; Select a DICOM file.
sFile = DIALOG_PICKFILE( $
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
    TITLE='Select DICOM Patient File', FILTER='*.dcm', $
    GET_PATH=path)
 
; Create a clone (aImgClone.dcm) of the selected file (sfile).
 oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $
    CLONE=sfile)
; Create a sequence at the root level.
vSeqId = oImg->AddPrivateSequence('VOI Min,Max', '0055', '12')
 
; Add items to the sequence, specifying SQ identifier returned by 
; AddPrivateSequence.
oImg->SetPrivateValue, 'VOI Min,Max', '0055', '13', 'IS', '215', $
   SEQID=vSeqID
oImg->SetPrivateValue, 'VOI Min,Max', '0055', '14', 'IS', '234', $
   SEQID=vSeqID
 
; Commit the changes.
oImg->Commit
 
; Make sure the private sequence exists.
vQuery = oImg->QueryPrivateValue('VOI Min,Max', '0055', '12')
If vQuery NE 0 THEN $
   PRINT, 'Private Sequence Exists in File.'
 
; Clean up object references.
OBJ_DESTROY, oImg
 
; Note: the following line allows you to run the project
; multiple times without having to manually delete the file.
; You cannot duplicate an existing file when creating or cloning
; a DICOM file.
FILE_DELETE, path +' aImgClone.dcm', /ALLOW_NONEXISTENT
 
END

Version History

6.1

Introduced