%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1994,2004 European Southern Observatory
%.IDENT      registsess.hlq
%.AUTHOR     PB, IPG/ESO
%.KEYWORDS   MIDAS, Session Manager
%.PURPOSE    On-line help file for the command: REGISTER/SESSION
%.VERSION    1.0  19-JAN-1994 : Creation, PB
%----------------------------------------------------------------
\se
SECTION./SESS
\es\co
REGISTER/SESSION					19-JAN-1994 PB
\oc\su
REGISTER/SESSION  session  directory  file  table
	Register a session in the session manager
\us\pu
Purpose:    
          Called at the initialisation of a context, the command
          REGISTER/SESSION creates a keyword table and sets internal
          keywords to register a session. This operation allows to
          define session management commands (e.g. SET/.. KEYDEL/..
          HELP/.. SAVINIT/.. etc..) which behavior is identical in all
          packages using the session manager.
\up\sy
Syntax:       
          REGISTER/SESSION  session  directory  file  table

\ys\pa
          session = identification name of the session (e.g. ccd, 
		long, echel, ...). 
		The two first letters are used for identification of the
                session.

\ap\pa
            directory = MIDAS name of the directory where the 
		initialisation file is located (e.g. STD_PROC, CON_PROC). 

\ap\pa 
            file = Name of the initialisation file, complete with 
		e.g. extension `.prg'.
\ap\pa 
            table = Name of the output keyword table, complete with 
		e.g. extension `.tbl'.
\ap\sa
See also:   
            INQUIRE/SESSION, WRITE/SESSION
\as\no
Note:       1) The command REGISTER/SESSION parses the initialisation
               file to generate the output keyword table. The first and
               last parsed lines can be indicated by the two comments
               lines: 
                 !Begin Session List 
                 !End Session List  
               which must be written exactly as above, the sign ! corresponding
               to the first character of the line.
	       Beware of WRITE/KEYWORDS inside IF blocks: These keywords
	       are also added to the keyword table, even though that IF block
	       may never get executed!

            2) Within the parsed section of the initialisation file, each
               keyword declaration line must have the following structure:
                
               WRITE/KEY <key_def>  <default>  !  <Description> 
               (e.g. WRITE/KEY CCDNAME/C/1/60  "?" ! CCD Name) 
                
               All items must be present. Lines which first non blank
               character is an exclamation mark (!) will be ignored.

            3) When a session is registered, a list of session management
               commands can be defined within the context, including:
               
               HELP/<session>  key  [mode]  
                 provides information about session keywords. Information
                 can be looked by selection of the keyword list (mode=KEY,
                 default mode), or by selection of the description list
                 (mode=DES). 

               SET/<session>  key1 = value1  key2 = value2 ... 
                 assigns a value to the session keywords. Keyword names
                 can be truncated to the shortest non ambiguous part.
                 Blank characters before and after the = sign are optional.
                 Multiple keywords can be set with the syntax, e.g.: 
                   SET/LONG NPIX=,340 
                 corresponding to NPIX(2) = 340. 
               
               SAVINIT/<session>  file  [mode] 
                 allows all keywords of a session to the saved as or
                 retrieved from the descriptors of a MIDAS file (image
                 or table). Mode can be WRITE (default) or READ.

               KEYDEL/<session>  
                 allows all keywords of a session to be deleted. 

               ERROR/<session>  command  key   
                 displays a standard message of the format:  
                   <command>: Wrong parameter <key> = {<key>}  
                 and displays the help related to this sesion keyword. 
               
            4) The above commands must be declared in the context file
               as follows: 
               
               CREATE/COMM  SET/<session>           @a keyset
               CREATE/COMM  SAVINIT/<session>       @a keyrdwr 
               CREATE/COMM  HELP/<session>          @a keyhelp
               CREATE/COMM  KEYDEL/<session>        @a keydel
               CREATE/COMM  ERROR/<session>         @a keyerror
               
               where <session> is the name of the declared session, like
               CCD, LONG, ECHELLE, MOS, etc...
\on\exs
Examples:
\ex
            REGISTER/SESSION  long  STD_PROC  lninit.prg  lntab.tbl
	      Scan procedure `lninit.prg' for WRITE/KEYW statements and store
	      the relevant keywords in the keyword table `lntab.tbl'.
\xe \sxe
