The IDLffDicomEx::GetValue function method returns the value of a DICOM attribute specified by a standard DICOM attribute tag. This method allows you to return values of public attributes. See IDLffDicomEx::GetPrivateValue for information on returning the values of private attributes.

GetValue will fail if you attempt to return a value for an attribute that does not exist, an attribute that does not have a value, or an attribute that has been removed. If you are not sure if an attribute exists or has a value use IDLffDicomEx::QueryValue before calling GetValue.

Syntax

Result = Obj->[IDLffDicomEx::]GetValue(DicomTag [, SEQID=integer] [, COUNT=variable] )

Return Value

Returns one of the following:

  • A scalar value for an attribute with one value.
  • A vector of scalar values for attributes with multiple values.
  • A long integer if the attribute is a sequence. This value is used as the SEQID keyword in subsequent calls to GetValue to access items contained in the sequence.
  • A vector of values when the sequence contains groups (set of repeating tags within the sequence. See the IDLffDicomEx::GetValueLength method “Example” section for code that uses such an array.

The DICOM standard requires that all values are an even length. If you assign an odd length string to a value, a trailing white space will be added. It may be necessary to trim trailing spaces (for VR types that allow trailing spaces to be ignored) when comparing an odd length string value to the value returned by GetValue.

Arguments

DicomTag

A string that identifies the group and element of a DICOM attribute in the form 'XXXX,XXXX'. The DicomTag argument must reference a public tag. SeeDICOM Attributes for a list of tags.

Keywords

SEQID

Set this keyword only if retrieving the value of an attribute that exists within a sequence. Use this keyword to specify 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.

COUNT

Set this keyword equal to a named variable that will contain an unsigned long value indicating the number of elements in this method’s return value. Possible values are:

  • 1 indicating the return value is a scalar value.
  • n where n is the number of elements in the returned array. This corresponds to the number of values in the multi-valued attribute.

Example

The following example reads the multi-valued Image Type attribute from a DICOM file in the examples\data directory. See IMAGE_TYPE for more information on this attribute. 

PRO read_imagetypeattr_doc
 
; Select a DICOM file to examine.
sFile = DIALOG_PICKFILE( $
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
    TITLE='Select DICOM Patient File', FILTER='*.dcm', $
    GET_PATH=path)
 
; Open the selected file in read-only mode.
 oImg = OBJ_NEW('IDLffDicomEx', sfile)
 
; Return the Image Type attribute that can have 2 to n values. 
result = oImg->GetValue('0008,0008', COUNT=vCount)
 
FOR i = 1, vCount DO BEGIN
   Print, 'Result number', i, + ' is ', result[i-1]
ENDFOR
 
END

For the mr_knee.dcm file, the following appears in the Output Log window:

Result number       1 is ORIGINAL
Result number       2 is PRIMARY

Version History

6.1

Introduced