;

                      SHELL UTILITIES




                  I Introduction

                  R RESOLVE

                  G GETVAR
:I
                                                Introduction

                       INTRODUCTION
                       ============




The  two  shell  utilities  described herein were created to
make shell  variables  more  useful.     Previously,   shell
variables  could only be created with the SHVAR and SHDEFINE
commands, and could only be interpreted when  the  user  was
operating inside  the SH shell.  These two utilities provide
new  ways  of  both  defining   and   referring   to   shell
variables.








                                                Introduction

Of   the   many  alternate  command  intefaces,  or  shells,
supported by ZCPR3, SH is  the  simplest.    It  performs  a
single  function  --  expansion of shell variable references
-- and  nothing  else.    In  many  cases,  particularly  in
turnkey  operations,  it  is  desirable  to operate inside a
more  complete  environment,  such  as  (V)MENU  or  VFILER.
These   environments  do  not  perform  expansion  of  shell
variable  references,  however,  so  in  many   cases   this
powerful capability  goes  unused.    These  utilities allow
shell variables to be created  and  referenced  from  within
(V)MENU  shells,  aliases,  VFILER  command  lines,  and ZEX
files.







:R
                                                     RESOLVE

                           RESOLVE
                           =======




This utility will expand shell variable references  when  SH
is not  the  top  shell.  It will also resolve references to
other system features, such as register values, System  File
names, and current disk and user designations.

The syntax is:

                RESOLVE <command line>

where  the command line may contain a number of substitution
flags.  The appropriate substitutions will be made, and  the
entire    command    line    will   be   placed   into   the
Multiple-Command Line in memory for immediate execution.


                                                     RESOLVE

The substitution flags recognized by RESOLVE are:

        %<text>         -> shell variable reference
        $D              -> current disk
        $U              -> current user
        $R<n>           -> register value, 0<=n<=9
        $F<n>           -> System File name, 1<=n<=4
        $N<n>           -> System File name, first 8 characters only
        $T<n>           -> System File name, extension only
        $|              -> multiple-command separator (;)

If either of the flag characters '%' or '$' appear twice  in
succession on the line, only one will be substituted.








                                                     RESOLVE

A  flag  for  a  substitute  multiple-command  separator  is
provided so  that  system  variable  references  in  several
succeeding commands  may  be  resolved  in  one  pass.  When
using this feature, it must be kept in  mind  that  although
the   memory-based   Multiple-Command   Line   may   be  200
characters in length (say), a  parameter  list  of  no  more
than 126  characters  may  be passed to a program.  Examples
are:

    RESOLVE ECHO DIRECTORY OF $F3 --$|XDIR $F3

    RESOLVE SHVAR TEMP $F3$|SETFILE 3 %WFILE$|            <<
                          RESOLVE SHVAR WFILE %%TEMP

The first example simply prints a  directory  of  all  files
matching System  File  three.   The second example swaps the
contents  of  System  File  three  and  the  shell  variable
'WFILE'.



                                                     RESOLVE

Nested  shell  variables  can  also be resolved by using the
'GO' command (if it is enabled in your system) as the  first
item on  the  command  line passed to RESOLVE.  For example,
if there are two shell variables defined as follows:

        Variable Name          Expansion
        -------------          ---------
           THIS                THAT
           THAT                COULD BE ANYTHING

the command line

                RESOLVE GO ECHO %%%THIS

will display

                COULD BE ANYTHING




                                                     RESOLVE

Options --

The only option available is help, which is exclusive.


Quiet Operation --

RESOLVE obeys  the  quiet  flag,  and  will  not  print  its
sign-on message if the flag is set.


Program Error Code --

RESOLVE  clears the Program Error Code byte upon invocation,
and will set it if there is a syntax error  in  the  command
line.  The following are examples of syntax errors:

                '$G' '$F8' '$4'

:G
                                                      GETVAR

                          GETVAR
                          ======

This  utility  will  print  a  user-defined prompt, accept a
line  of  input,  and  assign  that  line  of  input  to   a
user-defined shell variable.  The syntax of invocation is:

                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.








                                                      GETVAR

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,



                                                      GETVAR

giving   shell   variables   almost  the  power  of  aliases
(remember  that  references  to  shell  variables   may   be
nested).

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.

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.

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