ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/ZSYS/SIMTEL20/ZCPR3/SH.HQP/SH.HLP

Text File | 2000-06-30 | 13KB | 420 lines

;

           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.