;

          SH - A Named Variable Shell for ZCPR3


    -- The Shell SH --       -- Handling Shell Variables --
    S - The SH Command                D - SHDEFINE
    C - SH Concept                    V - SHVAR
    P - Potential Probs
                                  -- SH Variable File --
                                      F - SHFILE


:S

Command:  SH 1.0

Syntax:

    SH

Function:

    S� i� � Name� Variabl� Shel� fo� ZCPR3�  I� prompt� th� �
use� fo� � comman� line�� perform� a� interpretatio� o� th� �
comman� line� an� eithe� execute� th� comman� lin� itsel� o� �
passes the line on to the ZCPR3 Command Processor.

Options:

    None


Comments:
                                                            Variables
    SȠ permit� th� use� t� us� Name� Variables�� lik� �
MYFILE�� whic� ar� expande� i� � manne� simila� t� macro� i� �
hi� comman� lines��  Tw� programs� SHDEFIN� an� SHVAR� allo� �
th� use� t� dynamicall� creat� Name� Variables�� an� th� �
SHFILŠ comman� allow� Name� Variabl� definition� t� b� �
grouped into sets of variables.

    �� conventiona� CP/� comman� lin� coul� loo� somethin� �
lik� this:

         ED MYFILE.TXT

    Using SH, a ZCPR3 command line like                     Variables

         ED %WORKFILE

ca� b� generated�� and�� a� S� substitute� th� definitio� o� �
th� variabl� WORKFIL� whe� i� interpret� th� comman� line� �
"EĠ %WORKFILE�� coul� b� expande� int� "EĠ MYFILE.TXT�� i� �
WORKFILE=MYFILE.TXT��  B� changin� th� valu� o� th� variabl� �
WORKFILE�� th� meanin� o� th� comman� "EĠ %WORKFILE�� i� �
correspondingl� changed.

    Onc� SȠ i� invoke� (b� typin� th� comman� SH)�� an� �
comman� type� b� th� use� i� passe� thr� S� first�� expande� �
a� required�� an� then� i� th� comman� i� no� a� SH-residen� �
command�� th� expande� comman� lin� i� passe� t� ZCPR�� fo� �
processing.

    SȠ variable� ma� b� neste� t� an�� depth��  Recursion� �
however�� shoul� b� avoided� an� i� i� th� responsibilit� o� �
th� use� t� ensur� tha� recursio� doe� no� occur.
                                                            Variables
    '%%�� i� interprete� b�� SȠ a� � singl� '%'��  S� �
variable� are assigne� a� follows:

         VAR1 = "ED %%VAR2"       VAR2 = "MYFILE.TXT"

VAR1 is expanded as

         "ED %VAR2"

which is, in turn, expanded as

         "ED MYFILE.TXT"

which is finally executed by being passed to ZCPR3.

                                                            SH Commands
    There are three SH-resident commands:

         SHCMT   - switch SH to run in comment mode; in
                        comment mode, all lines which
                        do not begin with the character
                        ! are treated as comments and
                        flushed
         SHECHO  - with Echo enabled, all expanded command
                        lines are printed to the user to
                        show him what the line looked like
                        after expansion
         SHEXIT  - SH is popped from the Shell Stack,
                        enabling the next lower Shell for
                        execution

    The normal prompt for SH is:                            Comment Mode

         DU:NAME>>

as opposed to:

         DU:NAME>

fo� ZCPR3��  I� th� SHCM� (S� Comment� facilit� i� enabled� �
this prompt becomes:

         DU:NAME;

    An�� tex� issue� b� th� use� o� � comman� fil� (lik� �
ZEX�� wil� b� processe� a� � commen� unles� th� firs� �
characte� o� th� lin� i� a� exclamatio� mar� (!)�� whic� i� �
an indicator to process the command text that follows.

    Th� comman� SHCM� switche� t� commen� mode�� an� !SHCM� �
switches back.
                                                            Built-in Cmds
    Th� SHECHϠ comman� i� als� � toggle�� enablin� an� �
disablin� th� ech� o� comman� line� afte� al� variable� hav� �
been resolved.

    Th� SHEXI� comman� cause� th� Shel� Stac� t� b� poppe� �
on� level�� whic� i� tur� cause� th� SȠ Shel� t� b� �
terminated since it was on the top of the stack.

    Bot� SHECH� an� SHEXI� ca� b� execute� fro� S� Commen� �
mode by prefixing these commands with an exclamation mark.

    Th� �� comman� (� lin� beginnin� wit� � quesito� mark� �
invoke� th� built-i� hel� facilit� o� SH�� whic� simpl� �
reminds the user of what the built-in commands are for SH.

                                                            Other Shells
    SȠ� i� jus� beginnin� o� th� ZCPR�� Shel젠 Stac� �
applications�  MEN� an� VFILE� ar� bot� shell� now� an� the� �
execut� lik� SH�  Al� thre� shell� ca� pas� comman� line� t� �
ZCPR3�� hav� ZCPR�� execut� thes� command� i� it� norma� �
fashion�� complet� wit� th� command-searc� hierarchy�� an� �
the� retur� t� th� appropriat� shell� whe� done��  �� Shel� �
impose� � ne� initia� comman� lin� interpretatio� o� th� �
inpu� comman� line.


Selected Error Messages:

    "N� Shel� Stack� mean� tha� � Shel� Stac� ha� no� bee� �
installed in the ZCPR3 System and SH cannot run.

    "Shel� Stac� Full� mean� tha� ther� i� no� enoug� roo� �
on the Shell Stack for SH to push itself and SH cannot run.

    "Shel� Stac� Entr� Size� mean� tha� th� shel� stac� �
entrie� ar� to� shor� fo� S� t� defin� th� parameter� i� �
needs to control its operation.  SH cannot run.

Examples of Use:

    SH
         -- SH is invoked

:D

Command:  SHDEFINE 1.0

Syntax:

    SHDEFINE ufn        <-- define variables within file
or
    SHDEFINE            <-- define variables within SH.VAR

Function:

    SHDEFINŠ allow� th� use� t� interactivel� displa�� an� �
edi� th� assignmen� o� variable� i� � Shel� Variabl� file�  �
H� ma� add�� delete� an� redefin� Shel� Variable� a� wel� a� �
lis� al� curren� definition� o� th� CR� o� prin� the� o� th� �
printer.

Options:

    None

Comments:

    Us� o� SHDEFIN� i� explaine� withi� th� progra� itself�  �
I� i� menu-drive� an� th� erro� an� instructiona� message� �
ar� intended to be clear.

    Th� mos� comple� comman� i� th� � (fo� Edit�� command�  �
Afte� issuin� thi� command�� th� use� i� prompte� fo� � �
variabl� name��  I� h� give� th� nam� o� � variabl� no� ye� �
defined�� th� use� i� prompte� fo� � definition�� an� th� �
variabl� i� s� define� unles� th� use� responde� wit� jus� � �
RETURΠ a� thi� point��  I� th� nam� o� th� variabl� ha� �
alread�� bee� defined�� th� use� i� aske� i� h� wishe� t� �
delet� (D� o� redefin� (R� th� variable�  Appropriat� actio� �
is taken in response to the user input.

    The user must be a Wheel to run the SHDEFINE command.


Selected Error Messages:

    Self-Explanatory

Examples of Use:

    SHDEFINE myvars
         -- define variables in MYVARS.VAR

:F

Command:  SHFILE 1.0

Syntax:

    SHFILE         <-- display name of Shell Variable File
or
    SHFILE ufn     <-- set name of Shell Variable File

Function:

    SHFIL� display� o� set� th� nam� o� th� Shel� Variabl� �
Fil� t� b� use� b� SH��  SHFIL� ma� b� execute� whil� S� i� �
not running if desired.

Options:

    None


Comments:

    SHDEFINŠ an� SHVA� defin� variable� t� b� place� int� �
Shel� Variabl� Files��  SHFIL� define� whic� Shel� Variabl� �
File will be used by SH when it executes.

    Whe� S� an� SHVA� execute� th� name� variabl� fil� the� �
dea� wit� reside� i� th� ROO� directory.

Selected Error Messages:

    Self-Explanatory

Examples of Use:

    SHFILE
         -- display name of Shell Variable File

    SHFILE myvars.var
         -- define name of Shell Variable File

:V

Command:  SHVAR 1.0

Syntax:

    SHVAR          <-- list variables
or
    SHVAR var      <-- delete variable
or
    SHVAR var text <-- define/redefine variable

Function:

    SHVAҠ i� � utilit� whic� ca� lis� al� Shel� Variable� �
i� th� currently-define� Shel� Variabl� Fil� o� edi� thi� �
fil� t� delet� o� chang� on� particula� variabl� a� � time�  �
SHVAҠ i� sometime� mor� convenien� t� us� tha� SHDEFINE� �
whic� i� intende� fo� editin� group� o� variable� i� on� �
sitting.


Options:

    None

Comments:

    SHVA� ma� b� use� whil� runnin� S� o� not��  I� � Shel� �
Variabl� Fil� i� alread� define� t� th� ZCPR� System�� SHVA� �
uses this file.  If one is not defined, SHVAR uses SH.VAR.

    SH.VAR is always located in the ROOT directory.

    The user must be a Wheel to run SHVAR.

Selected Error Messages:

    Self-Explanatory


Examples of Use:

    SHVAR
         -- list shell variables

    SHVAR VAR2
         -- delete the variable VAR2

    SHVAR VARX THIS IS A TEST
         -- define VARX to "THIS IS A TEST"

:C

                        SH Concept

    Onc� SȠ i� invoke� (b� typin� th� comman� SH)�� an� �
comman� type� b� th� use� i� passe� thr� S� first�� expande� �
a� required�� an� then� i� th� comman� i� no� a� SH-residen� �
command�� th� expande� comman� lin� i� passe� t� ZCPR�� fo� �
processing.

    SȠ variable� ma� b� neste� t� an�� depth��  Recursion� �
however�� shoul� b� avoided� an� i� i� th� responsibilit� o� �
th� use� t� ensur� tha� recursio� doe� no� occur��  I� �
recursio� doe� occur�� th� comman� lin� buffe� wil� overflo� �
and SH will abort the command line.


    SȠ Variable� ar� reference� i� comman� line� a� �
"%varname"�� an� '%%� i� interprete� b� S� a� � singl� '%'�  �
T� illustrate�� assum� tha� S� variable� ar� assigne� a� �
follows:

         VAR1 = "ED %%VAR2"       VAR2 = "MYFILE.TXT"

The command line "%VAR1" is expanded as

         "ED %VAR2"

which is, in turn, is expanded as

         "ED MYFILE.TXT"

which is finally executed by being passed to ZCPR3.


    Shel� Variabl� File� ar� locate� i� th� ROO� director� �
for the commands SH and SHVAR.

    Th� use� mus� b� � Whee� i� orde� t� edi� Shel� �
Variabl� Files��  Th� command� SHDEFIN� an� SHVA� wil� onl� �
run if the user is a Wheel.


    There are three SH-resident commands:

         SHCMT   - switch SH to run in comment mode; in
                        comment mode, all lines which
                        do not begin with the character
                        ! are treated as comments and
                        flushed
         SHECHO  - with Echo enabled, all expanded command
                        lines are printed to the user to
                        show him what the line looked like
                        after expansion
         SHEXIT  - SH is popped from the Shell Stack,
                        enabling the next lower Shell for
                        execution

    The normal prompt for SH is:

         DU:NAME>>

as opposed to:

         DU:NAME>

fo� ZCPR3��  I� th� SHCM� (S� Comment� facilit� i� enabled� �
this prompt becomes:

         DU:NAME;

    An�� tex� issue� b� th� use� o� � comman� fil� (lik� �
ZEX�� wil� b� processe� a� � commen� unles� th� firs� �
characte� o� th� lin� i� a� exclamatio� mar� (!)�� whic� i� �
an indicator to process the command text that follows.

    Th� comman� SHCM� switche� t� commen� mode�� an� !SHCM� �
switches back.

    Th� SHECHϠ comman� i� als� � toggle�� enablin� an� �
disablin� th� ech� o� comman� line� afte� al� variable� hav� �
been resolved.

    Th� SHEXI� comman� cause� th� Shel� Stac� t� b� poppe� �
on� level�� whic� i� tur� cause� th� SȠ Shel� t� b� �
terminated since it was on the top of the stack.

    Bot� SHECH� an� SHEXI� ca� b� execute� fro� S� Commen� �
mode by prefixing these commands with an exclamation mark.

    Th� �� comman� (� lin� beginnin� wit� � quesito� mark� �
invoke� th� built-i� hel� facilit� o� SH�� whic� simpl� �
reminds the user of what the built-in commands are for SH.

:P

                    Potential Problems

    Onl� on� note� proble� exist� wit� SH��  Certai� ZCPR3-�
residen� an� SYSRCP-residen� command� shoul� b� avoided�  �
Thes� command� include:

         GO   - because the TPA has been changed since
                   the desired command executed

         SAVE - same reason

    SȠ� tend� t� b� � littl� slo�� i� it� loading�  �
Unfortunately�� SȠ ha� bee� mad� a� smal� a� possibl� an� �
wil� probabl�� continu� t� tak� mor� tim� tha� simpl� �
invoking the ZCPR3 command processor directly.