The IDLffDicomEx::GetPrivateValueLength function method returns the length of all values or of a specified value (in bytes) in a private DICOM attribute. This method uses a private code defined by the author of the private tag, a group number, and part of the element tag instead of a standard DICOM attribute tag to identify the private DICOM attribute.

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

Syntax

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

Return Value

Returns a long integer indicating the length of one of the following:

  • The length (in bytes) of all values when the VAULEINDEX keyword is not set
  • The length (in bytes) of a single value specified by the VALUEINDEX keyword
  • The number of repeating groups contained within a sequence if the PrivateCode, Group and Element arguments identify a sequence.

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 only if the private attribute 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 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.

VALUEINDEX

Set this keyword to an integer indicating the one-based index number of the value for which to return the length. If not set, this method returns the length of a single value for a single-valued attribute, or the length of all values for a multi-valued attribute.

An error will be issued if you specify a value larger than the number of values in the private attribute.

Examples

The following example adds private tags to the clone of a selected DICOM file, and commits this file to memory. It then queries for a private sequence to make sure it exists and proceeds to use GetPrivateValue (to return a vector of sequence identifiers, one for each group) and GetPrivateValueLength (to return the number of repeating groups) to access the length and value of a private attribute that is repeated within the sequence. 

PRO print_tags_doc, vTags, vTagCnt
 
; Format the output.
PRINT, FORMAT= $
   '(%"%3s, %2s, %-12s, %3s, %5s, %12s, %15s")', $
   'IDX', 'LVL', 'TAG',  'VR', 'SEQID', $
   'DESCRIPTION', 'VALUE'
 
; Cycle through the tags.
FOR xx = 0, vTagCnt-1  DO BEGIN
 
   ; If the item is nested within another item, indicate the 
   ; level using > symbol.
    IF (vTags[xx].Level GT 0) THEN BEGIN
      vLvl = STRJOIN(REPLICATE('>',vTags[xx].Level))
      vtg =  vLvl + vTags[xx].Tag
    ENDIF ELSE BEGIN
      vtg = vTags[xx].Tag
    ENDELSE
 
    ; If the tags are in a group, indicate this.
    IF (vTags[xx].GroupNum GT 0) THEN BEGIN
       PRINT, FORMAT='(%"%15s, %1d")', 'Group', vTags[xx].GroupNum
    ENDIF
 
   ; Print the fields of the structure. 
   PRINT, FORMAT = $
      '(%"%3d, %2d, %-12s, %3s, %5s, %12s, %15s")', $
       xx, vTags[xx].Level, vtg, vTags[xx].VR, $
       vTags[xx].SeqId, vTags[xx].Description, $
       vTags[xx].Value
ENDFOR
 
END
 
PRO dicom_getprivate_length_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)
; Add two sets of repeating tags (groups) to a private sequence
; (0051, 0012), which is created by AddPrivateGroup. This sequence
; exists at the root-level of the DICOM file. Add two sets of
; repeating tags to the root sequence.
vGrp1 = oImg->AddPrivateGroup('Root Private SQ', '0051', '12')
oImg->SetPrivateValue, 'Root Private SQ', '0051', '14', 'ST', $
   'gr1Tag1', SEQID=vGrp1
oImg->SetPrivateValue, 'Root Private SQ', '0051', '15', 'ST', $
   'gr1Tag2', SEQID=vGrp1
vGrp2 = oImg->AddPrivateGroup('Root Private SQ', '0051', '12')
oImg->SetPrivateValue, 'Root Private SQ', '0051', '14', 'ST', $
   'gr2Tag1', SEQID=vGrp2
oImg->SetPrivateValue, 'Root Private SQ', '0051', '15', 'ST', $
   'gr2Tag2', SEQID=vGrp2
 
; Print a range including the new tags to
; the Output Log window.
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
   START_TAG='0051,0000', STOP_TAG='0057,0000')
print_tags_doc, vTags, vTagCnt
 
; Commit the changes.
oImg->Commit
 
; Make sure the private sequence exists.
vQuery = oImg->QueryPrivateValue('Root Private SQ', '0051', '12')
If vQuery NE 0 THEN BEGIN
 
   ; Retrive the sequence identifier, lost after a commit. When the 
   ; sequence contains multiple groups, this returns an zero based  
   ; vector of sequence identifiers, one for each group.
   vSeqId = oImg->GetPrivateValue('Root Private SQ', '0051', '12')
 
   ; Return the number of sets of repeating tags in the private 
   ; sequence. This value is used to access a private value in 
   ; each group.
   vSeqLength = oImg->GetPrivateValueLength('Root Private SQ', $
      '0051', '12')
 
   For i = 1, vSeqLength do begin
      ; Return the length and value of each private attribute.
      vLength = oImg->GetPrivateValueLength('Root Private SQ', $
         '0051', '14', SEQID=vSeqId[i-1])
      vResult = oImg->GetPrivateValue('Root Private SQ', $
         '0051', '14', SEQID=vSeqId[i-1])
      Print, 'Sequence group ', i, + '(0051,1014) length is ', $ 
         vLength, + ' and value is ', vResult
   ENDFOR
ENDIF
 
; Clean up 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

The following appears in the Output Log window.

IDX, LV, TAG         ,  VR, SEQID,  DESCRIPTION,           VALUE
  0,  0, 0051,0010   ,  LO,      ,             , Root Private SQ
  1,  0, 0051,1012   ,  SQ,      ,             ,                
          Group, 1
  2,  1, >0051,0010  ,  LO,      ,             , Root Private SQ
  3,  1, >0051,1014  ,  ST,      ,             ,         gr1Tag1
  4,  1, >0051,1015  ,  ST,      ,             ,         gr1Tag2
          Group, 2
  5,  1, >0051,0010  ,  LO,      ,             , Root Private SQ
  6,  1, >0051,1014  ,  ST,      ,             ,         gr2Tag1
  7,  1, >0051,1015  ,  ST,      ,             ,         gr2Tag2
Sequence group 1(0051,1014) length is 8 and value is gr1Tag1 
Sequence group 2(0051,1014) length is 8 and value is gr2Tag1

Version History

6.1

Introduced