function PDSUPDATEKEYWORD, label, keyword, newValue, object = object

;+
;$Log:
;
; NAME:
;   PDSUPDATEKEYWORD
;
; PURPOSE:
;   Finds the line in a label containing the Keyword, updates it to the newValue,
;   and writes back the line. Units are maintained.
;
; CATEGORY:
;   AMIE Calibration - part of project 'AMIE_PIPELINE', but can be used stand-alone
;
; CALLING SEQUENCE:
;   newlabel = PDSUPDATEKEYWORD (label, keyword, newValue)
;
; INPUTS:
;   label: A string array containing a PDS label, e.g. created by pdsread
;   keyword: A valid PDS keyword which is existing in the label
;   newValue: The new value the keyword shall contain - NOTE: must be a string, if
;             hypens (") are needed, they need to be provided
;
; OPTIONAL INPUT PARAMETERS:
;   object: Set this to a valid object in the label to find keywords that belong to an
;           object (e.g. if you search for LINES in a file which contains two images).
;           Then, it will search only within this object.
;
; OUTPUTS:
;    The complete label, with the requested update implemented at the appropriate place
;
; COMMON BLOCKS:
;   None.
;
; SIDE EFFECTS:
;   Hopefully none.
;
; RESTRICTIONS:
;   Only handles one line keywords
;
; USED ROUTINES:
;   RSSD library: PDSUPDATEKEYWORD
;   PDS library:  PDSPAR

; MODIFICATION HISTORY:
;   V0.1 - 2004 Feb 06, dvk: First go
;   V1.0 - 2004 Feb 06, dvk: Updated usage; added 'object' - seems to work!
;   V1.1 - 2004 Aug 05, dvk: Added comments, moved to SOFTWARE directory
;
; (c) 2004, Detlef V. Koschny, ESA/RSSD
;-

;-----------------------------------------------------------------------------------------
; Defining arrays, constants, etc.
;-----------------------------------------------------------------------------------------
newLabel = label                                            ;to avoid changing the orginal

;-----------------------------------------------------------------------------------------
; Perform some checks
;-----------------------------------------------------------------------------------------
if strpos (Label (0), 'PDS_VERSION_ID                 = PDS3') NE 0 then $
   message, 'Not a PDS3 header'

sLabel = size (label)
if sLabel (0) NE 1 then message, 'Label not a one-dimensional array'
if sLabel (1) LT 2 then message, 'Label contains less than 2 entries'
if sLabel (2) NE 7 then message, 'Label not a string array'

sKeyword = size (keyword)
if sKeyword (1) NE 7 then message, 'Keyword not a string variable'

sNewValue = size (newValue)
if sNewValue (1) NE 7 then message, 'NewValue is not a string variable'

if keyword_set (object) then begin
     ;search whether the object is there
     allObjects = pdspar (Label, 'OBJECT', INDEX = ncount)  ;this is a string array

     posOfObject = -1
     for i = 0, n_elements (allObjects) - 1 do begin
        if strpos (allObjects (i), object) EQ 0 then posOfObject = i
     end
     if posOfObject EQ -1 then message, 'Object not found'

     ;to start at the right place when searching the keyword, get the line number
     ;of the beginning of the object. pdspar returns an array 'ncount' which contains
     ;it, just need to pick the right one.
     startOfObject = ncount (posOfObject)

endif

;-----------------------------------------------------------------------------------------
; Find the line in the label containing the keyword - first line is 0!
; Exit with an error if the keyword is found more than once.
; If 'object' is specified, find the line number of the beginning of the object, only
; go until the next END_OBJECT keyword.
;-----------------------------------------------------------------------------------------
if keyword_set (object) then startCount = startOfObject + 1 else startCount = 0

found = 0
endflag = 0
i = startCount - 1
REPEAT BEGIN
   i = i + 1
   if strpos (strtrim (newLabel (i), 1), keyword) EQ 0 then begin
        ; We search for the keyword - it has to be unique!
        ; Using strtrim removes leading blanks. If the keyword is
        ; passed in with a trailing blank, it is ensured that only
        ; complete words are found.
        if found EQ 1 then message, 'Keyword not unique'
        lineNo = i
        found = 1
   endif
   if keyword_set (object) then if strpos (newLabel (i), 'END_OBJECT') NE -1 then endflag = 1
ENDREP UNTIL ((endflag EQ 1) OR (i GE n_elements (newLabel) - 1))

if found EQ 0 then message, 'Keyword "' + keyword + '" not found'

;-----------------------------------------------------------------------------------------
; Check the length of the old value
;-----------------------------------------------------------------------------------------
oldValue = PDSPAR (newLabel, keyword)
oldValueLength = strlen (oldValue)
newValueLength = strlen (newValue)

;-----------------------------------------------------------------------------------------
; Check whether units are present, if yes, extract them
;-----------------------------------------------------------------------------------------
posOfLeftBracket = strpos (newLabel (lineNo), '<')
posOfRightBracket = strpos (newLabel (lineNo), '>')

unit = ''
if posOfLeftBracket (0) NE -1 and posOfRightBracket (0) NE -1 then begin
   ;both < and > are present...
   lengthOfUnit = posOfRightBracket (0) - posOfLeftBracket (0) - 1
   unit = strmid (newLabel (lineNo), posOfLeftBracket (0) + 1, lengthOfUnit)
endif

;-----------------------------------------------------------------------------------------
; Replace old value with new value - if new value shorter than old one, add the
; correct number of spaces
; Note: For some reason oldValueLength is an array, this comes from strlen
;-----------------------------------------------------------------------------------------
; first calculate number of spaces needed - if any
spacesAtEnd = ''
if oldValueLength (0) GT newValueLength (0) then begin
   difference = oldValueLength (0) - newValueLength  (0) ;for some reason these are arrays
   for i = 0, difference - 1 do spacesAtEnd = spacesAtEnd + ' '
endif

;if there is a unit, add it
stringToAdd = newValue
if unit NE '' then stringToAdd = stringToAdd + ' ' + '<'+ unit +'>'
stringToAdd = stringToAdd + spacesAtEnd

temp = newLabel (lineNo)                         ;workaround as strput doesn't like arrays
posOfEqualsign = strpos (temp, '=')
strput, temp, stringToAdd, posOfEqualsign + 2
newLabel (lineNo) = temp

;-----------------------------------------------------------------------------------------
; Wrap up
;-----------------------------------------------------------------------------------------

return, newLabel
end ;function PDSUpdateKeyword

pro test
    ; test stub reading a pds file and writing a new label with changes
    ; creates a file called 'pdstestlabel.txt'

    read_amiew, image, label
    noOfRecords = n_elements (label)

    ;strip off the <CR><LF> at the end
    new_label = strmid (label, 0, 78)

    new_label = PDSUPDATEKEYWORD (new_label, 'TEMPERATURE', '-9')
    new_label = PDSUPDATEKEYWORD (new_label, 'DATA_QUALITY_ID',  '20')
    new_label = PDSUPDATEKEYWORD (new_label, 'PRODUCER_FULL_NAME', '"Detlef Koschny"')

    new_label = PDSUPDATEKEYWORD (new_label, 'LINES', '9999999999', object = 'IMAGE')

    openw, outunit, 'c:\pdstestlabel.txt', /GET_LUN

    for i = 0, noOfRecords - 1 do printf, outunit, new_label (i)
    close, outunit
end ;test