% @(#)registsess.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:11:29
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1994 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 extension .prg.

\ap\pa 
            table     =   Name of the output keyword table, complete
                          with 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.

            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
\xe \sxe