The IDLffDicomEx::QueryValue function method checks a DICOM file for the presence of a specified 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 and have a value in order to succeed. Attempting to call GetValue, GetValueCount, GetValueLength, GetVR, and GetProperty methods all return an error when you attempt to access an attribute that does not exist in a DICOM file. GetValue and GetProperty also fail when attempting to access an attribute that does not have a value.
This method is especially useful for determining the number of frames in an image prior to attempting to use this value when accessing pixel data. The Number of Frames tag is typically only present in multi-frame image files so when writing code that handles both single frame and multi-frame images, QueryValue can be used to determine if the Number of Frames DICOM attribute is present in the file.
Tip: For IDLffDicomEx properties, you can query using a property name (e.g., NUMBER_OF_FRAMES) instead of having to specify the DICOM attribute (e.g., 0028,0008).
Syntax
Result = Obj->[IDLffDicomEx::]QueryValue(DicomTag [, SEQID=integer] )
Return Value
This method returns one of the following:
- 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 GetValue would cause an error. A return value of 2 means GetValue would succeed for the specified attribute.
Arguments
DicomTag
A string that identifies either of the following:
- A group and element of a DICOM attribute in the form 'XXXX,XXXX'. The DicomTag argument must reference a public tag. See DICOM Attributes for a list of tags.
- An IDLffDicomEx property name, such as BITS_ALLOCATED. Allowable property names are any of those listed in IDLffDicomEx Properties.
Note: When querying an IDLffDicomEx property name, the SEQID keyword is ignored. All named properties exist at the root level of the DICOM file, not within sequences.
Keywords
SEQID
Set this keyword only if retrieving the value of an attribute that 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 GetValue method.
- Set to 0 or do not specify this keyword to indicate the attribute exists at the root level of the DICOM file. This is the default.
Example
The following code checks for the Number of Frames attribute (0028,0008) indicating the image contains multiple frames. Attempting to just return a value for this attribute may fail as not all image SOP Classes require this tag to be present for single-frame images. For a complete example, see the “Example” section of IDLffDicomEx::ChangeTransferSyntax.
In an image containing multiple frames, the returned frames are indexed in a zero-based array; hence the Number of Frames (attribute or property) value minus one will return the desired frame when accessing pixel data.
frameTest = oImg->QueryValue('0028,0008')
IF FrameTest EQ 2 THEN BEGIN
oImg->GetProperty, NUMBER_OF_FRAMES=frames
frames = frames - 1
ENDIF ELSE BEGIN
frames = 0
ENDELSE
Version History