*******************************************************************************
*
*	 Display help from SYS.HELP, USER.HELP, BASIC.HELP or CONV.HELP
*
*	Module	%M%	Version	%I% 	Date	%H%
*
*	(c) Copyright 1998 Ardent Software Inc. - All Rights Reserved
*	This is unpublished proprietary source code of Ardent Software Inc.
*	The copyright notice above does not evidence any actual or intended
*	publication of such source code.
*
*******************************************************************************
*
*	Maintenence log - insert most recent change descriptions at top
*
*	Date.... GTAR# WHO Description.........................................
*	10/14/98 23801 SAP Change copyrights. 
*	10/22/96 19497 LA  Don't allow help to run across interCALL
*	06/21/93 11068 WLG Changed not to convert space to dot if SQL.HELP
*	01/20/93 10913 PVW Display pick help in pick flavor after sys.help
*	01/20/93 10913 PVW Fixed various help problems.
*	08/27/92 9261  PVW Allow format of HELP subject FROM help.file
*	07/27/92 9946  LPC Look for HELP files in the SYS.HELP directory
*	07/15/92 9872  LPC Allow any .HELP file to be used
*	10/08/91 8475  LPC Added "Formatting HELP" message for large displays.
*	10/08/91 8582  LPC Added routine to access USER.HELP file.
*	07/11/91 8486  DTM Fix PHELP resetting terminal characteristics
*	06/17/91 8484  JWT fix PHELP for PICK flavor accounts
*	06/11/91 8462  LPC Cleanup PHELP
*	06/05/91 8429  JWT Changed to build local select list if system select
*			list unreachable.  -- Also fixed auto position feature
*			when unrecognized help requested.
*	05/31/91 8409  LPC Fix call to CHOICE.BOX
*	05/31/91 8408  LPC Rewrite using Motif routines
*	09/10/89 5635  JWT Clear Printer in case HELP LPTR
*	07/25/88   -    -  Maintenence log purged at 5.2.1, see release 5.1.10.
*
*******************************************************************************

$OPTIONS PRIME

$INCLUDE UNIVERSE.INCLUDE MTF.INCL.H
$INCLUDE UNIVERSE.INCLUDE KEYWORD.H
$INCLUDE UNIVERSE.INCLUDE VOC.TYPE.H

      * If HELP is being executed via interCALL, do not allow it to run as
      * it does not request input in a way that interCALL can recognize

      IF @TTY = "uvcs" THEN
         STOP "It is not possible to run HELP from a client application"
      END

      inited=0

      choice.height = @CRTHIGH - 3
      choice.width = @CRTWIDE - 2
 
      *************************************************************************
      * initialize variables

      SAVEDLISTS = "UV.SAVEDLISTS"

      SYS.HELP  = "SYS.HELP"
      USER.HELP = "USER.HELP"
      PICK.HELP = "PICK.HELP"

      dot.help = ".HELP"

      read.help.list = TRUE

      no.button     = ""
      no.button<-1> = USER.HELP
      no.button<-1> = SYS.HELP

      help = "Additional help is not available"

      button.array = ""
      button.array<1> = 3
      button.array<2> = "More"
      button.array<3> = "End Help"
      button.array<4> = "List Commands"

      help.record = ""
      display.record = ""
      user.help.file.okay = TRUE
      pick.help.file.okay = TRUE

      *************************************************************************
      * open files

      open SAVEDLISTS to fv.saved else
         print "Cannot Open ": QUOTE( SAVEDLISTS )
         goto end.program
      end

      *************************************************************************
      * build a list of valid HELP keywords

      open "VOC" to voc else
         print "Cannot Open VOC file"
         goto end.program
      end

      read rec from voc, SYS.HELP else
         print "Cannot Read ": quote( SYS.HELP ): " from VOC"
         goto end.program
      end

      openpath rec<2> to master.help.file else
         print "Cannot Open ": quote( SYS.HELP )
         goto end.program
      end

      selectv master.help.file to select.list

      keyword.list = "USER.HELP"

      loop
      while readnext keyword.id from select.list do
         if keyword.id[5] = dot.help then
            keyword.list<-1> = keyword.id
         end
      repeat

      keyword.count = dcount(keyword.list,@FM)

      close master.help.file

      *****************************************************************
      * check if the flavor is PICK like

      PICK = 2
      REALITY = 8
      IN2 = 16

      pick.flavor = FALSE

      flavor = system(1001)

      if flavor = PICK or flavor = REALITY or flavor = IN2 then
         pick.flavor = TRUE
      end

      *****************************************************************
      * parse the command line

      sent.string = trim( @sentence )
      sent.array  = convert(" ",@FM,sent.string)

      if sent.array<1> = "RUN" or sent.array<1> = "RAID" then
         sent.array = delete(sent.array,1,0,0)
         sent.array = delete(sent.array,1,0,0)
      end

      sent.count  = dcount(sent.array,@FM)

      *************************************************************************
      * check format of statement
      *
      * UniVerse - HELP { help.file } { subject }
      *
      * or
      *
      * Prime    - HELP { subject } FROM { help.file }
      *

      prime.format = FALSE 

      from.id = sent.array<sent.count - 1>
      read from.rec from voc,from.id then
         if from.rec[1,1] = VOC$KEYWORD and from.rec<2> = KW$FROM then
            prime.format = TRUE
         end
      end

      *************************************************************************
      * remove HELP from sentence and rearrange sentence structure to be the
      * same.

      keyword.found = FALSE

      begin case
      case sent.count = 1
         sent.array = SYS.HELP
         sent.array<-1> = "*"
         sent.count = 2

      case prime.format
         * rearrange Prime format into UV format
         sent.array<1> = sent.array<sent.count>
         sent.count = sent.count - 2

      case sent.count > 2

         keyword.check = sent.array<2>
         if keyword.check[5] ne dot.help then
            keyword.check = keyword.check:dot.help
         end
         gosub find.keyword

         if keyword.found then
            sent.array = delete(sent.array,1,0,0)
            sent.count = sent.count - 1
         end else
            sent.array<1> = SYS.HELP
         end

      case sent.count = 2
         keyword.check = sent.array<2>
         if keyword.check[5] ne dot.help then
            keyword.check = keyword.check:dot.help
         end

         gosub find.keyword

         if keyword.found then
            voc.id = sent.array<2>
            read voc.rec from voc,voc.id then
                if voc.rec[1,1] = VOC$VERB then
                   sent.array<1> = SYS.HELP
                end else
                   sent.array<1> = keyword.check
                   sent.array<2> = "*"
                   no.button<-1> = keyword.check
                end
            end else
                sent.array<1> = keyword.check
                sent.array<2> = "*"
                no.button<-1> = keyword.check
            end
         end else
            sent.array<1> = SYS.HELP
         end

      end case

      *************************************************************************
      * get help.file

      help.file = sent.array<1>
      if help.file[5] ne dot.help and not(prime.format) then
         help.file = help.file:dot.help
      end
      help.list = help.file

      *************************************************************************
      * get subject list

      subject.found = FALSE
      subject = ''

      for i = 2 to sent.count
         subject = subject:" ":sent.array<i>
      next i

      subject = trim(subject)
      subject.id = subject

	  if help.file # "SQL.HELP" then
      	convert " " to "." in subject
	  end
      convert "-" to "." in subject

      gosub setup.buttons

      gosub display.help

      if not(subject.found) then
         print "HELP record for ":quote(subject.id):
         print " not found in ":help.file:" file. "
      end

      *************************************************************************
      * exit program and close files
 
end.program:

      if assigned(voc) then close voc
      if assigned(master.help.file) then close master.help.file
      if assigned(display.help.file) then
         if display.help.file.count then
            close display.help.file
         end
      end
      if assigned(fv.saved) then close fv.saved
      if assigned(user.help.file) and user.help.file.okay then
         close user.help.file
      end
      if assigned(pick.help.file) and pick.help.file.okay then
         close pick.help.file
      end
      stop

      *************************************************************************
      * subroutine to open the help file and display the information

display.help:

      if help.file ne USER.HELP and not(prime.format) then
         help.file = SYS.HELP:",":help.file
      end

      display.help.file.count = 0

      open help.file to display.help.file else
         if help.file = USER.HELP then return
         print "Cannot Open ": quote( help.file )
         return to end.program
      end

      display.help.file.count = 1

RETRY.SORT.BOX:
      if subject = "*" or subject = "" then
         if read.help.list then
            read array from fv.saved, help.list else gosub build.list
            read.help.list = FALSE
         end
         selval = 1

DO.SORT.BOX:
         title = "List of entries from ":help.file
         entries = dcount(array,@FM )
         print @(-1)
         call *SORT.BOX.B(title,1,@CRTHIGH-4,array,entries,1,selval,0,-1)
         if selval = -1 THEN
            print @(-1)
            return to end.program
         end
         display.record = ""
         subject = array<selval>
      end

      original.subject = subject

      if ( field(help.file,",",1) = SYS.HELP ) then
         keyword.check = subject:dot.help
         gosub find.keyword
         gosub setup.buttons
      end

      read.help.file = display.help.file
      read.help.name = help.file

      gosub read.help.subject

      *************************************************************************
      * look for function calls
 
      original.subject = subject
      subject = original.subject:"()"

      gosub read.help.subject

      if help.file = SYS.HELP:",":SYS.HELP then
         if pick.flavor then
            gosub display.pick.help
         end
         gosub display.user.help
      end

      if subject.found then return

      if read.help.list then
         read array from fv.saved, help.list else
            gosub build.list
         end
         read.help.list = FALSE
      end

      selval = 0
      loop
         remove cur.subject from array setting cur.delim
      until cur.delim = 0 do
      while subject > cur.subject do
         selval += 1
      repeat
      selval +=1

      goto DO.SORT.BOX:

      return

      *****************************************************************
      * finds word in keyword.list
      *
find.keyword:
      keyword.found = FALSE
      for i = 1 to keyword.count until keyword.found
         if keyword.check = keyword.list<i> then
            keyword.found = i
         end
      next i
      return

setup.buttons:

      button.array<1> = 3

      if keyword.found then
         keyword.len = len(keyword.check)
         locate(keyword.check,no.button;pos) else
            button.array<5> = keyword.check[1,keyword.len-5]:" Commands"
            button.array<1> = 4
         end
      end
      return

      *************************************************************************

read.help.subject:
      read help.record from read.help.file, subject then
         subject.found = TRUE

*        the following is only needed because PICK.HELP includes
*        SYS.HELP items which are different
         if pick.flavor then
            if help.file = SYS.HELP:",":SYS.HELP then
               if read.help.name = SYS.HELP:",":PICK.HELP then
                  if help.record = display.record then
                     return
                  end
               end
            end
         end

         display.record = help.record
         retval = 1
         print @(-1)
         print "   Formatting HELP screen..."
         call *CHOICE.BOX.B( 0, choice.height, choice.width, display.record, button.array, retval, 0 )
         begin case

         case retval = -1
            return to end.program

         case retval = 2
            subject = "*"
            return to RETRY.SORT.BOX

         case retval = 3
            help.file = keyword.check
            if keyword.check ne help.list then
               read.help.list = TRUE
               help.list = keyword.check
            end

            if help.file ne USER.HELP and not(prime.format) then
               help.file = SYS.HELP:",":help.file
            end

            subject = "*"

            close display.help.file

            display.help.file.count = 0

            open help.file to display.help.file else
               if help.file = USER.HELP then
                  return
               end
               print "Cannot Open ": quote( help.file )
               return to end.program
            end
            
            display.help.file.count = 1

            return to RETRY.SORT.BOX

         case 1
            print @(-1)

         end case

      end
      return

      *************************************************************************
      * subroutine to open USER HELP (if it exists)

display.user.help:

* The original subject has "()" appended to it, in case it wasn't found
* in the specified HELP.FILE (It may be labeled as a function).
* Reset the subject to it's original state

      subject = original.subject

      if unassigned(user.help.file) or NOT(user.help.file.okay) then
         user.help.file.okay = TRUE
         open USER.HELP to user.help.file else
            user.help.file.okay = FALSE
            return
         end
      end

      read.help.file = user.help.file
      read.help.name = USER.HELP

      gosub read.help.subject

      return

      *************************************************************************
      * subroutine to open SYS.HELP,PICK.HELP

display.pick.help:

      subject = original.subject

      if unassigned(pick.help.file) or NOT(pick.help.file.okay) then
         pick.help.file.okay = TRUE
         open SYS.HELP:",":PICK.HELP to pick.help.file else
            pick.help.file.okay = FALSE
            return
         end
      end

      read.help.file = pick.help.file
      read.help.name = SYS.HELP:",":PICK.HELP

      gosub read.help.subject

      return


      *************************************************************************
      * subroutine to build save lists if not present

build.list:

      print @(-1)
      print "Building list of record IDs from ": help.file: " file "

      execute 'SSELECT ': help.file :' # ""'

      if @SYSTEM.RETURN.CODE <= 0 then
         print "Unable to build list of IDs from ": help.file: " file "
         return to end.program
      end

      execute "SAVE.LIST &&.":help.file

      if @SYSTEM.RETURN.CODE <= 0 then
         print "Unable to build list of IDs from ": help.file: " file "
         return to end.program
      end

      open "&SAVEDLISTS&" to local.saved else
         print "Unable to build list of IDs from ": help.file: " file "
         return to end.program
      end

      read array from local.saved, "&&.":help.file else
         print "Unable to build list of IDs from ": help.file: " file "
         return to end.program
      end

      delete local.saved, "&&.":help.file

      close local.saved

      return

   end