IDLffDicomEx::QueryValue

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.

Note
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.

; Check to see if the image has multiple frames. 
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


6.1	Introduced