;
                                 GETVAR.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               3k (22)   1ADF  1.4        R. Nielsen 08/89         Z3COM4 

  1- Syntax  2- Input Editor  3- Notes  4- Examples of Use  5- Help File      


   GETVAR will print a user-defined prompt, accept a line of input, and assign
that line of input to  a user-defined  shell variable in  SH.VAR  on the ROOT:
directory. 
:1

   Syntax:  GETVAR <varname> <prompt text>

   Only the first eight characters of the variable name are significant.  

   The prompt text  will be printed left-justified on the console, followed by
a space.  The user's response will  be entered at this point.  Typing a Ctrl-C 
in the first position  on  the line will abort operation.  The contents of the
shell variable will then be unchanged.  If  a  Ctrl-C  is struck  in any other
position, it will be inserted in the line.  If a response is  to have a Ctrl-C
in the first position, put  it in any position but the first,  then delete the
chars in front of it.

   Control flags for inclusion in the prompt string:

   %>  -  switch to lowercase
   %<  -  switch to uppercase
   ^   -  treat next character as a ctrl character (^A is Ctrl-A)

Any character other than < or > following "%" is displayed literally.
:2
 Input Editor - 1/2 

   The input editor control keys are:

   ^S or left-arrow key if defined in TCAP   <--  move left one char
   ^D or right-arrow key if defined in TCAP  <--  move right one char
   ^E  <-- erase to [E]nd of line
   ^U  <-- delete char [U]nder cursor
   ^W  <-- delete [W]ord forward
   ^X  <-- kill entire line
  DEL  <-- delete char before cursor
  TAB  <-- move to end of line, or if at end, to beginning
   ^A  <-- move to beginning of previous word
   ^F  <-- move to beginning of next word 
   ^H  <-- delete char before cursor
   ^Q  <-- [Q]uote next char -- insert char literal
   ^C  <-- abort if at beginning of line
 Input Editor - 2/2 

   The input editor  scrolls  the  entered  text  within  the remainder of the 
physical line  following  the prompt,  allowing  you  to  move and edit freely 
within the line.  You may enter up to 127 chars.  Prompts  may be  longer than
the screen width.  

   Cursor  keys  are  evaluated  first,  and  may mask later functions.  These
editor commands are identical to those  used  in SH20,  except of course, that
command history recall  is  not possible  from within GETVAR,  and ^X will not
allow you to exit from GETVAR.
:3
 GETVAR Notes - 1/3 

   a. Shell variables created with GETVAR have two features that those created
      with SHVAR do not.

      o   Shell variable text may be lowercase (names will be uppercase).

      o   Shell variable text may be a  Multiple-Command Line.

      The first  of these features may  be useful when non-standard  utilities
      are used to retrieve and display a shell variable.   A  command  such as

                               ECHO %<varname>

      will always result in a capitalized display of the variable.  The second
      of  these features  has potentially  many uses,  giving  shell variables 
      almost the power of aliases (remember that references to shell variables
      may be nested).
 GETVAR Notes - 2/3 

   b. GETVAR does not check to see that the user is a Wheel,  but does provide
      a 'secure' input editor.   That is, the user cannot abort the program by
      striking a control-C at the beginning  of the input line.   The  program 
      may therefore  be  suitable  for  use  in  secure  systems,  although  a 
      malicious  user who can invoke the program  at will could  still corrupt 
      the SH.VAR file.

   c. GETVAR abides by  the  Quiet  Flag,  except for  the  display  of  error 
      messages,  and  will set the Program Error Code byte if  it is unable to
      create or write the shell variable file.

   d. The only option supported is the display of a help message.

   e. The  meanings  of  existing  variables  in  SH.VAR   can  be  edited  by 
      SHDEFINE.COM.
 GETVAR Notes - 3/3 

   f. Vs. 1.2 updates
      - Incorporated scrolling line editor instead of SYSLIB's INLINE.  Cntl-C
        aborts with no change to shell variable.
  
   g. Vs. 1.3 updates
      - Fixed bug causing SH.VAR file sometimes not to be updated.  Added ECHO
        routine to allow display of lower-case letters in prompt.   Display of
        sign-on banner no longer controlled by  quiet flag  (only printed when
        help is requested).  Linked with new Vs 4 LIBs.

   h. Vs. 1.4 updates
      - Moved uninitialized storage to DSEG.  Increased local stack size.
:4
 Examples of Use 

   a. GETVAR run What do you wish to run?<cr>   <-- you enter at command line
      What do you wish to run? DIR$|VFILER<cr>  <-- prompt shows, you respond
      RESOLVE %run<cr>                          <-- you enter variable name
        --> DIR is run followed by VFILER       <-- computer does this

      Variables are equated to  (replaced by) command line  text  of up to 126
      characters.   In this example 'run' equals to running  DIR  followed  by
      running VFILER.

   b. Get Help alias:

      HELP:;ROOT:dir14 $.h?p h;ROOT:quiet s;ROOT:getvar ghelp enter   <<
      desired help file by name -;ROOT:resolve hlp %ghelp;ROOT:quiet r;$d$u:

      GETVAR in the above alias  places the  operator's response  for 'desired
      help file' into  a variable named 'ghelp' which is located automatically
      in the ROOT: file SH.VAR.   RESOLVE sets  up  the  main  command string,
      expanding the 'ghelp' variable.  
:5

                                 SHUTILS.HLP 

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               8k (55)   C26B  n/a        Dreas Nielsen 4/86       Z3COM4 
==============================================================================

   Z-System HELP file for GETVAR and RESOLVE shell utilities.
