Identifier     update_history

 Purpose        write history information into the history tag of a given
                ISAP structure

 Synopsis       update_history, struc [,co=co][,/no_ts][,/no_cl]
                                [,file=file]

 Arguments      Name      I/O  Type      Description
                -----------------------------------------------------
                struc     I/O  struct    IA structure containing a history tag
                                         (e.g. AAR or Cal-G file)
                db         I   string    write entries for database purposes
                                         OBSOLETE 
                co         I   string    write the given string as a comment
                                         into the history tag
                no_ts      I   switch    don't write a time stamp
                no_cl      I   switch    don't write the command line
                file       I   string    The name of the journal file.
                                         Default: 'sap_default_journal.txt'
                
 Returns        ---

 Description    When an (IA/ISAP) subroutine is called update_history will
                write information into the history tag of the output
                structure. The default entry is a time stamp followed by the
                command line which called the subroutine. Alternatively it is 
                possible to write comments. The time 
                stamp (in the default IDL systime format) will always be 
                written except if the keyword /no_ts is set. The format of 
                the entries looks like:
                
                HISTORY = 'XX: informative string'

                where XX stands for a 2 character code describing the nature
                of the entry: TS: time stamp
                              CL: command line
                              ;DB: data base information (e.g. BASED_ON)
                                   OBSOLETE
                              CO: comment
                (Note that the keyword is always HISTORY). As a consequence an
                informative string that is longer than 80-8-2-6=64
                characters will be broken and continued in the next line. This
                continuation line will NOT contain the two character code.
                The supplied strings will be filled up to 64(68) characters
                to maintain a clean 80-character history layout.

                The routine first checks if the GUI variable !SAP_GUI is set.
                If so nothing is done (the GUI history handling will be
                implemented later). If not and if not keyword_set(no_cl) then
                the command line is extracted from the IA/ISAP journal file and
                added to the history tag (in the line following the time
                stamp). If the keyword /CO is set the corresponding entry will
                be added, too. The order of the entries is as follows:
                    TS (referring to the following entry)
                    CL
                    ;DB  OBSOLETE
                    CO

                A history could hence look like
                HISTORY = 'TS: Fri Oct 20 12:20:32 1995'
                HISTORY = 'CL: outaar=aa(inspd,cal13=mycal13,cal25_1a=mycal25_'
                HISTORY = '1a,cal25_1b=mycal25_1b)'
                HISTORY = 'TS: Fri Oct 20 12:25:35 1995'
                HISTORY = 'CO: There seems to be a problem with band1!'
                
                When the history string gets too long (more than 32767
                characters) the dimension of the history string array will be
                increased by one.

 Comment        The usage of the IDL journal file requires a proper
                initiation of this file. This will be done automatically
                during the startup of IA and GUI or can be performed
                interactively (in IDL) calling sap.pro. The startup procedure 
                will also close any user supplied journal file and initiate 
                the general session log file.

                To add a comment manually use write2hist.pro
                (e.g. write2hist, out, 'Now it works!').
                
                update_history doesn't return an error status because the only
                subroutine with an error status that is called is
                add_history_string. This subroutine, however, returns stat=1
                only for a syntax error, which will not occur when called from
                update history. The main reason is that update_history is
                not used for the GUI at the moment.

 Example           update_history, out

                   This should be the last command before return in an ISAP
                   subroutine that produces the output structure out. 

 Dependencies   CALLS: add_history_string, sap_error, sap_keyword_set 
                CALLED FROM: general auxillary routine

 Category       ISAP

 Filename       update_history.pro

 Dependencies   add_history_string.pro

 Author         E. Sturm (--> ES)

 Version        1.2

 History              20-10-95   ES+DL     definition of requirements    
                0.1   25-10-95   ES    
                1.0   30-11-95   ES        V1 delivery
                1.1   29-02-96   ES        modified action in case of struct
                                           doesn't contain history string
                1.2   12-07-96   ES        check, if journal file is open
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Copyright (C) 1995, Max-Planck-Institut fuer extraterrestrische Physik (MPE);
                    Garching, Germany                                       ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;